= Resource Directory Cookbook = This document includes instructions about installing and running the SENSEI Resource Directory. [[PageOutline(2-3,Table of Contents,inline)]] ---- == Introduction == The role of the ''Resource Directory'' (RD) is to make the glue between ''Resources'' who advertise the operations they offer as [wiki:RpResDescription Resource Descriptions] and potential clients that look for particular functionalities. Its place in the overall SENSEI system is presented below. [[Image(sensei-system.png, 60%, center)]] The main components comprising an RD are the following: * Resource publication - responsible for publication of available resources and their descriptions * Resource lookup - based on the received search parameters identifies suitable resources in the Resource Database * Resource database - stores descriptions of all resources RD supports the following interfaces for interaction with other SENSEI modules, Resource Providers and Resource Users: * RPI - Resource Publication Interface * RLI - [wiki:RuRli Resource Lookup Interface] The RD functionality is implemented in JAVA programming language in combination with a MySQL database for persistent storage of data. The RD objects are passed through JAVA DAO (Data Access Object) to database stored procedures for data management. Interaction with the resources and users is based on the Restlet framework (http://restlet.org). The Restlet approach utilizes the basic HTTP methods (POST, GET, PUT, DELETE) to build CRUD (Create, Read, Update, Delete) applications. All requests to RD and RD responses are XML formatted messages. Resources publish their descriptions using the RPI, while users search for specific resources using the RLI. [wiki:RpResDescription Resource Descriptions] are XML structures containing a set of tags describing the Resource, as well as the URL where the so called [wiki:RpRepDeployment Resource Endpoint] (REP) – access point to the Resource is located. REP provides the [wiki:RuRai Resource Access Interface] (RAI) for accessing the Resource. ''Advanced Resource Description'' (ARD) is type of tags that can be attached to the Resource Description. ARD is used to semantically describe SENSEI resources, it is specified in RDF (Resource Description Framework) format and can be queried with SPARQL statements using RLI. RD ''Notification Manager'' is in charge of maintaining subscriptions for clients subscribing to a Resource lookup, e.g. requesting information whenever a Resource Description is updated according to the defined criteria, a new resource matching the criteria becomes available or is not available anymore (criteria is based on the set of basic tags). An entity can subscribe to the RD by sending an XML message to RLI using HTTP POST method. RD Notification Manager will periodically send notifications to the specified callback URL, which should be enabled to receive an incoming connection. ''Peering'' is a voluntary interconnection of Resource Directories for the purpose of exchanging traffic between the Resource Directories. It can for example be used by distributed Resource Directories to create a (virtual) federated Resource Directory. The Resource Directory peering mechanism allows a set of distributed Resource Directories to store Resource Descriptions based on responsibility sharing based on domains (i.e. an RD will hold only Resource Descriptions for resources that belong to one of the domains the RD serves). The unique resource identifier that is part of the Resource Description for a resource contains the domain the resource belongs to. The naming and addressing mechanism for SENSEI is described in more detail in [SENSEI D3.4]. In principle the peering mechanism makes the RDs aware of each other. The awareness is provided by a messaging protocol that all the participating RDs adhere to. The messaging between the RDs is used to propagate Join, Leave and Alive messages between the Peered RDs. [[Image(rd-peering.png, 30%, center)]] If you try to lookup a resource that belongs to a different domain than the domain(s) served by the RD you are doing the lookup to, the request will be forwarded to the RD that, based on the domain, should hold the resource (if any). When you try to publish a new resource, the RD you try to publish to will also use this forwarding strategy if the resource you are trying to publish belongs to a different domain than the ones served by the RD you do the POST to. If you try to lookup or publish a Resource Description that belongs to a domain that is not served by any RDs in the set of peered RDs, you will get the following return message: {{{ No RPI server for domain: TheGivenDomain.com }}} ---- == Requirements == * Windows or Linux operating system * [http://java.sun.com/javase/downloads/widget/jdk6.jsp Java SDK], version 6.0 or higher * [http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/heliossr1 Eclipse IDE for Java EE Developers] * [http://dev.mysql.com/downloads/mysql MySQL server], version 5.0.3 or higher * [http://modis.ispras.ru/sedna/download.html Sedna XML database] * [wiki:resDirectory-dwl Resource Directory v2] (RD Eclipse project) * [wiki:resDirectory-dwl RESTArdRepov2] (ARD Repository Eclipse project) ---- == Download the code == Download Eclipse projects in tar.gz format and unpack them:[[BR]] [wiki:resDirectory-dwl Resource Directory download link] ---- == Compilation == Import [Resource Directory v2] and [RESTArdRepov2] projects into Eclipse workspace by selecting '''File -> Import -> General -> Existing Projects into Workspace''' from the Eclipse main menu: [[Image(1.png, center)]] [[Image(2.png, center)]] [[Image(3.png, center)]] Java source files from both projects should be automatically compiled if '''Project -> Build Automatically''' option is checked in Eclipse: [[Image(4.png, center)]] If Build Automatically option wasn't checked, you should compile projects by selecting '''Project -> Build All''': [[Image(5.png, center)]] Compiled Java classes can now be found in the '''{{{bin}}}''' directory inside each project. Database connection properties for the RD application can be modified if needed, inside the file '''{{{ConnectionPool.properties}}}''' from {{{database}}} package in the [Resource Directory v2] project. Properties should be edited if you've changed the database name or user's name in SQL scripts, or if your MySQL server doesn't run on localhost or on the default MySQL port 3306. ---- == Setting up MySQL database == SQL scripts can be found in the Resource Directory v2/doc directory. First, SQL script '''{{{ResourceDirectory_v2_create_user.sql}}}''' should be executed in order to create a DB user. Do it only once, otherwise you'll get the following error (if the user already exists):[[BR]] {{{ERROR 1396 (HY000) at line 5: Operation CREATE USER failed for 'sensei_rd2'@'%'}}} Then run the script '''{{{ResourceDirectory_v2.sql}}}''' to create the RD database structure. SQL scripts can be executed using e.g. MySQL Command Line Client or MySQL Query Browser.[[BR]] Or, scripts can be run from command prompt using the following commands: {{{ # create DB user mysql -u root -p < ResourceDirectory_v2_create_user.sql Enter password: ************ (root password) # create database structure mysql -u root -p < ResourceDirectory_v2.sql Enter password: ************ (root password) }}} Instructions for setting the MySQL max_connections variable can be found in '''{{{MySQL_config.txt}}}''' file. ---- == Running the ARD Repository == First, Sedna XML database for the ARDs (Advanced Resource Descriptions) should be set up.[[BR]] Download Sedna for your operating system from http://modis.ispras.ru/sedna/download.html - Unzip the downloaded file - Run Sedna: {{{SEDNA_PATH/bin/se_gov.exe}}} - Create arddb database (do it only once): {{{SEDNA_PATH/bin/se_cdb.exe arddb}}} - Start arddb database: {{{SEDNA_PATH/bin/se_sm.exe arddb}}} Steps for stopping Sedna: - Stop arddb database: {{{SEDNA_PATH/bin/se_smsd.exe arddb}}} - Stop Sedna: {{{se_stop.exe}}} Java class {{{ArdRepoServerMain}}} from the {{{com.sap.research.sensei.arddirectory.rest.test}}} package from [RESTArdRepov2] project should be run in order to start the ARD Repository. That can be done by executing the batch file inside the [RESTArdRepov2] directory: '''{{{runArdRepov2.bat}}}''' will run on Windows OS, or '''{{{runArdRepov2_linux.sh}}}''' on Linux. After that, ARD listing should be available at http://localhost:8185/ardrepo/ard ---- == Running the Resource Directory == There is a batch file inside the [Resource Directory v2] folder that can be used to start the RD: '''{{{runRDv2.bat}}}''' will run on Windows OS, or '''{{{runRDv2_linux.sh}}}''' on Linux.[[BR]] The batch file can be called with -help option, for getting a list of available RD startup parameters: {{{ c:\path\Resource Directory v2>runRDv2 -help usage: Resource Directory -help Print this message -host The routable IP address of this server (e.g: 173.1.81.228) -peered The domains this peered server serves -port The server port number -version Print the version information and exit }}} The RD can be run in non-peered mode by executing the batch file without parameters: {{{ runRDv2 }}} The RD can be run in peered mode by executing the batch file with -peered and -host options: {{{ # RD serving ericsson.com domain runRDv2 -peered ericsson.com -host 173.1.81.228 # RD serving multiple domains runRDv2 -peered ericsson.com telenor.com telenor.no -host 173.1.81.228 }}} The RD can be run with port option, for example: {{{ runRDv2 -port 8888 }}} for running the RD on port 8888. If -port option is not used, the RD will run on its default 8184 port. After starting the RD, you should be able to access it from a web browser at http://localhost:8184/rd. [[BR]] The RPI (Resource Publication Interface) and RLI (Resource Lookup Interface) will be located at: http://localhost:8184/rpi [[BR]] http://localhost:8184/rli [[BR]] http://localhost:8184/rli/mix/lookup If the RD is started in peered mode, the list of domains that this RD serves and the list of all other RDs in the peering network will be available at: http://localhost:8184/rdridomains ----