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

# 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

## 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 java.lang.Object

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

## 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
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
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
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`)