1 /**
2 The contents of this file are subject to the Mozilla Public License Version 1.1
3 (the "License"); you may not use this file except in compliance with the License.
4 You may obtain a copy of the License at http://www.mozilla.org/MPL/
5 Software distributed under the License is distributed on an "AS IS" basis,
6 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the
7 specific language governing rights and limitations under the License.
8
9 The Original Code is "Group.java". Description:
10 "An abstraction representing >1 message parts which may repeated together.
11 An implementation of Group should enforce contraints about on the contents of the group
12 and throw an exception if an attempt is made to add a Structure that the Group instance
13 does not recognize.
14 @author Bryan Tripp (bryan_tripp@sourceforge.net)"
15
16 The Initial Developer of the Original Code is University Health Network. Copyright (C)
17 2001. All Rights Reserved.
18
19 Contributor(s): ______________________________________.
20
21 Alternatively, the contents of this file may be used under the terms of the
22 GNU General Public License (the �GPL�), in which case the provisions of the GPL are
23 applicable instead of those above. If you wish to allow use of your version of this
24 file only under the terms of the GPL and not to allow others to use your version
25 of this file under the MPL, indicate your decision by deleting the provisions above
26 and replace them with the notice and other provisions required by the GPL License.
27 If you do not delete the provisions above, a recipient may use your version of
28 this file under either the MPL or the GPL.
29
30 */
31
32 package ca.uhn.hl7v2.model;
33
34 import ca.uhn.hl7v2.HL7Exception;
35
36 /**
37 * An abstraction representing >1 message parts which may repeated together.
38 * An implementation of Group should enforce contraints about on the contents of the group
39 * and throw an exception if an attempt is made to add a Structure that the Group instance
40 * does not recognize.
41 * @author Bryan Tripp (bryan_tripp@sourceforge.net)
42 */
43 public interface Group extends Structure {
44
45 /**
46 * Returns an array of Structure objects by name. For example, if the Group contains
47 * an MSH segment and "MSH" is supplied then this call would return a 1-element array
48 * containing the MSH segment. Multiple elements are returned when the segment or
49 * group repeats. The array may be empty if no repetitions have been accessed
50 * yet using the get(...) methods.
51 *
52 * @param name of the structure
53 * @return array of Structure objects
54 * @throws HL7Exception if the named Structure is not part of this Group.
55 */
56 Structure[] getAll(String name) throws HL7Exception;
57
58 /**
59 * Returns the named structure. If this Structure is repeating then the first
60 * repetition is returned. Creates the Structure if necessary.
61 *
62 * @param name of the structure
63 * @return first (or only) structure object
64 * @throws HL7Exception if the named Structure is not part of this Group.
65 */
66 Structure get(String name) throws HL7Exception;
67
68 /**
69 * Returns a particular repetition of the named Structure. If the given repetition
70 * number is one greater than the existing number of repetitions then a new
71 * Structure is created.
72 *
73 * @param name name of the structure
74 * @param rep repetition (zero-based)
75 * @return particular repetition of the named structure
76 * @throws HL7Exception if the named Structure is not part of this group,
77 * if the structure is not repeatable and the given rep is > 0,
78 * or if the given repetition number is more than one greater than the
79 * existing number of repetitions.
80 */
81 Structure get(String name, int rep) throws HL7Exception;
82
83 /**
84 * Returns true if the named structure is required.
85 *
86 * @param name name of the structure nested in this group
87 * @return true if structure is required
88 * @throws HL7Exception if the named Structure is not part of this group
89 */
90 boolean isRequired(String name) throws HL7Exception;
91
92 /**
93 * Returns true if the named structure is repeating.
94 *
95 * @param name name of the structure nested in this group
96 * @return true if structure is repeating
97 * @throws HL7Exception if the named Structure is not part of this group
98 */
99 boolean isRepeating(String name) throws HL7Exception;
100
101 /**
102 * Returns true if the named structure is a "choice element".
103 * Some HL7 structures (e.g. ORM_O01 in v2.5) have groups that have
104 * several possible first segments. In these structures, one of these
105 * "choice elements" must be present, but not more than one.
106 *
107 * @param name name of the structure nested in this group
108 * @return true if structure is a choice element
109 * @throws HL7Exception if the named Structure is not part of this group
110 *
111 */
112 boolean isChoiceElement(String name) throws HL7Exception;
113
114 /**
115 * Returns true if the named structure is a group.
116 *
117 * @param name name of the structure nested in this group
118 * @return true if structure is a choice element
119 * @throws HL7Exception if the named Structure is not part of this group
120 * @since 1.2
121 */
122 boolean isGroup(String name) throws HL7Exception;
123
124 /**
125 * Returns an ordered array of the names of the Structures in this
126 * Group. These names can be used to iterate through the group using
127 * repeated calls to <code>get(name)</code>.
128 *
129 * @return an ordered array of the names of the Structures in this Group
130 */
131 String[] getNames();
132
133 /**
134 * Returns the Class of the Structure at the given name index.
135 * @param name name of the structure nested in this group
136 * @return class of the structure or null if the class does not exist
137 */
138 Class<? extends Structure> getClass(String name);
139
140 /**
141 * Expands the group by introducing a new child Structure (i.e.
142 * a new Segment or Group). This method is used to support handling
143 * of unexpected segments (e.g. Z-segments).
144 * @param c class of the structure to insert (e.g. NTE.class)
145 * @param required whether the child is required
146 * @param repeating whether the child is repeating
147 * @param index index at which to insert the new child
148 * @param name the child name (e.g. "NTE")
149 * @return the name used to index the structure (may be appended with a number if
150 * name already used)
151 */
152 //public String insert(Class c, boolean required, boolean repeating, int index, String name) throws HL7Exception;
153
154 /**
155 * Expands the group definition to include a segment that is not
156 * defined by HL7 to be part of this group (eg an unregistered Z segment).
157 * The new segment is slotted at the end of the group. Thenceforward if
158 * such a segment is encountered it will be parsed into this location.
159 * If the segment name is unrecognized a GenericSegment is used. The
160 * segment is defined as repeating and not required.
161 *
162 * @param name name of the segment
163 * @return the final name of the segment (may be renamed if a segment of this
164 * name already exists.
165 * @throws HL7Exception if the segment could not be added
166 */
167 String addNonstandardSegment(String name) throws HL7Exception;
168
169 /**
170 * Expands the group definition to include a segment that is not
171 * defined by HL7 to be part of this group (eg an unregistered Z segment).
172 *
173 * @param name name of the segment
174 * @param theIndex index (zero-based) at which to insert this segment
175 * @return the name used to index the structure (may be appended with a number if
176 * name already used)
177 * @throws HL7Exception if the segment could not be added
178 */
179 String addNonstandardSegment(String name, int theIndex) throws HL7Exception;
180
181 }
182