Thu, 12 Oct 2017 19:44:07 +0800
merge
1 /*
2 * Copyright (c) 2004, 2011, 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 */
28 package com.sun.xml.internal.org.jvnet.fastinfoset.stax;
30 import java.io.IOException;
31 import javax.xml.stream.XMLStreamException;
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 */
86 public 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;
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();
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();
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();
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();
141 public void writeLowLevelTerminationAndMark()
142 throws IOException;
144 public void writeLowLevelStartElementIndexed(int type, int index)
145 throws IOException;
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;
156 public void writeLowLevelStartNamespaces()
157 throws IOException;
159 public void writeLowLevelNamespace(String prefix, String namespaceName)
160 throws IOException;
162 public void writeLowLevelEndNamespaces()
163 throws IOException;
165 public void writeLowLevelStartAttributes()
166 throws IOException;
168 public void writeLowLevelAttributeIndexed(int index)
169 throws IOException;
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;
180 public void writeLowLevelAttributeValue(String value)
181 throws IOException;
183 public void writeLowLevelStartNameLiteral(int type,
184 String prefix, byte[] utf8LocalName, String namespaceURI)
185 throws IOException;
187 public void writeLowLevelStartNameLiteral(int type,
188 String prefix, int localNameIndex, String namespaceURI)
189 throws IOException;
191 public void writeLowLevelEndStartElement()
192 throws IOException;
194 public void writeLowLevelEndElement()
195 throws IOException;
197 public void writeLowLevelText(char[] text, int length)
198 throws IOException;
200 public void writeLowLevelText(String text)
201 throws IOException;
203 public void writeLowLevelOctets(byte[] octets, int length)
204 throws IOException;
205 }