Project JXTA

net.jxta.id
Class IDFactory

java.lang.Object
  extended by net.jxta.util.ClassFactory
      extended by net.jxta.id.IDFactory

public final class IDFactory
extends ClassFactory

A factory class for creating new ID instances and for constructing ID instances from external representations such as strings or URIs.

When possible the factory will create IDs of the same ID Format as any base ids provided. For example, PipeIDs will be created to be the same ID Format as the PeerGroupID provided.

Some ID constructors allow specification of "seed" information. Each ID Format may use this seed information as it chooses or may require seed information of a specific form. In some cases the seed information will be used literally as provided to construct the resulting ID, but ID Formats may also choose to ignore the seed information entirely, use it as random number generator seed values, etc. Consult the implementation documentation for the ID Formats of interest to see how the seed information is used by each ID Format.

See Also:
ID, ClassFactory, JXTA Protocols Specification : IDs

Nested Class Summary
static interface IDFactory.Instantiator
          Interface for instantiators of IDs.
static interface IDFactory.URIInstantiator
          Extended instantiator which provides for construction from URIs and from scheme specific URN fragments.
 
Method Summary
static ID fromURI(URI source)
          Construct a new ID instance from a JXTA ID contained in a URI.
static ID fromURL(URL source)
          Deprecated. Use of URLs for representing JXTA IDs and this method are deprecated. Convert to using fromURI( URI ) instead.
protected  Map getAssocTable()
          Used by ClassFactory methods to get the mapping of ID types to constructors.
protected  Class getClassForKey()
          Used by ClassFactory methods to ensure that all keys used with the mapping are of the correct type.
protected  Class getClassOfInstantiators()
          Used by ClassFactory methods to ensure that all of the instance classes which register with this factory have the correct base class
static String getDefaultIDFormat()
          Returns a String containing the name of the default ID Format.
static URL jxtaURL(String uri)
          Deprecated. You should convert code which creates JXTA IDs from strings to instead use IDFactory.fromURI( new URI(String) ). This method was only provided to overcome problems with registration of URL handlers in foreign class loader environments (Servlets, Applets, etc.).
static URL jxtaURL(String protocol, String host, String file)
          Deprecated. You should convert code which creates JXTA IDs to instead use IDFactory.fromURI( new URI(...) ). This method was only provided to overcome problems with registration of URL handlers in foreign class loader environments (Servlets, Applets, etc.).
static CodatID newCodatID(PeerGroupID groupID)
          Creates a new CodatID Instance.
static CodatID newCodatID(PeerGroupID groupID, byte[] seed)
          Creates a new CodatID instance.
static CodatID newCodatID(PeerGroupID groupID, byte[] seed, InputStream in)
          Creates a new CodatID instance.
static CodatID newCodatID(PeerGroupID groupID, InputStream in)
          Creates a new CodatID instance.
static ModuleClassID newModuleClassID()
          Creates a new ModuleClassID instance.
static ModuleClassID newModuleClassID(ModuleClassID baseClass)
          Creates a new ModuleClassID instance.
static ModuleClassID newModuleClassID(String idformat)
          Creates a new ModuleClassID instance using the specified ID Format.
static ModuleSpecID newModuleSpecID(ModuleClassID baseClass)
          Creates a new ModuleSpecID instance.
static PeerGroupID newPeerGroupID()
          Creates a new PeerGroupID instance.
static PeerGroupID newPeerGroupID(byte[] seed)
          Creates a new PeerGroupID instance.
static PeerGroupID newPeerGroupID(PeerGroupID parent)
          Creates a new PeerGroupID instance with the specified parent group.
static PeerGroupID newPeerGroupID(PeerGroupID parent, byte[] seed)
          Creates a new PeerGroupID instance with the specified parent group.
static PeerGroupID newPeerGroupID(String idformat)
          Creates a new PeerGroupID instance using the specified ID Format.
static PeerGroupID newPeerGroupID(String idformat, byte[] seed)
          Creates a new PeerGroupID instance.
static PeerID newPeerID(PeerGroupID groupID)
          Creates a new PeerID instance.
static PeerID newPeerID(PeerGroupID groupID, byte[] seed)
          Creates a new PeerID instance.
static PipeID newPipeID(PeerGroupID groupID)
          Creates a new PipeID instance.
static PipeID newPipeID(PeerGroupID groupID, byte[] seed)
          Creates a new PipeID instance.
 boolean registerAssoc(String className)
          Register a class with the factory from its class name.
 
