ca.uhn.hl7v2.util

Class MessageNavigator

java.lang.Object

ca.uhn.hl7v2.util.MessageNavigator

Direct Known Subclasses:

SegmentFinder

public class MessageNavigator
extends 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

Constructors

Constructor and Description
MessageNavigator(Group root) Creates a new instance of MessageNavigator

Method Summary

Modifier and Type	Method and Description
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.
String	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)
String	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 String toChild(int child)
               throws HL7Exception

Moves to the sibling of the current location at the specified index.

Returns:

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 String 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

Returns:

Returns the name of the next item within its parent, or "" for the root (message)

Throws:

HL7Exception