001: package net.sf.saxon.event;
002:
003: import net.sf.saxon.trans.XPathException;
004:
005: import javax.xml.transform.Result;
006:
007: /**
008: * Receiver: This interface represents a recipient of XML tree-walking (push) events. It is
009: * based on SAX2's ContentHandler, but adapted to handle additional events, and
010: * to use Saxon's name pool. Namespaces and Attributes are handled by separate events
011: * following the startElement event. Schema types can be defined for elements and attributes.
012: * <p>
013: * The Receiver interface is an important internal interface within Saxon, and provides a powerful
014: * mechanism for integrating Saxon with other applications. It has been designed with extensibility
015: * and stability in mind. However, it should be considered as an interface designed primarily for
016: * internal use, and not as a completely stable part of the public Saxon API.
017: * <p>
018: * @author Michael H. Kay
019: */
020:
021: public interface Receiver extends Result {
022:
023: /**
024: * Set the pipeline configuration
025: */
026:
027: public void setPipelineConfiguration(PipelineConfiguration config);
028:
029: /**
030: * Get the pipeline configuration
031: */
032:
033: public PipelineConfiguration getPipelineConfiguration();
034:
035: /**
036: * Set the System ID of the destination tree
037: */
038:
039: public void setSystemId(String systemId);
040:
041: /**
042: * Notify the start of the event stream
043: */
044:
045: public void open() throws XPathException;
046:
047: /**
048: * Notify the start of a document node
049: */
050:
051: public void startDocument(int properties) throws XPathException;
052:
053: /**
054: * Notify the end of a document node
055: */
056:
057: public void endDocument() throws XPathException;
058:
059: /**
060: * Notify an unparsed entity URI.
061: * @param name The name of the unparsed entity
062: * @param systemID The system identifier of the unparsed entity
063: * @param publicID The public identifier of the unparsed entity
064: */
065:
066: public void setUnparsedEntity(String name, String systemID,
067: String publicID) throws XPathException;
068:
069: /**
070: * Notify the start of an element
071: * @param nameCode integer code identifying the name of the element within the name pool.
072: * @param typeCode integer code identifying the element's type within the name pool. The value -1
073: * indicates the default type, xdt:untyped.
074: * @param locationId an integer which can be interpreted using a LocationMap to return
075: * information such as line number and system ID. If no location information is available,
076: * the value zero is supplied.
077: * @param properties bit-significant properties of the element node. If there are no revelant
078: * properties, zero is supplied.
079: */
080:
081: public void startElement(int nameCode, int typeCode,
082: int locationId, int properties) throws XPathException;
083:
084: /**
085: * Notify a namespace. Namespaces are notified <b>after</b> the startElement event, and before
086: * any children for the element. The namespaces that are reported are only required
087: * to include those that are different from the parent element. The events represent namespace
088: * declarations and undeclarations rather than in-scope namespace nodes: an undeclaration is represented
089: * by a namespace code of zero. If the sequence of namespace events contains two
090: * A namespace must not conflict with any namespaces already used for element or attribute names.
091: * @param namespaceCode an integer: the top half is a prefix code, the bottom half a URI code.
092: * These may be translated into an actual prefix and URI using the name pool. A prefix code of
093: * zero represents the empty prefix (that is, the default namespace). A URI code of zero represents
094: * a URI of "", that is, a namespace undeclaration.
095: * @param properties The most important property is REJECT_DUPLICATES. If this property is set, the
096: * namespace declaration will be rejected if it conflicts with a previous declaration of the same
097: * prefix. If the property is not set, the namespace declaration will be ignored if it conflicts
098: * with a previous declaration. This reflects the fact that when copying a tree, namespaces for child
099: * elements are emitted before the namespaces of their parent element. Unfortunately this conflicts
100: * with the XSLT rule for complex content construction, where the recovery action in the event of
101: * conflicts is to take the namespace that comes last. XSLT therefore doesn't recover from this error:
102: * it sets the REJECT_DUPLICATES flag, and this is treated as a hard error.
103: */
104:
105: public void namespace(int namespaceCode, int properties)
106: throws XPathException;
107:
108: /**
109: * Notify an attribute. Attributes are notified after the startElement event, and before any
110: * children. Namespaces and attributes may be intermingled.
111: * @param nameCode The name of the attribute, as held in the name pool
112: * @param typeCode The type of the attribute, as held in the name pool. The additional bit
113: * NodeInfo.IS_DTD_TYPE may be set to indicate a DTD-derived type.
114: * @param locationId an integer which can be interpreted using a LocationMap to return
115: * information such as line number and system ID. If no location information is available,
116: * the value zero is supplied.
117: * @param properties Bit significant value. The following bits are defined:
118: * <dt>DISABLE_ESCAPING</dt> <dd>Disable escaping for this attribute</dd>
119: * <dt>NO_SPECIAL_CHARACTERS</dt> <dd>Attribute value contains no special characters</dd>
120: * @throws IllegalStateException: attempt to output an attribute when there is no open element
121: * start tag
122: */
123:
124: public void attribute(int nameCode, int typeCode,
125: CharSequence value, int locationId, int properties)
126: throws XPathException;
127:
128: /**
129: * Notify the start of the content, that is, the completion of all attributes and namespaces.
130: * Note that the initial receiver of output from XSLT instructions will not receive this event,
131: * it has to detect it itself. Note that this event is reported for every element even if it has
132: * no attributes, no namespaces, and no content.
133: */
134:
135: public void startContent() throws XPathException;
136:
137: /**
138: * Notify the end of an element. The receiver must maintain a stack if it needs to know which
139: * element is ending.
140: */
141:
142: public void endElement() throws XPathException;
143:
144: /**
145: * Notify character data. Note that some receivers may require the character data to be
146: * sent in a single event, but in general this is not a requirement.
147: * @param chars The characters
148: * @param locationId an integer which can be interpreted using a LocationMap to return
149: * information such as line number and system ID. If no location information is available,
150: * the value zero is supplied.
151: * @param properties Bit significant value. The following bits are defined:
152: * <dt>DISABLE_ESCAPING</dt> <dd>Disable escaping for this text node</dd>
153: * <dt>USE_CDATA</dt> <dd>Output as a CDATA section</dd>
154: * <dt>NO_SPECIAL_CHARACTERS</dt> <dd>Value contains no special characters</dd>
155: * <dt>WHITESPACE</dt> <dd>Text is all whitespace</dd>
156: */
157:
158: public void characters(CharSequence chars, int locationId,
159: int properties) throws XPathException;
160:
161: /**
162: * Output a processing instruction
163: * @param name The PI name. This must be a legal name (it will not be checked).
164: * @param data The data portion of the processing instruction
165: * @param locationId an integer which can be interpreted using a LocationMap to return
166: * information such as line number and system ID. If no location information is available,
167: * the value zero is supplied.
168: * @param properties Additional information about the PI. The following bits are
169: * defined:
170: * <dt>CHECKED</dt> <dd>Data is known to be legal (e.g. doesn't contain "?>")</dd>
171: * @throws IllegalArgumentException: the content is invalid for an XML processing instruction
172: */
173:
174: public void processingInstruction(String name, CharSequence data,
175: int locationId, int properties) throws XPathException;
176:
177: /**
178: * Notify a comment. Comments are only notified if they are outside the DTD.
179: * @param content The content of the comment
180: * @param locationId an integer which can be interpreted using a LocationMap to return
181: * information such as line number and system ID. If no location information is available,
182: * the value zero is supplied.
183: * @param properties Additional information about the comment. The following bits are
184: * defined:
185: * <dt>CHECKED</dt> <dd>Comment is known to be legal (e.g. doesn't contain "--")</dd>
186: * @throws IllegalArgumentException: the content is invalid for an XML comment
187: */
188:
189: public void comment(CharSequence content, int locationId,
190: int properties) throws XPathException;
191:
192: /**
193: * Notify the end of the event stream
194: */
195:
196: public void close() throws XPathException;
197:
198: }
199:
200: //
201: // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
202: // you may not use this file except in compliance with the License. You may obtain a copy of the
203: // License at http://www.mozilla.org/MPL/
204: //
205: // Software distributed under the License is distributed on an "AS IS" basis,
206: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
207: // See the License for the specific language governing rights and limitations under the License.
208: //
209: // The Original Code is: all this file.
210: //
211: // The Initial Developer of the Original Code is Michael H. Kay
212: //
213: // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
214: //
215: // Contributor(s): none.
216: //
|