iaik.ixsil.core

Class TransformInstruction

java.lang.Object

iaik.ixsil.core.TransformInstruction

public abstract class TransformInstruction
extends java.lang.Object

Abstract base class representing a transform instruction.

Field Summary

Fields

Modifier and Type	Field and Description
protected AlgorithmFactory	algorithmFactory_ Creates algorithms needed in case of verification.
protected java.lang.Object	cachedTransformInput_ Stores the result of the last transform which has already been processed.
static boolean	EXPLICITDATATYPE_RAW_ Constant for type of data set with method setExplicitData(java.lang.Object, boolean).
static boolean	EXPLICITDATATYPE_RESULT_ Constant for type of data set with method setExplicitData(java.lang.Object, boolean).
protected boolean	finalC14NApplied_ Stores whether the final canonicalization has been applied if member posOfLastInvokedTransform_ equals the number of transforms specified for this transform instruction.
protected int	posOfLastInvokedTransform_ Stores the position of the last transform which has already been processed.
protected java.util.List	transforms_ A list of references to Transform elements, each of which represents a transform algorithm used to generate the result of this transform instruction from the refered data.
protected org.w3c.dom.Element	transInstrDOMElem_ DOM element representation of the transform instruction element.
protected org.w3c.dom.Attr	typeAttr_ DOM attribute representation of the transform instruction's attribute named "Type".
protected org.w3c.dom.Attr	uriAttr_ DOM attribute representation of the transform instruction's attribute named "URI".
protected URIResolverParameters	uriResolverParameters_ Structure encapsulating some parameters for resolving URIs.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TransformInstruction(org.w3c.dom.Element transInstrDOMElem, iaik.ixsil.core.SignatureHandler signatureHandler) Creates a transform instruction object, depending on the specified use case.
protected	TransformInstruction(org.w3c.dom.Element transInstrDOMElem, URIResolverParameters uriResolverParameters, boolean useCase) Creates a transform instruction object, depending on the specified use case.

Method Summary

Modifier and Type	Method and Description
protected org.w3c.dom.Element	createAndInsertTransforms() Creates and adds the Transforms DOM element as first child of the DOM element representing the transform instruction.
org.w3c.dom.Element	getDOMElement() Gets the DOM Element representing the transform instruction.
java.io.InputStream	getExplicitData(boolean explicitDataType) Gets either the raw data (data resulting from resolving the URI attribute of the reference) or the result data (data resulting from the last of the specified transforms).
Transform[]	getTransforms() Gets an array with all Transform objects registerred for this transform instruction.
int	getTransformsNumber() Gets the number of transforms inserted into this transform instruction so far.
java.lang.String	getType() Gets the Type attribute value of the Element representing the transform instruction.
java.lang.String	getURI() Gets the URI attribute value of the Element representing the transform instruction.
void	insertTransformAt(Transform transform, int position) Inserts the specified transform at the specified position into the list of transforms which should be applied to the data refered by this transform instruction.
protected java.lang.Object	internalProcessTransforms(int positionOfLastIncludedTransform, boolean applyFinalC14N, boolean cloneResult) Resolves the transform instruction's URI (or takes the expicite data set previously respectively) and invokes all transforms starting with the first and ending with the one specified by means of the parameter positionOfLastIncludedTransform.
void	removeTransformAt(int position) Removes the transform at the specified position from the list of transforms which should be applied to the data refered by this transform instruction.
void	setExplicitData(java.lang.Object explicitData, boolean explicitDataType) Sets one of two possible kinds of explicit data:
void	setType(URI type) Sets the Type attribute value of the Element representing the transform instruction.
void	setURI(URI uri) Sets the URI attribute value of the Element representing the transform instruction.
protected void	signingInit(org.w3c.dom.Element transInstrDOMElem) Initializes this transform instruction object for the signature creation use case.
protected void	verifyingInit(org.w3c.dom.Element transInstrDOMElem) Initializes this transform instruction object for the signature verification use case.

Methods inherited from class java.lang.Object

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

Field Detail

EXPLICITDATATYPE_RAW_

public static final boolean EXPLICITDATATYPE_RAW_

Constant for type of data set with method setExplicitData(java.lang.Object, boolean).

See Also:

Constant Field Values

EXPLICITDATATYPE_RESULT_

public static final boolean EXPLICITDATATYPE_RESULT_

Constant for type of data set with method setExplicitData(java.lang.Object, boolean).

