1. Peergroups

2. Learning Objectives
This module will teach you how to manipulate groups
How to join a group
How to publish and discover groups
How to create a new group
How to create secure groups
Learning Objectives
In this module, we'll be showing how you can manipulate peergroups. Specifically, we'll show how to join a peergroup, how to publish and discover groups, how to create a new group, and how to create secure groups.

3. Creating Peergroup ID
If you need to create a peergroup, all peers must use same peergroup ID
In general, use pre-defined string
Can use JXTA Shell to generate string:
JXTA> mkpgrp mygroup
JXTA> groups group0: name = mygroup
JXTA> cat group <GID> urn:jxta:uuid-71A8EC0B31BA471BB053B287211BC </GID> ....
Creating Peergroup ID
Let's start with creating a peergroup. If you are going to create a peergroup, you will need a peergroup ID to identify this group. All peers must use the same peergroup ID for this peergroup. If two peers create a peergroup and each uses a different peergroup ID, they have essentially created two different peergroups.
In general, it's best to use a pre-defined string when creating your peergroup ID. This string can then be embedded in your application to create the peergroup.
You could create an application that creates a peergroup ID, run this application once, and then save the peergroup ID that was generated. However, an easier way to do this is to use the JXTA Shell to create a new peergroup. You can then save and use this peergroup ID in your application.
This example here shows running the mkpgrp command to create a new peergroup. The groups command lists all the groups this shell knows about – here we can see that our newly created group is stored as group0 in the Shell environment. By using cat we can display information about this group, including its peergroup ID.

4. Publishing Peergroups
Peergroups are automatically published locally when they are created
Published with default expiration values
No need to explicitly call DiscoveryService.publish()
To remotely publish a peergroup
Call DiscoveryService.remotePublish
Publishing Peergroups
Peergroups must be published so that other peers in the JXTA network can discover them.
By default, peergroups are automatically published locally (in the local cache) when they are created. Because of this, there is no need to explicitly call the method DiscoveryService.publish() to publish an advertisement locally. Peergroups are published with default expiration values. If you want to specifiy a different expiration value, you can re-publish with a new value.
To remotely publish a peergroup, you use the method remotePublish() to make the advertisement available to other peers in the peergroup.

5. Joining Peergroups Membership Service
Used to apply for peergroup membership, join a peergroup, and resign from a peergroup
Enables peer to establish an identity within a peergroup
Identities used by services to determine the capabilities which should be offered peers
Joining Peergroups
The Membership Service is used to apply for peergroup membership, join a peergroup, and resign from a peergroup.
This service also enables a peer to establish an identity within a peergroup. Identities can be used by services to determine the capabilities which should be offered to peers. The Membership Service can be used to control access of resources within the JXTA network as well as the capability for a peer to act as a rendezvous or relay within the peergroup.

6. Sequence of Establishing Identity
Apply
Peer provides membership service an initial credential; service returns an authenticator object
Join
The completed authenticator is returned to the membership service and the identity of the peer is adjusted
Resign
The existing identity for this peer is discarded
Sequence of Establishing Identity
The Membership Protocol can be used to restrict membership to peergroups. Any peer that wants to join the peergroup must present a set of credentials. The peergroup examines these credentials and then decides whether or not the peer can join the group.
The sequence of events in establishing a peer's identity and joining a peer group is: apply for membership, join the peergroup, resign from the peergroup.
Apply – Before joining a peergroup, a peer must first discover at least one member of the peergroup and apply for membership. The peer provides the Membership Service with an initial credential. The service returns an authenticator object.
Join – The peer completes the authenticator object and returns it to the Membership Service. The actual methods and values used here will depend on the specific requirements of this peergroup. If this is successful, the peer is allowed to join the group and its identity is adjusted.
Resign – When a peer resigns from a peergroup, the existing identity for this peer is discarded.

