ca.uhn.hl7v2.util

Class MessageIterator

java.lang.Object

ca.uhn.hl7v2.util.MessageIterator

All Implemented Interfaces:

Iterator<Structure>

public class MessageIterator
extends Object
implements Iterator<Structure>

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

Nested Classes

Modifier and Type	Class and Description
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

Constructors

Constructor and Description
MessageIterator(Structure start, String direction, boolean handleUnexpectedSegments) Creates a new instance of MessageIterator

Method Summary

Modifier and Type	Method and Description
static boolean	contains(Structure s, String name, boolean firstDescendentsOnly, boolean upToFirstRequired) Determines whether the given structure matches the given name, or contains a child that does.
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, String name, boolean firstDescendentsOnly, boolean upToFirstRequired) A match exists for the given name somewhere after the given position (in the normal serialization order).
Structure	next() Returns the next node in the message.
void	remove() Not supported
void	setDirection(String direction)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Iterator

forEachRemaining

Constructor Detail

MessageIterator

public MessageIterator(Structure start,
                       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 Iterator<Structure>

matchExistsAfterPosition

public static boolean matchExistsAfterPosition(MessageIterator.Position pos,
                                               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,
                               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 Structure 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 Iterator<Structure>

remove

public void remove()

Not supported

Specified by:

remove in interface Iterator<Structure>

getDirection

public String getDirection()

setDirection

public void setDirection(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.