JXTA

net.jxta.impl.id.binaryID
Class Instantiator

java.lang.Object
  extended by net.jxta.impl.id.binaryID.Instantiator
All Implemented Interfaces:
IDFactory.Instantiator, IDFactory.URIInstantiator

public final class Instantiator
extends Object
implements IDFactory.URIInstantiator

ID Factory for the binary ID type. All identifiers in this type are prefixed by "binaryid".

Author:
Daniel Brookshier turbogeek@cluck.com

Field Summary
(package private) static String BinaryIDEncoded
          Our ID Format
 
Constructor Summary
Instantiator()
           
 
Method Summary
 ID fromURI(URI source)
          Construct a new ID instance from a JXTA ID contained in a URI.
 ID fromURL(URL source)
          Construct a new ID instance from a JXTA ID contained in a URL.
 ID fromURNNamespaceSpecificPart(String encoded)
          Construct a new ID instance from the scheme specific portion of a jxta URN.
 String getSupportedIDFormat()
          Returns the ID Format value associated with this ID Format
 CodatID newCodatID(PeerGroupID groupID)
          Creates a new CodatID Instance.
 CodatID newCodatID(PeerGroupID groupID, byte[] seed)
          Creates a new CodatID instance.
 CodatID newCodatID(PeerGroupID groupID, byte[] idValue, InputStream in)
          Creates a new CodatID instance.
 CodatID newCodatID(PeerGroupID groupID, InputStream in)
          Creates a new CodatID instance.
 ModuleClassID newModuleClassID()
          Creates a new ModuleClassID instance.
 ModuleClassID newModuleClassID(ModuleClassID classID)
          Creates a new ModuleClassID instance.
 ModuleSpecID newModuleSpecID(ModuleClassID classID)
          Creates a new ModuleSpecID instance.
 PeerGroupID newPeerGroupID()
          Creates a new PeerGroupID instance.
 PeerGroupID newPeerGroupID(byte[] idValue)
          Creates a new PeerGroupID instance.
 PeerGroupID newPeerGroupID(PeerGroupID parent)
          Creates a new PeerGroupID instance with the specified parent group.
 PeerGroupID newPeerGroupID(PeerGroupID parent, byte[] idValue)
          Creates a new PeerGroupID instance with the specified parent group.
 PeerID newPeerID(PeerGroupID groupID)
          Creates a new PeerID instance.
 PeerID newPeerID(PeerGroupID groupID, byte[] idValue)
          Creates a new PeerID instance.
 PipeID newPipeID(PeerGroupID groupID)
          Creates a new PipeID instance.
 PipeID newPipeID(PeerGroupID groupID, byte[] idValue)
          Creates a new PipeID instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BinaryIDEncoded

static final String BinaryIDEncoded
Our ID Format

See Also:
Constant Field Values
Constructor Detail

Instantiator

public Instantiator()
Method Detail

getSupportedIDFormat

public String getSupportedIDFormat()
Returns the ID Format value associated with this ID Format

Specified by:
getSupportedIDFormat in interface IDFactory.Instantiator
Returns:
String containing the ID format value for this format.

fromURL

public ID fromURL(URL source)
           throws MalformedURLException,
                  UnknownServiceException
Construct a new ID instance from a JXTA ID contained in a URL.

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

fromURI

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

Specified by:
fromURI in interface IDFactory.Instantiator
Parameters:
source - URI which will be decoded to create a new ID instance.
Returns:
ID containing the new ID instance initialized from the source.
Throws:
URISyntaxException - if the URI provided is not a valid, recognized JXTA URI.

fromURNNamespaceSpecificPart

public ID fromURNNamespaceSpecificPart(String encoded)
                                throws URISyntaxException
Construct a new ID instance from the scheme specific portion of a jxta URN.

Specified by:
fromURNNamespaceSpecificPart in interface IDFactory.Instantiator
Parameters:
encoded - the scheme specific portion of a jxta URN.
Returns:
ID containing the new ID instance initialized from the source.
Throws:
URISyntaxException - if the URI provided is not a valid, recognized JXTA URI.

newCodatID

public 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.

Specified by:
newCodatID in interface IDFactory.Instantiator
Parameters:
groupID - The group to which this content will belong.
Returns:
The newly created CodatID.
Throws:
UnsupportedOperationException - This form is not supported. Use CODAT from UUID package instead.
See Also:
Codat

