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 XMLStructures of a particular XMLSignature that is to be generated. The behavior is undefined if XMLStructures from different providers or different mechanism types are used together.

Also, the XMLStructures 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