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 an ordered array of the names of the Structures in this 
085       * Group.  These names can be used to iterate through the group using 
086       * repeated calls to <code>get(name)</code>. 
087       */
088      public String[] getNames();
089      
090      /**
091       * Returns the Class of the Structure at the given name index.  
092       */
093      public Class getClass(String name);
094      
095      /**
096       * Expands the group by introducing a new child Structure (i.e. 
097       * a new Segment or Group).  This method is used to support handling 
098       * of unexpected segments (e.g. Z-segments).  
099       * @param c class of the structure to insert (e.g. NTE.class) 
100       * @param required whether the child is required 
101       * @param repeating whether the child is repeating 
102       * @param index index at which to insert the new child
103       * @param name the child name (e.g. "NTE")
104       * @return the name used to index the structure (may be appended with a number if 
105       *        name already used)
106       */
107      //public String insert(Class c, boolean required, boolean repeating, int index, String name) throws HL7Exception;
108      
109        /**
110         * Expands the group definition to include a segment that is not 
111         * defined by HL7 to be part of this group (eg an unregistered Z segment). 
112         * The new segment is slotted at the end of the group.  Thenceforward if 
113         * such a segment is encountered it will be parsed into this location. 
114         * If the segment name is unrecognized a GenericSegment is used.  The 
115         * segment is defined as repeating and not required.  
116         */
117        public String addNonstandardSegment(String name) throws HL7Exception;
118    
119        /**
120         * Expands the group definition to include a segment that is not 
121         * defined by HL7 to be part of this group (eg an unregistered Z segment).
122         * 
123         * @param The index (zero-indexed) at which to insert this segment
124         */
125        public String addNonstandardSegment(String name, int theIndex) throws HL7Exception;
126    
127    }
128    
129    // sample code ... 
130    /*Group m = new MessageImpl();
131    try {
132        m.add(new MSH()); 
133        ((MSH)m.get("MSH")).getFieldSeparator().setValue("|");
134        m.getMSH().getFieldSeparator().setValue("|");
135        
136        m.getERR(0).getThing();
137    } catch (HL7Exception e) {
138        
139    }*/