Package ca.uhn.hl7v2.app

Class HL7Service

java.lang.Object

ca.uhn.hl7v2.concurrent.Service

ca.uhn.hl7v2.app.HL7Service

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

SimpleServer, TwoPortService

public abstract class HL7Service
extends Service

An HL7 service. Accepts incoming TCP/IP connections and creates Connection objects. Uses a single ApplicationRouter object (for all Connections) to define the Applications to which message are sent. To configure, use registerApplication() or loadApplicationsFromFile().

A separate thread looks for Connections that have been closed (locally or remotely) and discards them.

Author:

Bryan Tripp, Christian Ohr

Constructor Summary

Constructors

Constructor	Description
HL7Service(HapiContext theHapiContext)
HL7Service(Parser parser, LowerLayerProtocol llp)
HL7Service(Parser parser, LowerLayerProtocol llp, ExecutorService executorService)	Creates a new instance of Server

Method Summary

Modifier and Type	Method	Description
protected void	afterStartup()	Called after startup before the thread enters its main loop.
protected void	afterTermination()	Called after the thread has left its main loop.
Connection	getRemoteConnection(String ipAddress)	Returns a connection to a remote host that was initiated by the given remote host.
List<Connection>	getRemoteConnections()	Returns all currently active connections.
protected boolean	keepRunning()	Deprecated. Use Service.isRunning().
void	loadApplicationsFromFile(File f)	A convenience method for registering applications (using registerApplication() ) with this service.
void	newConnection(ActiveConnection c)	Called by subclasses when a new Connection is made.
void	registerApplication(ApplicationRouter.AppRoutingData appRouting, ReceivingApplication<? extends Message> application)	Registers the given application to handle messages corresponding to ALL message types and trigger events.
void	registerApplication(ReceivingApplication<? extends Message> application)	Registers the given application to handle messages corresponding to ALL message types and trigger events.
void	registerApplication(String messageType, String triggerEvent, Application handler)	Deprecated. use registerApplication(String, String, ca.uhn.hl7v2.protocol.ReceivingApplication) and AppWrapper
void	registerApplication(String messageType, String triggerEvent, ReceivingApplication handler)	Registers the given application to handle messages corresponding to the given type and trigger event.
void	registerConnectionListener(ConnectionListener listener)	Registers the given ConnectionListener with the HL7Service - when a remote host makes a new Connection, all registered listeners will be notified.
void	setExceptionHandler(ReceivingApplicationExceptionHandler exHandler)	Sets an exception handler which will be invoked in the event of a failure during parsing, processing, or encoding of an incoming message or its response.
void	setParserExeptionHandler(Receiver.ReceiverParserExceptionHandler parserExeptionHandler)	Register a receiver level parser exception handler so that an application can be notified of protocol level parsing errors if any
boolean	unregisterApplication(ApplicationRouter.AppRoutingData appRouting)	Unregisteres the first application that matches the routing data
boolean	unregisterApplication(ReceivingApplication<? extends Message> application)	Unregisteres the passed application

Methods inherited from class ca.uhn.hl7v2.concurrent.Service

getExecutorService, getServiceExitedWithException, handle, isRunning, prepareTermination, run, setServiceExitedWithException, setShutdownTimeout, start, startAndWait, stop, stopAndWait, waitForTermination

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

HL7Service

public HL7Service(HapiContext theHapiContext)

Parameters:

theHapiContext - HapiContext

HL7Service

public HL7Service(Parser parser,
 LowerLayerProtocol llp)

Parameters:

parser - parser to be used

llp - LowerLayerProtocol

HL7Service

public HL7Service(Parser parser,
 LowerLayerProtocol llp,
 ExecutorService executorService)

Creates a new instance of Server

Parameters:

parser - parser to be used

llp - LowerLayerProtocol

executorService - executor used for starting threads

Method Details

afterStartup

protected void afterStartup()

Called after startup before the thread enters its main loop. This implementation launches a cleaner thread that removes stale connections from the connection list. Override to initialize resources for the running thread, e.g. opening ServerSockets etc.

Overrides:

afterStartup in class Service

afterTermination

protected void afterTermination()

