The cxf: component provides integration with Apache CXF for connecting to JAX-WS services hosted in CXF.

+/*]]>*/

CXF Component
- URI format
- Options
  - The descriptions of the dataformats @@ -7037,71 +7037,33 @@ hibernate:[entityClassName][?options]
    See Also
    - Hibernate Example
    -
    HL7 Component
    - -
    The hl7 component is used for working with the HL7 MLLP protocol and HL7 v2 messages using the HAPI library.
    - -
    This component supports the following:
    -
    - HL7 MLLP codec for Mina
    - Agnostic data format using either plain String objects or HAPI HL7 model objects.
    - Type Converter from/to HAPI and String
    - HL7 DataFormat using HAPI library
    - Even more ease-of-use as it's integrated well with the camel-mina (Camel 2.11: camel-mina2 ) component.
    - - -
    Maven users will need to add the following dependency to their pom.xml for this component:
    -
    - -
    - -
    HL7 MLLP protocol
    -
    HL7 is often used with the HL7 MLLP protocol that is a text based TCP socket based protocol. This component ships with a Mina Codec that conforms to the MLLP protocol so you can easily expose a HL7 listener that accepts HL7 requests over the TCP transport.
    - -
    To expose a HL7 listener service we reuse the existing mina/mina2 component where we just use the HL7MLLPCodec as codec.
    - -
    The HL7 MLLP codec has the following options:
    -
    +

HL7 MLLP protocol

HL7 is often used with the HL7 MLLP protocol that is a text based TCP socket based protocol. This component ships with a Mina Codec that conforms to the MLLP protocol so you can easily expose a HL7 listener that accepts HL7 requests over the TCP transport.

To expose a HL7 listener service we reuse the existing mina/mina2 component where we just use the HL7MLLPCodec as codec.

The HL7 MLLP codec has the following options:

Name	Default Value	Description
`startByte`	`0x0b`	The start byte spanning the HL7 payload.
`endByte1`	`0x1c`	The first end byte spanning the HL7 payload.
`endByte2`	`0x0d`	The 2nd end byte spanning the HL7 payload.
`charset`	JVM Default	The encoding (is a charset name) to use for the codec. If not provided, Camel will use the JVM default Charset.
`convertLFtoCR`	`true` (Camel 2.11:`false`)	Will convert `\n` to `\r` (`0x0d`, 13 decimal) as HL7 stipulates `\r` as segment terminators. The HAPI library requires the use of `\r`.
`validate`	`true`	Whether HAPI Parser should validate or not.
`parser`	`ca.uhn.hl7v2.parser.PipeParser`	Camel 2.11: To use a custom parser. Must be of type `ca.uhn.hl7v2.parser.Parser`.

- -

Exposing a HL7 listener

In our Spring XML file, we configure an endpoint to listen for HL7 requests using TCP:

-
-

Notice that we use TCP on localhost on port 8888. We use sync=true to indicate that this listener is synchronous and therefore will return a HL7 response to the caller. Then we setup mina to use our HL7 codec with codec=#hl7codec. Notice that hl7codec is just a Spring bean ID, so we could have named it mygreatcodecforhl7 or whatever. The codec is also set up in the Spring XML file:

-
-

Above we also configure the charset encoding to use (iso-8859-1).

- -

The endpoint hl7listener can then be used in a route as a consumer, as this Java DSL example illustrates:

-
-

This is a very simple route that will listen for HL7 and route it to a service named patientLookupService that is also a Spring bean ID we have configured in the Spring XML as:

-
-

Another powerful feature of Camel is that we can have our business logic in POJO classes that is not tied to Camel as shown here:

-
-

Notice that this class uses just imports from the HAPI library and not from Camel.

- -

HL7 Model using java.lang.String

The HL7MLLP codec uses plain String as its data format. Camel uses its Type Converter to convert to/from strings to the HAPI HL7 model objects. However, you can use plain String objects if you prefer, for instance if you wish to parse the data yourself.

- -

See samples for such an example.

- -

HL7v2 Model using HAPI

