JXTA

net.jxta.id
Class ID

java.lang.Object
  extended by net.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
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.
 URL getURL()
          Deprecated. URIs are now the preferred way of manipulating IDs
protected  ID intern()
          Returns a canonical representation for the ID object.
 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
clone, 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.

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.

Overrides:
toString in class Object
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

@Deprecated
public URL getURL()
Deprecated. URIs are now the preferred 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 )

intern

protected ID intern()
Returns a canonical representation for the ID object.

A pool of IDs, is maintained privately by the class.

When the intern() method is invoked, if the pool already contains a ID equal to this ID object as determined by the equals(Object) method, then the ID from the pool is returned. Otherwise, this ID object is added to the pool and a reference to this ID object is returned.

It follows that for any two ID s and t, s.intern() == t.intern() is true if and only if s.equals(t) is true.

Returns:
a ID that has the same value as this type, but is guaranteed to be from a pool of unique types.

toURI

public URI toURI()
Returns a URI representation of the ID. URIs are the preferred 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 )

JXSE