1. // DeclHandler.java - Optional handler for DTD declaration events.
  2. // Public Domain: no warranty.
  3. // $Id: DeclHandler.java,v 1.1 2001/05/20 03:12:57 curcuru Exp $
  4. package org.xml.sax.ext;
  5. import org.xml.sax.SAXException;
  6. /**
  7. * SAX2 extension handler for DTD declaration events.
  8. *
  9. * <blockquote>
  10. * <em>This module, both source code and documentation, is in the
  11. * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  12. * </blockquote>
  13. *
  14. * <p>This is an optional extension handler for SAX2 to provide
  15. * information about DTD declarations in an XML document. XML
  16. * readers are not required to support this handler, and this
  17. * handler is not included in the core SAX2 distribution.</p>
  18. *
  19. * <p>Note that data-related DTD declarations (unparsed entities and
  20. * notations) are already reported through the {@link
  21. * org.xml.sax.DTDHandler DTDHandler} interface.</p>
  22. *
  23. * <p>If you are using the declaration handler together with a lexical
  24. * handler, all of the events will occur between the
  25. * {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD} and the
  26. * {@link org.xml.sax.ext.LexicalHandler#endDTD endDTD} events.</p>
  27. *
  28. * <p>To set the DeclHandler for an XML reader, use the
  29. * {@link org.xml.sax.XMLReader#setProperty setProperty} method
  30. * with the propertyId "http://xml.org/sax/properties/declaration-handler".
  31. * If the reader does not support declaration events, it will throw a
  32. * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
  33. * or a
  34. * {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException}
  35. * when you attempt to register the handler.</p>
  36. *
  37. * @since 1.0
  38. * @author David Megginson,
  39. * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
  40. * @version 1.0
  41. * @see org.xml.sax.XMLReader
  42. */
  43. public interface DeclHandler
  44. {
  45. /**
  46. * Report an element type declaration.
  47. *
  48. * <p>The content model will consist of the string "EMPTY", the
  49. * string "ANY", or a parenthesised group, optionally followed
  50. * by an occurrence indicator. The model will be normalized so
  51. * that all parameter entities are fully resolved and all whitespace
  52. * is removed,and will include the enclosing parentheses. Other
  53. * normalization (such as removing redundant parentheses or
  54. * simplifying occurrence indicators) is at the discretion of the
  55. * parser.</p>
  56. *
  57. * @param name The element type name.
  58. * @param model The content model as a normalized string.
  59. * @exception SAXException The application may raise an exception.
  60. */
  61. public abstract void elementDecl (String name, String model)
  62. throws SAXException;
  63. /**
  64. * Report an attribute type declaration.
  65. *
  66. * <p>Only the effective (first) declaration for an attribute will
  67. * be reported. The type will be one of the strings "CDATA",
  68. * "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY",
  69. * "ENTITIES", a parenthesized token group with
  70. * the separator "|" and all whitespace removed, or the word
  71. * "NOTATION" followed by a space followed by a parenthesized
  72. * token group with all whitespace removed.</p>
  73. *
  74. * <p>Any parameter entities in the attribute value will be
  75. * expanded, but general entities will not.</p>
  76. *
  77. * @param eName The name of the associated element.
  78. * @param aName The name of the attribute.
  79. * @param type A string representing the attribute type.
  80. * @param valueDefault A string representing the attribute default
  81. * ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if
  82. * none of these applies.
  83. * @param value A string representing the attribute's default value,
  84. * or null if there is none.
  85. * @exception SAXException The application may raise an exception.
  86. */
  87. public abstract void attributeDecl (String eName,
  88. String aName,
  89. String type,
  90. String valueDefault,
  91. String value)
  92. throws SAXException;
  93. /**
  94. * Report an internal entity declaration.
  95. *
  96. * <p>Only the effective (first) declaration for each entity
  97. * will be reported. All parameter entities in the value
  98. * will be expanded, but general entities will not.</p>
  99. *
  100. * @param name The name of the entity. If it is a parameter
  101. * entity, the name will begin with '%'.
  102. * @param value The replacement text of the entity.
  103. * @exception SAXException The application may raise an exception.
  104. * @see #externalEntityDecl
  105. * @see org.xml.sax.DTDHandler#unparsedEntityDecl
  106. */
  107. public abstract void internalEntityDecl (String name, String value)
  108. throws SAXException;
  109. /**
  110. * Report a parsed external entity declaration.
  111. *
  112. * <p>Only the effective (first) declaration for each entity
  113. * will be reported.</p>
  114. *
  115. * @param name The name of the entity. If it is a parameter
  116. * entity, the name will begin with '%'.
  117. * @param publicId The declared public identifier of the entity, or
  118. * null if none was declared.
  119. * @param systemId The declared system identifier of the entity.
  120. * @exception SAXException The application may raise an exception.
  121. * @see #internalEntityDecl
  122. * @see org.xml.sax.DTDHandler#unparsedEntityDecl
  123. */
  124. public abstract void externalEntityDecl (String name, String publicId,
  125. String systemId)
  126. throws SAXException;
  127. }
  128. // end of DeclHandler.java