Package ca.uhn.hl7v2

Interface HapiContext

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

DefaultHapiContext

public interface HapiContext
extends Closeable

Interface that provides a starting point for

• Configuring HAPI core services (e.g. parsing)
• Obtaining correspondingly configured instances of HAPI core services

HapiContext instances are not supposed to be singletons, i.e. if necessary, it is possible to have several HapiContexts within one application.

HapiContext objects maintains the following configuration information

• ExecutorService: thread executors used for the HAPI networking features in ca.uhn.hl7v2.app
• LowerLayerProtocol: MLLP protocol used for the HAPI networking features in ca.uhn.hl7v2.app
• SocketFactory: Socket factory used for the HAPI networking features in ca.uhn.hl7v2.app
• ParserConfiguration: detail configuration for all HL7 parsers
• ModelClassFactory: lookup for message model classes during parsing or message creation
• ValidationContext: validation rules used during parsing or during a dedcated validation step
• ValidationRuleBuilder: alternative way of providing a ValidationContext
• ValidationExceptionHandlerFactory: factory for exception handler used during message validation

HapiContext serves as factory for HAPI objects that refer to this configuration. Changing the configuration automatically influence all HAPI objects that were created and will be created using the given factory instance:

• PipeParser
• XMLParser
• GenericParser
• Validator
• ConnectionHub
• SimpleServer
• TwoPortService

Method Summary

Modifier and Type	Method	Description
CodeStoreRegistry	getCodeStoreRegistry()
Validator	getConformanceValidator()	Returns a ca.uhn.hl7v2.conf.check.Validator instance.
ConnectionHub	getConnectionHub()	Deprecated. use newClient(String, int, boolean)
ExecutorService	getExecutorService()
GenericParser	getGenericParser()
LowerLayerProtocol	getLowerLayerProtocol()
<R> Validator<R>	getMessageValidator()
ModelClassFactory	getModelClassFactory()
ParserConfiguration	getParserConfiguration()
PipeParser	getPipeParser()
ProfileStore	getProfileStore()
ServerConfiguration	getServerConfiguration()
SocketFactory	getSocketFactory()
ValidationContext	getValidationContext()
<R> ValidationExceptionHandlerFactory<R>	getValidationExceptionHandlerFactory()
ValidationRuleBuilder	getValidationRuleBuilder()
XMLParser	getXMLParser()
Connection	newClient(String host, int port, boolean tls)	Construct a new HL7 Client which will connect to an external TCP server for the purpose of sending messages (and receiving responses).
Connection	newClient(String host, int outboundPort, int inboundPort, boolean tls)	Construct a new HL7 two-port client which will connect to an external TCP server for the purpose of sending messages (and receiving responses).
Connection	newLazyClient(String host, int port, boolean tls)	Construct a new HL7 Client which will connect to an external TCP server for the purpose of sending messages (and receiving responses).
Connection	newLazyClient(String host, int outboundPort, int inboundPort, boolean tls)	Construct a new HL7 two-port client which will connect to an external TCP server for the purpose of sending messages (and receiving responses).
<T extends Message> T	newMessage(Class<T> clazz)	Creates a new message of the provided message structure class, without further initializing the message
Message	newMessage(String eventType, String triggerEvent, Version version)	Creates a new message of the given event type, trigger and version, and initializes the message header
HL7Service	newServer(int port, boolean tls)	Construct a new HL7 Server which will listen for incoming connections
HL7Service	newServer(int port, boolean tls, boolean acceptAll)	Construct a new HL7 Server which will listen for incoming connections and will pass all messages to the responders, even if the message control id is not known to the server
HL7Service	newServer(int inboundPort, int outboundPort, boolean tls)	Construct a new HL7 Server which will listen for a pair of connections (one for incoming messages, one for outgoing)
void	setCodeStoreRegistry(CodeStoreRegistry store)
void	setExecutorService(ExecutorService executorService)
void	setLowerLayerProtocol(LowerLayerProtocol llp)
void	setModelClassFactory(ModelClassFactory modelClassFactory)
void	setParserConfiguration(ParserConfiguration configuration)
void	setProfileStore(ProfileStore store)
void	setServerConfiguration(ServerConfiguration theServerConfiguration)	Sets the ServerConfiguration to be used by all HL7 servers obtained from this class.
void	setSocketFactory(SocketFactory socketFactory)
void	setValidationContext(ValidationContext context)
void	setValidationContext(String contextClassName)	Sets a default ValidationContext.
<R> void	setValidationExceptionHandlerFactory(ValidationExceptionHandlerFactory<R> factory)
void	setValidationRuleBuilder(ValidationRuleBuilder ruleBuilder)	Sets a default ValidationRuleBuilder.
void	setValidationRuleBuilder(String builderClassName)	Sets a new instance of ValidationRuleBuilder as default.

