Interface SequenceEncoder

This section provides the description of the SEQUENCE encoder interface. The encoder implements methods for placing structure elements into the SEQUENCE. The elements will be in the order in which they are added to the sequence. Each method, except for the first four, has three overloaded variants. The first variant with a “value” parameter, such as Int32(int value), converts an argument of Java primitive type into a corresponding ASN.1 universal type encoding. The second overloaded method with a “tag” parameter, such as Int32(int tag, int value), creates an implicitly tagged element’s encoding for the “value” parameter. The tag class in this case is ContextSpecific. The tag value must be between 0 and 30 inclusive. And the third overloaded method with a “tc” parameter of type TagClass, such as Int32(int tag, int value, TagClass tc), creates an implicitly tagged element’s encoding with a tag class specified in the tc parameter. Use this overload if you want to encode an implicitly tagged element with a tag class other than ContextSpecific. You can specify one of the three possible tag classes: ContextSpecific, Application or Private. The described scenario is repeated for each method that has three overloads, so the descriptions for the second and third overloads are omitted to avoid cluttering the manual with repetitive information.

ASN.1 tagging is used to avoid ambiguity in the decoding process by providing context for elements and ensuring the correct interpretation of their types. A common scenario where ambiguity can arise is when two elements of the same type are adjacent and the first one is optional. In this case, the decoder does not know if the current element is the first optional or the second mandatory. Typically, applications address this issue by using implicit tags for optional elements, as it helps the decoder distinguish between the optional and mandatory elements. Implicitly tagged elements are created using the method overloads described above.

In most cases, ambiguity can be avoided by using ASN.1 implicit tagging. However, implicit tagging redefines the original context of an element, which in turn can potentially introduce ambiguity. In order to explicitly define the context and ensure unambiguous decoding, explicit tagging is used. It also preserves the original context of the element.

The SequenceEncoder interface declares a Texp method to obtain an encoder of type TexpEncoder that allows an application to create an explicitly tagged element.

Interface declaration:

public interface SequenceEncoder {
	int count();
	int getSize();
		
	TexpEncoder Texp();
	
	SequenceEncoder Sequence();
	SequenceEncoder Sequence(int tag);
	SequenceEncoder Sequence(int tag, TagClass tc);
	
	SequenceOfEncoder SequenceOf(UType uType);	
	SequenceOfEncoder SequenceOf(int tag, UType uType);	
	SequenceOfEncoder SequenceOf(int tag, UType uType, TagClass tc);	

	void Int32(int value);
	void Int32(int tag, int value);
	void Int32(int tag, int value, TagClass tc);

	void Int64(long value);
	void Int64(int tag, long value);
	void Int64(int tag, long value, TagClass tc);

	void Boolean(boolean value);
	void Boolean(int tag, boolean value);
	void Boolean(int tag, boolean value, TagClass tc);

	void Real32(float value);
	void Real32(int tag, float value);
	void Real32(int tag, float value, TagClass tc);
	
	void Real64(double value);
	void Real64(int tag, double value);
	void Real64(int tag, double value, TagClass tc);
	
	void UTF8String(String value);
	void UTF8String(int tag, String value);
	void UTF8String(int tag, String value, TagClass tc);

	void BMPString(String value);
	void BMPString(int tag, String value);
	void BMPString(int tag, String value, TagClass tc);
	
	void IA5String(String value);
	void IA5String(int tag, String value);
	void IA5String(int tag, String value, TagClass tc);
	
	void PrintableString(String value);
	void PrintableString(int tag, String value);
	void PrintableString(int tag, String value, TagClass tc);
	
	void GndTime(java.util.GregorianCalendar value);
	void GndTime(int tag, java.util.GregorianCalendar value);
	void GndTime(int tag, java.util.GregorianCalendar value, TagClass tc);
	
	void OctetString(byte[] buffer);
	void OctetString(int tag, byte[] buffer);
	void OctetString(int tag, byte[] buffer, TagClass tc);
	
	void OctetString(byte[] buffer, int offset, int length);
	void OctetString(int tag, byte[] buffer, int offset, int length);
	void OctetString(int tag, byte[] buffer, int offset, int length, TagClass tc);
	
	void OctetString(java.util.UUID uuid);
	void OctetString(int tag, java.util.UUID uuid);
	void OctetString(int tag, java.util.UUID uuid, TagClass tc);
	
	void Null(); 
}

Interface method descriptions:

