LSInput


1   /*
2    * Copyright (c) 2004 World Wide Web Consortium,
3    *
4    * (Massachusetts Institute of Technology, European Research Consortium for
5    * Informatics and Mathematics, Keio University). All Rights Reserved. This
6    * work is distributed under the W3C(r) Software License [1] in the hope that
7    * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
8    * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
9    *
10   * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
11   */
12  
13  package org.w3c.dom.ls;
14  
15  /**
16   *  This interface represents an input source for data. 
17   * <p> This interface allows an application to encapsulate information about 
18   * an input source in a single object, which may include a public 
19   * identifier, a system identifier, a byte stream (possibly with a specified 
20   * encoding), a base URI, and/or a character stream. 
21   * <p> The exact definitions of a byte stream and a character stream are 
22   * binding dependent. 
23   * <p> The application is expected to provide objects that implement this 
24   * interface whenever such objects are needed. The application can either 
25   * provide its own objects that implement this interface, or it can use the 
26   * generic factory method <code>DOMImplementationLS.createLSInput()</code> 
27   * to create objects that implement this interface. 
28   * <p> The <code>LSParser</code> will use the <code>LSInput</code> object to 
29   * determine how to read data. The <code>LSParser</code> will look at the 
30   * different inputs specified in the <code>LSInput</code> in the following 
31   * order to know which one to read from, the first one that is not null and 
32   * not an empty string will be used: 
33   * <ol>
34   * <li> <code>LSInput.characterStream</code> 
35   * </li>
36   * <li> 
37   * <code>LSInput.byteStream</code> 
38   * </li>
39   * <li> <code>LSInput.stringData</code> 
40   * </li>
41   * <li> 
42   * <code>LSInput.systemId</code> 
43   * </li>
44   * <li> <code>LSInput.publicId</code> 
45   * </li>
46   * </ol> 
47   * <p> If all inputs are null, the <code>LSParser</code> will report a 
48   * <code>DOMError</code> with its <code>DOMError.type</code> set to 
49   * <code>"no-input-specified"</code> and its <code>DOMError.severity</code> 
50   * set to <code>DOMError.SEVERITY_FATAL_ERROR</code>. 
51   * <p> <code>LSInput</code> objects belong to the application. The DOM 
52   * implementation will never modify them (though it may make copies and 
53   * modify the copies, if necessary). 
54   * <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
55  and Save Specification</a>.
56   */
57  public interface LSInput {
58      /**
59       *  An attribute of a language and binding dependent type that represents 
60       * a stream of 16-bit units. The application must encode the stream 
61       * using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when 
62       * using character streams. If an XML declaration is present, the value 
63       * of the encoding attribute will be ignored. 
64       */
65      public java.io.Reader   getCharacterStream();
66      /**
67       *  An attribute of a language and binding dependent type that represents 
68       * a stream of 16-bit units. The application must encode the stream 
69       * using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when 
70       * using character streams. If an XML declaration is present, the value 
71       * of the encoding attribute will be ignored. 
72       */
73      public void setCharacterStream(java.io.Reader   characterStream);
74  
75      /**
76       *  An attribute of a language and binding dependent type that represents 
77       * a stream of bytes. 
78       * <br> If the application knows the character encoding of the byte 
79       * stream, it should set the encoding attribute. Setting the encoding in 
80       * this way will override any encoding specified in an XML declaration 
81       * in the data. 
82       */
83      public java.io.InputStream   getByteStream();
84      /**
85       *  An attribute of a language and binding dependent type that represents 
86       * a stream of bytes. 
87       * <br> If the application knows the character encoding of the byte 
88       * stream, it should set the encoding attribute. Setting the encoding in 
89       * this way will override any encoding specified in an XML declaration 
90       * in the data. 
91       */
92      public void setByteStream(java.io.InputStream   byteStream);
93  
94      /**
95       *  String data to parse. If provided, this will always be treated as a 
96       * sequence of 16-bit units (UTF-16 encoded characters). It is not a 
97       * requirement to have an XML declaration when using 
98       * <code>stringData</code>. If an XML declaration is present, the value 
99       * of the encoding attribute will be ignored. 
100      */
101     public String   getStringData();
102     /**
103      *  String data to parse. If provided, this will always be treated as a 
104      * sequence of 16-bit units (UTF-16 encoded characters). It is not a 
105      * requirement to have an XML declaration when using 
106      * <code>stringData</code>. If an XML declaration is present, the value 
107      * of the encoding attribute will be ignored. 
108      */
109     public void setStringData(String   stringData);
110 
111     /**
112      *  The system identifier, a URI reference [<a HREF='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this 
113      * input source. The system identifier is optional if there is a byte 
114      * stream, a character stream, or string data. It is still useful to 
115      * provide one, since the application will use it to resolve any 
116      * relative URIs and can include it in error messages and warnings. (The 
117      * LSParser will only attempt to fetch the resource identified by the 
118      * URI reference if there is no other input available in the input 
119      * source.) 
120      * <br> If the application knows the character encoding of the object 
121      * pointed to by the system identifier, it can set the encoding using 
122      * the <code>encoding</code> attribute. 
123      * <br> If the specified system ID is a relative URI reference (see 
124      * section 5 in [<a HREF='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the DOM 
125      * implementation will attempt to resolve the relative URI with the 
126      * <code>baseURI</code> as the base, if that fails, the behavior is 
127      * implementation dependent. 
128      */
129     public String   getSystemId();
130     /**
131      *  The system identifier, a URI reference [<a HREF='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this 
132      * input source. The system identifier is optional if there is a byte 
133      * stream, a character stream, or string data. It is still useful to 
134      * provide one, since the application will use it to resolve any 
135      * relative URIs and can include it in error messages and warnings. (The 
136      * LSParser will only attempt to fetch the resource identified by the 
137      * URI reference if there is no other input available in the input 
138      * source.) 
139      * <br> If the application knows the character encoding of the object 
140      * pointed to by the system identifier, it can set the encoding using 
141      * the <code>encoding</code> attribute. 
142      * <br> If the specified system ID is a relative URI reference (see 
143      * section 5 in [<a HREF='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the DOM 
144      * implementation will attempt to resolve the relative URI with the 
145      * <code>baseURI</code> as the base, if that fails, the behavior is 
146      * implementation dependent. 
147      */
148     public void setSystemId(String   systemId);
149 
150     /**
151      *  The public identifier for this input source. This may be mapped to an 
152      * input source using an implementation dependent mechanism (such as 
153      * catalogues or other mappings). The public identifier, if specified, 
154      * may also be reported as part of the location information when errors 
155      * are reported. 
156      */
157     public String   getPublicId();
158     /**
159      *  The public identifier for this input source. This may be mapped to an 
160      * input source using an implementation dependent mechanism (such as 
161      * catalogues or other mappings). The public identifier, if specified, 
162      * may also be reported as part of the location information when errors 
163      * are reported. 
164      */
165     public void setPublicId(String   publicId);
166 
167     /**
168      *  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 
169      * resolving a relative <code>systemId</code> to an absolute URI. 
170      * <br> If, when used, the base URI is itself a relative URI, an empty 
171      * string, or null, the behavior is implementation dependent. 
172      */
173     public String   getBaseURI();
174     /**
175      *  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 
176      * resolving a relative <code>systemId</code> to an absolute URI. 
177      * <br> If, when used, the base URI is itself a relative URI, an empty 
178      * string, or null, the behavior is implementation dependent. 
179      */
180     public void setBaseURI(String   baseURI);
181 
182     /**
183      *  The character encoding, if known. The encoding must be a string 
184      * acceptable for an XML encoding declaration ([<a HREF='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section 
185      * 4.3.3 "Character Encoding in Entities"). 
186      * <br> This attribute has no effect when the application provides a 
187      * character stream or string data. For other sources of input, an 
188      * encoding specified by means of this attribute will override any 
189      * encoding specified in the XML declaration or the Text declaration, or 
190      * an encoding obtained from a higher level protocol, such as HTTP [<a HREF='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>]. 
191      */
192     public String   getEncoding();
193     /**
194      *  The character encoding, if known. The encoding must be a string 
195      * acceptable for an XML encoding declaration ([<a HREF='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section 
196      * 4.3.3 "Character Encoding in Entities"). 
197      * <br> This attribute has no effect when the application provides a 
198      * character stream or string data. For other sources of input, an 
199      * encoding specified by means of this attribute will override any 
200      * encoding specified in the XML declaration or the Text declaration, or 
201      * an encoding obtained from a higher level protocol, such as HTTP [<a HREF='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>]. 
202      */
203     public void setEncoding(String   encoding);
204 
205     /**
206      *  If set to true, assume that the input is certified (see section 2.13 
207      * in [<a HREF='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]) when 
208      * parsing [<a HREF='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. 
209      */
210     public boolean getCertifiedText();
211     /**
212      *  If set to true, assume that the input is certified (see section 2.13 
213      * in [<a HREF='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]) when 
214      * parsing [<a HREF='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. 
215      */
216     public void setCertifiedText(boolean certifiedText);
217 
218 }
219
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags