codec.asn1
Class ASN1Choice

java.lang.Object
  |
  +--codec.asn1.ASN1AbstractType
        |
        +--codec.asn1.ASN1Choice

All Implemented Interfaces:

ASN1Type, Cloneable, Externalizable, Serializable

Direct Known Subclasses:

GeneralName

public class ASN1Choice

extends ASN1AbstractType

This type represents the ASN.1 CHOICE type as specified in ITU-T Recommendation X.680. On decoding, the decoder must be able to decide umambiguously which alternative choice it has to decode. For this reason all elements in a CHOICE type must have distinctive tags.

This class does not enforce the distinctive tag rule. Instead, the alternative with the first matching tag should be chosen by decoders. The application that builds the CHOICE type must take care not to produce ambiguous sets of alternatives.

This class distinguishes alternative choices and an inner type. Upon decoding, the inner type is selected from the list of choices based on the identifier octets encountered in the encoded stream. This type is then set as the inner type of this instance. Unless an inner type is set (either explicitly or by means of decoding) the state of the choice is undefined.

This instance always mimicks its inner type. The methods getTag, getTagClass, getValue all return the appropriate results of the corresponding method of the inner type. On encoding an instance of this class the inner type is encoded.

No nested CHOICE classes are supported. In principle this is easily supported but it is not good style to build such structures.

Version:

"$Id: ASN1Choice.java,v 1.3 2004/08/06 15:01:20 flautens Exp $"

Author:

Volker Roth

See Also:

Serialized Form

Constructor Summary

ASN1Choice()
Creates an instance with an initial capacity of 2.

ASN1Choice(int capacity)
Creates an instance with the given initial capacity.

Method Summary

void	addType(ASN1Type t) Adds the given type as an alternative choice to the collection of choices.
void	checkConstraints() Checks the constraint on the inner type if it is set.
void	clear() Clears the internal list of choices.
void	decode(Decoder dec) Decodes the inner type to the given decoder.
void	encode(Encoder enc) Encodes this type to the given encoder.
ASN1Type	getInnerType() Returns the inner ASN.1 type.
int	getTag() Returns the tag of the inner type.
int	getTagClass() Returns the tag class of the inner type.
ASN1Type	getType(int tag, int tagclass) Returns the choice with the given tag and tagclass if it exists, otherwise null is returned.
Object	getValue() Returns the value of the inner type.
boolean	isExplicit() Returns the tagging of the inner type.
boolean	isType(int tag, int tagclass) Returns true if the given tag and tag class matches the tag and tag class of this instance.
void	setConstraint(Constraint constraint) Sets the Constraint of the inner type.
void	setExplicit(boolean explicit) Sets the tagging of the inner type as either EXPLICIT or IMPLICIT.
void	setInnerType(ASN1Type t) Sets the inner type.
String	toString() Returns a string representation of this type.
void	trimToSize() Trims the internal list of choices to the actual number of choices stored in it.

Methods inherited from class codec.asn1.ASN1AbstractType

getConstraint, isOptional, readExternal, setOptional, writeExternal

Methods inherited from class java.lang.Object

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

Constructor Detail

ASN1Choice

public ASN1Choice()

Creates an instance with an initial capacity of 2.

ASN1Choice

public ASN1Choice(int capacity)

Creates an instance with the given initial capacity. The capacity determines the number of choices to store. This instance is backed by an ArrayList, hence the capacity is increased dynamically as required. Use the trimToSize() method to trim the internal list to the number of stored choices in order to reclaim memory.

Parameters:

capacity - The initial capacity for storing choices.

Throws:

IllegalArgumentException - if the capacity is less than 1.

Method Detail

addType

public void addType(ASN1Type t)

Adds the given type as an alternative choice to the collection of choices. The caller has to take care that no ambiguous choices are added. Each added type must have a distinctive tag.

CHOICE elements must neither be OPTIONAL nor tagged IMPLICIT. For safety, this method calls setOptional(false) and setExplicit(true) on the given type. Callers must not alter this setting after adding a type to this choice. However, the CHOICE itself can be declared OPTIONAL.

Parameters:

t - The ASN.1 type to add as a choice.

Throws:

NullPointerException - if the given type is null.

IllegalArgumentException - if the given type is a ASN1Choice type.

getType

public ASN1Type getType(int tag,
                        int tagclass)

Returns the choice with the given tag and tagclass if it exists, otherwise null is returned. This method is called by the decoder in order to determine the appropriate type to decode. The returned type is set up as the inner type by the decoder.

Parameters:

tag - The tag of the type encountered in the encoded stream. The tags of the various primitive ASN.1 types are defined in class ASN1.

