iaik.asn1

Class ConstructedType

java.lang.Object

iaik.asn1.ASN1Object

iaik.asn1.ConstructedType

Direct Known Subclasses:

OCTET_STRING, SEQUENCE, SET, TaggedType, UNKNOWN

public abstract class ConstructedType
extends ASN1Object

This class is the super class for all structured ASN.1 types.

Within the ASN.1 architecture of the IAIK-JCE library, this ConstructedType class rather models ASN.1 types which have to be encoded constructed, and not only native structured ASN.1 types. The ASN.1 type OCTET_STRING, for instance, in its nature represents a simple ASN.1 type and therefore has to be DER encoded by using the primitive definite method where the number of data octets explicitly has to be specified just behind the identifier octet. However sometimes it may be preferable to use the indefinite constructed method for BER encoding an octet string, in particular when dealing with large amounts of raw data. For that reason, also the OCTET_STRING class inherits from this ConstructedType class. Indefinite length encoding is indicated by the length octet 0x80, and the data octets are concluded by two consecutive octets of all zero (0x00 0x00).
As an example, the raw data bytes 0x12 0xAB 0x34 may be encoded definite primitive, e.g.:

 0x04 0x03 0x12 0xAB 0x34
 

or they may be encoded indefinite constructed, e.g.:

 0x24 0x80
           0x04 0x02 0x12 0xAB
           0x04 0x01 0x34
 0x00 0x00
 

An application never directly will instantiate this ConstructedType class, rather it will instantiate a proper subclass, e.g. SEQUENCE or SET. Components may be added by means of a proper addComponent method, e.g.:

 byte[] value = {(byte)0x12, (byte)0xAB, (byte)0x34 };
 OCTET_STRING oct = new OCTET_STRING(value);
 INTEGER i = new INTEGER(3);
 SEQUENCE seq = new SEQUENCE();
 seq.addComponent(oct);
 seq.addComponent(i);
 

A component may be removed by using one of the removeComponent methods, or they may be replaced by calling the setComponent method.

For building SEQUENCE OF respectively SET OF structures of ASN1Type implementing class instances, use the createSequenceOf respectively createSetOf methods of the ASN class.

See Also:

SEQUENCE, SET, OCTET_STRING, ASN1Object

Field Summary

Fields

Modifier and Type	Field and Description
protected int	content_count The number of components in the buffer.
protected ASN1Object[]	content_data The buffer where the components are stored.

Fields inherited from class iaik.asn1.ASN1Object

asnType, constructed, encode_listener, indefinite_length, isStringType, stream_mode

Constructor Summary

Constructors

Constructor and Description
ConstructedType() Creates a new ConstructedType object.

Method Summary

Methods

Modifier and Type	Method and Description
void	addComponent(ASN1Object component) Adds a new ASN1Object component to the end of this ConstructedType.
void	addComponent(ASN1Object component, int index) Inserts a new component to a given location within the ConstructedType.
void	addEncodeListener(EncodeListener encodeListener, int id, int afterComponent) Adds a component encode listener which wants to be notified when the encoding of this constructed ASN1Object has to be performed.
int	countComponents() Returns the number of component objects.
protected void	decode(int length, java.io.InputStream is) Decodes the next available data from the InputStream.
protected void	encode(java.io.OutputStream os) DER encodes this ASN1Object and writes the result to the supplied OutputStream.
ASN1Object	getComponentAt(int index) Returns the component at the given location within a ConstructedType.
java.util.Enumeration	getComponents() Returns an Enumeration that iterates over the component objects.
java.lang.Object	getValue() Returns the value of this ConstructedType as an array of ASN1Objects.
void	removeComponent(ASN1Object component) Removes a component from a ConstructedType.
void	removeComponent(int index) Removes a component at the given location within a ConstructedType.
void	setComponent(int index, ASN1Object value) Sets the component at the given location within a ConstructedType.
void	setValue(java.lang.Object object) Sets the value of this ConstructedType.

Methods inherited from class iaik.asn1.ASN1Object

addEncodeListener, encodeObject, getAsnType, indefiniteLength, isA, isConstructed, isStringType, setAutomaticRepair, setAutomaticRepairRecursive, setIndefiniteLength, setIndefiniteRecursive, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

content_data

protected ASN1Object[] content_data

The buffer where the components are stored.

content_count

protected int content_count

The number of components in the buffer.

Constructor Detail

ConstructedType

public ConstructedType()

Creates a new ConstructedType object. An empty array is created to be filled with ASN1Objects by means of proper addComponent methods. An application will not directly use this constructor for creating a constructed ASN1Object, rather it will instantiate a proper subclass, e.g. SEQUENCE or SET.

Method Detail

getValue

public java.lang.Object getValue()

Returns the value of this ConstructedType as an array of ASN1Objects. Generally the object returned by this method represents an array of ASN1Objects. However, a particular subclass, e.g. OCTET_STRING may change the exact meaning of this method according to specific requirements.

Specified by:

getValue in class ASN1Object

Returns:

the components as array of ASN1Objects

setValue

public void setValue(java.lang.Object object)

Sets the value of this ConstructedType. Generally the value to be set by this method represents an array of ASN1Objects. However, a particular subclass, e.g. OCTET_STRING may change the exact meaning of this method according to specific requirements.

Specified by:

setValue in class ASN1Object

