Using the P42 network

Requirements:

• The plugin-interface should be implemented.
• You have to create the advertisements of the plugin with the actual SDK.

Basic setup and group functionality

Create your own service group

Before you can use the network functionality of the peeranha network you have to create a unique service group for your plugin. The following code example illustrates how you create your own service group:

PeerGroup svcPg = 
   Network.createServiceGroup(PluginID);

Subsequently the service group has to be registered to our network. The following subsection shows you how to register a peer group to the network.

Registering of a peer group(also service group) to the network

when a peer group is registered you are able to use the methods send and receive of the network like this:

Network.register(PluginID, 
		PeerGroup, 
		[ Optional: UserName ]);

The network of peeranha42 supports the possibility to own different names in several registered peer groups. Therefore you can specify any user name like you want to. In the case of null as optional user name the network uses the given peer name in this peer group. This name is createdd when you start the configurator and specify a peer name.

Usage of the listeners in the registered peer groups

By implementing the listeners you can get events in the different registered peer groups. The listeners support different tasks like checking the state of the connection to the rendezvous and updating the arrays with the found peers, pipes or group advertisements. The advantage for the developer is that she/he does not worry about the discovery tasks. So you will be informed of changes from the different listener types.

The following listeners are provided when the peer group is registered:

• P42RendezvousListener (informs you about the actual state of the connection to the connected rendezvous)
• P42PeerAdvListener (gives you an array with the actually found Peer Advertisements)
• P42PipeAdvListener (gives you an array with the actually found Pipe Advertisements)
• P42PeerGroupListener (gives you an array with the actually found Peer Group Advertisements)

In order that you can use a listener you have to register it for the plugin in the right peer group. This works like it is shown in the following code example:

Register a P42RendezvousListeners:

Network.addP42RendezvousListener(PluginID, 
			PeerGroup, 
			P42ConnectionListener);

Register a P42PeerAdvListeners:

Network.addP42PeerAdvListener(PluginID, 
			PeerGroup, 
			P42PeerAdvListener);

Register a P42PipeAdvListeners:

Network.addP42PipeAdvListener(PluginID, 
			PeerGroup, 
			P42PipeAdvListener);

Register a P42PeerGroupListeners:

Network.addP42PeerGroupListener(PluginID, 
			PeerGroup, 
			P42PeerGroupListener);

As soon as a new listener is registered to the network you can handle the events which are given by these listeners.

If there are changes concerning the connection state you can get them like this:

public void rendezvousEvent(PeerGroup pg, 
		boolean isConnectedToRendezvous) {
...
}

When the network founds new advertisements regarding peers, pipes or groups the corresponding listeners notice the plugin. Therefore different methods have to be implemented.

// This method is invoked if the 
// P42PeerAdvListener is registered
public void changedPeersEvent(PeerGroup pg, 
	PeerAdvertisement peerAdv_arr[]) {
...
}

// This method is invoked if the 
// P42PipeAdvListener is registered
public void changedPipesEvent(PeerGroup pg, 
	PipeAdvertisement pipeAdv_arr[]) {
...
}

// This method is invoked if the 
// P42PeerGroupListener is registered
public void changedGroupsEvent(PeerGroup pg, 
	PeerGroupAdvertisement pgAdv_arr[]) {
...
}

If a listener should be deregistered you have to do the following for the different registered listeners:

 // deregister a P42RendezvousListeners
 Network.removeP42RendezvousListener(PluginID, 
			PeerGroup, 
			P42ConnectionListener);

 // deregister a P42PeerAdvListeners
 Network.removeP42PeerAdvListener(PluginID, 
			PeerGroup, 
			P42PeerAdvListener);

 // deregister a P42PipeAdvListeners
 Network.removeP42PipeAdvListener(PluginID, 
			PeerGroup, 
			P42PipeAdvListener);
 
 // deregister a P42PeerGroupListeners
 Network.removeP42PeerGroupListener(PluginID, 
			PeerGroup, 
			P42PeerGroupListener);

Deregistering of peer groups

Before you can leave a registered peer group you have to invoke the deregister function in the network of peeranha42. Therefore you can use two different ways which are described in the following subsections.

