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 MessageTypeRouter 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 and Description
HL7Service(HapiContext theHapiContext)
HL7Service(Parser parser, LowerLayerProtocol llp) Creates a new instance of Server using a default thread pool
HL7Service(Parser parser, LowerLayerProtocol llp, ExecutorService executorService) Creates a new instance of Server

Method Summary

Methods

Modifier and Type	Method and 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 IP) 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(). Deprecated as of version 0.6.
void	loadApplicationsFromFile(File f) A convenience method for registering applications (using registerApplication() ) with this service.
void	newConnection(Connection c) Called by subclasses when a new Connection is made.
void	registerApplication(ApplicationRouter.AppRoutingData appRouting, ReceivingApplication application) Registers the given application to handle messages corresponding to ALL message types and trigger events.
void	registerApplication(ReceivingApplication application) Registers the given application to handle messages corresponding to ALL message types and trigger events.
void	registerApplication(String messageType, String triggerEvent, Application handler) Registers the given application to handle messages corresponding to the given type and trigger event.
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.

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 Detail

HL7Service

public HL7Service(HapiContext theHapiContext)

HL7Service

public HL7Service(Parser parser,
          LowerLayerProtocol llp)

Creates a new instance of Server using a default thread pool

HL7Service

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

Creates a new instance of Server

Method Detail

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(Connection c)

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

getRemoteConnection

public Connection getRemoteConnection(String IP)

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. TODO currently nobody calls this...

getRemoteConnections

public List<Connection> getRemoteConnections()

Returns all currently active 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.

registerApplication

public void registerApplication(String messageType,
                       String triggerEvent,
                       Application 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(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 application)

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

registerApplication

public void registerApplication(ReceivingApplication application)

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

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.

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