ca.uhn.hl7v2.util
Class MessageNavigator

java.lang.Object
  extended by ca.uhn.hl7v2.util.MessageNavigator
Direct Known Subclasses:
SegmentFinder

public class MessageNavigator
extends java.lang.Object

Used to navigate the nested group structure of a message. This is an alternate way of accessing parts of a message, ie rather than getting a segment through a chain of getXXX() calls on the message, you can create a MessageNavigator for the message, "navigate" to the desired segment, and then call getCurrentStructure() to get the segment you have navigated to. A message navigator always has a "current location" pointing to some structure location (segment or group location) within the message. Note that a location exists whether or not there are any instances of the structure at that location.

This class is used by Terser, which presents an even more convenient way of navigating a message.

This class also has an iterate() method, which iterates over segments (and optionally groups).

Author:
Bryan Tripp

Constructor Summary
MessageNavigator(Group root)
          Creates a new instance of MessageNavigator
 
Method Summary
 void drillDown(int rep)
          Drills down into the group at the CURRENT location.
 void drillDown(int childNumber, int rep)
          Drills down into the group at the given index within the current group -- ie sets the location pointer to the first structure within the child
 boolean drillUp()
          Switches the group context to the parent of the current group, and sets the child pointer to the next sibling.
 Structure[] getCurrentChildReps()
          Returns the array of structures at the current location.
 Group getCurrentGroup()
          Returns the group within which the pointer is currently located.
 Structure getCurrentStructure(int rep)
          Returns the given rep of the structure at the current location.
 Group getRoot()
           
 boolean hasNextChild()
          Returns true if there is a sibling following the current location.
 void iterate(boolean segmentsOnly, boolean loop)
          Iterates through the message tree to the next segment/group location (regardless of whether an instance of the segment exists).
 void nextChild()
          Moves to the next sibling of the current location.
 void reset()
          Resets the location to the beginning of the tree (the root)
 void toChild(int child)
          Moves to the sibling of the current location at the specified index.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MessageNavigator

public MessageNavigator(Group root)
Creates a new instance of MessageNavigator

Parameters:
root - the root of navigation -- may be a message or a group within a message. Navigation will only occur within the subtree of which the given group is the root.
Method Detail

getRoot

public Group getRoot()

drillDown

public void drillDown(int childNumber,
                      int rep)
               throws HL7Exception
Drills down into the group at the given index within the current group -- ie sets the location pointer to the first structure within the child

Parameters:
childNumber - the index of the group child into which to drill
rep - the group repetition into which to drill
Throws:
HL7Exception

drillDown

public void drillDown(int rep)
               throws HL7Exception
Drills down into the group at the CURRENT location.

Throws:
HL7Exception

drillUp

public boolean drillUp()
Switches the group context to the parent of the current group, and sets the child pointer to the next sibling.

Returns:
false if already at root

hasNextChild

public boolean hasNextChild()
Returns true if there is a sibling following the current location.


nextChild

public void nextChild()
               throws HL7Exception
Moves to the next sibling of the current location.

Throws:
HL7Exception

toChild

public void toChild(int child)
             throws HL7Exception
Moves to the sibling of the current location at the specified index.

Throws:
HL7Exception

reset

public void reset()
Resets the location to the beginning of the tree (the root)


getCurrentStructure

public Structure getCurrentStructure(int rep)
                              throws HL7Exception
Returns the given rep of the structure at the current location. If at root, always returns the root (the rep is ignored).

Throws:
HL7Exception

getCurrentGroup

public Group getCurrentGroup()
Returns the group within which the pointer is currently located. If at the root, the root is returned.


getCurrentChildReps

public Structure[] getCurrentChildReps()
                                throws HL7Exception
Returns the array of structures at the current location. Throws an exception if pointer is at root.

Throws:
HL7Exception

iterate

public void iterate(boolean segmentsOnly,
                    boolean loop)
             throws HL7Exception
Iterates through the message tree to the next segment/group location (regardless of whether an instance of the segment exists). If the end of the tree is reached, starts over at the root. Only enters the first repetition of a repeating group -- explicit navigation (using the drill...() methods) is necessary to get to subsequent reps.

Parameters:
segmentsOnly - if true, only stops at segments (not groups)
loop - if true, loops back to beginning when end of msg reached; if false, throws HL7Exception if end of msg reached
Throws:
HL7Exception


Copyright © 2001-2011 University Health Network. All Rights Reserved.