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