001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions Copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2006-2009 Sun Microsystems, Inc. 015 * Portions copyright 2011-2016 ForgeRock AS. 016 */ 017package org.forgerock.opendj.io; 018 019import java.io.Closeable; 020import java.io.Flushable; 021import java.io.IOException; 022 023import org.forgerock.opendj.ldap.ByteSequence; 024 025/** 026 * An interface for encoding ASN.1 elements to a data source. 027 * <p> 028 * Methods for creating {@link ASN1Writer}s are provided in the {@link ASN1} 029 * class. 030 */ 031public interface ASN1Writer extends Closeable, Flushable { 032 033 /** 034 * Closes this ASN.1 writer, flushing it first. Closing a previously closed 035 * ASN.1 writer has no effect. Any unfinished sequences and/or sets will be 036 * ended. 037 * 038 * @throws IOException 039 * If an error occurs while closing. 040 */ 041 @Override 042 void close() throws IOException; 043 044 /** 045 * Flushes this ASN.1 writer so that any buffered elements are written 046 * immediately to their intended destination. Then, if that destination is 047 * another byte stream, flush it. Thus one {@code flush()} invocation will 048 * flush all the buffers in a chain of streams. 049 * <p> 050 * If the intended destination of this stream is an abstraction provided by 051 * the underlying operating system, for example a file, then flushing the 052 * stream guarantees only that bytes previously written to the stream are 053 * passed to the operating system for writing; it does not guarantee that 054 * they are actually written to a physical device such as a disk drive. 055 * 056 * @throws IOException 057 * If an error occurs while flushing. 058 */ 059 @Override 060 void flush() throws IOException; 061 062 /** 063 * Writes a boolean element using the Universal Boolean ASN.1 type tag. 064 * 065 * @param value 066 * The boolean value. 067 * @return A reference to this ASN.1 writer. 068 * @throws IOException 069 * If an error occurs while writing the element. 070 */ 071 ASN1Writer writeBoolean(boolean value) throws IOException; 072 073 /** 074 * Writes a boolean element using the provided type tag. 075 * 076 * @param type 077 * The type tag of the element. 078 * @param value 079 * The boolean value. 080 * @return A reference to this ASN.1 writer. 081 * @throws IOException 082 * If an error occurs while writing the element. 083 */ 084 ASN1Writer writeBoolean(byte type, boolean value) throws IOException; 085 086 /** 087 * Finishes writing a sequence element. 088 * 089 * @return A reference to this ASN.1 writer. 090 * @throws IOException 091 * If an error occurs while writing the element. 092 * @throws IllegalStateException 093 * If there is no sequence being written. 094 */ 095 ASN1Writer writeEndSequence() throws IOException; 096 097 /** 098 * Finishes writing a set element. 099 * 100 * @return A reference to this ASN.1 writer. 101 * @throws IOException 102 * If an error occurs while writing the element. 103 * @throws IllegalStateException 104 * If there is no set being written. 105 */ 106 ASN1Writer writeEndSet() throws IOException; 107 108 /** 109 * Writes an enumerated element using the provided type tag. 110 * 111 * @param type 112 * The type tag of the element. 113 * @param value 114 * The enumerated value. 115 * @return A reference to this ASN.1 writer. 116 * @throws IOException 117 * If an error occurs while writing the element. 118 */ 119 ASN1Writer writeEnumerated(byte type, int value) throws IOException; 120 121 /** 122 * Writes an enumerated element using the Universal Enumerated ASN.1 type 123 * tag. 124 * 125 * @param value 126 * The enumerated value. 127 * @return A reference to this ASN.1 writer. 128 * @throws IOException 129 * If an error occurs while writing the element. 130 */ 131 ASN1Writer writeEnumerated(int value) throws IOException; 132 133 /** 134 * Writes an integer element using the provided type tag. 135 * 136 * @param type 137 * The type tag of the element. 138 * @param value 139 * The integer value. 140 * @return A reference to this ASN.1 writer. 141 * @throws IOException 142 * If an error occurs while writing the element. 143 */ 144 ASN1Writer writeInteger(byte type, int value) throws IOException; 145 146 /** 147 * Writes an integer element using the provided type tag. 148 * 149 * @param type 150 * The type tag of the element. 151 * @param value 152 * The integer value. 153 * @return A reference to this ASN.1 writer. 154 * @throws IOException 155 * If an error occurs while writing the element. 156 */ 157 ASN1Writer writeInteger(byte type, long value) throws IOException; 158 159 /** 160 * Writes an integer element using the Universal Integer ASN.1 type tag. 161 * 162 * @param value 163 * The integer value. 164 * @return A reference to this ASN.1 writer. 165 * @throws IOException 166 * If an error occurs while writing the element. 167 */ 168 ASN1Writer writeInteger(int value) throws IOException; 169 170 /** 171 * Writes an integer element using the Universal Integer ASN.1 type tag. 172 * 173 * @param value 174 * The integer value. 175 * @return A reference to this ASN.1 writer. 176 * @throws IOException 177 * If an error occurs while writing the element. 178 */ 179 ASN1Writer writeInteger(long value) throws IOException; 180 181 /** 182 * Writes a null element using the Universal Null ASN.1 type tag. 183 * 184 * @return A reference to this ASN.1 writer. 185 * @throws IOException 186 * If an error occurs while writing the element. 187 */ 188 ASN1Writer writeNull() throws IOException; 189 190 /** 191 * Writes a null element using the provided type tag. 192 * 193 * @param type 194 * The type tag of the element. 195 * @return A reference to this ASN.1 writer. 196 * @throws IOException 197 * If an error occurs while writing the element. 198 */ 199 ASN1Writer writeNull(byte type) throws IOException; 200 201 /** 202 * Writes an octet string element using the provided type tag. 203 * 204 * @param type 205 * The type tag of the element. 206 * @param value 207 * The byte array containing the octet string data. 208 * @return A reference to this ASN.1 writer. 209 * @throws IOException 210 * If an error occurs while writing the element. 211 */ 212 ASN1Writer writeOctetString(byte type, byte[] value) throws IOException; 213 214 /** 215 * Writes an octet string element using the provided type tag. 216 * 217 * @param type 218 * The type tag of the element. 219 * @param value 220 * The byte array containing the octet string data. 221 * @param offset 222 * The offset in the byte array. 223 * @param length 224 * The number of bytes to write. 225 * @return A reference to this ASN.1 writer. 226 * @throws IOException 227 * If an error occurs while writing the element. 228 */ 229 ASN1Writer writeOctetString(byte type, byte[] value, int offset, int length) throws IOException; 230 231 /** 232 * Writes an octet string element using the provided type tag. 233 * 234 * @param type 235 * The type tag of the element. 236 * @param value 237 * The octet string value. 238 * @return A reference to this ASN.1 writer. 239 * @throws IOException 240 * If an error occurs while writing the element. 241 */ 242 ASN1Writer writeOctetString(byte type, ByteSequence value) throws IOException; 243 244 /** 245 * Writes a string as a UTF-8 encoded octet string element using the 246 * provided type tag. 247 * 248 * @param type 249 * The type tag of the element. 250 * @param value 251 * The string to be written as a UTF-8 encoded octet string. 252 * @return A reference to this ASN.1 writer. 253 * @throws IOException 254 * If an error occurs while writing the element. 255 */ 256 ASN1Writer writeOctetString(byte type, String value) throws IOException; 257 258 /** 259 * Writes an octet string element using the Universal Octet String ASN.1 260 * type tag. 261 * 262 * @param value 263 * The byte array containing the octet string data. 264 * @return A reference to this ASN.1 writer. 265 * @throws IOException 266 * If an error occurs while writing the element. 267 */ 268 ASN1Writer writeOctetString(byte[] value) throws IOException; 269 270 /** 271 * Writes an octet string element using the Universal Octet String ASN.1 272 * type tag. 273 * 274 * @param value 275 * The byte array containing the octet string data. 276 * @param offset 277 * The offset in the byte array. 278 * @param length 279 * The number of bytes to write. 280 * @return A reference to this ASN.1 writer. 281 * @throws IOException 282 * If an error occurs while writing the element. 283 */ 284 ASN1Writer writeOctetString(byte[] value, int offset, int length) throws IOException; 285 286 /** 287 * Writes an octet string element using the Universal Octet String ASN.1 288 * type tag. 289 * 290 * @param value 291 * The octet string value. 292 * @return A reference to this ASN.1 writer. 293 * @throws IOException 294 * If an error occurs while writing the element. 295 */ 296 ASN1Writer writeOctetString(ByteSequence value) throws IOException; 297 298 /** 299 * Writes a string as a UTF-8 encoded octet string element using the 300 * Universal Octet String ASN.1 type tag. 301 * 302 * @param value 303 * The string to be written as a UTF-8 encoded octet string. 304 * @return A reference to this ASN.1 writer. 305 * @throws IOException 306 * If an error occurs while writing the element. 307 */ 308 ASN1Writer writeOctetString(String value) throws IOException; 309 310 /** 311 * Writes a sequence element using the Universal Sequence ASN.1 type tag. 312 * All further writes will append elements to the sequence until 313 * {@link #writeEndSequence} is called. 314 * 315 * @return A reference to this ASN.1 writer. 316 * @throws IOException 317 * If an error occurs while writing the element. 318 */ 319 ASN1Writer writeStartSequence() throws IOException; 320 321 /** 322 * Writes a sequence element using the provided type tag. All further writes 323 * will append elements to the sequence until {@link #writeEndSequence} is 324 * called. 325 * 326 * @param type 327 * The type tag of the element. 328 * @return A reference to this ASN.1 writer. 329 * @throws IOException 330 * If an error occurs while writing the element. 331 */ 332 ASN1Writer writeStartSequence(byte type) throws IOException; 333 334 /** 335 * Writes a set element using the Universal Set ASN.1 type tag. All further 336 * writes will append elements to the set until {@link #writeEndSet} is 337 * called. 338 * 339 * @return A reference to this ASN.1 writer. 340 * @throws IOException 341 * If an error occurs while writing the element. 342 */ 343 ASN1Writer writeStartSet() throws IOException; 344 345 /** 346 * Writes a set element using the provided type tag. All further writes will 347 * append elements to the set until {@link #writeEndSet} is called. 348 * 349 * @param type 350 * The type tag of the element. 351 * @return A reference to this ASN.1 writer. 352 * @throws IOException 353 * If an error occurs while writing the element. 354 */ 355 ASN1Writer writeStartSet(byte type) throws IOException; 356}