/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at
* trunk/opends/resource/legal-notices/OpenDS.LICENSE
* or https://OpenDS.dev.java.net/OpenDS.LICENSE.
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at
* trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
* add the following below this CDDL HEADER, with the fields enclosed
* by brackets "[]" replaced with your own identifying information:
* Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*
*
* Copyright 2006-2009 Sun Microsystems, Inc.
* Portions Copyright 2012 Forgerock AS
*/
package org.opends.server.protocols.asn1;
import java.io.Closeable;
import java.io.IOException;
import org.opends.server.types.ByteString;
import org.opends.server.types.ByteStringBuilder;
/**
* An interface for decoding ASN.1 elements from a data source.
* <p>
* Methods for creating {@link ASN1Reader}s are provided in the
* {@link ASN1} class.
*/
public interface ASN1Reader extends Closeable
{
/**
* Closes this ASN.1 reader.
*
* @throws IOException if an I/O error occurs
*/
void close() throws IOException;
/**
* Determines if a complete ASN.1 element is waiting to be read.
*
* @return <code>true</code> if another complete element is available or
* <code>false</code> otherwise.
* @throws ASN1Exception If an error occurs while trying to decode
* an ASN1 element.
*/
public boolean elementAvailable() throws ASN1Exception;
/**
* Determines if at least one ASN.1 element is waiting to be read.
*
* @return <code>true</code> if another element is available or
* <code>false</code> if the EOF is reached.
* @throws ASN1Exception
* If an error occurs while trying to decode an ASN1
* element.
*/
boolean hasNextElement() throws ASN1Exception;
/**
* Gets the data length of the next element without actually reading
* the element and advancing the cursor.
*
* @return The data length of the next element or -1 if the EOF is
* encountered.
* @throws ASN1Exception
* If an error occurs while determining the length.
*/
int peekLength() throws ASN1Exception;
/**
* Gets the BER type of the next element without actually reading
* the element and advancing the cursor.
*
* @return The BER type of the next element or -1 if the EOF is
* encountered.
* @throws ASN1Exception
* If an error occurs while determining the BER type.
*/
byte peekType() throws ASN1Exception;
/**
* Reads the next ASN.1 element as a boolean and advance the cursor.
*
* @return The decoded boolean value.
* @throws ASN1Exception
* If the element cannot be decoded as a boolean.
*/
boolean readBoolean() throws ASN1Exception;
/**
* Finishes reading an explicit tag. Any elements not read in the
* explicit tag will be discarded.
*
* @throws ASN1Exception
* If an error occurs while advancing to the end of the
* explicit tag.
*/
void readEndExplicitTag() throws ASN1Exception;
/**
* Finishes reading a sequence. Any elements not read in the
* sequence will be discarded.
*
* @throws ASN1Exception
* If an error occurs while advancing to the end of the
* sequence.
*/
void readEndSequence() throws ASN1Exception;
/**
* Finishes reading a set. Any elements not read in the set will be
* discarded.
*
* @throws ASN1Exception
* If an error occurs while advancing to the end of the set.
*/
void readEndSet() throws ASN1Exception;
/**
* Reads the next ASN.1 element as an enumerated value and advances
* the cursor.
*
* @return The decoded enumerated value.
* @throws ASN1Exception
* If the element cannot be decoded as an enumerated value.
*/
int readEnumerated() throws ASN1Exception;
/**
* Reads the next ASN.1 element as an integer and advances the
* cursor.
*
* @return The decoded integer value.
* @throws ASN1Exception
* If the element cannot be decoded as a integer.
*/
long readInteger() throws ASN1Exception;
/**
* Reads the next ASN.1 element as a null element and advances the
* cursor.
*
* @throws ASN1Exception
* If the element cannot be decoded as an null element.
*/
void readNull() throws ASN1Exception;
/**
* Reads the next ASN.1 element as an octet string and advances the
* cursor.
*
* @return The decoded octet string value represented using a
* {@link ByteString}.
* @throws ASN1Exception
* If the element cannot be decoded as an octet string.
*/
ByteString readOctetString() throws ASN1Exception;
/**
* Reads the next ASN.1 element as an octet string and advances the
* cursor. The data will be appended to the provided
* {@link ByteStringBuilder}.
*
* @param buffer
* The {@link ByteStringBuilder} to append the data to.
* @throws ASN1Exception
* If the element cannot be decoded as an octet string.
*/
void readOctetString(ByteStringBuilder buffer) throws ASN1Exception;
/**
* Reads the next ASN.1 element as an octet string and advances the
* cursor. The data will be decoded to a UTF-8 string. This method
* is equivalent to:
*
* <pre>
* readOctetStringAsString("UTF-8");
* </pre>
*
* @return The string representation of the octet string data.
* @throws ASN1Exception
* If the element cannot be decoded as an octet string.
*/
String readOctetStringAsString() throws ASN1Exception;
/**
* Reads the next ASN.1 element as an octet string and advances the
* cursor. The data will be decoded to a string using the provided
* character set.
*
* @param charSet
* The character set to use in order to decode the data
* into a string.
* @return The string representation of the octet string data.
* @throws ASN1Exception
* If the element cannot be decoded as an octet string.
*/
String readOctetStringAsString(String charSet) throws ASN1Exception;
/**
* Reads the next ASN.1 element as an explicit tag. All further
* reads will read the elements in the explicit tag until
* {@link #readEndExplicitTag()} is called.
*
* @throws ASN1Exception
* If the next element is not an explicit tag.
*/
void readStartExplicitTag() throws ASN1Exception;
/**
* Reads the next ASN.1 element as a sequence. All further reads
* will read the elements in the sequence until
* {@link #readEndSequence()} is called.
*
* @throws ASN1Exception
* If the next element is not a sequence.
*/
void readStartSequence() throws ASN1Exception;
/**
* Reads the next ASN.1 element as a set. All further reads will read
* the elements in the sequence until {@link #readEndSet()} is called.
*
* @throws ASN1Exception
* If the next element is not a set.
*/
void readStartSet() throws ASN1Exception;
/**
* Advances this ASN.1 reader beyond the next ASN.1 element without
* decoding it.
*
* @throws ASN1Exception
* If the next ASN.1 element could not be skipped.
*/
void skipElement() throws ASN1Exception;
}