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 "IStructureDefinition.java"
010 *
011 * The Initial Developer of the Original Code is University Health Network. Copyright (C)
012 * 2001.  All Rights Reserved.
013 *
014 * Contributor(s):
015 *
016 * Alternatively, the contents of this file may be used under the terms of the
017 * GNU General Public License (the  �GPL�), in which case the provisions of the GPL are
018 * applicable instead of those above.  If you wish to allow use of your version of this
019 * file only under the terms of the GPL and not to allow others to use your version
020 * of this file under the MPL, indicate your decision by deleting  the provisions above
021 * and replace  them with the notice and other provisions required by the GPL License.
022 * If you do not delete the provisions above, a recipient may use your version of
023 * this file under either the MPL or the GPL.
024 *
025 */
026
027
028package ca.uhn.hl7v2.parser;
029
030import java.util.List;
031import java.util.Set;
032
033import ca.uhn.hl7v2.model.Structure;
034
035/**
036 * Contains information about the composition of a given type of {@link Structure}.
037 * At runtime, parsers will use accessors provided by various structure types (messages, groups,
038 * segments) to determine the structure of a messages. Structure definitions are used
039 * to cache that information between parse calls.
040 */
041public interface IStructureDefinition {
042
043    /**
044     * @return Returns this structure's first sibling (in other words, its
045     *         parent's first child). Returns
046     *         <code>null<code> if this is the first sibling, or if this has no parent
047     */
048    IStructureDefinition getFirstSibling();
049
050    /**
051     * @return Returns the next leaf (segment) after this one, within the same
052     * group, only if one exists and this structure is also a leaf. Otherwise returns <code>null</code>.
053     */
054    IStructureDefinition getNextLeaf();
055
056    /**
057     * @return The name of the segment, as it is known to it's parent. This
058     * will differ from {{@link #getName()}} in the case of multiple segments
059     * with the same name in a group, e.g. the two PID segments in ADT_A17,
060     * where the second one it known as PID2 to it's parent. 
061     */
062    String getNameAsItAppearsInParent();
063    
064    /**
065     * @return Returns the name of this structure
066     */
067    String getName();
068
069    /**
070     * @return Returns true if this structure is a segment
071     */
072    boolean isSegment();
073
074    /**
075     * @return Returns true if this is a repeatable structure
076     */
077    boolean isRepeating();
078
079    /**
080     * @return Returns all children of this structure definition
081     */
082    List<StructureDefinition> getChildren();
083
084    /**
085     * @return Returns the index of the position of this structure
086     * within it's parent's children
087     */
088    int getPosition();
089
090    /**
091     * @return Returns the parent structure of this structure, if one exists.
092     * Otherwise, returns null.
093     */
094    IStructureDefinition getParent();
095
096    /**
097     * @return Returns true if this structure is the final child of it's parent.
098     */
099    boolean isFinalChildOfParent();
100
101    /**
102     * @return Returns this structure's next sibling within it's parent, if any.
103     */
104    IStructureDefinition getNextSibling();
105
106    /**
107     * @return Does this structure have children (i.e. is it not a segment)
108     */
109    boolean hasChildren();
110
111    /**
112     * Should only be called on a leaf node (segment). Returns the names
113     * of all valid children which may follow this one, at any level in the
114     * hierarchy (including as later siblings of parent structures to
115     * this one)
116     */
117    Set<String> getNamesOfAllPossibleFollowingLeaves();
118
119    /**
120     * May return null
121     * @return
122     */
123    IStructureDefinition getFirstChild();
124
125    /**
126     * Returns the names of any possible children that could be the first
127     * required child of this group.
128     *
129     * For instance, for the group below "ORC" and "OBR" would both be
130     * returned, as they are both potential first children of this group.
131     *
132     * Note that the name returned by {@link #getName() this.getName()}
133     * is also returned.
134     *
135     * <code>
136     *               ORDER_OBSERVATION
137     *    {
138     *    [ ORC ]
139     *    OBR
140     *    [ { NTE } ]
141     *    [ CTD ]
142     *                  OBSERVATION
143     *       {
144     *       [ OBX ]
145     *       [ { NTE } ]
146     *       }
147     *                  OBSERVATION
148     *    [ { FT1 } ]
149     *    [ { CTI } ]
150     *    }
151     *                  ORDER_OBSERVATION
152     *     </code>
153     *
154     */
155    Set<String> getAllPossibleFirstChildren();
156
157    /**
158     * @return Returns the names of all children of this structure, including first elements within child groups
159     */
160    Set<String> getAllChildNames();
161
162    /**
163     * @return Is this a required structure within it's parent
164     */
165    boolean isRequired();
166
167}