Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Group |
|
| 1.0;1 |
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 | public 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 | public 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 | public 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 | public 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 | public 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 | public 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 | public 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 | public 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 | public 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 | public 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 | public String addNonstandardSegment(String name, int theIndex) throws HL7Exception; | |
180 | ||
181 | } | |
182 |