This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.


javax.xml.crypto.dsig.keyinfo
class KeyInfoFactory

java.lang.Object extended by javax.xml.crypto.dsig.keyinfo.KeyInfoFactory

Most common way to construct:

KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");

Based on 131 examples


public abstract class KeyInfoFactory
extends Object

A factory for creating {@link KeyInfo} objects from scratch or for unmarshalling a KeyInfo object from a corresponding XML representation.

Each instance of KeyInfoFactory supports a specific XML mechanism type. To create a KeyInfoFactory, call one of the static {@link #getInstance getInstance} methods, passing in the XML mechanism type desired, for example:

KeyInfoFactory factory = KeyInfoFactory.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.

KeyInfoFactory 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("KeyInfoFactory.DOM", "org.example.DOMKeyInfoFactory");
 

Also, the XMLStructures that are created by this factory may contain state specific to the KeyInfo and are not intended to be reusable.

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

Note that a caller must use the same KeyInfoFactory instance to create the XMLStructures of a particular KeyInfo object. The behavior is undefined if XMLStructures from different providers or different mechanism types are used together.

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


Constructor Summary
protected

          Default constructor, for invocation by subclasses.
 
Method Summary
static KeyInfoFactory

          Returns a KeyInfoFactory that supports the default XML processing mechanism and representation type ("DOM").
static KeyInfoFactory
getInstance(String mechanismType)

          Returns a KeyInfoFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").
static KeyInfoFactory
getInstance(String mechanismType, Provider provider)

          Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
static KeyInfoFactory
getInstance(String mechanismType, String provider)

          Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
 String

          Returns the type of the XML processing mechanism and representation supported by this KeyInfoFactory (ex: "DOM")
 Provider

          Returns the provider of this KeyInfoFactory.
abstract URIDereferencer

          Returns a reference to the URIDereferencer that is used by default to dereference URIs in javax.xml.crypto.dsig.keyinfo.RetrievalMethod objects.
abstract boolean

          Indicates whether a specified feature is supported.
abstract KeyInfo
newKeyInfo(List content)

          Creates a KeyInfo containing the specified list of key information types.
abstract KeyInfo
newKeyInfo(List content, String id)

          Creates a KeyInfo containing the specified list of key information types and optional id.
abstract KeyName

          Creates a KeyName from the specified name.
abstract KeyValue

          Creates a KeyValue from the specified public key.
abstract PGPData
newPGPData(byte[] keyId)

          Creates a PGPData from the specified PGP public key identifier.
abstract PGPData
newPGPData(byte[] keyId, byte[] keyPacket, List other)

          Creates a PGPData from the specified PGP public key identifier, and optional key material packet and list of external elements.
abstract PGPData
newPGPData(byte[] keyPacket, List other)

          Creates a PGPData from the specified PGP key material packet and optional list of external elements.
abstract RetrievalMethod

          Creates a RetrievalMethod from the specified URI.
abstract RetrievalMethod
newRetrievalMethod(String uri, String type, List transforms)

          Creates a RetrievalMethod from the specified parameters.
abstract X509Data
newX509Data(List content)

          Creates a X509Data containing the specified list of X.509 content.
abstract X509IssuerSerial
newX509IssuerSerial(String issuerName, BigInteger serialNumber)

          Creates an X509IssuerSerial from the specified X.500 issuer distinguished name and serial number.
abstract KeyInfo

          Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: javax.xml.crypto.dom.DOMStructure) instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

KeyInfoFactory

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

Method Detail

getInstance

public static KeyInfoFactory getInstance()
Returns a KeyInfoFactory that supports the default XML processing mechanism and representation type ("DOM").

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