The HL7v2 model uses Java objects from the HAPI library. Using this library, we can encode and decode from the EDI format (ER7) that is mostly used with HL7v2.
-With this model you can code with Java objects instead of the EDI based HL7 format that can be hard for humans to read and understand.

- -

The sample below is a request to lookup a patient with the patient ID 0101701234.

-
-

- -

Using the HL7 model we can work with the data as a ca.uhn.hl7v2.model.Message object.
-To retrieve the patient ID in the message above, you can do this in Java code:

-
-

- -

If you know the message type in advance, you can be more type-safe:

-
-

- -

Camel has built-in type converters, so when this operation is invoked:

-
-

Camel will convert the received HL7 data from String to Message. This is powerful when combined with the HL7 listener, then you as the end-user don't have to work with byte[], String or any other simple object formats. You can just use the HAPI HL7v2 model objects.

- -

HL7 DataFormat

The HL7 component ships with a HL7 data format that can be used to format between String and HL7 model objects.

Message Headers

The unmarshal operation adds these MSH fields as headers on the Camel message:

Message Headers

The unmarshal operation adds these MSH fields as headers on the Camel message:

< td colspan="1" rowspan="1" class="confluenceTd">

MYCLIENT

Key	MSH field	Example
`CamelHL7SendingApplication`	`MSH-3`	`MYSERVER`
`CamelHL7SendingFacility`	`MSH-4`	`MYSERVERAPP`
`CamelHL7ReceivingApplication`	`MSH-5`
`CamelHL7ReceivingFacility`	`MSH-6`	`MYCLIENTAPP`
`CamelHL7Timestamp`	`MSH-7`	`20071231235900`
`CamelHL7Security`	`MSH-8`	`null`
`CamelHL7MessageType`	`MSH-9-1`	`ADT`
`CamelHL7TriggerEvent`	`MSH-9-2`	`A01`
`CamelHL7MessageControl`	`MSH-10`	`1234`
`CamelHL7ProcessingId`	`MSH-11`	`P`
`CamelHL7VersionId`	`MSH-12`	`2.4`

- -

All headers are String types. If a header value is missing, its value is null.

- -

Options

The HL7 Data Format supports the following options:

All headers are String types. If a header value is missing, its value is null.

Options

The HL7 Data Format supports the following options:

Option	Default	Description
`validate`	true	Whether the HAPI Parser should validate using the default validation rules. Camel 2.11: better use the `parser` option and initialize the parser with the desired HAPI `ValidationContext`
`parser`	`ca.uhn.hl7v2.parser.GenericParser`	Camel 2.11: To use a cus tom parser. Must be of type `ca.uhn.hl7v2.parser.Parser`. Note that `GenericParser` also allows to parse XML-encoded HL7v2 messages.

- -

Dependencies

- -

To use HL7 in your Camel routes you'll need to add a dependency on camel-hl7 listed above, which implements this data format.

- -

The HAPI library since Version 0.6 has been split into a base library and several structure libraries, one for each HL7v2 message version:

- -

- - -

By default camel-hl7 only references the HAPI base library. Applications are responsible for including structure libraries themselves. For example, if a application works with HL7v2 message versions 2.4 and 2.5 then the following dependencies must be added:

- -

-
-

- -

Alternatively, an OSGi bundle containing the base library, all structures libraries and required dependencies (on the bundle classpath) can be downloaded from the central Maven repository.

- -

-
-

- - -

Terser language (Camel 2.11)

- -

HAPI provides a Terser class that provides access to fields using a commonly used terse location specification syntax. The Terser language allows to use this syntax to extract values from messages and to use them as expressions and predicates for filtering, content-based routing etc.

- -

Sample:

- -

-
-

- - -

HL7 Validation predicate (Camel 2.11)

- -

Often it is preferable to parse a HL7v2 message and validate it against a HAPI ValidationContext in a separate step afterwards.

- -

Sample:

- -

-
-

- - -

HL7 Acknowledgement expression (Camel 2.11)

- -

A common task in HL7v2 processing is to generate an acknowledgement message as response to an incoming HL7v2 message, e.g. based on a validation result. The ack expression lets us accomplish this very elegantly:

- -

-
-

- - -

More Samples

In the following example we send a HL7 request to a HL7 listener and retrieves a response. We use plain String types in this example:

