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