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.XMLDTDSource;
021:
022: /**
023: * The DTD handler interface defines callback methods to report
024: * information items in the DTD of an XML document. Parser components
025: * interested in DTD information implement this interface and are
026: * registered as the DTD handler on the DTD source.
027: *
028: * @see XMLDTDContentModelHandler
029: *
030: * @author Andy Clark, IBM
031: *
032: * @version $Id: XMLDTDHandler.java 447247 2006-09-18 05:23:52Z mrglavas $
033: */
034: public interface XMLDTDHandler {
035:
036: //
037: // Constants
038: //
039:
040: /**
041: * Conditional section: INCLUDE.
042: *
043: * @see #CONDITIONAL_IGNORE
044: */
045: public static final short CONDITIONAL_INCLUDE = 0;
046:
047: /**
048: * Conditional section: IGNORE.
049: *
050: * @see #CONDITIONAL_INCLUDE
051: */
052: public static final short CONDITIONAL_IGNORE = 1;
053:
054: //
055: // XMLDTDHandler methods
056: //
057:
058: /**
059: * The start of the DTD.
060: *
061: * @param locator The document locator, or null if the document
062: * location cannot be reported during the parsing of
063: * the document DTD. However, it is <em>strongly</em>
064: * recommended that a locator be supplied that can
065: * at least report the base system identifier of the
066: * DTD.
067: * @param augmentations Additional information that may include infoset
068: * augmentations.
069: *
070: * @throws XNIException Thrown by handler to signal an error.
071: */
072: public void startDTD(XMLLocator locator, Augmentations augmentations)
073: throws XNIException;
074:
075: /**
076: * This method notifies of the start of a parameter entity. The parameter
077: * entity name start with a '%' character.
078: *
079: * @param name The name of the parameter entity.
080: * @param identifier The resource identifier.
081: * @param encoding The auto-detected IANA encoding name of the entity
082: * stream. This value will be null in those situations
083: * where the entity encoding is not auto-detected (e.g.
084: * internal parameter entities).
085: * @param augmentations Additional information that may include infoset
086: * augmentations.
087: *
088: * @throws XNIException Thrown by handler to signal an error.
089: */
090: public void startParameterEntity(String name,
091: XMLResourceIdentifier identifier, String encoding,
092: Augmentations augmentations) throws XNIException;
093:
094: /**
095: * Notifies of the presence of a TextDecl line in an entity. If present,
096: * this method will be called immediately following the startEntity call.
097: * <p>
098: * <strong>Note:</strong> This method is only called for external
099: * parameter entities referenced in the DTD.
100: *
101: * @param version The XML version, or null if not specified.
102: * @param encoding The IANA encoding name of the entity.
103: * @param augmentations Additional information that may include infoset
104: * augmentations.
105: *
106: * @throws XNIException Thrown by handler to signal an error.
107: */
108: public void textDecl(String version, String encoding,
109: Augmentations augmentations) throws XNIException;
110:
111: /**
112: * This method notifies the end of a parameter entity. Parameter entity
113: * names begin with a '%' character.
114: *
115: * @param name The name of the parameter entity.
116: * @param augmentations Additional information that may include infoset
117: * augmentations.
118: *
119: * @throws XNIException Thrown by handler to signal an error.
120: */
121: public void endParameterEntity(String name,
122: Augmentations augmentations) throws XNIException;
123:
124: /**
125: * The start of the DTD external subset.
126: *
127: * @param identifier The resource identifier.
128: * @param augmentations
129: * Additional information that may include infoset
130: * augmentations.
131: * @exception XNIException
132: * Thrown by handler to signal an error.
133: */
134: public void startExternalSubset(XMLResourceIdentifier identifier,
135: Augmentations augmentations) throws XNIException;
136:
137: /**
138: * The end of the DTD external subset.
139: *
140: * @param augmentations Additional information that may include infoset
141: * augmentations.
142: *
143: * @throws XNIException Thrown by handler to signal an error.
144: */
145: public void endExternalSubset(Augmentations augmentations)
146: throws XNIException;
147:
148: /**
149: * A comment.
150: *
151: * @param text The text in the comment.
152: * @param augmentations Additional information that may include infoset
153: * augmentations.
154: *
155: * @throws XNIException Thrown by application to signal an error.
156: */
157: public void comment(XMLString text, Augmentations augmentations)
158: throws XNIException;
159:
160: /**
161: * A processing instruction. Processing instructions consist of a
162: * target name and, optionally, text data. The data is only meaningful
163: * to the application.
164: * <p>
165: * Typically, a processing instruction's data will contain a series
166: * of pseudo-attributes. These pseudo-attributes follow the form of
167: * element attributes but are <strong>not</strong> parsed or presented
168: * to the application as anything other than text. The application is
169: * responsible for parsing the data.
170: *
171: * @param target The target.
172: * @param data The data or null if none specified.
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 processingInstruction(String target, XMLString data,
179: Augmentations augmentations) throws XNIException;
180:
181: /**
182: * An element declaration.
183: *
184: * @param name The name of the element.
185: * @param contentModel The element content model.
186: * @param augmentations Additional information that may include infoset
187: * augmentations.
188: *
189: * @throws XNIException Thrown by handler to signal an error.
190: */
191: public void elementDecl(String name, String contentModel,
192: Augmentations augmentations) throws XNIException;
193:
194: /**
195: * The start of an attribute list.
196: *
197: * @param elementName The name of the element that this attribute
198: * list is associated with.
199: * @param augmentations Additional information that may include infoset
200: * augmentations.
201: *
202: * @throws XNIException Thrown by handler to signal an error.
203: */
204: public void startAttlist(String elementName,
205: Augmentations augmentations) throws XNIException;
206:
207: /**
208: * An attribute declaration.
209: *
210: * @param elementName The name of the element that this attribute
211: * is associated with.
212: * @param attributeName The name of the attribute.
213: * @param type The attribute type. This value will be one of
214: * the following: "CDATA", "ENTITY", "ENTITIES",
215: * "ENUMERATION", "ID", "IDREF", "IDREFS",
216: * "NMTOKEN", "NMTOKENS", or "NOTATION".
217: * @param enumeration If the type has the value "ENUMERATION" or
218: * "NOTATION", this array holds the allowed attribute
219: * values; otherwise, this array is null.
220: * @param defaultType The attribute default type. This value will be
221: * one of the following: "#FIXED", "#IMPLIED",
222: * "#REQUIRED", or null.
223: * @param defaultValue The attribute default value, or null if no
224: * default value is specified.
225: * @param nonNormalizedDefaultValue The attribute default value with no normalization
226: * performed, or null if no default value is specified.
227: * @param augmentations Additional information that may include infoset
228: * augmentations.
229: *
230: * @throws XNIException Thrown by handler to signal an error.
231: */
232: public void attributeDecl(String elementName, String attributeName,
233: String type, String[] enumeration, String defaultType,
234: XMLString defaultValue,
235: XMLString nonNormalizedDefaultValue,
236: Augmentations augmentations) throws XNIException;
237:
238: /**
239: * The end of an attribute list.
240: *
241: * @param augmentations Additional information that may include infoset
242: * augmentations.
243: *
244: * @throws XNIException Thrown by handler to signal an error.
245: */
246: public void endAttlist(Augmentations augmentations)
247: throws XNIException;
248:
249: /**
250: * An internal entity declaration.
251: *
252: * @param name The name of the entity. Parameter entity names start with
253: * '%', whereas the name of a general entity is just the
254: * entity name.
255: * @param text The value of the entity.
256: * @param nonNormalizedText The non-normalized value of the entity. This
257: * value contains the same sequence of characters that was in
258: * the internal entity declaration, without any entity
259: * references expanded.
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 internalEntityDecl(String name, XMLString text,
266: XMLString nonNormalizedText, Augmentations augmentations)
267: throws XNIException;
268:
269: /**
270: * An external entity declaration.
271: *
272: * @param name The name of the entity. Parameter entity names start
273: * with '%', whereas the name of a general entity is just
274: * the entity name.
275: * @param identifier An object containing all location information
276: * pertinent to this external entity.
277: * @param augmentations Additional information that may include infoset
278: * augmentations.
279: *
280: * @throws XNIException Thrown by handler to signal an error.
281: */
282: public void externalEntityDecl(String name,
283: XMLResourceIdentifier identifier,
284: Augmentations augmentations) throws XNIException;
285:
286: /**
287: * An unparsed entity declaration.
288: *
289: * @param name The name of the entity.
290: * @param identifier An object containing all location information
291: * pertinent to this unparsed entity declaration.
292: * @param notation The name of the notation.
293: * @param augmentations Additional information that may include infoset
294: * augmentations.
295: *
296: * @throws XNIException Thrown by handler to signal an error.
297: */
298: public void unparsedEntityDecl(String name,
299: XMLResourceIdentifier identifier, String notation,
300: Augmentations augmentations) throws XNIException;
301:
302: /**
303: * A notation declaration
304: *
305: * @param name The name of the notation.
306: * @param identifier An object containing all location information
307: * pertinent to this notation.
308: * @param augmentations Additional information that may include infoset
309: * augmentations.
310: *
311: * @throws XNIException Thrown by handler to signal an error.
312: */
313: public void notationDecl(String name,
314: XMLResourceIdentifier identifier,
315: Augmentations augmentations) throws XNIException;
316:
317: /**
318: * The start of a conditional section.
319: *
320: * @param type The type of the conditional section. This value will
321: * either be CONDITIONAL_INCLUDE or CONDITIONAL_IGNORE.
322: * @param augmentations Additional information that may include infoset
323: * augmentations.
324: *
325: * @throws XNIException Thrown by handler to signal an error.
326: *
327: * @see #CONDITIONAL_INCLUDE
328: * @see #CONDITIONAL_IGNORE
329: */
330: public void startConditional(short type, Augmentations augmentations)
331: throws XNIException;
332:
333: /**
334: * Characters within an IGNORE conditional section.
335: *
336: * @param text The ignored text.
337: * @param augmentations Additional information that may include infoset
338: * augmentations.
339: *
340: * @throws XNIException Thrown by handler to signal an error.
341: */
342: public void ignoredCharacters(XMLString text,
343: Augmentations augmentations) throws XNIException;
344:
345: /**
346: * The end of a conditional section.
347: *
348: * @param augmentations Additional information that may include infoset
349: * augmentations.
350: *
351: * @throws XNIException Thrown by handler to signal an error.
352: */
353: public void endConditional(Augmentations augmentations)
354: throws XNIException;
355:
356: /**
357: * The end of the DTD.
358: *
359: * @param augmentations Additional information that may include infoset
360: * augmentations.
361: *
362: * @throws XNIException Thrown by handler to signal an error.
363: */
364: public void endDTD(Augmentations augmentations) throws XNIException;
365:
366: // set the source of this handler
367: public void setDTDSource(XMLDTDSource source);
368:
369: // return the source from which this handler derives its events
370: public XMLDTDSource getDTDSource();
371:
372: } // interface XMLDTDHandler
|