This document is also available in non-normative
Copyright © 2007 DERI, All Rights Reserved. DERI liability, trademark, document use, and software licensing rules apply.
This deliverable will describe the APIs of the D-FOAF system.
1.
Introduction
1.1
Vocabulary
2
Delivered APIs
2.1
ISOA
2.1.1
Main Concepts
2.1.2
Available Methods
2.1.3
Available data (URIs)
2.1.4
Requests statuses
2.1.4
Authentication
2.1.6
Access Control
2.1.7
How to implement Authentication in a SOA client
2.1.8
Authentication process example
2.2
IHLI
2.2.1
How To Initialize a Peer
2.2.2
Joining an existing network
2.2.3
Accepting incoming join requests
2.2.4
Leaving the network
2.2.5
Local query implementation
2.2.6
Performing a broadcast query
2.2.7
A broadcast response
2.2.8
Other Functionalities
2.3
IRDF
2.3.1
TypeConversion
2.3.2
RdfQuery
2.3.3
DbFace
2.3.4
ListValueIterator
2.3.5
ModelX
2.3.6
ModelImplSesame1X
2.4
IJAVA
2.5
IAuth
2.6
IRealm
2.7
Conclusion
6
Acknowledgements
References
This document provides an overview of the FOAFRealm project. It describes architecture and capabilities of this software component.
Figure 1: DFOAF: deployment diagram
The DFOAF/FOAFRealm projects have delivered a digital identity based on social networks; the architecture of the systems is described in DistributedFOAFRealm (DFOAF) Architecture Description. This document presents a deployment diagram and components description; however, the components' interfaces are described in this section. We distinguish six interfaces; but only one of them is really important for developers: The SOA interface. The aim of this section is to present all of them.
The current implementation of FOAFRealm consists of four layers (see Fig. 1):
FOAFRealm SOA is build using REST Web Services approach. In summary, RESTful Web Services are resource based and uses HTTP protocol to access, change, remove or add resources in the server. Resources are identified with unique URI. FOAFRealm SOA uses RDF to exchange the data between client and server. More information could be find in thesis: Service Oriented Architecture for Distributed Identity Management System [6]. REST detailed information Section 2.6, FOAFRealm SOA details Chapters 4, 5, 6.
In REST there are only four methods available. These methods could operate on infinitive amount of data identified by URI. REST uses 4 HTTP methods:
In the following description foafrealm.org/soa/ is a example base service URI.
All the previously mentioned requests could return a common set of HTTP stutuses.
All the previously mentioned requests could return a common set of HTTP stutuses. In FOAFRealm SOA there is HTTP Basic authentication method implemented.
HTTP Basic is supported by majority internet browsers. To use the HTTP Basic outside the browser, there should be specific information send in request header.
To be authenticated, there should be following header field sent:
Authentication: Basic Base64 encoded(login':'password)
If the authentication information is not send (and is required), then the SOA will respond with 401 Unauthenticated HTTP status and the Realm name will be send with WWWAuthenticate: Basic realm="FOAFRealm SOA realm".
Generally, GET method is available without authentication. However to access some specific information about user (like friendship level) user needs to be authenticated.
Other methods (POST, PUT, DELETE) requires user authorisation, and only the owner of the FOAFRealm profile could send such request. For example, only test@test.com, could send the POST request to the http://soa.address/test@test.com/phone.
SOA does not have specific method to log the user in, furthermore the HTTP Basic is stateless. So to authorise user in client there should be done some test to check if user is the one that he/she claims to be. To do that there should be send some request that needs authentication. There could be for example a new timestamp send with POST request. If the SOA answers with "401 3 Unauthenticated", it means that user should not be logged in, if the answer status is 200, it means that the user should be logged in.
To ease the process the special URI was prepared. The http://soa.address/[mbox]/auth should be send with empty content by POST method. The same answers will be returned.
After successful authentication information about user should be kept on client side to be attached in the next request.
The underlying P2P network takes advantage of the HyperCuP protocol. The protocol's implementation is delivered by the HLI [2] library. An example how to use the library can be found in [5]. The following sections describe and show examples how to use the P2P API.
To initialize a peer, the Configurator interface must be obtained. Then, the service address and an alias must be provided. Moreover, there is a need to provide the implementation of the query, which is invoked when the broadcast message comes. The broadcast issues have been described in section 2.2.6. The possible code might looks like the following:
String url = http://localhost:8080/HyperCuPSample/services/HyperCuPService; String alias = HLItest; Configurator conf = HyperCuP.getInstance().registerServiceURL(url,alias); conf.registerLocalQuery((LocalQuery) Class.forName(lqi).newInstance());
After, the successful peer initialization there are two choices. The peer might accept an incoming connection or might join to an existing network.
The peer to whom is sent the request is called Integration Champion (ic). Sometimes, there is a need to obtain the Configurator interface one more time. Therefore, the code might look like this:
String url = http://localhost:8080/HyperCuPSample/services/HyperCuPService;
String ic = http://localhost:8180/HyperCuPSample/services/HyperCuPService;
Configurator conf = HyperCuP.getInstance().getConfigurator(url);
try {
conf.joinNetwork(ic, url);
}catch (Exception e) { response.getWriter().write(e.getMessage());
}
Now, the peers should be connected.
In the previous example, a peer located on the server localhost:8180 has accepted an incoming connection. In reality, the peer does not have to execute any code to be able to accept the incoming connection.
Checking if the peer is in the hypercube in order to check if the peer has joined the network successfully, the folowing code could be invoked:
HyperCuP.getInstance().isJoinedToNetwork(st);
In order to leave the network, the following code should be executed:
Configuratorconf=HyperCuP.getInstance().unregisterServiceURL(url);
It assures of the correct hypercube structure, after leaving. Taking advantage of broadcast messages In order to use the broadcast, several preceding steps must be performed. Firstly there is a need to implement how the peer behaves, when the query comes. Then, the broadcast can be started. When the results are collected, they can be browsed.
The query response and parameters must implement the java.io.Serializable interface. A simple example of the implementation has been presented below:
package mypackage;
import java.io.Serializable;
import java.util.Date;
import org.hypercup.LocalQuery;
import org.hypercup.manage.HyperCuP;
public class LocalQueryImpl implements LocalQuerypublic Serializable performQuery(Serializable arg0)
{
{
return "My answer: "+System.nanoTime();
}
}
In this example, each peer which uses this implementation and is given the query, responds with the current time on the server machine. In practice, the arg0 might be a HashMap instead of String.
In order to leave the network, the following code should be executed:
Configuratorconf=HyperCuP.getInstance().unregisterServiceURL(url);
It assures of the correct hypercube structure, after leaving. Taking advantage of broadcast messages In order to use the broadcast, several preceding steps must be performed. Firstly there is a need to implement how the peer behaves, when the query comes. Then, the broadcast can be started. When the results are collected, they can be browsed.
Once the query is sent, the results are given. An example of how to browse the results has been presented below:
for (BroadcastResult b : result)
{
response.getWriter().writeln("result:"+b.getResult().toString()+"from:"+b.getUri());
}
The results are stored in the Collection of BroadcastResults which looks like the following:
public interface BroadcastResult {Serializable getResult(); URI getUri();
}
Therefore, a peer is given with the addressee of the sender and the response.
HLI has also several other features that are less important from the perspective of the user. Firstly, the implementation tries to recover the cube, if a peer disappear from the network not invoking the leaving protocol. Moreover, peers in the same network must have the same version of the library, otherwise they will not be able to cooperate for security reasons. In addition, peers must take care about each other by sending the keepalive messages to their neightbours. The interval between the messages can be easily changed.
Version The following command obtains the HLI version:
HyperCuP.getInstance().getVersion());
Keepalive interval To get the default keepalive interval, the following method should be invoked:
HyperCuP.getInstance().getDefaultKeepAliveInterval()
The following example changes the interval to 5 seconds:
HyperCuP.getInstance().setDefaultKeepAliveInterval(50000)
This section briefly presents classes and methods we use to manage rdf data; methods provided by RDF2GO [1] library are included.
Class is responsible for conversions between java and repository types.
RDF queries.
An implementation of an iterator to tabular queries.
An interface that extends Model from RDF2Go 1
An implementation of the ModelX and Model.
The way how the webserver uses provided authentication plugin can be found in the webserver documentation. Since we use tomcat, such information is on its webpage [4].
The tomcat realm interface is minutely described on the tomcat website [4].
In this report the target architecture of the FOAFRealm / DFOAF systems has been described. So far, the system has been sucessfully deployed with JeromeDL[4], a digital library with semantics.
The easiest way to get aquainted with the system functionality is to visit an updated-public instance of the JeromeDL; for example, Digital Library of the DERI Ireland.
The authors of the report whould like to thank Sebastian Ryszard Kruk, Tomasz Woroniecki, and Wladyslaw Bultrowicz for their input in the system development and implementation.
[1] RDF2GO
[2] HyperCuP Lightweight Implementation project
[3] JeromeDL project.
[4] Tomcat's Realm interface.
[5] S. Grzonkowski. Security in distributed (p2pbased) user management system. Master's thesis, Gdansk University of Technology, ETI faculty, 2006.
[6] A. Gzella. Service oriented architecture for distributed identity management system. Master's thesis, Gdansk University of Technology, ETI faculty, 2006.