Receiver


1   package net.sf.saxon.event;
2   import net.sf.saxon.trans.XPathException;
3   
4   import javax.xml.transform.Result  ;
5   /**
6     * Receiver: This interface represents a recipient of XML tree-walking (push) events. It is
7     * based on SAX2's ContentHandler, but adapted to handle additional events, and
8     * to use Saxon's name pool. Namespaces and Attributes are handled by separate events
9     * following the startElement event. Schema types can be defined for elements and attributes.
10    * <p>
11    * The Receiver interface is an important internal interface within Saxon, and provides a powerful
12    * mechanism for integrating Saxon with other applications. It has been designed with extensibility
13    * and stability in mind. However, it should be considered as an interface designed primarily for
14    * internal use, and not as a completely stable part of the public Saxon API.
15    * <p>
16    * @author Michael H. Kay
17    */
18  
19  public interface Receiver extends Result   {
20  
21      /**
22      * Set the pipeline configuration
23      */
24  
25      public void setPipelineConfiguration(PipelineConfiguration config);
26  
27      /**
28      * Get the pipeline configuration
29      */
30  
31      public PipelineConfiguration getPipelineConfiguration();
32  
33      /**
34      * Set the System ID of the destination tree
35      */
36  
37      public void setSystemId(String   systemId);
38  
39      /**
40      * Notify the start of the event stream
41      */
42  
43      public void open() throws XPathException;
44  
45      /**
46       * Notify the start of a document node
47       */
48  
49      public void startDocument(int properties) throws XPathException;
50  
51      /**
52       * Notify the end of a document node
53       */
54  
55      public void endDocument() throws XPathException;
56  
57      /**
58      * Notify an unparsed entity URI.
59      * @param name The name of the unparsed entity
60      * @param systemID The system identifier of the unparsed entity
61      * @param publicID The public identifier of the unparsed entity
62      */
63  
64      public void setUnparsedEntity(String   name, String   systemID, String   publicID) throws XPathException;
65  
66      /**
67       * Notify the start of an element
68       * @param nameCode integer code identifying the name of the element within the name pool.
69       * @param typeCode integer code identifying the element's type within the name pool. The value -1
70       * indicates the default type, xdt:untyped.
71       * @param locationId an integer which can be interpreted using a LocationMap to return
72       * information such as line number and system ID. If no location information is available,
73       * the value zero is supplied.
74       * @param properties bit-significant properties of the element node. If there are no revelant
75       * properties, zero is supplied.
76      */
77  
78      public void startElement(int nameCode, int typeCode, int locationId, int properties)
79              throws XPathException;
80  
81      /**
82       * Notify a namespace. Namespaces are notified <b>after</b> the startElement event, and before
83       * any children for the element. The namespaces that are reported are only required
84       * to include those that are different from the parent element. The events represent namespace
85       * declarations and undeclarations rather than in-scope namespace nodes: an undeclaration is represented
86       * by a namespace code of zero. If the sequence of namespace events contains two
87       * A namespace must not conflict with any namespaces already used for element or attribute names.
88       * @param namespaceCode an integer: the top half is a prefix code, the bottom half a URI code.
89       * These may be translated into an actual prefix and URI using the name pool. A prefix code of
90       * zero represents the empty prefix (that is, the default namespace). A URI code of zero represents
91       * a URI of "", that is, a namespace undeclaration.
92       * @param properties The most important property is REJECT_DUPLICATES. If this property is set, the
93       * namespace declaration will be rejected if it conflicts with a previous declaration of the same
94       * prefix. If the property is not set, the namespace declaration will be ignored if it conflicts
95       * with a previous declaration. This reflects the fact that when copying a tree, namespaces for child
96       * elements are emitted before the namespaces of their parent element. Unfortunately this conflicts
97       * with the XSLT rule for complex content construction, where the recovery action in the event of
98       * conflicts is to take the namespace that comes last. XSLT therefore doesn't recover from this error:
99       * it sets the REJECT_DUPLICATES flag, and this is treated as a hard error.
100     */
101 
102     public void namespace(int namespaceCode, int properties) throws XPathException;
103 
104     /**
105      * Notify an attribute. Attributes are notified after the startElement event, and before any
106      * children. Namespaces and attributes may be intermingled.
107      * @param nameCode The name of the attribute, as held in the name pool
108      * @param typeCode The type of the attribute, as held in the name pool. The additional bit
109      * NodeInfo.IS_DTD_TYPE may be set to indicate a DTD-derived type.
110      * @param locationId an integer which can be interpreted using a LocationMap to return
111      * information such as line number and system ID. If no location information is available,
112      * the value zero is supplied.
113      * @param properties Bit significant value. The following bits are defined:
114      *        <dt>DISABLE_ESCAPING</dt>    <dd>Disable escaping for this attribute</dd>
115      *        <dt>NO_SPECIAL_CHARACTERS</dt>      <dd>Attribute value contains no special characters</dd>
116      * @throws IllegalStateException: attempt to output an attribute when there is no open element
117      * start tag
118     */
119 
120     public void attribute(int nameCode, int typeCode, CharSequence   value, int locationId, int properties)
121             throws XPathException;
122 
123     /**
124     * Notify the start of the content, that is, the completion of all attributes and namespaces.
125     * Note that the initial receiver of output from XSLT instructions will not receive this event,
126     * it has to detect it itself. Note that this event is reported for every element even if it has
127     * no attributes, no namespaces, and no content.
128     */
129 
130     public void startContent() throws XPathException;
131 
132     /**
133     * Notify the end of an element. The receiver must maintain a stack if it needs to know which
134     * element is ending.
135     */
136 
137     public void endElement() throws XPathException;
138 
139     /**
140      * Notify character data. Note that some receivers may require the character data to be
141      * sent in a single event, but in general this is not a requirement.
142      * @param chars The characters
143      * @param locationId an integer which can be interpreted using a LocationMap to return
144      * information such as line number and system ID. If no location information is available,
145      * the value zero is supplied.
146      * @param properties Bit significant value. The following bits are defined:
147      *        <dt>DISABLE_ESCAPING</dt>           <dd>Disable escaping for this text node</dd>
148      *        <dt>USE_CDATA</dt>                  <dd>Output as a CDATA section</dd>
149      *        <dt>NO_SPECIAL_CHARACTERS</dt>      <dd>Value contains no special characters</dd>
150      *        <dt>WHITESPACE</dt>                 <dd>Text is all whitespace</dd>
151      */
152 
153     public void characters(CharSequence   chars, int locationId, int properties)
154             throws XPathException;
155 
156     /**
157      * Output a processing instruction
158      * @param name The PI name. This must be a legal name (it will not be checked).
159      * @param data The data portion of the processing instruction
160      * @param locationId an integer which can be interpreted using a LocationMap to return
161      * information such as line number and system ID. If no location information is available,
162      * the value zero is supplied.
163      * @param properties Additional information about the PI. The following bits are
164      * defined:
165      *        <dt>CHECKED</dt>    <dd>Data is known to be legal (e.g. doesn't contain "?>")</dd>
166      * @throws IllegalArgumentException: the content is invalid for an XML processing instruction
167      */
168 
169     public void processingInstruction(String   name, CharSequence   data, int locationId, int properties)
170             throws XPathException;
171 
172     /**
173      * Notify a comment. Comments are only notified if they are outside the DTD.
174      * @param content The content of the comment
175      * @param locationId an integer which can be interpreted using a LocationMap to return
176      * information such as line number and system ID. If no location information is available,
177      * the value zero is supplied.
178      * @param properties Additional information about the comment. The following bits are
179      * defined:
180      *        <dt>CHECKED</dt>    <dd>Comment is known to be legal (e.g. doesn't contain "--")</dd>
181      * @throws IllegalArgumentException: the content is invalid for an XML comment
182      */
183 
184     public void comment(CharSequence   content, int locationId, int properties) throws XPathException;
185 
186     /**
187     * Notify the end of the event stream
188     */
189 
190     public void close() throws XPathException;
191 
192 
193 
194 }
195 
196 //
197 // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
198 // you may not use this file except in compliance with the License. You may obtain a copy of the
199 // License at http://www.mozilla.org/MPL/
200 //
201 // Software distributed under the License is distributed on an "AS IS" basis,
202 // WITHOUT WARRANTY OF ANY KIND, either express or implied.
203 // See the License for the specific language governing rights and limitations under the License.
204 //
205 // The Original Code is: all this file.
206 //
207 // The Initial Developer of the Original Code is Michael H. Kay
208 //
209 // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
210 //
211 // Contributor(s): none.
212 //
213
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags