001 /*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003 *
004 * This code is free software; you can redistribute it and/or modify it
005 * under the terms of the GNU General Public License version 2 only, as
006 * published by the Free Software Foundation. Sun designates this
007 * particular file as subject to the "Classpath" exception as provided
008 * by Sun in the LICENSE file that accompanied this code.
009 *
010 * This code is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013 * version 2 for more details (a copy is included in the LICENSE file that
014 * accompanied this code).
015 *
016 * You should have received a copy of the GNU General Public License version
017 * 2 along with this work; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019 *
020 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021 * CA 95054 USA or visit www.sun.com if you need additional information or
022 * have any questions.
023 */
024
025 /*
026 * This file is available under and governed by the GNU General Public
027 * License version 2 only, as published by the Free Software Foundation.
028 * However, the following notice accompanied the original version of this
029 * file and, per its terms, should not be removed:
030 *
031 * Copyright (c) 2004 World Wide Web Consortium,
032 *
033 * (Massachusetts Institute of Technology, European Research Consortium for
034 * Informatics and Mathematics, Keio University). All Rights Reserved. This
035 * work is distributed under the W3C(r) Software License [1] in the hope that
036 * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
037 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
038 *
039 * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
040 */
041
042 package org.w3c.dom.ls;
043
044 /**
045 * This interface represents an input source for data.
046 * <p> This interface allows an application to encapsulate information about
047 * an input source in a single object, which may include a public
048 * identifier, a system identifier, a byte stream (possibly with a specified
049 * encoding), a base URI, and/or a character stream.
050 * <p> The exact definitions of a byte stream and a character stream are
051 * binding dependent.
052 * <p> The application is expected to provide objects that implement this
053 * interface whenever such objects are needed. The application can either
054 * provide its own objects that implement this interface, or it can use the
055 * generic factory method <code>DOMImplementationLS.createLSInput()</code>
056 * to create objects that implement this interface.
057 * <p> The <code>LSParser</code> will use the <code>LSInput</code> object to
058 * determine how to read data. The <code>LSParser</code> will look at the
059 * different inputs specified in the <code>LSInput</code> in the following
060 * order to know which one to read from, the first one that is not null and
061 * not an empty string will be used:
062 * <ol>
063 * <li> <code>LSInput.characterStream</code>
064 * </li>
065 * <li>
066 * <code>LSInput.byteStream</code>
067 * </li>
068 * <li> <code>LSInput.stringData</code>
069 * </li>
070 * <li>
071 * <code>LSInput.systemId</code>
072 * </li>
073 * <li> <code>LSInput.publicId</code>
074 * </li>
075 * </ol>
076 * <p> If all inputs are null, the <code>LSParser</code> will report a
077 * <code>DOMError</code> with its <code>DOMError.type</code> set to
078 * <code>"no-input-specified"</code> and its <code>DOMError.severity</code>
079 * set to <code>DOMError.SEVERITY_FATAL_ERROR</code>.
080 * <p> <code>LSInput</code> objects belong to the application. The DOM
081 * implementation will never modify them (though it may make copies and
082 * modify the copies, if necessary).
083 * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407'>Document Object Model (DOM) Level 3 Load
084 and Save Specification</a>.
085 */
086 public interface LSInput {
087 /**
088 * An attribute of a language and binding dependent type that represents
089 * a stream of 16-bit units. The application must encode the stream
090 * using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when
091 * using character streams. If an XML declaration is present, the value
092 * of the encoding attribute will be ignored.
093 */
094 public java.io.Reader getCharacterStream();
095
096 /**
097 * An attribute of a language and binding dependent type that represents
098 * a stream of 16-bit units. The application must encode the stream
099 * using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when
100 * using character streams. If an XML declaration is present, the value
101 * of the encoding attribute will be ignored.
102 */
103 public void setCharacterStream(java.io.Reader characterStream);
104
105 /**
106 * An attribute of a language and binding dependent type that represents
107 * a stream of bytes.
108 * <br> If the application knows the character encoding of the byte
109 * stream, it should set the encoding attribute. Setting the encoding in
110 * this way will override any encoding specified in an XML declaration
111 * in the data.
112 */
113 public java.io.InputStream getByteStream();
114
115 /**
116 * An attribute of a language and binding dependent type that represents
117 * a stream of bytes.
118 * <br> If the application knows the character encoding of the byte
119 * stream, it should set the encoding attribute. Setting the encoding in
120 * this way will override any encoding specified in an XML declaration
121 * in the data.
122 */
123 public void setByteStream(java.io.InputStream byteStream);
124
125 /**
126 * String data to parse. If provided, this will always be treated as a
127 * sequence of 16-bit units (UTF-16 encoded characters). It is not a
128 * requirement to have an XML declaration when using
129 * <code>stringData</code>. If an XML declaration is present, the value
130 * of the encoding attribute will be ignored.
131 */
132 public String getStringData();
133
134 /**
135 * String data to parse. If provided, this will always be treated as a
136 * sequence of 16-bit units (UTF-16 encoded characters). It is not a
137 * requirement to have an XML declaration when using
138 * <code>stringData</code>. If an XML declaration is present, the value
139 * of the encoding attribute will be ignored.
140 */
141 public void setStringData(String stringData);
142
143 /**
144 * The system identifier, a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this
145 * input source. The system identifier is optional if there is a byte
146 * stream, a character stream, or string data. It is still useful to
147 * provide one, since the application will use it to resolve any
148 * relative URIs and can include it in error messages and warnings. (The
149 * LSParser will only attempt to fetch the resource identified by the
150 * URI reference if there is no other input available in the input
151 * source.)
152 * <br> If the application knows the character encoding of the object
153 * pointed to by the system identifier, it can set the encoding using
154 * the <code>encoding</code> attribute.
155 * <br> If the specified system ID is a relative URI reference (see
156 * section 5 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the DOM
157 * implementation will attempt to resolve the relative URI with the
158 * <code>baseURI</code> as the base, if that fails, the behavior is
159 * implementation dependent.
160 */
161 public String getSystemId();
162
163 /**
164 * The system identifier, a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this
165 * input source. The system identifier is optional if there is a byte
166 * stream, a character stream, or string data. It is still useful to
167 * provide one, since the application will use it to resolve any
168 * relative URIs and can include it in error messages and warnings. (The
169 * LSParser will only attempt to fetch the resource identified by the
170 * URI reference if there is no other input available in the input
171 * source.)
172 * <br> If the application knows the character encoding of the object
173 * pointed to by the system identifier, it can set the encoding using
174 * the <code>encoding</code> attribute.
175 * <br> If the specified system ID is a relative URI reference (see
176 * section 5 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the DOM
177 * implementation will attempt to resolve the relative URI with the
178 * <code>baseURI</code> as the base, if that fails, the behavior is
179 * implementation dependent.
180 */
181 public void setSystemId(String systemId);
182
183 /**
184 * The public identifier for this input source. This may be mapped to an
185 * input source using an implementation dependent mechanism (such as
186 * catalogues or other mappings). The public identifier, if specified,
187 * may also be reported as part of the location information when errors
188 * are reported.
189 */
190 public String getPublicId();
191
192 /**
193 * The public identifier for this input source. This may be mapped to an
194 * input source using an implementation dependent mechanism (such as
195 * catalogues or other mappings). The public identifier, if specified,
196 * may also be reported as part of the location information when errors
197 * are reported.
198 */
199 public void setPublicId(String publicId);
200
201 /**
202 * The base URI to be used (see section 5.1.4 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]) for
203 * resolving a relative <code>systemId</code> to an absolute URI.
204 * <br> If, when used, the base URI is itself a relative URI, an empty
205 * string, or null, the behavior is implementation dependent.
206 */
207 public String getBaseURI();
208
209 /**
210 * The base URI to be used (see section 5.1.4 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]) for
211 * resolving a relative <code>systemId</code> to an absolute URI.
212 * <br> If, when used, the base URI is itself a relative URI, an empty
213 * string, or null, the behavior is implementation dependent.
214 */
215 public void setBaseURI(String baseURI);
216
217 /**
218 * The character encoding, if known. The encoding must be a string
219 * acceptable for an XML encoding declaration ([<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section
220 * 4.3.3 "Character Encoding in Entities").
221 * <br> This attribute has no effect when the application provides a
222 * character stream or string data. For other sources of input, an
223 * encoding specified by means of this attribute will override any
224 * encoding specified in the XML declaration or the Text declaration, or
225 * an encoding obtained from a higher level protocol, such as HTTP [<a href='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>].
226 */
227 public String getEncoding();
228
229 /**
230 * The character encoding, if known. The encoding must be a string
231 * acceptable for an XML encoding declaration ([<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section
232 * 4.3.3 "Character Encoding in Entities").
233 * <br> This attribute has no effect when the application provides a
234 * character stream or string data. For other sources of input, an
235 * encoding specified by means of this attribute will override any
236 * encoding specified in the XML declaration or the Text declaration, or
237 * an encoding obtained from a higher level protocol, such as HTTP [<a href='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>].
238 */
239 public void setEncoding(String encoding);
240
241 /**
242 * If set to true, assume that the input is certified (see section 2.13
243 * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]) when
244 * parsing [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>].
245 */
246 public boolean getCertifiedText();
247
248 /**
249 * If set to true, assume that the input is certified (see section 2.13
250 * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]) when
251 * parsing [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>].
252 */
253 public void setCertifiedText(boolean certifiedText);
254
255 }
|