Note that the list of registered providers may be retrieved via the {@link Security#getProviders() Security.getProviders()} method.

Returns:
a new KeyInfoFactory

getInstance

public static KeyInfoFactory getInstance(String mechanismType)
Returns a KeyInfoFactory 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 a KeyInfoFactory implementation of the desired mechanism type. It traverses the list of registered security Providers, starting with the most preferred Provider. A new KeyInfoFactory object from the first Provider that supports the specified mechanism is returned.

Note that the list of registered providers may be retrieved via the {@link Security#getProviders() Security.getProviders()} method.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.
Returns:
a new KeyInfoFactory

getInstance

public static KeyInfoFactory getInstance(String mechanismType,
                                         Provider provider)
Returns a KeyInfoFactory 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 Service Providers section of the API overview for a list of standard mechanism types.
provider - the Provider object
Returns:
a new KeyInfoFactory

getInstance

public static KeyInfoFactory getInstance(String mechanismType,
                                         String provider)
                                  throws NoSuchProviderException
Returns a KeyInfoFactory 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 {@link Security#getProviders() Security.getProviders()} method.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.
provider - the string name of the provider
Returns:
a new KeyInfoFactory
Throws:
NoSuchProviderException - if the specified provider is not registered in the security provider list

getMechanismType

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

Returns:
the XML processing mechanism type supported by this KeyInfoFactory

getProvider

public final Provider getProvider()
Returns the provider of this KeyInfoFactory.

Returns:
the provider of this KeyInfoFactory

getURIDereferencer

public abstract URIDereferencer getURIDereferencer()
Returns a reference to the URIDereferencer that is used by default to dereference URIs in {@link RetrievalMethod} objects.

Returns:
a reference to the default URIDereferencer

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

newKeyInfo

public abstract KeyInfo newKeyInfo(List content)
Creates a KeyInfo containing the specified list of key information types.

Parameters:
content - a list of one or more {@link XMLStructure}s representing key information types. The list is defensively copied to protect against subsequent modification.
Returns:
a KeyInfo

newKeyInfo

public abstract KeyInfo newKeyInfo(List content,
                                   String id)
Creates a KeyInfo containing the specified list of key information types and optional id. The id parameter represents the value of an XML ID attribute and is useful for referencing the KeyInfo from other XML structures.

Parameters:
content - a list of one or more {@link XMLStructure}s representing key information types. The list is defensively copied to protect against subsequent modification.
id - the value of an XML ID (may be null)
Returns:
a KeyInfo

newKeyName

public abstract KeyName newKeyName(String name)
Creates a KeyName from the specified name.

Parameters:
name - the name that identifies the key
Returns:
a KeyName

newKeyValue

public abstract KeyValue newKeyValue(PublicKey key)
                              throws KeyException
Creates a KeyValue from the specified public key.

Parameters:
key - the public key
Returns:
a KeyValue
Throws:
KeyException - if the key's algorithm is not recognized or supported by this KeyInfoFactory

newPGPData

public abstract PGPData newPGPData(byte[] keyId)
Creates a PGPData from the specified PGP public key identifier.

Parameters:
keyId - a PGP public key identifier as defined in RFC 2440, section 11.2. The array is cloned to protect against subsequent modification.
Returns:
a PGPData

newPGPData

public abstract PGPData newPGPData(byte[] keyId,
                                   byte[] keyPacket,
                                   List other)
Creates a PGPData from the specified PGP public key identifier, and optional key material packet and list of external elements.

Parameters:
keyId - a PGP public key identifier as defined in RFC 2440, section 11.2. The array is cloned to protect against subsequent modification.
keyPacket - a PGP key material packet as defined in RFC 2440, section 5.5. The array is cloned to protect against subsequent modification. May be null.
other - a list of {@link XMLStructure}s representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May be null or empty.
Returns:
a PGPData

newPGPData

public abstract PGPData newPGPData(byte[] keyPacket,
                                   List other)
Creates a PGPData from the specified PGP key material packet and optional list of external elements.

Parameters:
keyPacket - a PGP key material packet as defined in RFC 2440, section 5.5. The array is cloned to protect against subsequent modification.
other - a list of {@link XMLStructure}s representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May be null or empty.
Returns:
a PGPData

newRetrievalMethod

public abstract RetrievalMethod newRetrievalMethod(String uri)
Creates a RetrievalMethod from the specified URI.

Parameters:
uri - the URI that identifies the KeyInfo information to be retrieved
Returns:
a RetrievalMethod

newRetrievalMethod

public abstract RetrievalMethod newRetrievalMethod(String uri,
                                                   String type,
                                                   List transforms)
Creates a RetrievalMethod from the specified parameters.

Parameters:
uri - the URI that identifies the KeyInfo information to be retrieved
type - a URI that identifies the type of KeyInfo information to be retrieved (may be null)
transforms - a list of {@link Transform}s. The list is defensively copied to protect against subsequent modification. May be null or empty.
Returns:
a RetrievalMethod

newX509Data

public abstract X509Data newX509Data(List content)
Creates a X509Data containing the specified list of X.509 content.

Parameters:
content - a list of one or more X.509 content types. Valid types are {@link String} (subject names), byte[] (subject key ids), {@link java.security.cert.X509Certificate}, {@link X509CRL}, or {@link XMLStructure} ({@link X509IssuerSerial} objects or elements from an external namespace). Subject names are distinguished names in RFC 2253 String format. Implementations MUST support the attribute type keywords defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC and UID). Implementations MAY support additional keywords. The list is defensively copied to protect against subsequent modification.
Returns:
a X509Data

newX509IssuerSerial

public abstract X509IssuerSerial newX509IssuerSerial(String issuerName,
                                                     BigInteger serialNumber)
Creates an X509IssuerSerial from the specified X.500 issuer distinguished name and serial number.

Parameters:
issuerName - the issuer's distinguished name in RFC 2253 String format. Implementations MUST support the attribute type keywords defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC and UID). Implementations MAY support additional keywords.
serialNumber - the serial number
Returns:
an X509IssuerSerial

unmarshalKeyInfo

public abstract KeyInfo unmarshalKeyInfo(XMLStructure xmlStructure)
                                  throws MarshalException
Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: {@link DOMStructure}) instance.

Parameters:
xmlStructure - a mechanism-specific XML structure from which to unmarshal the keyinfo from
Returns:
the KeyInfo
Throws:
MarshalException - if an unrecoverable exception occurs during unmarshalling


This documentation differs from the official API. Jadeite adds extra features to the API including: variable font sizes, constructions examples, placeholders for classes and methods, and auto-generated “See Also” links. Additionally it is missing some items found in standard Javadoc documentation, including: generics type information, “Deprecated” tags and comments, “See Also” links, along with other minor differences. Please send any questions or feedback to bam@cs.cmu.edu.
This page displays the Jadeite version of the documention, which is derived from the offical documentation that contains this copyright notice:
Copyright 2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.
The official Sun™ documentation can be found here at http://java.sun.com/javase/6/docs/api/.