PeerManager Manual v1.0

1. Introduction

PeerManager is a framework for managing services in a P2P application. The purpose of this framework is to provide a service layer independant of the underlying P2P network. PeerManager handles the instantiation, execution, advertisment and discovery of client and server services. This abstraction allows developers to focus on specific services instead of functionality common to other applications.

This project is being developed for use with OCKHAM registry network project but because it is useful outside of the OCKHAM project it will be distributed by itself as well.

1.1 Project Status

Peermanager is nearing a 1.0 release, beyond that release no work is planned.

PeerManager was originally written for the JXTA framework but the focus has shifted to providing TCP networking.  While clients and servers will work over either a TCP Socket or JxtaSocket the JXTA portion of this project is not being worked on at this time.

1.2 Getting & Building PeerManager

Currently PeerManager is only available as source code. You can download the source at https://svn.osuosl.org/public/ockham/PeerManager.

2. Licensing

PeerManager is released under the GNU General Public License but contains binaries from the Apache Software Foundation and Project JXTA which are bound by the Apache license v2.0 and the JXTA license respectively.

Apache Notice

This product includes software developed by
The Apache Software Foundation (http://www.apache.org/).

Portions of this software were developed at the National Center
for Supercomputing Applications (NCSA) at the University of
Illinois at Urbana-Champaign.

This software contains code derived from the RSA Data Security
Inc. MD5 Message-Digest Algorithm, including various
modifications by Spyglass Inc., Carnegie Mellon University, and
Bell Communications Research, Inc (Bellcore).

Regular expression support is provided by the PCRE library package,
which is open source software, written by Philip Hazel, and copyright
by the University of Cambridge, England. The original software is
available from
      ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/

JXTA Notice

This product includes software developed by Sun Microsystems, Inc. for JXTA(TM) technology

The full license texts are available with this distribution in the following files:

• Apache-LICENSE-2.0.txt
• JXTA-LICENSE.txt
• GPL-LICENSE.txt

3. Network Abstraction

The underlying network is abstracted from the services.  Servers and Clients should in most cases not need to know what network they are working on.  This is made possible by the Network interface.  A specific implementation should be created for the network peermanager operates on.  Peermanager provides TCPNetwork and JXTANetwork implementations.

Clients and servers will interact with a Network implementation to do the following:

• Open an incoming or outgoing connection.
• Determine if a peer can be found on the network.
• Report to the network layer that a peer was not responsive 

4. Clients & Servers

The PeerManager facilitates two types of services, clients and servers. The distinction between the two is in the direction of the traffic. Clients send data and servers receive data.

4.1. Servers

A server is any service that accepts incoming data. There are two types of servers, consumers and responsive. Responsive servers respond, while consumers do not.

A server service is comprised of two parts. A Server and a RequestHandler. The server is only concerned with how to receive the message and how to instantiate the RequestHandler. Once a RequestHandler is instantiated it is passed off to the ServerManager so the Server can resume waiting for more requests. By configuring a Server implementation to use different handlers it can serve many different types of requests.
The RequestHandler is a runnable encapsulation of the logic for handling a specific type of request. This model allows execution of different request processing to be handled by a single load manager.

Required attributes:

• serverName - name of the server, see the section on naming services
• className - fully qualified classname of a class implementing Server
• handlerClass- fully qualified classname of the class that encapsulates the logic for this specific server. Class must extend from ServerHandler

Example configuration:

<peerManager>
...
<servers>
	<server
	        serverName="OCKHAM:Testing:PeerManagerTester"
                className="org.osuosl.jxta.peermanager.server.JXTAServer"
                 handlerClass="org.osuosl.jxta.peermanager.testing.TestRequestHandler"
	/>
</servers>
...
<peerManager>

4.2. Clients

A Client is a service that connects to a server to send or request data.

The preferred client is the SocketClient.  This client will operate using any network that supports java.net.Socket.  

Required attributes:

• clientName - name of the server, see the section on naming services
• className - fully qualified classname of a class implementing Client

Optional attributes:

Example configuration:

<peerManager>
...
<clients>
     <client
          clientName="OCKHAM:Testing:PeerManagerTester"
          className="org.osuosl.jxta.peermanager.testing.TestClient"
     >

     </client>
</clients>
...
<peerManager>

5. Load Management

A PeerManager potentially can control many client and or server services. The management of these services are divided up into four concurrent areas: Servers, Clients, Server Discovery, Server Publishing. A manager class controls each of the four areas with the PeerManager acting as the master.

The initial version of PeerManager will only contain simple implementations of the managers. Managers are loaded via configuration at runtime allowing new implementations to be plugged in at any time.

5.1 Peer Manager

The PeerManager object is the central point of the framework. It contains and manages the other four managers and also contains the list of servers and clients.

SimplePeerManager is a simple implementation of PeerManager. It is only a basic implementation that initializes and starts the other components. It contains no load management or prioritization of other managers.

Required attributes:

• peerName - name of the peer, this may be taken from the JXTA configuration at somepoint.
• className - fully qualfied classname that implements PeerManager

Example configuration:

<peerManager
     peerName="Peter's WorkStation"
     className="org.osuosl.jxta.peermanager.manager.SimplePeerManager"
>
...
</peerManager>

To instantiate a PeerManager you use PeerManagerLoader.createPeerManager(). By default the configuration file is "services.xml" but you may optionally pass in the name of another file in the classpath.

Example usage:

// create a PeerManager using the specified file
PeerManager peerManager = PeerManagerLoader.createPeerManage("myServices.xml");

//start JXTA and get the peergroup
PeerGroup = startJXTA();

//set the peergroup for the peerManager
peerManager.setPeerGroup( PeerGroup );

// start the PeerManager
peerManager.start();

5.2.Server Manager

The server manager handles the processing of requests received by servers. A single server manager can handle the requests from multiple servers. This is achieved by encapsulating the logic of servers into RequestHandlers. RequestHandlers extend from Thread so that they can be executed by a ServerManager without it having knowledge of how or what processing it does.

SimpleServerManager is a simple implementation of ServerManager. Currently it only fufills the basic needs of receiving and executing requests. It makes no consideration of processing load or priorities.

Required attributes:

• className - fully qualfied class name of a ServerManager implementation

Example configuration:

<peerManager>
...
<serverManager
     className="org.osuosl.jxta.peermanager.manager.server.SimpleServerManager">
     <!-- set Interval of request execution -->
     <property name="interval" value="60000"/>
</serverManager>
...
</peerManager>

6. Configuring Additional or Custom Properties

Only required properties are specified in the DTD describing the configuration file. Optional properties or properties added in custom implementations can be specified using <property> tags provided the property conforms to the bean standard. This is available for any component to provide a defined yet flexible configuration file

Example:

<serverManager
       className="org.osuosl.jxta.peermanager.manager.server.SimpleServerManager">
       <property name="interval" value="60000"/>
</serverManager>

The configuration file is parsed using the commons-digeseter from the Apache Software group. The ruleset for parsing is defined in configRules.xml. If you wish to modify the parsing model you may specificy a new rules.xml by calling PeerManagerLoader.createPeerManager( String configfile, String rulesfile )

7. Naming Server and Client Services

The names of clients and servers are used for publishing and discovery of advertisements. The names of clients and servers should be identical or no matches will be found. When a PeerManager publishes a server it appends the PeerName onto the ServerName, when making discovery attempts a wildcard is used to look for all peers. All peers on a network must use the same scheme for advertising and publishing.

Server formula:

<ServiceName>:<PeerName>

Example of MyPeer publishing MyService:

MyService:MyPeer

Example of search query:

MyService:*

Naming will be moved into its own component at some point to keep the logic for determining publish strings and query strings in a central place. This will allow different naming schemes to be used if desired. This is not an essential feature so it is unsure when it will be implemented.

8. JXTA 

JXTA is a P2P framework created by Sun Microsystems.  PeerManager was originally designed to work with JXTA and has some components specific to it.

8.1. DiscoveryManager

The DiscoveryManager handles the discovery of advertisements for servers. P2P networks are inherently dynamic, peers may join or publish advertisements at different times. Because of this a peer needs to periodically try to discover new advertisements.

SimpleDiscoveryManager is a simple implementation of DiscoveryManager. It periodically sends discovery requests to find servers for the clients that the PeerManager is running. Any responses are stored with the client that uses them.

Required attributes:
className - fully qualfied class name of a ServerManager implementation

Example configuration:

<peerManager>
...
<discoveryManager
     className="...peermanager.manager.discovery.SimpleDiscoveryManager">
     <property name="interval" value="60000"/>
</discoveryManager>
...
</peerManager>

8.2. AdvertiesmentManager

The AdvertisementManager handles publishing advertisements for servers that a PeerManager is running. The purpose of this manager is to ensure that advertisements reach other peers. Peers can join the network at any time and re-publishing an advertisement

SimpleAdvertisementManager is the simple implementation of AdvertisementManager. It periodically remotely publishes advertisements for servers the PeerManager is running. Advertisements for Response servers are not published since they not intended to receive unsolicited requests.

Required attributes:

• className - fully qualfied class name of a ServerManager implementation

Example configuration:

<peerManager>
...
<advertisementManager
     className="...peermanager.manager.advertisement.SimpleAdvertisementManager">
     <property name="interval" value="60000"/>
</advertisementManager>
...
</peerManager>

9. Logging

Log4J is used to provide logging. By default logging on PeerManager will be set to INFO.

10. Code Samples

A Client / Server pair has been included for testing and to be sample code. The test services use the JXTA network to send data.

The files are located in package org.osuosl.jxta.peermanager:

• TestClient.java - client that sends a simple request
• TestRequestHandler.java - handler that processes the request and sends a response
• TestResponseHandler.java - handler that processes the response from the server
• services.xml - configuration file for the test PeerManager
• PeerManagerTester.java - application that instantiates and starts the test PeerManager