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.Source; 23 import javax.xml.transform.Templates; 24 import javax.xml.transform.TransformerConfigurationException; 25 import javax.xml.transform.TransformerFactory; 26 import org.xml.sax.XMLFilter; 27 28 /** 29 * This class extends TransformerFactory to provide SAX-specific 30 * factory methods. It provides two types of ContentHandlers, 31 * one for creating Transformers, the other for creating Templates 32 * objects. 33 * 34 * <p>If an application wants to set the ErrorHandler or EntityResolver 35 * for an XMLReader used during a transformation, it should use a URIResolver 36 * to return the SAXSource which provides (with getXMLReader) a reference to 37 * the XMLReader.</p> 38 */ 39 public abstract class SAXTransformerFactory extends TransformerFactory { 40 41 /** If {@link javax.xml.transform.TransformerFactory#getFeature} 42 * returns true when passed this value as an argument, 43 * the TransformerFactory returned from 44 * {@link javax.xml.transform.TransformerFactory#newInstance} may 45 * be safely cast to a SAXTransformerFactory. 46 */ 47 public static final String FEATURE = 48 "http://javax.xml.transform.sax.SAXTransformerFactory/feature"; 49 50 /** If {@link javax.xml.transform.TransformerFactory#getFeature} 51 * returns true when passed this value as an argument, 52 * the {@link #newXMLFilter(Source src)} 53 * and {@link #newXMLFilter(Templates templates)} methods are supported. 54 */ 55 public static final String FEATURE_XMLFILTER = 56 "http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter"; 57 58 /** 59 * The default constructor is protected on purpose. 60 */ SAXTransformerFactory()61 protected SAXTransformerFactory() {} 62 63 /** 64 * Get a TransformerHandler object that can process SAX 65 * ContentHandler events into a Result, based on the transformation 66 * instructions specified by the argument. 67 * 68 * @param src The Source of the transformation instructions. 69 * 70 * @return TransformerHandler ready to transform SAX events. 71 * 72 * @throws TransformerConfigurationException If for some reason the 73 * TransformerHandler can not be created. 74 */ newTransformerHandler(Source src)75 public abstract TransformerHandler newTransformerHandler(Source src) 76 throws TransformerConfigurationException; 77 78 /** 79 * Get a TransformerHandler object that can process SAX 80 * ContentHandler events into a Result, based on the Templates argument. 81 * 82 * @param templates The compiled transformation instructions. 83 * 84 * @return TransformerHandler ready to transform SAX events. 85 * 86 * @throws TransformerConfigurationException If for some reason the 87 * TransformerHandler can not be created. 88 */ newTransformerHandler( Templates templates)89 public abstract TransformerHandler newTransformerHandler( 90 Templates templates) throws TransformerConfigurationException; 91 92 /** 93 * Get a TransformerHandler object that can process SAX 94 * ContentHandler events into a Result. The transformation 95 * is defined as an identity (or copy) transformation, for example 96 * to copy a series of SAX parse events into a DOM tree. 97 * 98 * @return A non-null reference to a TransformerHandler, that may 99 * be used as a ContentHandler for SAX parse events. 100 * 101 * @throws TransformerConfigurationException If for some reason the 102 * TransformerHandler cannot be created. 103 */ newTransformerHandler()104 public abstract TransformerHandler newTransformerHandler() 105 throws TransformerConfigurationException; 106 107 /** 108 * Get a TemplatesHandler object that can process SAX 109 * ContentHandler events into a Templates object. 110 * 111 * @return A non-null reference to a TransformerHandler, that may 112 * be used as a ContentHandler for SAX parse events. 113 * 114 * @throws TransformerConfigurationException If for some reason the 115 * TemplatesHandler cannot be created. 116 */ newTemplatesHandler()117 public abstract TemplatesHandler newTemplatesHandler() 118 throws TransformerConfigurationException; 119 120 /** 121 * Create an XMLFilter that uses the given Source as the 122 * transformation instructions. 123 * 124 * @param src The Source of the transformation instructions. 125 * 126 * @return An XMLFilter object, or null if this feature is not supported. 127 * 128 * @throws TransformerConfigurationException If for some reason the 129 * TemplatesHandler cannot be created. 130 */ newXMLFilter(Source src)131 public abstract XMLFilter newXMLFilter(Source src) 132 throws TransformerConfigurationException; 133 134 /** 135 * Create an XMLFilter, based on the Templates argument.. 136 * 137 * @param templates The compiled transformation instructions. 138 * 139 * @return An XMLFilter object, or null if this feature is not supported. 140 * 141 * @throws TransformerConfigurationException If for some reason the 142 * TemplatesHandler cannot be created. 143 */ newXMLFilter(Templates templates)144 public abstract XMLFilter newXMLFilter(Templates templates) 145 throws TransformerConfigurationException; 146 } 147