components/camel-mllp/README.md - camel - Git at Google

 # camel-mllp
 Camel MLLP Component

 See MLLP Specification here:
 http://www.hl7.org/documentcenter/public_temp_E7494E36-1C23-BA17-0C5E72EF77542E1F/wg/inm/mllp_transport_specification.PDF

 # Description
 The camel-mllp component is specifically designed to handle the nuances of the MLLP protocol and provide
 the functionality required by Healthcare providers to communicate with other systems using the MLLP protocol.

 The component uses byte[] payloads, and relies on the Camel type conversion system for converting other payload
 types to/from byte[].  This allows using other HL7 Libraries (i.e. HAPI) to parse the messages.  The component
 provides a 'charset' URI option that will cause the endpoint to set the CamelCharsetName property on the exchange
 which allows the proper conversion of byte[] to String payloads for Consumers.

 The component provides a simple URI for configuring MLLP endpoints:
 MLLP-Producers:
   to( "mllp://<host or ip>:<port>" )
 MLLP-Consumers:
   from("mllp://<host or ip>:<listening port>) to listen on a specific address
   from("mllp://port") to listen on all local addresses

 MLLP-Producers also interrogate the HL7 Acknowledgment received from the external system and if a negative acknowledgment
 is received, the producer sets an exception on the exchange indicating the type of negative acknowledgement that was
 received (i.e. a HL7 Application Reject Acknowledgement, Application Error Acknowledgement,
 Commit Reject Acknowledgement and Commit Error Acknowledgement).  This enables the use of Camel Redelivery
 Policies to configure redelivery attempts and routing erroneous messages to alternate endpoints for analysis.

 MLLP-Consumers will, by default, automatically generate an acknowledgement.  A HL7 Application Accept Acknowledgment
 will be generated for successfully processed messages, or a HL7 Application Error Acknowledgement for messages where an
 exception is raised during the processing of the exchange.  The HL7 acknowledgement can also be specified by setting the
 CamelMllpAcknowledgement property on the exchange - if present, the value of this property will be used for the HL7
 acknowledgment.  The automatic generation of an HL7 acknowledgment can be completely disabled by setting the autoAck
 URI parameter to false.  If autoAck=false and the CamelMllpAcknowledgment property is not set on the exchange, and
 exception will be raised.

 The component also provides a Camel Processor that is capable of generating HL7 Acknowledgements.  Therefore, the HAPI
 is not required to generate HL7 Acknowledgements - however, it can be used if desired.
 By default, the processor will generate a HL7 Application Accept Acknowledgement if there is not an exception on the
 Camel Exchange - otherwise it will generate a HL7 Application Error Acknowledgement.  The generated acknowledgement
 is placed in the CamelMllpAcknowledgment property on the Exchange.

 Regardless of whether the HL7 Acknowledgment is generated or specified using the CamelMllpAcknowledgement Exchange property,
 the MLLP-Consumer will set the CamelHllpAcknowledgement and CamelHllpAcknowledgementCode headers on the Message after the
 acknowledgment is successfully transmitted to the external system.

 Since the MLLP protocol does not typically use a large number of concurrent connections, the camel-mllp component uses
 a simple thread-per-connection model based an standard Java Sockets.  This keeps the implementation simple, and also
 eliminates the dependencies on other camel components.

 # Rationalization
 While Camel already includes some of this functionality in the camel-hl7 component, the implementation does not
 provide all of the functionality required to effectively handle the MLLP protocol - especially under adverse conditions.

 The camel-hl7 Mina codec and Netty decoder do not handle MLLP Framing errors very well - the component will hang waiting
 for frames to complete in some instances.

 While both camel-mina and camel-netty provide a "timeout" function, it is only applied to Producers.  MLLP Consumers
 also need to be able to timeout to recover from MLLP framing errors.  Additionally, the timeout functionality of the
 camel-netty component is disable after any data is received on the connection, making in ineffective for detecting
 timeouts after the first messages is received.

 Also, neither the Mina codec nor the Netty decoder interrogate HL7 Acknowledgments.  Therefore, it is much more
 difficult to use the redelivery and error handling features Camel provides.

 The above issues may be addressable by updating/patching the existing components, but there is one more that is not.
 Both camel-netty and camel-mina are designed to handle a large number of concurrent connections, rapid connect/disconnect
 rates, and asynchronous communication.  Forcing, these components to deal with the small number of stateful connections
 inherent to the MLLP protocol seems inappropriate.

 An attempt was made to update the camel-netty decoder provided by the camel-hl7 component to deal with the nuances of
 the MLLP protocol, but it quickly became very complicated.  The decoder was updated to correctly deal with the MLLP
 frame.  The current implementation is based on the Netty DelimiterBasedFrameDecoder, but this decoder only looks for a
 single byte terminator and MLLP uses two bytes to terminate it's frame.  Additionally, the second terminating byte of the
 MLLP frame can't be used alone because that byte is also contained in HL7 messages (it is the HL7 Segment Delimiter).
 An implementation resembling the Netty LineBasedFrameDecoder was written at it correctly handled the MLLP framing issues,
 but the timout issues were never addressed.

 For MLLP Consumers, the decoder needs to dynamically install a timeout handler whenver a partial MLLP frame is received,
 and then remove it when the frame is completed.  For MLLP Producers, the decoder would need to install a timeout handler
 at some point to enable detecting a missing acknowledgement in addition to the timeout handler to deal with the
 partial/incomplete acknowledgement.

 # MLLP Background
 The MLLP protocol is inherently synchronous because external systems almost always require the order of messages to be
 maintained (i.e. FIFO delivery).

 When a MLLP-Producer sends a message to an external system, it is required to wait for
 an HL7 Acknowledgement before sending the next message.  Additionally, the content of the acknowlegement must be examined
 to determine the specific type of the acknowlegement before the next message can be transmitted.  If the acknowledgement
 is a HL7 Application Error Acknowledgement, the MLLP-Producer should retransmit the message a few times (the number of
 redelivery attempts is application specific).  If the acknowledgment is a HL7 Application Reject Acknowledgement, there
 is something wrong with the message and redelivery will never succeed.  The HL7 Messages acknowledged with an HL7 Application
 Reject Acknowledgement must be routed to an alternate destination to allow users to investigate the nature of the error
 so it can be corrected.

 When a MLLP-Consumer receives a message from an external system, the sending system is required to wait for an HL7 Acknowledgement
 before transmitting the next message.  The MLLP-Consumer normally persists the message in a durable store and then replies
 to the sending system with a HL7 Application Accept Acknowledgement.  If a transient error occurs while persisting the
 message, the MLLP-Consumer should reply with a HL7 Application Error Acknowledgment and allow the external system to resend
 the message.  If the MLLP-Consumer detects the that the received message is invalid for some reason and the message could
 never be processed, it should reply with an HL7 Application Reject Acknowledgement and the sending system should not
 attempt to resend the message.

 NOTE:  Some external systems do not handle HL7 NACKS ( HL7 Application Reject Acknowledgments and HL7 Application Error
 Acknowledgements) - they do not interrogate the HL7 Acknowledgment to determine if it is a negative acknowledgement and
 assume any acknowledgement received is an HL7 ACK (HL7 Application Accept Acknowledgement).  In order to prevent message
 loss when dealing with external systems that behave in this fashion, the MLLP-Consumer must be capable of closing the
 TCP connection in lew of sending and HL7 NACK, which will force the external system to resend the message.  Additionally,
 the MLLP-Consumer may be required to behave differently for each type of HL7 NACK - it may need to close the TCP connection
 instead of sending HL7 Application Error Acknowledgements, and route the messages that would be normally not be persisted
 to an alternate durable store before sending the HL7 Application Reject acknowledgement.

 Systems using the MLLP protocol normally use stateful TCP connections - the connections are established and left open
 for extended periods of time.

 A MLLP-Consumer endpoint may have more than one TCP connection at a given time, but this is not the typical case.  Normally
 there is a single active TCP connection to a MLLP-Consumer.

 A MLLP-Producer endpoint should only have a single TCP connection at any given time. If the producer attempts to open more
 than one connection to an external system, it oftentimes causes issues with the external system.  Additionally, since FIFO
 must be maintained, only
	# camel-mllp
	Camel MLLP Component

	See MLLP Specification here:
	http://www.hl7.org/documentcenter/public_temp_E7494E36-1C23-BA17-0C5E72EF77542E1F/wg/inm/mllp_transport_specification.PDF

	# Description
	The camel-mllp component is specifically designed to handle the nuances of the MLLP protocol and provide
	the functionality required by Healthcare providers to communicate with other systems using the MLLP protocol.

	The component uses byte[] payloads, and relies on the Camel type conversion system for converting other payload
	types to/from byte[]. This allows using other HL7 Libraries (i.e. HAPI) to parse the messages. The component
	provides a 'charset' URI option that will cause the endpoint to set the CamelCharsetName property on the exchange
	which allows the proper conversion of byte[] to String payloads for Consumers.

	The component provides a simple URI for configuring MLLP endpoints:
	MLLP-Producers:
	to( "mllp://<host or ip>:<port>" )
	MLLP-Consumers:
	from("mllp://<host or ip>:<listening port>) to listen on a specific address
	from("mllp://port") to listen on all local addresses

	MLLP-Producers also interrogate the HL7 Acknowledgment received from the external system and if a negative acknowledgment
	is received, the producer sets an exception on the exchange indicating the type of negative acknowledgement that was
	received (i.e. a HL7 Application Reject Acknowledgement, Application Error Acknowledgement,
	Commit Reject Acknowledgement and Commit Error Acknowledgement). This enables the use of Camel Redelivery
	Policies to configure redelivery attempts and routing erroneous messages to alternate endpoints for analysis.

	MLLP-Consumers will, by default, automatically generate an acknowledgement. A HL7 Application Accept Acknowledgment
	will be generated for successfully processed messages, or a HL7 Application Error Acknowledgement for messages where an
	exception is raised during the processing of the exchange. The HL7 acknowledgement can also be specified by setting the
	CamelMllpAcknowledgement property on the exchange - if present, the value of this property will be used for the HL7
	acknowledgment. The automatic generation of an HL7 acknowledgment can be completely disabled by setting the autoAck
	URI parameter to false. If autoAck=false and the CamelMllpAcknowledgment property is not set on the exchange, and
	exception will be raised.

	The component also provides a Camel Processor that is capable of generating HL7 Acknowledgements. Therefore, the HAPI
	is not required to generate HL7 Acknowledgements - however, it can be used if desired.
	By default, the processor will generate a HL7 Application Accept Acknowledgement if there is not an exception on the
	Camel Exchange - otherwise it will generate a HL7 Application Error Acknowledgement. The generated acknowledgement
	is placed in the CamelMllpAcknowledgment property on the Exchange.

	Regardless of whether the HL7 Acknowledgment is generated or specified using the CamelMllpAcknowledgement Exchange property,
	the MLLP-Consumer will set the CamelHllpAcknowledgement and CamelHllpAcknowledgementCode headers on the Message after the
	acknowledgment is successfully transmitted to the external system.

	Since the MLLP protocol does not typically use a large number of concurrent connections, the camel-mllp component uses
	a simple thread-per-connection model based an standard Java Sockets. This keeps the implementation simple, and also
	eliminates the dependencies on other camel components.

	# Rationalization
	While Camel already includes some of this functionality in the camel-hl7 component, the implementation does not
	provide all of the functionality required to effectively handle the MLLP protocol - especially under adverse conditions.

	The camel-hl7 Mina codec and Netty decoder do not handle MLLP Framing errors very well - the component will hang waiting
	for frames to complete in some instances.

	While both camel-mina and camel-netty provide a "timeout" function, it is only applied to Producers. MLLP Consumers
	also need to be able to timeout to recover from MLLP framing errors. Additionally, the timeout functionality of the
	camel-netty component is disable after any data is received on the connection, making in ineffective for detecting
	timeouts after the first messages is received.

	Also, neither the Mina codec nor the Netty decoder interrogate HL7 Acknowledgments. Therefore, it is much more
	difficult to use the redelivery and error handling features Camel provides.

	The above issues may be addressable by updating/patching the existing components, but there is one more that is not.
	Both camel-netty and camel-mina are designed to handle a large number of concurrent connections, rapid connect/disconnect
	rates, and asynchronous communication. Forcing, these components to deal with the small number of stateful connections
	inherent to the MLLP protocol seems inappropriate.

	An attempt was made to update the camel-netty decoder provided by the camel-hl7 component to deal with the nuances of
	the MLLP protocol, but it quickly became very complicated. The decoder was updated to correctly deal with the MLLP
	frame. The current implementation is based on the Netty DelimiterBasedFrameDecoder, but this decoder only looks for a
	single byte terminator and MLLP uses two bytes to terminate it's frame. Additionally, the second terminating byte of the
	MLLP frame can't be used alone because that byte is also contained in HL7 messages (it is the HL7 Segment Delimiter).
	An implementation resembling the Netty LineBasedFrameDecoder was written at it correctly handled the MLLP framing issues,
	but the timout issues were never addressed.

	For MLLP Consumers, the decoder needs to dynamically install a timeout handler whenver a partial MLLP frame is received,
	and then remove it when the frame is completed. For MLLP Producers, the decoder would need to install a timeout handler
	at some point to enable detecting a missing acknowledgement in addition to the timeout handler to deal with the
	partial/incomplete acknowledgement.

	# MLLP Background
	The MLLP protocol is inherently synchronous because external systems almost always require the order of messages to be
	maintained (i.e. FIFO delivery).

	When a MLLP-Producer sends a message to an external system, it is required to wait for
	an HL7 Acknowledgement before sending the next message. Additionally, the content of the acknowlegement must be examined
	to determine the specific type of the acknowlegement before the next message can be transmitted. If the acknowledgement
	is a HL7 Application Error Acknowledgement, the MLLP-Producer should retransmit the message a few times (the number of
	redelivery attempts is application specific). If the acknowledgment is a HL7 Application Reject Acknowledgement, there
	is something wrong with the message and redelivery will never succeed. The HL7 Messages acknowledged with an HL7 Application
	Reject Acknowledgement must be routed to an alternate destination to allow users to investigate the nature of the error
	so it can be corrected.

	When a MLLP-Consumer receives a message from an external system, the sending system is required to wait for an HL7 Acknowledgement
	before transmitting the next message. The MLLP-Consumer normally persists the message in a durable store and then replies
	to the sending system with a HL7 Application Accept Acknowledgement. If a transient error occurs while persisting the
	message, the MLLP-Consumer should reply with a HL7 Application Error Acknowledgment and allow the external system to resend
	the message. If the MLLP-Consumer detects the that the received message is invalid for some reason and the message could
	never be processed, it should reply with an HL7 Application Reject Acknowledgement and the sending system should not
	attempt to resend the message.

	NOTE: Some external systems do not handle HL7 NACKS ( HL7 Application Reject Acknowledgments and HL7 Application Error
	Acknowledgements) - they do not interrogate the HL7 Acknowledgment to determine if it is a negative acknowledgement and
	assume any acknowledgement received is an HL7 ACK (HL7 Application Accept Acknowledgement). In order to prevent message
	loss when dealing with external systems that behave in this fashion, the MLLP-Consumer must be capable of closing the
	TCP connection in lew of sending and HL7 NACK, which will force the external system to resend the message. Additionally,
	the MLLP-Consumer may be required to behave differently for each type of HL7 NACK - it may need to close the TCP connection
	instead of sending HL7 Application Error Acknowledgements, and route the messages that would be normally not be persisted
	to an alternate durable store before sending the HL7 Application Reject acknowledgement.

	Systems using the MLLP protocol normally use stateful TCP connections - the connections are established and left open
	for extended periods of time.

	A MLLP-Consumer endpoint may have more than one TCP connection at a given time, but this is not the typical case. Normally
	there is a single active TCP connection to a MLLP-Consumer.

	A MLLP-Producer endpoint should only have a single TCP connection at any given time. If the producer attempts to open more
	than one connection to an external system, it oftentimes causes issues with the external system. Additionally, since FIFO
	must be maintained, only