001 /**
002 The contents of this file are subject to the Mozilla Public License Version 1.1
003 (the "License"); you may not use this file except in compliance with the License.
004 You may obtain a copy of the License at http://www.mozilla.org/MPL/
005 Software distributed under the License is distributed on an "AS IS" basis,
006 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the
007 specific language governing rights and limitations under the License.
008
009 The Original Code is "Group.java". Description:
010 "An abstraction representing >1 message parts which may repeated together.
011 An implementation of Group should enforce contraints about on the contents of the group
012 and throw an exception if an attempt is made to add a Structure that the Group instance
013 does not recognize.
014 @author Bryan Tripp (bryan_tripp@sourceforge.net)"
015
016 The Initial Developer of the Original Code is University Health Network. Copyright (C)
017 2001. All Rights Reserved.
018
019 Contributor(s): ______________________________________.
020
021 Alternatively, the contents of this file may be used under the terms of the
022 GNU General Public License (the �GPL�), in which case the provisions of the GPL are
023 applicable instead of those above. If you wish to allow use of your version of this
024 file only under the terms of the GPL and not to allow others to use your version
025 of this file under the MPL, indicate your decision by deleting the provisions above
026 and replace them with the notice and other provisions required by the GPL License.
027 If you do not delete the provisions above, a recipient may use your version of
028 this file under either the MPL or the GPL.
029
030 */
031
032 package ca.uhn.hl7v2.model;
033
034 import ca.uhn.hl7v2.HL7Exception;
035
036 /**
037 * An abstraction representing >1 message parts which may repeated together.
038 * An implementation of Group should enforce contraints about on the contents of the group
039 * and throw an exception if an attempt is made to add a Structure that the Group instance
040 * does not recognize.
041 * @author Bryan Tripp (bryan_tripp@sourceforge.net)
042 */
043 public interface Group extends Structure {
044
045 /**
046 * Returns an array of Structure objects by name. For example, if the Group contains
047 * an MSH segment and "MSH" is supplied then this call would return a 1-element array
048 * containing the MSH segment. Multiple elements are returned when the segment or
049 * group repeats. The array may be empty if no repetitions have been accessed
050 * yet using the get(...) methods.
051 * @throws HL7Exception if the named Structure is not part of this Group.
052 */
053 public Structure[] getAll(String name) throws HL7Exception;
054
055 /**
056 * Returns the named structure. If this Structure is repeating then the first
057 * repetition is returned. Creates the Structure if necessary.
058 * @throws HL7Exception if the named Structure is not part of this Group.
059 */
060 public Structure get(String name) throws HL7Exception;
061
062 /**
063 * Returns a particular repetition of the named Structure. If the given repetition
064 * number is one greater than the existing number of repetitions then a new
065 * Structure is created.
066 * @throws HL7Exception if the named Structure is not part of this group,
067 * if the structure is not repeatable and the given rep is > 0,
068 * or if the given repetition number is more than one greater than the
069 * existing number of repetitions.
070 */
071 public Structure get(String name, int rep) throws HL7Exception;
072
073 /**
074 * Returns true if the named structure is required.
075 */
076 public boolean isRequired(String name) throws HL7Exception;
077
078 /**
079 * Returns true if the named structure is repeating.
080 */
081 public boolean isRepeating(String name) throws HL7Exception;
082
083 /**
084 * Returns true if the named structure is a group.
085 *
086 * @since 1.2
087 */
088 public boolean isGroup(String name) throws HL7Exception;
089
090 /**
091 * Returns an ordered array of the names of the Structures in this
092 * Group. These names can be used to iterate through the group using
093 * repeated calls to <code>get(name)</code>.
094 */
095 public String[] getNames();
096
097 /**
098 * Returns the Class of the Structure at the given name index.
099 */
100 public Class<? extends Structure> getClass(String name);
101
102 /**
103 * Expands the group by introducing a new child Structure (i.e.
104 * a new Segment or Group). This method is used to support handling
105 * of unexpected segments (e.g. Z-segments).
106 * @param c class of the structure to insert (e.g. NTE.class)
107 * @param required whether the child is required
108 * @param repeating whether the child is repeating
109 * @param index index at which to insert the new child
110 * @param name the child name (e.g. "NTE")
111 * @return the name used to index the structure (may be appended with a number if
112 * name already used)
113 */
114 //public String insert(Class c, boolean required, boolean repeating, int index, String name) throws HL7Exception;
115
116 /**
117 * Expands the group definition to include a segment that is not
118 * defined by HL7 to be part of this group (eg an unregistered Z segment).
119 * The new segment is slotted at the end of the group. Thenceforward if
120 * such a segment is encountered it will be parsed into this location.
121 * If the segment name is unrecognized a GenericSegment is used. The
122 * segment is defined as repeating and not required.
123 */
124 public String addNonstandardSegment(String name) throws HL7Exception;
125
126 /**
127 * Expands the group definition to include a segment that is not
128 * defined by HL7 to be part of this group (eg an unregistered Z segment).
129 *
130 * @param The index (zero-indexed) at which to insert this segment
131 */
132 public String addNonstandardSegment(String name, int theIndex) throws HL7Exception;
133
134 }
135
136 // sample code ...
137 /*Group m = new MessageImpl();
138 try {
139 m.add(new MSH());
140 ((MSH)m.get("MSH")).getFieldSeparator().setValue("|");
141 m.getMSH().getFieldSeparator().setValue("|");
142
143 m.getERR(0).getThing();
144 } catch (HL7Exception e) {
145
146 }*/