JXTA

net.jxta.platform
Class ModuleSpecID

java.lang.Object
  extended by net.jxta.id.ID
      extended by net.jxta.platform.ModuleSpecID
All Implemented Interfaces:
Serializable

public abstract class ModuleSpecID
extends ID

A ModuleSpecID uniquely identifies a particular network behaviour (wire protocol and choregraphy) that may be embodied by a Jxta Module. There may be any number of implementations of a given SpecID. All such implementations are assumed to be network compatible.

The Specification that corresponds to a given ModuleSpecID may be published in a ModuleSpecAdvertisement. This advertisement is uniquely identified by the ModuleSpecID that it describes.

The various implementations of a given SpecID may be published in ModuleImplAdvertisements. These advertisements are identified by the ModuleSpecID that they implement and a compatibility statement. ModuleImplAdvertisements baring the same SpecID and compatibility statement are theorethicaly interchangeable. However they may be subsequently discriminated by a Description element.

A ModuleSpecID embeds a ModuleClassID which uniquely identifies a base Module class. A base module class defines a local behaviour and one API per compatible JXTA implementation.

A ModuleSpecID therefore uniquely identifies an abstract module, of which an implementation compatible with the local JXTA implementation may be located and instantiated.

In the standard PeerGroup implementation of the java reference implementation the various services are specified as a list of ModuleSpecID, for each of which the group locates and loads an implementation as part of the group's initialization.

See Also:
PeerGroup, Module, ModuleClassID, ModuleSpecAdvertisement, ModuleImplAdvertisement, ID, Advertisement, Serialized Form

Field Summary
 
Fields inherited from class net.jxta.id.ID
nullID, URIEncodingName, URNNamespace
 
Constructor Summary
ModuleSpecID()
           
 
Method Summary
static ModuleSpecID create(URI fromURI)
          Creates an ID by parsing the given URI.
abstract  ModuleClassID getBaseClass()
          Return a ModuleClassID of the same base class but with the role portion set to zero. aka "the base class".
 ModuleSpecID intern()
          Returns a canonical representation for the ID object.
abstract  boolean isOfSameBaseClass(ModuleClassID id)
          Returns true if this ModuleSpecID is of the same base class than the given class.
abstract  boolean isOfSameBaseClass(ModuleSpecID id)
          Returns true if this ModuleSpecID is of the same base class than the the given ModuleSpecID.
 
Methods inherited from class net.jxta.id.ID
getIDFormat, getUniqueValue, getURL, toString, toURI
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ModuleSpecID

public ModuleSpecID()
Method Detail

create

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

intern

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

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

isOfSameBaseClass

public abstract boolean isOfSameBaseClass(ModuleClassID id)
Returns true if this ModuleSpecID is of the same base class than the given class. Note: This method is NOT named "isOfClass" because a ModuleClassID may have two portions; one that denotes a class proper, and an optional second one that denotes a "Role". For convenience, we refer the class stripped of its role portion as "the base class" although this is not a totally accurate term. A ModuleSpecID, is of a base class but is not related to any kind of role. So using "isOfClass" could be misleading. Base classes are represented by a class with the role ID set to zero, which happens to be a valid class. This routine may be used for comparison with such a class, of course.

Parameters:
id - Module class id to compare with
Returns:
boolean true if equals

isOfSameBaseClass

public abstract boolean isOfSameBaseClass(ModuleSpecID id)
Returns true if this ModuleSpecID is of the same base class than the the given ModuleSpecID.

Parameters:
id - Module spec id to compare with
Returns:
boolean true if equals

getBaseClass

public abstract ModuleClassID getBaseClass()
Return a ModuleClassID of the same base class but with the role portion set to zero. aka "the base class".

Returns:
ModuleClassID the base class.

JXSE