More Samples

In the following example we send a HL7 request to a HL7 listener and retrieves a response. We use plain String types in this example:

- -

In the next sample, we want to route HL7 requests from our HL7 listener to our business logic. We have our business logic in a plain POJO that we have registered in the registry as hl7service = for instance using Spring and letting the bean id = hl7service.

- -

Our business logic is a plain POJO only using the HAPI library so we have these operations defined:

- -

Then we set up the Camel routes using the RouteBuilder as follows:

- -

Notice that we use the HL7 DataFormat to enrich our Camel Message with the MSH fields preconfigured on the Camel Message. This lets us much more easily define our routes using the fluent builders.
-If we do not use the HL7 DataFormat, then we do not gains these headers and we must resort to a different technique for computing the MSH trigger event (= what kind of HL7 message it is). This is a big advantage of the HL7 DataFormat over the plain HL7 type converters.

- -

Sample using plain String objects

In this sample we use plain String objects as the data format, that we send, process and receive. As the sample is part of a unit test, there is some code for assertions, but you should be able to understand what happens. First we send the plain string, Hello World, to the HL7MLLPCodec and receive the response as a plain string, Bye World.

Notice that we use the HL7 DataFormat to enrich our Camel Message with the MSH fields preconfigured on the Camel Message. This lets us much more easily define our routes using the fluent builders.
If we do not use the HL7 DataFormat, then we do not gains these headers and we must resort to a different technique for computing the MSH trigger event (= what kind of HL7 message it is). This is a big advantage of the HL7 DataFormat over the plain HL7 type converters.

Sample using plain String objects

- -

Here we process the incoming data as plain String and send the response also as plain String:

- -

Apache Shiro is a powerful and flexible open-source security framework that cleanly handles authentication, authorization, enterprise session management and cryptography. The objective of the Apache Shiro project is to provide the most robust and comprehensive application security framework available while also being very easy to understand and extremely simple to use.

This camel shiro-security component allows authentication and authorization support to be applied to different segments of a camel route.

Shiro security is applied on a route using a Camel Policy. A Policy in Camel utilizes a strategy pattern for applying interceptors on Camel Processors. It offering the ability to apply cross-cutting concerns (for example. security, transactions etc) on sections/segments of a camel route.

Maven users will need to add the following dependency to their pom.xml for this component:

Shiro Security Basics

To employ Shiro security on a camel route, a ShiroSecurityPolicy object must be instantiated with security configuration details (including users, passwords, roles etc). This object must then be applied to a camel route. This ShiroSecurityPolicy Object may also be registered in the Camel registry (JNDI or ApplicationContextRegistry) and then utilized on other routes in the Camel Context.

Configuration details are provided to the ShiroSecurityPolicy using an Ini file (properties file) or an Ini object. The Ini file is a standard Shiro configuration file containing user/role details as shown below

Instantiating a ShiroSecurityPolicy Object

ShiroSecurityPolicy Options

Name	Default Value	Type	Description
`iniResourcePath or ini`	`none`	Resource String or Ini Object	A mandatory Resource String for the iniResourcePath or an instance of an Ini object must be passed to the security policy. Resources can be acquired from the file system, classpath, or URLs when prefixed with "file:, classpath:, or url:" respectively. For e.g "classpath:shiro.ini"
`passPhrase`	`An AES 128 based key`	byte[]	A passPhrase to decrypt ShiroSecurityToken(s) sent along with Message Exchanges
`alwaysReauthenticate`	`true`	boolean	Setting to ensure re-authentication on every individual request. If set to false, the user is authenticated and locked such than only requests from the same user going forward are authenticated.
`permissionsList`	`none`	List<Permission>	A List of permissions required in order for an authenticated user to be authorized to perform further action i.e continue further on the route. If no Permissions list is provided to the ShiroSecurityPolicy object, then authorization is deemed as not required
`cipherService`	`AES`	org.apache.shiro.crypto.CipherService	Shiro ships with AES & Blowfish based CipherServices. You may use one these or pass in your own Cipher implementation
`base64`	`false`	`boolean`	Camel 2.12: To use base64 encoding for the security token header, which allows transferring the header over JMS etc. This option must also be set on `ShiroSecurityTokenInjector` as well.

