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}