newCodatID

public 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 variant 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 variant of CodatID should be used with great caution and pre-planning.

Specified by:
newCodatID in interface IDFactory.Instantiator
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.
Throws:
UnsupportedOperationException - This form is not supported. Use CODAT from UUID package instead.
See Also:
Codat

newCodatID

public 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.

Specified by:
newCodatID in interface IDFactory.Instantiator
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:
UnsupportedOperationException - This form is not supported. Use CODAT from UUID package instead.
IOException - I/O Error reading document
See Also:
Codat

newCodatID

public CodatID newCodatID(PeerGroupID groupID,
                          byte[] idValue,
                          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 variant 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 variant of CodatID should be used with great caution and pre-planning.

Specified by:
newCodatID in interface IDFactory.Instantiator
Parameters:
groupID - The group to which this ID will belong.
idValue - 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:
UnsupportedOperationException - This form is not supported. Use CODAT from UUID package instead.
IOException - I/O Error reading document
See Also:
Codat

newPeerID

public 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.

Specified by:
newPeerID in interface IDFactory.Instantiator
Parameters:
groupID - the group to which this PeerID will belong.
Returns:
The newly created PeerID.
See Also:
PeerGroup

newPeerID

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

Specified by:
newPeerID in interface IDFactory.Instantiator
Parameters:
groupID - the group to which this PeerID will belong.
idValue - 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 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.

Specified by:
newPeerGroupID in interface IDFactory.Instantiator
Returns:
The newly created PeerGroupID.
See Also:
PeerGroup

newPeerGroupID

public PeerGroupID newPeerGroupID(byte[] idValue)
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 variant of PeerGroupID should be used with great caution and pre-planning.

Specified by:
newPeerGroupID in interface IDFactory.Instantiator
Parameters:
idValue - 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 PeerGroupID newPeerGroupID(PeerGroupID parent)
Creates a new PeerGroupID instance with the specified parent group. A new random peer group id will be generated.

Specified by:
newPeerGroupID in interface IDFactory.Instantiator
Parameters:
parent - The group which will be the parent of this group.
Returns:
The newly created PeerGroupID.
See Also:
PeerGroup

newPeerGroupID

public PeerGroupID newPeerGroupID(PeerGroupID parent,
                                  byte[] idValue)
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 variant of PeerGroupID should be used with great caution and pre-planning.

Specified by:
newPeerGroupID in interface IDFactory.Instantiator
Parameters:
parent - The group which will be the parent of this group.
idValue - 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 PipeID newPipeID(PeerGroupID groupID)
Creates a new PipeID instance. A new random PipeID will be generated.

Specified by:
newPipeID in interface IDFactory.Instantiator
Parameters:
groupID - The group to which this Pipe ID will belong.
Returns:
The newly created PipeID.

newPipeID

public PipeID newPipeID(PeerGroupID groupID,
                        byte[] idValue)
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 variant 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 variant of PipeID should be used with great caution and pre-planning.

Specified by:
newPipeID in interface IDFactory.Instantiator
Parameters:
groupID - the group to which this Pipe ID will belong.
idValue - 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 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.

Specified by:
newModuleClassID in interface IDFactory.Instantiator
Returns:
The newly created ModuleClassID.
Throws:
UnsupportedOperationException - This form is not supported because a binary ID is meant to be created with a random ID.
See Also:
Module

newModuleClassID

public ModuleClassID newModuleClassID(ModuleClassID classID)
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.

Specified by:
newModuleClassID in interface IDFactory.Instantiator
Parameters:
classID - The ModuleClassID which will be used as a base class for this new role value instance.
Returns:
The newly created ModuleClassID.
Throws:
UnsupportedOperationException - This form is not supported because a binary ID is meant to be created with a random ID.
See Also:
Module

newModuleSpecID

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

Specified by:
newModuleSpecID in interface IDFactory.Instantiator
Parameters:
classID - The ModuleClassID which will be used as a base class for this new ModuleSpecID.
Returns:
The newly created ModuleSpecID.
Throws:
UnsupportedOperationException - This form is not supported because a binary ID is meant to be created with a random ID. Use UUID instead.
See Also:
Module

JXSE