Package 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:

  • Constructor Details

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

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

    • 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