ca.uhn.hl7v2.util.Terser

public class Terser extends Object

Wraps a message to provide access to fields using a terse location specification syntax. For example:

terser.set("MSH-9-3", "ADT_A01");
can be used instead of
message.getMSH().getMessageType().getMessageStructure().setValue("ADT_A01");

The syntax of a location spec is as follows:

location_spec: segment_path_spec "-" field ["(" rep ")"] ["-" component ["-" subcomponent]]

... where rep, field, component, and subcomponent are integers (representing, respectively, the field repetition (starting at 0), and the field number, component number, and subcomponent numbers (starting at 1). Omitting the rep is equivalent to specifying 0; omitting the component or subcomponent is equivalent to specifying 1.

The syntax for the segment_path_spec is as follows:

segment_path_spec: ["/"] (group_spec ["(" rep ")"] "/")* segment_spec ["(" rep ")"]

... where rep has the same meaning as for fields.

A leading "/" indicates that navigation to the location begins at the root of the message; omitting this indicates that navigation begins at the current location of the underlying SegmentFinder (see getFinder() -- this allows manual navigation if desired). The syntax for group_spec is:

group_spec: ["."] group_name_pattern

Here, a . indicates that the group should be searched for (using a SegmentFinder) starting at the current location in the message. The wildcards "*" and "?" represent any number of arbitrary characters, and a single arbitrary character, respectively. For example, "M*" and "?S?" match MSH. The first group with a name that matches the given group_name_pattern will be matched.

The segment_spec is analogous to the group_spec.

As another example, the following subcomponent in an SIU_S12 message:

msg.getSIU_S12_RGSAISNTEAIGNTEAILNTEAIPNTE(1).getSIU_S12_AIGNTE().getAIG().getResourceGroup(1).getIdentifier();

... is referenced by all of the following location_spec:

/SIU_S12_RGSAISNTEAIGNTEAILNTEAIPNTE(1)/SIU_S12_AIGNTE/AIG-5(1)-1 /*AIG*(1)/SIU_S12_AIGNTE/AIG-5(1)-1 /*AIG*(1)/.AIG-5(1)


 
 The search function only iterates through rep 0 of each group. Thus if rep 0 of the first group
 in this example was desired instead of rep 1, the following syntax would also work (since there
 is only one AIG segment position in SUI_S12):
 
 
 /.AIG-5(1)



Author:
Bryan Tripp, Ryan W. Gross (General Electric Corporation - Healthcare IT).







Constructor Summary
Constructors

Constructor
Description
Terser(Message message)

Creates a new instance of Terser







Method Summary




Modifier and Type
Method
Description
static String
get(Segment segment,
 int field,
 int rep,
 int component,
 int subcomponent)

Returns the string value of the Primitive at the given location.

String
get(String spec)


 Gets the string value of the field specified.

SegmentFinder
getFinder()

Returns the segment finder used by this Terser.

static int[]
getIndices(String spec)

Given a Terser path, returns an array containing field num, field rep, component, and
 subcomponent.

static Primitive
getPrimitive(Type type,
 int component,
 int subcomponent)

Returns the Primitive object at the given location in the given field.

Segment
getSegment(String segSpec)

Returns the segment specified in the given segment_path_spec.

static int
numComponents(Type t)

Returns the number of components in the given type, i.e.

static int
numSubComponents(Type type,
 int component)

Returns the number of sub-components in the specified component, i.e.

static void
set(Segment segment,
 int field,
 int rep,
 int component,
 int subcomponent,
 String value)

Sets the string value of the Primitive at the given location.

static void
set(Segment segment,
 Location location,
 String value)
 
void
set(String spec,
 String value)

Sets the string value of the field specified.





Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait









Constructor Details



Terser
public Terser(Message message)
Creates a new instance of Terser

Parameters:
message - message for which the Terser is created









Method Details



get
public static String get(Segment segment,
 int field,
 int rep,
 int component,
 int subcomponent)
                  throws HL7Exception
Returns the string value of the Primitive at the given location.

Parameters:
segment - the segment from which to get the primitive
field - the field number (indexed from 1)
rep - the field repetition (indexed from 0)
component - the component number (indexed from 1, use 1 for primitive field)
subcomponent - the subcomponent number (indexed from 1, use 1 for primitive component)
Returns:
string value of the Primitive at the given location
Throws:
HL7Exception - if the primitive could not be obtained





set
public static void set(Segment segment,
 int field,
 int rep,
 int component,
 int subcomponent,
 String value)
                throws HL7Exception
Sets the string value of the Primitive at the given location.

Parameters:
segment - the segment from which to get the primitive
field - the field number (indexed from 1)
rep - the field repetition (indexed from 0)
component - the component number (indexed from 1, use 1 for primitive field)
subcomponent - the subcomponent number (indexed from 1, use 1 for primitive component)
value - value to be set
Throws:
HL7Exception - if the value could not be set





set
public static void set(Segment segment,
 Location location,
 String value)
                throws HL7Exception

Throws:
HL7Exception





getPrimitive
public static Primitive getPrimitive(Type type,
 int component,
 int subcomponent)
Returns the Primitive object at the given location in the given field. It is intended that
 the given type be at the field level, although extra components will be added blindly if, for
 example, you provide a primitive subcomponent instead and specify component or subcomponent >
 1

Parameters:
type - the type from which to get the primitive
component - the component number (indexed from 1, use 1 for primitive field)
subcomponent - the subcomponent number (indexed from 1, use 1 for primitive component)
Returns:
the Primitive object at the given location





get
public String get(String spec)
           throws HL7Exception

 Gets the string value of the field specified. See the class docs for syntax of the location
 spec.
 
 
 If a repetition is omitted for a repeating segment or field, the first rep is used. If the
 component or subcomponent is not specified for a composite field, the first component is used
 (this allows one to write code that will work with later versions of the HL7 standard).

Parameters:
spec - field specification
Returns:
string value of the specified field
Throws:
HL7Exception - if the primitive could not be obtained





getSegment
public Segment getSegment(String segSpec)
                   throws HL7Exception
Returns the segment specified in the given segment_path_spec.

Parameters:
segSpec - segment specification
Returns:
the segment specified
Throws:
HL7Exception - if the segment could not be obtained





getIndices
public static int[] getIndices(String spec)
                        throws HL7Exception
Given a Terser path, returns an array containing field num, field rep, component, and
 subcomponent.

Parameters:
spec - field specification
Returns:
an array containing field num, field rep, component, and subcomponent
Throws:
HL7Exception - if the field does not exist





set
public void set(String spec,
 String value)
         throws HL7Exception
Sets the string value of the field specified. See class docs for location spec syntax.

Parameters:
spec - primitive path specification
value - value to be set
Throws:
HL7Exception - if the primitive does not exist





numSubComponents
public static int numSubComponents(Type type,
 int component)
Returns the number of sub-components in the specified component, i.e. the number of standard
 sub-components (e.g. 6 for CE) plus any extra components that that have been added at
 runtime.

Parameters:
type - composite type
component - numbered from 1
Returns:
number of sub-components in the specified component





numComponents
public static int numComponents(Type t)
Returns the number of components in the given type, i.e. the number of standard components
 (e.g. 6 for CE) plus any extra components that have been added at runtime.

Parameters:
t - composite type
Returns:
the number of components in the given type





getFinder
public SegmentFinder getFinder()
Returns the segment finder used by this Terser. Navigating the finder will influence the
 behaviour of the Terser accordingly. Ie when the full path of the segment is not specified
 the segment will be sought beginning at the current location of the finder.

Returns:
the segment finder used by this Terser

Class Terser

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

Terser

Method Details

get

set

set

getPrimitive

get

getSegment

getIndices

set

numSubComponents

numComponents

getFinder