Migrating GRAM from GT4.0

The 4.2.0 protocol has been changed to be WSRF 1.2, WSN 1.3 and WS Addressing 1.0 compliant. There is no backward compatibility between 4.2.0 and 4.0.

1. Admin - Migration Guide

1.1. Default local resource manager

In GRAM4 an administrator can configure a default local resource manager being used for job submission if the client did not specify any in a job submission request. Check section Defining a default local resource manager in the System Administrator's Guide for more information.

1.2. Audit Logging

The log4j configuration for audit logging in GRAM4 in 4.2 is slightly different compared to the 4.0 series. This involves log4j and database configuration changes. For the log4j configuration check section section Configure Log4j in the System Administrator's Guide for more information. For the database related changes check Configure the Database in JNDI in the System Administrator's Guide.

1.3. Job lifetime

An administrator can configure lifetime parameters for all jobs in GRAM4's JNDI configuration. In short these parameters restrict the maximum lifetime a client can set on a job, and the maximum time a job is kept in the container and thus in the persistence directory after the job had been fully processed. Check section Job Lifetime in the Execution key concepts and section Job lifetime configuration in the System Administrator's Guide for more information.

1.4. Local Java calls from GRAM4 to RFT

By default GRAM4 in the 4.0 series does Web Service invocations when calling RFT to perform staging and file cleanup. The default in GRAM4 in 4.2 is local java calls to significantly improve performance in jobs with staging and file cleanup. If GRAM4 is configured to use RFT in a separate machine local invocations are disabled. For more information check the section GRAM4 - RFT interaction in the System Administrator's Guide

1.5. Threads for SEG event processing

An administrator can configure the number of threads in the thread-pool that is responsible for handling scheduler events. The default size should be fine for all Scheduler Event Generators (SEGs) provided by Globus. It might be interesting for custom written SEGs. Check section Configuring thread-pools in the System Administrator's Guide for more information.

2. User - Migration Guide

2.1. Specification upgrade related changes

Due to the WSRF, WSN and WS-Adressing specification upgrade some namespaces changed. All occurences of the following old 4.0 namespaces must be updated to the new 4.2 namespaces.

4.04.2

http://schemas.xmlsoap.org/ws/2004/03/addressing

http://www.w3.org/2005/08/addressing

http://www.globus.org/namespaces/2004/10/gram/job

http://www.globus.org/namespaces/2008/03/gram/job

http://www.globus.org/namespaces/2004/10/rft

http://www.globus.org/namespaces/2008/04/rft

Additionally, in a job description the ReferenceProperties element must be renamed to ReferenceParameters.

The following shows a factoryEndpoint element of a 4.0 job description and a 4.2 job description:

# Endpoint in 4.0
<factoryEndpoint
  xmlns:gram="http://www.globus.org/namespaces/2004/10/gram/job"
  xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing">
  <wsa:Address>
    https://grid-w.ncsa.teragrid.org:8444/wsrf/services/ManagedJobFactoryService
  </wsa:Address>
  <wsa:ReferenceProperties>
    <gram:ResourceID>Fork</gram:ResourceID>
  </wsa:ReferenceProperties>
</factoryEndpoint>

# Endpoint in 4.2
<factoryEndpoint
  xmlns:gram="http://www.globus.org/namespaces/2008/03/gram/job"
  xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <wsa:Address>
    https://grid-w.ncsa.teragrid.org:8444/wsrf/services/ManagedJobFactoryService
  </wsa:Address>
  <wsa:ReferenceParameters>
    <gram:ResourceID>Fork</gram:ResourceID>
  </wsa:ReferenceParameters>
</factoryEndpoint>

2.2. Local resource manager

GRAM4 in 4.2 defines a default local resource manager which is used for job execution if the user did not explicitly specify one. A user however still can specify a local resource manager (LRM), e.g. if it's required that a job runs in a certain LRM. Check

2.3. Job Lifetime

globusrun-ws in 4.0 sets a default lifetime of 24h on a job if a user does not explicitly set it. In 4.2 a job will run to completion in any event if no lifetime is specified, i.e. it will not be terminated after 24h.

However, there are server-side settings define limits on an explicitly requested lifetime, and that determine what will happen to a completed job if no lifetime had been set. Check section Job Lifetime in the Execution key concepts and section Job Lifetime in the User's Guide for more information.

3. Developer - Migration Guide

3.1. Specification upgrade related changes

Due to the WSRF, WSN and WS-Adressing specification upgrade namespaces of many components have changed. Check section Specification upgrade related changes and the Java WS Core Migration guide for details.

3.2. Job termination

GRAM4 does not extend from the ImmediateResourceTermination port type anymore, i.e. the Destroy() operation is no longer available to synchronously destroy job resources. Instead GRAM4 offers an asynchronous Terminate() method that lets clients terminate jobs and destroy a job resource. Check the TerminateManagedJobPortType PortType in the section 'WSDL and Schema Definition' of the Developer's guide for details and section Job termination for explanations of the new termination interface.

3.3. Job lifetime

The Java API GramJob in 4.0 sets a default lifetime of 24h on a job if a developer does not explicitly set it. In 4.2 it will not be set and a job will run to completion in any event if no lifetime is specified, i.e. it will not be terminated after 24h.

However, there are server-side settings define limits on an explicitly requested lifetime, and that determine what will happen to a completed job if no lifetime had been set. Check section Job Lifetime in the Execution key concepts and section Job Lifetime in the User's Guide for more information.

3.4. Subscription resources

