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