1. // $Id: SAXTransformerFactory.java,v 1.2.22.1 2004/07/13 22:27:50 jsuttor Exp $
  2. /*
  3. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  4. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  5. */
  6. /*
  7. * @(#)SAXTransformerFactory.java 1.13 04/07/13
  8. */
  9. package javax.xml.transform.sax;
  10. import javax.xml.transform.*;
  11. import org.xml.sax.XMLFilter;
  12. /**
  13. * This class extends TransformerFactory to provide SAX-specific
  14. * factory methods. It provides two types of ContentHandlers,
  15. * one for creating Transformers, the other for creating Templates
  16. * objects.
  17. *
  18. * <p>If an application wants to set the ErrorHandler or EntityResolver
  19. * for an XMLReader used during a transformation, it should use a URIResolver
  20. * to return the SAXSource which provides (with getXMLReader) a reference to
  21. * the XMLReader.</p>
  22. */
  23. public abstract class SAXTransformerFactory extends TransformerFactory {
  24. /** If {@link javax.xml.transform.TransformerFactory#getFeature}
  25. * returns true when passed this value as an argument,
  26. * the TransformerFactory returned from
  27. * {@link javax.xml.transform.TransformerFactory#newInstance} may
  28. * be safely cast to a SAXTransformerFactory.
  29. */
  30. public static final String FEATURE =
  31. "http://javax.xml.transform.sax.SAXTransformerFactory/feature";
  32. /** If {@link javax.xml.transform.TransformerFactory#getFeature}
  33. * returns true when passed this value as an argument,
  34. * the {@link #newXMLFilter(Source src)}
  35. * and {@link #newXMLFilter(Templates templates)} methods are supported.
  36. */
  37. public static final String FEATURE_XMLFILTER =
  38. "http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter";
  39. /**
  40. * The default constructor is protected on purpose.
  41. */
  42. protected SAXTransformerFactory() {}
  43. /**
  44. * Get a TransformerHandler object that can process SAX
  45. * ContentHandler events into a Result, based on the transformation
  46. * instructions specified by the argument.
  47. *
  48. * @param src The Source of the transformation instructions.
  49. *
  50. * @return TransformerHandler ready to transform SAX events.
  51. *
  52. * @throws TransformerConfigurationException If for some reason the
  53. * TransformerHandler can not be created.
  54. */
  55. public abstract TransformerHandler newTransformerHandler(Source src)
  56. throws TransformerConfigurationException;
  57. /**
  58. * Get a TransformerHandler object that can process SAX
  59. * ContentHandler events into a Result, based on the Templates argument.
  60. *
  61. * @param templates The compiled transformation instructions.
  62. *
  63. * @return TransformerHandler ready to transform SAX events.
  64. *
  65. * @throws TransformerConfigurationException If for some reason the
  66. * TransformerHandler can not be created.
  67. */
  68. public abstract TransformerHandler newTransformerHandler(
  69. Templates templates) throws TransformerConfigurationException;
  70. /**
  71. * Get a TransformerHandler object that can process SAX
  72. * ContentHandler events into a Result. The transformation
  73. * is defined as an identity (or copy) transformation, for example
  74. * to copy a series of SAX parse events into a DOM tree.
  75. *
  76. * @return A non-null reference to a TransformerHandler, that may
  77. * be used as a ContentHandler for SAX parse events.
  78. *
  79. * @throws TransformerConfigurationException If for some reason the
  80. * TransformerHandler cannot be created.
  81. */
  82. public abstract TransformerHandler newTransformerHandler()
  83. throws TransformerConfigurationException;
  84. /**
  85. * Get a TemplatesHandler object that can process SAX
  86. * ContentHandler events into a Templates object.
  87. *
  88. * @return A non-null reference to a TransformerHandler, that may
  89. * be used as a ContentHandler for SAX parse events.
  90. *
  91. * @throws TransformerConfigurationException If for some reason the
  92. * TemplatesHandler cannot be created.
  93. */
  94. public abstract TemplatesHandler newTemplatesHandler()
  95. throws TransformerConfigurationException;
  96. /**
  97. * Create an XMLFilter that uses the given Source as the
  98. * transformation instructions.
  99. *
  100. * @param src The Source of the transformation instructions.
  101. *
  102. * @return An XMLFilter object, or null if this feature is not supported.
  103. *
  104. * @throws TransformerConfigurationException If for some reason the
  105. * TemplatesHandler cannot be created.
  106. */
  107. public abstract XMLFilter newXMLFilter(Source src)
  108. throws TransformerConfigurationException;
  109. /**
  110. * Create an XMLFilter, based on the Templates argument..
  111. *
  112. * @param templates The compiled transformation instructions.
  113. *
  114. * @return An XMLFilter object, or null if this feature is not supported.
  115. *
  116. * @throws TransformerConfigurationException If for some reason the
  117. * TemplatesHandler cannot be created.
  118. */
  119. public abstract XMLFilter newXMLFilter(Templates templates)
  120. throws TransformerConfigurationException;
  121. }