1 /*
   2  * reserved comment block
   3  * DO NOT REMOVE OR ALTER!
   4  */
   5 /*
   6  * Licensed to the Apache Software Foundation (ASF) under one or more
   7  * contributor license agreements.  See the NOTICE file distributed with
   8  * this work for additional information regarding copyright ownership.
   9  * The ASF licenses this file to You under the Apache License, Version 2.0
  10  * (the "License"); you may not use this file except in compliance with
  11  * the License.  You may obtain a copy of the License at
  12  *
  13  *      http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  */
  21 
  22 package com.sun.org.apache.xerces.internal.xni;
  23 
  24 import com.sun.org.apache.xerces.internal.xni.parser.XMLDTDContentModelSource;
  25 
  26 /**
  27  * The DTD content model handler interface defines callback methods
  28  * to report information items in DTD content models of an element
  29  * declaration. Parser components interested in DTD content model
  30  * information implement this interface and are registered as the DTD
  31  * content model handler on the DTD content model source.
  32  *
  33  * @see XMLDTDHandler
  34  *
  35  * @author Andy Clark, IBM
  36  *
  37  */
  38 public interface XMLDTDContentModelHandler {
  39 
  40     //
  41     // Constants
  42     //
  43 
  44     // separators
  45 
  46     /**
  47      * A choice separator for children and mixed content models. This
  48      * separator is used to specify that the allowed child is one of a
  49      * collection.
  50      * <p>
  51      * For example:
  52      * <pre>
  53      * &lt;!ELEMENT elem (foo|bar)&gt;
  54      * &lt;!ELEMENT elem (foo|bar+)&gt;
  55      * &lt;!ELEMENT elem (foo|bar|baz)&gt;
  56      * &lt;!ELEMENT elem (#PCDATA|foo|bar)*&gt;
  57      * </pre>
  58      *
  59      * @see #SEPARATOR_SEQUENCE
  60      */
  61     public static final short SEPARATOR_CHOICE = 0;
  62 
  63     /**
  64      * A sequence separator for children content models. This separator
  65      * is used to specify that the allowed children must follow in the
  66      * specified sequence.
  67      * <p>
  68      * <pre>
  69      * &lt;!ELEMENT elem (foo,bar)&gt;
  70      * &lt;!ELEMENT elem (foo,bar*)&gt;
  71      * &lt;!ELEMENT elem (foo,bar,baz)&gt;
  72      * </pre>
  73      *
  74      * @see #SEPARATOR_CHOICE
  75      */
  76     public static final short SEPARATOR_SEQUENCE = 1;
  77 
  78     // occurrence counts
  79 
  80     /**
  81      * This occurrence count limits the element, choice, or sequence in a
  82      * children content model to zero or one. In other words, the child
  83      * is optional.
  84      * <p>
  85      * For example:
  86      * <pre>
  87      * &lt;!ELEMENT elem (foo?)&gt;
  88      * </pre>
  89      *
  90      * @see #OCCURS_ZERO_OR_MORE
  91      * @see #OCCURS_ONE_OR_MORE
  92      */
  93     public static final short OCCURS_ZERO_OR_ONE = 2;
  94 
  95     /**
  96      * This occurrence count limits the element, choice, or sequence in a
  97      * children content model to zero or more. In other words, the child
  98      * may appear an arbitrary number of times, or not at all. This
  99      * occurrence count is also used for mixed content models.
 100      * <p>
 101      * For example:
 102      * <pre>
 103      * &lt;!ELEMENT elem (foo*)&gt;
 104      * &lt;!ELEMENT elem (#PCDATA|foo|bar)*&gt;
 105      * </pre>
 106      *
 107      * @see #OCCURS_ZERO_OR_ONE
 108      * @see #OCCURS_ONE_OR_MORE
 109      */
 110     public static final short OCCURS_ZERO_OR_MORE = 3;
 111 
 112     /**
 113      * This occurrence count limits the element, choice, or sequence in a
 114      * children content model to one or more. In other words, the child
 115      * may appear an arbitrary number of times, but must appear at least
 116      * once.
 117      * <p>
 118      * For example:
 119      * <pre>
 120      * &lt;!ELEMENT elem (foo+)&gt;
 121      * </pre>
 122      *
 123      * @see #OCCURS_ZERO_OR_ONE
 124      * @see #OCCURS_ZERO_OR_MORE
 125      */
 126     public static final short OCCURS_ONE_OR_MORE = 4;
 127 
 128     //
 129     // XMLDTDContentModelHandler methods
 130     //
 131 
 132     /**
 133      * The start of a content model. Depending on the type of the content
 134      * model, specific methods may be called between the call to the
 135      * startContentModel method and the call to the endContentModel method.
 136      *
 137      * @param elementName The name of the element.
 138      * @param augmentations Additional information that may include infoset
 139      *                      augmentations.
 140      *
 141      * @throws XNIException Thrown by handler to signal an error.
 142      */
 143     public void startContentModel(String elementName, Augmentations augmentations)
 144         throws XNIException;
 145 
 146     /**
 147      * A content model of ANY.
 148      *
 149      * @param augmentations Additional information that may include infoset
 150      *                      augmentations.
 151      *
 152      * @throws XNIException Thrown by handler to signal an error.
 153      *
 154      * @see #empty
 155      * @see #startGroup
 156      */
 157     public void any(Augmentations augmentations) throws XNIException;
 158 
 159     /**
 160      * A content model of EMPTY.
 161      *
 162      * @throws XNIException Thrown by handler to signal an error.
 163      *
 164      * @param augmentations Additional information that may include infoset
 165      *                      augmentations.
 166      *
 167      * @see #any
 168      * @see #startGroup
 169      */
 170     public void empty(Augmentations augmentations) throws XNIException;
 171 
 172     /**
 173      * A start of either a mixed or children content model. A mixed
 174      * content model will immediately be followed by a call to the
 175      * <code>pcdata()</code> method. A children content model will
 176      * contain additional groups and/or elements.
 177      *
 178      * @param augmentations Additional information that may include infoset
 179      *                      augmentations.
 180      *
 181      * @throws XNIException Thrown by handler to signal an error.
 182      *
 183      * @see #any
 184      * @see #empty
 185      */
 186     public void startGroup(Augmentations augmentations) throws XNIException;
 187 
 188     /**
 189      * The appearance of "#PCDATA" within a group signifying a
 190      * mixed content model. This method will be the first called
 191      * following the content model's <code>startGroup()</code>.
 192      *
 193      * @param augmentations Additional information that may include infoset
 194      *                      augmentations.
 195      *
 196      * @throws XNIException Thrown by handler to signal an error.
 197      *
 198      * @see #startGroup
 199      */
 200     public void pcdata(Augmentations augmentations) throws XNIException;
 201 
 202     /**
 203      * A referenced element in a mixed or children content model.
 204      *
 205      * @param elementName The name of the referenced element.
 206      * @param augmentations Additional information that may include infoset
 207      *                      augmentations.
 208      *
 209      * @throws XNIException Thrown by handler to signal an error.
 210      */
 211     public void element(String elementName, Augmentations augmentations)
 212         throws XNIException;
 213 
 214     /**
 215      * The separator between choices or sequences of a mixed or children
 216      * content model.
 217      *
 218      * @param separator The type of children separator.
 219      * @param augmentations Additional information that may include infoset
 220      *                      augmentations.
 221      *
 222      * @throws XNIException Thrown by handler to signal an error.
 223      *
 224      * @see #SEPARATOR_CHOICE
 225      * @see #SEPARATOR_SEQUENCE
 226      */
 227     public void separator(short separator, Augmentations augmentations)
 228         throws XNIException;
 229 
 230     /**
 231      * The occurrence count for a child in a children content model or
 232      * for the mixed content model group.
 233      *
 234      * @param occurrence The occurrence count for the last element
 235      *                   or group.
 236      * @param augmentations Additional information that may include infoset
 237      *                      augmentations.
 238      *
 239      * @throws XNIException Thrown by handler to signal an error.
 240      *
 241      * @see #OCCURS_ZERO_OR_ONE
 242      * @see #OCCURS_ZERO_OR_MORE
 243      * @see #OCCURS_ONE_OR_MORE
 244      */
 245     public void occurrence(short occurrence, Augmentations augmentations)
 246         throws XNIException;
 247 
 248     /**
 249      * The end of a group for mixed or children content models.
 250      *
 251      * @param augmentations Additional information that may include infoset
 252      *                      augmentations.
 253      *
 254      * @throws XNIException Thrown by handler to signal an error.
 255      */
 256     public void endGroup(Augmentations augmentations) throws XNIException;
 257 
 258     /**
 259      * The end of a content model.
 260      *
 261      * @param augmentations Additional information that may include infoset
 262      *                      augmentations.
 263      *
 264      * @throws XNIException Thrown by handler to signal an error.
 265      */
 266     public void endContentModel(Augmentations augmentations) throws XNIException;
 267 
 268     // set content model source
 269     public void setDTDContentModelSource(XMLDTDContentModelSource source);
 270 
 271     // get content model source
 272     public XMLDTDContentModelSource getDTDContentModelSource();
 273 
 274 } // interface XMLDTDContentModelHandler