Class Gram

java.lang.Object
org.globus.gram.Gram

public class Gram extends Object
This is the main class for using the Globus GRAM API It implements all of the GRAM API functionality such as job submission, canceling, gatekeeper pinging, and job signaling. It also allows for callback registering and unregistering.
  • Field Details

    • logger

      private static org.apache.commons.logging.Log logger
    • callbackHandlers

      protected static Hashtable callbackHandlers
  • Constructor Details

    • Gram

      public Gram()
  • Method Details

    • gatekeeperConnect

      private static Socket gatekeeperConnect(GSSCredential cred, ResourceManagerContact rmc, boolean doDel, boolean limitedDelegation) throws GSSException, GramException
      Throws:
      GSSException
      GramException
    • checkProtocolVersion

      private static void checkProtocolVersion(int protocolVersion) throws GramException
      Throws:
      GramException
    • checkHttpReply

      private static void checkHttpReply(int code) throws GramException
      Parameters:
      code -
      Throws:
      GramException
    • getActiveJobs

      public static int getActiveJobs()
      Returns total number of jobs currently running for all credentials -- all callback handlers
      Returns:
      number of jobs running
    • getActiveJobs

      public static int getActiveJobs(GSSCredential cred)
      Returns number of jobs currently running for a specified credential (one credential one callback handler)
      Returns:
      number of jobs running for given credential
    • ping

      public static void ping(String resourceManagerContact) throws GramException, GSSException
      Performs ping operation on the gatekeeper with default user credentials. Verifies if the user is authorized to submit a job to that gatekeeper.
      Parameters:
      resourceManagerContact - resource manager contact
      Throws:
      GramException - if an error occurs or user in unauthorized
      GSSException
    • ping

      public static void ping(GSSCredential cred, String resourceManagerContact) throws GramException, GSSException
      Performs ping operation on the gatekeeper with specified user credentials. Verifies if the user is authorized to submit a job to that gatekeeper.
      Parameters:
      cred - user credentials
      resourceManagerContact - resource manager contact
      Throws:
      GramException - if an error occurs or user in unauthorized
      GSSException
    • request

      public static void request(String resourceManagerContact, GramJob job) throws GramException, GSSException
      Submits a GramJob to specified gatekeeper as an interactive job. Performs limited delegation.
      Parameters:
      resourceManagerContact - resource manager contact
      job - gram job
      Throws:
      GramException - if an error occurs during submisson
      GSSException
    • request

      public static void request(String resourceManagerContact, GramJob job, boolean batchJob) throws GramException, GSSException
      Submits a GramJob to specified gatekeeper as a interactive or batch job. Performs limited delegation.
      Parameters:
      resourceManagerContact - resource manager contact
      job - gram job
      batchJob - true if batch job, interactive otherwise
      Throws:
      GramException - if an error occurs during submisson
      GSSException
    • request

      public static void request(String resourceManagerContact, GramJob job, boolean batchJob, boolean limitedDelegation) throws GramException, GSSException
      Submits a GramJob to specified gatekeeper as a interactive or batch job.
      Parameters:
      resourceManagerContact - resource manager contact
      job - gram job
      batchJob - true if batch job, interactive otherwise.
      limitedDelegation - true for limited delegation, false for full delegation. limited delegation should be the default option.
      Throws:
      GramException - if an error occurs during submisson
      GSSException
    • jmConnect

      private static GatekeeperReply jmConnect(GSSCredential cred, GlobusURL jobURL, String msg) throws GramException, GSSException
      Throws:
      GramException
      GSSException
    • produceRenewToken

      private static byte[] produceRenewToken(ExtendedGSSContext c, byte[] token) throws GSSException
      Frames and wraps a token according to the GRAM "renew" protocol for use in a GSI delegation handshake. The input token is framed with a 4 byte big-endian token length header, and the resulting framed token wrapped in SSL mode (GSSContext's GSS_MODE option set to MODE_SSL)
      Parameters:
      c - The context used to wrap the token
      token - The unaltered output of the context's initDelegation
      Returns:
      a wrapped, framed token to send to globus job manager
      Throws:
      GSSException - if an error occurs during token wrapping or if context is insufficient
    • consumeRenewToken

      private static byte[] consumeRenewToken(ExtendedGSSContext c, byte[] wrappedToken) throws GSSException
      Unwraps and discards frame of a token according to the GRAM "renew" protocol for use in a GSI delegation handshake. The input token is received from a globus job manager and comes wrapped (SSL mode) and framed with a 4 byte big-endian token length header.
      Parameters:
      c - The context to use to unwrap the token
      wrappedToken - Token received from job manager during GSI handshake
      Returns:
      a token that can be passed to the context's next initDelegation
      Throws:
      GSSException - if an error occurs during token wrapping or if context is insufficient
    • renewDelegationHandshake

      private static GatekeeperReply renewDelegationHandshake(ExtendedGSSContext context, GSSCredential newCred, GSIGssOutputStream out, GSIGssInputStream in) throws GSSException, IOException
      Completes a GSI delegation handshake with a globus job manager that has agreed to a (previously sent) GRAM "renew" request. After the job manager receives the last token in the handshake, it responds with a message following the GRAM protocol indicating delegation success or failure.
      Parameters:
      context - Previously established context with job manager
      newCred - The credential used to generate a new delegated proxy
      out - Stream used to send messages to job manager
      in - Stream used to receive messages from job manager
      Returns:
      the GRAM response message indicating delegation status
      Throws:
      GSSException - if an error occurs during token wrapping/unwrapping
      IOException - if a communication error occurs
    • renew

      public static void renew(GramJob job, GSSCredential newCred) throws GramException, GSSException
      Requests that a globus job manager accept newly delegated credentials. Uses limited delegation.
      Parameters:
      job - The job whose credentials are to be renewed/refreshed
      newCred - The credentials to use in the delegation process
      Throws:
      GSSException - if a GSSAPI error occurs
      GramException - if a connection/communication error occurs or if delegation failed
    • renew

      public static void renew(GramJob job, GSSCredential newCred, boolean limitedDelegation) throws GramException, GSSException
      Requests that a globus job manager accept newly delegated credentials. This consists of a "renew" message in the GRAM protocol followed by a GSI delegation handshake using wrapped/framed tokens. Upon successful delegation, the job's credentials are set to the ones used in delegation.
      Parameters:
      job - The job whose credentials are to be renewed/refreshed
      newCred - The credentials to use in the delegation process
      limitedDelegation - Whether to use a full or limited proxy
      Throws:
      GSSException - if a GSSAPI error occurs
      GramException - if a connection/communication error occurs or if delegation failed
    • cancel

      public static void cancel(GramJob job) throws GramException, GSSException
      This function cancels an already running job.
      Parameters:
      job - job to be canceled
      Throws:
      GramException - if an error occurs during cancel
      GSSException
    • jobStatus

      public static void jobStatus(GramJob job) throws GramException, GSSException
      This function updates the status of a job (within the job object), and throws an exception if the status is not OK. If the job manager cannot be contacted the job error code is set to GramException.ERROR_CONTACTING_JOB_MANAGER and an exception with the same error code is thrown.
      Parameters:
      job - the job whose status is to be updated.
      Throws:
      GramException - if an error occurs during status update.
      GSSException
    • jobSignal

      public static int jobSignal(GramJob job, int signal, String arg) throws GramException, GSSException
      This function sends a signal to a job.
      Parameters:
      job - the signaled job
      signal - type of the signal
      arg - argument of the signal
      Throws:
      GramException - if an error occurs during cancel
      GSSException
    • registerListener

      public static void registerListener(GramJob job) throws GramException, GSSException
      This function registers the job for status updates.
      Parameters:
      job - the job
      Throws:
      GramException - if an error occurs during registration
      GSSException
    • registerListener

      public static void registerListener(GramJob job, CallbackHandler handler) throws GramException, GSSException
      Throws:
      GramException
      GSSException
    • unregisterListener

      public static void unregisterListener(GramJob job) throws GramException, GSSException
      This function unregisters the job from callback listener. The job status will not be updated.
      Parameters:
      job - the job
      Throws:
      GramException - if an error occurs during unregistering
      GSSException
    • unregisterListener

      public static void unregisterListener(GramJob job, CallbackHandler handler) throws GramException, GSSException
      Throws:
      GramException
      GSSException
    • deactivateAllCallbackHandlers

      public static void deactivateAllCallbackHandlers()
      Deactivates all callback handlers.
    • deactivateCallbackHandler

      public static CallbackHandler deactivateCallbackHandler(GSSCredential cred)
      Deactivates a callback handler for a given credential.
      Parameters:
      cred - the credential of the callback handler.
      Returns:
      the callback handler that was deactivated. Null, if no callback handler is associated with the credential
    • initCallbackHandler

      private static CallbackHandler initCallbackHandler(GSSCredential cred) throws GSSException, GramException
      Throws:
      GSSException
      GramException
    • getJobCredentials

      private static GSSCredential getJobCredentials(GramJob job) throws GSSException
      Throws:
      GSSException
    • debug

      private static void debug(String header, GatekeeperReply reply)
      Debug function for displaying the gatekeeper reply.
    • debug

      private static void debug(String header, HttpResponse response)
      Debug function for displaying HTTP responses.
    • debug

      private static void debug(String header, String msg)
      A general debug message that prints the header and msg when the debug level is smaler than 3
      Parameters:
      header - The header to be printed
      msg - The message to be printed