001: /*
002: * @(#)XmlChars.java 1.1 00/08/05
003: *
004: * Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved.
005: */
006:
007: package com.sun.xml.dtdparser;
008:
009: import org.xml.sax.Locator;
010: import org.xml.sax.SAXException;
011: import org.xml.sax.SAXParseException;
012:
013: import java.util.EventListener;
014:
015: /**
016: * All DTD parsing events are signaled through this interface.
017: */
018: public interface DTDEventListener extends EventListener {
019:
020: public void setDocumentLocator(Locator loc);
021:
022: /**
023: * Receive notification of a Processing Instruction.
024: * Processing instructions contain information meaningful
025: * to the application.
026: *
027: * @param target The target of the proceessing instruction
028: * which should have meaning to the application.
029: * @param data The instruction itself which should contain
030: * valid XML characters.
031: * @throws SAXException
032: */
033: public void processingInstruction(String target, String data)
034: throws SAXException;
035:
036: /**
037: * Receive notification of a Notation Declaration.
038: * Notation declarations are used by elements and entities
039: * for identifying embedded non-XML data.
040: *
041: * @param name The notation name, referred to by entities and
042: * elements.
043: * @param publicId The public identifier
044: * @param systemId The system identifier
045: */
046: public void notationDecl(String name, String publicId,
047: String systemId) throws SAXException;
048:
049: /**
050: * Receive notification of an unparsed entity declaration.
051: * Unparsed entities are non-XML data.
052: *
053: * @param name The name of the unparsed entity.
054: * @param publicId The public identifier
055: * @param systemId The system identifier
056: * @param notationName The associated notation
057: */
058: public void unparsedEntityDecl(String name, String publicId,
059: String systemId, String notationName) throws SAXException;
060:
061: /**
062: * Receive notification of a internal general entity declaration event.
063: *
064: * @param name The internal general entity name.
065: * @param value The value of the entity, which may include unexpanded
066: * entity references. Character references will have been
067: * expanded.
068: * @throws SAXException
069: * @see #externalGeneralEntityDecl(String, String, String)
070: */
071: public void internalGeneralEntityDecl(String name, String value)
072: throws SAXException;
073:
074: /**
075: * Receive notification of an external parsed general entity
076: * declaration event.
077: * <p/>
078: * <p>If a system identifier is present, and it is a relative URL, the
079: * parser will have resolved it fully before passing it through this
080: * method to a listener.</p>
081: *
082: * @param name The entity name.
083: * @param publicId The entity's public identifier, or null if
084: * none was given.
085: * @param systemId The entity's system identifier.
086: * @throws SAXException
087: * @see #unparsedEntityDecl(String, String, String, String)
088: */
089: public void externalGeneralEntityDecl(String name, String publicId,
090: String systemId) throws SAXException;
091:
092: /**
093: * Receive notification of a internal parameter entity declaration
094: * event.
095: *
096: * @param name The internal parameter entity name.
097: * @param value The value of the entity, which may include unexpanded
098: * entity references. Character references will have been
099: * expanded.
100: * @throws SAXException
101: * @see #externalParameterEntityDecl(String, String, String)
102: */
103: public void internalParameterEntityDecl(String name, String value)
104: throws SAXException;
105:
106: /**
107: * Receive notification of an external parameter entity declaration
108: * event.
109: * <p/>
110: * <p>If a system identifier is present, and it is a relative URL, the
111: * parser will have resolved it fully before passing it through this
112: * method to a listener.</p>
113: *
114: * @param name The parameter entity name.
115: * @param publicId The entity's public identifier, or null if
116: * none was given.
117: * @param systemId The entity's system identifier.
118: * @throws SAXException
119: * @see #unparsedEntityDecl(String, String, String, String)
120: */
121: public void externalParameterEntityDecl(String name,
122: String publicId, String systemId) throws SAXException;
123:
124: /**
125: * Receive notification of the beginning of the DTD.
126: *
127: * @param in Current input entity.
128: * @see #endDTD()
129: */
130: public void startDTD(InputEntity in) throws SAXException;
131:
132: /**
133: * Receive notification of the end of a DTD. The parser will invoke
134: * this method only once.
135: *
136: * @throws SAXException
137: * @see #startDTD(InputEntity)
138: */
139: public void endDTD() throws SAXException;
140:
141: /**
142: * Receive notification that a comment has been read.
143: * <p/>
144: * <P> Note that processing instructions are the mechanism designed
145: * to hold information for consumption by applications, not comments.
146: * XML systems may rely on applications being able to access information
147: * found in processing instructions; this is not true of comments, which
148: * are typically discarded.
149: *
150: * @param text the text within the comment delimiters.
151: * @throws SAXException
152: */
153: public void comment(String text) throws SAXException;
154:
155: /**
156: * Receive notification of character data.
157: * <p/>
158: * <p>The Parser will call this method to report each chunk of
159: * character data. SAX parsers may return all contiguous character
160: * data in a single chunk, or they may split it into several
161: * chunks; however, all of the characters in any single event
162: * must come from the same external entity, so that the Locator
163: * provides useful information.</p>
164: * <p/>
165: * <p>The application must not attempt to read from the array
166: * outside of the specified range.</p>
167: * <p/>
168: * <p>Note that some parsers will report whitespace using the
169: * ignorableWhitespace() method rather than this one (validating
170: * parsers must do so).</p>
171: *
172: * @param ch The characters from the DTD.
173: * @param start The start position in the array.
174: * @param length The number of characters to read from the array.
175: * @throws SAXException
176: * @see #ignorableWhitespace(char[], int, int)
177: */
178: public void characters(char ch[], int start, int length)
179: throws SAXException;
180:
181: /**
182: * Receive notification of ignorable whitespace in element content.
183: * <p/>
184: * <p>Validating Parsers must use this method to report each chunk
185: * of ignorable whitespace (see the W3C XML 1.0 recommendation,
186: * section 2.10): non-validating parsers may also use this method
187: * if they are capable of parsing and using content models.</p>
188: * <p/>
189: * <p>SAX parsers may return all contiguous whitespace in a single
190: * chunk, or they may split it into several chunks; however, all of
191: * the characters in any single event must come from the same
192: * external entity, so that the Locator provides useful
193: * information.</p>
194: * <p/>
195: * <p>The application must not attempt to read from the array
196: * outside of the specified range.</p>
197: *
198: * @param ch The characters from the DTD.
199: * @param start The start position in the array.
200: * @param length The number of characters to read from the array.
201: * @throws SAXException
202: * @see #characters(char[], int, int)
203: */
204: public void ignorableWhitespace(char ch[], int start, int length)
205: throws SAXException;
206:
207: /**
208: * Receive notification that a CDATA section is beginning. Data in a
209: * CDATA section is is reported through the appropriate event, either
210: * <em>characters()</em> or <em>ignorableWhitespace</em>.
211: *
212: * @throws SAXException
213: * @see #endCDATA()
214: */
215: public void startCDATA() throws SAXException;
216:
217: /**
218: * Receive notification that the CDATA section finished.
219: *
220: * @throws SAXException
221: * @see #startCDATA()
222: */
223: public void endCDATA() throws SAXException;
224:
225: public void fatalError(SAXParseException e) throws SAXException;
226:
227: public void error(SAXParseException e) throws SAXException;
228:
229: public void warning(SAXParseException err) throws SAXException;
230:
231: public final short CONTENT_MODEL_EMPTY = 0;
232: public final short CONTENT_MODEL_ANY = 1;
233: public final short CONTENT_MODEL_MIXED = 2;
234: public final short CONTENT_MODEL_CHILDREN = 3;
235:
236: /**
237: * receives notification that parsing of content model is beginning.
238: *
239: * @param elementName name of the element whose content model is going to be defined.
240: * @param contentModelType {@link #CONTENT_MODEL_EMPTY}
241: * this element has EMPTY content model. This notification
242: * will be immediately followed by the corresponding endContentModel.
243: * {@link #CONTENT_MODEL_ANY}
244: * this element has ANY content model. This notification
245: * will be immediately followed by the corresponding endContentModel.
246: * {@link #CONTENT_MODEL_MIXED}
247: * this element has mixed content model. #PCDATA will not be reported.
248: * each child element will be reported by mixedElement method.
249: * {@link #CONTENT_MODEL_CHILDREN}
250: * this elemen has child content model. The actual content model will
251: * be reported by childElement, startModelGroup, endModelGroup, and
252: * connector methods. Possible call sequences are:
253: * <p/>
254: * START := MODEL_GROUP
255: * MODEL_GROUP := startModelGroup TOKEN (connector TOKEN)* endModelGroup
256: * TOKEN := childElement
257: * | MODEL_GROUP
258: */
259: public void startContentModel(String elementName,
260: short contentModelType) throws SAXException;
261:
262: /**
263: * receives notification that parsing of content model is finished.
264: */
265: public void endContentModel(String elementName,
266: short contentModelType) throws SAXException;
267:
268: public final short USE_NORMAL = 0;
269: public final short USE_IMPLIED = 1;
270: public final short USE_FIXED = 2;
271: public final short USE_REQUIRED = 3;
272:
273: /**
274: * For each entry in an ATTLIST declaration,
275: * this event will be fired.
276: * <p/>
277: * <p/>
278: * DTD allows the same attributes to be declared more than
279: * once, and in that case the first one wins. I think
280: * this method will be only fired for the first one,
281: * but I need to check.
282: */
283: public void attributeDecl(String elementName, String attributeName,
284: String attributeType, String[] enumeration,
285: short attributeUse, String defaultValue)
286: throws SAXException;
287:
288: public void childElement(String elementName, short occurence)
289: throws SAXException;
290:
291: /**
292: * receives notification of child element of mixed content model.
293: * this method is called for each child element.
294: *
295: * @see #startContentModel(String, short)
296: */
297: public void mixedElement(String elementName) throws SAXException;
298:
299: public void startModelGroup() throws SAXException;
300:
301: public void endModelGroup(short occurence) throws SAXException;
302:
303: public final short CHOICE = 0;
304: public final short SEQUENCE = 1;
305:
306: /**
307: * Connectors in one model group is guaranteed to be the same.
308: * <p/>
309: * <p/>
310: * IOW, you'll never see an event sequence like (a|b,c)
311: *
312: * @return {@link #CHOICE} or {@link #SEQUENCE}.
313: */
314: public void connector(short connectorType) throws SAXException;
315:
316: public final short OCCURENCE_ZERO_OR_MORE = 0;
317: public final short OCCURENCE_ONE_OR_MORE = 1;
318: public final short OCCURENCE_ZERO_OR_ONE = 2;
319: public final short OCCURENCE_ONCE = 3;
320: }
|