Interface SequenceOfDecoder

This interface provides methods for decoding elements from an encoded SEQUENCE OF <ElementType> collection, where ElementType is a uniform ASN.1 type. An application specifies this type when it creates a decoder. On creation, a SEQUENCE OF decoder determines the total size of encoded elements enclosed in the SEQUENCE OF and sets the current element pointer to the first encoded element. Each decode method of the interface decodes an element at the current position as being of the type implied by the method. Note that implicitly or explicitly tagged elements are not allowed.

Interface declaration:

public interface SequenceOfDecoder {
    int count() throws FormatAsnException;
    boolean hasNext();
    void skip() throws AsnException;
    boolean isNull() throws AsnException;
	
    SequenceDecoder Sequence() throws AsnException;
    SequenceOfDecoder SequenceOf(UType uType) throws AsnException;
    int Int32() throws AsnException;
    int Int32(int minValue, int maxValue) throws AsnException;
    long Int64() throws AsnException;
    boolean Boolean() throws AsnException;
    float Real32() throws AsnException;
    float Real32(boolean checkForUnderflow) throws AsnException;
    double Real64() throws AsnException;
    double Real64(boolean checkForUnderflow) throws AsnException;
    String UTF8String() throws AsnException;
    String UTF8String(int requiredLength) throws AsnException;
    String UTF8String(int minLength, int maxLength) throws AsnException;
    String BMPString() throws AsnException;
    String BMPString(int requiredLength) throws AsnException;
    String BMPString(int minLength, int maxLength) throws AsnException;
    String IA5String() throws AsnException;
    String IA5String(int requiredLength) throws AsnException;
    String IA5String(int minLength, int maxLength) throws AsnException;
    String PrintableString() throws AsnException;
    java.util.GregorianCalendar GndTimeToGC() throws AsnException;
    byte[] OctetString() throws AsnException;
    byte[] OctetString(int requiredLength) throws AsnException;
    byte[] OctetString(int minLength, int maxLength) throws AsnException;
}