Applying Shiro Authentication on a Camel Route

The ShiroSecurityPolicy, tests and permits incoming message exchanges containing a encrypted SecurityToken in the Message Header to proceed further following proper authentication. The SecurityToken object contains a Username/Password details that are used to determine where the user is a valid user.

Applying Shiro Authorization on a Camel Route

Authorization can be applied on a camel route by associating a Permissions List with the ShiroSecurityPolicy. The Permissions List specifies the permissions necessary for the user to proceed with the execution of the route segment. If the user does not have the proper permission set, the request is not authorized to continue any further.

Creating a ShiroSecurityToken and injecting it into a Message Exchange

A ShiroSecurityToken object may be created and injected into a Message Exchange using a Shiro Processor called ShiroSecurityTokenInjector. An example of injecting a ShiroSecurityToken using a ShiroSecurityTokenInjector in the client is shown below

Sending Messages to routes secured by a ShiroSecurityPolicy

Messages and Message Exchanges sent along the camel route where the security policy is applied need to be accompanied by a SecurityToken in the Exchange Header. The SecurityToken is an encrypted object that holds a Username and Password. The SecurityToken is encrypted using AES 128 bit security by default and can be changed to any cipher of your choice.

Given below is an example of how a request may be sent using a ProducerTemplate in Camel along with a SecurityToken

Sending Messages to routes secured by a ShiroSecurityPolicy

Given below is an example of how a request may be sent using a ProducerTemplate in Camel along with a SecurityToken

Sending Messages to routes secured by a ShiroSecurityPolicy (much easier from Camel 2.12 onwards)

From Camel 2.12 onwards its even easier as you can provide the subject in two different ways.

Using ShiroSecurityToken

You can send a message to a Camel route with a header of key ShiroSecurityConstants.SHIRO_SECURITY_TOKEN of the type org.apache.camel.component.shiro.security.ShiroSecurityToken that contains the username and password. For example:

You can also provide the username and password in two different headers as shown below:

When you use the username and password headers, then the ShiroSecurityPolicy in the Camel route will automatic transform those into a single header with key ShiroSecurityConstants.SHIRO_SECURITY_TOKEN with the token. Then token is either a ShiroSecurityToken instance, of a base64 representation as a String (the latter is when you have set base64=true).

When you use the username and password headers, then the ShiroSecurityPolicy in the Camel route will automatic transform those into a single header with key ShiroSecurityConstants.SHIRO_SECURITY_TOKEN with the token. Then token is either a ShiroSecurityToken instance, or a base64 representation as a String (the latter is when you have set base64=true).

SIP Component

In this example we unmarshal a zipped payload from an ActiveMQ queue called MY_QUEUE to its original format, and forward it for processing to the UnZippedMessageProcessor. Note that the compression Level employed during the marshalling should be identical to the one employed during unmarshalling to avoid errors.

See Also

HL7 Component

HL7 MLLP protocol

HL7 MLLP protocol

Exposing a HL7 listener

HL7 Model using java.lang.String

HL7v2 Model using HAPI

HL7 DataFormat

HL7 DataFormat

Message Headers

Message Headers

Options

Options

Dependencies

Terser language (Camel 2.11)

HL7 Validation predicate (Camel 2.11)

HL7 Acknowledgement expression (Camel 2.11)

More Samples

More Samples

Sample using plain String objects

Sample using plain String objects

See Also

See Also

HTTP Component

See Also

Shiro Security Component

Shiro Security Basics

Instantiating a ShiroSecurityPolicy Object

ShiroSecurityPolicy Options

ShiroSecurityPolicy Options

Applying Shiro Authentication on a Camel Route

Applying Shiro Authorization on a Camel Route

Creating a ShiroSecurityToken and injecting it into a Message Exchange

Sending Messages to routes secured by a ShiroSecurityPolicy

Sending Messages to routes secured by a ShiroSecurityPolicy

Sending Messages to routes secured by a ShiroSecurityPolicy (much easier from Camel 2.12 onwards)

Using ShiroSecurityToken

SIP Component