A Service Provider Interface for transform and canonicalization algorithms.

Each instance of TransformService supports a specific transform or canonicalization algorithm and XML mechanism type. To create a TransformService, call one of the static getInstance methods, passing in the algorithm URI and XML mechanism type desired, for example:

TransformService ts = TransformService.getInstance(Transform.XPATH2, "DOM");

TransformService implementations are registered and loaded using the java.security.Provider mechanism. Each TransformService service provider implementation should include a MechanismType service attribute that identifies the XML mechanism type that it supports. If the attribute is not specified, "DOM" is assumed. For example, a service provider that supports the XPath Filter 2 Transform and DOM mechanism would be specified in the Provider subclass as:

    put("TransformService." + Transform.XPATH2,
        "org.example.XPath2TransformService");
    put("TransformService." + Transform.XPATH2 + " MechanismType", "DOM");

TransformService implementations that support the DOM mechanism type must abide by the DOM interoperability requirements defined in the DOM Mechanism Requirements. See the TransformService section in the Java Security Standard Algorithm Names Specification for a list of standard algorithm URIs and mechanism types.

Once a TransformService has been created, it can be used to process Transform or CanonicalizationMethod objects. If the Transform or CanonicalizationMethod exists in XML form (for example, when validating an existing XMLSignature), the init(XMLStructure, XMLCryptoContext) method must be first called to initialize the transform and provide document context (even if there are no parameters). Alternatively, if the Transform or CanonicalizationMethod is being created from scratch, the init(TransformParameterSpec) method is called to initialize the transform with parameters and the marshalParams method is called to marshal the parameters to XML and provide the transform with document context. Finally, the transform method is called to perform the transformation.

Concurrent Access

The static methods of this class are guaranteed to be thread-safe. Multiple threads may concurrently invoke the static methods defined in this class with no ill effects.

However, this is not true for the non-static methods defined by this class. Unless otherwise documented by a specific provider, threads that need to access a single TransformService instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different TransformService instance need not synchronize.

Modifier and Type	Class and Description
private static class	TransformService.MechanismMapEntry

Modifier and Type	Field and Description
private String	algorithm
private String	mechanism
private Provider	provider

Access	Constructor and Description
protected	TransformService() Default constructor, for invocation by subclasses.

Method Summary

Modifier and Type	Method and Description
public final String	Returns: the algorithm URI getAlgorithm() Implements javax.xml.crypto.AlgorithmMethod.getAlgorithm. Returns the URI of the algorithm supported by this `TransformService`.
public static TransformService	Returns: a new `TransformService` getInstance(String the URI of the algorithm. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard transform algorithms. algorithm, String the type of the XML processing mechanism and representation. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types. mechanismType) Returns a `TransformService` that supports the specified algorithm URI (ex: `Transform#XPATH2`) and mechanism type (ex: DOM).
public static TransformService	Returns: a new `TransformService` getInstance(String the URI of the algorithm. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard transform algorithms. algorithm, String the type of the XML processing mechanism and representation. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types. mechanismType, Provider the `Provider` object provider) Returns a `TransformService` that supports the specified algorithm URI (ex: `Transform#XPATH2`) and mechanism type (ex: DOM) as supplied by the specified provider.
public static TransformService	Returns: a new `TransformService` getInstance(String the URI of the algorithm. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard transform algorithms. algorithm, String the type of the XML processing mechanism and representation. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types. mechanismType, String the string name of the provider provider) Returns a `TransformService` that supports the specified algorithm URI (ex: `Transform#XPATH2`) and mechanism type (ex: DOM) as supplied by the specified provider.
public final String	Returns: the mechanism type getMechanismType() Returns the mechanism type supported by this `TransformService`.
public final Provider	Returns: the provider getProvider() Returns the provider of this `TransformService`.
public abstract void	init(TransformParameterSpec the algorithm parameters (may be `null` if not required or optional) params) Initializes this `TransformService` with the specified parameters.
public abstract void	init(XMLStructure a mechanism-specific structure containing the parent structure parent, XMLCryptoContext the `XMLCryptoContext` containing additional context (may be `null` if not applicable) context) Initializes this `TransformService` with the specified parameters and document context.
public abstract void	marshalParams(XMLStructure a mechanism-specific structure containing the parent node that the marshalled parameters should be appended to parent, XMLCryptoContext the `XMLCryptoContext` containing additional context (may be `null` if not applicable) context) Marshals the algorithm-specific parameters.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

