Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
HapiContext |
|
| 1.0;1 |
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.io.Closeable; | |
29 | import java.util.concurrent.ExecutorService; | |
30 | ||
31 | import ca.uhn.hl7v2.app.Connection; | |
32 | import ca.uhn.hl7v2.app.ConnectionHub; | |
33 | import ca.uhn.hl7v2.app.HL7Service; | |
34 | import ca.uhn.hl7v2.app.ServerConfiguration; | |
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.model.Message; | |
39 | import ca.uhn.hl7v2.parser.*; | |
40 | import ca.uhn.hl7v2.util.SocketFactory; | |
41 | import ca.uhn.hl7v2.validation.ValidationContext; | |
42 | import ca.uhn.hl7v2.validation.ValidationExceptionHandlerFactory; | |
43 | import ca.uhn.hl7v2.validation.Validator; | |
44 | import ca.uhn.hl7v2.validation.builder.ValidationRuleBuilder; | |
45 | ||
46 | /** | |
47 | * Interface that provides a starting point for | |
48 | * <ul> | |
49 | * <li>Configuring HAPI core services (e.g. parsing) | |
50 | * <li>Obtaining correspondingly configured instances of HAPI core services | |
51 | * </ul> | |
52 | * <p/> | |
53 | * HapiContext instances are not supposed to be singletons, i.e. if necessary, it is possible to | |
54 | * have several HapiContexts within one application. | |
55 | * <p/> | |
56 | * HapiContext objects maintains the following configuration information | |
57 | * <ul> | |
58 | * <li>{@link ExecutorService}: thread executors used for the HAPI networking features in | |
59 | * ca.uhn.hl7v2.app | |
60 | * <li>{@link LowerLayerProtocol}: MLLP protocol used for the HAPI networking features in | |
61 | * ca.uhn.hl7v2.app | |
62 | * <li>{@link SocketFactory}: Socket factory used for the HAPI networking features in | |
63 | * ca.uhn.hl7v2.app | |
64 | * <li>{@link ParserConfiguration}: detail configuration for all HL7 parsers | |
65 | * <li>{@link ModelClassFactory}: lookup for message model classes during parsing or message | |
66 | * creation | |
67 | * <li>{@link ValidationContext}: validation rules used during parsing or during a dedcated | |
68 | * validation step | |
69 | * <li>{@link ValidationRuleBuilder}: alternative way of providing a ValidationContext | |
70 | * <li>{@link ValidationExceptionHandlerFactory}: factory for exception handler used during message validation | |
71 | * </ul> | |
72 | * <p/> | |
73 | * HapiContext serves as factory for HAPI objects that refer to this configuration. Changing the | |
74 | * configuration automatically influence all HAPI objects that were created and will be created | |
75 | * using the given factory instance: | |
76 | * <ul> | |
77 | * <li>{@link PipeParser} | |
78 | * <li>{@link XMLParser} | |
79 | * <li>{@link GenericParser} | |
80 | * <li>{@link Validator} | |
81 | * <li>{@link ConnectionHub} | |
82 | * <li>{@link ca.uhn.hl7v2.app.SimpleServer} | |
83 | * <li>{@link ca.uhn.hl7v2.app.TwoPortService} | |
84 | * </ul> | |
85 | */ | |
86 | public interface HapiContext extends Closeable { | |
87 | ||
88 | /** | |
89 | * @return the {@link ExecutorService} to be used by all services that spawn threads | |
90 | */ | |
91 | ExecutorService getExecutorService(); | |
92 | ||
93 | /** | |
94 | * @param executorService the {@link ExecutorService} to be used by all services that spawn | |
95 | * threads | |
96 | */ | |
97 | void setExecutorService(ExecutorService executorService); | |
98 | ||
99 | /** | |
100 | * @return a new ConnectionHub instance | |
101 | * @deprecated use {@link #newClient(String, int, boolean)} | |
102 | */ | |
103 | ConnectionHub getConnectionHub(); | |
104 | ||
105 | /** | |
106 | * @return the {@link ParserConfiguration} to be used by all parsers obtained from this class. | |
107 | */ | |
108 | ParserConfiguration getParserConfiguration(); | |
109 | ||
110 | /** | |
111 | * @return the {@link ServerConfiguration} to be used by all HL7 servers obtained from this class. | |
112 | * @see #newServer(int, boolean) | |
113 | * @see #newServer(int, int, boolean) | |
114 | */ | |
115 | ServerConfiguration getServerConfiguration(); | |
116 | ||
117 | /** | |
118 | * Sets the {@link ServerConfiguration} to be used by all HL7 servers obtained from this class. | |
119 | * | |
120 | * @see #newServer(int, boolean) | |
121 | * @see #newServer(int, int, boolean) | |
122 | */ | |
123 | void setServerConfiguration(ServerConfiguration theServerConfiguration); | |
124 | ||
125 | /** | |
126 | * @param configuration {@link ParserConfiguration} to be used by all parsers obtained from this | |
127 | * class. | |
128 | */ | |
129 | void setParserConfiguration(ParserConfiguration configuration); | |
130 | ||
131 | /** | |
132 | * @return the {@link ValidationContext} to be used by all parsers obtained from this class. | |
133 | */ | |
134 | ValidationContext getValidationContext(); | |
135 | ||
136 | /** | |
137 | * @param context {@link ValidationContext} to be used by all parsers obtained from this class. | |
138 | */ | |
139 | void setValidationContext(ValidationContext context); | |
140 | ||
141 | /** | |
142 | * Sets a default {@link ValidationContext}. Note that a default {@link ValidationRuleBuilder} | |
143 | * has precedence of this ValidationContext. | |
144 | * | |
145 | * @param contextClassName class name of the {@link ValidationContext} to be used by all parsers | |
146 | * obtained from this class. | |
147 | */ | |
148 | void setValidationContext(String contextClassName); | |
149 | ||
150 | /** | |
151 | * @return the {@link ValidationRuleBuilder} to be used by all parsers obtained from this class. | |
152 | */ | |
153 | ValidationRuleBuilder getValidationRuleBuilder(); | |
154 | ||
155 | /** | |
156 | * Sets a default {@link ValidationRuleBuilder}. Note that this {@link ValidationRuleBuilder} | |
157 | * has precedence over a default {@link ValidationContext} set with | |
158 | * {@link #setValidationContext(ValidationContext)} or {@link #setValidationContext(String)} | |
159 | * | |
160 | * @param ruleBuilder {@link ValidationRuleBuilder} to be used by all parsers obtained from this | |
161 | * class. | |
162 | */ | |
163 | void setValidationRuleBuilder(ValidationRuleBuilder ruleBuilder); | |
164 | ||
165 | /** | |
166 | * Sets a new instance of {@link ValidationRuleBuilder} as default. Note that this | |
167 | * {@link ValidationRuleBuilder} has precedence over a default {@link ValidationContext} set | |
168 | * with {@link #setValidationContext(ValidationContext)} or | |
169 | * {@link #setValidationContext(String)} | |
170 | * | |
171 | * @param builderClassName class name of the {@link ValidationRuleBuilder} to be used by all | |
172 | * parsers obtained from this class. | |
173 | */ | |
174 | void setValidationRuleBuilder(String builderClassName); | |
175 | ||
176 | /** | |
177 | * @return the {@link ModelClassFactory} to be used by all parsers obtained from this class. | |
178 | */ | |
179 | ModelClassFactory getModelClassFactory(); | |
180 | ||
181 | /** | |
182 | * @param modelClassFactory the {@link ModelClassFactory} to be used by all parsers obtained | |
183 | * from this class. | |
184 | */ | |
185 | void setModelClassFactory(ModelClassFactory modelClassFactory); | |
186 | ||
187 | /** | |
188 | * @return the {@link ProfileStore} to be used for loading conformance profile files | |
189 | */ | |
190 | ProfileStore getProfileStore(); | |
191 | ||
192 | /** | |
193 | * @param store the {@link ProfileStore} to be used for loading conformance profile files | |
194 | */ | |
195 | void setProfileStore(ProfileStore store); | |
196 | ||
197 | /** | |
198 | * @return the {@link CodeStoreRegistry} to be used for serving codes for conformance profiles | |
199 | */ | |
200 | CodeStoreRegistry getCodeStoreRegistry(); | |
201 | ||
202 | /** | |
203 | * @param store the {@link CodeStoreRegistry} to be used for serving codes for conformance profiles | |
204 | */ | |
205 | void setCodeStoreRegistry(CodeStoreRegistry store); | |
206 | ||
207 | // Default instances of business objects | |
208 | ||
209 | /** | |
210 | * @return a new PipeParser instance initialized as set with | |
211 | * {@link #setModelClassFactory(ModelClassFactory)}, | |
212 | * {@link #setValidationContext(String)} and | |
213 | * {@link #setParserConfiguration(ParserConfiguration)}. | |
214 | */ | |
215 | PipeParser getPipeParser(); | |
216 | ||
217 | /** | |
218 | * @return a new XMLParser instance initialized as set with | |
219 | * {@link #setModelClassFactory(ModelClassFactory)}, | |
220 | * {@link #setValidationContext(String)} and | |
221 | * {@link #setParserConfiguration(ParserConfiguration)}. | |
222 | */ | |
223 | XMLParser getXMLParser(); | |
224 | ||
225 | /** | |
226 | * @return a new GenericParser instance initialized as set with | |
227 | * {@link #setModelClassFactory(ModelClassFactory)}, | |
228 | * {@link #setValidationContext(String)} and | |
229 | * {@link #setParserConfiguration(ParserConfiguration)}. | |
230 | */ | |
231 | GenericParser getGenericParser(); | |
232 | ||
233 | /** | |
234 | * Returns a ca.uhn.hl7v2.conf.check.Validator instance. It is recommended to | |
235 | * use {@link #getMessageValidator()} and configure a Validation rule that checks | |
236 | * a message against a conformance profile | |
237 | * | |
238 | * @return a ca.uhn.hl7v2.conf.check.Validator instance initialized as set with | |
239 | * {@link #setCodeStoreRegistry(CodeStoreRegistry)} | |
240 | */ | |
241 | ca.uhn.hl7v2.conf.check.Validator getConformanceValidator(); | |
242 | ||
243 | /** | |
244 | * @return a MessageValidator instance initialized with the {@link ValidationContext} as set | |
245 | * using {@link #setValidationContext(ValidationContext)}. For each validation it will | |
246 | * use a new instance of {@link ca.uhn.hl7v2.validation.ValidationExceptionHandler ValidationExceptionHandler} as obtained by | |
247 | * {@link #getValidationExceptionHandlerFactory()}. | |
248 | */ | |
249 | <R> Validator<R> getMessageValidator(); | |
250 | ||
251 | <R> ValidationExceptionHandlerFactory<R> getValidationExceptionHandlerFactory(); | |
252 | ||
253 | /** | |
254 | * @param factory a {@link ValidationExceptionHandlerFactory} that is used to create | |
255 | * a {@link ca.uhn.hl7v2.validation.ValidationExceptionHandler ValidationExceptionHandler} during message validation. | |
256 | */ | |
257 | <R> void setValidationExceptionHandlerFactory(ValidationExceptionHandlerFactory<R> factory); | |
258 | ||
259 | /** | |
260 | * @return the {@link LowerLayerProtocol} instance used by all HL7 MLLP operations | |
261 | */ | |
262 | LowerLayerProtocol getLowerLayerProtocol(); | |
263 | ||
264 | /** | |
265 | * @param llp the {@link LowerLayerProtocol} instance used by all HL7 MLLP operations | |
266 | */ | |
267 | void setLowerLayerProtocol(LowerLayerProtocol llp); | |
268 | ||
269 | /** | |
270 | * @return the {@link SocketFactory} instance used by HL7 networking operations | |
271 | */ | |
272 | SocketFactory getSocketFactory(); | |
273 | ||
274 | /** | |
275 | * @param socketFactory the {@link SocketFactory} instance used by HL7 networking operations | |
276 | */ | |
277 | void setSocketFactory(SocketFactory socketFactory); | |
278 | ||
279 | /** | |
280 | * Construct a new HL7 Server which will listen for incoming connections | |
281 | * | |
282 | * @param port The port on which to listen for new connections | |
283 | * @param tls Whether or not to use SSL/TLS | |
284 | * @return HL7 service running on the configured port using the default parser and executor | |
285 | * service instances provided by this interface. Note that the returned service <b>will not | |
286 | * be started</b>, and must manually be started using {@link HL7Service#start()} or | |
287 | * {@link HL7Service#startAndWait()} | |
288 | * @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 | |
289 | * @see #setSocketFactory(SocketFactory) | |
290 | */ | |
291 | HL7Service newServer(int port, boolean tls); | |
292 | ||
293 | /** | |
294 | * Construct a new HL7 Server which will listen for a pair of connections (one for | |
295 | * incoming messages, one for outgoing) | |
296 | * | |
297 | * @param inboundPort The port on which to listen for connections for inbound messages | |
298 | * @param outboundPort The port on which to listen for connections for outgoing messages | |
299 | * @param tls Whether or not to use SSL/TLS | |
300 | * @return HL7 service running on the configured ports using the default parser and executor | |
301 | * service instances provided by this interface. Note that the returned service <b>will not | |
302 | * be started</b>, and must manually be started using {@link HL7Service#start()} or | |
303 | * {@link HL7Service#startAndWait()} | |
304 | * @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 | |
305 | * @see #setSocketFactory(SocketFactory) | |
306 | */ | |
307 | HL7Service newServer(int inboundPort, int outboundPort, boolean tls); | |
308 | ||
309 | /** | |
310 | * Construct a new HL7 Client which will connect to an external TCP server for | |
311 | * the purpose of sending messages (and receiving responses). Unless otherwise | |
312 | * stated, the connection is established by the time this method | |
313 | * returns, or an exception should be thrown if the connection can not be | |
314 | * established. If a connection to this server already exists, it is reused. | |
315 | * <p> | |
316 | * Note that connections are pooled by the HapiContext by default. If multiple | |
317 | * concurrent connections to the same server are required, the easiest way | |
318 | * to accomplish this is currently to create multiple HapiContext instances. | |
319 | * </p> | |
320 | * | |
321 | * @param host The host IP/hostname to connect to | |
322 | * @param port The port to connect to | |
323 | * @param tls Whether or not to use SSL/TLS | |
324 | * @return Returns a connection which can be used to transmit messages. Note that this method | |
325 | * will attempt to connect to the specified address, and will throw an exception | |
326 | * if it fails to connect. | |
327 | * @throws HL7Exception If the connection can not be initialized for any reason | |
328 | * @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 | |
329 | */ | |
330 | Connection newClient(String host, int port, boolean tls) throws HL7Exception; | |
331 | ||
332 | /** | |
333 | * Construct a new HL7 Client which will connect to an external TCP server for | |
334 | * the purpose of sending messages (and receiving responses). The connection | |
335 | * should be established by the time the first message is sent. | |
336 | * <p> | |
337 | * Note that connections are pooled by the HapiContext by default. If multiple | |
338 | * concurrent connections to the same server are required, the easiest way | |
339 | * to accomplish this is currently to create multiple HapiContext instances. | |
340 | * </p> | |
341 | * | |
342 | * @param host The host IP/hostname to connect to | |
343 | * @param port The port to connect to | |
344 | * @param tls Whether or not to use SSL/TLS | |
345 | * @return Returns a connection which can be used to transmit messages. | |
346 | * @throws HL7Exception If the connection can not be initialized for any reason | |
347 | * @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 | |
348 | */ | |
349 | Connection newLazyClient(String host, int port, boolean tls) throws HL7Exception; | |
350 | ||
351 | /** | |
352 | * Construct a new HL7 two-port client which will connect to an external TCP server for | |
353 | * the purpose of sending messages (and receiving responses). Unless otherwise | |
354 | * stated, the connection is established by the time this method | |
355 | * returns, or an exception should be thrown if the connection can not be | |
356 | * established. If a connection to this server already exists, it is reused. | |
357 | * <p> | |
358 | * Note that connections are pooled by the HapiContext by default. If multiple | |
359 | * concurrent connections to the same server are required, the easiest way | |
360 | * to accomplish this is currently to create multiple HapiContext instances. | |
361 | * </p> | |
362 | * | |
363 | * @param host The host IP/hostname to connect to | |
364 | * @param outboundPort The port to connect to for outgoing messages | |
365 | * @param inboundPort The port to connect to for inbound (response) messages | |
366 | * @param tls Whether or not to use SSL/TLS | |
367 | * @return Returns a connection which can be used to transmit messages. Note that this method | |
368 | * will attempt to connect to the specified address, and will throw an exception | |
369 | * if it fails to connect. | |
370 | * @throws HL7Exception If the connection can not be initialized for any reason | |
371 | */ | |
372 | Connection newClient(String host, int outboundPort, int inboundPort, boolean tls) throws HL7Exception; | |
373 | ||
374 | /** | |
375 | * Construct a new HL7 two-port client which will connect to an external TCP server for | |
376 | * the purpose of sending messages (and receiving responses). The connection | |
377 | * should be established by the time the first message is sent. | |
378 | * <p> | |
379 | * Note that connections are pooled by the HapiContext by default. If multiple | |
380 | * concurrent connections to the same server are required, the easiest way | |
381 | * to accomplish this is currently to create multiple HapiContext instances. | |
382 | * </p> | |
383 | * | |
384 | * @param host The host IP/hostname to connect to | |
385 | * @param outboundPort The port to connect to for outgoing messages | |
386 | * @param inboundPort The port to connect to for inbound (response) messages | |
387 | * @param tls Whether or not to use SSL/TLS | |
388 | * @return Returns a connection which can be used to transmit messages. | |
389 | * @throws HL7Exception If the connection can not be initialized for any reason | |
390 | */ | |
391 | Connection newLazyClient(String host, int outboundPort, int inboundPort, boolean tls) throws HL7Exception; | |
392 | ||
393 | /** | |
394 | * Creates a new message of the given event type, trigger and version, and initializes the message header | |
395 | * | |
396 | * @param eventType event type, e.g. ADT | |
397 | * @param triggerEvent trigger event, e.g. A01 | |
398 | * @param version HL7v2 version | |
399 | * @return Message object of the type determined by the underlying model class factory | |
400 | * @throws HL7Exception if no message object could be created | |
401 | */ | |
402 | Message newMessage(String eventType, String triggerEvent, Version version) throws HL7Exception; | |
403 | ||
404 | /** | |
405 | * Creates a new message of the provided message structure class, without further initializing the message | |
406 | * | |
407 | * @param clazz message structure class | |
408 | * @param <T> message structure class type | |
409 | * @return the created message instance | |
410 | * @throws HL7Exception | |
411 | */ | |
412 | <T extends Message> T newMessage(Class<T> clazz) throws HL7Exception; | |
413 | } |