Project JXTA

net.jxta.id
Class ID

java.lang.Object
  extended bynet.jxta.id.ID
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
CodatID, ModuleClassID, ModuleSpecID, PeerGroupID, PeerID, PipeID

public abstract class ID
extends Object
implements Serializable

IDs are used to uniquely identify peers, peer groups, pipes and other types of objects manipulated by the JXTA APIs.

See Also:
IDFactory, CodatID, PeerID, PeerGroupID, PipeID, ModuleClassID, ModuleSpecID, JXTA Protocols Specification : IDs, Serialized Form

Field Summary
static ID nullID
          The null ID.
static String URIEncodingName
          This defines the URI scheme that we will be using to present JXTA IDs.
static String URNNamespace
          This defines the URN Namespace that we will be using to present JXTA IDs.
 
Constructor Summary
protected ID()
          Constructor for IDs.
 
Method Summary
 Object clone()
          Deprecated. IDs are immutable. clone() is never ever needed.
static ID create(URI fromURI)
          Creates an ID by parsing the given URI.
abstract  String getIDFormat()
          Returns a string identifier which indicates which ID format is used by this ID instance.
abstract  Object getUniqueValue()
          Returns an object containing the unique value of the ID.
abstract  URL getURL()
          Deprecated. URIs are now the prefered way of manipulating IDs
 String toString()
          Returns a string representation of the ID.
 URI toURI()
          Returns a URI representation of the ID.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

URIEncodingName

public static final String URIEncodingName
This defines the URI scheme that we will be using to present JXTA IDs. JXTA IDs are encoded for presentation into URIs (see IETF RFC 2396 Uniform Resource Identifiers (URI) : Generic Syntax ) as URNs (see IETF RFC 2141 Uniform Resource Names (URN) Syntax ).

See Also:
Constant Field Values

URNNamespace

public static final String URNNamespace
This defines the URN Namespace that we will be using to present JXTA IDs. The namespace allows URN resolvers to determine which sub-resolver to use to resolve URN references. All JXTA IDs are presented in this namespace.

See Also:
Constant Field Values

nullID

public static final ID nullID
The null ID. The NullID is often used as a placeholder in fields which are uninitialized.

This is a singleton within the scope of a VM.

Constructor Detail

ID

protected ID()
Constructor for IDs. IDs are constructed using the IDFactory or create(URI).

Method Detail

create

public static ID create(URI fromURI)
Creates an ID by parsing the given URI.

This convenience factory method works as if by invoking the IDFactory.fromURI(URI) method; any URISyntaxException thrown is caught and wrapped in a new IllegalArgumentException object, which is then thrown.

This method is provided for use in situations where it is known that the given string is a legal ID, for example for ID constants declared within in a program, and so it would be considered a programming error for the URI not to parse as such. The IDFactory, which throws URISyntaxException directly, should be used situations where a ID is being constructed from user input or from some other source that may be prone to errors.

Parameters:
fromURI - The URI to be parsed into an ID
Returns:
The new ID
Throws:
NullPointerException - If fromURI is null
IllegalArgumentException - If the given URI is not a valid ID.

clone

public final Object clone()
Deprecated. IDs are immutable. clone() is never ever needed.

Returns a "clone" of this ID. "this" IS ALWAYS RETURNED because IDs are immutable objects.

Returns:
the same object you passed in.

toString

public String toString()
Returns a string representation of the ID. This representation should be used primarily for debugging purposes. For most other situations IDs should be externalized as Java URI Objects via toURI().

The default implementation is the toString() of the ID represented as a URI.

Returns:
String containing the URI

getIDFormat

public abstract String getIDFormat()
Returns a string identifier which indicates which ID format is used by this ID instance.

Returns:
a string identifier which indicates which ID format is used by this ID instance.

getUniqueValue

public abstract Object getUniqueValue()
Returns an object containing the unique value of the ID. This object must provide implementations of toString(), equals() and hashCode() that are canonical and consistent from run-to-run given the same input values. Beyond this nothing should be assumed about the nature of this object. For some implementations the object returned may be this.

Returns:
Object which can provide canonical representations of the ID.

getURL

public abstract URL getURL()
Deprecated. URIs are now the prefered way of manipulating IDs

Returns a URL representation of the ID. The JXTA ID Factory can be used to construct ID Objects from URLs containing JXTA IDs.

Returns:
URL Object containing the URI
See Also:
IDFactory.fromURL( java.net.URL )

toURI

public URI toURI()
Returns a URI representation of the ID. URIs are the prefered way of externalizing and presenting JXTA IDs. The JXTA ID Factory can be used to construct ID Objects from URIs containing JXTA IDs.

Returns:
URI Object containing the URI
See Also:
IDFactory.fromURI( java.net.URI )

JXTA J2SE