PageRenderTime 41ms CodeModel.GetById 13ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-2-pre4/com/microstar/xml/XmlHandler.java

#
Java | 243 lines | 29 code | 28 blank | 186 comment | 0 complexity | a3440e30c40793387f6e777ee7ce9ab5 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
  1. // XmlHandler.java: the callback interface.
  2. // NO WARRANTY! See README, and copyright below.
  3. // $Id: XmlHandler.java 3792 2001-09-02 05:37:43Z spestov $
  4. package com.microstar.xml;
  5. /**
  6. * XML Processing Interface.
  7. * <p>Whenever you parse an XML document, you must provide an object
  8. * from a class that implements this interface to receive the parsing
  9. * events.
  10. * <p>If you do not want to implement this entire interface, you
  11. * can extend the <code>HandlerBase</code> convenience class and
  12. * then implement only what you need.
  13. * <p>If you are using SAX, you should implement the SAX handler
  14. * interfaces rather than this one.
  15. * @author Copyright (c) 1997, 1998 by Microstar Software Ltd.
  16. * @author written by David Megginson &lt;dmeggins@microstar.com&gt;
  17. * @version 1.1
  18. * @see XmlParser
  19. * @see HandlerBase
  20. * @see org.xml.sax.EntityHandler
  21. * @see org.xml.sax.DocumentHandler
  22. * @see org.xml.sax.ErrorHandler
  23. */
  24. public interface XmlHandler {
  25. /**
  26. * Start the document.
  27. * <p>&AElig;lfred will call this method just before it
  28. * attempts to read the first entity (the root of the document).
  29. * It is guaranteed that this will be the first method called.
  30. * @exception java.lang.Exception The handler may throw any exception.
  31. * @see #endDocument
  32. */
  33. public void startDocument ()
  34. throws java.lang.Exception;
  35. /**
  36. * End the document.
  37. * <p>&AElig;lfred will call this method once, when it has
  38. * finished parsing the XML document.
  39. * It is guaranteed that this will be the last method called.
  40. * @exception java.lang.Exception The handler may throw any exception.
  41. * @see #startDocument
  42. */
  43. public void endDocument ()
  44. throws java.lang.Exception;
  45. /**
  46. * Resolve an External Entity.
  47. * <p>Give the handler a chance to redirect external entities
  48. * to different URIs. &AElig;lfred will call this method for the
  49. * top-level document entity, for external text (XML) entities,
  50. * and the external DTD subset (if any).
  51. * @param publicId The public identifier, or null if none was supplied.
  52. * @param systemId The system identifier.
  53. * @return The replacement system identifier, or null to use
  54. * the default.
  55. * @exception java.lang.Exception The handler may throw any exception.
  56. * @see #startExternalEntity
  57. * @see #endExternalEntity
  58. */
  59. public Object resolveEntity (String publicId, String systemId)
  60. throws java.lang.Exception;
  61. /**
  62. * Begin an external entity.
  63. * <p>&AElig;lfred will call this method at the beginning of
  64. * each external entity, including the top-level document entity
  65. * and the external DTD subset (if any).
  66. * <p>If necessary, you can use this method to track the location
  67. * of the current entity so that you can resolve relative URIs
  68. * correctly.
  69. * @param systemId The URI of the external entity that is starting.
  70. * @exception java.lang.Exception The handler may throw any exception.
  71. * @see #endExternalEntity
  72. * @see #resolveEntity
  73. */
  74. public void startExternalEntity (String systemId)
  75. throws java.lang.Exception;
  76. /**
  77. * End an external entity.
  78. * <p>&AElig;lfred will call this method at the end of
  79. * each external entity, including the top-level document entity
  80. * and the external DTD subset.
  81. * <p>If necessary, you can use this method to track the location
  82. * of the current entity so that you can resolve relative URIs
  83. * correctly.
  84. * @param systemId The URI of the external entity that is ending.
  85. * @exception java.lang.Exception The handler may throw any exception.
  86. * @see #startExternalEntity
  87. * @see #resolveEntity
  88. */
  89. public void endExternalEntity (String systemId)
  90. throws java.lang.Exception;
  91. /**
  92. * Document type declaration.
  93. * <p>&AElig;lfred will call this method when or if it encounters
  94. * the document type (DOCTYPE) declaration.
  95. * <p>Please note that the public and system identifiers will
  96. * not always be a reliable indication of the DTD in use.
  97. * @param name The document type name.
  98. * @param publicId The public identifier, or null if unspecified.
  99. * @param systemId The system identifier, or null if unspecified.
  100. * @exception java.lang.Exception The handler may throw any exception.
  101. */
  102. public void doctypeDecl (String name, String publicId, String systemId)
  103. throws java.lang.Exception;
  104. /**
  105. * Attribute.
  106. * <p>&AElig;lfred will call this method once for each attribute
  107. * (specified or defaulted) before reporting a startElement event.
  108. * It is up to your handler to collect the attributes, if
  109. * necessary.
  110. * <p>You may use XmlParser.getAttributeType() to find the attribute's
  111. * declared type.
  112. * @param name The name of the attribute.
  113. * @param type The type of the attribute (see below).
  114. * @param value The value of the attribute, or null if the attribute
  115. * is <code>#IMPLIED</code>.
  116. * @param isSpecified True if the value was specified, false if it
  117. * was defaulted from the DTD.
  118. * @exception java.lang.Exception The handler may throw any exception.
  119. * @see #startElement
  120. * @see XmlParser#declaredAttributes
  121. * @see XmlParser#getAttributeType
  122. * @see XmlParser#getAttributeDefaultValue
  123. */
  124. public void attribute (String aname, String value, boolean isSpecified)
  125. throws java.lang.Exception;
  126. /**
  127. * Start an element.
  128. * <p>&AElig;lfred will call this method at the beginning of each
  129. * element. By the time this is called, all of the attributes
  130. * for the element will already have been reported using the
  131. * <code>attribute</code> method.
  132. * @param elname The element type name.
  133. * @exception java.lang.Exception The handler may throw any exception.
  134. * @see #attribute
  135. * @see #endElement
  136. * @see XmlParser#declaredElements
  137. * @see XmlParser#getElementContentType
  138. */
  139. public void startElement (String elname)
  140. throws java.lang.Exception;
  141. /**
  142. * End an element.
  143. * <p>&AElig;lfred will call this method at the end of each element
  144. * (including EMPTY elements).
  145. * @param elname The element type name.
  146. * @exception java.lang.Exception The handler may throw any exception.
  147. * @see #startElement
  148. * @see XmlParser#declaredElements
  149. * @see XmlParser#getElementContentType
  150. */
  151. public void endElement (String elname)
  152. throws java.lang.Exception;
  153. /**
  154. * Character data.
  155. * <p>&AElig;lfred will call this method once for each chunk of
  156. * character data found in the contents of elements. Note that
  157. * the parser may break up a long sequence of characters into
  158. * smaller chunks and call this method once for each chunk.
  159. * <p>Do <em>not</em> attempt to read more than <var>length</var>
  160. * characters from the array, or to read before the
  161. * <var>start</var> position.
  162. * @param ch The character data.
  163. * @param start The starting position in the array.
  164. * @param length The number of characters available.
  165. * @exception java.lang.Exception The handler may throw any exception.
  166. */
  167. public void charData (char ch[], int start, int length)
  168. throws java.lang.Exception;
  169. /**
  170. * Ignorable whitespace.
  171. * <p>&AElig;lfred will call this method once for each sequence
  172. * of ignorable whitespace in element content (never in mixed content).
  173. * <p>For details, see section 2.10 of the XML 1.0 recommendation.
  174. * <p>Do <em>not</em> attempt to read more than <var>length</var>
  175. * characters from the array or to read before the <var>start</var>
  176. * position.
  177. * @param ch The literal whitespace characters.
  178. * @param start The starting position in the array.
  179. * @param length The number of whitespace characters available.
  180. * @exception java.lang.Exception The handler may throw any exception.
  181. */
  182. public void ignorableWhitespace (char ch[], int start, int length)
  183. throws java.lang.Exception;
  184. /**
  185. * Processing instruction.
  186. * <p>&AElig;lfred will call this method once for each
  187. * processing instruction. Note that processing instructions may
  188. * appear outside of the top-level element. The
  189. * @param target The target (the name at the start of the PI).
  190. * @param data The data, if any (the rest of the PI).
  191. * @exception java.lang.Exception The handler may throw any exception.
  192. */
  193. public void processingInstruction (String target, String data)
  194. throws java.lang.Exception;
  195. /**
  196. * Fatal XML parsing error.
  197. * <p>&AElig;lfred will call this method whenever it encounters
  198. * a serious error. The parser will attempt to continue past this
  199. * point so that you can find more possible error points, but if
  200. * this method is called you should assume that the document is
  201. * corrupt and you should not try to use its contents.
  202. * <p>Note that you can use the <code>XmlException</code> class
  203. * to encapsulate all of the information provided, though the
  204. * use of the class is not mandatory.
  205. * @param message The error message.
  206. * @param systemId The system identifier of the entity that
  207. * contains the error.
  208. * @param line The approximate line number of the error.
  209. * @param column The approximate column number of the error.
  210. * @exception java.lang.Exception The handler may throw any exception.
  211. * @see XmlException
  212. */
  213. public void error (String message, String systemId, int line, int column)
  214. throws java.lang.Exception;
  215. }