View Javadoc

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