Parameters:

object - the value to be set as an array of ASN1Objects

addComponent

public void addComponent(ASN1Object component)

Adds a new ASN1Object component to the end of this ConstructedType. The ConstructedType automatically grows if the the predefined number of components is exceeded.

Overrides:

addComponent in class ASN1Object

Parameters:

component - the ASN1Object component to be added; not used

See Also:

ConstructedType

addComponent

public void addComponent(ASN1Object component,
                int index)

Inserts a new component to a given location within the ConstructedType. The ConstructedType automatically grows if the the predefined number of components is exceeded. If the supplied index is invalid, because it is shorter than 0, or because it exceeds the number of components currently included, an ArrayIndexOutOfBoundsException will be raised.

Parameters:

component - the ASN1Object component to be inserted

index - the index where to insert the new component

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is invalid

removeComponent

public void removeComponent(ASN1Object component)

Removes a component from a ConstructedType. If the component is not included in the ConstructedType, nothing is done. After removing one component, the remaining components are shifted to fill the gap.

Parameters:

component - the ASN1Object component to be removed

removeComponent

public void removeComponent(int index)

Removes a component at the given location within a ConstructedType. After removing one component, the remaining components are shifted to fill the gap.

Parameters:

index - the index of the component to be removed

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is invalid

getComponentAt

public ASN1Object getComponentAt(int index)

Returns the component at the given location within a ConstructedType.

Overrides:

getComponentAt in class ASN1Object

Parameters:

index - the desired position

Returns:

the ASN1Object component located at the given position

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is invalid

See Also:

ConstructedType

setComponent

public void setComponent(int index,
                ASN1Object value)

Sets the component at the given location within a ConstructedType. If an ASN1Object already exists at the specified position it will be replaced.

Parameters:

index - the location of the ConstructedType to which the given ASN1Object shall be written

value - the ASN1Object component to be set

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is invalid

countComponents

public int countComponents()

Returns the number of component objects. Zero if none.

Overrides:

countComponents in class ASN1Object

Returns:

the number of components this ConstructedType contains

See Also:

ConstructedType

getComponents

public java.util.Enumeration getComponents()

Returns an Enumeration that iterates over the component objects.

Returns:

an Enumeration of components in this ConstructedType

encode

protected void encode(java.io.OutputStream os)
               throws java.io.IOException

DER encodes this ASN1Object and writes the result to the supplied OutputStream. In stream mode the components are encoded in correct order and the indefinite length encoding method is used, in normal mode the components are encoded in reverse order to facilitate length determination. Indefinite length encoding may be preferable when dealing with large objects where whole the data is not known at beginning of the data transfer.

Specified by:

encode in class ASN1Object

Parameters:

os - the output stream to which to write the data

Throws:

java.io.IOException - if an error occurs while reading from the stream

decode

protected void decode(int length,
          java.io.InputStream is)
               throws CodingException,
                      java.io.IOException

Decodes the next available data from the InputStream. The supplied input stream carries DER encoded data. The next length bytes represent the encoding of this ASN1Object to be decoded. If length < 0, the supplied ASN1Object has been encoded by means of the indefinite length encoding method, and so the encoding has to be parsed for two consecutive EOC octets of all zeros. Indefinite length encoding only is appropriate (and therefore allowed) for constructed ASN.1 types.

This is a protected method and will not be used by an application for DER decoding an encoded ASN1Object. An application will call one of the decode methods of the DerCoder class for performing the decoding. The DerCoder then determines the number of bytes (length) obtained by the particular ASN1Object and internally calls the decode method of that ASN1Object.

Specified by:

decode in class ASN1Object

Parameters:

length - the length of the ASN1Object which shall be decoded, i.e. the number of the bytes representing the ASN1Object to be decoded

is - the input stream from which the data is read in

Throws:

java.io.IOException - if an error occurs while reading from the stream

CodingException - if a decoding error occurs

addEncodeListener

public void addEncodeListener(EncodeListener encodeListener,
                     int id,
                     int afterComponent)

Adds a component encode listener which wants to be notified when the encoding of this constructed ASN1Object has to be performed. A class that wishes to be registered as an EncodeListener for a specific ASN1Object has to implement the EncodeListener interface. The actual registration for encoding notification is done when calling an addEncodeListener method on a particular ASN1Object. Later, when the encoding of the current ASN1Object is performed, the program execution jumps to the encodeCalled method of each registered EncodeListener implementation for querying for information that is needed for the encoding procedure. After having executed the encodeCalled methods of all registered listeners, the particular encode method of the ASN1Object is executed. In contrast to the addEncodeListener method of parent class ASN1Object, for a constructed now you can specify the component after which the encoding process shall "pause" to get the values for the remaining components. Imagine, for instance, a SEQUENCE being composed of five components for which you do not know the values of the last 3 components before the first 2 components have been encoded. In this case you may register an EncodeListener to execute its encodeCalled method after 2 components have been encoded, e.g.:

 SEQUENCE seq = ...;
 seq.addEncodeListener(myEncodeListener, 1, 2);
 

Attention! Adding an component encode listener only makes sense if this constructed ASN1Object is to be encoded using stream mode.

Parameters:

encodeListener - the EncodeListener

id - an id which lets listeners distinguish between objects

afterComponent - the number of component after which the EncodeListener should be called

See Also:

EncodeListener