ca.uhn.hl7v2.util
Class MessageIterator

java.lang.Object
  extended by ca.uhn.hl7v2.util.MessageIterator
All Implemented Interfaces:
java.util.Iterator

public class MessageIterator
extends java.lang.Object
implements java.util.Iterator

Iterates over all defined nodes (ie segments, groups) in a message, regardless of whether they have been instantiated previously. This is a tricky process, because the number of nodes is infinite, due to infinitely repeating segments and groups. See next() for details on how this is handled. This implementation assumes that the first segment in each group is present (as per HL7 rules). Specifically, when looking for a segment location, an empty group that has a spot for the segment will be overlooked if there is anything else before that spot. This may result in surprising (but sensible) behaviour if a message is missing the first segment in a group.

Author:
Bryan Tripp

Nested Class Summary
static class MessageIterator.Index
          An index of a child structure within a group, consisting of the name and rep of of the child.
static class MessageIterator.Position
          A structure position within a message.
 
Constructor Summary
MessageIterator(Structure start, java.lang.String direction, boolean handleUnexpectedSegments)
          Creates a new instance of MessageIterator
 
Method Summary
static boolean contains(Structure s, java.lang.String name, boolean firstDescendentsOnly, boolean upToFirstRequired)
          Determines whether the given structure matches the given name, or contains a child that does.
 java.lang.String getDirection()
           
static MessageIterator.Index getIndex(Group parent, Structure child)
          Returns the index of the given structure as a child of the given parent.
 boolean hasNext()
          Returns true if another object exists in the iteration sequence.
static boolean isLast(MessageIterator.Position p)
          Tests whether the name of the given Index matches the name of the last child of the given group.
static boolean matchExistsAfterPosition(MessageIterator.Position pos, java.lang.String name, boolean firstDescendentsOnly, boolean upToFirstRequired)
          A match exists for the given name somewhere after the given position (in the normal serialization order).
 java.lang.Object next()
          Returns the next node in the message.
 void remove()
          Not supported
 void setDirection(java.lang.String direction)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MessageIterator

public MessageIterator(Structure start,
                       java.lang.String direction,
                       boolean handleUnexpectedSegments)
Creates a new instance of MessageIterator

Method Detail

hasNext

public boolean hasNext()
Returns true if another object exists in the iteration sequence.

Specified by:
hasNext in interface java.util.Iterator

matchExistsAfterPosition

public static boolean matchExistsAfterPosition(MessageIterator.Position pos,
                                               java.lang.String name,
                                               boolean firstDescendentsOnly,
                                               boolean upToFirstRequired)
                                        throws HL7Exception
A match exists for the given name somewhere after the given position (in the normal serialization order).

Parameters:
pos - the message position after which to look (note that this specifies the message instance)
name - the name of the structure to look for
firstDescendentsOnly - only searches the first children of a group
upToFirstRequired - only searches the children of a group up to the first required child (normally the first one). This is used when we are parsing a message in order and looking for a place to parse a particular segment -- if the message is correct then it can't go after a required position of a different name.
Throws:
HL7Exception

contains

public static boolean contains(Structure s,
                               java.lang.String name,
                               boolean firstDescendentsOnly,
                               boolean upToFirstRequired)
Determines whether the given structure matches the given name, or contains a child that does.

Parameters:
s - the structure to check
name - the name to look for
firstDescendentsOnly - only checks first descendents (i.e. first child, first child of first child, etc.) In theory the first child of a group should always be present, and we don't use this method with subsequent children because finding the next position within a group is straightforward.
upToFirstRequired - only checks first descendents and of their siblings up to the first required one. This may be needed because in practice some first children of groups are not required.

isLast

public static boolean isLast(MessageIterator.Position p)
Tests whether the name of the given Index matches the name of the last child of the given group.


next

public java.lang.Object next()

Returns the next node in the message. Sometimes the next node is ambiguous. For example at the end of a repeating group, the next node may be the first segment in the next repetition of the group, or the next sibling, or an undeclared segment locally added to the group's end. Cases like this are disambiguated using getDirection(), which returns the name of the structure that we are "iterating towards". Usually we are "iterating towards" a segment of a certain name because we have a segment string that we would like to parse into that node. Here are the rules:

  1. If at a group, next means first child.
  2. If at a non-repeating segment, next means next "position"
  3. If at a repeating segment: if segment name matches direction then next means next rep, otherwise next means next "position".
  4. If at a segment within a group (not at the end of the group), next "position" means next sibling
  5. If at the end of a group: If name of group or any of its "first decendents" matches direction, then next position means next rep of group. Otherwise if direction matches name of next sibling of the group, or any of its first descendents, next position means next sibling of the group. Otherwise, next means a new segment added to the group (with a name that matches "direction").
  6. "First descendents" means first child, or first child of the first child, or first child of the first child of the first child, etc.

Specified by:
next in interface java.util.Iterator

remove

public void remove()
Not supported

Specified by:
remove in interface java.util.Iterator

getDirection

public java.lang.String getDirection()

setDirection

public void setDirection(java.lang.String direction)

getIndex

public static MessageIterator.Index getIndex(Group parent,
                                             Structure child)
Returns the index of the given structure as a child of the given parent. Returns null if the child isn't found.



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