TransformService (Java SE 26 & JDK 26)
Description: declaration: module: java.xml.crypto, package: javax.xml.crypto.dsig, class: TransformService
Keywords: javax.xml.crypto.dsig.TransformService class

# 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
External Specifications
  - Java Security Standard Algorithm Names

- ## Field Summary

  ### Fields declared in interface Transform

  `BASE64, ENVELOPED, XPATH, XPATH2, XSLT`
  Modifier and Type
  Field
  Description
  `static final String`
  `BASE64`
  The Base64 transform algorithm URI.
  `static final String`
  `ENVELOPED`
  The Enveloped Signature transform algorithm URI.
  `static final String`
  `XPATH`
  The XPath transform algorithm URI.
  `static final String`
  `XPATH2`
  The XPath Filter 2 transform algorithm URI.
  `static final String`
  `XSLT`
  The XSLT transform algorithm URI.

- ## 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 Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

  ### Methods declared in interface Transform

  `getParameterSpec, transform, transform`
  Modifier and Type
  Method
  Description
  `AlgorithmParameterSpec`
  `getParameterSpec()`
  Returns the algorithm-specific input parameters associated with this `Transform`.
  `Data`
  `transform(Data data, XMLCryptoContext context)`
  Transforms the specified data using the underlying transform algorithm.
  `Data`
  `transform(Data data, XMLCryptoContext context, OutputStream os)`
  Transforms the specified data using the underlying transform algorithm.

  ### Methods declared in interface XMLStructure

  `isFeatureSupported`
  Modifier and Type
  Method
  Description
  `boolean`
  `isFeatureSupported(String feature)`
  Indicates whether a specified feature is supported.

- ## 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
    External Specifications
      - Java Security Standard Algorithm Names
    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
    External Specifications
      - Java Security Standard Algorithm Names
    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
    External Specifications
      - Java Security Standard Algorithm Names
    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