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 }*/