Package 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
    Description
    MessageNavigator(Group root)
    Creates a new instance of MessageNavigator

  • Method Summary

    Modifier and Type
    Method
    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 Details

    • 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 Details

    • 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