View Javadoc
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   */
27  
28  package com.sun.xml.internal.org.jvnet.fastinfoset.stax;
29  
30  import java.io.IOException;
31  import 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   */
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;
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 }