/**

  * The contents of this file are subject to the Mozilla Public License Version 1.1

  * (the "License"); you may not use this file except in compliance with the License.

  * You may obtain a copy of the License at http://www.mozilla.org/MPL/

  * Software distributed under the License is distributed on an "AS IS" basis,

  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the

  * specific language governing rights and limitations under the License.

  *

  * The Original Code is "IStructureDefinition.java"

  *

  * The Initial Developer of the Original Code is University Health Network. Copyright (C)

  * 2001.  All Rights Reserved.

  *

  * Contributor(s):

  *

  * Alternatively, the contents of this file may be used under the terms of the

  * GNU General Public License (the  �GPL�), in which case the provisions of the GPL are

  * applicable instead of those above.  If you wish to allow use of your version of this

  * file only under the terms of the GPL and not to allow others to use your version

  * of this file under the MPL, indicate your decision by deleting  the provisions above

  * and replace  them with the notice and other provisions required by the GPL License.

  * If you do not delete the provisions above, a recipient may use your version of

  * this file under either the MPL or the GPL.

  *

  */

 package ca.uhn.hl7v2.parser;

 import java.util.List;

 import java.util.Set;

 /**

  * Contains information about the composition of a given type of {@link ca.uhn.hl7v2.model.Structure Structure}.

  * At runtime, parsers will use accessors provided by various structure types (messages, groups,

  * segments) to determine the structure of a messages. Structure definitions are used

  * to cache that information between parse calls.

  */

 public interface IStructureDefinition {

     /**

      * @return Returns this structure's first sibling (in other words, its

      *         parent's first child). Returns

      *         <code>null<code> if this is the first sibling, or if this has no parent

      */

     IStructureDefinition getFirstSibling();

     /**

      * @return Returns the next leaf (segment) after this one, within the same

      * group, only if one exists and this structure is also a leaf. Otherwise returns <code>null</code>.

      */

     IStructureDefinition getNextLeaf();

     /**

      * @return The name of the segment, as it is known to it's parent. This

      * will differ from {{@link #getName()}} in the case of multiple segments

      * with the same name in a group, e.g. the two PID segments in ADT_A17,

      * where the second one it known as PID2 to it's parent. 

      */

     String getNameAsItAppearsInParent();

     /**

      * @return Returns the name of this structure

      */

     String getName();

     /**

      * @return Returns true if this structure is a segment

      */

     boolean isSegment();

     /**

      * @return Returns true if this is a repeatable structure

      */

     boolean isRepeating();

     /**

      * @return Returns all children of this structure definition

      */

     List<StructureDefinition> getChildren();

     /**

      * @return Returns the index of the position of this structure

      * within it's parent's children

      */

     int getPosition();

     /**

      * @return Returns the parent structure of this structure, if one exists.

      * Otherwise, returns null.

      */

     IStructureDefinition getParent();

     /**

      * @return Returns true if this structure is the final child of it's parent.

      */

     boolean isFinalChildOfParent();

     /**

      * @return Returns this structure's next sibling within it's parent, if any.

      */

     IStructureDefinition getNextSibling();

     /**

      * @return Does this structure have children (i.e. is it not a segment)

      */

     boolean hasChildren();

     /**

      * Should only be called on a leaf node (segment). Returns the names

      * of all valid children which may follow this one, at any level in the

      * hierarchy (including as later siblings of parent structures to

      * this one)

      *

      * @return the names of all valid children which may follow this one

      */

     Set<String> getNamesOfAllPossibleFollowingLeaves();

     /**

      * @return structure definition of first child of null if there is no child

      */

     IStructureDefinition getFirstChild();

     /**

      * Returns the names of any possible children that could be the first

      * required child of this group.

      *

      * For instance, for the group below "ORC" and "OBR" would both be

      * returned, as they are both potential first children of this group.

      *

      * Note that the name returned by {@link #getName() this.getName()}

      * is also returned.

      *

      * <code>

      *               ORDER_OBSERVATION

      *          {

      *          [ ORC ]

      *          OBR

      *          [ { NTE } ]

      *          [ CTD ]

      *                        OBSERVATION

      *             {

      *             [ OBX ]

      *             [ { NTE } ]

      *             }

      *                        OBSERVATION

      *          [ { FT1 } ]

      *          [ { CTI } ]

      *          }

      *                        ORDER_OBSERVATION

      *           </code>

      *

      *

      * @return the names of any possible children that could be the first

      * required child of this group

      */

     Set<String> getAllPossibleFirstChildren();

     /**

      * @return Returns the names of all children of this structure, including first elements within child groups

      */

     Set<String> getAllChildNames();

     /**

      * @return true if this element a choice element

      *

      * @see ca.uhn.hl7v2.model.Group#isChoiceElement(String)

      */

     boolean isChoiceElement();

     /**

      * @return true if this a required structure within it's parent

      */

     boolean isRequired();

 }