7. Secure Peergroups
Need to assign a secure membership service to the peergroup
Decentralized (Peergroup certificates)
Centralized (LDAP authentication server)
Define principal roles in the peergroup
Read only – read/write access
Act as relay or rendezvous
etc.
Peergroup advertisement publishing scope
Secure Peergroups
A secure membership can be assigned to a peergroup to control access to the resources shared within the peergroup.
Different authentication policies can be enforced using either a centralized certificate authenticator or a distributed certificate authentication policy
The membership service can define roles with different levels of resource access – for example, read only or read/write access, and the ability to act as a relay or rendezvous.

8. Peergroup – Java API Creating & Publishing Peergroups
getAllPurposePeerGroupImplAdvertisement()
Get an allPurpose peerGroup ModuleImplAdvertisement compatible with this group.
newGroup(Advertisement pgAdv) newGroup(PeerGroupID pgID) newGroup(PeerGroupID gid, Advertisement impl, java.lang.String name, java.lang.String descr)
Create a new group and publish it.
publishGroup(java.lang.String name, java.lang.String descr)
Force publication of the group if it hasn't already been done.
Java API: Creating and Publishing Peergroups
PeerGroup.getAllPurposePeerGroupImplAdvertisement()
Creates a generic advertisement; it automatically sets all of the attributes of the peergroup advertisement (based on whichever peergroup is being used as the parent of the new peergroup)
PeerGroup.newGroup()
Creates a new peergroup and publishes it locally; it will be indexed on the rendezvous. Note: Although newGroup() publishes the peergroup advertisement automatically, you must explicitly publish other types of advertisements you create.
The first format creates a peergroup from its peergroup advertisement. [Note: This method is used when the peergroup advertisement has been discovered first.]
The second format instantiate a group from its groupID only. Use this when creating a group that has already been published and discovered. The typical uses of this routine are therefore: (1) instantiating a group which is assumed to exist and whose GID is known; (2) creating a new group using an already published advertisement, which was typically published for that purpose. [Note: This method is used when the peergroup has been instantiated and the peergroup ID is known.]
The third format is typically used when creating a whole new group based on a newly created and possibly unpublished implementation advertisement. You first call getAllPurposePeerGroupImplAdvertisement() and then pass the returned advertisement to newGroup(). [Note: this method is used when a new peergroup is constructed from scratch using a new implementation representation.]
PeerGroup.publishGroup()
This method publishes a peergroup advertisement. It is used to republish the peergroup advertisement in case new information is added or updated in the advertisement.

9. Membership Service – Java API
Joining Peergroups
apply(AuthenticationCredential application)
Request the necessary credential to join the group with which this service is associated.
getAuthCredentials() getCurrentCredentials()
Returns the current credentials for this peer
join(Authenticator authenticated)
Join the group by the virtue of the complete authentication provided.
makeCredential(Element element)
Given a fragment of a StructuredDocument, reconstruct a Credential object from that fragment.
resign()
Leave the group to which this service is attached.
Java API: Joining Peergroups
PeerGroup.apply()
MembershipService.getAuthCredentials()
MembershipService.getCurrentCredentials()
MembershipService.join()
MembershipService.makeCredential()
MembershipService.resign()

