001: /*
002: * Fast Infoset ver. 0.1 software ("Software")
003: *
004: * Copyright, 2004-2005 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * Software is licensed under the Apache License, Version 2.0 (the "License");
007: * you may not use this file except in compliance with the License. You may
008: * obtain a copy of the License at:
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing, software
013: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015: * License for the specific language governing permissions and limitations.
016: *
017: * Sun supports and benefits from the global community of open source
018: * developers, and thanks the community for its important contributions and
019: * open standards-based technology, which Sun has adopted into many of its
020: * products.
021: *
022: * Please note that portions of Software may be provided with notices and
023: * open source licenses from such communities and third parties that govern the
024: * use of those portions, and any licenses granted hereunder do not alter any
025: * rights and obligations you may have under such open source licenses,
026: * however, the disclaimer of warranty and limitation of liability provisions
027: * in this License will apply to all Software in this distribution.
028: *
029: * You acknowledge that the Software is not designed, licensed or intended
030: * for use in the design, construction, operation or maintenance of any nuclear
031: * facility.
032: *
033: * Apache License
034: * Version 2.0, January 2004
035: * http://www.apache.org/licenses/
036: *
037: */
038:
039: package org.jvnet.fastinfoset.stax;
040:
041: import com.sun.xml.fastinfoset.EncodingConstants;
042: import java.io.IOException;
043: import javax.xml.stream.XMLStreamException;
044: import org.jvnet.fastinfoset.EncodingAlgorithmIndexes;
045:
046: /**
047: * Low level Fast Infoset stream writer.
048: * <p>
049: * This interface provides additional stream-based serialization methods for the
050: * case where an application is in specific control of the serialization
051: * process and has the knowledge to call the LowLevel methods in the required
052: * order.
053: * <p>
054: * For example, the application may be able to perform efficient information
055: * to indexing mapping and to provide certain information in UTF-8 encoded form.
056: * <p>
057: * These methods may be used in conjuction with {@link javax.xml.stream.XMLStreamWriter}
058: * as long as an element fragment written using the efficient streaming methods
059: * are self-contained and no sub-fragment is written using methods from
060: * {@link javax.xml.stream.XMLStreamWriter}.
061: * <p>
062: * The required call sequence is as follows:
063: * <pre>
064: * CALLSEQUENCE := {@link #startDocument startDocument}
065: * initiateLowLevelWriting ELEMENT
066: * {@link #endDocument endDocument}
067: * | initiateLowLevelWriting ELEMENT // for fragment
068: *
069: * ELEMENT := writeLowLevelTerminationAndMark
070: * NAMESPACES?
071: * ELEMENT_NAME
072: * ATTRIBUTES?
073: * writeLowLevelEndStartElement
074: * CONTENTS
075: * writeLowLevelEndElement
076: *
077: * NAMESPACES := writeLowLevelStartNamespaces
078: * writeLowLevelNamespace*
079: * writeLowLevelEndNamespaces
080: *
081: * ELEMENT_NAME := writeLowLevelStartElementIndexed
082: * | writeLowLevelStartNameLiteral
083: * | writeLowLevelStartElement
084: *
085: * ATTRUBUTES := writeLowLevelStartAttributes
086: * (ATTRIBUTE_NAME writeLowLevelAttributeValue)*
087: *
088: * ATTRIBUTE_NAME := writeLowLevelAttributeIndexed
089: * | writeLowLevelStartNameLiteral
090: * | writeLowLevelAttribute
091: *
092: *
093: * CONTENTS := (ELEMENT | writeLowLevelText writeLowLevelOctets)*
094: * </pre>
095: * <p>
096: * Some methods defer to the application for the mapping of information
097: * to indexes.
098: */
099: public interface LowLevelFastInfosetStreamWriter {
100: /**
101: * Initiate low level writing of an element fragment.
102: * <p>
103: * This method must be invoked before other low level method.
104: */
105: public void initiateLowLevelWriting() throws XMLStreamException;
106:
107: /**
108: * Get the next index to apply to an Element Information Item.
109: * <p>
110: * This will increment the next obtained index such that:
111: * <pre>
112: * i = w.getNextElementIndex();
113: * j = w.getNextElementIndex();
114: * i == j + 1;
115: * </pre>
116: * @return the index.
117: */
118: public int getNextElementIndex();
119:
120: /**
121: * Get the next index to apply to an Attribute Information Item.
122: * This will increment the next obtained index such that:
123: * <pre>
124: * i = w.getNextAttributeIndex();
125: * j = w.getNextAttributeIndex();
126: * i == j + 1;
127: * </pre>
128: * @return the index.
129: */
130: public int getNextAttributeIndex();
131:
132: /**
133: * Get the current index that was applied to an [local name] of an
134: * Element or Attribute Information Item.
135: * </pre>
136: * @return the index.
137: */
138: public int getLocalNameIndex();
139:
140: /**
141: * Get the next index to apply to an [local name] of an Element or Attribute
142: * Information Item.
143: * This will increment the next obtained index such that:
144: * <pre>
145: * i = w.getNextLocalNameIndex();
146: * j = w.getNextLocalNameIndex();
147: * i == j + 1;
148: * </pre>
149: * @return the index.
150: */
151: public int getNextLocalNameIndex();
152:
153: public void writeLowLevelTerminationAndMark() throws IOException;
154:
155: public void writeLowLevelStartElementIndexed(int type, int index)
156: throws IOException;
157:
158: /**
159: * Write the start of an element.
160: *
161: * @return true if element is indexed, otherwise false.
162: */
163: public boolean writeLowLevelStartElement(int type, String prefix,
164: String localName, String namespaceURI) throws IOException;
165:
166: public void writeLowLevelStartNamespaces() throws IOException;
167:
168: public void writeLowLevelNamespace(String prefix,
169: String namespaceName) throws IOException;
170:
171: public void writeLowLevelEndNamespaces() throws IOException;
172:
173: public void writeLowLevelStartAttributes() throws IOException;
174:
175: public void writeLowLevelAttributeIndexed(int index)
176: throws IOException;
177:
178: /**
179: * Write an attribute.
180: *
181: * @return true if attribute is indexed, otherwise false.
182: */
183: public boolean writeLowLevelAttribute(String prefix,
184: String namespaceURI, String localName) throws IOException;
185:
186: public void writeLowLevelAttributeValue(String value)
187: throws IOException;
188:
189: public void writeLowLevelStartNameLiteral(int type, String prefix,
190: byte[] utf8LocalName, String namespaceURI)
191: throws IOException;
192:
193: public void writeLowLevelStartNameLiteral(int type, String prefix,
194: int localNameIndex, String namespaceURI) throws IOException;
195:
196: public void writeLowLevelEndStartElement() throws IOException;
197:
198: public void writeLowLevelEndElement() throws IOException;
199:
200: public void writeLowLevelText(char[] text, int length)
201: throws IOException;
202:
203: public void writeLowLevelText(String text) throws IOException;
204:
205: public void writeLowLevelOctets(byte[] octets, int length)
206: throws IOException;
207: }
|