XMLSignature object from a corresponding XML representation. Each instance of XMLSignatureFactory supports a specific XML mechanism type. To create an XMLSignatureFactory, call one of the static {@link #getInstance 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 section of the API overview. See the Service Providers section of the API overview for a list of standard mechanism types.
XMLSignatureFactory implementations are registered and loaded using the {@link java.security.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.
Once the XMLSignatureFactory has been created, objects can be instantiated by calling the appropriate method. For example, a {@link Reference} instance may be created by invoking one of the{@link #newReference newReference} methods.
Alternatively, an XMLSignature may be created from an existing XML representation by invoking the {@link #unmarshalXMLSignature unmarshalXMLSignature} method and passing it a mechanism-specific {@link 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 {@link DOMValidateContext} objects.XMLSignature created by the factory can also be marshalled to an XML representation and signed, by invoking the {@link XMLSignature#sign sign} method of the {@link XMLSignature} object and passing it a mechanism-specific {@link XMLSignContext} object containing the signing key and marshalling parameters (see {@link 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.
@author Sean Mullan
@author JSR 105 Expert Group
| |