See Also:

Constant Field Values

transInstrDOMElem_

protected org.w3c.dom.Element transInstrDOMElem_

DOM element representation of the transform instruction element.

uriAttr_

protected org.w3c.dom.Attr uriAttr_

DOM attribute representation of the transform instruction's attribute named "URI".

typeAttr_

protected org.w3c.dom.Attr typeAttr_

DOM attribute representation of the transform instruction's attribute named "Type".

uriResolverParameters_

protected URIResolverParameters uriResolverParameters_

Structure encapsulating some parameters for resolving URIs.

algorithmFactory_

protected AlgorithmFactory algorithmFactory_

Creates algorithms needed in case of verification.

transforms_

protected java.util.List transforms_

A list of references to Transform elements, each of which represents a transform algorithm used to generate the result of this transform instruction from the refered data.

cachedTransformInput_

protected java.lang.Object cachedTransformInput_

Stores the result of the last transform which has already been processed.

posOfLastInvokedTransform_

protected int posOfLastInvokedTransform_

Stores the position of the last transform which has already been processed. The output of this transform is currently stored in cachedTransformInput_.

finalC14NApplied_

protected boolean finalC14NApplied_

Stores whether the final canonicalization has been applied if member posOfLastInvokedTransform_ equals the number of transforms specified for this transform instruction.

Constructor Detail

TransformInstruction

protected TransformInstruction(org.w3c.dom.Element transInstrDOMElem,
                               URIResolverParameters uriResolverParameters,
                               boolean useCase)
                        throws TransformInstructionException

Creates a transform instruction object, depending on the specified use case.

Parameters:

transInstrDOMElem - The DOM element representation of the transform instruction.

uriResolverParameters - Some parameters which are used for resolving URI references.

useCase - Indicates if this constructor is invoked in the the context of signing or verification. Please use the values SignatureHandler.SIGNING_ or SignatureHandler.VERIFYING_.

Throws:

TransformInstructionException - if constructing the transform instruction object fails for any reason.

TransformInstruction

protected TransformInstruction(org.w3c.dom.Element transInstrDOMElem,
                               iaik.ixsil.core.SignatureHandler signatureHandler)
                        throws TransformInstructionException

Creates a transform instruction object, depending on the specified use case.

Parameters:

transInstrDOMElem - The DOM element representation of the transform instruction.

signatureHandler - The signature handler responsible for the Signature bearing this TransformInstruction.

Throws:

TransformInstructionException - if constructing the transform instruction object fails for any reason.

Method Detail

signingInit

protected void signingInit(org.w3c.dom.Element transInstrDOMElem)

Initializes this transform instruction object for the signature creation use case.

Parameters:

transInstrDOMElem - The DOM element representation of the transform instruction.

verifyingInit

protected void verifyingInit(org.w3c.dom.Element transInstrDOMElem)
                      throws TransformInstructionException

Initializes this transform instruction object for the signature verification use case.

Parameters:

transInstrDOMElem - The DOM element representation of the transform instruction.

Throws:

TransformInstructionException - if initialization of the reference object fails for any reason.

setURI

public void setURI(URI uri)

Sets the URI attribute value of the Element representing the transform instruction. If the attribute has already been set, it will be overwritten. If the uri parameter equals null, the possibly existing URI attribute will be removed.

Parameters:

uri - The URI for the attribute value.

getURI

public java.lang.String getURI()

Gets the URI attribute value of the Element representing the transform instruction.

Returns:

the attribute value or null if the URI attribute is not available.

setType

public void setType(URI type)

Sets the Type attribute value of the Element representing the transform instruction. If the attribute has already been set, it will be overwritten. If the type parameter equals null, the possibly existing Type attribute will be removed.

Parameters:

type - The URI for the attribute value.

getType

public java.lang.String getType()

Gets the Type attribute value of the Element representing the transform instruction.

Returns:

the attribute value or null if the Type attribute is not available.

getDOMElement

public org.w3c.dom.Element getDOMElement()

Gets the DOM Element representing the transform instruction.

Returns:

the DOM Element representing the transform instruction.

insertTransformAt

public void insertTransformAt(Transform transform,
                              int position)
                       throws ReferenceException

Inserts the specified transform at the specified position into the list of transforms which should be applied to the data refered by this transform instruction.

Parameters:

transform - The transform to be inserted. Must not be null.