Called after the thread has left its main loop. This implementation stops the connection cleaner thread and closes any open connections. Override to clean up additional resources from the running thread, e.g. closing ServerSockets.

Overrides:

afterTermination in class Service

keepRunning

protected boolean keepRunning()

Deprecated.

Use Service.isRunning(). Deprecated as of version 0.6.

Returns true if the thread should continue to run, false otherwise (ie if stop() has been called).

newConnection

public void newConnection(ActiveConnection c)

Called by subclasses when a new Connection is made. Registers the ApplicationRouter with the given Connection and stores it.

Parameters:

c - existing connection

getRemoteConnection

public Connection getRemoteConnection(String ipAddress)

Returns a connection to a remote host that was initiated by the given remote host. If the connection has not been made, this method blocks until the remote host connects.

Parameters:

ipAddress - IP Address

Returns:

connection that was initiated by the given address

getRemoteConnections

public List<Connection> getRemoteConnections()

Returns all currently active connections.

Returns:

list of active remote connections

registerConnectionListener

public void registerConnectionListener(ConnectionListener listener)

Registers the given ConnectionListener with the HL7Service - when a remote host makes a new Connection, all registered listeners will be notified.

Parameters:

listener - connection listener to be called

registerApplication

public void registerApplication(String messageType,
 String triggerEvent,
 Application handler)

Deprecated.

use registerApplication(String, String, ca.uhn.hl7v2.protocol.ReceivingApplication) and AppWrapper

Registers the given application to handle messages corresponding to the given type and trigger event. Only one application can be registered for a given message type and trigger event combination. A repeated registration for a particular combination of type and trigger event over-writes the previous one. Note that the wildcard "*" for messageType or triggerEvent means any type or event, respectively.

registerApplication

public void registerApplication(String messageType,
 String triggerEvent,
 ReceivingApplication handler)

Registers the given application to handle messages corresponding to the given type and trigger event. Only one application can be registered for a given message type and trigger event combination. A repeated registration for a particular combination of type and trigger event over-writes the previous one. Note that the wildcard "*" for messageType or triggerEvent means any type or event, respectively.

registerApplication

public void registerApplication(ApplicationRouter.AppRoutingData appRouting,
 ReceivingApplication<? extends Message> application)

Registers the given application to handle messages corresponding to ALL message types and trigger events.

registerApplication

public void registerApplication(ReceivingApplication<? extends Message> application)

Registers the given application to handle messages corresponding to ALL message types and trigger events.

unregisterApplication

public boolean unregisterApplication(ApplicationRouter.AppRoutingData appRouting)

Unregisteres the first application that matches the routing data

Parameters:

appRouting -

Returns:

true if an application was unregistered, false otherwise

unregisterApplication

public boolean unregisterApplication(ReceivingApplication<? extends Message> application)

Unregisteres the passed application

Parameters:

application - receiving application

Returns:

true if an application was unregistered, false otherwise

setExceptionHandler

public void setExceptionHandler(ReceivingApplicationExceptionHandler exHandler)

Sets an exception handler which will be invoked in the event of a failure during parsing, processing, or encoding of an incoming message or its response.

setParserExeptionHandler

public void setParserExeptionHandler(Receiver.ReceiverParserExceptionHandler parserExeptionHandler)

Register a receiver level parser exception handler so that an application can be notified of protocol level parsing errors if any

loadApplicationsFromFile

public void loadApplicationsFromFile(File f)
                              throws IOException,
HL7Exception,
ClassNotFoundException,
InstantiationException,
IllegalAccessException

A convenience method for registering applications (using registerApplication() ) with this service. Information about which Applications should handle which messages is read from the given text file. Each line in the file should have the following format (entries tab delimited):

message_type trigger_event application_class

message_type trigger_event application_class

Note that message type and event can be the wildcard "*", which means any.

For example, if you write an Application called org.yourorganiztion.ADTProcessor that processes several types of ADT messages, and another called org.yourorganization.ResultProcessor that processes result messages, you might have a file that looks like this:

ADT * org.yourorganization.ADTProcessor
ORU R01 org.yourorganization.ResultProcessor

Each class listed in this file must implement Application and must have a zero-argument constructor.

Throws:

IOException

HL7Exception

ClassNotFoundException

InstantiationException

IllegalAccessException