Methods inherited from class net.jxta.util.ClassFactory
getAvailableKeys, getEntrySet, getInstantiator, registerAssoc, registerFromResources, registerFromString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getAssocTable

protected Map getAssocTable()
Used by ClassFactory methods to get the mapping of ID types to constructors.

Specified by:
getAssocTable in class ClassFactory
Returns:
Hashtable the hashtable containing the mappings.

getClassForKey

protected Class getClassForKey()
Used by ClassFactory methods to ensure that all keys used with the mapping are of the correct type.

Specified by:
getClassForKey in class ClassFactory
Returns:
Class object of the key type.

getClassOfInstantiators

protected Class getClassOfInstantiators()
Used by ClassFactory methods to ensure that all of the instance classes which register with this factory have the correct base class

Specified by:
getClassOfInstantiators in class ClassFactory
Returns:
Class object of the key type.

registerAssoc

public boolean registerAssoc(String className)
Register a class with the factory from its class name. We override the standard implementation to get the id type from the class and use that as the key to register the class with the factory.

Overrides:
registerAssoc in class ClassFactory
Parameters:
className - The class name which will be regiestered.
Returns:
boolean true if the class was registered otherwise false.

getDefaultIDFormat

public static String getDefaultIDFormat()
Returns a String containing the name of the default ID Format.

Returns:
The current default ID Format.

fromURI

public static ID fromURI(URI source)
                  throws URISyntaxException
Construct a new ID instance from a JXTA ID contained in a URI.

Parameters:
source - URI which will be decoded to create a new ID instance.
Returns:
ID containing the new ID instance initialized from the URI.
Throws:
URISyntaxException - If the URI provided is not a valid, recognized JXTA URI.

fromURL

public static ID fromURL(URL source)
                  throws MalformedURLException,
                         UnknownServiceException
Deprecated. Use of URLs for representing JXTA IDs and this method are deprecated. Convert to using fromURI( URI ) instead.

Construct a new ID instance from a JXTA ID contained in a URI.

Parameters:
source - URI which will be decoded to create a new ID instance.
Returns:
ID containing the new ID instance initialized from the URI.
Throws:
UnknownServiceException - Is thrown if the URI provided is of a format unrecognized by this JXTA implementation.
MalformedURLException - Is thrown if the URI provided is not a valid, recognized JXTA URI.

newCodatID

public static CodatID newCodatID(PeerGroupID groupID)
Creates a new CodatID Instance. A new random CodatID is created for the provided Peer Group. This type of CodatID can be used as a canonical reference for dynamic content.

Parameters:
groupID - the group to which this content will belong.
Returns:
The newly created CodatID.
See Also:
Codat

newCodatID

public static CodatID newCodatID(PeerGroupID groupID,
                                 byte[] seed)
Creates a new CodatID instance. A new CodatID is created for the provided Peer Group. This type of CodatID can be used as a canonical reference for dynamic content.

This varient of CodatID allows you to create "Well-known" codats within the context of diverse groups. This can be useful for common services that need to do discovery without advertisements or for network organization services. Because of the potential for ID collisions and the difficulties with maintaining common service interfaces this varient of CodatID should be used with great caution and pre-planning.

Parameters:
groupID - the group to which this content will belong.
seed - The seed information which will be used in creating the codatID. The seed information should be at least four bytes in length, though longer values are better.
Returns:
The newly created CodatID.
See Also:
Codat

newCodatID

public static CodatID newCodatID(PeerGroupID groupID,
                                 InputStream in)
                          throws IOException
Creates a new CodatID instance. A new random CodatID is created for the provided Peer Group and contains a hash value for the Codat data. This type of Codat ID is most appropriate for static content. By including a hash value this form of Codat ID provides greater assurance of the canonical property of IDs. It also allows the document content returned when this ID is used to be verified to ensure it has not been altered.

Parameters:
groupID - The group to which this ID will belong.
in - The InputStream from which the content hash is calculated. The stream is read until EOF and then closed.
Returns:
The newly created CodatID.
Throws:
IOException - I/O Error reading document
See Also:
Codat

newCodatID

public static CodatID newCodatID(PeerGroupID groupID,
                                 byte[] seed,
                                 InputStream in)
                          throws IOException
Creates a new CodatID instance. A new CodatID is created for the provided Peer Group and contains a hash value for the Codat data. By including a hash value this form of Codat ID provides greater assurance of the canonical property of IDs. It also allows the document content returned when this ID is used to be verified to ensure it has not been altered. This type of Codat ID is most appropriate for static content.

