- Protocol and API
- JXTA Goals
- JXTA Peer and Java
- Overview of the JXTA Protocols JAVA API
- Summary of Java API for JXTA Protocols
- Where JXTA Applications Begin
- The Peer
- Starting JXTA
- Peer Discovery Protocol API
- Peer Resolver Protocol API
- Peer Information Protocol
- Peer Membership Protocol
- Pipe Binding Protocol API
- Peer Endpoint Protocol
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
Peer Membership Protocol
The peer membership protocol is a mechanism for joining peer groups. The protocol should not be confused with group creation and management except that when you create a group, you specify a specific implementation of this protocol.
What the membership protocol does is impose and verify specific requirements for a peer to join a group. In other words, the protocol makes sure you give the right answers to questions that identifies you as a valid group candidate before you are allowed to join a group. Alternatively, the implementation could look up other information or even ask other peers to vote. The possibilities are endless, and the protocol works as a framework to begin the process and allow the user to join once the requirements are met.
After you have successfully joined a group, you are issued a credential. The credential is an XML document that is used as a token of proof that you are a member of the group. The membership protocol does not keep track of users that have joined. In a peer environment, it is impractical to use a server for validating membership. The credential serves as a way to allow peers to recognize each other as valid members of the same peer group (see Chapter 6, "Working with Groups," for a complete example of peer membership).
Membership Service
The MembershipService class is an abstract class that defines generic methods used for a concrete membership service class. Figure 3.13 shows the UML for this abstract class. This class is described in detail in Chapter 6 but the following is a short description of the methods:
){kind=link}
getName—Returns the name of the service. The name is often used to match the membership service with its authenticator.
getInterface—Returns this object as a service.
apply—Request the necessary Authenticator object to join the group based on a given policy. An AuthenticationCredential is provided to help select what version of Authenticator should be used and/or to initialize an Authenticator object. Returns an Authenticator object associated with the join. The Authenticator object has setter methods that must be properly set so that the authenticator returns a valid state to allow the peer into the group.
join—Join the group. A valid Authenticator object from the apply method is provided. The result is a Credential object that can be used when needed to prove the peer is valid.
resign—Method called to resign a peer from the group.
getCurrentCredentials—Returns an enumeration of current credentials that identify the peer.
getAuthCredentials—Returns an enumeration of the current AuthenticationCredential objects.
makeCredential—Helper method used to create a credential from an XML element. This can be used to recreate a credential that was stored as XML.
Figure 3.13 UML for MembershipService interface.
AuthenticationCredential
AuthenticationCredential provides the authentication method and an identity. In the UML diagram in Figure 3.14, the getMethod method of the Authentication class returns a string that is used to look up the authenticator. The identity information is derived by the implementation of the Credential interface methods.
){kind=link}
One way to look at the AuthenticationCredential is as an initial introduction. Because of the object passed via a join, the membership service knows the peer, its current group, specific credential information, and the method with which the peer is attempting to join.
Figure 3.14 UML for AuthenticationCredential class.
Credential
After you have joined a group, you are issued a credential. The credential implements the credential interface that was shown in Figure 3.14. The credential is a custom implementation that can hold some type of data that is used to identify the peer to the group. Usually, the basic implementation is used because many groups are not concerned with security.
Null Membership Service
The UML in Figure 3.15 is an implementation of the Null membership service. The classes NullMembershipService, NullCredential, and NullAuthenticator are based on MembershipService, Credential, and AuthenticationCredential, respectively. The Null membership is the default membership for the world peer group and any sub-group unless specifically overridden by adding a custom membership service class.
){kind=link}
Figure 3.15 UML for NullMembershipService, NullCredential, and NullAuthenticator classes.
The Join Process
Joining a group via the membership protocol is a multi-step process. The steps are as follows:
-
Obtain or create an initial AuthenticationCredential object. The AuthenticationCredential constructor takes a credential document, the peer group, and the authentication method that the group uses.
-
Get the membership service from the group. Calling the getMembershipService method of the peer group you are going to join does this.
-
Call the apply method of the membership service with your authentication credential. This primes the membership service for step 5.
-
Fill in the appropriate data in the authenticator object.
-
Test the authenticator. You call the isReadyForJoin method of the authenticator and, if true, you can safely join the group.
-
Call the membership service method join.
The result of the join is a final credential that you can pass to other peers in messages. The group also contains this credential that will automatically be added to standard XML messages that require a credential.
Joining a Group
There are two different ways to join groups—via a null authenticator and with a custom group.
Null authentication is the default authenticator for the World group and the default for any new group. Null authentication does not care who you are and performs only token processing to start the peer group normally. The following is a very simple join:
MembershipService membership; membership = (MembershipService) newGroup.getMembershipService(); credential= membership.join( null );
Joining with a custom group is a little more difficult. The first step is to obtain the actual membership service from your group:
MembershipService membership; membership = (MembershipService) newGroup.getMembershipService();
Now you create an authentication credential. The following example uses the group you are joining, the authentication method name, and an initial credential:
AuthenticationCredential authCred;
authCred = new AuthenticationCredential( newGroup
, authenticationMethod
, credentials );
Note that the authentication method string needs to match an authentication method supported by the membership service. The reason for specifying by name is so that different authenticators can be used in diffeereent languages.
Next, you obtain an authenticator by applying to the group. What this does is create an authenticator that is based on your credentials, the group, and the type of authentication you are requesting. Note that you could have multiple authentication methods and credentials represented by authentication credentials. In other words, an insurance group could be made up of patients and doctors. Patients could use a different credential and authentication method than a doctor who may need a different level of identification and processing. Here is an example of the apply method:
Authenticator authenticator = (Authenticator)membership.apply( authCred );
At this point, you now have an object that implements the Authenticator interface. The object is going to have specific methods to configure the authenticator that are specific to the requirements of the group, the method of authentication, and the initial credentials. The settings may be as simple as the username to a series of questions to a name and password.
The Authenticator interface includes a method called isReadyForJoin. The method is implemented to return true if the state of the custom data represents the requirements for a valid join. The following lines check the authenticator to see if it is valid. If you pass, you go ahead and join the group. The isReadyForJoin is also called during join. Make sure you check prior to joining to ensure proper handling of an invalid authenticator object:
if( authenticator.isReadyForJoin() ) {
finalCredential= membership.join( authenticator );
}
If the join method fails because the authenticator returns false for the isReadyForJoin method or for some other reason, the PeerGroupException is thrown.
Final Credential
Notice in the prior example that the return value from the join is a custom implementation of a Credential object. The credential is used for all communications with other peers to prove that you have joined the group. The credential is used by the authenticator service to ensure that only valid peer group members can use services.
Renewing Membership
The protocol specification states that the membership protocol includes the ability to renew a membership. The initial version of the Java API does not include the ability to renew a membership. However, you can write your custom authentication credential that specifies a renewal authentication method and accept the final credential that was created after you joined the group.
Resigning Membership
Resignation from a group is simple. Just call the resign method of the MembershipService object. The credentials used to join the group are destroyed as a part of this process:
membership.resign();