Methods inherited from interface java.io.Closeable

close

Method Details

getExecutorService

ExecutorService getExecutorService()

Returns:

the ExecutorService to be used by all services that spawn threads

setExecutorService

void setExecutorService(ExecutorService executorService)

Parameters:

executorService - the ExecutorService to be used by all services that spawn threads

getConnectionHub

ConnectionHub getConnectionHub()

Deprecated.

use newClient(String, int, boolean)

Returns:

a new ConnectionHub instance

getParserConfiguration

ParserConfiguration getParserConfiguration()

Returns:

the ParserConfiguration to be used by all parsers obtained from this class.

getServerConfiguration

ServerConfiguration getServerConfiguration()

Returns:

the ServerConfiguration to be used by all HL7 servers obtained from this class.

See Also:

• newServer(int, boolean)
• newServer(int, int, boolean)

setServerConfiguration

void setServerConfiguration(ServerConfiguration theServerConfiguration)

Sets the ServerConfiguration to be used by all HL7 servers obtained from this class.

See Also:

• newServer(int, boolean)
• newServer(int, int, boolean)

setParserConfiguration

void setParserConfiguration(ParserConfiguration configuration)

Parameters:

configuration - ParserConfiguration to be used by all parsers obtained from this class.

getValidationContext

ValidationContext getValidationContext()

Returns:

the ValidationContext to be used by all parsers obtained from this class.

setValidationContext

void setValidationContext(ValidationContext context)

Parameters:

context - ValidationContext to be used by all parsers obtained from this class.

setValidationContext

void setValidationContext(String contextClassName)

Sets a default ValidationContext. Note that a default ValidationRuleBuilder has precedence of this ValidationContext.

Parameters:

contextClassName - class name of the ValidationContext to be used by all parsers obtained from this class.

getValidationRuleBuilder

ValidationRuleBuilder getValidationRuleBuilder()

Returns:

the ValidationRuleBuilder to be used by all parsers obtained from this class.

setValidationRuleBuilder

void setValidationRuleBuilder(ValidationRuleBuilder ruleBuilder)

Sets a default ValidationRuleBuilder. Note that this ValidationRuleBuilder has precedence over a default ValidationContext set with setValidationContext(ValidationContext) or setValidationContext(String)

Parameters:

ruleBuilder - ValidationRuleBuilder to be used by all parsers obtained from this class.

setValidationRuleBuilder

void setValidationRuleBuilder(String builderClassName)

Sets a new instance of ValidationRuleBuilder as default. Note that this ValidationRuleBuilder has precedence over a default ValidationContext set with setValidationContext(ValidationContext) or setValidationContext(String)

Parameters:

builderClassName - class name of the ValidationRuleBuilder to be used by all parsers obtained from this class.

getModelClassFactory

ModelClassFactory getModelClassFactory()

Returns:

the ModelClassFactory to be used by all parsers obtained from this class.

setModelClassFactory

void setModelClassFactory(ModelClassFactory modelClassFactory)

Parameters:

modelClassFactory - the ModelClassFactory to be used by all parsers obtained from this class.

getProfileStore

ProfileStore getProfileStore()

Returns:

the ProfileStore to be used for loading conformance profile files

setProfileStore

void setProfileStore(ProfileStore store)

Parameters:

store - the ProfileStore to be used for loading conformance profile files

getCodeStoreRegistry

CodeStoreRegistry getCodeStoreRegistry()

Returns:

the CodeStoreRegistry to be used for serving codes for conformance profiles

