[HAPI-devel] alternative HAPI syntax

[Tripp, B. <Bry...@uh...>]

I should mention an addition to HAPI over the holidays.  This is partly in
response to Alex's question about writing version-independent code, and
partly because drilling down through a message can result in a really long
chain of getters. 

There is a new class, ca.uhn.hl7v2.util.Terser (meaning it lets you write
code that is more "terse" -- if you can think of a better name, speak up).
A Terser acts as a wrapper for a Message object, and provides a new syntax
for setting and getting message fields.  This new syntax is 1) shorter, and
2) version-independent (if you're careful).  

For convenience, here is the class JavaDoc: 

---- 

public class Terser
extends java.lang.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; ommitting
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

Here, a . indicates that the group should be searched for (using a
SegmentFinder) starting at the current location in the message. A "*"
indicates that the given group name is a substring -- the first group with a
name that contains the given group_name as a substring 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().g
etResourceGroup(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)


----

This syntax is mainly intended as a shortcut for experienced HAPI users.
The disadvantage is that your navigation through the message is checked at
runtime rather than compile time.  It's in the CVS repository if you want to
try it.  Feedback is welcome. 

Bryan 



This e-mail may contain confidential and/or privileged information
for the sole use of the intended recipient. Any review or distribution
by anyone other than the person for whom it was originally intended is
strictly
prohibited. If you have received this e-mail in error, please contact the
sender and
delete all copies. Opinions, conclusions or other information contained in
this e-mail may not be that of the organization.