Developing a Service

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.

After the DHN installation, the HNM configuration is located in the $GLOBUS_LOCATION/etc/org_diligentproject_keeperservice_hnm/jndi-config.xml under the HNMConfiguration resource. The parameters to configure are:

• country: two letter code of the country (e.g. IT)
• location: a freetext placeholder (e.g. Pisa)
• latitude: the latitude of your DHN to correctly place it on a Google Map
• longitude: the longitude of your DHN to correctly place it on a Google Map

The latter two parameters (latitude and longitude) to set for the DILIGENT partner DHNs can be found here

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.