Developing a Service

THIS SECTION OF GCUBE DOCUMENTATION IS OBSOLETE. THE NEW VERSION IS UNDER CONSTRUCTION.

How to develop a WSRF service that works in DILIGENT

Introduction

In these pages it is explained how to prepare a service to be compliant with the Final RC version of the DILIGENT Collective Layer. This mainly means:

to follow some rules related to the service packaging procedure
to integrate a service with the Collective Layer libraries that allow it to be published and discovered by others and to be aware of the infrastructure/VO/DL/DHN in which it is acting on

Service files and rules

A gCube service is primarly a WSRF service runnable on Java WS Core v4.0.4, therefore it must follow the packaging rules to build a GT4 Deployable GAR file. In addition to such rules, others are required by the Collective Layer to correctly manage the services.

WSDD files

A service could be deployed in a secure or a non secure DL. In the latter case, the CL layer deploys the service without the security enabled on its operation. In order to do that, two Web Service Deployment Descriptor (WSDD) files must be provided, one that declares the Security Descriptor and another one without such a declaration. These two files must per placed in the /etc folder included in the GAR and must be named as follows:

deploy-server.wsdd (security enabled)
deploy-server.wsdd_NOSEC (security disabled)

For further details about how to declare the Security Descriptor in the WSDD file, see here.

Service Stubs

The service stub classes have to be placed in a separate JAR file, not included in the GAR file. This is because of the CL layer needs a full controll on the undeploy the stubs by assuring that they are undeployed only if and when they are no longer used by other services.

GAR ID

When a GAR file is deployed on a Java WS Core container, it is labelled with a GAR ID. Such GAR ID is used at undeployment time to remove the package. Since it is not so simple to programmatically detect the assigned ID, the following rule has been fixed: the GAR ID is the gar filename without the .gar extension.

Example: if the GAR filename of my service is org_diligentproject_class_service.gar the GAR ID will be org_diligentproject_class_service

This rule has, of course, an impact on the service code because it has to be taken into account for example when the service tries to access to its etc/gar.id folder.

Service profile

A service profile is an XML file that describes a Service Archive. How to write a service profile is explained in the Profile Specification section of this manual.

Putting all together: the service Archive on ETICS

In order to be registered on the DILIGENT infrastructure, a Service must be packaged in a Service Archive using the ETICS facilities. An appropriate configuration there must package all the packages logically related to a service in a single artifacts and its tarball must be available on the ETICS repository.

Managing a gCube Running Instance state on a DHN

Once a service is deployed on a DHN, it has to be initialized before to be able to accept requests from its clients. This initialization is normally located in the service or factory constructor or in a class that implements the javax.xml.rpc.server.ServiceLifecycle interface. Part of it concerns the DHN initialization, another part is related to the specific semantic initialization of the service. For the DHN initialization the service has to interact with the Node Access Library in the following way:

Define a class that implements the org.diligentproject.keeperservice.hnm.impl.startup.gCubeRIStateICallback interface:


package org.diligentproject.keeperservice.hnm.impl.startup;

public interface gCubeRIStateICallback {

	/**
	 * Invoked when the RI passes in a Ready state
	 * 
	 */
	public void ready();

	/**
	 * Invoked when the RI passes in a Failed state
	 * 
	 */
	public void failed();

	/**
	 * Invoked when the RI passes in a Disabled state
	 * 
	 */
	public void disabled();

	/**
	 * Invoked when the RI is redeployed as substitute of a
	 * died/unreachable/disabled RI (final advanced release)
	 * 
	 */
	public void redeployed();
}

Move the RI initialization in the ready() method of such a class.

Register the RI on the DHN in the constructor of your Service or Factory class or in the init() method of a class that implements the ServiceLifecycle interface using one of the registration method provided by the static class org.diligentproject.keeperservice.hnm.impl.startup.gCubeStartupManager:

gCubeStartupManager.registerRI(<ServiceClass>, <ServiceName>, <gCubeRIStateICallback>);

or 

gCubeStartupManager.registerRI(<ServiceClass>, <ServiceName>, <gCubeRIStateICallback>, <SimpleCredentialsListener>);

or 

gCubeStartupManager.registerRI(<ServiceClass>, <ServiceName>, <gCubeRIStateICallback>, <MultipleCredentialsListener>);

Then, once the RI is ready, the ready() callback method is invoked and the RI can start to interact with the CL and DLL services and all the incoming requests are authorized and passed to the appropriate service's operation.

Report any change in the RI state by invoking the setState() method exposed by the Node Access Library

Example

TBP

Integrating DHN's Collective Layer components

For a service, acting in a DHN means to interact not only with the local Java WS Core container, but also with part of the Collective Layer software installed on the node. Such software allows to:

access to the local DHN configuration
publish/retrieve information in/from the DILIGENT Information Ssytem
understand the context in which a service is acting
configure and exploit the authentication mechanisms

To understand how this works, we give in the following a short overview of each module available on the node and the related link to the module documentation. However, the security integration is discussed in the next section.

DIS-HLSClient

The DIS-HLSClient is a Java library that allows to query the DIS in order to retrieve any information handled there (i.e. WS-ResourceProperties and DILIGENT resource profiles). The latest version of the library is composed by a set of Managers, one per each logical section of the information your service wants to query. By requesting the appropriate Manager (like the ones for DHNs data or the WS-ResourceProperties), it is possible to query the a subset of the information available with better performances than the previous versions. However, a generic Manager is also available to perform queries on the whole information available on the DIS. It is of course less efficient w.r.t. the specialized ones since, of course, it queries a bigger set of data.

Another thing to keep in mind when dealing with the DIS-HLSClient is the secure or non secure context. Each method of the library accepts two parameters (in addition to the others): a parameter instance of org.gridforum.jgss.ExtendedGSSCredential and a parameter instance of org.apache.axis.message.addressing.EndpointReferenceType. If a service is acting in a secure DL, then it has to pass to each method of the library the credentials it is actually using to contact other secure services. By analysing such credentials, the DIS-HLSClient is able to understand the DL in which the service is actually acting on and therefore appropriately filters the queries in order to retrieve only the information belonging to that DL. On the other hand, if a Running Instance is acting in a non secure DL, it has to pass its current EndPointReference from which the DIS-HLSClient understands the DL and, again, filters the queries by minding on the DL context. See DL context to understand how a Ri can identify the type of its current DL.

For a complete documentation of the DIS-HLSClient see here.

DIS-IP

The DIS-IP is a Java library used to feed the DILIGENT Information System with the information needed to allow the discovering of the local RIs and their state and the DHN itself in the infrastructure. We can classify the information published in:

DILIGENT Resource profiles:
- Profiles in DILIGENT are XML documents that describe one of the identified DILIGENT Resources needed to set up a DL (). Services managing such resources can use the DIS-IP methods to publish their profiles on the DIS. For more information about the profiles see DILIGENT Resources and profiles.

WS-ResourceProperties:
- A Running Instance typically wants to publish a view of its current state in the DILIGENT Information system in order to allow others to distinguish the RI or one of its WS-Resources among the others available on the infrastructure. In the WSRF world, this is achieved by exposing WS-ResourceProperties. The DIS-IP allows to register such properties as Aggregator Source and in this way the DIS is able to automatically harvest them and made them available to the appropriate DIS-HLSClient's Manager.

As for the DIS-HLSClient, the DIS-IP needs to detect the current DL and it follows the same approach. Therefore, its methods accept both the org.gridforum.jgss.ExtendedGSSCredential and th org.apache.axis.message.addressing.EndpointReferenceType parameters. Then, it is up to the RI to pass the correct one depending on the DL context.

For a complete documentation of the DIS-IP see here.

DILIGENTProvider

The DILIGENTProvider is an operation provider (a sort of implementation by delegation) that plugs some "system-level" WS-ResourceProperties to the ones published by a Running Instance in order to have a correct management of them in the DIS. Its implementation is mandatory when a service plans to publish its state in the DIS since its PropertySet is requested by the DIS-IP.

For a complete documentation about how to plug the provider in a service see here.

NAL

The Node Access Library is a Java library available on each DHN allowing services to access to the local DHN configuration. Via this library, a DILIGENT service can understand its context. A number of methods here allow to retrieve RI, DHN, DL and VO information.

For a complete documentation about the NAL libray see here.

Configure the HNMService

The HNMService is the service in charge of the management of a DHN. This mainly means that it is responsible for the deployment/undeployment operations on the node and for the production of the DHN profile. For the latter activity, HNMService is able to detect most of the characteristics of the node, but, some of them have to be configured manually at DHN installation time.

JNDI file

The HNMService performs JNDI lookups for some static configuration parameters. Its JNDI file is located in $GLOBUS_LOCATION/etc/org_diligentproject_keeperservice_hnm/jndi-config.xml

The global resource HNMServiceConfiguration groups the configuration parameters. The following ones have to be changed accordingly to the suggestions reported:

infrastructure This parameter specify the type of infrastructure to join:
- PPS: the PPS infrastructure (in case the DHN has to join Arte or ImpECt VOs)
- development: the development infrastructure (in case the DHN has to join the devsec VO)

The default value is PPS.