setCodeStoreRegistry

void setCodeStoreRegistry(CodeStoreRegistry store)

Parameters:

store - the CodeStoreRegistry to be used for serving codes for conformance profiles

getPipeParser

PipeParser getPipeParser()

Returns:

a new PipeParser instance initialized as set with setModelClassFactory(ModelClassFactory), setValidationContext(String) and setParserConfiguration(ParserConfiguration).

getXMLParser

XMLParser getXMLParser()

Returns:

a new XMLParser instance initialized as set with setModelClassFactory(ModelClassFactory), setValidationContext(String) and setParserConfiguration(ParserConfiguration).

getGenericParser

GenericParser getGenericParser()

Returns:

a new GenericParser instance initialized as set with setModelClassFactory(ModelClassFactory), setValidationContext(String) and setParserConfiguration(ParserConfiguration).

getConformanceValidator

Validator getConformanceValidator()

Returns a ca.uhn.hl7v2.conf.check.Validator instance. It is recommended to use getMessageValidator() and configure a Validation rule that checks a message against a conformance profile

Returns:

a ca.uhn.hl7v2.conf.check.Validator instance initialized as set with setCodeStoreRegistry(CodeStoreRegistry)

getMessageValidator

<R> Validator<R> getMessageValidator()

Returns:

a MessageValidator instance initialized with the ValidationContext as set using setValidationContext(ValidationContext). For each validation it will use a new instance of ValidationExceptionHandler as obtained by getValidationExceptionHandlerFactory().

getValidationExceptionHandlerFactory

<R> ValidationExceptionHandlerFactory<R> getValidationExceptionHandlerFactory()

setValidationExceptionHandlerFactory

<R> void setValidationExceptionHandlerFactory(ValidationExceptionHandlerFactory<R> factory)

Parameters:

factory - a ValidationExceptionHandlerFactory that is used to create a ValidationExceptionHandler during message validation.

getLowerLayerProtocol

LowerLayerProtocol getLowerLayerProtocol()

Returns:

the LowerLayerProtocol instance used by all HL7 MLLP operations

setLowerLayerProtocol

void setLowerLayerProtocol(LowerLayerProtocol llp)

Parameters:

llp - the LowerLayerProtocol instance used by all HL7 MLLP operations

getSocketFactory

SocketFactory getSocketFactory()

Returns:

the SocketFactory instance used by HL7 networking operations

setSocketFactory

void setSocketFactory(SocketFactory socketFactory)

Parameters:

socketFactory - the SocketFactory instance used by HL7 networking operations

newServer

HL7Service newServer(int port,
 boolean tls)

Construct a new HL7 Server which will listen for incoming connections

Parameters:

port - The port on which to listen for new connections

tls - Whether or not to use SSL/TLS

Returns:

HL7 service running on the configured port using the default parser and executor service instances provided by this interface. Note that the returned service will not be started, and must manually be started using Service.start() or Service.startAndWait()

See Also:

• here for an example of how to use this method
• setSocketFactory(SocketFactory)

newServer

HL7Service newServer(int port,
 boolean tls,
 boolean acceptAll)

Construct a new HL7 Server which will listen for incoming connections and will pass all messages to the responders, even if the message control id is not known to the server

Parameters:

port - The port on which to listen for new connections

tls - Whether or not to use SSL/TLS

acceptAll - Whether or not to accept all messages

Returns:

HL7 service running on the configured port using the default parser and executor service instances provided by this interface. Note that the returned service will not be started, and must manually be started using Service.start() or Service.startAndWait()

See Also:

• here<> for an example of how to use this method
• setSocketFactory(SocketFactory)

newServer

HL7Service newServer(int inboundPort,
 int outboundPort,
 boolean tls)

Construct a new HL7 Server which will listen for a pair of connections (one for incoming messages, one for outgoing)

Parameters:

inboundPort - The port on which to listen for connections for inbound messages

outboundPort - The port on which to listen for connections for outgoing messages

tls - Whether or not to use SSL/TLS

Returns:

HL7 service running on the configured ports using the default parser and executor service instances provided by this interface. Note that the returned service will not be started, and must manually be started using Service.start() or Service.startAndWait()

