1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 // $Id: SAXTransformerFactory.java 446598 2006-09-15 12:55:40Z jeremias $
19
20 package javax.xml.transform.sax;
21
22 import javax.xml.transform;
23
24 import org.xml.sax.XMLFilter;
25
26 /**
27 * This class extends TransformerFactory to provide SAX-specific
28 * factory methods. It provides two types of ContentHandlers,
29 * one for creating Transformers, the other for creating Templates
30 * objects.
31 *
32 * <p>If an application wants to set the ErrorHandler or EntityResolver
33 * for an XMLReader used during a transformation, it should use a URIResolver
34 * to return the SAXSource which provides (with getXMLReader) a reference to
35 * the XMLReader.</p>
36 */
37 public abstract class SAXTransformerFactory extends TransformerFactory {
38
39 /** If {@link javax.xml.transform.TransformerFactory#getFeature}
40 * returns true when passed this value as an argument,
41 * the TransformerFactory returned from
42 * {@link javax.xml.transform.TransformerFactory#newInstance} may
43 * be safely cast to a SAXTransformerFactory.
44 */
45 public static final String FEATURE =
46 "http://javax.xml.transform.sax.SAXTransformerFactory/feature";
47
48 /** If {@link javax.xml.transform.TransformerFactory#getFeature}
49 * returns true when passed this value as an argument,
50 * the {@link #newXMLFilter(Source src)}
51 * and {@link #newXMLFilter(Templates templates)} methods are supported.
52 */
53 public static final String FEATURE_XMLFILTER =
54 "http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter";
55
56 /**
57 * The default constructor is protected on purpose.
58 */
59 protected SAXTransformerFactory() {}
60
61 /**
62 * Get a TransformerHandler object that can process SAX
63 * ContentHandler events into a Result, based on the transformation
64 * instructions specified by the argument.
65 *
66 * @param src The Source of the transformation instructions.
67 *
68 * @return TransformerHandler ready to transform SAX events.
69 *
70 * @throws TransformerConfigurationException If for some reason the
71 * TransformerHandler can not be created.
72 */
73 public abstract TransformerHandler newTransformerHandler(Source src)
74 throws TransformerConfigurationException;
75
76 /**
77 * Get a TransformerHandler object that can process SAX
78 * ContentHandler events into a Result, based on the Templates argument.
79 *
80 * @param templates The compiled transformation instructions.
81 *
82 * @return TransformerHandler ready to transform SAX events.
83 *
84 * @throws TransformerConfigurationException If for some reason the
85 * TransformerHandler can not be created.
86 */
87 public abstract TransformerHandler newTransformerHandler(
88 Templates templates) throws TransformerConfigurationException;
89
90 /**
91 * Get a TransformerHandler object that can process SAX
92 * ContentHandler events into a Result. The transformation
93 * is defined as an identity (or copy) transformation, for example
94 * to copy a series of SAX parse events into a DOM tree.
95 *
96 * @return A non-null reference to a TransformerHandler, that may
97 * be used as a ContentHandler for SAX parse events.
98 *
99 * @throws TransformerConfigurationException If for some reason the
100 * TransformerHandler cannot be created.
101 */
102 public abstract TransformerHandler newTransformerHandler()
103 throws TransformerConfigurationException;
104
105 /**
106 * Get a TemplatesHandler object that can process SAX
107 * ContentHandler events into a Templates object.
108 *
109 * @return A non-null reference to a TransformerHandler, that may
110 * be used as a ContentHandler for SAX parse events.
111 *
112 * @throws TransformerConfigurationException If for some reason the
113 * TemplatesHandler cannot be created.
114 */
115 public abstract TemplatesHandler newTemplatesHandler()
116 throws TransformerConfigurationException;
117
118 /**
119 * Create an XMLFilter that uses the given Source as the
120 * transformation instructions.
121 *
122 * @param src The Source of the transformation instructions.
123 *
124 * @return An XMLFilter object, or null if this feature is not supported.
125 *
126 * @throws TransformerConfigurationException If for some reason the
127 * TemplatesHandler cannot be created.
128 */
129 public abstract XMLFilter newXMLFilter(Source src)
130 throws TransformerConfigurationException;
131
132 /**
133 * Create an XMLFilter, based on the Templates argument..
134 *
135 * @param templates The compiled transformation instructions.
136 *
137 * @return An XMLFilter object, or null if this feature is not supported.
138 *
139 * @throws TransformerConfigurationException If for some reason the
140 * TemplatesHandler cannot be created.
141 */
142 public abstract XMLFilter newXMLFilter(Templates templates)
143 throws TransformerConfigurationException;
144 }