net.jxta.membership
Class MembershipService

java.lang.Object
  |
  +--net.jxta.membership.MembershipService

All Implemented Interfaces:

Module, Service

public abstract class MembershipService

extends java.lang.Object

implements Service

The membership service allows a peer to establish an identity within a peer group. Once an identity has been a established a credential is available which allows the peer to prove that it rightfully has that identity. Identities are used by services to determine the capabilities which should be offered to peers.

When a peer group is instantiated on a peer the membership service for that peer group establishes a default temporary identity for the peer within the peergroup. This identity, by convention, only allows the peer to establish their true identity.

The sequence for establishing an indentity for a peer within a peer group is as follows:

Apply	The peer provides the membership service an initial credential which may be used by the service to determine which method of authentication is to be used to establish the identity of this peer. If the service allows authentication using the requested mechanism then an appropriate authenticator object is returned. Authenticator
Join	The completed authenticator is returned to the Membership service and the identity of this peer is adjusted based on the new credential available from the authenticator. Until the "join() is completed the identity of the peer remains as it was.
Resign	Whatever existing identities that were established for this peer are discarded and the list of current identities reverts to contain only the "nobody" identity.

There is also the question of the duration of validity of the Credential objects returned.

Since:

JXTA 1.0

Version:

$Revision: 1.3 $

Constructor Summary

MembershipService()

Method Summary

abstract Authenticator	apply(AuthenticationCredential application) Request the necessary credentials to join the group with which this service is associated.
abstract java.util.Enumeration	getAuthCredentials() Returns the current credentials for this peer.
abstract java.util.Enumeration	getCurrentCredentials() Returns the current credentials for this peer.
abstract Credential	getDefaultCredential() Returns the default credential for this peer.
Service	getInterface() service objects are not manipulated directly to protect usage of the service.
java.lang.String	getName() Returns the name of the associated service.
abstract Credential	join(Authenticator authenticated) Join the group by virtue of the completed authentication provided.
abstract Credential	makeCredential(Element element) Given a fragment of a StructuredDocument, reconstruct a Credential object from that fragment.
abstract void	resign() Resign all credentials which were previously gained through prior join() operations.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.jxta.service.Service

getImplAdvertisement

Methods inherited from interface net.jxta.platform.Module

init, startApp, stopApp

Constructor Detail

MembershipService

public MembershipService()

Method Detail

getName

public final java.lang.String getName()

Returns the name of the associated service. Each service has a unique name.

Returns:

String the name of this service.

getInterface

public Service getInterface()

service objects are not manipulated directly to protect usage of the service. A service interface is returned to access the service methods.

Specified by:

getInterface in interface Service

Returns:

service public interface of the service

apply

public abstract Authenticator apply(AuthenticationCredential application)
                             throws PeerGroupException,
                                    ProtocolNotSupportedException

Request the necessary credentials to join the group with which this service is associated.

Parameters:

application - The authenticationCredential associated with this membership application. See AuthenticationCredential for more information.

Returns:

PeerGroupCredential the desired credential

Throws:

PeerGroupException - Thrown in the event of errors. This exception spec is currently a placeholder and needs to be narrowed.

ProtocolNotSupportedException - if the authentication method requested in the application is not supported by this service.

join

public abstract Credential join(Authenticator authenticated)
                         throws PeerGroupException

Join the group by virtue of the completed authentication provided.

Parameters:

authenticated - the completed authentication.

Returns:

Credential the credential for this completed authentication.

Throws:

PeerGroupException - Thrown in the event of errors. This exception spec is currently a placeholder and needs to be narrowed.

resign

public abstract void resign()
                     throws PeerGroupException

Resign all credentials which were previously gained through prior join() operations.

Throws:

PeerGroupException - Thrown in the event of errors. This exception spec is currently a placeholder and needs to be narrowed.

getDefaultCredential

public abstract Credential getDefaultCredential()
                                         throws PeerGroupException

Returns the default credential for this peer. This is normally the "nobody" credential which is provided by default.

Throws:

PeerGroupException - Thrown in the event of errors. This exception spec is currently a placeholder and needs to be narrowed.

getCurrentCredentials

public abstract java.util.Enumeration getCurrentCredentials()
                                                     throws PeerGroupException

Returns the current credentials for this peer. The elements of the enumeration are all of types derived from "Credential". Before join() or after resign() are called, this enumeration will consist of a single element, a default credential which is usually has the identity "nobody". This credential always exists, but likely offers few, if any, privledges within this group.

Returns:

Enumeration of the Credentials currently associated with this peer for this peergroup.

Throws:

PeerGroupException - Thrown in the event of errors. This exception spec is currently a placeholder and needs to be narrowed.

getAuthCredentials

public abstract java.util.Enumeration getAuthCredentials()
                                                  throws PeerGroupException

Returns the current credentials for this peer. The elements of the enumeration are all of types derived from AuthenticationCredential

Returns:

Enumeration of the AuthenticationCredentials which were used to establish the current identities.

Throws:

PeerGroupException - Thrown in the event of errors. This exception spec is currently a placeholder and needs to be narrowed.

makeCredential

public abstract Credential makeCredential(Element element)
                                   throws PeerGroupException,
                                          java.lang.Exception

Given a fragment of a StructuredDocument, reconstruct a Credential object from that fragment.

Parameters:

element - The StructuredDocument fragment to use for building the credential.

Returns:

Credential The created credential

Throws:

PeerGroupException - Thrown in the event of errors. This exception spec is currently a placeholder and needs to be narrowed.

java.lang.Exception - Thrown in the event of errors. This exception spec is currently a placeholder and needs to be narrowed.