Leave all registered peer groups of a plugin

With the help of this method you can leave all joined peer groups of a plugin. This method should be invoked at the latest in the stop method of the plugin. When the method is invoked you only have to give the pluginID as parameter.

Network.deregister(PluginID);

Leave a specified peer group of a plugin

To leave a specified peer group of a plugin you have to do the following:

Network.deregister(PluginID, PeerGroup);

Creating peer group(s)

Creation of a new peer group

You can create a new peer group with the following statement:

PeerGroup newpg = 
  Network.createGroup(PeerGroup parentPeerGroup, 
	String peerGroupName, 
	String peerGroupDescription);

If null is inserted as ParentPeerGroup the new created peer group is a subgroup of the Peeranha42PeerGroup. You usually can use each arbitrary peer group. After the new peer group has been created it has to to be registered before you can use the network in this group.

Creating a peer group with a found peer group advertisement

If you have an existing PeerGroupAdvertisement you can use it to create a new peer group instance. This is especially used if you have found PeerGroupAdvertisements with the registered P42PeerGroupListener or manually with getGroupDiscoveryResults(described in the next section).

PeerGroup newpg = 
   Network.createGroup(PeerGroupAdvertisement, 
	ParentPeerGroup);

How do I get the Advertisements without using a listener of a specified peer group?

• It is possible to get the pipe advertisements in a specified peer group of plugin by the folowing statement:
  

  PipeAdvertisement[] peers = 
    Network.getPipeDiscoveryResults(PluginID, 
  	PeerGroup, 
  	String);

  
  After you have done this you get an array with the actually found pipe advertisements in this peer group. By using the search term it is possible to specify the search. When you have found the pipe of a peer you are able to send this peer messages like it is described in the next section.
• If you want to find the peer group advertisements in a peer group of a plugin you can do this like this:
  

  PeerGroupAdvertisement[] groups = 
    Network.getGroupDiscoveryResults(PluginID, 
  	PeerGroup, 
  	String);

  
  This function works analogue to getPipeDiscoveryResults above. The unique difference is that you get back an array with peer group advertisents.
• The way to get the peer advertisements works similar to the two methods above. If any peers are found in the specified group you get back an array with the found peer advertisements. If there are no peers found in the group it will be null returned by the three funcions.
  

  PeerAdvertisement[] peeradvs =
    Network.getGroupDiscoveryResults(PluginID,
  	PeerGroup, 
  	String);

  
  This function is necessary if you want to acquire the IDs of peers in order to send a message to a specified set of peers(peerIDs).

Sending messages over the network

When a peer group has been registered with the help of the register method to the network the plugin is able to send messages in the registered peer group. Therefore you have three possiblities:

Sending unicast messages

If you only want to send one peer a message you can do this by executing the following statement:

Network.sendMsg(PluginID, 
		PeerGroup, 
		PipeAdvertisement, 
		Message);

The parameter peer group indicates the peer group in which the message should be sent. With the specification of the pipe advertisement you define the peer who should be receive the message.

Sending multicast messages

If you want to send a message to all peers in peer group except yourself you can do this by leaving out the pipe advertisement of the unicast sending method. The other parameters do not change.

Network.sendMsg(PluginID, PeerGroup, Message);

Sending messages to a Set of peers(peerIDs)

If you have the desire to send messages to a specified set of peers you get a Set or Collection(for more information look at the java API at java.sun.com --> package jav.util) with the corresponding peerIDs of the specified peers.

Network.sendMsgToSet(PeerGroup, Set, Message);

Receiving messages

If you want to use the following receive function there has to be an implemented Receiver-Interface. By implementing this Receiver you also have to implement the method public Plugin getPlugin(). This should return the reference to your plugin. Unless you have not implemented this method you are not able to receive messages in the following receive method:

public void receive(PeerGroup pg, 
	PipeAdvertisement pa, 
	Message msg)

The parameter peer group indicates in which peer group the arrived message was sent. Furthermore the method gives gives back the pipe advertismement of the peer who send this message. So you are able to reply to this message.