Proficiency in developing, deploying, and invoking grid services with Introduce is critical to successful use of the caGrid Transfer Tools; they are simple extensions to the normal service generation process.
Information and tutorials are available on the Introduce web site. We recommend you take the Introduce 1.2 tutorial and familiarize yourself with the Transfer Service Architecture. An example service, which is detailed in the guide below, can be found here.
In Introduce, add the caGrid_Transfer extension to your service to utilize Grid Transfer. Prior to service generation, this is found in the Advanced tab of the creation panel. After the service has been generated, select caGrid_Transfer in the Extensions tab as shown in the image below:
Using Introduce, you create a new Operation on your service in the usual manner (either on the main service or on a service context). The screenshot below shows the user creating a new operation on the main service context named "getSomeData". This operation returns a TransferServiceContextReference.
On the client side, if a method from your service utilized the TransferServiceHelper to locally stage data, and returned the type TransferServiceContextReference, the TransferServiceContextClient and TransferClientHelper can be used to retrieve the data on the client. Below is a client example of how this can be executed in an insecure environment:
Again, in a secure environment:
You can always use the secure method of retrieving data, but if the connection URL is http then the credentials will not be used, and regular sockets will be used to retrieve the data.
Code inside the service is straightforward: when the user calls a method you created (i.e. getSomeData()) that you provided them, your service must find their data, create the TransferContextResourceReference, and return the reference. Once the user has received the data, they can call destroy() on the resource. An example:
The caGrid Transfer service can also be used to upload data from client to service. The service, as in the download case, must provide a method which returns an TransferServiceContextReference. Thay can do this by using the TransferServiceHelper API, except, in this case they will call the createTransferContext(DataDescriptor dd) operation. This operation does not take any data in, as the intent is that the data is staged in by something else, however, it does generate the resource and reserve a url where that data can be written and then eventually stored on the local machine. Below is an example of how the client is to use the TransferServiceContextClient and TransferClientHelper in order to upload data to grid service so that it can be used:
Again, in a secure environment:
Again, as described before, you can always use the secure method of retrieving data but if the connection URL is http, the credentials will not be use and regular sockets will be used to upload the data.
When a user calls the createTransfer method that you provided, the TransferContextResourceReference is created, a DataStagedCallback is registered, and the reference is returned. Once the the data is uploaded and the setStatus operation is called on the resource (to let the resource know that the data is staged), the DataStagedCallback that was registered with the resource will be executed. This allows your implementation to process the uploaded data. An example of this code is as follows:
Note that the invocation of the DataStagedCallback is an asynchronous operation. That is, when the client calls tclient1.setStatus(Status.Staged), the call will return without waiting for the DataStagedCall function to complete its operation. On one hand, this implementation allows a client to proceed and overlap data staging operations with other client-side operations. On the other hand, if a client calls a service method that needs the data being uploaded, there is no guarantee that the DataStagedCall function will have completed before the client calls said service method. To address this issue, implement a checkUpload() service method, which will return false if the DataStagedCall function has not finished and true otherwise, and/or a waitUpload() service method, which will block until the DataStagedCall function finishes its process. To implement these functions, the service developer can use a service resource to monitor the state of the DataStagedCall function. An example is provided below:
A service resource class called MonitorUpload is created:
This class (represented in a XML schema) is registered as service resource while creating the service using the Introduce toolkit. The example putSomeData method should be modified as follows:
The two additional service methods could be implemented as follows:
The client would call these service methods if it wanted to check the upload or wait until the upload is completed.
When uploading data to a secure transfer service, it has been discovered that the DataStagedCallback object used to process the completed updoad might be destroyed by the Java garbage collector. Details about this issue can be located on the in the caGrid Issue Tracker on Gforge in Bug 22321.
A fix has been implemented for this bug and applied to the caGrid 1.4 source code, but has not been back-ported to caGrid 1.3. We recommend that you upgrade to Transfer 1.4 if you encounter this bug or need to use secure data uploads.
As of caGrid 1.2, the DataDescriptor constructor can take in an Object as the first parameter. Technically, anything that the service (and the transfer context specifically) knows how to serialize (as specified in both .wsdd files) can be handed to this constructor to pass some metadata about the transfer to the client. In practice, this Object is a placeholder for a future iteration of the transfer service that will add in standardized support for describing the Transfer streams. At this time, it is not recommended to put anything other than null in the constructor, because a new client of your service would not have the beans and type descriptor files to be able to retrieve your metadata without customizing their client.
However, if you would like to customize the metadata on a Transfer context using a basic Axis type (such as a String or another basic type that is known to all service and doesn't require custom serialization), pass in the data to the server operation that creates the Transfer context. Then you can use this String in your DataDescriptor constructor to set a String descriptor (metadata) on the DataDescriptor object:
The client can retrieve this metadata when it receives the transfer context:
|Note that trying to set DataDescriptor fields client-side will NOT update the metadata value and data descriptor name for others. (i.e., the "set" methods on the DataDescriptor object, when used client-side, have no effect).|
The caGrid Transfer service MUST be deployed to the same container that the invoking grid service in deployed. Like all caGrid services, only Tomcat and JBoss are currently supported. Prior to deployment of caGrid Transfer, Globus must be deployed to the container, and (if desired) security configuration must be completed. This can be accomplished by the caGrid Installer, or manually by following the instructions provided by Globus.
After you have acquired caGrid and setup your container, you can deploy the caGrod Transfer Service. This is accomplished by entering the caGrid Transfer project directory. From the top of the caGrid release:Then deploy to either Tomcat or JBoss (tomcat example below):
Next, deploy your service by entering the services directory:
Then deploy to either Tomcat or JBoss (tomcat example below):