oracle.hsgbu.hdr.hl7

Interface RimService

public interface RimService

Provides methods to persist and query RIM objects in HDR. This interface provides methods to access factories used in the creation of RIM objects and provides some additional session information.

The submit method persists and queries RIM objects by associating a ControlAct with other Act objects in the Rim package

The accessor methods of the factories are organized by the types of RIM objects: Entity, Role, and Act. These factories contain the complete list of vocabulary-based classes and return the appropriate structural class. For example, there is no special subclass for a document act. Therefore, the newClinicalDocument factory method returns an instance of Act with the class codes set to "DOC". Creating an ObservationAct returns an Observation, which is a subclass of Act. The class code of this Observation is set to "OBS". Creating a specimen observation returns an Observation and sets the class code to "SPCOBS". This same pattern is also true for roles and entities.

ActRelationship and Participation objects are instantiated by the Act object to which the ActRelationship or Participation object is attached. For example:

 // Get an observation instance from the act factory
 Observation obs = actFactory.newObservation(...);
 // Create the ActRelationship and add it to the set of outbound Act Relationships for the observation
 ActRelationship ar = obs.addOBActRelationship( arType, target);
 

The queryActs method is a convenience method that queries RIM objects based on the criteria specified in the ActFetch. The convenience method wraps around the submit method, unwraps the returned ControlAct object, and returns an Iterator of Act objects. Fetches are constructed in the same way as specified in the query package. The queryActRelationships, queryEntities, queryParticipations, and queryRoles methods work in the same way as the queryActs method. The following is sample code to use the query convenience methods:

 // get an instance of the query component factory
 QueryComponentFactory queryComponentFactory = QueryComponentFactory.getInstance(serviceLocator);
 // get an instance of the datatypes factory DataTypeFactory dataTypeFactory =
 DataTypeFactory.getInstance(serviceLocator); // construct an
 ActAttributeCriteria ActAttributeCriteria actAttrCriteria = queryComponentFactory.newActAttributeCriteria();
 // set the ClassCode == ENC to retrieve encounters
 actAttrCriteria.setClassCode(SearchOperator.EQUALS, ActClass.ENC);
 // set the StatusCode == ACTIVE to retrieve active encounters
 actAttrCriteria.setStatusCode(SearchOperator.EQUALS,ActStatus.ACTIVE);
 // set the version flag to retrieve only current versions
 actAttrCriteria.setCurrentVersion(true); // construct an ActFetch with the specified criteria
 ActFetch actFetch = queryComponentFactory.newActFetch(actAttrCriteria);
 rimService = serviceLocator.getRimService();
 // use the convenience method
 java.util.Iterator actIter = rimService.queryActs(serviceLocator, actFetch);
 

All HL7-defined Act, Entity, and Role classes have a corresponding factory except where those classes are not supported by HDR.

Method Summary

Modifier and Type	Method and Description
UID	getInternalOID() Gets the object identifier (OID) used as the root for HDR-assigned identifiers.
Iterator	queryActRelationships(ServiceLocator sl, ActRelationshipFetch fetch) This convenience method provides the user a way to query ActRelationships without the need of wrapping the ActRelationshipFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call
Iterator	queryActs(ServiceLocator sl, ActFetch fetch) This convenience method provides the user a way to query Acts without the need of wrapping the ActFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call
Iterator	queryEntities(ServiceLocator sl, EntityFetch fetch) This convenience method provides the user a way to query Entities without the need of wrapping the EntityFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call
Iterator	queryParticipations(ServiceLocator sl, ParticipationFetch fetch) This convenience method provides the user a way to query Participations without the need of wrapping the ParticipationFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call
Iterator	queryRoles(ServiceLocator sl, RoleFetch fetch) This convenience method provides the user a way to query Roles without the need of wrapping the RoleFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call
ControlAct	submit(ControlAct ctrlAct) Processes a ControlAct object.

Method Detail

getInternalOID

UID getInternalOID()
            throws HDRRimException

Gets the object identifier (OID) used as the root for HDR-assigned identifiers. In addition to any identifiers explicitly added to an object, HDR assigns a unique, internal identifier that can be used to identify the object uniquely. This OID is automatically assigned by the factory methods.

Returns:

The UID used as the internal root by HDR.

Throws:

HDRRimException

queryActs

Iterator queryActs(ServiceLocator sl,
                   ActFetch fetch)
            throws HDRRimException

This convenience method provides the user a way to query Acts without the need of wrapping the ActFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call

Parameters:

sl - service locator, which will be used to instantiate a new instance of a Control Act to use to submit to the RimService

fetch - the fetch to be executed

Returns:

the queried client objects within an Iterator

Throws:

HDRRimException

queryActRelationships

Iterator queryActRelationships(ServiceLocator sl,
                               ActRelationshipFetch fetch)
                        throws HDRRimException

This convenience method provides the user a way to query ActRelationships without the need of wrapping the ActRelationshipFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call

Parameters:

sl - service locator, which will be used to instantiate a new instance of a Control Act to use to submit to the RimService

fetch - the fetch to be executed

Returns:

the queried client objects within an Iterator

Throws:

HDRRimException

queryEntities

Iterator queryEntities(ServiceLocator sl,
                       EntityFetch fetch)
                throws HDRRimException

This convenience method provides the user a way to query Entities without the need of wrapping the EntityFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call

Parameters:

sl - service locator, which will be used to instantiate a new instance of a Control Act to use to submit to the RimService

fetch - the fetch to be executed

Returns:

the queried client objects within an Iterator

Throws:

HDRRimException

queryParticipations

Iterator queryParticipations(ServiceLocator sl,
                             ParticipationFetch fetch)
                      throws HDRRimException

This convenience method provides the user a way to query Participations without the need of wrapping the ParticipationFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call

Parameters:

sl - service locator, which will be used to instantiate a new instance of a Control Act to use to submit to the RimService

fetch - the fetch to be executed

Returns:

the queried client objects within an Iterator

Throws:

HDRRimException

queryRoles

Iterator queryRoles(ServiceLocator sl,
                    RoleFetch fetch)
             throws HDRRimException

This convenience method provides the user a way to query Roles without the need of wrapping the RoleFetch in a ControlAct and then unwrapping the ControlAct returned from the RimService submit API call

Parameters:

sl - service locator, which will be used to instantiate a new instance of a Control Act to use to submit to the RimService

fetch - the fetch to be executed

Returns:

the queried client objects within an Iterator

Throws:

HDRRimException

submit

ControlAct submit(ControlAct ctrlAct)
           throws HDRRimException

Processes a ControlAct object. Persists all Act, Role, and Entity objects related either directly or indirectly to the ControlAct object. If the object is recognized and already exists in HDR, the object is updated, else a new object is created. If the ControlAct object has an ActRelationship object of type "SUBJ" to a QueryAct, this method performs the query specified by the QueryAct.

Parameters:

ctrlAct - The ControlAct to be processed.

Returns:

• A null object if submit was called for persistence.
• A non-null ControlAct object if submit was called for queries. If no actual results are returned from a query, its wrapped query result object will contain an InfrastructureRootImpl[] of length 0.

Throws:

oracle.hsgbu.hdr.exception.server.CommonRuntimeException - If there is a logical problem with a submission. Such an error may only be corrected by modifying the data passed to the submit(oracle.hsgbu.hdr.hl7.rim.ControlAct) method.

HDRRimException - If there is any other problem besides a CommonRuntimeException. Such exceptions may be corrected without changing the submitted ControlAct.