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}