Home » xml-commons-external-1.4.01-src » javax » xml » transform » stream » [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: StreamResult.java 829970 2009-10-26 21:15:29Z mrglavas $
   19   
   20   package javax.xml.transform.stream;
   21   
   22   import java.io.File;
   23   import java.io.OutputStream;
   24   import java.io.Writer;
   25   
   26   import javax.xml.transform.Result;
   27   
   28   /**
   29    * <p>Acts as an holder for a transformation result,
   30    * which may be XML, plain Text, HTML, or some other form of markup.</p>
   31    *
   32    * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
   33    */
   34   public class StreamResult implements Result {
   35   
   36       /** If {@link javax.xml.transform.TransformerFactory#getFeature}
   37        * returns true when passed this value as an argument,
   38        * the Transformer supports Result output of this type.
   39        */
   40       public static final String FEATURE =
   41           "http://javax.xml.transform.stream.StreamResult/feature";
   42   
   43       /**
   44        * Zero-argument default constructor.
   45        */
   46       public StreamResult() {
   47       }
   48   
   49       /**
   50        * Construct a StreamResult from a byte stream.  Normally,
   51        * a stream should be used rather than a reader, so that
   52        * the transformer may use instructions contained in the
   53        * transformation instructions to control the encoding.
   54        *
   55        * @param outputStream A valid OutputStream reference.
   56        */
   57       public StreamResult(OutputStream outputStream) {
   58           setOutputStream(outputStream);
   59       }
   60   
   61       /**
   62        * Construct a StreamResult from a character stream.  Normally,
   63        * a stream should be used rather than a reader, so that
   64        * the transformer may use instructions contained in the
   65        * transformation instructions to control the encoding.  However,
   66        * there are times when it is useful to write to a character
   67        * stream, such as when using a StringWriter.
   68        *
   69        * @param writer  A valid Writer reference.
   70        */
   71       public StreamResult(Writer writer) {
   72           setWriter(writer);
   73       }
   74   
   75       /**
   76        * Construct a StreamResult from a URL.
   77        *
   78        * @param systemId Must be a String that conforms to the URI syntax.
   79        */
   80       public StreamResult(String systemId) {
   81           this.systemId = systemId;
   82       }
   83   
   84       /**
   85        * Construct a StreamResult from a File.
   86        *
   87        * @param f Must a non-null File reference.
   88        */
   89       public StreamResult(File f) {
   90           setSystemId(f);
   91       }
   92   
   93       /**
   94        * Set the ByteStream that is to be written to.  Normally,
   95        * a stream should be used rather than a reader, so that
   96        * the transformer may use instructions contained in the
   97        * transformation instructions to control the encoding.
   98        *
   99        * @param outputStream A valid OutputStream reference.
  100        */
  101       public void setOutputStream(OutputStream outputStream) {
  102           this.outputStream = outputStream;
  103       }
  104   
  105       /**
  106        * Get the byte stream that was set with setOutputStream.
  107        *
  108        * @return The byte stream that was set with setOutputStream, or null
  109        * if setOutputStream or the ByteStream constructor was not called.
  110        */
  111       public OutputStream getOutputStream() {
  112           return outputStream;
  113       }
  114   
  115       /**
  116        * Set the writer that is to receive the result.  Normally,
  117        * a stream should be used rather than a writer, so that
  118        * the transformer may use instructions contained in the
  119        * transformation instructions to control the encoding.  However,
  120        * there are times when it is useful to write to a writer,
  121        * such as when using a StringWriter.
  122        *
  123        * @param writer  A valid Writer reference.
  124        */
  125       public void setWriter(Writer writer) {
  126           this.writer = writer;
  127       }
  128   
  129       /**
  130        * Get the character stream that was set with setWriter.
  131        *
  132        * @return The character stream that was set with setWriter, or null
  133        * if setWriter or the Writer constructor was not called.
  134        */
  135       public Writer getWriter() {
  136           return writer;
  137       }
  138   
  139       /**
  140        * Set the systemID that may be used in association
  141        * with the byte or character stream, or, if neither is set, use
  142        * this value as a writeable URI (probably a file name).
  143        *
  144        * @param systemId The system identifier as a URI string.
  145        */
  146       public void setSystemId(String systemId) {
  147           this.systemId = systemId;
  148       }
  149   
  150       /**
  151        * <p>Set the system ID from a <code>File</code> reference.</p>
  152        * 
  153        * <p>Note the use of {@link File#toURI()} and {@link File#toURL()}.
  154        * <code>toURI()</code> is preferred and used if possible.
  155        * To allow JAXP 1.3 to run on J2SE 1.3, <code>toURL()</code>
  156        * is used if a {@link NoSuchMethodException} is thrown by the attempt
  157        * to use <code>toURI()</code>.</p>
  158        *
  159        * @param f Must a non-null File reference.
  160        */
  161       public void setSystemId(File f) {
  162           this.systemId = FilePathToURI.filepath2URI(f.getAbsolutePath());
  163       }
  164   
  165       /**
  166        * Get the system identifier that was set with setSystemId.
  167        *
  168        * @return The system identifier that was set with setSystemId, or null
  169        * if setSystemId was not called.
  170        */
  171       public String getSystemId() {
  172           return systemId;
  173       }
  174   
  175       //////////////////////////////////////////////////////////////////////
  176       // Internal state.
  177       //////////////////////////////////////////////////////////////////////
  178   
  179       /**
  180        * The systemID that may be used in association
  181        * with the byte or character stream, or, if neither is set, use
  182        * this value as a writeable URI (probably a file name).
  183        */
  184       private String systemId;
  185   
  186       /**
  187        * The byte stream that is to be written to.
  188        */
  189       private OutputStream outputStream;
  190   
  191       /**
  192        * The character stream that is to be written to.
  193        */
  194       private Writer writer;
  195   }

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