tagclass - The tag class of the type encountered in the encoded stream. The tag class identifiers are defined in class ASN1. See for instance CLASS_UNIVERSAL.

Returns:

The choice with matching tag and tag class or null if no matching choice is found.

isType

public boolean isType(int tag,
                      int tagclass)

Description copied from class: ASN1AbstractType

Returns true if the given tag and tag class matches the tag and tag class of this instance. This method is used primarily by decoders and variable types such as ASN1Choice and ASN1OpenType. It enables decoders to query a variable type whether a decoded type is accepted.

This method provides a default implementation that matches the given tag and tag class against the values returned by getTag and getTagClass respectively.

Overrides:

isType in class ASN1AbstractType

Following copied from class: codec.asn1.ASN1AbstractType

Parameters:

tag - The tag to compare with.

tagclass - The tag class to compare with.

Returns:

true if the given tag and tag class matches this type and false otherwise.

trimToSize

public void trimToSize()

Trims the internal list of choices to the actual number of choices stored in it.

clear

public void clear()

Clears the internal list of choices. The inner type remains unaffected if it is already set. number of choices stored in it.

getInnerType

public ASN1Type getInnerType()

Returns the inner ASN.1 type.

Returns:

The inner ASN.1 type.

setInnerType

public void setInnerType(ASN1Type t)

Sets the inner type.

Parameters:

t - The type to set as the inner type.

Throws:

NullPointerException - if the given type is null.

getTag

public int getTag()

Returns the tag of the inner type.

Overrides:

getTag in class ASN1AbstractType

Returns:

The tag of the inner type.

Throws:

IllegalStateException - if the inner type is not set.

getTagClass

public int getTagClass()

Returns the tag class of the inner type.

Overrides:

getTagClass in class ASN1AbstractType

Returns:

The tag class of the inner type.

Throws:

IllegalStateException - if the inner type is not set.

getValue

public Object getValue()

Returns the value of the inner type. The default inner type is ASN1Null. This method calls getValue on the inner type and returns the result.

Overrides:

getValue in class ASN1AbstractType

Returns:

The value of the inner type.

Throws:

IllegalStateException - if the inner type is not set.

setExplicit

public void setExplicit(boolean explicit)

Sets the tagging of the inner type as either EXPLICIT or IMPLICIT. The default is EXPLICIT. Encoders skip the encoding of identifier octets for types that are declared as IMPLICIT.

Overrides:

setExplicit in class ASN1AbstractType

Parameters:

explicit - true if this type shall be tagged EXPLICIT and false if it shall be encoded IMPLICIT.

Throws:

IllegalStateException - if the inner type is not set.

isExplicit

public boolean isExplicit()

Returns the tagging of the inner type.

Overrides:

isExplicit in class ASN1AbstractType

Returns:

true if the inner type is tagged EXPLICIT and false if it is tagged IMPLICIT.

Throws:

IllegalStateException - if the inner type is not set.

setConstraint

public void setConstraint(Constraint constraint)

Sets the Constraint of the inner type. For instance an ASN.1 INTEGER might be constrained to a certain range such as INTEGER (0..99). null can be passed as a constraint which disables constraint checking.

Overrides:

setConstraint in class ASN1AbstractType

Parameters:

constraint - The Constraint of this type.

Throws:

IllegalStateException - if the inner type is not set.

checkConstraints

public void checkConstraints()
                      throws ConstraintException

Checks the constraint on the inner type if it is set. Otherwise this method returns silently.

Overrides:

checkConstraints in class ASN1AbstractType

Throws:

ConstraintException - if this type is not in the appropriate range of values.

IllegalStateException - if the inner type is not set.

encode

public void encode(Encoder enc)
            throws ASN1Exception,
                   IOException

Encodes this type to the given encoder. Before this method is called, the inner type must be set. Otherwise an IllegalStateException is thrown.

If this method is declared OPTIONAL then still an exception is thrown. The OPTIONAL flag is checked only by encoders and decoders. Transparent handling of CHOICE types can be achieved by calling writeType(ASN1Choice choice) on the encoder. The encoder's method checks if its argument is OPTIONAL.

Overrides:

encode in class ASN1AbstractType

Parameters:

enc - The Encoder to use for encoding.

Throws:

IllegalStateException - if the inner type is not set.

decode

public void decode(Decoder dec)
            throws ASN1Exception,
                   IOException

Decodes the inner type to the given decoder.

Overrides:

decode in class ASN1AbstractType

Parameters:

dec - The decoder to decode to.

Throws:

IllegalStateException - if the open type cannot be resolved on runtime.

toString

public String toString()

Returns a string representation of this type.

Overrides:

toString in class Object

Returns:

The string representation.