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

# Class XMLSignatureFactory

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

public abstract class XMLSignatureFactory extends Object
A factory for creating `XMLSignature` objects from scratch or for unmarshalling an `XMLSignature` object from a corresponding XML representation.

## XMLSignatureFactory Type

Each instance of `XMLSignatureFactory` supports a specific XML mechanism type. To create an `XMLSignatureFactory`, call one of the static `getInstance` methods, passing in the XML mechanism type desired, for example:

> `XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");`

The objects that this factory produces will be based on DOM and abide by the DOM interoperability requirements as defined in the DOM Mechanism Requirements. See the `XMLSignatureFactory` section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.

`XMLSignatureFactory` implementations are registered and loaded using the `Provider` mechanism. For example, a service provider that supports the DOM mechanism would be specified in the `Provider` subclass as:

        put("XMLSignatureFactory.DOM", "org.example.DOMXMLSignatureFactory");

An implementation MUST minimally support the default mechanism type: DOM.

Note that a caller must use the same `XMLSignatureFactory` instance to create the `XMLStructure`s of a particular `XMLSignature` that is to be generated. The behavior is undefined if `XMLStructure`s from different providers or different mechanism types are used together.

Also, the `XMLStructure`s that are created by this factory may contain state specific to the `XMLSignature` and are not intended to be reusable.

## Creating XMLSignatures from scratch

Once the `XMLSignatureFactory` has been created, objects can be instantiated by calling the appropriate method. For example, a `Reference` instance may be created by invoking one of the `newReference` methods.

## Unmarshalling XMLSignatures from XML

Alternatively, an `XMLSignature` may be created from an existing XML representation by invoking the `unmarshalXMLSignature` method and passing it a mechanism-specific `XMLValidateContext` instance containing the XML content:

    DOMValidateContext context = new DOMValidateContext(key, signatureElement);
    XMLSignature signature = factory.unmarshalXMLSignature(context);

Each `XMLSignatureFactory` must support the required `XMLValidateContext` types for that factory type, but may support others. A DOM `XMLSignatureFactory` must support `DOMValidateContext` objects.

## Signing and marshalling XMLSignatures to XML

Each `XMLSignature` created by the factory can also be marshalled to an XML representation and signed, by invoking the `sign` method of the `XMLSignature` object and passing it a mechanism-specific `XMLSignContext` object containing the signing key and marshalling parameters (see `DOMSignContext`). For example:

       DOMSignContext context = new DOMSignContext(privateKey, document);
       signature.sign(context);

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 `XMLSignatureFactory` instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different `XMLSignatureFactory` instance need not synchronize.

Since:
  1.6
