001: /*
002: * The Apache Software License, Version 1.1
003: *
004: *
005: * Copyright (c) 2000-2002 The Apache Software Foundation. All rights
006: * reserved.
007: *
008: * Redistribution and use in source and binary forms, with or without
009: * modification, are permitted provided that the following conditions
010: * are met:
011: *
012: * 1. Redistributions of source code must retain the above copyright
013: * notice, this list of conditions and the following disclaimer.
014: *
015: * 2. Redistributions in binary form must reproduce the above copyright
016: * notice, this list of conditions and the following disclaimer in
017: * the documentation and/or other materials provided with the
018: * distribution.
019: *
020: * 3. The end-user documentation included with the redistribution,
021: * if any, must include the following acknowledgment:
022: * "This product includes software developed by the
023: * Apache Software Foundation (http://www.apache.org/)."
024: * Alternately, this acknowledgment may appear in the software itself,
025: * if and wherever such third-party acknowledgments normally appear.
026: *
027: * 4. The names "Xerces" and "Apache Software Foundation" must
028: * not be used to endorse or promote products derived from this
029: * software without prior written permission. For written
030: * permission, please contact apache@apache.org.
031: *
032: * 5. Products derived from this software may not be called "Apache",
033: * nor may "Apache" appear in their name, without prior written
034: * permission of the Apache Software Foundation.
035: *
036: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
037: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
038: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
039: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
040: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
041: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
042: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
043: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
044: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
045: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
046: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
047: * SUCH DAMAGE.
048: * ====================================================================
049: *
050: * This software consists of voluntary contributions made by many
051: * individuals on behalf of the Apache Software Foundation and was
052: * originally based on software copyright (c) 1999, International
053: * Business Machines, Inc., http://www.apache.org. For more
054: * information on the Apache Software Foundation, please see
055: * <http://www.apache.org/>.
056: */
057:
058: package com.sun.xml.stream.xerces.xni;
059:
060: /**
061: * The DTD content model handler interface defines callback methods
062: * to report information items in DTD content models of an element
063: * declaration. Parser components interested in DTD content model
064: * information implement this interface and are registered as the DTD
065: * content model handler on the DTD content model source.
066: *
067: * @see XMLDTDHandler
068: *
069: * @author Andy Clark, IBM
070: *
071: * @version $Id: XMLDTDContentModelHandler.java,v 1.2 2006/04/01 06:01:46 jeffsuttor Exp $
072: */
073: public interface XMLDTDContentModelHandler {
074:
075: //
076: // Constants
077: //
078:
079: // separators
080:
081: /**
082: * A choice separator for children and mixed content models. This
083: * separator is used to specify that the allowed child is one of a
084: * collection.
085: * <p>
086: * For example:
087: * <pre>
088: * <!ELEMENT elem (foo|bar)>
089: * <!ELEMENT elem (foo|bar+)>
090: * <!ELEMENT elem (foo|bar|baz)>
091: * <!ELEMENT elem (#PCDATA|foo|bar)*>
092: * </pre>
093: *
094: * @see #SEPARATOR_SEQUENCE
095: */
096: public static final short SEPARATOR_CHOICE = 0;
097:
098: /**
099: * A sequence separator for children content models. This separator
100: * is used to specify that the allowed children must follow in the
101: * specified sequence.
102: * <p>
103: * <pre>
104: * <!ELEMENT elem (foo,bar)>
105: * <!ELEMENT elem (foo,bar*)>
106: * <!ELEMENT elem (foo,bar,baz)>
107: * </pre>
108: *
109: * @see #SEPARATOR_CHOICE
110: */
111: public static final short SEPARATOR_SEQUENCE = 1;
112:
113: // occurrence counts
114:
115: /**
116: * This occurrence count limits the element, choice, or sequence in a
117: * children content model to zero or one. In other words, the child
118: * is optional.
119: * <p>
120: * For example:
121: * <pre>
122: * <!ELEMENT elem (foo?)>
123: * </pre>
124: *
125: * @see #OCCURS_ZERO_OR_MORE
126: * @see #OCCURS_ONE_OR_MORE
127: */
128: public static final short OCCURS_ZERO_OR_ONE = 2;
129:
130: /**
131: * This occurrence count limits the element, choice, or sequence in a
132: * children content model to zero or more. In other words, the child
133: * may appear an arbitrary number of times, or not at all. This
134: * occurrence count is also used for mixed content models.
135: * <p>
136: * For example:
137: * <pre>
138: * <!ELEMENT elem (foo*)>
139: * <!ELEMENT elem (#PCDATA|foo|bar)*>
140: * </pre>
141: *
142: * @see #OCCURS_ZERO_OR_ONE
143: * @see #OCCURS_ONE_OR_MORE
144: */
145: public static final short OCCURS_ZERO_OR_MORE = 3;
146:
147: /**
148: * This occurrence count limits the element, choice, or sequence in a
149: * children content model to one or more. In other words, the child
150: * may appear an arbitrary number of times, but must appear at least
151: * once.
152: * <p>
153: * For example:
154: * <pre>
155: * <!ELEMENT elem (foo+)>
156: * </pre>
157: *
158: * @see #OCCURS_ZERO_OR_ONE
159: * @see #OCCURS_ZERO_OR_MORE
160: */
161: public static final short OCCURS_ONE_OR_MORE = 4;
162:
163: //
164: // XMLDTDContentModelHandler methods
165: //
166:
167: /**
168: * The start of a content model. Depending on the type of the content
169: * model, specific methods may be called between the call to the
170: * startContentModel method and the call to the endContentModel method.
171: *
172: * @param elementName The name of the element.
173: * @param augmentations Additional information that may include infoset
174: * augmentations.
175: *
176: * @throws XNIException Thrown by handler to signal an error.
177: */
178: public void startContentModel(String elementName,
179: Augmentations augmentations) throws XNIException;
180:
181: /**
182: * A content model of ANY.
183: *
184: * @param augmentations Additional information that may include infoset
185: * augmentations.
186: *
187: * @throws XNIException Thrown by handler to signal an error.
188: *
189: * @see #empty
190: * @see #startGroup
191: */
192: public void any(Augmentations augmentations) throws XNIException;
193:
194: /**
195: * A content model of EMPTY.
196: *
197: * @throws XNIException Thrown by handler to signal an error.
198: *
199: * @param augmentations Additional information that may include infoset
200: * augmentations.
201: *
202: * @see #any
203: * @see #startGroup
204: */
205: public void empty(Augmentations augmentations) throws XNIException;
206:
207: /**
208: * A start of either a mixed or children content model. A mixed
209: * content model will immediately be followed by a call to the
210: * <code>pcdata()</code> method. A children content model will
211: * contain additional groups and/or elements.
212: *
213: * @param augmentations Additional information that may include infoset
214: * augmentations.
215: *
216: * @throws XNIException Thrown by handler to signal an error.
217: *
218: * @see #any
219: * @see #empty
220: */
221: public void startGroup(Augmentations augmentations)
222: throws XNIException;
223:
224: /**
225: * The appearance of "#PCDATA" within a group signifying a
226: * mixed content model. This method will be the first called
227: * following the content model's <code>startGroup()</code>.
228: *
229: * @param augmentations Additional information that may include infoset
230: * augmentations.
231: *
232: * @throws XNIException Thrown by handler to signal an error.
233: *
234: * @see #startGroup
235: */
236: public void pcdata(Augmentations augmentations) throws XNIException;
237:
238: /**
239: * A referenced element in a mixed or children content model.
240: *
241: * @param elementName The name of the referenced element.
242: * @param augmentations Additional information that may include infoset
243: * augmentations.
244: *
245: * @throws XNIException Thrown by handler to signal an error.
246: */
247: public void element(String elementName, Augmentations augmentations)
248: throws XNIException;
249:
250: /**
251: * The separator between choices or sequences of a mixed or children
252: * content model.
253: *
254: * @param separator The type of children separator.
255: * @param augmentations Additional information that may include infoset
256: * augmentations.
257: *
258: * @throws XNIException Thrown by handler to signal an error.
259: *
260: * @see #SEPARATOR_CHOICE
261: * @see #SEPARATOR_SEQUENCE
262: */
263: public void separator(short separator, Augmentations augmentations)
264: throws XNIException;
265:
266: /**
267: * The occurrence count for a child in a children content model or
268: * for the mixed content model group.
269: *
270: * @param occurrence The occurrence count for the last element
271: * or group.
272: * @param augmentations Additional information that may include infoset
273: * augmentations.
274: *
275: * @throws XNIException Thrown by handler to signal an error.
276: *
277: * @see #OCCURS_ZERO_OR_ONE
278: * @see #OCCURS_ZERO_OR_MORE
279: * @see #OCCURS_ONE_OR_MORE
280: */
281: public void occurrence(short occurrence, Augmentations augmentations)
282: throws XNIException;
283:
284: /**
285: * The end of a group for mixed or children content models.
286: *
287: * @param augmentations Additional information that may include infoset
288: * augmentations.
289: *
290: * @throws XNIException Thrown by handler to signal an error.
291: */
292: public void endGroup(Augmentations augmentations)
293: throws XNIException;
294:
295: /**
296: * The end of a content model.
297: *
298: * @param augmentations Additional information that may include infoset
299: * augmentations.
300: *
301: * @throws XNIException Thrown by handler to signal an error.
302: */
303: public void endContentModel(Augmentations augmentations)
304: throws XNIException;
305:
306: } // interface XMLDTDContentModelHandler
|