position - The position where to insert the transform into the list. Must be greater or equal 0 and must be less or equal the number of transforms inserted so far.

Throws:

ReferenceException - if requesting the DOM element representation from the transform fails.

createAndInsertTransforms

protected org.w3c.dom.Element createAndInsertTransforms()

Creates and adds the Transforms DOM element as first child of the DOM element representing the transform instruction.

Returns:

the Transforms DOM element which has been created and added to the DOM element representing the transform instruction.

getTransformsNumber

public int getTransformsNumber()

Gets the number of transforms inserted into this transform instruction so far.

Returns:

the number of transforms inserted into this transform instruction so far.

removeTransformAt

public void removeTransformAt(int position)

Removes the transform at the specified position from the list of transforms which should be applied to the data refered by this transform instruction.

Parameters:

position - The position of the tranform to be removed in the list. Must be greater or equal 0 and must be less than the number of transforms which have been inserted so far.

getTransforms

public Transform[] getTransforms()

Gets an array with all Transform objects registerred for this transform instruction.

Returns:

an array with all Transform objects, or null if there are no transforms.

setExplicitData

public void setExplicitData(java.lang.Object explicitData,
                            boolean explicitDataType)

Sets one of two possible kinds of explicit data:

Raw data

This kind of data is equivalent to the result of resolving the URI specified for the transform instruction. It forms the input of the first transform, or the resulting data itself, if there are no transforms specified.

Result data

This kind of data is equivalent to the output of the last transform specified for the reference, or to the result of resolving the URI specified for the reference if there are no transforms specified.

This method can be used for some reasons:

Signature creation

• It is useful to avoid either reference resolving, or transform computation, or both, if the result of these operations is already available for the application.
• For one Reference per Signature it is allowed to omit its URI attribute. In this case at least the raw data must be provided explicitely.

Signature verification

• If the verifying application already knows about the result of either the URI resolving or the transform computation, it is useful to skip these processes and instead provide the corresponding data explicitely.
• If no URI has been provided by the Signer, the verifier is supposed to know about the raw data. In this case the verifier must have the possibility to provide at least the raw data.

Parameters:

explicitData - The explicit data bytes to be set. Must not be null and must either be of type InputStream or NodeList.

explicitDataType - Determines the type of explicit data (raw or result data). Please use the values EXPLICITDATATYPE_RAW_ or EXPLICITDATATYPE_RESULT_.

getExplicitData

public java.io.InputStream getExplicitData(boolean explicitDataType)

Gets either the raw data (data resulting from resolving the URI attribute of the reference) or the result data (data resulting from the last of the specified transforms). Which kind of data is desired must be indicated with the explicitDataType flag.

This method will not compute the desired data. If it is not available, this method will return null. If the data is not available as an java.io.InputStream, this method will also return null.

Parameters:

explicitDataType - Determines the type of explicit data (raw or digest input). Please use the values EXPLICITDATATYPE_RAW_ or EXPLICITDATATYPE_RESULT_.

Returns:

the desired kind of explicit data.

internalProcessTransforms

protected java.lang.Object internalProcessTransforms(int positionOfLastIncludedTransform,
                                                     boolean applyFinalC14N,
                                                     boolean cloneResult)
                                              throws TransformInstructionException

Resolves the transform instruction's URI (or takes the expicite data set previously respectively) and invokes all transforms starting with the first and ending with the one specified by means of the parameter positionOfLastIncludedTransform.

The result of this computation is returned; it can either be an java.io.InputStream or a org.w3c.dom.NodeList, depending on the result type of the last transform.

Further invokations of this method with a value of positionOfLastIncludedTransform higher than its current value will not reinvoke all the transforms, but use the (cached) result of this method instead.

Parameters:

positionOfLastIncludedTransform - The position of the last transform included in the computation described above. A value 0 means that no transform is invoked at all; in such a case the input for the first transform is returned.

applyFinalC14N - This parameter is evaluated only if the parameter positionOfLastIncludedTransform equals the number of transforms specified for this transform instruction and if the last transform provides the result as a NodeList. In such a case the parameter determines whether this method returns that NodeList or applies the final canonicalization and returns an InputStream instead.

cloneResult - Determines wheter the result of this method should be cloned (only in case that it is an InputStream) or not.

Returns:

the computation result.

Throws:

TransformInstructionException - if neither the URI attribute has been set nor a cached transform input exists, or if processing the transforms fails for any other reason.