001: // DeclHandler.java - Optional handler for DTD declaration events.
002: // http://www.saxproject.org
003: // Public Domain: no warranty.
004: // $Id: DeclHandler.java,v 1.1.1.1 2002/05/03 23:29:41 yuvalo Exp $
005:
006: package org.xml.sax.ext;
007:
008: import org.xml.sax.SAXException;
009:
010: /**
011: * SAX2 extension handler for DTD declaration events.
012: *
013: * <blockquote>
014: * <em>This module, both source code and documentation, is in the
015: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
016: * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
017: * for further information.
018: * </blockquote>
019: *
020: * <p>This is an optional extension handler for SAX2 to provide more
021: * complete information about DTD declarations in an XML document.
022: * XML readers are not required to recognize this handler, and it
023: * is not part of core-only SAX2 distributions.</p>
024: *
025: * <p>Note that data-related DTD declarations (unparsed entities and
026: * notations) are already reported through the {@link
027: * org.xml.sax.DTDHandler DTDHandler} interface.</p>
028: *
029: * <p>If you are using the declaration handler together with a lexical
030: * handler, all of the events will occur between the
031: * {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD} and the
032: * {@link org.xml.sax.ext.LexicalHandler#endDTD endDTD} events.</p>
033: *
034: * <p>To set the DeclHandler for an XML reader, use the
035: * {@link org.xml.sax.XMLReader#setProperty setProperty} method
036: * with the property name
037: * <code>http://xml.org/sax/properties/declaration-handler</code>
038: * and an object implementing this interface (or null) as the value.
039: * If the reader does not report declaration events, it will throw a
040: * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
041: * when you attempt to register the handler.</p>
042: *
043: * @since SAX 2.0 (extensions 1.0)
044: * @author David Megginson
045: * @version 2.0.1 (sax2r2)
046: */
047: public interface DeclHandler {
048:
049: /**
050: * Report an element type declaration.
051: *
052: * <p>The content model will consist of the string "EMPTY", the
053: * string "ANY", or a parenthesised group, optionally followed
054: * by an occurrence indicator. The model will be normalized so
055: * that all parameter entities are fully resolved and all whitespace
056: * is removed,and will include the enclosing parentheses. Other
057: * normalization (such as removing redundant parentheses or
058: * simplifying occurrence indicators) is at the discretion of the
059: * parser.</p>
060: *
061: * @param name The element type name.
062: * @param model The content model as a normalized string.
063: * @exception SAXException The application may raise an exception.
064: */
065: public abstract void elementDecl(String name, String model)
066: throws SAXException;
067:
068: /**
069: * Report an attribute type declaration.
070: *
071: * <p>Only the effective (first) declaration for an attribute will
072: * be reported. The type will be one of the strings "CDATA",
073: * "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY",
074: * "ENTITIES", a parenthesized token group with
075: * the separator "|" and all whitespace removed, or the word
076: * "NOTATION" followed by a space followed by a parenthesized
077: * token group with all whitespace removed.</p>
078: *
079: * <p>The value will be the value as reported to applications,
080: * appropriately normalized and with entity and character
081: * references expanded. </p>
082: *
083: * @param eName The name of the associated element.
084: * @param aName The name of the attribute.
085: * @param type A string representing the attribute type.
086: * @param mode A string representing the attribute defaulting mode
087: * ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if
088: * none of these applies.
089: * @param value A string representing the attribute's default value,
090: * or null if there is none.
091: * @exception SAXException The application may raise an exception.
092: */
093: public abstract void attributeDecl(String eName, String aName,
094: String type, String mode, String value) throws SAXException;
095:
096: /**
097: * Report an internal entity declaration.
098: *
099: * <p>Only the effective (first) declaration for each entity
100: * will be reported. All parameter entities in the value
101: * will be expanded, but general entities will not.</p>
102: *
103: * @param name The name of the entity. If it is a parameter
104: * entity, the name will begin with '%'.
105: * @param value The replacement text of the entity.
106: * @exception SAXException The application may raise an exception.
107: * @see #externalEntityDecl
108: * @see org.xml.sax.DTDHandler#unparsedEntityDecl
109: */
110: public abstract void internalEntityDecl(String name, String value)
111: throws SAXException;
112:
113: /**
114: * Report a parsed external entity declaration.
115: *
116: * <p>Only the effective (first) declaration for each entity
117: * will be reported.</p>
118: *
119: * @param name The name of the entity. If it is a parameter
120: * entity, the name will begin with '%'.
121: * @param publicId The declared public identifier of the entity, or
122: * null if none was declared.
123: * @param systemId The declared system identifier of the entity.
124: * @exception SAXException The application may raise an exception.
125: * @see #internalEntityDecl
126: * @see org.xml.sax.DTDHandler#unparsedEntityDecl
127: */
128: public abstract void externalEntityDecl(String name,
129: String publicId, String systemId) throws SAXException;
130:
131: }
132:
133: // end of DeclHandler.java
|