HDR HL7 Data Types

This package contains an implementation of a subset of the HL7 Data Types specification, to meet HDR RIM interface requirements. The attributes (id, class, status,...) of the HL7 version 3 RIM objects are defined in terms of these Data Types, as are the parameters and return types of the RIM API. In accordance with the specification, these data type objects are immutable—their value cannot be changed once created.

You can do the following:

Use the DataTypeFactory (see Use the DataTypeFactory)
HL7 Null Flavors (see HL7 Null Flavors)
Unsupported Operations (see Unsupported Operations)
Coded Types (see Coded Types)
Collections (SET, BAG, LIST, IVL) (see Collections (SET, BAG, LIST, IVL))
HL7 Timing Specification (GTS, PIVL, EIVL, IVL<TS>, TS) (see HL7 Timing Specification (GTS, PIVL, EIVL, IVL<TS>, TS))

Use the DataTypeFactory

New Data Type objects should always be instantiated using the DataTypeFactory methods exclusively. Most of the factory methods throw CommonException or ETSException if there is a problem creating the new instance.

Creating Constants

As the factory methods throw checked exceptions, we do not recommend defining static final constants for Data Type values. If you find it useful to define constants, it is preferable to declare them as final member variables that can be initialized in the constructor (where exceptions can be handled more easily).

The CNE Domain Constants (defined in the package oracle.hsgbu.hdr.hl7.domain) define values for the CS type RIM coded attributes.

Abstract Types (ANY, BIN, QTY)

There are no factory methods for the ANY Data Type, because it is an abstract type. No value can be just an ANY without belonging to one of the concrete Data Types. For RIM attributes of type ANY (such as Observation.value, call the factory method for the appropriate concrete type (ST, ED, CD, GTS, etc.) and pass that type as the parameter to the RIM API.

Similarly, there is no factory method available for the Data Type BIN. It is a protected type that is only declared within the HL7 Data Type Specification. For properties of type BIN, you can substitute either ED or ST as the parameter to the factory method.

QTY is another example of an abstract type with no factory method. The specific subtype of Quantity (PQ, INT, REAL, and so on.) should be substituted instead.

HL7 Null Flavors

The Data Types Specification defines a hierarchy of different kinds of exceptional values, or null values. You can use the isNull method to determine whether a Data Type is one of these exceptional values; the nullFlavor method returns a CS code that specifies what kind of exceptional value it is.

In general, a Java null should never be passed to any of the parameters of the Data Types methods. You should use the DataTypeFactory to create an object with the appropriate HL7 null flavor instead. NI is the default null flavor, and should be used if you are uncertain about whether any of the more specific flavors of null are applicable.

The null flavor factory methods are guaranteed to return a valid Data Type with a null flavor, and never throw an exception. The CS codes for the null flavor values themselves are provided as convenience constants in the HL7.domain package.

Unsupported Operations

The present implementation of the HL7 Data Types Specification is only partially complete. Several methods throw a runtime UnsupportedOperationException, such as the arithmetic and comparison operations on Quantities, and many of the properties of the Timing Specification (GTS, PIVL, ...).

Coded Types

The HL7 Coded Types (CD, CE, CV and so on.) are stored in both HDR and ETS. Accordingly, several types of factory methods are provided for each coded type:

Methods that accept any of the HL7 properties (Examples: newCE(ST code, UID codeSystem, ST codeSystemName, ST codeSystemVersion, ED originalText)) (Example 7-41).
Methods that simply accept an ETS ID (Examples: newCE(String etsID)). The DataTypeFactory uses the ServiceLocator to retrieve the corresponding properties from ETS (Example 7-42); note that use of this method should be avoided because of the additional communication overhead with the server.
Convenience methods that accept only the mandatory attributes, and default all of the others to null flavors (Examples: newCE(String code, String codeSystem). Note that the second parameter of this method is the code system OID, and not the code system name (Example 7-43).

The complete mapping of code system names to OIDs can be retrieved in the following ways:

By viewing corresponding coding schemes in ETS UI (preferred).
For code systems registered with HL7, an online OID repository is provided as a free service.

These code samples help you do the following:

Create Coded Data Type through Full Set of Properties (see Example 7-30)
Create Coded Data Type through ETS ID (Not Recommended) (see Example 7-31)
Create Coded Data Type through Code and Code System OID (see Example 7-32)
Create Coded Data Type through Code and Code System Name (see Example 7-33)

Example 7-30 Create Coded Data Type through Full Set of Properties (Recommended)

DataTypeFactory dtf = DataTypeFactory.getInstance();
 CD code = df.newCD(df.newST("233604007"), df.newUID("2.16.840.1.113883.6.96"),
    df.newST("SNOMED-CT"), df.newST("v1"), df.newST("Pneumonia"));

Example 7-31 Create Coded Data Type through ETS ID (Not Recommended)

DataTypeFactory dtf = DataTypeFactory.getInstance(); CD code = df.newCD("CON-2217");

Example 7-32 Create Coded Data Type through Code and Code System OID

DataTypeFactory dtf = DataTypeFactory.getInstance(); CD code = df.newCD("233604007", "2.16.840.1.113883.6.96");

Example 7-33 Create Coded Data Type through Code and Code System Name

DataTypeFactory dtf = DataTypeFactory.getInstance();
 CD code = df.newCD(df.newST("233604007"), df.nullUID(NullFlavor.NI),
    df.newST("SNOMED-CT"), df.newST("v1"), df.newST("Pneumonia"));

Collections (SET, BAG, LIST, IVL)

The factory methods for aggregate Data Types accept an array of elements (such as newSET_II(II[] identifiers)). The promotion operation is also provided, from a single Data Type into a trivial collection containing only that one element: newSET_II(II element).

HL7 Timing Specification (GTS, PIVL, EIVL, IVL<TS>, TS)

The factory methods for the time-related Data Types accept a literal string formatted according to the syntax defined in the HL7 specification. This literal is parsed to extract the properties (boundaries of an Interval, elements of a GTS) of the Data Type. If there is a syntax error in the string, a CommonException is thrown by the factory method.