Home » xml-commons-external-1.4.01-src » javax » xml » transform » sax » [javadoc | source]

    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   }

Home » xml-commons-external-1.4.01-src » javax » xml » transform » sax » [javadoc | source]