Module java.xml.crypto
Package javax.xml.crypto.dsig

# Class TransformService

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

All Implemented Interfaces:
  `AlgorithmMethod`, `Transform`, `XMLStructure`

public abstract class TransformService extends Object implements Transform
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 `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.

Since:
  1.6

## Field Summary

### Fields declared in interface javax.xml.crypto.dsig.Transform

`BASE64, ENVELOPED, XPATH, XPATH2, XSLT`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`TransformService()`
Default constructor, for invocation by subclasses.

## Method Summary

Modifier and Type
Method
Description
`final String`
`getAlgorithm()`
Returns the URI of the algorithm supported by this `TransformService`.
`static TransformService`
`getInstance(String algorithm, String mechanismType)`
Returns a `TransformService` that supports the specified algorithm URI (ex: `Transform.XPATH2`) and mechanism type (ex: DOM).
`static TransformService`
`getInstance(String algorithm, String mechanismType, String provider)`
Returns a `TransformService` that supports the specified algorithm URI (ex: `Transform.XPATH2`) and mechanism type (ex: DOM) as supplied by the specified provider.
`static TransformService`
`getInstance(String algorithm, String mechanismType, 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.
`final String`
`getMechanismType()`
Returns the mechanism type supported by this `TransformService`.
`final Provider`
`getProvider()`
Returns the provider of this `TransformService`.
`abstract void`
`init(TransformParameterSpec params)`
Initializes this `TransformService` with the specified parameters.
`abstract void`
`init(XMLStructure parent, XMLCryptoContext context)`
Initializes this `TransformService` with the specified parameters and document context.
`abstract void`
`marshalParams(XMLStructure parent, XMLCryptoContext context)`
Marshals the algorithm-specific parameters.

### Methods declared in class java.lang.Object

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

### Methods declared in interface javax.xml.crypto.dsig.Transform

`getParameterSpec, transform, transform`

### Methods declared in interface javax.xml.crypto.XMLStructure

`isFeatureSupported`

## Constructor Details

### TransformService

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

## Method Details

### getInstance

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` - 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` - 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:
  a new `TransformService`
Throws:
  `NullPointerException` - if `algorithm` or `mechanismType` is `null`
  `NoSuchAlgorithmException` - if no `Provider` supports a `TransformService` implementation for the specified algorithm and mechanism type
See Also:
  - `Provider`

### getInstance

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` - 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` - 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` - the `Provider` object
Returns:
  a new `TransformService`
Throws:
  `NullPointerException` - if `provider`, `algorithm`, or `mechanismType` is `null`
  `NoSuchAlgorithmException` - if a `TransformService` implementation for the specified algorithm and mechanism type is not available from the specified `Provider` object
See Also:
  - `Provider`

### getInstance

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` - 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` - 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` - the string name of the provider
Returns:
  a new `TransformService`
Throws:
  `NoSuchProviderException` - if the specified provider is not registered in the security provider list
  `NullPointerException` - if `provider`, `mechanismType`, or `algorithm` is `null`
  `NoSuchAlgorithmException` - if a `TransformService` implementation for the specified algorithm and mechanism type is not available from the specified provider
See Also:
  - `Provider`

### getMechanismType

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

Returns:
  the mechanism type

### getAlgorithm

public final String getAlgorithm()
Returns the URI of the algorithm supported by this `TransformService`.

Specified by:
  `getAlgorithm` in interface `AlgorithmMethod`
Returns:
  the algorithm URI

### getProvider

public final Provider getProvider()
Returns the provider of this `TransformService`.

Returns:
  the provider

### init

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` - the algorithm parameters (may be `null` if not required or optional)
Throws:
  `InvalidAlgorithmParameterException` - if the specified parameters are invalid for this algorithm

### marshalParams

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` - a mechanism-specific structure containing the parent node that the marshalled parameters should be appended to
  `context` - the `XMLCryptoContext` containing additional context (may be `null` if not applicable)
Throws:
  `ClassCastException` - if the type of `parent` or `context` is not compatible with this `TransformService`
  `NullPointerException` - if `parent` is `null`
  `MarshalException` - if the parameters cannot be marshalled

### init

public abstract void init(XMLStructure parent, XMLCryptoContext context) throws InvalidAlgorithmParameterException
Initializes this `TransformService` with the specified parameters and document context.

Parameters:
  `parent` - a mechanism-specific structure containing the parent structure
  `context` - the `XMLCryptoContext` containing additional context (may be `null` if not applicable)
Throws:
  `ClassCastException` - if the type of `parent` or `context` is not compatible with this `TransformService`
  `NullPointerException` - if `parent` is `null`
  `InvalidAlgorithmParameterException` - if the specified parameters are invalid for this algorithm