See Also:

• here for an example of how to use this method
• setSocketFactory(SocketFactory)

newClient

Connection newClient(String host,
 int port,
 boolean tls)
              throws HL7Exception

Construct a new HL7 Client which will connect to an external TCP server for the purpose of sending messages (and receiving responses). Unless otherwise stated, the connection is established by the time this method returns, or an exception should be thrown if the connection can not be established. If a connection to this server already exists, it is reused.

Note that connections are pooled by the HapiContext by default. If multiple concurrent connections to the same server are required, the easiest way to accomplish this is currently to create multiple HapiContext instances.

Parameters:

host - The host IP/hostname to connect to

port - The port to connect to

tls - Whether or not to use SSL/TLS

Returns:

Returns a connection which can be used to transmit messages. Note that this method will attempt to connect to the specified address, and will throw an exception if it fails to connect.

Throws:

HL7Exception - If the connection can not be initialized for any reason

See Also:

• here for an example of how to use this method

newLazyClient

Connection newLazyClient(String host,
 int port,
 boolean tls)
                  throws HL7Exception

Construct a new HL7 Client which will connect to an external TCP server for the purpose of sending messages (and receiving responses). The connection should be established by the time the first message is sent.

Note that connections are pooled by the HapiContext by default. If multiple concurrent connections to the same server are required, the easiest way to accomplish this is currently to create multiple HapiContext instances.

Parameters:

host - The host IP/hostname to connect to

port - The port to connect to

tls - Whether or not to use SSL/TLS

Returns:

Returns a connection which can be used to transmit messages.

Throws:

HL7Exception - If the connection can not be initialized for any reason

See Also:

• here for an example of how to use this method

newClient

Connection newClient(String host,
 int outboundPort,
 int inboundPort,
 boolean tls)
              throws HL7Exception

Construct a new HL7 two-port client which will connect to an external TCP server for the purpose of sending messages (and receiving responses). Unless otherwise stated, the connection is established by the time this method returns, or an exception should be thrown if the connection can not be established. If a connection to this server already exists, it is reused.

Note that connections are pooled by the HapiContext by default. If multiple concurrent connections to the same server are required, the easiest way to accomplish this is currently to create multiple HapiContext instances.

Parameters:

host - The host IP/hostname to connect to

outboundPort - The port to connect to for outgoing messages

inboundPort - The port to connect to for inbound (response) messages

tls - Whether or not to use SSL/TLS

Returns:

Returns a connection which can be used to transmit messages. Note that this method will attempt to connect to the specified address, and will throw an exception if it fails to connect.

Throws:

HL7Exception - If the connection can not be initialized for any reason

newLazyClient

Connection newLazyClient(String host,
 int outboundPort,
 int inboundPort,
 boolean tls)
                  throws HL7Exception

Construct a new HL7 two-port client which will connect to an external TCP server for the purpose of sending messages (and receiving responses). The connection should be established by the time the first message is sent.

Note that connections are pooled by the HapiContext by default. If multiple concurrent connections to the same server are required, the easiest way to accomplish this is currently to create multiple HapiContext instances.

Parameters:

host - The host IP/hostname to connect to

outboundPort - The port to connect to for outgoing messages

inboundPort - The port to connect to for inbound (response) messages

tls - Whether or not to use SSL/TLS

Returns:

Returns a connection which can be used to transmit messages.

Throws:

HL7Exception - If the connection can not be initialized for any reason

newMessage

Message newMessage(String eventType,
 String triggerEvent,
 Version version)
            throws HL7Exception

Creates a new message of the given event type, trigger and version, and initializes the message header

Parameters:

eventType - event type, e.g. ADT

triggerEvent - trigger event, e.g. A01

version - HL7v2 version

Returns:

Message object of the type determined by the underlying model class factory

Throws:

HL7Exception - if no message object could be created

newMessage

<T extends Message> T newMessage(Class<T> clazz)
                          throws HL7Exception

Creates a new message of the provided message structure class, without further initializing the message

Type Parameters:

T - message structure class type

Parameters:

clazz - message structure class

Returns:

the created message instance

Throws:

HL7Exception