001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.xerces.xni;
019:
020: import org.apache.xerces.xni.parser.XMLDTDContentModelSource;
021:
022: /**
023: * The DTD content model handler interface defines callback methods
024: * to report information items in DTD content models of an element
025: * declaration. Parser components interested in DTD content model
026: * information implement this interface and are registered as the DTD
027: * content model handler on the DTD content model source.
028: *
029: * @see XMLDTDHandler
030: *
031: * @author Andy Clark, IBM
032: *
033: * @version $Id: XMLDTDContentModelHandler.java 447247 2006-09-18 05:23:52Z mrglavas $
034: */
035: public interface XMLDTDContentModelHandler {
036:
037: //
038: // Constants
039: //
040:
041: // separators
042:
043: /**
044: * A choice separator for children and mixed content models. This
045: * separator is used to specify that the allowed child is one of a
046: * collection.
047: * <p>
048: * For example:
049: * <pre>
050: * <!ELEMENT elem (foo|bar)>
051: * <!ELEMENT elem (foo|bar+)>
052: * <!ELEMENT elem (foo|bar|baz)>
053: * <!ELEMENT elem (#PCDATA|foo|bar)*>
054: * </pre>
055: *
056: * @see #SEPARATOR_SEQUENCE
057: */
058: public static final short SEPARATOR_CHOICE = 0;
059:
060: /**
061: * A sequence separator for children content models. This separator
062: * is used to specify that the allowed children must follow in the
063: * specified sequence.
064: * <p>
065: * <pre>
066: * <!ELEMENT elem (foo,bar)>
067: * <!ELEMENT elem (foo,bar*)>
068: * <!ELEMENT elem (foo,bar,baz)>
069: * </pre>
070: *
071: * @see #SEPARATOR_CHOICE
072: */
073: public static final short SEPARATOR_SEQUENCE = 1;
074:
075: // occurrence counts
076:
077: /**
078: * This occurrence count limits the element, choice, or sequence in a
079: * children content model to zero or one. In other words, the child
080: * is optional.
081: * <p>
082: * For example:
083: * <pre>
084: * <!ELEMENT elem (foo?)>
085: * </pre>
086: *
087: * @see #OCCURS_ZERO_OR_MORE
088: * @see #OCCURS_ONE_OR_MORE
089: */
090: public static final short OCCURS_ZERO_OR_ONE = 2;
091:
092: /**
093: * This occurrence count limits the element, choice, or sequence in a
094: * children content model to zero or more. In other words, the child
095: * may appear an arbitrary number of times, or not at all. This
096: * occurrence count is also used for mixed content models.
097: * <p>
098: * For example:
099: * <pre>
100: * <!ELEMENT elem (foo*)>
101: * <!ELEMENT elem (#PCDATA|foo|bar)*>
102: * </pre>
103: *
104: * @see #OCCURS_ZERO_OR_ONE
105: * @see #OCCURS_ONE_OR_MORE
106: */
107: public static final short OCCURS_ZERO_OR_MORE = 3;
108:
109: /**
110: * This occurrence count limits the element, choice, or sequence in a
111: * children content model to one or more. In other words, the child
112: * may appear an arbitrary number of times, but must appear at least
113: * once.
114: * <p>
115: * For example:
116: * <pre>
117: * <!ELEMENT elem (foo+)>
118: * </pre>
119: *
120: * @see #OCCURS_ZERO_OR_ONE
121: * @see #OCCURS_ZERO_OR_MORE
122: */
123: public static final short OCCURS_ONE_OR_MORE = 4;
124:
125: //
126: // XMLDTDContentModelHandler methods
127: //
128:
129: /**
130: * The start of a content model. Depending on the type of the content
131: * model, specific methods may be called between the call to the
132: * startContentModel method and the call to the endContentModel method.
133: *
134: * @param elementName The name of the element.
135: * @param augmentations Additional information that may include infoset
136: * augmentations.
137: *
138: * @throws XNIException Thrown by handler to signal an error.
139: */
140: public void startContentModel(String elementName,
141: Augmentations augmentations) throws XNIException;
142:
143: /**
144: * A content model of ANY.
145: *
146: * @param augmentations Additional information that may include infoset
147: * augmentations.
148: *
149: * @throws XNIException Thrown by handler to signal an error.
150: *
151: * @see #empty
152: * @see #startGroup
153: */
154: public void any(Augmentations augmentations) throws XNIException;
155:
156: /**
157: * A content model of EMPTY.
158: *
159: * @throws XNIException Thrown by handler to signal an error.
160: *
161: * @param augmentations Additional information that may include infoset
162: * augmentations.
163: *
164: * @see #any
165: * @see #startGroup
166: */
167: public void empty(Augmentations augmentations) throws XNIException;
168:
169: /**
170: * A start of either a mixed or children content model. A mixed
171: * content model will immediately be followed by a call to the
172: * <code>pcdata()</code> method. A children content model will
173: * contain additional groups and/or elements.
174: *
175: * @param augmentations Additional information that may include infoset
176: * augmentations.
177: *
178: * @throws XNIException Thrown by handler to signal an error.
179: *
180: * @see #any
181: * @see #empty
182: */
183: public void startGroup(Augmentations augmentations)
184: throws XNIException;
185:
186: /**
187: * The appearance of "#PCDATA" within a group signifying a
188: * mixed content model. This method will be the first called
189: * following the content model's <code>startGroup()</code>.
190: *
191: * @param augmentations Additional information that may include infoset
192: * augmentations.
193: *
194: * @throws XNIException Thrown by handler to signal an error.
195: *
196: * @see #startGroup
197: */
198: public void pcdata(Augmentations augmentations) throws XNIException;
199:
200: /**
201: * A referenced element in a mixed or children content model.
202: *
203: * @param elementName The name of the referenced element.
204: * @param augmentations Additional information that may include infoset
205: * augmentations.
206: *
207: * @throws XNIException Thrown by handler to signal an error.
208: */
209: public void element(String elementName, Augmentations augmentations)
210: throws XNIException;
211:
212: /**
213: * The separator between choices or sequences of a mixed or children
214: * content model.
215: *
216: * @param separator The type of children separator.
217: * @param augmentations Additional information that may include infoset
218: * augmentations.
219: *
220: * @throws XNIException Thrown by handler to signal an error.
221: *
222: * @see #SEPARATOR_CHOICE
223: * @see #SEPARATOR_SEQUENCE
224: */
225: public void separator(short separator, Augmentations augmentations)
226: throws XNIException;
227:
228: /**
229: * The occurrence count for a child in a children content model or
230: * for the mixed content model group.
231: *
232: * @param occurrence The occurrence count for the last element
233: * or group.
234: * @param augmentations Additional information that may include infoset
235: * augmentations.
236: *
237: * @throws XNIException Thrown by handler to signal an error.
238: *
239: * @see #OCCURS_ZERO_OR_ONE
240: * @see #OCCURS_ZERO_OR_MORE
241: * @see #OCCURS_ONE_OR_MORE
242: */
243: public void occurrence(short occurrence, Augmentations augmentations)
244: throws XNIException;
245:
246: /**
247: * The end of a group for mixed or children content models.
248: *
249: * @param augmentations Additional information that may include infoset
250: * augmentations.
251: *
252: * @throws XNIException Thrown by handler to signal an error.
253: */
254: public void endGroup(Augmentations augmentations)
255: 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)
266: 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
|