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