10. Create a Peergroup— Java
private PeerGroup createGroup() {
PeerGroupAdvertisement adv;
System.out.println("Creating a new group advertisement");
try {
// create a new all purpose peergroup.
ModuleImplAdvertisement implAdv =
myGroup.getAllPurposePeerGroupImplAdvertisement();
PeerGroup pg = myGroup.newGroup(null, // Assign new group ID
implAdv, // The implem. adv
"PubTest", // Group name
"testing group adv"); // Helpful descr.
// print the name of the group and the peer group ID
adv = pg.getPeerGroupAdvertisement();
PeerGroupID GID = adv.getPeerGroupID();
System.out.println(" Group = " +adv.getName() +
"\n Group ID = " + GID.toString());
} catch (Exception e) {
System.out.println("Group creation failed with " + e.toString());
return null; }
// publish this advertisement (send to other peers, rdv peers)
discovery.publish(adv, DiscoveryService.GROUP,
PeerGroup.DEFAULT_LIFETIME,
PeerGroup.DEFAULT_EXPIRATION);
discovery.remotePublish(adv, DiscoveryService.GROUP);
System.out.println("Group published successfully.");
} catch (IOException e) {
System.out.println("Error publishing group advertisement");
e.printStackTrace();
return(pg);
Java: Create a Peergroup
This example creates a generic JXTA peergroup. In other words, it will not define alternate endpoints or services. It will simply use default services provided by the platform.
The example creates a group named PubTest, and publishes the Group Advertisement with a default lifetime of one year, and an expiration for others of 2 hours.

11. Join a Peergroup—Java private void joinGroup(PeerGroup grp) {
StructuredDocument creds = null;
try {
// Generate the credentials for the Peer Group
AuthenticationCredential authCred =
new AuthenticationCredential( grp, null, creds );
// Get the MembershipService from the peer group
MembershipService membership = grp.getMembershipService();
// Get the Authenticator from the Authentication creds
Authenticator auth = membership.apply( authCred );
// All authenticators besides 'Null' require you to do something here.
// Check if everything is okay to join the group
if (auth.isReadyForJoin()){
Credential myCred = membership.join(auth);
System.out.println("Joined group " + grp.getPeerGroupName());
// display the credential as a plain text document.
System.out.println("\nCredential: ");
StructuredTextDocument doc = (StructuredTextDocument)
myCred.getDocument(new MimeMediaType("text/plain"));
StringWriter out = new StringWriter();
doc.sendToWriter(out);
System.out.println(out.toString());
out.close(); }
else
System.out.println("Failure: unable to join group");
catch (Exception e){
System.out.println("Failure in authentication.");
Java: Join a Peergroup
In this example, we show how to use the Java API to join a peergroup.
First, we need to generate credentials for the peergroup we want to join. Authentication credentials are used by the JXTA MembershipService services as the basis for applications for peergroup membership. The AuthenticationCredential provides two important pieces of information: the authentication method being requested and the identity information which will be provided to that authentication method. Not all authentication methods use the identity information. The constructor new AuthenticationCredential() takes three arguments:
the peergroup we want to join
authentication method (null in this example)
a structured document containing identity information (not used in this example)
Then, we retrieve the Membership Service from the peergroup we want to join and call its apply() method to get the authenticator object: Authenticator auth = membership.apply( authCred );
All authenticators besides 'Null' would require us to do something at this point – perhaps fill in a user ID and a password. After we do whatever is required (nothing in this example), we check if everything is okay to join the group: auth.isReadyForJoin();
If everything is ready, we call MembershipService.join() to join the peergroup: Credential myCred = membership.join(auth); This method returns a credential – the identity of this peer in the peergroup it just joined.
We then display the credential as a plain text document.

12. Peergroup Service – C API
Registering and Accessing Peergroups
jxta_register_group_instance (Jxta_id *gid, Jxta_PG *pg)
This method registers a group instance.
jxta_unregister_group_instance (Jxta_id *gid, Jxta_PG *pg)
This method unregisters a group instance.
jxta_lookup_group_instance (Jxta_id *gid, Jxta_PG **pg)
This method is used to access a child peergroup instance
jxta_PG_get_GID(Jxta_PG* self, Jxta_PGID** gid)
This method is used to access the peergroup ID
jxta_PG_get_PID(Jxta_PG* self, Jxta_PID** pid)
This method is used to access peerid
jxta_PG_get_groupname(Jxta_PG* self, JString** gname)
This method is used to access the peergroup name
C API: Registering and Accessing Peergroups
The C API has two functions for registering and deregistering peergroups. You register a peergroup when you are instantiating an instance of the peergroup on the peer. You deregister when you deallocate the peergroup when the peer is leaving the peergroup.
jxta_register_group_instance()
jxta_unregister_group_instance()
Use the jxta_lookup_group_instance() function to check if the peergroup has already been instantiated on the peer. We don't want to instantiate the same peer twice on the same peer.
jxta_lookup_group_instance()
These functions are used to access the peergroup ID, the peer ID, and the peergroup name:
jxta_PG_get_GID()
jxta_PG_get_PID()
jxta_PG_get_groupname()

13. Peergroup Service – C API
Accessing Peergroup Services
jxta_PG_get_endpoint_service(Jxta_PG* self,Jxta_endpoint_service** endp)
This method is used to access the peergroup endpoint service
jxta_PG_get_rendezvous_service(Jxta_PG* self,Jxta_rdv_service** rdv)
This method is used to access the peergroup rendezvous service
jxta_PG_get_discovery_service(Jxta_PG* self,Jxta_discovery_service** disco)
This method is used to access the peergroup discovery service
jxta_PG_get__membership_service(Jxta_PG* self,Jxta_membership_service** membership)
This method is used to access the peergroup membership service
jxta_PG_get_pipe_service(Jxta_PG* self, Jxta_pipe_service** pipe)
This method is used to access the peergroup pipe service
jxta_PG_get_resolver_service(Jxta_PG* self, Jxta_resolver_service** resolver)
This method is used to access the peergroup resolver service
jxta_PG_get_peerinfo_service(Jxta_PG* self, Jxta_peerinfo_service** peerinfo)
This method is used to access the peerinfo pipe service
C API: Accessing Peergroup Services
These methods are used to access the various peergroup services. For example, the jxta_PG_get_discovery_service() method is used to access the peergroup discovery service, while the jxta_PG_get_membership_service() method is used to access the peergroup membership service.

14. Peergroup Service – C API
Creating Peergroups
jxta_PG_newfromadv (Jxta_PG *self, Jxta_advertisement *pgAdv Jxta_vector *resource_groups, Jxta_PG **result)
Instantiate a group from its given advertisement Use this when a published implementation advertisement for the group sub-class can be discovered.
jxta_PG_newfromimpl (Jxta_PG *self, Jxta_PGID *gid, jxta_advertisement *impl, JString *name, JString *description, Jxta_vector *resource_groups, Jxta_PG **result)
Convenience method, instantiate a group from its elementary pieces and publish the corresponding peer group advertisement.
jxta_PG_newfromid (Jxta_PG *self, Jxta_PGID *gid, Jxta_vector *resource_groups, Jxta_PG **result)
Instantiate a group from its group ID only.
C API: Creating Peergroups
jxta_PG_newfromadv()
This function instantiates a group from its given advertisement. You should use this function when a published implementation advertisement for the group sub-class can be discovered.
jxta_PG_newfromimpl()
This function instantiates a group from its elementary pieces and publishes the corresponding peergroup advertisement. This method is used when a new peergroup is constructed from scratch.
jxta_PG_newfromid()
This function instantiates a group from its group ID only. This function is used when the peergroup has previously been instantiated and the peergroup ID is known.

15. Join a Group—C Jxta_PG * newPG = NULL; Jxta_PGA * pga = NULL
/* Discover advertisement of the group we are looking to join */
jxta_PG_get_discovery_service(group, &discovery);
discovery_service_get_local_advertisements(discovery,
DISC_GROUP,
(char *)jstring_get_string(attr),
(char *)jstring_get_string(value),
& res_vec);
if (res_vec != NULL ) {
for (i=0; i < jxta_vector_size(res_vec); i++ ){
jxta_vector_get_object_at (res_vec, (Jxta_object**)&pga, i);
JXTA_OBJECT_SHARE(pga);
} else {
// No group advertisements retrieved }
/* Reuse the resource groups of our parent. */
jxta_PG_get_resourcegroups( group, &resources );
/* add the new group's parent */
jxta_vector_add_object_last( resources, (Jxta_object*) group );
res = jxta_PG_newfromadv ( group, (Jxta_advertisement*) pga, resources, &newPG );
C: Join a Group
This example illustrates how to use the C API to join a group.
First, we need to discover the advertisement of the group we're looking to join. We do this by retrieving the discovery service from our peergroup: jxta_PG_get_discovery_service(group, &discovery)
Then, we check if the local cache contains the group advertisement: discovery_service_get_local_advertisements( ... ); This functions takes five arguments:
discovery service
type of advertisement we're looking for
attribute used to narrow the search (optional)
value used to narrow the search – used as attribute/value pair (optional)
reservations that are found in the local cache
We reuse the resource groups of the parent when we clone the services of the parent peergroup. This is just a convenience method to ease the creation of a new peergroup, as you don't have to provide a full new implementation. The parent peergroup keeps a pointer to all its children peergroups.
Finally, we create the new peergroup: jxta_PG_newfromadv( ... )

16. Join a Group—C (continued)
if( res == JXTA_SUCCESS ) {
// Group correctly joined }
/* looking for a rendezvous */
jxta_PG_get_GID( newPG, &gid );
jxta_id_to_jstring( gid, &gidstr );
while( iterations < 20 ) {
//Searching for Rendezvous
/* flush */
if( 0 == (iterations % 3) ) {
int qid = discovery_service_get_remote_advertisements(discovery,
NULL,
DISC_ADV,
"RdvGroupId",
jstring_get_string(gidstr), 5,
NULL);
/* nap a while */
jpr_thread_delay( 5 * 1000 * 1000 );
C: Join a Group (continued)
If the call to jxta_PG_newfromadv() returned JXTA_SUCCESS, then we know the group was joined correctly.
Next, we need to look for a rendezvous for this peergroup. We get the peergroup ID of our new peergroup: jxta_PG_get_GID( newPD, &gid );
Then we loop looking for a rendezvous peer for this peergroup. We send out a discovery request looking for advertisements for rendezvous peers – the attribute = “RdvGroupID” and the value is the group ID of our new peergroup. The discovery_service_get_remote_advertisements() method takes 7 arguments:
discovery service
(NULL) peer ID of specific peer to send this request to
type of advertisement we're looking for; because we're looking for a rendezvous advertisement, we use DISC_ADV (all non-peer and non-peergroup advertisements).
attribute used to narrow the search (“RdvGroupId”)
value used to narrow the search – (our group ID)
maximum number of advertisements to be returned from one peer
(NULL) discovery listener
Each peergroup has its own set of rendezvous. When the peer joins the peergroup, it needs to find rendezvous for this peergroup.

17. Join a Group—C (continued)
discovery_service_get_local_advertisements(discovery,
DISC_ADV,
"RdvGroupId",
jstring_get_string(gidstr),
& res_vec);
if (res_vec != NULL ) {
int i;
for (i=0; i < jxta_vector_size(res_vec); i++ ) {
Jxta_RdvAdvertisement * rdvAdv = NULL;
jxta_vector_get_object_at ( res_vec, (Jxta_object**)&rdvAdv, i);
if( NULL != rdvAdv )
jid = jxta_RdvAdvertisement_get_RdvPeerId( rdvAdv );
jxta_id_get_uniqueportion( jid, &jidstr );
addr_e = jxta_endpoint_address_new( (char*) jstring_get_string(jidstr));
jxta_PG_get_rendezvous_service( (Jxta_PG*) group, &rdv );
jxta_peer_set_address (peer, addr_e);
jxta_rdv_service_add_peer( (Jxta_rdv_service*) rdv, peer);
break; }
/* To resign from a peergroup */
Jxta_membership_service * membership;
jxta_PG_get_membership_service( group, &membership );
if( NULL != membership ) {
jxta_membership_service_resign( membership );
C: Join a Group (continued)
After sending out discovery requests, we then go and check the local cache to see if we've received any responses (i.e., received any advertisements for rendezvous peers for our new peergroup).
If we've found a rendezvous, we loop through the vector of returned rendezvous advertisements (res_vec), and extract the peer ID of the rendezvous: jxta_RdvAdvertisement_get_RdvPeerId( rdvAdv );
Then, we get the unique portion of the peer ID and use this to create a new endpoint address: jxta_endpoint_address_new( ... );
Finally, we get the rendezvous service, and then add our peer: jxta_rdv_service_add_peer( ... );
Resigning from a peergroup
If we want to resign from a peergroup, we just need to get the membership service and pass it to the jxta_membership_service_resign() function.

18. End – Peergroups