algorithm	back to summary
private String algorithm

mechanism	back to summary
private String mechanism

provider	back to summary
private Provider provider

Constructor Detail

TransformService	back to summary
protected TransformService() Default constructor, for invocation by subclasses.

Method Detail

getAlgorithm back to summary

getAlgorithm	back to summary
public final String getAlgorithm() Implements javax.xml.crypto.AlgorithmMethod.getAlgorithm. Returns the URI of the algorithm supported by this `TransformService`. Returns:String the algorithm URI

public final String getAlgorithm()

Implements javax.xml.crypto.AlgorithmMethod.getAlgorithm.

Returns the URI of the algorithm supported by this TransformService.

Returns:String: the algorithm URI

getInstance back to summary

getInstance	back to summary
public static TransformService getInstance(String algorithm, String mechanismType) throws NoSuchAlgorithmException Returns a `TransformService` that supports the specified algorithm URI (ex: `Transform#XPATH2`) and mechanism type (ex: DOM). This method uses the standard JCA provider lookup mechanism to locate and instantiate a `TransformService` implementation of the desired algorithm and `MechanismType` service attribute. It traverses the list of registered security `Provider`s, starting with the most preferred `Provider`. A new `TransformService` object from the first `Provider` that supports the specified algorithm and mechanism type is returned. Note that the list of registered providers may be retrieved via the `Security.getProviders()` method. Implementation Note The JDK Reference Implementation additionally uses the `jdk.security.provider.preferred` `Security` property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned by `Security.getProviders()`. Parameters algorithm:String the URI of the algorithm. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard transform algorithms. mechanismType:String the type of the XML processing mechanism and representation. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types. Returns:TransformService a new `TransformService` Exceptions NoSuchAlgorithmException: if no `Provider` supports a `TransformService` implementation for the specified algorithm and mechanism type NullPointerException: if `algorithm` or `mechanismType` is `null` External Specification Java Security Standard Algorithm Names See Also `Provider`

public static TransformService getInstance(String algorithm, String mechanismType) throws NoSuchAlgorithmException