This varient of CodatID allows you to create "Well-known" codats within the context of diverse groups. This can be useful for common services that need to do discovery without advertisements or for network organization services. Because of the potential for ID collisions and the difficulties with maintaining common service interfaces this varient of CodatID should be used with great caution and pre-planning.

Parameters:
groupID - The group to which this ID will belong.
seed - The seed information which will be used in creating the codat ID. The seed information should be at least four bytes in length, though longer values are better.
in - The InputStream from which the content hash is calculated. The stream is read until EOF and then closed.
Returns:
The newly created CodatID.
Throws:
IOException - I/O Error reading document
See Also:
Codat

newPeerID

public static PeerID newPeerID(PeerGroupID groupID)
Creates a new PeerID instance. A new random peer id will be generated. The PeerID will be a member of the provided group.

Parameters:
groupID - the group to which this PeerID will belong.
Returns:
The newly created PeerID.
See Also:
PeerGroup

newPeerID

public static PeerID newPeerID(PeerGroupID groupID,
                               byte[] seed)
Creates a new PeerID instance. A new PeerID will be generated. The PeerID will be a member of the provided group.

Parameters:
groupID - the group to which this PeerID will belong.
seed - The seed information which will be used in creating the PeerID. The seed information should be at least four bytes in length, though longer values are better.
Returns:
The newly created PeerID.
See Also:
PeerGroup

newPeerGroupID

public static PeerGroupID newPeerGroupID()
Creates a new PeerGroupID instance. A new random peer group id will be generated. The PeerGroupID will be created using the default ID Format.

Returns:
The newly created PeerGroupID.
See Also:
PeerGroup

newPeerGroupID

public static PeerGroupID newPeerGroupID(String idformat)
Creates a new PeerGroupID instance using the specified ID Format. A new random peer group id will be generated.

Returns:
The newly created PeerGroupID.
See Also:
PeerGroup

newPeerGroupID

public static PeerGroupID newPeerGroupID(byte[] seed)
Creates a new PeerGroupID instance. A new PeerGroupID will be generated using the provided seed information. The PeerGroupID will be created using the default ID Format.

This method allows you to create "Well-known" PeerGroupIDs. This is similar to how the JXTA "World Peer Group" and "Net Peer Group". "Well-known" IDs can be useful for common services that need to do discovery without advertisements or for network organization services. Because of the potential for ID collisions and the difficulties with maintaining common service interfaces this varient of PeerGroupID should be used with great caution and pre-planning.

Parameters:
seed - The seed information which will be used in creating the PeerGroupID. The seed information should be at least four bytes in length, though longer values are better.
Returns:
The newly created PeerGroupID.
See Also:
PeerGroup

newPeerGroupID

public static PeerGroupID newPeerGroupID(String idformat,
                                         byte[] seed)
Creates a new PeerGroupID instance. A new PeerGroupID will be generated using the provided seed information. The PeerGroupID will be created using the default ID Format.

This method allows you to create "Well-known" PeerGroupIDs. This is similar to how the JXTA "World Peer Group" and "Net Peer Group". "Well-known" IDs can be useful for common services that need to do discovery without advertisements or for network organization services. Because of the potential for ID collisions and the difficulties with maintaining common service interfaces this varient of PeerGroupID should be used with great caution and pre-planning.

Parameters:
seed - The seed information which will be used in creating the PeerGroupID. The seed information should be at least four bytes in length, though longer values are better.
Returns:
The newly created PeerGroupID.
See Also:
PeerGroup

newPeerGroupID

public static PeerGroupID newPeerGroupID(PeerGroupID parent)
Creates a new PeerGroupID instance with the specified parent group. A new random peer group id will be generated.

Parameters:
parent - The group which will be the parent of this group.
Returns:
The newly created PeerGroupID.
See Also:
PeerGroup

newPeerGroupID

public static PeerGroupID newPeerGroupID(PeerGroupID parent,
                                         byte[] seed)
Creates a new PeerGroupID instance with the specified parent group. A new PeerGroupID will be generated using the provided seed information.

This method allows you to create "Well-known" PeerGroupIDs. This is similar to how the JXTA "World Peer Group" and "Net Peer Group". "Well-known" IDs can be useful for common services that need to do discovery without advertisements or for network organization services. Because of the potential for ID collisions and the difficulties with maintaining common service interfaces this varient of PeerGroupID should be used with great caution and pre-planning.

