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: SAXSource.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.stream.StreamSource;
   24   
   25   import org.xml.sax.InputSource;
   26   import org.xml.sax.XMLReader;
   27   
   28   /**
   29    * <p>Acts as an holder for SAX-style Source.</p>
   30    * 
   31    * <p>Note that XSLT requires namespace support. Attempting to transform an
   32    * input source that is not
   33    * generated with a namespace-aware parser may result in errors.
   34    * Parsers can be made namespace aware by calling the
   35    * {@link javax.xml.parsers.SAXParserFactory#setNamespaceAware(boolean awareness)} method.</p>
   36    * 
   37    * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
   38    * @version $Revision: 446598 $, $Date: 2006-09-15 08:55:40 -0400 (Fri, 15 Sep 2006) $
   39    */
   40   public class SAXSource implements Source {
   41   
   42       /**
   43        * If {@link javax.xml.transform.TransformerFactory#getFeature}
   44        * returns true when passed this value as an argument,
   45        * the Transformer supports Source input of this type.
   46        */
   47       public static final String FEATURE =
   48           "http://javax.xml.transform.sax.SAXSource/feature";
   49   
   50       /**
   51        * <p>Zero-argument default constructor.  If this constructor is used, and
   52        * no SAX source is set using
   53        * {@link #setInputSource(InputSource inputSource)} , then the
   54        * <code>Transformer</code> will
   55        * create an empty source {@link org.xml.sax.InputSource} using
   56        * {@link org.xml.sax.InputSource#InputSource() new InputSource()}.</p>
   57        *
   58        * @see javax.xml.transform.Transformer#transform(Source xmlSource, Result outputTarget)
   59        */
   60       public SAXSource() { }
   61   
   62       /**
   63        * Create a <code>SAXSource</code>, using an {@link org.xml.sax.XMLReader}
   64        * and a SAX InputSource. The {@link javax.xml.transform.Transformer}
   65        * or {@link javax.xml.transform.sax.SAXTransformerFactory} will set itself
   66        * to be the reader's {@link org.xml.sax.ContentHandler}, and then will call
   67        * reader.parse(inputSource).
   68        *
   69        * @param reader An XMLReader to be used for the parse.
   70        * @param inputSource A SAX input source reference that must be non-null
   71        * and that will be passed to the reader parse method.
   72        */
   73       public SAXSource(XMLReader reader, InputSource inputSource) {
   74           this.reader      = reader;
   75           this.inputSource = inputSource;
   76       }
   77   
   78       /**
   79        * Create a <code>SAXSource</code>, using a SAX <code>InputSource</code>.
   80        * The {@link javax.xml.transform.Transformer} or
   81        * {@link javax.xml.transform.sax.SAXTransformerFactory} creates a
   82        * reader via {@link org.xml.sax.helpers.XMLReaderFactory}
   83        * (if setXMLReader is not used), sets itself as
   84        * the reader's {@link org.xml.sax.ContentHandler}, and calls
   85        * reader.parse(inputSource).
   86        *
   87        * @param inputSource An input source reference that must be non-null
   88        * and that will be passed to the parse method of the reader.
   89        */
   90       public SAXSource(InputSource inputSource) {
   91           this.inputSource = inputSource;
   92       }
   93   
   94       /**
   95        * Set the XMLReader to be used for the Source.
   96        *
   97        * @param reader A valid XMLReader or XMLFilter reference.
   98        */
   99       public void setXMLReader(XMLReader reader) {
  100           this.reader = reader;
  101       }
  102   
  103       /**
  104        * Get the XMLReader to be used for the Source.
  105        *
  106        * @return A valid XMLReader or XMLFilter reference, or null.
  107        */
  108       public XMLReader getXMLReader() {
  109           return reader;
  110       }
  111   
  112       /**
  113        * Set the SAX InputSource to be used for the Source.
  114        *
  115        * @param inputSource A valid InputSource reference.
  116        */
  117       public void setInputSource(InputSource inputSource) {
  118           this.inputSource = inputSource;
  119       }
  120   
  121       /**
  122        * Get the SAX InputSource to be used for the Source.
  123        *
  124        * @return A valid InputSource reference, or null.
  125        */
  126       public InputSource getInputSource() {
  127           return inputSource;
  128       }
  129   
  130       /**
  131        * Set the system identifier for this Source.  If an input source
  132        * has already been set, it will set the system ID or that
  133        * input source, otherwise it will create a new input source.
  134        *
  135        * <p>The system identifier is optional if there is a byte stream
  136        * or a character stream, but it is still useful to provide one,
  137        * since the application can use it to resolve relative URIs
  138        * and can include it in error messages and warnings (the parser
  139        * will attempt to open a connection to the URI only if
  140        * no byte stream or character stream is specified).</p>
  141        *
  142        * @param systemId The system identifier as a URI string.
  143        */
  144       public void setSystemId(String systemId) {
  145   
  146           if (null == inputSource) {
  147               inputSource = new InputSource(systemId);
  148           } else {
  149               inputSource.setSystemId(systemId);
  150           }
  151       }
  152   
  153       /**
  154        * <p>Get the base ID (URI or system ID) from where URIs
  155        * will be resolved.</p>
  156        *
  157        * @return Base URL for the <code>Source</code>, or <code>null</code>.
  158        */
  159       public String getSystemId() {
  160   
  161           if (inputSource == null) {
  162               return null;
  163           } else {
  164               return inputSource.getSystemId();
  165           }
  166       }
  167   
  168       /**
  169        * The XMLReader to be used for the source tree input. May be null.
  170        */
  171       private XMLReader reader;
  172   
  173       /**
  174        * <p>The SAX InputSource to be used for the source tree input.
  175        * Should not be <code>null<code>.</p>
  176        */
  177       private InputSource inputSource;
  178   
  179       /**
  180        * Attempt to obtain a SAX InputSource object from a Source
  181        * object.
  182        *
  183        * @param source Must be a non-null Source reference.
  184        *
  185        * @return An InputSource, or null if Source can not be converted.
  186        */
  187       public static InputSource sourceToInputSource(Source source) {
  188   
  189           if (source instanceof SAXSource) {
  190               return ((SAXSource) source).getInputSource();
  191           } else if (source instanceof StreamSource) {
  192               StreamSource ss      = (StreamSource) source;
  193               InputSource  isource = new InputSource(ss.getSystemId());
  194   
  195               isource.setByteStream(ss.getInputStream());
  196               isource.setCharacterStream(ss.getReader());
  197               isource.setPublicId(ss.getPublicId());
  198   
  199               return isource;
  200           } else {
  201               return null;
  202           }
  203       }
  204   }
  205   

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