ca.uhn.hl7v2.model

Class AbstractGroup

java.lang.Object

ca.uhn.hl7v2.model.AbstractStructure

ca.uhn.hl7v2.model.AbstractGroup

All Implemented Interfaces:

Group, Structure, Visitable, Serializable

Direct Known Subclasses:

AbstractMessage, GenericGroup

public abstract class AbstractGroup
extends AbstractStructure
implements Group

A partial implementation of Group. Subclasses correspond to specific groups of segments (and/or other sub-groups) that are implicitly defined by message structures in the HL7 specification. A subclass should define it's group structure by putting repeated calls to the add(...) method in it's constructor. Each call to add(...) adds a specific component to the Group.

Author:

Bryan Tripp (bryan_tripp@sourceforge.net)

See Also:

Serialized Form

Field Summary

Fields inherited from class ca.uhn.hl7v2.model.AbstractStructure

log

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractGroup(Group parent, ModelClassFactory factory) This constructor should be used by implementing classes that do not also implement Message.

Method Summary

Modifier and Type	Method and Description
boolean	accept(MessageVisitor visitor, Location location) Iterates over the contained structures and calls the visitor for each of them.
protected String	add(Class<? extends Structure> c, boolean required, boolean repeating) Adds a new Structure (group or segment) to this Group.
protected String	add(Class<? extends Structure> c, boolean required, boolean repeating, boolean choiceElement) Adds a new Structure (group or segment) to this Group.
protected String	add(Class<? extends Structure> c, boolean required, boolean repeating, int index) Adds a new Structure (group or segment) to this Group.
String	addNonstandardSegment(String name) Expands the group definition to include a segment that is not defined by HL7 to be part of this group (eg an unregistered Z segment).
String	addNonstandardSegment(String theName, int theIndex) Expands the group definition to include a segment that is not defined by HL7 to be part of this group (eg an unregistered Z segment).
void	clear() Clears all data from this structure.
int	currentReps(String name) Returns the number of existing repetitions of the named structure.
Structure	get(String name) Returns the named structure.
Structure	get(String name, int rep) Returns a particular repetition of the named Structure.
Structure[]	getAll(String name) Returns an array of Structure objects by name.
protected <T extends Structure> List<T>	getAllAsList(String name, Class<T> theType) Returns a list containing all existing repetitions of the structure identified by name
Class<? extends Structure>	getClass(String name) Returns the Class of the Structure at the given name index.
int	getFieldNumForName(String name) Given a child structure name, returns the child index (which is 1-indexed, meaning that the first child is at index 1
ModelClassFactory	getModelClassFactory() Returns the ModelClassFactory associated with this structure
String	getName() Returns the class name (excluding package).
String[]	getNames() Returns an ordered array of the names of the Structures in this Group.
Set<String>	getNonStandardNames() Returns a Set containing the names of all non-standard structures which have been added to this structure
protected int	getReps(String name)
protected <T extends Structure> T	getTyped(String name, Class<T> type)
protected <T extends Structure> T	getTyped(String name, int rep, Class<T> type)
protected String	insert(Class<? extends Structure> c, boolean required, boolean repeating, boolean choiceElement, int index, String name)
protected String	insert(Class<? extends Structure> c, boolean required, boolean repeating, int index, String name) Inserts the given structure into this group, at the indicated index number.
Structure	insertRepetition(String name, int index) Inserts a repetition of a given Structure into repetitions of that structure by name.
protected void	insertRepetition(String name, Structure structure, int index) Inserts a repetition of a given Structure into repetitions of that structure by name.
boolean	isChoiceElement(String theName) Returns true if the named structure is a "choice element".
boolean	isEmpty() Returns true if this Visitable has actual content
boolean	isGroup(String name) Returns true if the named structure is a group
boolean	isRepeating(String name) Returns true if the named structure is required.
boolean	isRequired(String name) Returns true if the named structure is required.
Location	provideLocation(Location location, int index, int repetition) Reusing the location of this object's parent, this method returns its own location within the message.
Structure	removeRepetition(String name, int index) Removes a repetition of a given Structure objects by name.
protected Structure	tryToInstantiateStructure(Class<? extends Structure> c, String name) Attempts to create an instance of the given class and return it as a Structure.
protected void	visitNestedStructures(MessageVisitor visitor, Location location)

Methods inherited from class ca.uhn.hl7v2.model.AbstractStructure

getMessage, getParent

Methods inherited from class java.lang.Object

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

Methods inherited from interface ca.uhn.hl7v2.model.Structure

getMessage, getParent

Constructor Detail

AbstractGroup

protected AbstractGroup(Group parent,
                        ModelClassFactory factory)

This constructor should be used by implementing classes that do not also implement Message.

Parameters:

parent - the group to which this Group belongs.

factory - the factory for classes of segments, groups, and datatypes under this group

Method Detail

get

public Structure get(String name)
              throws HL7Exception

Returns the named structure. If this Structure is repeating then the first repetition is returned. Creates the Structure if necessary.

Specified by:

get in interface Group

Parameters:

name - of the structure

Returns:

first (or only) structure object

Throws:

HL7Exception - if the named Structure is not part of this Group.

getTyped

protected <T extends Structure> T getTyped(String name,
                                           Class<T> type)

get

public Structure get(String name,
                     int rep)
              throws HL7Exception

Returns a particular repetition of the named Structure. If the given repetition number is one greater than the existing number of repetitions then a new Structure is created.

Specified by:

get in interface Group

Parameters:

name - name of the structure

rep - repetition (zero-based)

Returns:

particular repetition of the named structure

Throws:

HL7Exception - if the named Structure is not part of this group, if the structure is not repeatable and the given rep is > 0, or if the given repetition number is more than one greater than the existing number of repetitions.

isEmpty

public boolean isEmpty()
                throws HL7Exception

Returns true if this Visitable has actual content

Specified by:

isEmpty in interface Visitable

Returns:

true if Visitable is empty

Throws:

HL7Exception - if an error occurred while determining emptiness

getTyped

protected <T extends Structure> T getTyped(String name,
                                           int rep,
                                           Class<T> type)

getReps

protected int getReps(String name)

addNonstandardSegment

public String addNonstandardSegment(String name)
                             throws HL7Exception

Expands the group definition to include a segment that is not defined by HL7 to be part of this group (eg an unregistered Z segment). The new segment is slotted at the end of the group. Thenceforward if such a segment is encountered it will be parsed into this location. If the segment name is unrecognized a GenericSegment is used. The segment is defined as repeating and not required.

Specified by:

addNonstandardSegment in interface Group

Parameters:

name - name of the segment

Returns:

the final name of the segment (may be renamed if a segment of this name already exists.

Throws:

HL7Exception - if the segment could not be added

addNonstandardSegment

public String addNonstandardSegment(String theName,
                                    int theIndex)
                             throws HL7Exception

Description copied from interface: Group

Expands the group definition to include a segment that is not defined by HL7 to be part of this group (eg an unregistered Z segment).

Specified by:

addNonstandardSegment in interface Group

Parameters:

theName - name of the segment

theIndex - index (zero-based) at which to insert this segment

Returns:

the name used to index the structure (may be appended with a number if name already used)

Throws:

HL7Exception - if the segment could not be added

getNonStandardNames

public Set<String> getNonStandardNames()

Returns a Set containing the names of all non-standard structures which have been added to this structure

Returns:

set of non-standard structures

getNames

public String[] getNames()

Returns an ordered array of the names of the Structures in this Group. These names can be used to iterate through the group using repeated calls to get(name).

Specified by:

getNames in interface Group

Returns:

an ordered array of the names of the Structures in this Group

add

protected String add(Class<? extends Structure> c,
                     boolean required,
                     boolean repeating)
              throws HL7Exception

Adds a new Structure (group or segment) to this Group. A place for the Structure is added to the group but there are initially zero repetitions. This method should be used by the constructors of implementing classes to specify which Structures the Group contains - Structures should be added in the order in which they appear. Note that the class is supplied instead of an instance because we want there initially to be zero instances of each structure but we want the AbstractGroup code to be able to create instances as necessary to support get(...) calls.

Returns:

the actual name used to store this structure (may be appended with an integer if there are duplicates in the same Group).

Throws:

HL7Exception

add

protected String add(Class<? extends Structure> c,
                     boolean required,
                     boolean repeating,
                     boolean choiceElement)
              throws HL7Exception

Adds a new Structure (group or segment) to this Group. A place for the Structure is added to the group but there are initially zero repetitions. This method should be used by the constructors of implementing classes to specify which Structures the Group contains - Structures should be added in the order in which they appear. Note that the class is supplied instead of an instance because we want there initially to be zero instances of each structure but we want the AbstractGroup code to be able to create instances as necessary to support get(...) calls.

Returns:

the actual name used to store this structure (may be appended with an integer if there are duplicates in the same Group).

Throws:

HL7Exception

add

protected String add(Class<? extends Structure> c,
                     boolean required,
                     boolean repeating,
                     int index)
              throws HL7Exception

Adds a new Structure (group or segment) to this Group. A place for the Structure is added to the group but there are initially zero repetitions. This method should be used by the constructors of implementing classes to specify which Structures the Group contains - Structures should be added in the order in which they appear. Note that the class is supplied instead of an instance because we want there initially to be zero instances of each structure but we want the AbstractGroup code to be able to create instances as necessary to support get(...) calls.

Returns:

the actual name used to store this structure (may be appended with an integer if there are duplicates in the same Group).

Throws:

HL7Exception

tryToInstantiateStructure

protected Structure tryToInstantiateStructure(Class<? extends Structure> c,
                                              String name)
                                       throws HL7Exception

Attempts to create an instance of the given class and return it as a Structure.

Parameters:

c - the Structure implementing class

name - an optional name of the structure (used by Generic structures; may be null)

Throws:

HL7Exception

isChoiceElement

public boolean isChoiceElement(String theName)
                        throws HL7Exception

Returns true if the named structure is a "choice element". Some HL7 structures (e.g. ORM_O01 in v2.5) have groups that have several possible first segments. In these structures, one of these "choice elements" must be present, but not more than one.

Specified by:

isChoiceElement in interface Group

Parameters:

theName - name of the structure nested in this group

Returns:

true if structure is a choice element

Throws:

HL7Exception - if the named Structure is not part of this group

isGroup

public boolean isGroup(String name)
                throws HL7Exception

Returns true if the named structure is a group

Specified by:

isGroup in interface Group

Parameters:

name - name of the structure nested in this group

Returns:

true if structure is a choice element

Throws:

HL7Exception - if the named Structure is not part of this group

isRequired

public boolean isRequired(String name)
                   throws HL7Exception

Returns true if the named structure is required.

Specified by:

isRequired in interface Group

Parameters:

name - name of the structure nested in this group

Returns:

true if structure is required

Throws:

HL7Exception - if the named Structure is not part of this group

isRepeating

public boolean isRepeating(String name)
                    throws HL7Exception

Returns true if the named structure is required.

Specified by:

isRepeating in interface Group

Parameters:

name - name of the structure nested in this group

Returns:

true if structure is repeating

Throws:

HL7Exception - if the named Structure is not part of this group

currentReps

public int currentReps(String name)
                throws HL7Exception

Returns the number of existing repetitions of the named structure.

Parameters:

name - structure name

Returns:

number of existing repetitions of the named structure

Throws:

HL7Exception - if the structure is unknown

getAll

public Structure[] getAll(String name)
                   throws HL7Exception

Returns an array of Structure objects by name. For example, if the Group contains an MSH segment and "MSH" is supplied then this call would return a 1-element array containing the MSH segment. Multiple elements are returned when the segment or group repeats. The array may be empty if no repetitions have been accessed yet using the get(...) methods.

Specified by:

getAll in interface Group

Parameters:

name - of the structure

Returns:

array of Structure objects

Throws:

HL7Exception - if the named Structure is not part of this Group.

getAllAsList

protected <T extends Structure> List<T> getAllAsList(String name,
                                                     Class<T> theType)
                                              throws HL7Exception

Returns a list containing all existing repetitions of the structure identified by name

Throws:

HL7Exception - if the named Structure is not part of this Group.

removeRepetition

public Structure removeRepetition(String name,
                                  int index)
                           throws HL7Exception

Removes a repetition of a given Structure objects by name. For example, if the Group contains 10 repititions an OBX segment and "OBX" is supplied with an index of 2, then this call would remove the 3rd repetition. Note that in this case, the Set ID field in the OBX segments would also need to be renumbered manually.

Parameters:

name - structure name

index - repetition to remove the structure from

Returns:

The removed structure

Throws:

HL7Exception - if the named Structure is not part of this Group.

insertRepetition

protected void insertRepetition(String name,
                                Structure structure,
                                int index)
                         throws HL7Exception

Inserts a repetition of a given Structure into repetitions of that structure by name. For example, if the Group contains 10 repetitions an OBX segment and an OBX is supplied with an index of 2, then this call would insert the new repetition at index 2. (Note that in this example, the Set ID field in the OBX segments would also need to be renumbered manually).

Throws:

HL7Exception - if the named Structure is not part of this Group.

insertRepetition

public Structure insertRepetition(String name,
                                  int index)
                           throws HL7Exception

Inserts a repetition of a given Structure into repetitions of that structure by name. For example, if the Group contains 10 repititions an OBX segment and an OBX is supplied with an index of 2, then this call would insert the new repetition at index 2. Note that in this case, the Set ID field in the OBX segments would also need to be renumbered manually.

Parameters:

name - structure name

index - repetition to insert the structure

Returns:

The inserted structure

Throws:

HL7Exception - if the named Structure is not part of this Group.

getFieldNumForName

public int getFieldNumForName(String name)
                       throws HL7Exception

Given a child structure name, returns the child index (which is 1-indexed, meaning that the first child is at index 1

Parameters:

name - structure name

Returns:

position of the structure in this group

Throws:

HL7Exception - if the structure is unknown

getClass

public Class<? extends Structure> getClass(String name)

Returns the Class of the Structure at the given name index.

Specified by:

getClass in interface Group

Parameters:

name - name of the structure nested in this group

Returns:

class of the structure or null if the class does not exist

getName

public String getName()

Returns the class name (excluding package).

Specified by:

getName in interface Structure

Returns:

name of this structure

See Also:

Structure.getName()

insert

protected String insert(Class<? extends Structure> c,
                        boolean required,
                        boolean repeating,
                        int index,
                        String name)
                 throws HL7Exception

Inserts the given structure into this group, at the indicated index number. This method is used to support handling of unexpected segments (e.g. Z-segments). In contrast, specification of the group's normal children should be done at construction time, using the add(...) method.

Throws:

HL7Exception

insert

protected String insert(Class<? extends Structure> c,
                        boolean required,
                        boolean repeating,
                        boolean choiceElement,
                        int index,
                        String name)
                 throws HL7Exception

Throws:

HL7Exception

clear

public void clear()

Clears all data from this structure.

getModelClassFactory

public final ModelClassFactory getModelClassFactory()

Returns the ModelClassFactory associated with this structure

Returns:

the ModelClassFactory associated with this structure

accept

public boolean accept(MessageVisitor visitor,
                      Location location)
               throws HL7Exception

Iterates over the contained structures and calls the visitor for each of them.

Specified by:

accept in interface Visitable

Parameters:

visitor - MessageVisitor instance to be called back.

location - location of the group

Returns:

true if visiting shall continue, false if not

Throws:

HL7Exception

provideLocation

public Location provideLocation(Location location,
                                int index,
                                int repetition)

Description copied from interface: Visitable

Reusing the location of this object's parent, this method returns its own location within the message.

Specified by:

provideLocation in interface Visitable

Parameters:

location - the parents location

index - index of this object

repetition - repetition of this object

Returns:

this objects location

visitNestedStructures

protected void visitNestedStructures(MessageVisitor visitor,
                                     Location location)
                              throws HL7Exception

Throws:

HL7Exception