View Javadoc

1   /**
2   The contents of this file are subject to the Mozilla Public License Version 1.1 
3   (the "License"); you may not use this file except in compliance with the License. 
4   You may obtain a copy of the License at http://www.mozilla.org/MPL/ 
5   Software distributed under the License is distributed on an "AS IS" basis, 
6   WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the 
7   specific language governing rights and limitations under the License. 
8   
9   The Original Code is "HapiContext.java".  Description: 
10  "HAPI configuration and factory" 
11  
12  The Initial Developer of the Original Code is University Health Network. Copyright (C) 
13  2001.  All Rights Reserved. 
14  
15  Contributor(s): ______________________________________. 
16  
17  Alternatively, the contents of this file may be used under the terms of the 
18  GNU General Public License (the  "GPL"), in which case the provisions of the GPL are 
19  applicable instead of those above.  If you wish to allow use of your version of this 
20  file only under the terms of the GPL and not to allow others to use your version 
21  of this file under the MPL, indicate your decision by deleting  the provisions above 
22  and replace  them with the notice and other provisions required by the GPL License.  
23  If you do not delete the provisions above, a recipient may use your version of 
24  this file under either the MPL or the GPL. 
25   */
26  package ca.uhn.hl7v2;
27  
28  import java.util.concurrent.ExecutorService;
29  
30  import ca.uhn.hl7v2.app.Connection;
31  import ca.uhn.hl7v2.app.ConnectionHub;
32  import ca.uhn.hl7v2.app.HL7Service;
33  import ca.uhn.hl7v2.app.SimpleServer;
34  import ca.uhn.hl7v2.app.TwoPortService;
35  import ca.uhn.hl7v2.conf.store.CodeStoreRegistry;
36  import ca.uhn.hl7v2.conf.store.ProfileStore;
37  import ca.uhn.hl7v2.llp.LowerLayerProtocol;
38  import ca.uhn.hl7v2.parser.GenericParser;
39  import ca.uhn.hl7v2.parser.ModelClassFactory;
40  import ca.uhn.hl7v2.parser.ParserConfiguration;
41  import ca.uhn.hl7v2.parser.PipeParser;
42  import ca.uhn.hl7v2.parser.XMLParser;
43  import ca.uhn.hl7v2.util.SocketFactory;
44  import ca.uhn.hl7v2.validation.ValidationContext;
45  import ca.uhn.hl7v2.validation.ValidationExceptionHandler;
46  import ca.uhn.hl7v2.validation.ValidationExceptionHandlerFactory;
47  import ca.uhn.hl7v2.validation.Validator;
48  import ca.uhn.hl7v2.validation.builder.ValidationRuleBuilder;
49  
50  /**
51   * Interface that provides a starting point for
52   * <ul>
53   * <li>Configuring HAPI core services (e.g. parsing)
54   * <li>Obtaining correspondingly configured instances of HAPI core services
55   * </ul>
56   * 
57   * HapiContext instances are not supposed to be singletons, i.e. if necessary, it is possible to
58   * have several HapiContexts within one application.
59   * <p>
60   * HapiContext objects maintains the following configuration information
61   * <ul>
62   * <li>{@link ExecutorService}: thread executors used for the HAPI networking features in
63   * ca.uhn.hl7v2.app
64   * <li>{@link LowerLayerProtocol}: MLLP protocol used for the HAPI networking features in
65   * ca.uhn.hl7v2.app
66   * <li>{@link SocketFactory}: Socket factory used for the HAPI networking features in
67   * ca.uhn.hl7v2.app
68   * <li>{@link ParserConfiguration}: detail configuration for all HL7 parsers
69   * <li>{@link ModelClassFactory}: lookup for message model classes during parsing or message
70   * creation
71   * <li>{@link ValidationContext}: validation rules used during parsing or during a dedcated
72   * validation step
73   * <li>{@link ValidationRuleBuilder}: alternative way of providing a ValidationContext
74   * <li>{@link ValidationExceptionHandlerFactory}: factory for exception handler used during message validation
75   * </ul>
76   * <p>
77   * HapiContext serves as factory for HAPI objects that refer to this configuration. Changing the
78   * configuration automatically influence all HAPI objects that were created and will be created
79   * using the given factory instance:
80   * <ul>
81   * <li>{@link PipeParser}
82   * <li>{@link XMLParser}
83   * <li>{@link GenericParser}
84   * <li>{@link Validator}
85   * <li>{@link ConnectionHub}
86   * <li>{@link SimpleServer}
87   * <li>{@link TwoPortService}
88   * </ul>
89   * 
90   */
91  public interface HapiContext {
92  
93  	/**
94  	 * @return the {@link ExecutorService} to be used by all services that spawn threads
95  	 */
96  	ExecutorService getExecutorService();
97  
98  	/**
99  	 * @param executorService the {@link ExecutorService} to be used by all services that spawn
100 	 *            threads
101 	 */
102 	void setExecutorService(ExecutorService executorService);
103 
104 	/**
105 	 * @return a new ConnectionHub instance
106 	 */
107 	ConnectionHub getConnectionHub();
108 
109 	/**
110 	 * @return the {@link ParserConfiguration} to be used by all parsers obtained from this class.
111 	 */
112 	ParserConfiguration getParserConfiguration();
113 
114 	/**
115 	 * @param configuration {@link ParserConfiguration} to be used by all parsers obtained from this
116 	 *            class.
117 	 */
118 	void setParserConfiguration(ParserConfiguration configuration);
119 
120 	/**
121 	 * @return the {@link ValidationContext} to be used by all parsers obtained from this class.
122 	 */
123 	ValidationContext getValidationContext();
124 
125 	/**
126 	 * @param context {@link ValidationContext} to be used by all parsers obtained from this class.
127 	 */
128 	void setValidationContext(ValidationContext context);
129 
130 	/**
131 	 * Sets a default {@link ValidationContext}. Note that a default {@link ValidationRuleBuilder}
132 	 * has precedence of this ValidationContext.
133 	 * 
134 	 * @param contextClassName class name of the {@link ValidationContext} to be used by all parsers
135 	 *            obtained from this class.
136 	 */
137 	void setValidationContext(String contextClassName);
138 
139 	/**
140 	 * @return the {@link ValidationRuleBuilder} to be used by all parsers obtained from this class.
141 	 */
142 	ValidationRuleBuilder getValidationRuleBuilder();
143 
144 	/**
145 	 * Sets a default {@link ValidationRuleBuilder}. Note that this {@link ValidationRuleBuilder}
146 	 * has precedence over a default {@link ValidationContext} set with
147 	 * {@link #setValidationContext(ValidationContext)} or {@link #setValidationContext(String)}
148 	 * 
149 	 * @param ruleBuilder {@link ValidationRuleBuilder} to be used by all parsers obtained from this
150 	 *            class.
151 	 */
152 	void setValidationRuleBuilder(ValidationRuleBuilder ruleBuilder);
153 
154 	/**
155 	 * Sets a new instance of {@link ValidationRuleBuilder} as default. Note that this
156 	 * {@link ValidationRuleBuilder} has precedence over a default {@link ValidationContext} set
157 	 * with {@link #setValidationContext(ValidationContext)} or
158 	 * {@link #setValidationContext(String)}
159 	 * 
160 	 * @param builderClassName class name of the {@link ValidationRuleBuilder} to be used by all
161 	 *            parsers obtained from this class.
162 	 */
163 	void setValidationRuleBuilder(String builderClassName);
164 
165 	/**
166 	 * @return the {@link ModelClassFactory} to be used by all parsers obtained from this class.
167 	 */
168 	ModelClassFactory getModelClassFactory();
169 
170 	/**
171 	 * @param modelClassFactory the {@link ModelClassFactory} to be used by all parsers obtained
172 	 *            from this class.
173 	 */
174 	void setModelClassFactory(ModelClassFactory modelClassFactory);
175 	
176 	/**
177 	 * @return the {@link ProfileStore} to be used for loading conformance profile files
178 	 */
179 	ProfileStore getProfileStore();
180 	
181 	/**
182 	 * @param store the {@link ProfileStore} to be used for loading conformance profile files
183 	 */
184 	void setProfileStore(ProfileStore store);
185 	
186     /**
187      * @return the {@link CodeStoreRegistry} to be used for serving codes for conformance profiles
188      */
189 	CodeStoreRegistry getCodeStoreRegistry();
190     
191     /**
192      * @param store the {@link CodeStoreRegistry} to be used for serving codes for conformance profiles
193      */
194     void setCodeStoreRegistry(CodeStoreRegistry store);	
195 
196 	// Default instances of business objects
197 
198 	/**
199 	 * @return a new PipeParser instance initialized as set with
200 	 *         {@link #setModelClassFactory(ModelClassFactory)},
201 	 *         {@link #setValidationContext(String)} and
202 	 *         {@link #setParserConfiguration(ParserConfiguration)}.
203 	 */
204 	PipeParser getPipeParser();
205 
206 	/**
207 	 * @return a new XMLParser instance initialized as set with
208 	 *         {@link #setModelClassFactory(ModelClassFactory)},
209 	 *         {@link #setValidationContext(String)} and
210 	 *         {@link #setParserConfiguration(ParserConfiguration)}.
211 	 */
212 	XMLParser getXMLParser();
213 
214 	/**
215 	 * @return a new GenericParser instance initialized as set with
216 	 *         {@link #setModelClassFactory(ModelClassFactory)},
217 	 *         {@link #setValidationContext(String)} and
218 	 *         {@link #setParserConfiguration(ParserConfiguration)}.
219 	 */
220 	GenericParser getGenericParser();
221 
222     /**
223      * Returns a ca.uhn.hl7v2.conf.check.Validator instance. It is recommended to
224      * use {@link #getMessageValidator()} and configure a Validation rule that checks
225      * a message against a conformance profile
226      * 
227      * @return a ca.uhn.hl7v2.conf.check.Validator instance initialized as set with
228      * {@link #setCodeStoreRegistry(CodeStoreRegistry)}
229      */
230     ca.uhn.hl7v2.conf.check.Validator getConformanceValidator();
231     
232 	/**
233 	 * @return a MessageValidator instance initialized with the {@link ValidationContext} as set
234 	 *         using {@link #setValidationContext(ValidationContext)}. For each validation it will
235 	 *         use a new instance of {@link ValidationExceptionHandler} as obtained by
236 	 *         {@link #getValidationExceptionHandlerFactory()}.
237 	 */
238 	<R> Validator<R> getMessageValidator();
239 	
240 	<R> ValidationExceptionHandlerFactory<R> getValidationExceptionHandlerFactory();
241 	
242 	/**
243 	 * @param factory a {@link ValidationExceptionHandlerFactory} that is used to create
244 	 * a {@link ValidationExceptionHandler} during message validation.
245 	 */
246 	<R> void setValidationExceptionHandlerFactory(ValidationExceptionHandlerFactory<R> factory);
247 
248 	/**
249 	 * @return the {@link LowerLayerProtocol} instance used by all HL7 MLLP operations
250 	 */
251 	LowerLayerProtocol getLowerLayerProtocol();
252 
253 	/**
254 	 * @param llp the {@link LowerLayerProtocol} instance used by all HL7 MLLP operations
255 	 */
256 	void setLowerLayerProtocol(LowerLayerProtocol llp);
257 
258 	/**
259 	 * @return the {@link SocketFactory} instance used by HL7 networking operations
260 	 */
261 	SocketFactory getSocketFactory();
262 
263 	/**
264 	 * @param socketFactory the {@link SocketFactory} instance used by HL7 networking operations
265 	 */
266 	void setSocketFactory(SocketFactory socketFactory);
267 
268 	/**
269 	 * Construct a new HL7 Server which will listen for incoming connections
270 	 * 
271 	 * @param port The port on which to listen for new connections
272 	 * @param tls Whether or not to use SSL/TLS
273 	 * @return HL7 service running on the configured port using the default parser and executor
274 	 *         service instances provided by this interface. Note that the returned service <b>will not
275 	 *         be started</b>, and must manually be started using {@link HL7Service#start()} or
276 	 *         {@link HL7Service#startAndWait()}
277 	 * @see <a href="http://hl7api.sourceforge.net/xref/ca/uhn/hl7v2/examples/SendAndReceiveAMessage.html">here</a> for an example of how to use this method
278 	 * @see #setSocketFactory(SocketFactory)
279 	 */
280 	HL7Service newServer(int port, boolean tls);
281 
282 	/**
283 	 * Construct a new HL7 Server which will listen for a pair of connections (one for
284 	 * incoming messages, one for outgoing)
285 	 * 
286 	 * @param inboundPort The port on which to listen for connections for inbound messages
287 	 * @param outboundPort The port on which to listen for connections for outgoing messages
288 	 * @param tls Whether or not to use SSL/TLS
289 	 * @return HL7 service running on the configured ports using the default parser and executor
290 	 *         service instances provided by this interface. Note that the returned service <b>will not
291 	 *         be started</b>, and must manually be started using {@link HL7Service#start()} or
292 	 *         {@link HL7Service#startAndWait()}
293 	 * @see <a href="http://hl7api.sourceforge.net/xref/ca/uhn/hl7v2/examples/SendAndReceiveAMessage.html">here</a> for an example of how to use this method
294 	 * @see #setSocketFactory(SocketFactory)
295 	 */
296 	HL7Service newServer(int inboundPort, int outboundPort, boolean tls);
297 	
298 	/**
299 	 * Construct a new HL7 Client which will connect to an external TCP server for
300 	 * the purpose of sending messages (and receiving responses). Unless otherwise
301 	 * stated, the connection should be established by the time this method
302 	 * returns, or an exception should be thrown if the connection can not be
303 	 * established.
304 	 * 
305 	 * @param host The host IP/hostname to connect to
306 	 * @param port The port to connect to
307 	 * @param tls Whether or not to use SSL/TLS
308 	 * @return Returns a connection which can be used to transmit messages. Note that this method
309 	 *         will attempt to connect to the specified address, and will throw an exception
310 	 *         if it fails to connect.
311 	 * @see <a href="http://hl7api.sourceforge.net/xref/ca/uhn/hl7v2/examples/SendAndReceiveAMessage.html">here</a> for an example of how to use this method
312 	 * @throws HL7Exception If the connection can not be initialized for any reason 
313 	 */
314 	Connection newClient(String host, int port, boolean tls) throws HL7Exception;
315 
316 	/**
317 	 * Construct a new HL7 two-port client which will connect to an external TCP server for
318 	 * the purpose of sending messages (and receiving responses). Unless otherwise
319 	 * stated, the connection should be established by the time this method
320 	 * returns, or an exception should be thrown if the connection can not be
321 	 * established.
322 	 * 
323 	 * @param host The host IP/hostname to connect to
324 	 * @param outboundPort The port to connect to for outgoing messages
325 	 * @param inboundPort The port to connect to for inbound (response) messages
326 	 * @param tls Whether or not to use SSL/TLS
327 	 * @return Returns a connection which can be used to transmit messages. Note that this method
328 	 *         will attempt to connect to the specified address, and will throw an exception
329 	 *         if it fails to connect.
330 	 * @throws HL7Exception If the connection can not be initialized for any reason 
331 	 */
332 	Connection newClient(String host, int outboundPort, int inboundPort, boolean tls) throws HL7Exception;
333 
334 }