This page last changed on Nov 14, 2011 by awoods.
Introduction
This document is intended to provide guidelines for developing your own custom services that can be deployed into the DuraCloud services framework.
The framework has been designed to allow any Java code that can be deployed as an OSGi bundle and implements the ComputeService interface to be dynamically installable into a running DuraCloud application instance.
Overview
In order to understand the flow of services within the services framework, there are several entities with which to become familiar:
DuraService
- web application that exposes a REST-API for end-user management of services
- deploy service
- undeploy service
- configure service
- get service listing
- get service properties
- responsible for retrieving a service to be deployed from the Service Registry and streaming it to the ServicesAdmin
- responsible for mediating subsequent end-user management of deployed services to ServicesAdmin
- responsible for passing service configuration to the OSGi container when a service is being deployed.
- service configuration is defined in the service-repo.xml which is built based on the ServiceInfo class for each service
Service Registry
- persistent holding area of deployable services
- contains Service Packages and a single services-configuration descriptor XML object
- implemented as one or more DuraCloud "space(s)"
- the properties file to initialize DuraCloud contains duraservice.service-storage properties which allow configuration of the host, port, context and space
Service Package
- for simple services, this can be a single OSGi bundle, jar file
- for more involved services, this would be a zip file containing
- OSGi bundle jar that implements the ComputeService interface
- OSGi bundle jars that are both dependencies of the ComputeService bundle (above) and not among the base bundles installed in the OSGi Container by default
- any support files (see 'Example Services' below)
ServicesAdmin
- management component resident in the OSGi container
- exposes an internal REST-API through which communication from DuraService takes place
- responsible for actually communicating with services via their common ComputeService interfaces
- responsible for keeping track of currently deployed services and dependency-link counters
OSGi Container
Example Services
All of the below services are currently functional and available in the DuraCloud source baseline.
They can all be found within the services directory
Pure Java Services
- Bulk Bit Integrity Service
- Bit Integrity Tools Service
- Hello Service
- Duplication On Change Service
- ImageConversion Service
- MediaStreaming Service
Web Application Services
- HelloWebAppWrapper Service
- J2K Service
- CloudSync Service
Bulk (Hadoop) Services
- Bulk Bit Integrity Service
- Bulk ImageConversion Service
- Duplication On Demand Service
System Services
- Script Service
- ImageMagick Service
- WebAppUtil Service
Implementation Guidelines
 | This portion is still under construction. |
OSGi Compatibility
- Although there are several available OSGi containers, and the DuraCloud test harnesses employ Equinox, Felix, and Knoplerfish, the production container into which services need to be able to deploy is Equinox.
ComputeService Interface
Dependency Packaging
Service Descriptor
Development Tools and Environment
This section describes how to start your local DuraCloud OSGi container, as well as how to install and inspect services in the OSGi container from both a commandline tool and via Duradmin.
The DuraCloud OSGi container
- Create the DuraCloud OSGi container.
cd trunk/services/servicesadmin
mvn clean -f pom-run.xml pax:provision
chmod +x runner/run.sh
- Optionally, create a portable OSGi container.
- This generates a zip file named, 'paxrunner-runner.zip' containing everything necessary to run your OSGi container
mvn clean -f pom-run.xml pax:provision -Dpax.provision.executor=zip
- Copy the 'paxrunner-runner.zip' wherever you like, and unzip it.
- Debugging your OSGi container and bundles
- Edit the runner/run.sh script to include the debugging switches
- Replace
java -Xms512M -Xmx768M -DBUNDLE_HOME=$BUNDLE_HOME...
- With
java -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=9001,server=y,suspend=n -Xms512M -Xmx768M -DBUNDLE_HOME=$BUNDLE_HOME...
- Start OSGi container
- Note, the environment variable $BUNDLE_HOME must exist. This variable defines where the DuraCloud services will be installed. Also, a logback.xml should exist in the $BUNDLE_HOME directory. See example logback.xml
cd trunk/services/servicesadmin/runner
./run.sh
Deploying a simple service in isolation
This section describes how to install/uninstall, start/stop, and inspect DuraCloud services via a commandline tool, without needing to have Duradmin or the other DuraCloud webapps running.
- Start the OSGi container, from above.
- Check that the OSGi container is running, GET the following URL:
curl http://localhost:8089/org.duracloud.services.admin_[VERSION]/
- Where VERSION equals something like: '1.2.1' or '1.3.0.SNAPSHOT'
- Note, if you are using a snapshot version, the '-' needs to be converted to a '.' in the URL (e.g. 1.3.0-SNAPSHOT => 1.3.0.SNAPSHOT)
- Start the DuraCloud OSGi services client.
Note, the ServicesAdminClient uses a relative path to find the services from their respective maven build 'target' directories. Therefore, it is necessary that the ServicesAdminClientCLI is started from the 'servicesadminclient' directory.
cd trunk/servicesadminclient
java -jar target/servicesadminclient-[VERSION]-cli.jar localhost [VERSION]
- Install and start HelloService, from servicesadminclient
- Start servicesadminclient-cli from the commandline as detailed above
- to install a service, enter 'i'
- to select the Hello Service, enter 'h'
- to start the Hello Service, enter 'a'
- to select the Hello Service, enter 'h'
- to inspect the Hello Service, enter ''
- to select the Hello Service, enter 'h'
- Check which services are running, GET the following URL:
curl http://localhost:8089/org.duracloud.services.admin_[VERSION]/services/list
- The complete REST API of the OSGi Services Administration component can be found here.
Deploying a simple service from Duradmin
This section describes how to set up your local DuraCloud webapps to run services. This assumes the DuraCloud webapps are running on the localhost.
- Initialize DuraCloud webapps
- See initialization instructions
- Note, the service registry space must be configured in the init.properties
- Note, the service registry manifest name must be configured in the init.properties
- You will know as soon as you select the 'Services' tab in duradmin, below, if the service configuration is correct. This configuration has the potential for causing issue. Below is an example of the pertinent section of init.properties that will need updates. This example has defined the service registry space as, 'service-repo', and it has defined the service manifest file name as, 'duracloud-service-repo.xml'
- Upload helloservice into service registry space
- Log into duradmin : http://localhost:8080/duradmin
- Create service registry space (for example: 'service-repo')
- Upload helloservice-[VERSION].jar into the service registry space
- Do not change the file name, it must match the name listed in the service manifest.
- Upload the service manifest into the service registry space
- The service manifest is a build product of the duraservice project. The non-production services are commented out of the class that generates the service manifest (duraservice: ServiceXmlGenerator.java). You will need to uncomment HelloServiceInfo() in ServiceXmlGenerator.java in the 'serviceInfos' array, and optionally comment out the services that you are not currently testing. Then rebuild the duraservice project without the tests (assuming your commenting updates break the tests).
cd trunk/duraservice
mvn clean install -DskipTests
- Look in duraservice/target for duracloud-[VERSION]-service-repo.xml
- Make sure that the service manifest file name matches what you configured in the init.properties file.
- In duradmin, go to the 'Services' tab and deploy the service.
- Monitor logs produced by duraservice ($CATALINA_HOME/logs/catalina.out) and the OSGi container (as defined by your $BUNDLE_HOME/logback.xml).
|