External Specifications
  - Java Security Standard Algorithm Names

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static XMLSignatureFactory`
  `getInstance()`
  Returns an `XMLSignatureFactory` that supports the default XML processing mechanism and representation type ("DOM").
  `static XMLSignatureFactory`
  `getInstance(String mechanismType)`
  Returns an `XMLSignatureFactory` that supports the specified XML processing mechanism and representation type (ex: "DOM").
  `static XMLSignatureFactory`
  `getInstance(String mechanismType, String provider)`
  Returns an `XMLSignatureFactory` that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
  `static XMLSignatureFactory`
  `getInstance(String mechanismType, Provider provider)`
  Returns an `XMLSignatureFactory` that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
  `final KeyInfoFactory`
  `getKeyInfoFactory()`
  Returns a `KeyInfoFactory` that creates `KeyInfo` objects.
  `final String`
  `getMechanismType()`
  Returns the type of the XML processing mechanism and representation supported by this `XMLSignatureFactory` (ex: "DOM").
  `final Provider`
  `getProvider()`
  Returns the provider of this `XMLSignatureFactory`.
  `abstract URIDereferencer`
  `getURIDereferencer()`
  Returns a reference to the `URIDereferencer` that is used by default to dereference URIs in `Reference` objects.
  `abstract boolean`
  `isFeatureSupported(String feature)`
  Indicates whether a specified feature is supported.
  `abstract CanonicalizationMethod`
  `newCanonicalizationMethod(String algorithm, C14NMethodParameterSpec params)`
  Creates a `CanonicalizationMethod` for the specified algorithm URI and parameters.
  `abstract CanonicalizationMethod`
  `newCanonicalizationMethod(String algorithm, XMLStructure params)`
  Creates a `CanonicalizationMethod` for the specified algorithm URI and parameters.
  `abstract DigestMethod`
  `newDigestMethod(String algorithm, DigestMethodParameterSpec params)`
  Creates a `DigestMethod` for the specified algorithm URI and parameters.
  `abstract Manifest`
  `newManifest(List<? extends Reference> references)`
  Creates a `Manifest` containing the specified list of `Reference`s.
  `abstract Manifest`
  `newManifest(List<? extends Reference> references, String id)`
  Creates a `Manifest` containing the specified list of `Reference`s and optional id.
  `abstract Reference`
  `newReference(String uri, DigestMethod dm)`
  Creates a `Reference` with the specified URI and digest method.
  `abstract Reference`
  `newReference(String uri, DigestMethod dm, List<? extends Transform> transforms, String type, String id)`
  Creates a `Reference` with the specified parameters.
  `abstract Reference`
  `newReference(String uri, DigestMethod dm, List<? extends Transform> transforms, String type, String id, byte[] digestValue)`
  Creates a `Reference` with the specified parameters and pre-calculated digest value.
  `abstract Reference`
  `newReference(String uri, DigestMethod dm, List<? extends Transform> appliedTransforms, Data result, List<? extends Transform> transforms, String type, String id)`
  Creates a `Reference` with the specified parameters.
  `abstract SignatureMethod`
  `newSignatureMethod(String algorithm, SignatureMethodParameterSpec params)`
  Creates a `SignatureMethod` for the specified algorithm URI and parameters.
  `abstract SignatureProperties`
  `newSignatureProperties(List<? extends SignatureProperty> properties, String id)`
  Creates a `SignatureProperties` containing the specified list of `SignatureProperty`s and optional id.
  `abstract SignatureProperty`
  `newSignatureProperty(List<? extends XMLStructure> content, String target, String id)`
  Creates a `SignatureProperty` containing the specified list of `XMLStructure`s, target URI and optional id.
  `abstract SignedInfo`
  `newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List<? extends Reference> references)`
  Creates a `SignedInfo` with the specified canonicalization and signature methods, and list of one or more references.
  `abstract SignedInfo`
  `newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List<? extends Reference> references, String id)`
  Creates a `SignedInfo` with the specified parameters.
  `abstract Transform`
  `newTransform(String algorithm, TransformParameterSpec params)`
  Creates a `Transform` for the specified algorithm URI and parameters.
  `abstract Transform`
  `newTransform(String algorithm, XMLStructure params)`
  Creates a `Transform` for the specified algorithm URI and parameters.
  `abstract XMLObject`
  `newXMLObject(List<? extends XMLStructure> content, String id, String mimeType, String encoding)`
  Creates an `XMLObject` from the specified parameters.
  `abstract XMLSignature`
  `newXMLSignature(SignedInfo si, KeyInfo ki)`
  Creates an `XMLSignature` and initializes it with the contents of the specified `SignedInfo` and `KeyInfo` objects.
  `abstract XMLSignature`
  `newXMLSignature(SignedInfo si, KeyInfo ki, List<? extends XMLObject> objects, String id, String signatureValueId)`
  Creates an `XMLSignature` and initializes it with the specified parameters.
  `abstract XMLSignature`
  `unmarshalXMLSignature(XMLValidateContext context)`
  Unmarshals a new `XMLSignature` instance from a mechanism-specific `XMLValidateContext` instance.
  `abstract XMLSignature`
  `unmarshalXMLSignature(XMLStructure xmlStructure)`
  Unmarshals a new `XMLSignature` instance from a mechanism-specific `XMLStructure` instance.

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

- ## Constructor Details

  - ### XMLSignatureFactory

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

- ## Method Details

  - ### getInstance

    public static XMLSignatureFactory getInstance(String mechanismType)
    Returns an `XMLSignatureFactory` that supports the specified XML processing mechanism and representation type (ex: "DOM").

    This method uses the standard JCA provider lookup mechanism to locate and instantiate an `XMLSignatureFactory` implementation of the desired mechanism type. It traverses the list of registered security `Provider`s, starting with the most preferred `Provider`. A new `XMLSignatureFactory` object from the first `Provider` that supports the specified mechanism 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:
      `mechanismType` - the type of the XML processing mechanism and representation. See the `XMLSignatureFactory` section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
    Returns:
      a new `XMLSignatureFactory`
    Throws:
      `NullPointerException` - if `mechanismType` is `null`
      `NoSuchMechanismException` - if no `Provider` supports an `XMLSignatureFactory` implementation for the specified mechanism
    External Specifications
      - Java Security Standard Algorithm Names
    See Also:
      - `Provider`

  - ### getInstance

    public static XMLSignatureFactory getInstance(String mechanismType, Provider provider)
    Returns an `XMLSignatureFactory` that supports the requested XML processing mechanism and representation 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:
      `mechanismType` - the type of the XML processing mechanism and representation. See the `XMLSignatureFactory` section in the Java Security Standard Algorithm Names Specification for a list of standard mechanism types.
      `provider` - the `Provider` object
    Returns:
      a new `XMLSignatureFactory`
    Throws:
      `NullPointerException` - if `provider` or `mechanismType` is `null`
      `NoSuchMechanismException` - if an `XMLSignatureFactory` implementation for the specified mechanism is not available from the specified `Provider` object
    External Specifications
      - Java Security Standard Algorithm Names
    See Also:
      - `Provider`

  - ### getInstance

    public static XMLSignatureFactory getInstance(String mechanismType, String provider) throws NoSuchProviderException
    Returns an `XMLSignatureFactory` that supports the requested XML processing mechanism and representation 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:
      `mechanismType` - the type of the XML processing mechanism and representation. See the `XMLSignatureFactory` 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 `XMLSignatureFactory`
    Throws:
      `NoSuchProviderException` - if the specified provider is not registered in the security provider list
      `NullPointerException` - if `provider` or `mechanismType` is `null`
      `NoSuchMechanismException` - if an `XMLSignatureFactory` implementation for the specified mechanism is not available from the specified provider
    External Specifications
      - Java Security Standard Algorithm Names
    See Also:
      - `Provider`

  - ### getInstance

    public static XMLSignatureFactory getInstance()
    Returns an `XMLSignatureFactory` that supports the default XML processing mechanism and representation type ("DOM").

    This method uses the standard JCA provider lookup mechanism to locate and instantiate an `XMLSignatureFactory` implementation of the default mechanism type. It traverses the list of registered security `Provider`s, starting with the most preferred `Provider`. A new `XMLSignatureFactory` object from the first `Provider` that supports the DOM mechanism is returned.

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

    Returns:
      a new `XMLSignatureFactory`
    Throws:
      `NoSuchMechanismException` - if no `Provider` supports an `XMLSignatureFactory` implementation for the DOM mechanism
    See Also:
      - `Provider`

  - ### getMechanismType

    public final String getMechanismType()
    Returns the type of the XML processing mechanism and representation supported by this `XMLSignatureFactory` (ex: "DOM").
    Returns:
      the XML processing mechanism type supported by this `XMLSignatureFactory`

  - ### getProvider

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

  - ### newXMLSignature

    public abstract XMLSignature newXMLSignature(SignedInfo si, KeyInfo ki)
    Creates an `XMLSignature` and initializes it with the contents of the specified `SignedInfo` and `KeyInfo` objects.
    Parameters:
      `si` - the signed info
      `ki` - the key info (may be `null`)
    Returns:
      an `XMLSignature`
    Throws:
      `NullPointerException` - if `si` is `null`

  - ### newXMLSignature

    public abstract XMLSignature newXMLSignature(SignedInfo si, KeyInfo ki, List<? extends XMLObject> objects, String id, String signatureValueId)
    Creates an `XMLSignature` and initializes it with the specified parameters.
    Parameters:
      `si` - the signed info
      `ki` - the key info (may be `null`)
      `objects` - a list of `XMLObject`s (may be empty or `null`)
      `id` - the Id (may be `null`)
      `signatureValueId` - the SignatureValue Id (may be `null`)
    Returns:
      an `XMLSignature`
    Throws:
      `NullPointerException` - if `si` is `null`
      `ClassCastException` - if any of the `objects` are not of type `XMLObject`

  - ### newReference

    public abstract Reference newReference(String uri, DigestMethod dm)
    Creates a `Reference` with the specified URI and digest method.
    Parameters:
      `uri` - the reference URI (may be `null`)
      `dm` - the digest method
    Returns:
      a `Reference`
    Throws:
      `IllegalArgumentException` - if `uri` is not RFC 2396 compliant
      `NullPointerException` - if `dm` is `null`

  - ### newReference

    public abstract Reference newReference(String uri, DigestMethod dm, List<? extends Transform> transforms, String type, String id)
    Creates a `Reference` with the specified parameters.
    Parameters:
      `uri` - the reference URI (may be `null`)
      `dm` - the digest method
      `transforms` - a list of `Transform`s. The list is defensively copied to protect against subsequent modification. May be `null` or empty.
      `type` - the reference type, as a URI (may be `null`)
      `id` - the reference ID (may be `null`)
    Returns:
      a `Reference`
    Throws:
      `ClassCastException` - if any of the `transforms` are not of type `Transform`
      `IllegalArgumentException` - if `uri` is not RFC 2396 compliant
      `NullPointerException` - if `dm` is `null`

  - ### newReference

    public abstract Reference newReference(String uri, DigestMethod dm, List<? extends Transform> transforms, String type, String id, byte[] digestValue)
    Creates a `Reference` with the specified parameters and pre-calculated digest value.

    This method is useful when the digest value of a `Reference` has been previously computed. See for example, the OASIS-DSS (Digital Signature Services) specification.

    Parameters:
      `uri` - the reference URI (may be `null`)
      `dm` - the digest method
      `transforms` - a list of `Transform`s. The list is defensively copied to protect against subsequent modification. May be `null` or empty.
      `type` - the reference type, as a URI (may be `null`)
      `id` - the reference ID (may be `null`)
      `digestValue` - the digest value. The array is cloned to protect against subsequent modification.
    Returns:
      a `Reference`
    Throws:
      `ClassCastException` - if any of the `transforms` are not of type `Transform`
      `IllegalArgumentException` - if `uri` is not RFC 2396 compliant
      `NullPointerException` - if `dm` or `digestValue` is `null`

  - ### newReference

    public abstract Reference newReference(String uri, DigestMethod dm, List<? extends Transform> appliedTransforms, Data result, List<? extends Transform> transforms, String type, String id)
    Creates a `Reference` with the specified parameters.

    This method is useful when a list of transforms have already been applied to the `Reference`. See for example, the OASIS-DSS (Digital Signature Services) specification.

    When an `XMLSignature` containing this reference is generated, the specified `transforms` (if non-null) are applied to the specified `result`. The `Transforms` element of the resulting `Reference` element is set to the concatenation of the `appliedTransforms` and `transforms`.

    Parameters:
      `uri` - the reference URI (may be `null`)
      `dm` - the digest method
      `appliedTransforms` - a list of `Transform`s that have already been applied. The list is defensively copied to protect against subsequent modification. The list must contain at least one entry.
      `result` - the result of processing the sequence of `appliedTransforms`
      `transforms` - a list of `Transform`s that are to be applied when generating the signature. The list is defensively copied to protect against subsequent modification. May be `null` or empty.
      `type` - the reference type, as a URI (may be `null`)
      `id` - the reference ID (may be `null`)
    Returns:
      a `Reference`
    Throws:
      `ClassCastException` - if any of the transforms (in either list) are not of type `Transform`
      `IllegalArgumentException` - if `uri` is not RFC 2396 compliant or `appliedTransforms` is empty
      `NullPointerException` - if `dm`, `appliedTransforms` or `result` is `null`

  - ### newSignedInfo

    public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List<? extends Reference> references)
    Creates a `SignedInfo` with the specified canonicalization and signature methods, and list of one or more references.
    Parameters:
      `cm` - the canonicalization method
      `sm` - the signature method
      `references` - a list of one or more `Reference`s. The list is defensively copied to protect against subsequent modification.
    Returns:
      a `SignedInfo`
    Throws:
      `ClassCastException` - if any of the references are not of type `Reference`
      `IllegalArgumentException` - if `references` is empty
      `NullPointerException` - if any of the parameters are `null`

  - ### newSignedInfo

    public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List<? extends Reference> references, String id)
    Creates a `SignedInfo` with the specified parameters.
    Parameters:
      `cm` - the canonicalization method
      `sm` - the signature method
      `references` - a list of one or more `Reference`s. The list is defensively copied to protect against subsequent modification.
      `id` - the id (may be `null`)
    Returns:
      a `SignedInfo`
    Throws:
      `ClassCastException` - if any of the references are not of type `Reference`
      `IllegalArgumentException` - if `references` is empty
      `NullPointerException` - if `cm`, `sm`, or `references` are `null`

  - ### newXMLObject

    public abstract XMLObject newXMLObject(List<? extends XMLStructure> content, String id, String mimeType, String encoding)
    Creates an `XMLObject` from the specified parameters.
    Parameters:
      `content` - a list of `XMLStructure`s. The list is defensively copied to protect against subsequent modification. May be `null` or empty.
      `id` - the Id (may be `null`)
      `mimeType` - the mime type (may be `null`)
      `encoding` - the encoding (may be `null`)
    Returns:
      an `XMLObject`
    Throws:
      `ClassCastException` - if `content` contains any entries that are not of type `XMLStructure`

  - ### newManifest

    public abstract Manifest newManifest(List<? extends Reference> references)
    Creates a `Manifest` containing the specified list of `Reference`s.
    Parameters:
      `references` - a list of one or more `Reference`s. The list is defensively copied to protect against subsequent modification.
    Returns:
      a `Manifest`
    Throws:
      `NullPointerException` - if `references` is `null`
      `IllegalArgumentException` - if `references` is empty
      `ClassCastException` - if `references` contains any entries that are not of type `Reference`

  - ### newManifest

    public abstract Manifest newManifest(List<? extends Reference> references, String id)
    Creates a `Manifest` containing the specified list of `Reference`s and optional id.
    Parameters:
      `references` - a list of one or more `Reference`s. The list is defensively copied to protect against subsequent modification.
      `id` - the id (may be `null`)
    Returns:
      a `Manifest`
    Throws:
      `NullPointerException` - if `references` is `null`
      `IllegalArgumentException` - if `references` is empty
      `ClassCastException` - if `references` contains any entries that are not of type `Reference`

  - ### newSignatureProperty

    public abstract SignatureProperty newSignatureProperty(List<? extends XMLStructure> content, String target, String id)
    Creates a `SignatureProperty` containing the specified list of `XMLStructure`s, target URI and optional id.
    Parameters:
      `content` - a list of one or more `XMLStructure`s. The list is defensively copied to protect against subsequent modification.
      `target` - the target URI of the Signature that this property applies to
      `id` - the id (may be `null`)
    Returns:
      a `SignatureProperty`
    Throws:
      `NullPointerException` - if `content` or `target` is `null`
      `IllegalArgumentException` - if `content` is empty
      `ClassCastException` - if `content` contains any entries that are not of type `XMLStructure`

  - ### newSignatureProperties

    public abstract SignatureProperties newSignatureProperties(List<? extends SignatureProperty> properties, String id)
    Creates a `SignatureProperties` containing the specified list of `SignatureProperty`s and optional id.
    Parameters:
      `properties` - a list of one or more `SignatureProperty`s. The list is defensively copied to protect against subsequent modification.
      `id` - the id (may be `null`)
    Returns:
      a `SignatureProperties`
    Throws:
      `NullPointerException` - if `properties` is `null`
      `IllegalArgumentException` - if `properties` is empty
      `ClassCastException` - if `properties` contains any entries that are not of type `SignatureProperty`

  - ### newDigestMethod

    public abstract DigestMethod newDigestMethod(String algorithm, DigestMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a `DigestMethod` for the specified algorithm URI and parameters.
    Parameters:
      `algorithm` - the URI identifying the digest algorithm
      `params` - algorithm-specific digest parameters (may be `null`)
    Returns:
      the `DigestMethod`
    Throws:
      `InvalidAlgorithmParameterException` - if the specified parameters are inappropriate for the requested algorithm
      `NoSuchAlgorithmException` - if an implementation of the specified algorithm cannot be found
      `NullPointerException` - if `algorithm` is `null`

  - ### newSignatureMethod

    public abstract SignatureMethod newSignatureMethod(String algorithm, SignatureMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a `SignatureMethod` for the specified algorithm URI and parameters.
    Parameters:
      `algorithm` - the URI identifying the signature algorithm
      `params` - algorithm-specific signature parameters (may be `null`)
    Returns:
      the `SignatureMethod`
    Throws:
      `InvalidAlgorithmParameterException` - if the specified parameters are inappropriate for the requested algorithm
      `NoSuchAlgorithmException` - if an implementation of the specified algorithm cannot be found
      `NullPointerException` - if `algorithm` is `null`

  - ### newTransform

    public abstract Transform newTransform(String algorithm, TransformParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a `Transform` for the specified algorithm URI and parameters.
    Parameters:
      `algorithm` - the URI identifying the transform algorithm
      `params` - algorithm-specific transform parameters (may be `null`)
    Returns:
      the `Transform`
    Throws:
      `InvalidAlgorithmParameterException` - if the specified parameters are inappropriate for the requested algorithm
      `NoSuchAlgorithmException` - if an implementation of the specified algorithm cannot be found
      `NullPointerException` - if `algorithm` is `null`

  - ### newTransform

    public abstract Transform newTransform(String algorithm, XMLStructure params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a `Transform` for the specified algorithm URI and parameters. The parameters are specified as a mechanism-specific `XMLStructure` (ex: `DOMStructure`). This method is useful when the parameters are in XML form or there is no standard class for specifying the parameters.
    Parameters:
      `algorithm` - the URI identifying the transform algorithm
      `params` - a mechanism-specific XML structure from which to unmarshal the parameters from (may be `null` if not required or optional)
    Returns:
      the `Transform`
    Throws:
      `ClassCastException` - if the type of `params` is inappropriate for this `XMLSignatureFactory`
      `InvalidAlgorithmParameterException` - if the specified parameters are inappropriate for the requested algorithm
      `NoSuchAlgorithmException` - if an implementation of the specified algorithm cannot be found
      `NullPointerException` - if `algorithm` is `null`

  - ### newCanonicalizationMethod

    public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm, C14NMethodParameterSpec params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a `CanonicalizationMethod` for the specified algorithm URI and parameters.
    Parameters:
      `algorithm` - the URI identifying the canonicalization algorithm
      `params` - algorithm-specific canonicalization parameters (may be `null`)
    Returns:
      the `CanonicalizationMethod`
    Throws:
      `InvalidAlgorithmParameterException` - if the specified parameters are inappropriate for the requested algorithm
      `NoSuchAlgorithmException` - if an implementation of the specified algorithm cannot be found
      `NullPointerException` - if `algorithm` is `null`

  - ### newCanonicalizationMethod

    public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm, XMLStructure params) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException
    Creates a `CanonicalizationMethod` for the specified algorithm URI and parameters. The parameters are specified as a mechanism-specific `XMLStructure` (ex: `DOMStructure`). This method is useful when the parameters are in XML form or there is no standard class for specifying the parameters.
    Parameters:
      `algorithm` - the URI identifying the canonicalization algorithm
      `params` - a mechanism-specific XML structure from which to unmarshal the parameters from (may be `null` if not required or optional)
    Returns:
      the `CanonicalizationMethod`
    Throws:
      `ClassCastException` - if the type of `params` is inappropriate for this `XMLSignatureFactory`
      `InvalidAlgorithmParameterException` - if the specified parameters are inappropriate for the requested algorithm
      `NoSuchAlgorithmException` - if an implementation of the specified algorithm cannot be found
      `NullPointerException` - if `algorithm` is `null`

  - ### getKeyInfoFactory

    public final KeyInfoFactory getKeyInfoFactory()
    Returns a `KeyInfoFactory` that creates `KeyInfo` objects. The returned `KeyInfoFactory` has the same mechanism type and provider as this `XMLSignatureFactory`.
    Returns:
      a `KeyInfoFactory`
    Throws:
      `NoSuchMechanismException` - if a `KeyFactory` implementation with the same mechanism type and provider is not available

  - ### unmarshalXMLSignature

    public abstract XMLSignature unmarshalXMLSignature(XMLValidateContext context) throws MarshalException
    Unmarshals a new `XMLSignature` instance from a mechanism-specific `XMLValidateContext` instance.
    Parameters:
      `context` - a mechanism-specific context from which to unmarshal the signature from
    Returns:
      the `XMLSignature`
    Throws:
      `NullPointerException` - if `context` is `null`
      `ClassCastException` - if the type of `context` is inappropriate for this factory
      `MarshalException` - if an unrecoverable exception occurs during unmarshalling

  - ### unmarshalXMLSignature

    public abstract XMLSignature unmarshalXMLSignature(XMLStructure xmlStructure) throws MarshalException
    Unmarshals a new `XMLSignature` instance from a mechanism-specific `XMLStructure` instance. This method is useful if you only want to unmarshal (and not validate) an `XMLSignature`.
    Parameters:
      `xmlStructure` - a mechanism-specific XML structure from which to unmarshal the signature from
    Returns:
      the `XMLSignature`
    Throws:
      `NullPointerException` - if `xmlStructure` is `null`
      `ClassCastException` - if the type of `xmlStructure` is inappropriate for this factory
      `MarshalException` - if an unrecoverable exception occurs during unmarshalling

  - ### isFeatureSupported

    public abstract boolean isFeatureSupported(String feature)
    Indicates whether a specified feature is supported.
    Parameters:
      `feature` - the feature name (as an absolute URI)
    Returns:
      `true` if the specified feature is supported, `false` otherwise
    Throws:
      `NullPointerException` - if `feature` is `null`

  - ### getURIDereferencer

    public abstract URIDereferencer getURIDereferencer()
    Returns a reference to the `URIDereferencer` that is used by default to dereference URIs in `Reference` objects.
    Returns:
      a reference to the default `URIDereferencer` (never `null`)