Coverage Report - ca.uhn.hl7v2.HapiContext
 
Classes in this File Line Coverage Branch Coverage Complexity
HapiContext
N/A
N/A
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.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  
 }