Parameters:
parent - The group which will be the parent of this group.
seed - The seed information which will be used in creating the PeerGroupID. The seed information should be at least four bytes in length, though longer values are better.
Returns:
The newly created PeerGroupID.
See Also:
PeerGroup

newPipeID

public static PipeID newPipeID(PeerGroupID groupID)
Creates a new PipeID instance. A new random PipeID will be generated.

Parameters:
groupID - The group to which this Pipe ID will belong.
Returns:
The newly created PipeID.

newPipeID

public static PipeID newPipeID(PeerGroupID groupID,
                               byte[] seed)
Creates a new PipeID instance. A new pipe id will be generated with the provided seed information. The Pipe ID will be a member of the provided group.

This varient of PipeID allows you to create "Well-known" pipes within the context of diverse groups. This can be useful for common services that need to do discovery without advertisements or for network organization services. Because of the potential for ID collisions and the difficulties with maintaining common service interfaces this varient of PipeID should be used with great caution and pre-planning.

Parameters:
groupID - the group to which this Pipe ID will belong.
seed - The seed information which will be used in creating the pipeID. The seed information should be at least four bytes in length, though longer values are better.
Returns:
the newly created PipeID.

newModuleClassID

public static ModuleClassID newModuleClassID()
Creates a new ModuleClassID instance. A new random ModuleClassID will be generated with a zero value role identifier. This form of ModuleClassID is appropriate for cases where the module does not need to be distinguished from other instances of the same Module. The ModuleClassID will be created using the default ID Format.

Returns:
The newly created ModuleClassID.
See Also:
Module

newModuleClassID

public static ModuleClassID newModuleClassID(String idformat)
Creates a new ModuleClassID instance using the specified ID Format. A new random ModuleClassID will be generated with a zero value role identifier. This form of ModuleClassID is appropriate for cases where the module does not need to be distinguished from other instances of the same Module.

Returns:
The newly created ModuleClassID.
See Also:
Module

newModuleClassID

public static ModuleClassID newModuleClassID(ModuleClassID baseClass)
Creates a new ModuleClassID instance. A new random ModuleClassID will be generated with a a random value role identifier and a base class of the provided ModuleClassID. This form of ModuleClassID is appropriate for cases where it is necessary to distinguish instances of the same service interface.

Parameters:
baseClass - The ModuleClassID which will be used as a base class for this new role value instance.
Returns:
The newly created ModuleClassID.
See Also:
Module

newModuleSpecID

public static ModuleSpecID newModuleSpecID(ModuleClassID baseClass)
Creates a new ModuleSpecID instance. A new random ModuleSpecID will be generated.

Parameters:
baseClass - The ModuleClassID which will be used as a base class for this new ModuleSpecID.
Returns:
The newly created ModuleSpecID.
See Also:
Module

jxtaURL

public static URL jxtaURL(String protocol,
                          String host,
                          String file)
                   throws MalformedURLException
Deprecated. You should convert code which creates JXTA IDs to instead use IDFactory.fromURI( new URI(...) ). This method was only provided to overcome problems with registration of URL handlers in foreign class loader environments (Servlets, Applets, etc.).

This method should be used instead of using new java.net.URL( ) to create URLs for use with IDFactory. URL construction can cause classes to be loaded using the system classLoader (JXTA IDs require the class sun.net.www.protocol.urn.Handler for Sun JVMs). This class loading will fail in many enviroments such as web-servers, servlet containers, application servers, or java web start where a user class loader is used to load all JXTA resources.

Parameters:
protocol - The protocol for this URL
host - The host for this URL
file - The file for this URL
Returns:
a newly created URL for the resource specified.
Throws:
MalformedURLException - if an unknown protocol is specified.

jxtaURL

public static URL jxtaURL(String uri)
                   throws MalformedURLException
Deprecated. You should convert code which creates JXTA IDs from strings to instead use IDFactory.fromURI( new URI(String) ). This method was only provided to overcome problems with registration of URL handlers in foreign class loader environments (Servlets, Applets, etc.).

This method should be used instead of using new java.net.URL( ) to create URLs for use with IDFactory. URL construction can cause classes to be loaded using the system classLoader (JXTA IDs require the class sun.net.www.protocol.urn.Handler for Sun JVMs). This class loading will fail in many enviroments such as web-servers, servlet containers, application servers, or java web start where a user class loader is used to load all JXTA resources.

Parameters:
uri - the String to parse as a URL.
Returns:
a newly created URL for the resource specified.
Throws:
MalformedURLException - if an unknown protocol is specified.

JXTA J2SE