HDR RIM Services
Core functions:
Use The RIM Service
The RimService provides the primary mechanism to persist or query Entities, Roles, Acts and related objects through HDR. Both persist and query operations are supported through the RimService.submit(ControlAct) method.
The control act passed to submit is expected to contain one outbound ActRelationship with a typeCode of SUBJ with an instance of a subclass of Act as its target, which can similarly be related to other objects to form a graph of objects to be persisted. If the target Act of the Act Relationship is an instance of a QueryAct, a data query results; see Section 7.5 for more information about querying.
These code samples help you to:
- Create an Organization Using a Registry Event (see Example 7-16)
- Create an Encounter Using a CREATE_OR_UPDATE Reference to a Patient Object (see Example 7-17)
- Pass an Invalid Code to Generate an Exception (see Example 7-18)
- Rim Validation Exception Output (see Example 7-19)
Example 7-16 Create an Organization Using a Registry Event
The following example illustrates the registration of an Entity—in this case an Organization is created. To create any Entity in HDR you must provide a Role and an Act; typically an AssignedEntity Role is used, and a RegistryEvent is used for the Act.
// Create the ORG Entity to be registered
SET_II orgId = dataTypeFactory.newSET_II("9.989898.5.3.1", "ORG002", true);
Organization organization = entityFactory.newOrganization(
dataTypeFactory.nullCE(NullFlavor.NI),
EntityDeterminer.INSTANCE, orgId);
// Build up the organization name using
SET<CS> orgNameUseCode= dataTypeFactory.newSET_CS(dataTypeFactory.newCS("L"));
ENXP orgNameUsePart = dataTypeFactory.newENXP("Pro Health Systems", null,
dataTypeFactory.nullSET<CS>(NullFlavor.NI));
ENXP[] orgNameUsePartArray = new ENXP[] {orgNameUsePart};
ON orgName = dataTypeFactory.newON(orgNameUsePartArray, orgNameUseCode,
dataTypeFactory.nullIVL<TS>(NullFlavor.NI));
// Set the organization name, desc and status
organization.setName(dataTypeFactory.newBAG<EN>(orgName));
organization.setStatusCode(EntityStatus.ACTIVE);
// build a TEL type and addto the telecom attribute.
SET<CS> orgTelUseCode= dataTypeFactory.newSET_CS(dataTypeFactory.newCS("H"));
TEL orgTel = dataTypeFactory.newTEL("tel", "1-510-555-1234",
dataTypeFactory.nullGTS(NullFlavor.NI),orgTelUseCode);
organization.addTelecom(orgTel);
// build an ADXP type and add the address
ADXP adxp1 = dataTypeFactory.newADXP("100 Oracle Parkway", dataTypeFactory.newCS("SAL"));
ADXP adxp2 = dataTypeFactory.newADXP("Redwood Shores", dataTypeFactory.newCS("CTY"));
ADXP adxp3 = dataTypeFactory.newADXP("CA", dataTypeFactory.newCS("STA"));
ADXP adxp4 = dataTypeFactory.newADXP("94065", dataTypeFactory.newCS("ZIP"));
ADXP adxp5 = dataTypeFactory.newADXP("US", dataTypeFactory.newCS("CNT"));
ADXP[] addrPartArray = new ADXP[] {
adxp1,
adxp2,
adxp3,
adxp4,
adxp5
};
AD addr = dataTypeFactory.newAD(addrPartArray,
dataTypeFactory.newSET<CS>(dataTypeFactory.newCS("WP")),
dataTypeFactory.nullGTS(NullFlavor.NI));
organization.addAddr(addr);
// Create an ASSIGNED Role for the organization,
// with the organization as the player
// CD roleCode = dataTypeFactory.newCD("000172","HDR Supplemental");
SET_II assignedRoleId = dataTypeFactory.newSET_II("9.989898.5.49.1", "ASSIGNED0002", true);
Role role =
roleFactory.newAssignedEntity(dataTypeFactory.newCE("000174","2.16.840.1.113894.1004.100.100.2.5"),
organization, null, assignedRoleId);
// Create the registry act. Registry acts are used to denote a
// registration of a Role or Entity, in this case an ORG Entity.
// The registry act will later be associated with the control act
// using an act relationship
SET_II regActId = dataTypeFactory.newSET_II("9.989898.5.42.1", "REG0012", true);
Act regAct = actFactory.newRegistryAct(ActMood.EVN, dataTypeFactory.nullCD
(NullFlavor.NI), regActId);
// Create a "SBJ" Participation between the registry act
// and the identified role
regAct.addParticipation(ParticipationType.SBJ, role);
// Create the control act, providing an Id and a null trigger event
SET_II ctrlActId = dataTypeFactory.newSET_II("9.989898.5.28.1", "CACT0012", true);
ControlAct controlAct = actFactory.newControlActEvent(dataTypeFactory.nullCD
(NullFlavor.NI), ctrlActId);
// Create an outbound Act Relationship between the control act
// and registry act
controlAct.addOBActRelationship(ActRelationshipType.SUBJ, regAct);
// Submit the control act. The returned control act will be
// null unless a query act was specified in the act relationship
// on the control act
ControlAct returnedControlAct = rimService.submit(controlAct);In addition to illustrating the basic structure of a submission, Example 7-16 highlights the following:
- Construction of datatypes: AD, ADXP, CD, CS, ENXP, EN, II, ON, TEL.
- Construction of sets of datatypes: SET_CS, SET_II.
- Construction of NullFlavor objects as the appropriate datatype class.
- Elements of Organizations that are necessary to pass TCA validation. For example: Organization Name use code of H; Telecom Scheme of TEL.
Reference Modifiers
In the prior example, all objects are newly created. To update an object, fetch it using the query mechanism and use the createNewVersion method to create a new version.
HDR also provides a mechanism to create a reference to an object that already exists and to permit an object to be created or updated without first querying the object. This is achieved by making a reference to an object using the ReferenceModifier class. This approach may also improve an application's performance because it eliminates the need to fetch the affected objects to the client tier prior to updating.
The simplest reference that can be created is the MustExist reference. A MustExist reference mandates that an object with a specified Instance Identifier has already been created. It is useful when creating ActRelationships or Participations to objects that have already been persisted.
Two other reference types worth discussing in more detail are the CreateOrOverlay and the CreateOrUpdate types. These reference types either create the object with the supplied attributes if it does not already exist, or they cause the creation of a new version of the object with attributes set in a manner consistent with the reference modifier used. For more information about the difference between the CreateOrOverlay and CreateOrUpdate methods, and for information about other reference types see the ReferenceModifier class description.
Example 7-17 Create an Encounter Using a CREATE_OR_UPDATE Reference to a Patient Object
// Create the Patient II
SET_II patientId = dataTypeFactory.newSET_II("9.989898.5.2","PAT1001", true);
// Use a Create Or Update reference for the Patient
Patient patientRole = (Patient)roleFactory.makeReference(
ReferenceModifier.CREATE_OR_UPDATE, RoleClass.PAT,
dataTypeFactory.nullCE(NullFlavor.NP),
null, null, patientId, 0);
// Create the Patient Encounter Event (Class Code:ENC)
// The Encounter will later be associated with the control act
// using an act relationship
SET_II encActId = dataTypeFactory.newSET_II("9.989898.5.6.100","ENC1001", true);
// Use "ActCode" for the codingscheme; UID is 2.16.840.1.113883.5.4
Act encAct = actFactory.newPatientEncounter(ActMood.EVN,
dataTypeFactory.newCD("IMP","2.16.840.1.113883.5.4"), encActId);
// Create a "SBJ" Participation between the registry act
// and the identified role
encAct.addParticipation(ParticipationType.SBJ, patientRole);
// Create the control act, providing an Id and a null trigger event
SET_II ctrlActId = dataTypeFactory.newSET_II
("9.989898.5.28", "CACT001032", true);
ControlAct controlAct = actFactory.newControlActEvent(
dataTypeFactory.nullCD(NullFlavor.NP), ctrlActId);
// Create an outbound Act Relationship between the control act
// and registry act
controlAct.addOBActRelationship(ActRelationshipType.SUBJ, encAct);
// Submit the control act. The returned control act will be
// null unless a query act was specified in the act relationship
// on the control act
ControlAct returnedControlAct = rimService.submit(controlAct);Exception Handling
Invalid objects submitted in a graph cause HDR to bundle validation exceptions. These bundles consist of one exception per validation error; there may be multiple exceptions relating to an object. The exceptions contain methods to return the Ids of the related invalid object.
Example 7-18 Pass an Invalid Code to Generate an Exception
// Create the Patient Encounter Event (Class Code:ENC)
// The Encounter will later be associated with the control act
// using an act relationship
SET_II encActId = dataTypeFactory.newSET_II("9.989898.5.6.100", "ENC1001", true);
// UNKNOWN_CODE is expected to cause validation to fail
Act encAct = actFactory.newPatientEncounter(ActMood.EVN,
dataTypeFactory.newCD("UNKNOWN_CODE","2.16.840.1.113883.5.4"), encActId);
// Create the control act, providing an Id and a null trigger event
SET_II ctrlActId = dataTypeFactory.newSET_II("9.989898.5.28", "CACT001032", true);
ControlAct controlAct = actFactory.newControlActEvent(dataTypeFactory.nullCD
(NullFlavor.NP), ctrlActId);
// Create an outbound Act Relationship between the control act
// and registry act
controlAct.addOBActRelationship(ActRelationshipType.SUBJ, encAct);
try
{
// Submit the control act. The returned control act will be
// null unless a query act was specified in the act relationship
// on the control act
ControlAct returnedControlAct = rimService.submit(controlAct);
}
catch (HDRRimException e)
{
CommonException[] exceptions = e.getBundledExceptions();
for (int i=0; i<exceptions.length; i++)
{
if(exceptions[i] instanceof RimObjectException)
{
System.out.println(
((RimObjectException)exceptions[i]).getIds());
}
}
e.printStackTrace();
}This code generates the following output:
{9.989898.5-34789202; 9.989898.5.6.100-ENC1001}...where 9.989898.5-34789202 is the internal Instance Indicator created on all objects by HDR and 9.989898.5.6.100-ENC1001 is the II submitted with the Encounter object. Additionally, the full exception stack trace is< printed, and the exception details attributes that fail validation.
Example 7-19 Rim Validation Exception Output
oracle.hsgbu.hdr.exception.HDRRimException
CODE = CMN_001: Multiple exception occured while processing. Please see the individual exceptions for details.
MESSAGE = HDR_CMN_001: Multiple exception occured while processing. Please see the individual exceptions for details.
[1] oracle.hsgbu.hdr.base.persist.exception.CorePersistenceValidationException
CODE = HDR_CORE_UNKNOWN_CODE
MESSAGE = HDR_CPS_PVE006: Unknown Code for attributeName:CODE, code:UNKNOWN_CODE, codeOid:2.16.840.1.113883.5.4, codeSystemName:null, codeVersionName:2.01.4 and token:EncounterEventResource
...
Child Exceptions:
oracle.hsgbu.hdr.exception.HDRRimException
CODE = HDR_CORE_UNKNOWN_CODE
MESSAGE = HDR_CPS_PVE006: Unknown Code for attributeName:CODE, code:UNKNOWN_CODE, codeOid:2.16.840.1.113883.5.4, codeSystemName:null, codeVersionName:2.01.4 and token:EncounterEventResource
Original Stacktrace:
HDR_CPS_PVE006: Unknown Code for attributeName:CODE, code:UNKNOWN_CODE, codeOid:2.16.840.1.113883.5.4, codeSystemName:null, codeVersionName:2.01.4 and token:EncounterEventResource
...
...