Interface method descriptions:

  • count

      int count() throws FormatAsnException;

    Returns the number of elements in the encoding of a SEQUENCE OF.
    Exceptions: FormatAsnException;

  • hasNext

      boolean hasNext();

    Checks if the SEQUENCE OF decoder has another element to decode.
    Exceptions: no exceptions;

  • skip

      void skip() throws AsnException;

    Skips the current element of the encoded SEQUENCE OF and moves the pointer to the next element.
    Exceptions: FormatAsnException, EndOfContainerAsnException;

  • isNull

      boolean isNull() throws EndOfContainerAsnException;

    Checks if the current element in the SEQUENCE OF encoding is ASN.1 NULL. Handling NULL elements is described in the Handling ASN.1 NULL subsection of “Interface SequenceDecoder”.
    Exceptions: FormatAsnException, EndOfContainerAsnException;

  • Sequence

      SequenceDecoder Sequence() throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.Sequence as a uniform type of the elements to decode a SEQUENCE OF SEQUENCE collection. The method creates a decoder of type SequenceDecoder that allows an application to decode a nested SEQUENCE from the current position of the encoded collection of sequences and returns the decoder to the application.
    Exceptions: Standard Exceptions;

  • SequenceOf

      SequenceOfDecoder SequenceOf(UType uType)

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.Sequence as a uniform type of the elements to decode a SEQUENCE OF SEQUENCE collection. The method creates a decoder for a nested SEQUENCE OF uType collection, where uType is an ASN.1 type provided as an argument on the method call.
    Exceptions: Standard Exceptions;

  • Int32

      int Int32() throws AsnException;
  int Int32(int minValue, int maxValue) throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.Integer as a uniform type of the elements to decode a SEQUENCE OF INTEGER collection. The method decodes the current element of the encoded collection as being of ASN.1 INTEGER and returns it to the application as a 32-bit Java integer. If the decoded value doesn’t fit to 32-bit integer, an exception of type OverflowAsnException is thrown. For example, this can happen if the value encoded in the current element was originally a 64-bit integer. As for the overload of Int32 with minValue and maxValue parameters, it allows an application to apply constraints on the value being decoded. If it doesn’t fit to the range [minValue, maxValue] inclusive, an exception of type ConstraintAsnException is thrown.
    Exceptions:

    • Standard Exceptions;
    • OverflowAsnException;
    • ConstraintAsnException can be thrown only by the Int32 overloads with minValue and maxValue constraint parameters;

  • Int64

      long Int64() throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.Integer as a uniform type of the elements to decode a SEQUENCE OF INTEGER collection. The method decodes the current element of the encoded collection as being of ASN.1 INTEGER and returns a 64-bit Java integer value to the application. If the decoded value doesn’t fit to 64-bit Java integer, an exception of type OverflowAsnException is thrown.
    Exceptions: Standard Exceptions, OverflowAsnException;

  • Boolean

      boolean Boolean() throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.Boolean as a uniform type of the elements to decode a SEQUENCE OF BOOLEAN collection. The method decodes the current element of the encoded collection as being of ASN.1 BOOLEAN and returns a Java boolean value to the application.
    Exceptions: Standard Exceptions;

  • Real32

      float Real32() throws AsnException;
  float Real32(boolean checkForUnderflow) throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.Real as a uniform type of the elements to decode a SEQUENCE OF REAL collection. The method decodes the current element of the encoded collection as being of ASN.1 REAL and returns a 32-bit Java float value to the application. If the decoded value is out of range [Float.MAX_VALUE, Float.MIN_VALUE], an OverflowAsnException is thrown. Such can happen if the value encoded in this ASN.1 REAL element was originally a 64-bit floating point value. The other edge case is when an ASN.1 REAL element cannot be decoded as a 32-bit Java float without losing precision. If you want to detect loss of precision with throwing UnderflowAsnException, call the Real32 overload with true for the checkForUnderflow parameter. Losing precision can happen if the value encoded in ASN.1 REAL element was originally a 64-bit floating point value.
    Exceptions: Standard Exceptions, OverflowAsnException, UnderflowAsnException;

  • Real64

      double Real64() throws AsnException;
  double Real64(boolean checkForUnderflow) throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.Real as a uniform type of the elements to decode a SEQUENCE OF REAL collection. The method decodes the current element of the encoded collection as being of ASN.1 REAL and returns a 64-bit Java double to the application. If the decoded value is out of range [Double.MAX_VALUE, Double.MIN_VALUE], an OverflowAsnException is thrown. The other edge case is when an ASN.1 REAL element cannot be decoded as a 64-bit Java double without losing precision. If you want to detect loss of precision with throwing UnderflowAsnException, call the Real64 overload with true for the checkForUnderflow parameter.
    Exceptions: Standard Exceptions, OverflowAsnException, UnderflowAsnException;

  • UTF8String

      String UTF8String() throws AsnException;
  String UTF8String(int requiredLength) throws AsnException;
  String UTF8String(int minLength, int maxLength) throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.UTF8String as a uniform type of the elements to decode a SEQUENCE OF UTF8String collection. The method decodes the current element of the encoded collection as being of ASN.1 UTF8String and returns a Java String value to the application. If an application expects a string of a specific length, it can call the method overload with the requiredLength parameter. If the length is limited to a certain range, it can call the method overload with the minLength and maxLength parameters. If the decoded value does not conform to the constraints, an exception of type ConstraintAsnException is thrown.
    Exceptions: Standard Exceptions, ConstraintAsnException;

  • BMPString

      String BMPString() throws AsnException;
  String BMPString(int requiredLength) throws AsnException;
  String BMPString(int minLength, int maxLength) throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.BMPString as a uniform type of the elements to decode a SEQUENCE OF BMPString collection. The method decodes the current element of the encoded collection as being of ASN.1 BMPString and returns a Java String value to the application. If an application expects a string of a specific length, it can call the method overload with the requiredLength parameter. If the length is limited to a certain range, it can call the method overload with the minLength and maxLength parameters. If the decoded value does not conform to the constraints, an exception of type ConstraintAsnException is thrown.
    Exceptions: Standard Exceptions, ConstraintAsnException;

  • IA5String

      String IA5String() throws AsnException;
  String IA5String(int requiredLength) throws AsnException;
  String IA5String(int minLength, int maxLength) throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.IA5String as a uniform type of the elements to decode a SEQUENCE OF IA5String collection. The method decodes the current element of the encoded collection as being of ASN.1 IA5String and returns a Java String value to the application. If an application expects a string of a specific length, it can call the method overload with the requiredLength parameter. If the length is limited to a certain range, it can call the method overload with the minLength and maxLength parameters. If the decoded value does not conform to the constraints, an exception of type ConstraintAsnException is thrown.
    Exceptions: Standard Exceptions, ConstraintAsnException;

  • PrintableString

      String PrintableString() throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.PrintableString as a uniform type of the elements to decode a SEQUENCE OF PrintableString collection. The method decodes the current element of the encoded collection as being of ASN.1 PrintableString and returns a Java String value to the application.
    Exceptions: Standard Exceptions;

  • GndTimeToGC

      java.util.GregorianCalendar GndTimeToGC() throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.GeneralizedTime as a uniform type of the elements to decode a SEQUENCE OF GeneralizedTime collection. The method decodes the current element of the encoded collection as being of ASN.1 GeneralizedTime and returns a GregorianCalendar instance to the application.
    Exceptions: Standard Exceptions;

  • OctetString

      byte[] OctetString() throws AsnException;
  byte[] OctetString(int requiredLength) throws AsnException;
  byte[] OctetString(int minLength, int maxLength) throws AsnException;

    This method is allowed to call if the SEQUENCE OF <ElementType> decoder was created by specifying UType.OctetString as a uniform type of the elements to decode a SEQUENCE OF OctetString collection. The method decodes the current element of the encoded collection as being of ASN.1 OctetString and returns a Java byte array to the application. If an application expects a byte array of a specific length, it can call the method overload with the requiredLength parameter. If the length is limited to a certain range, it can call the method overload with the minLength and maxLength parameters. If the decoded byte array does not conform to the constraints, an exception of type ConstraintAsnException is thrown.
    Exceptions: Standard Exceptions, ConstraintAsnException.

