ConstructedType ("Entrust Authority Security Toolkit for the Java Platform")

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.

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

Method Summary

All Methods Instance Methods Concrete 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 which should be added to the ConstructedType
    
    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

Class ConstructedType

Field Summary

Fields inherited from class iaik.asn1.ASN1Object

Constructor Summary

Method Summary

Methods inherited from class iaik.asn1.ASN1Object

Methods inherited from class java.lang.Object

Field Detail

content_data

content_count

Constructor Detail

ConstructedType

Method Detail

getValue

setValue

addComponent

addComponent

removeComponent

removeComponent

getComponentAt

setComponent

countComponents

getComponents

encode

decode

addEncodeListener