View Javadoc
1   /*
2    * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.xml.transform.sax;
27  
28  import javax.xml.transform.*;
29  
30  import org.xml.sax.XMLFilter;
31  
32  /**
33   * This class extends TransformerFactory to provide SAX-specific
34   * factory methods.  It provides two types of ContentHandlers,
35   * one for creating Transformers, the other for creating Templates
36   * objects.
37   *
38   * <p>If an application wants to set the ErrorHandler or EntityResolver
39   * for an XMLReader used during a transformation, it should use a URIResolver
40   * to return the SAXSource which provides (with getXMLReader) a reference to
41   * the XMLReader.</p>
42   */
43  public abstract class SAXTransformerFactory extends TransformerFactory {
44  
45      /** If {@link javax.xml.transform.TransformerFactory#getFeature}
46       * returns true when passed this value as an argument,
47       * the TransformerFactory returned from
48       * {@link javax.xml.transform.TransformerFactory#newInstance} may
49       * be safely cast to a SAXTransformerFactory.
50       */
51      public static final String FEATURE =
52          "http://javax.xml.transform.sax.SAXTransformerFactory/feature";
53  
54      /** If {@link javax.xml.transform.TransformerFactory#getFeature}
55       * returns true when passed this value as an argument,
56       * the {@link #newXMLFilter(Source src)}
57       * and {@link #newXMLFilter(Templates templates)} methods are supported.
58       */
59      public static final String FEATURE_XMLFILTER =
60          "http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter";
61  
62      /**
63       * The default constructor is protected on purpose.
64       */
65      protected SAXTransformerFactory() {}
66  
67      /**
68       * Get a TransformerHandler object that can process SAX
69       * ContentHandler events into a Result, based on the transformation
70       * instructions specified by the argument.
71       *
72       * @param src The Source of the transformation instructions.
73       *
74       * @return TransformerHandler ready to transform SAX events.
75       *
76       * @throws TransformerConfigurationException If for some reason the
77       * TransformerHandler can not be created.
78       */
79      public abstract TransformerHandler newTransformerHandler(Source src)
80          throws TransformerConfigurationException;
81  
82      /**
83       * Get a TransformerHandler object that can process SAX
84       * ContentHandler events into a Result, based on the Templates argument.
85       *
86       * @param templates The compiled transformation instructions.
87       *
88       * @return TransformerHandler ready to transform SAX events.
89       *
90       * @throws TransformerConfigurationException If for some reason the
91       * TransformerHandler can not be created.
92       */
93      public abstract TransformerHandler newTransformerHandler(
94          Templates templates) throws TransformerConfigurationException;
95  
96      /**
97       * Get a TransformerHandler object that can process SAX
98       * ContentHandler events into a Result. The transformation
99       * is defined as an identity (or copy) transformation, for example
100      * to copy a series of SAX parse events into a DOM tree.
101      *
102      * @return A non-null reference to a TransformerHandler, that may
103      * be used as a ContentHandler for SAX parse events.
104      *
105      * @throws TransformerConfigurationException If for some reason the
106      * TransformerHandler cannot be created.
107      */
108     public abstract TransformerHandler newTransformerHandler()
109         throws TransformerConfigurationException;
110 
111     /**
112      * Get a TemplatesHandler object that can process SAX
113      * ContentHandler events into a Templates object.
114      *
115      * @return A non-null reference to a TransformerHandler, that may
116      * be used as a ContentHandler for SAX parse events.
117      *
118      * @throws TransformerConfigurationException If for some reason the
119      * TemplatesHandler cannot be created.
120      */
121     public abstract TemplatesHandler newTemplatesHandler()
122         throws TransformerConfigurationException;
123 
124     /**
125      * Create an XMLFilter that uses the given Source as the
126      * transformation instructions.
127      *
128      * @param src The Source of the transformation instructions.
129      *
130      * @return An XMLFilter object, or null if this feature is not supported.
131      *
132      * @throws TransformerConfigurationException If for some reason the
133      * TemplatesHandler cannot be created.
134      */
135     public abstract XMLFilter newXMLFilter(Source src)
136         throws TransformerConfigurationException;
137 
138     /**
139      * Create an XMLFilter, based on the Templates argument..
140      *
141      * @param templates The compiled transformation instructions.
142      *
143      * @return An XMLFilter object, or null if this feature is not supported.
144      *
145      * @throws TransformerConfigurationException If for some reason the
146      * TemplatesHandler cannot be created.
147      */
148     public abstract XMLFilter newXMLFilter(Templates templates)
149         throws TransformerConfigurationException;
150 }