In GRAM4 in the 4.0 series a client had to destroy subscription resources before destroying a job if it subscribed for notifications in order to cleanup state on the server-side. In GRAM4 in 4.2 all subscription resources of a job resource are destroyed on the server-side automatically if a job resource is destroyed. There's no need to keep track of subscription resources anymore.

3.5. Default local resource manager

In GRAM4 an administrator can configure a default local resource manager (LRM) being used for job submission if the client did not specify any in a job submission request. To submit a job to the default local resource manager just don't put a ReferenceParameters element in the EndpointReference used to contact GRAM4's job factory service. By querying resource properties of GRAM4's factory service a client can find out which local resource manager is the default, or which LRM's are available on the server-side.

3.6. Client-side generated UUIDS for MultiJobs

In GRAM4 in GT 4.0 the client-side generated submission being set in CreateManagedJobInputType.JobID had been used as server-side job id for multi-jobs. In GRAM4 in 4.2 a UUID is created on the server-side to manage the job and the client-side generated ID will only be stored to enable reliable job submission. A client cannot use the self-generated id for any job operation besides a second submission call for multi-jobs anymore. See section Client-Side Generated Submission ID for more information about this.

3.7. API changes

3.7.1. Service

3.7.1.1. Namespace

All occurrences of http://www.globus.org/namespaces/2004/10/gram/job had been replaced by http://www.globus.org/namespaces/2008/03/gram/job.

3.7.1.2. ResourceProperties
  • {http://www.globus.org/namespaces/2008/03/gram/job/faults}fault from the ManagedJobPortType is an array instead of a single element now. All faults that happen during job processing will be added to that array.
  • New {http://www.globus.org/namespaces/2008/03/gram/job}availableLocalResourceManager All local resource managers that are configured in this GRAM4 instance.
  • New {http://www.globus.org/namespaces/2008/03/gram/job}jobTTLAfterProcessing Time in seconds a job resource will stay alive after a job finished processing in GRAM4 (including fileStageOut, fileCleanUp). When this time elapsed the job resource is destroyed and no longer be available for a client. A negative values means that the job resource will never be destroyed.
  • New {http://www.globus.org/namespaces/2008/03/gram/job}maxJobLifetime Max time in seconds a user can set as initial lifetime in job submission or in subsequent setTerminationTime calls. A negative value means that there is no limit.
3.7.1.3. State change notification topic

The QName of the topic that clients use to subscribe for job state change information changed to {http://www.globus.org/namespaces/2008/03/gram/job}stateChangeNotificationMessage. (In GRAM4 in 4.0 it was {http://www.globus.org/namespaces/2004/10/gram/job}state)

3.7.1.4. Job states

New values of the resource property {http://www.globus.org/namespaces/2008/03/gram/job/types}state: UserTerminateDone and UserTerminateFailed.

3.7.1.5. Fault types
  • {http://www.globus.org/namespaces/2008/03/gram/job/release}ResourceNotReleasedFaultType: thrown when a resource cannot not be released but it still exists.
  • {http://www.globus.org/namespaces/2008/03/gram/job/terminate}ResourceNotTerminatedFaultType: Thrown when a resource cannot not be terminated but still exists.
  • {http://www.globus.org/namespaces/2008/03/gram/job/faults}DelegatedCredentialDestroyFaultType: Thrown when a job resource is terminated with request to destroy delegated credentials, and the delegated credential can't be destroyed. This fault is also added to the job RP fault and part of a notification message if a delegated credential cannot be destroyed in asynchronous termination.
  • {http://www.globus.org/namespaces/2008/03/gram/job/faults}JobResourceExpiredFaultType: Added to the job RP fault and part of a notification message if a resource expired.
  • {http://www.globus.org/namespaces/2008/03/gram/job/faults}StagingTerminateFaultType: Added to the job RP fault and part of a notification message if termination of a running transfer at RFT as part of job termination failed.
  • {http://www.globus.org/namespaces/2008/03/gram/job/faults}LocalResourceManagerJobTerminateFaultType: Added to the job RP fault and part of a notification message if termination of a job at the local resource manager as part of job termination failed.
3.7.1.6. Job destruction

GRAM4 does no longer extend from the ImmediateResourceTermination port type, i.e. does no longer offer the Destroy method. Instead jobs must be terminated. See above description.

3.7.2. Client

3.7.2.1. Java client API: GramJob
  • There is a new method for job termination:

    boolean terminate(
       boolean destroyAfterCleanUp,
       boolean continueNotifying,
       boolean destroyDelegatedCredentials)
       throws ResourceUnknownFaultType, DelegatedCredentialDestroyFaultType,
              ResourceNotTerminatedFaultType
  • The methods destroy(), cancel() are kept for convenience and implemented to do calls to terminate() with following settings: Resource destruction after cleanup, no notifications about success or failure of termination, destruction of delegated credentials if GramJob did the delegation. These methods are marked as deprecated and will be removed in 4.4.
  • The method to set the duration of a job changed from

    public void setDuration(Date duration)

    to

    public void setDuration(int hours, int minutes)

    Check bug 5806 for details.

  • The default Axis stub timeout was extended from from 2min to 5min.
  • No more default lifetime of a job: If a client does not explicitly set a lifetime GramJob does not set it. The job will run to completion then. If GramJob delegates credentials and no lifetime of a job has been specified, the lifetime of the delegated credentials will not explicitly be set but the timeleft-value of the proxy will be used. If a lifetime is specified for a job the lifetime of the delegated credentials will be the same like the lifetime of the job.
  • The method GramJob.getFault() returns an array of FaultType objects instead of a single FaultType object.
  • The method isLocallyDestroyed() was removed because it didn't make sense with the new job termination anymore.
3.7.2.2. C client API