GT 4.0 Component Guide to Public Interfaces: Data Replication Service (DRS)

Table of Contents

1. Semantics and syntax of APIs
1.1. Programming Model Overview
1.2. Component API
2. Semantics and syntax of the WSDL
2.1. Protocol overview
2.2. Operations
2.3. Resource properties
2.4. Faults
2.5. WSDL and Schema Definition
3. Command-line tools
4. Overview of Graphical User Interface
4.1. Overview of the purpose and functionality of the GUI
4.2. Command and options
4.3. Limitations
5. Semantics and syntax of domain-specific interface
5.1. Interface introduction
5.2. Syntax of the interface
6. Configuration interface
7. Environment variable interface

1. Semantics and syntax of APIs

1.1. Programming Model Overview

The DRS is a WS-RF compliant service implemented using the Globus Java WS Core. It exposes a set of Resource Properties and operations to allow users to create replication resources, control replication resources' lifecycle, and inspect the state of replication resources' activities along with the success or failure of individual replicated data sets. In this release, the WSDL and the command-line clients are the primary public interfaces for developers. Two java interfaces exist on the service-side to allow developers and users to modify the source selection behavior of the DRS. These interfaces allow users to chose alternate schemes to select sources beyond the random selection provided by default.

1.2. Component API

Interfaces to influence source selection include:

  • ReplicaCatalogFilter
  • SourceSelector

Please see service-side interfaces for documentation on these interfaces.

2. Semantics and syntax of the WSDL

2.1. Protocol overview

The DRS provides a set of Resource Properties and SOAP operations to create, manipulate and inspect replication activities. Users will begin by creating a replication resource (AKA "Replicator") by invoking the create operation and passing it a URL of the replication request file (described in the domain-specific interface section). Users may start, stop, suspend and resume the Replicator when necessary. Typically a user is expected to simply start the resource and allow it to run through completion. During and after the course of replication activities performed by the resource, users may invoke standard "get resource property" and DRS-specific "find" operations to inspect the state of the resource. When the resource finishes the replication activities and the user has satisfactorily inspected the resource state, the resource should be destroyed using the standard "destroy" operation.

2.2. Operations

Supported operations include:

  • createReplicator creates the "Replicator" resource.

    • [in] InitialTerminationTime The requested initial termination time for the resource.

    • [in] requestFileRequest The request-file style request.

      • credentialEPR Endpoint Reference of the user's delegated credential.
      • options Replication options which include a set of options pertinent to the transfer stage of the request, such as concurrency, parallel streams, tcp buffer size, etc.
      • autostart A Boolean flag indicating whether the resource should be automatically started following resource creation.
      • requestFileUri The URI of the request file. Currently supported schemes include http, file, and ftp.
      • format The request file format (domain-specific). Currently, the service only supports a simple "Table" format.
    • [out] EPR The Endpoint Reference of the Replicator resource.
    • [fault] fault Indicates a general failure when attempting to create the Replicator resource.

  • start starts the resource.

    • [fault] invalidStateFault Indicates the resource is in an invalid state to perform the operation.

  • stop stops the resource.

    • [fault] invalidStateFault Indicates the resource is in an invalid state to perform the operation.

  • suspend suspends the resource.

    • [fault] invalidStateFault Indicates the resource is in an invalid state to perform the operation.

  • resume resumes the resource.

    • [fault] invalidStateFault Indicates the resource is in an invalid state to perform the operation.

  • findItems Finds state information for individual replication items.

    • [in] byUri Finds by replication URI (currently, this value must be the logical filename, LFN, rather than a properly formed URI). This param is mutually-exclusive with byStatus.
    • [in] byStatus Find by status, which includes Pending, Finished, Failed, and Terminated. This param is mutually-exclusive with byUri.
    • [in] offset An offset into the results set.
    • [in] limit A limit of results to be returned to the client.
    • [out] items An array of items to be returned to the client as a result of the find operation. Each item in the array contains the complete status of the replication item including its identifier, priority, status, error (if any), sources, and destinations.
    • [fault] internalErrorFault Indicates that an internal error occurred.

2.3. Resource properties

Supported resource properties for DataRep include:

  • status: The status of the resource, such as Pending, Active, Suspended, Terminated, Destroyed, etc.
  • stage: The current stage or activity of the resource, such as Discover, Transfer, and Register.
  • result: The final result (if any) of the resource, such as Finished, Failed, and Exception.
  • errorMessage: A verbose description of an error (if any) encountered by the resource. The message may include error or exception information returned by one of the dependent components, such as RLS or RFT.
  • count: An element containing counts of individual replication items pertaining to total, finished, failed, and terminated replication items.

2.4. Faults

Supported faults include:

  • CreateReplicatorFault Indicates that the service failed to create the Replicator resource.
  • RequestBodyMissingFault Indicates that the request body of the create message parameters was missing.
  • CredentialEprMissingFault Indicates that the delegated credential EPR was missing from the create message.
  • InvalidStateFault Indicates that the requested lifecycle operation (e.g., start, stop, suspend, resume) was performed on a resource that was not in the proper state for the operation to succeed (e.g., performing a resume operation on a non-suspended Replicator resource).
  • InternalErrorFaultType Indicates that an internal error occurred (e.g., internal system failure, etc.).

2.5. WSDL and Schema Definition

For more information, please see the Replicator Port Type or the complete list of schemas.

3. Command-line tools

Please see the GT 4.0 DRS Command-line Reference.

4. Overview of Graphical User Interface

4.1. Overview of the purpose and functionality of the GUI

The DRS does not provide a GUI interface.

4.2. Command and options

Not available

4.3. Limitations

Not available

5. Semantics and syntax of domain-specific interface

5.1. Interface introduction

The DRS domain-specific interface defines the structure and expected contents of a request file used when creating a replication resource. When the client invokes the create operation of the DRS, it will be expected to submit a properly formatted request file. It is important to understand the structure of the request file and to ensure that the file is well-formed.

5.2. Syntax of the interface

For the present release, the DRS request file format is fairly trivial. The request file is structured as a "Table" style of rows and columns of text. Each row represent a requested replication item described in two columns. The first column contains the identifier of the data set which will be discovered and replicated. The identifier must be resolvable by the Replica Location Index (see the JNDI configuration for defaultIndexUrl). In most cases, it is expected that the identifier be a Logical Filename (LFN) per the Replica Location Service definition. The second column of the row contains the URL of the "destination" for the replication item. The two columns must be delimited by a TAB character and each row must be delimited by an EOL character.

[Note]Note

The service will not accept SPACE characters as a substitute for the TAB character.

The following example shows the output of a small request file.

% cat example.req
my-lfn-1        gsiftp://myhost:9001/sandbox/examples/files/my-pfn-1
my-lfn-2        gsiftp://myhost:9001/sandbox/examples/files/my-pfn-2
my-lfn-3        gsiftp://myhost:9001/sandbox/examples/files/my-pfn-3
my-lfn-4        gsiftp://myhost:9001/sandbox/examples/files/my-pfn-4
my-lfn-5        gsiftp://myhost:9001/sandbox/examples/files/my-pfn-5

6. Configuration interface

Please see the GT 4.0 DRS Command-line Reference.

7. Environment variable interface

  • GLOBUS_LOCATION=/path/to/globus/install