Programmatically Syncing with the Trust Fabric

[ GTS: Administrators Guide | Developers Guide | caGrid: Documentation Guides ]

Overview

SyncGTS provides a client API for programmatically syncing with the trust fabric. This allows developers to integrate SyncGTS into applications and other software projects.  This guide provides sample code for syncing with the trust fabric programmatically.

Prerequisites

Software

1. Install Java 6 SDK.
2. Install caGrid.

Create Sync Description File

SyncGTS is configured through an XML configuration file herein referred to as the Sync Description. The default Sync Description file can be found in SYNC_GTS_HOME/ext/resource/sync-description.xml.  SyncGTS is pre-configured to work with the Target Grid specified during installation and in most cases does not need to be modified.

Install Trust Root(s)

In order for SyncGTS to sync with a GTS service, it is required that the local environment trust the GTS service with which it will be synced. In other words, Globus must trust the certificate authority that issued the GTS Service's credentials. Globus can be configured to trust a certificate authority by placing a copy of the certificate authority's certificate in the directory USER_HOME/.globus/certificates.  The file copied must be in PEM format and have a .[0-9] extension.  For example if your CA's certificate is named cacert.pem, then is must be copied to USER_HOME/.globus/certificates as cacert.0 .

SyncGTS is pre-configured to trust the Trust Fabric Certificate Authority of the Target Grid you specified during installation.  The default trust roots are contained in the directory SYNC_GTS_HOME/ext/resources/certificates.  If the GTS you are syncing with has credentials issued by one of the default trust roots, you MUST copy the contents of SYNC_GTS_HOME/ext/resources/certificates to USER_HOME/.globus/certificates.

Syncing With the Trust Fabric (Once)

The example code below syncs with the trust fabric once using a specified SyncDescription:

import gov.nih.nci.cagrid.common.Utils;
import gov.nih.nci.cagrid.syncgts.bean.SyncDescription;
import gov.nih.nci.cagrid.syncgts.core.SyncGTS;

import java.io.File;


public class SyncGTSExample {

    public void syncWithTrustFabric(File syncDescription) throws Exception {
        // Load Sync Description

        String pathToSyncDescription = "sync-description.xml";
        SyncDescription description = (SyncDescription) Utils.deserializeDocument(pathToSyncDescription,
            SyncDescription.class);

        // Sync with the Trust Fabric Once

        SyncGTS.getInstance().syncOnce(description);
    }

}

Syncing With the Trust Fabric (Repeatedly)

The example code below syncs with the trust fabric repeatedly in the background using a specified SyncDescription:

import gov.nih.nci.cagrid.common.Utils;
import gov.nih.nci.cagrid.syncgts.bean.SyncDescription;
import gov.nih.nci.cagrid.syncgts.core.SyncGTS;

import java.io.File;


public class SyncGTSExample {

    public void syncWithTrustFabric(File syncDescription) throws Exception {
        // Load Sync Description

        String pathToSyncDescription = "sync-description.xml";
        SyncDescription description = (SyncDescription) Utils.deserializeDocument(pathToSyncDescription,
            SyncDescription.class);

        // Sync with the Trust Fabric Repeatedly

        SyncGTS.getInstance().syncAndResyncInBackground(description, false);
    }

}