Note that interface methods do not allow null for any of the parameters, otherwise an IllegalArgumentException is thrown.

  • count

      int count()

    Returns the number of elements in the SEQUENCE, excluding elements in nested containers;

  • getSize

      int getSize()

    Returns the encoding size in bytes it will have when the encoding is created. The data within all nested containers is also counted. This method is useful if there is a limit for the size of the encoded data;

  • Texp

      TexpEncoder Texp()

    The name “Texp” is derived from “Tag explicit”. This method returns an encoder of type TexpEncoder that allows an application to add an explicitly tagged element to the current position of the SEQUENCE. The application must provide one and only one element to the encoder. The TexpEncoder interface is described in section Interface TexpEncoder;

  • Sequence

      SequenceEncoder Sequence()
  SequenceEncoder Sequence(int tag)
  SequenceEncoder Sequence(int tag, TagClass tc)

    Creates a SEQUENCE encoder of type SequenceEncoder that adds a nested SEQUENCE to the current position of the SEQUENCE and returns the encoder to the application. The application can then add elements to the nested sequence through the encoder interface. The second overloaded Sequence method creates an encoder for an implicitly tagged sequence where the tag is of the ContextSpecific class. The third overloaded method allows an application to specify the tag class other than ContextSpecific;

  • SequenceOf

      SequenceOfEncoder SequenceOf(UType uType)
  SequenceOfEncoder SequenceOf(int tag, UType uType)
  SequenceOfEncoder SequenceOf(int tag, UType uType, TagClass tc)

    Creates a SEQUENCE OF encoder of type SequenceOfEncoder that adds a SEQUENCE OF element to the current position of the SEQUENCE and returns the encoder to the application. ASN.1 defines a SEQUENCE OF as an ordered collection of elements of the same type. That is, the elements added by the application to the SEQUENCE OF must be of the ASN.1 universal type specified when the encoder has been created. The encoder interface is described in section Interface SequenceOfEncoder. The second overloaded SequenceOf method creates an encoder for an implicitly tagged SEQUNCE OF element of ContextSpecific class. And, as usual, the third overload allows an application to specify the tag class other than ContextSpecific;

  • Int32

      void Int32(int value)
  void Int32(int tag, int value)
  void Int32(int tag, int value, TagClass tc)

    Adds a 32-bit integer value to the current position of the SEQUENCE as an ASN.1 INTEGER element;

  • Int64

      void Int64(long value)
  void Int64(int tag, long value)
  void Int64(int tag, long value, TagClass tc)

    Adds a 64-bit integer value to the current position of the SEQUENCE as an ASN.1 INTEGER element;

  • Boolean

      void Boolean(boolean value)
  void Boolean(int tag, boolean value)
  void Boolean(int tag, boolean value, TagClass tc)

    Adds a Boolean value to the current position of the SEQUENCE as an ASN.1 BOOLEAN element;

  • Real32

      void Real32(float value)
  void Real32(int tag, float value)
  void Real32(int tag, float value, TagClass tc)

    Adds a 32-bit real value to the current position of the SEQUENCE as an ASN.1 REAL element;

  • Real64

      void Real64(double value)
  void Real64(int tag, double value)
  void Real64(int tag, double value, TagClass tc)

    Adds a 64-bit real value to the current position of the SEQUENCE as an ASN.1 REAL element;

  • UTF8String

      void UTF8String(String value)
  void UTF8String(int tag, String value)
  void UTF8String(int tag, String value, TagClass tc)

    Adds a Java string to the current position of the SEQUENCE as an ASN.1 UTF8String element;

  • BMPString

      void BMPString(String value)
  void BMPString(int tag, String value)
  void BMPString(int tag, String value, TagClass tc)

    Adds a Java string to the current position of the SEQUENCE as an ASN.1 BMPString element;

  • IA5String

      void IA5String(String value)
  void IA5String(int tag, String value)
  void IA5String(int tag, String value, TagClass tc)

    Adds a Java string to the current position of the SEQUENCE as an ASN.1 IA5String element;

  • PrintableString

      void PrintableString(String value)
  void PrintableString(int tag, String value)
  void PrintableString(int tag, String value, TagClass tc)

    Adds a Java string to the current position of the SEQUENCE as an ASN.1 PrintableString element;

  • GndTime

      void GndTime(GregorianCalendar value);
  void GndTime(int tag, GregorianCalendar value);
  void GndTime(int tag, GregorianCalendar value, TagClass tc);

    Adds a GregorianCalendar value to the current position of the SEQUENCE as an ASN.1 element of type GeneralizedTime;

  • OctetString

      void OctetString(byte[] buffer)
  void OctetString(int tag, byte[] buffer)
  void OctetString(int tag, byte[] buffer, TagClass tc)
	
  void OctetString(byte[] buffer, int offset, int length)
  void OctetString(int tag, byte[] buffer, int offset, int length)
  void OctetString(int tag, byte[] buffer, int offset, int length, TagClass tc)
	
  void OctetString(java.util.UUID uuid)
  void OctetString(int tag, java.util.UUID uuid)
  void OctetString(int tag, java.util.UUID uuid, TagClass tc)

    The first six overloads of the method add a Java byte array to the current position of the SEQUENCE as an ASN.1 OctetString element. The first triple of overloaded methods adds an entire byte array. The second triple of overloads allows an application to specify the offset and length. The last triple of overloads adds a UUID value as an OctetString element of 16 octets;

  • Null

      void Null()

    If the ASN.1 syntax defines a given element as OPTIONAL, and the value to be specified is a Java null or the corresponding data is missing, an application can omit the element or specify ASN.1 NULL by calling the Null method. ASN.1 NULL is used when it is necessary to explicitly represent the absence of a value for an optional element, rather than omitting it from the encoding altogether.

TABLE OF CONTENTS