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 * @since 1.4 44 */ 45 public abstract class SAXTransformerFactory extends TransformerFactory { 46 47 /** If {@link javax.xml.transform.TransformerFactory#getFeature} 48 * returns true when passed this value as an argument, 49 * the TransformerFactory returned from 50 * {@link javax.xml.transform.TransformerFactory#newInstance} may 51 * be safely cast to a SAXTransformerFactory. 52 */ 53 public static final String FEATURE = 54 "http://javax.xml.transform.sax.SAXTransformerFactory/feature"; 55 56 /** If {@link javax.xml.transform.TransformerFactory#getFeature} 57 * returns true when passed this value as an argument, 58 * the {@link #newXMLFilter(Source src)} 59 * and {@link #newXMLFilter(Templates templates)} methods are supported. 60 */ 61 public static final String FEATURE_XMLFILTER = 62 "http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter"; 63 64 /** 65 * The default constructor is protected on purpose. 66 */ 67 protected SAXTransformerFactory() {} 68 69 /** 70 * Get a TransformerHandler object that can process SAX 71 * ContentHandler events into a Result, based on the transformation 72 * instructions specified by the argument. 73 * 74 * @param src The Source of the transformation instructions. 75 * 76 * @return TransformerHandler ready to transform SAX events. 77 * 78 * @throws TransformerConfigurationException If for some reason the 79 * TransformerHandler can not be created. 80 */ 81 public abstract TransformerHandler newTransformerHandler(Source src) 82 throws TransformerConfigurationException; 83 84 /** 85 * Get a TransformerHandler object that can process SAX 86 * ContentHandler events into a Result, based on the Templates argument. 87 * 88 * @param templates The compiled transformation instructions. 89 * 90 * @return TransformerHandler ready to transform SAX events. 91 * 92 * @throws TransformerConfigurationException If for some reason the 93 * TransformerHandler can not be created. 94 */ 95 public abstract TransformerHandler newTransformerHandler( 96 Templates templates) throws TransformerConfigurationException; 97 98 /** 99 * Get a TransformerHandler object that can process SAX 100 * ContentHandler events into a Result. The transformation 101 * is defined as an identity (or copy) transformation, for example 102 * to copy a series of SAX parse events into a DOM tree. 103 * 104 * @return A non-null reference to a TransformerHandler, that may 105 * be used as a ContentHandler for SAX parse events. 106 * 107 * @throws TransformerConfigurationException If for some reason the 108 * TransformerHandler cannot be created. 109 */ 110 public abstract TransformerHandler newTransformerHandler() 111 throws TransformerConfigurationException; 112 113 /** 114 * Get a TemplatesHandler object that can process SAX 115 * ContentHandler events into a Templates object. 116 * 117 * @return A non-null reference to a TransformerHandler, that may 118 * be used as a ContentHandler for SAX parse events. 119 * 120 * @throws TransformerConfigurationException If for some reason the 121 * TemplatesHandler cannot be created. 122 */ 123 public abstract TemplatesHandler newTemplatesHandler() 124 throws TransformerConfigurationException; 125 126 /** 127 * Create an XMLFilter that uses the given Source as the 128 * transformation instructions. 129 * 130 * @param src The Source of the transformation instructions. 131 * 132 * @return An XMLFilter object, or null if this feature is not supported. 133 * 134 * @throws TransformerConfigurationException If for some reason the 135 * TemplatesHandler cannot be created. 136 */ 137 public abstract XMLFilter newXMLFilter(Source src) 138 throws TransformerConfigurationException; 139 140 /** 141 * Create an XMLFilter, based on the Templates argument.. 142 * 143 * @param templates The compiled transformation instructions. 144 * 145 * @return An XMLFilter object, or null if this feature is not supported. 146 * 147 * @throws TransformerConfigurationException If for some reason the 148 * TemplatesHandler cannot be created. 149 */ 150 public abstract XMLFilter newXMLFilter(Templates templates) 151 throws TransformerConfigurationException; 152 }