XMLDTDContentModelHandler


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