defaultVO
- This parameter has to be filled with the name of the VO in which the DHN will act. This is the Default VO where the DHN and all the hosted RIs will be published as default behavior. The DHN is pre-configured to work in three different VOs (ARTE, ImpECt and Development) or in the root VO (named diligent). One of the followings has to be specified as default VO value:
  - /diligent → to join only the global DILIGENT VO
  - /diligent/ARTE → to join the ARTE VO (working in the pre-production infrastructure)
  - /diligent/ImpECt → to join the ImpECt VO (working in the pre-production infrastructure)
  - /diligent/devsec → to join the Secure Development VO (working in the development infrastructure)

The default value is /diligent.

DHNProfileUpdateIntervalInMillis
- the DHN profile is updated accordingly to this interval. The interval is specified as milliseconds.
latitude + longitude
- these two coordinates are used to correctly place the DHN on the Google Map visualized by the Monitoring Portlet. To discover which are the coordinates for the DILIGENT partner DHNs see here
country: two letter code of the country (e.g. IT)
location: a free text placeholder (e.g. Pisa)
localFileSystem
- the partition on your file system that you want to share with the hosted services
DHNType
- allowed values here are: Dynamic, Static and SelfCleaning. A static DHN is not used as target for the dynamic deployment, while a SelfCleaning is automatically cleaned every night (used just for demos). The default value is Dynamic.
securityEnabled
- if true, the DHN supports a secure context both at VO and DL level. In this case, it is necessary to

configure the DHN following the instructions reported here
overwrite the $GLOBUS_LOCATION/etc/org_diligentproject_keeperservice_hnm/deploy-server.wsdd with the $GLOBUS_LOCATION/etc/org_diligentproject_keeperservice_hnm/deploy-server.wsdd_SEC

rootDHN
- state if the DHN is a root DHN or not (the root DHNs are special nodes dedicated to the VO management)

There are other parameters in the resource and they have to be left with their default values.

DHN static description file

The DHN profile can be enriched with some static labels that describes the DHN characteristics. These labels are matched at deployment time with the ones reported . Such labels can be added to the $GLOBUS_LOCATION/etc/org_diligentproject_keeperservice_hnm/customDHNlabels.xml file.

VOMap files

A VO Map is a file placed in the $GLOBUS_LOCATION/etc/org_diligentproject_keeperservice_hnm/VOMaps folder reporting all the basic EPRs needed to properly startup a DHN. Such EPRs are the starting point to discover all the others gCube resource available in the VO.
An example of VO Map file can be found here
The file name has to follow a naming convention:

VOMap_<VO-name>.xml if the VO is not the root one in the current infrastructure
VOMap_<VO-name>_<infrastructure-name>.xml if the VO is the root one

Installation troubleshooting

In case something goes wrong in the restart of the Java WS Core container after an upgrade of the HNM Service, it is possible to source the $GLOBUS_LOCATION/etc/org_diligentproject_keeperservice_hnm/utils/cleanDHNstate.sh script. This script cleans up the DHN state and forces the HNM Service to rebuild the DHN state from scratch. The script has to be executed when the container is not running.

Integrating the Security

The support for service security includes:

the configuration of the java WS Core container security (see here)
the configuration of the service security (see here)
the interaction with other services using Secure Conversation (see here)
the interaction with the Delegation Service to obtain valid service credentials (see here)
the appropriate configuration of the service Tasks on the Credential Renewal Service (see here)

The DL context

Understand the DL in which a service is acting on is a fundamental step toward the intergration of such a service in DILIGENT. In fact, once deployed, a Running Instance of a service can be shared among multiple DLs and, depending on the current DL, it is able to see different resources and has different access rigths. The actual implementation of the Collective Layer supports two scenarios:

a non secure DL where the RIs are not shared with other DLs
a secure DL where the RIs can be shared among different DLs

A service has to be implemented by taking these two scenarios because it has to behave in a different way depending on the scenario in which it is acting on. In the following, we give some basic information about how to deal with the DL context.

Detect if your DL is secure or not

Therefore, the first problem to solve is to detect if the DL is secure or not. To do that, a method on the NAL library is available, boolean isDLSecure(String DLname).

Identify your DL

when the Security is enabled
→ the DL ID is available as attribute written in the proxy certificate the service has retrieved from the Delegation Service. The DIS-IP and DIS-HLSClient have to be invoked by passing the service credentials to their methods.
when the Security is not enabled
→ the DL is identified from the EPR of the Running Instance; in this case, the DL is pre-assigned at deployment time and it never changes during the RI lifetime. The DIS-IP and DIS-HLSClient have to be invoked by passing the EPR to their methods.

How to contact the RIs belonging to your DL

If a Running Instance detects that it is running in a non secure DL, it can contact the other RIs in the usual unauthenticated way. If it detects that the current DL has been created in a secure context, then it has to invoke the operations that other RIs have declared as authenticated (the information can be derived also from the Service Profile, where the service security descriptor has to be included, if any) in the way described here.