A use case for the SequenceOfDecoder interface:

This is a continuation of the example from “Interface SequenceOfEncoder “. That example demonstrates the process of encoding a list of integers using a SEQUENCE OF encoder. This example demonstrates the reverse process of decoding an encoded list of integers using a SEQUENCE OF decoder. The process is implemented in the decodeList method, which accepts the input data through the encoding parameter. It performs the following operations:

  1. Calls the static Sequence method of the base class ASNDecoder to create a decoder for the outermost SEQUENCE. It’s named asnStructure;
  2. Calls the SequenceOf method of asnStructure with UType.Integer as an argument to create a decoder for the SEQUENCE OF INTEGER collection. The decoder is named asnCollection;
  3. In the “for” circle, fills the list of integers with decoded elements;
  4. Returns the list of integers.

Here’s the ASN.1 data structure syntax:

DataStructure ::= SEQUENCE {
    integerCollection   SEQUENCE OF INTEGER
}

And here’s the decoding process:

public ArrayList<Integer> decodeList(byte[] encoding) throws AsnException
{
    SequenceDecoder asnStructure = ASNDecoder.Sequence(encoding);
    SequenceOfDecoder asnCollection = asnStructure.SequenceOf(UType.Integer);
        
    ArrayList<Integer> integerList = new ArrayList<Integer>(); 
    while(asnCollection.hasNext()) {
        integerList.add(asnCollection.Int32());
    }		
    return integerList;
}

TABLE OF CONTENTS