1/*
2 * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 *
25 * THIS FILE WAS MODIFIED BY SUN MICROSYSTEMS, INC.
26 */
27
28package com.sun.xml.internal.org.jvnet.fastinfoset.stax;
29
30import java.io.IOException;
31import javax.xml.stream.XMLStreamException;
32
33/**
34 * Low level Fast Infoset stream writer.
35 * <p>
36 * This interface provides additional stream-based serialization methods for the
37 * case where an application is in specific control of the serialization
38 * process and has the knowledge to call the LowLevel methods in the required
39 * order.
40 * <p>
41 * For example, the application may be able to perform efficient information
42 * to indexing mapping and to provide certain information in UTF-8 encoded form.
43 * <p>
44 * These methods may be used in conjuction with {@link javax.xml.stream.XMLStreamWriter}
45 * as long as an element fragment written using the efficient streaming methods
46 * are self-contained and no sub-fragment is written using methods from
47 * {@link javax.xml.stream.XMLStreamWriter}.
48 * <p>
49 * The required call sequence is as follows:
50 * <pre>
51 * CALLSEQUENCE    := {@link #startDocument startDocument}
52 *                    initiateLowLevelWriting ELEMENT
53 *                    {@link #endDocument endDocument}
54 *                 |  initiateLowLevelWriting ELEMENT   // for fragment
55 *
56 * ELEMENT         := writeLowLevelTerminationAndMark
57 *                    NAMESPACES?
58 *                    ELEMENT_NAME
59 *                    ATTRIBUTES?
60 *                    writeLowLevelEndStartElement
61 *                    CONTENTS
62 *                    writeLowLevelEndElement
63 *
64 * NAMESPACES      := writeLowLevelStartNamespaces
65 *                    writeLowLevelNamespace*
66 *                    writeLowLevelEndNamespaces
67 *
68 * ELEMENT_NAME    := writeLowLevelStartElementIndexed
69 *                 |  writeLowLevelStartNameLiteral
70 *                 |  writeLowLevelStartElement
71 *
72 * ATTRUBUTES      := writeLowLevelStartAttributes
73 *                   (ATTRIBUTE_NAME writeLowLevelAttributeValue)*
74 *
75 * ATTRIBUTE_NAME  := writeLowLevelAttributeIndexed
76 *                 |  writeLowLevelStartNameLiteral
77 *                 |  writeLowLevelAttribute
78 *
79 *
80 * CONTENTS      := (ELEMENT | writeLowLevelText writeLowLevelOctets)*
81 * </pre>
82 * <p>
83 * Some methods defer to the application for the mapping of information
84 * to indexes.
85 */
86public interface LowLevelFastInfosetStreamWriter {
87    /**
88     * Initiate low level writing of an element fragment.
89     * <p>
90     * This method must be invoked before other low level method.
91     */
92    public void initiateLowLevelWriting()
93    throws XMLStreamException;
94
95    /**
96     * Get the next index to apply to an Element Information Item.
97     * <p>
98     * This will increment the next obtained index such that:
99     * <pre>
100     * i = w.getNextElementIndex();
101     * j = w.getNextElementIndex();
102     * i == j + 1;
103     * </pre>
104     * @return the index.
105     */
106    public int getNextElementIndex();
107
108    /**
109     * Get the next index to apply to an Attribute Information Item.
110     * This will increment the next obtained index such that:
111     * <pre>
112     * i = w.getNextAttributeIndex();
113     * j = w.getNextAttributeIndex();
114     * i == j + 1;
115     * </pre>
116     * @return the index.
117     */
118    public int getNextAttributeIndex();
119
120    /**
121     * Get the current index that was applied to an [local name] of an
122     * Element or Attribute Information Item.
123     * </pre>
124     * @return the index.
125     */
126    public int getLocalNameIndex();
127
128    /**
129     * Get the next index to apply to an [local name] of an Element or Attribute
130     * Information Item.
131     * This will increment the next obtained index such that:
132     * <pre>
133     * i = w.getNextLocalNameIndex();
134     * j = w.getNextLocalNameIndex();
135     * i == j + 1;
136     * </pre>
137     * @return the index.
138     */
139    public int getNextLocalNameIndex();
140
141    public void writeLowLevelTerminationAndMark()
142    throws IOException;
143
144    public void writeLowLevelStartElementIndexed(int type, int index)
145    throws IOException;
146
147    /**
148     * Write the start of an element.
149     *
150     * @return true if element is indexed, otherwise false.
151     */
152    public boolean writeLowLevelStartElement(int type,
153            String prefix, String localName, String namespaceURI)
154            throws IOException;
155
156    public void writeLowLevelStartNamespaces()
157    throws IOException;
158
159    public void writeLowLevelNamespace(String prefix, String namespaceName)
160        throws IOException;
161
162    public void writeLowLevelEndNamespaces()
163    throws IOException;
164
165    public void writeLowLevelStartAttributes()
166    throws IOException;
167
168    public void writeLowLevelAttributeIndexed(int index)
169    throws IOException;
170
171    /**
172     * Write an attribute.
173     *
174     * @return true if attribute is indexed, otherwise false.
175     */
176    public boolean writeLowLevelAttribute(
177            String prefix, String namespaceURI, String localName)
178            throws IOException;
179
180    public void writeLowLevelAttributeValue(String value)
181    throws IOException;
182
183    public void writeLowLevelStartNameLiteral(int type,
184            String prefix, byte[] utf8LocalName, String namespaceURI)
185            throws IOException;
186
187    public void writeLowLevelStartNameLiteral(int type,
188            String prefix, int localNameIndex, String namespaceURI)
189            throws IOException;
190
191    public void writeLowLevelEndStartElement()
192    throws IOException;
193
194    public void writeLowLevelEndElement()
195    throws IOException;
196
197    public void writeLowLevelText(char[] text, int length)
198    throws IOException;
199
200    public void writeLowLevelText(String text)
201    throws IOException;
202
203    public void writeLowLevelOctets(byte[] octets, int length)
204    throws IOException;
205}
206