Returns a TransformService that supports the specified algorithm URI (ex: Transform#XPATH2) and mechanism type (ex: DOM).

This method uses the standard JCA provider lookup mechanism to locate and instantiate a TransformService implementation of the desired algorithm and MechanismType service attribute. It traverses the list of registered security Providers, starting with the most preferred Provider. A new TransformService object from the first Provider that supports the specified algorithm and mechanism type is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Implementation Note

The JDK Reference Implementation additionally uses the jdk.security.provider.preferred Security property to determine the preferred provider order for the specified algorithm. This may be different than the order of providers returned by Security.getProviders().

Parameters

algorithm:String: the URI of the algorithm. See the TransformService section in the Java Security Standard Algorithm Names Specification for a list of standard transform algorithms.
mechanismType:String: the type of the XML processing mechanism and representation. See the TransformService section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.

Returns:TransformService

a new TransformService

Exceptions

NoSuchAlgorithmException:: if no Provider supports a TransformService implementation for the specified algorithm and mechanism type
NullPointerException:: if algorithm or mechanismType is null

External Specification

Java Security Standard Algorithm Names

See Also

Provider

getInstance back to summary

getInstance	back to summary
public static TransformService getInstance(String algorithm, String mechanismType, Provider provider) throws NoSuchAlgorithmException Returns a `TransformService` that supports the specified algorithm URI (ex: `Transform#XPATH2`) and mechanism type (ex: DOM) as supplied by the specified provider. Note that the specified `Provider` object does not have to be registered in the provider list. Parameters algorithm:String the URI of the algorithm. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard transform algorithms. mechanismType:String the type of the XML processing mechanism and representation. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types. provider:Provider the `Provider` object Returns:TransformService a new `TransformService` Exceptions NoSuchAlgorithmException: if a `TransformService` implementation for the specified algorithm and mechanism type is not available from the specified `Provider` object NullPointerException: if `provider`, `algorithm`, or `mechanismType` is `null` External Specification Java Security Standard Algorithm Names See Also `Provider`

public static TransformService getInstance(String algorithm, String mechanismType, Provider provider) throws NoSuchAlgorithmException

Returns a TransformService that supports the specified algorithm URI (ex: Transform#XPATH2) and mechanism type (ex: DOM) as supplied by the specified provider. Note that the specified Provider object does not have to be registered in the provider list.

Parameters

algorithm:String: the URI of the algorithm. See the TransformService section in the Java Security Standard Algorithm Names Specification for a list of standard transform algorithms.
mechanismType:String: the type of the XML processing mechanism and representation. See the TransformService section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
provider:Provider: the Provider object

Returns:TransformService

a new TransformService

Exceptions

NoSuchAlgorithmException:: if a TransformService implementation for the specified algorithm and mechanism type is not available from the specified Provider object
NullPointerException:: if provider, algorithm, or mechanismType is null

External Specification

Java Security Standard Algorithm Names

See Also

Provider

getInstance back to summary

getInstance	back to summary
public static TransformService getInstance(String algorithm, String mechanismType, String provider) throws NoSuchAlgorithmException, NoSuchProviderException Returns a `TransformService` that supports the specified algorithm URI (ex: `Transform#XPATH2`) and mechanism type (ex: DOM) as supplied by the specified provider. The specified provider must be registered in the security provider list. Note that the list of registered providers may be retrieved via the `Security.getProviders()` method. Parameters algorithm:String the URI of the algorithm. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard transform algorithms. mechanismType:String the type of the XML processing mechanism and representation. See the `TransformService` section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types. provider:String the string name of the provider Returns:TransformService a new `TransformService` Exceptions NoSuchAlgorithmException: if a `TransformService` implementation for the specified algorithm and mechanism type is not available from the specified provider NoSuchProviderException: if the specified provider is not registered in the security provider list NullPointerException: if `provider`, `mechanismType`, or `algorithm` is `null` External Specification Java Security Standard Algorithm Names See Also `Provider`

public static TransformService getInstance(String algorithm, String mechanismType, String provider) throws NoSuchAlgorithmException, NoSuchProviderException

Returns a TransformService that supports the specified algorithm URI (ex: Transform#XPATH2) and mechanism type (ex: DOM) as supplied by the specified provider. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters

algorithm:String: the URI of the algorithm. See the TransformService section in the Java Security Standard Algorithm Names Specification for a list of standard transform algorithms.
mechanismType:String: the type of the XML processing mechanism and representation. See the TransformService section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
provider:String: the string name of the provider

Returns:TransformService

a new TransformService

Exceptions

NoSuchAlgorithmException:: if a TransformService implementation for the specified algorithm and mechanism type is not available from the specified provider
NoSuchProviderException:: if the specified provider is not registered in the security provider list
NullPointerException:: if provider, mechanismType, or algorithm is null

External Specification

Java Security Standard Algorithm Names

See Also

Provider

getMechanismType back to summary

getMechanismType	back to summary
public final String getMechanismType() Returns the mechanism type supported by this `TransformService`. Returns:String the mechanism type

public final String getMechanismType()

Returns the mechanism type supported by this TransformService.

Returns:String: the mechanism type

getProvider back to summary

getProvider	back to summary
public final Provider getProvider() Returns the provider of this `TransformService`. Returns:Provider the provider

public final Provider getProvider()

Returns the provider of this TransformService.

Returns:Provider: the provider

init back to summary

init	back to summary
public abstract void init(TransformParameterSpec params) throws InvalidAlgorithmParameterException Initializes this `TransformService` with the specified parameters. If the parameters exist in XML form, the `init(XMLStructure, XMLCryptoContext)` method should be used to initialize the `TransformService`. Parameters params:TransformParameterSpec the algorithm parameters (may be `null` if not required or optional) Exceptions InvalidAlgorithmParameterException: if the specified parameters are invalid for this algorithm

public abstract void init(TransformParameterSpec params) throws InvalidAlgorithmParameterException

Initializes this TransformService with the specified parameters.

If the parameters exist in XML form, the init(XMLStructure, XMLCryptoContext) method should be used to initialize the TransformService.

Parameters

params:TransformParameterSpec: the algorithm parameters (may be null if not required or optional)

Exceptions

InvalidAlgorithmParameterException:: if the specified parameters are invalid for this algorithm

init back to summary

init	back to summary
public abstract void init(XMLStructure parent, XMLCryptoContext context) throws InvalidAlgorithmParameterException Initializes this `TransformService` with the specified parameters and document context. Parameters parent:XMLStructure a mechanism-specific structure containing the parent structure context:XMLCryptoContext the `XMLCryptoContext` containing additional context (may be `null` if not applicable) Exceptions InvalidAlgorithmParameterException: if the specified parameters are invalid for this algorithm ClassCastException: if the type of `parent` or `context` is not compatible with this `TransformService` NullPointerException: if `parent` is `null`

public abstract void init(XMLStructure parent, XMLCryptoContext context) throws InvalidAlgorithmParameterException

Initializes this TransformService with the specified parameters and document context.

Parameters

parent:XMLStructure: a mechanism-specific structure containing the parent structure
context:XMLCryptoContext: the XMLCryptoContext containing additional context (may be null if not applicable)

Exceptions

InvalidAlgorithmParameterException:: if the specified parameters are invalid for this algorithm
ClassCastException:: if the type of parent or context is not compatible with this TransformService
NullPointerException:: if parent is null

marshalParams back to summary

marshalParams	back to summary
public abstract void marshalParams(XMLStructure parent, XMLCryptoContext context) throws MarshalException Marshals the algorithm-specific parameters. If there are no parameters to be marshalled, this method returns without throwing an exception. Parameters parent:XMLStructure a mechanism-specific structure containing the parent node that the marshalled parameters should be appended to context:XMLCryptoContext the `XMLCryptoContext` containing additional context (may be `null` if not applicable) Exceptions MarshalException: if the parameters cannot be marshalled ClassCastException: if the type of `parent` or `context` is not compatible with this `TransformService` NullPointerException: if `parent` is `null`

public abstract void marshalParams(XMLStructure parent, XMLCryptoContext context) throws MarshalException

Marshals the algorithm-specific parameters. If there are no parameters to be marshalled, this method returns without throwing an exception.

Parameters

parent:XMLStructure: a mechanism-specific structure containing the parent node that the marshalled parameters should be appended to
context:XMLCryptoContext: the XMLCryptoContext containing additional context (may be null if not applicable)

Exceptions

MarshalException:: if the parameters cannot be marshalled
ClassCastException:: if the type of parent or context is not compatible with this TransformService
NullPointerException:: if parent is null

javax.xml.crypto.dsig back to summary

private Class TransformService.MechanismMapEntry

Class Inheritance

extends Object
implements Map.Entry<String, String>

java.lang.Object
javax.xml.crypto.dsig.TransformService.MechanismMapEntry

All Implemented Interfaces

java.util.Map.Entry

Field Summary

Modifier and Type	Field and Description
private final String	algorithm
private final String	key
private final String	mechanism

Constructor Summary

Access	Constructor and Description
pack-priv	MechanismMapEntry(String algorithm, String mechanism)

Method Summary

Modifier and Type	Method and Description
public boolean	equals(Object o) Overrides java.lang.Object.equals. Implements java.util.Map.Entry.equals. Compares the specified object with this entry for equality.
public String	getKey() Implements java.util.Map.Entry.getKey. Returns the key corresponding to this entry.
public String	getValue() Implements java.util.Map.Entry.getValue. Returns the value corresponding to this entry.
public int	hashCode() Overrides java.lang.Object.hashCode. Implements java.util.Map.Entry.hashCode. Returns the hash code value for this map entry.
public String	setValue(String value) Implements java.util.Map.Entry.setValue. Replaces the value corresponding to this entry with the specified value (optional operation).

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll toString wait wait wait

Field Detail

algorithm	back to summary
private final String algorithm

key	back to summary
private final String key

mechanism	back to summary
private final String mechanism

Constructor Detail

MechanismMapEntry	back to summary
pack-priv MechanismMapEntry(String algorithm, String mechanism)

Method Detail

equals back to summary

equals	back to summary
public boolean equals(Object o) Overrides java.lang.Object.equals. Implements java.util.Map.Entry.equals. Doc from java.util.Map.Entry.equals. Compares the specified object with this entry for equality. Returns `true` if the given object is also a map entry and the two entries represent the same mapping. More formally, two entries `e1` and `e2` represent the same mapping if (e1.getKey()==null ? e2.getKey()==null : e1.getKey().equals(e2.getKey())) && (e1.getValue()==null ? e2.getValue()==null : e1.getValue().equals(e2.getValue())) This ensures that the `equals` method works properly across different implementations of the `Map.Entry` interface.

public boolean equals(Object o)

Overrides java.lang.Object.equals.

Implements java.util.Map.Entry.equals.

Doc from java.util.Map.Entry.equals.

Compares the specified object with this entry for equality. Returns true if the given object is also a map entry and the two entries represent the same mapping. More formally, two entries e1 and e2 represent the same mapping if

    (e1.getKey()==null ?
     e2.getKey()==null : e1.getKey().equals(e2.getKey()))  &&
    (e1.getValue()==null ?
     e2.getValue()==null : e1.getValue().equals(e2.getValue()))

This ensures that the equals method works properly across different implementations of the Map.Entry interface.

getKey	back to summary
public String getKey() Implements java.util.Map.Entry.getKey. Doc from java.util.Map.Entry.getKey. Returns the key corresponding to this entry.

getKey

back to summary

public String getKey()

Implements java.util.Map.Entry.getKey.

Doc from java.util.Map.Entry.getKey.

Returns the key corresponding to this entry.

getValue back to summary

getValue	back to summary
public String getValue() Implements java.util.Map.Entry.getValue. Doc from java.util.Map.Entry.getValue. Returns the value corresponding to this entry. If the mapping has been removed from the backing map (by the iterator's `remove` operation), the results of this call are undefined.

public String getValue()

Implements java.util.Map.Entry.getValue.

Doc from java.util.Map.Entry.getValue.

Returns the value corresponding to this entry. If the mapping has been removed from the backing map (by the iterator's remove operation), the results of this call are undefined.

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Implements java.util.Map.Entry.hashCode. Doc from java.util.Map.Entry.hashCode. Returns the hash code value for this map entry. The hash code of a map entry `e` is defined to be: (e.getKey()==null ? 0 : e.getKey().hashCode()) ^ (e.getValue()==null ? 0 : e.getValue().hashCode()) This ensures that `e1.equals(e2)` implies that `e1.hashCode()==e2.hashCode()` for any two Entries `e1` and `e2`, as required by the general contract of `Object.hashCode`.

public int hashCode()

Overrides java.lang.Object.hashCode.

Implements java.util.Map.Entry.hashCode.

Doc from java.util.Map.Entry.hashCode.

Returns the hash code value for this map entry. The hash code of a map entry e is defined to be:

    (e.getKey()==null   ? 0 : e.getKey().hashCode()) ^
    (e.getValue()==null ? 0 : e.getValue().hashCode())

This ensures that e1.equals(e2) implies that e1.hashCode()==e2.hashCode() for any two Entries e1 and e2, as required by the general contract of Object.hashCode.

setValue back to summary

setValue	back to summary
public String setValue(String value) Implements java.util.Map.Entry.setValue. Doc from java.util.Map.Entry.setValue. Replaces the value corresponding to this entry with the specified value (optional operation). (Writes through to the map.) The behavior of this call is undefined if the mapping has already been removed from the map (by the iterator's `remove` operation).

public String setValue(String value)

Implements java.util.Map.Entry.setValue.

Doc from java.util.Map.Entry.setValue.

Replaces the value corresponding to this entry with the specified value (optional operation). (Writes through to the map.) The behavior of this call is undefined if the mapping has already been removed from the map (by the iterator's remove operation).

public abstract Class TransformService

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class TransformService.MechanismMapEntry

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail