/* * 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 legal-notices/CDDLv1_0.txt * or http://forgerock.org/license/CDDLv1.0.html. * 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 legal-notices/CDDLv1_0.txt. * 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. *

* 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 true if another complete element is available or * false 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 true if another element is available or * false 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: * *

   * readOctetStringAsString("UTF-8");
   * 
* * @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; }