Package org.globus.gram
Class Gram
- java.lang.Object
-
- org.globus.gram.Gram
-
public class Gram extends java.lang.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 Summary
Fields Modifier and Type Field Description protected static java.util.Hashtable
callbackHandlers
private static org.apache.commons.logging.Log
logger
-
Constructor Summary
Constructors Constructor Description Gram()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
cancel(GramJob job)
This function cancels an already running job.private static void
checkHttpReply(int code)
private static void
checkProtocolVersion(int protocolVersion)
private static byte[]
consumeRenewToken(ExtendedGSSContext c, byte[] wrappedToken)
Unwraps and discards frame of a token according to the GRAM "renew" protocol for use in a GSI delegation handshake.static void
deactivateAllCallbackHandlers()
Deactivates all callback handlers.static CallbackHandler
deactivateCallbackHandler(org.ietf.jgss.GSSCredential cred)
Deactivates a callback handler for a given credential.private static void
debug(java.lang.String header, java.lang.String msg)
A general debug message that prints the header and msg when the debug level is smaler than 3private static void
debug(java.lang.String header, GatekeeperReply reply)
Debug function for displaying the gatekeeper reply.private static void
debug(java.lang.String header, HttpResponse response)
Debug function for displaying HTTP responses.private static java.net.Socket
gatekeeperConnect(org.ietf.jgss.GSSCredential cred, ResourceManagerContact rmc, boolean doDel, boolean limitedDelegation)
static int
getActiveJobs()
Returns total number of jobs currently running for all credentials -- all callback handlersstatic int
getActiveJobs(org.ietf.jgss.GSSCredential cred)
Returns number of jobs currently running for a specified credential (one credential one callback handler)private static org.ietf.jgss.GSSCredential
getJobCredentials(GramJob job)
private static CallbackHandler
initCallbackHandler(org.ietf.jgss.GSSCredential cred)
private static GatekeeperReply
jmConnect(org.ietf.jgss.GSSCredential cred, GlobusURL jobURL, java.lang.String msg)
static int
jobSignal(GramJob job, int signal, java.lang.String arg)
This function sends a signal to a job.static void
jobStatus(GramJob job)
This function updates the status of a job (within the job object), and throws an exception if the status is not OK.static void
ping(java.lang.String resourceManagerContact)
Performs ping operation on the gatekeeper with default user credentials.static void
ping(org.ietf.jgss.GSSCredential cred, java.lang.String resourceManagerContact)
Performs ping operation on the gatekeeper with specified user credentials.private static byte[]
produceRenewToken(ExtendedGSSContext c, byte[] token)
Frames and wraps a token according to the GRAM "renew" protocol for use in a GSI delegation handshake.static void
registerListener(GramJob job)
This function registers the job for status updates.static void
registerListener(GramJob job, CallbackHandler handler)
static void
renew(GramJob job, org.ietf.jgss.GSSCredential newCred)
Requests that a globus job manager accept newly delegated credentials.static void
renew(GramJob job, org.ietf.jgss.GSSCredential newCred, boolean limitedDelegation)
Requests that a globus job manager accept newly delegated credentials.private static GatekeeperReply
renewDelegationHandshake(ExtendedGSSContext context, org.ietf.jgss.GSSCredential newCred, GSIGssOutputStream out, GSIGssInputStream in)
Completes a GSI delegation handshake with a globus job manager that has agreed to a (previously sent) GRAM "renew" request.static void
request(java.lang.String resourceManagerContact, GramJob job)
Submits a GramJob to specified gatekeeper as an interactive job.static void
request(java.lang.String resourceManagerContact, GramJob job, boolean batchJob)
Submits a GramJob to specified gatekeeper as a interactive or batch job.static void
request(java.lang.String resourceManagerContact, GramJob job, boolean batchJob, boolean limitedDelegation)
Submits a GramJob to specified gatekeeper as a interactive or batch job.static void
unregisterListener(GramJob job)
This function unregisters the job from callback listener.static void
unregisterListener(GramJob job, CallbackHandler handler)
-
-
-
Method Detail
-
gatekeeperConnect
private static java.net.Socket gatekeeperConnect(org.ietf.jgss.GSSCredential cred, ResourceManagerContact rmc, boolean doDel, boolean limitedDelegation) throws org.ietf.jgss.GSSException, GramException
- Throws:
org.ietf.jgss.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(org.ietf.jgss.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(java.lang.String resourceManagerContact) throws GramException, org.ietf.jgss.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 unauthorizedorg.ietf.jgss.GSSException
-
ping
public static void ping(org.ietf.jgss.GSSCredential cred, java.lang.String resourceManagerContact) throws GramException, org.ietf.jgss.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 credentialsresourceManagerContact
- resource manager contact- Throws:
GramException
- if an error occurs or user in unauthorizedorg.ietf.jgss.GSSException
-
request
public static void request(java.lang.String resourceManagerContact, GramJob job) throws GramException, org.ietf.jgss.GSSException
Submits a GramJob to specified gatekeeper as an interactive job. Performs limited delegation.- Parameters:
resourceManagerContact
- resource manager contactjob
- gram job- Throws:
GramException
- if an error occurs during submissonorg.ietf.jgss.GSSException
-
request
public static void request(java.lang.String resourceManagerContact, GramJob job, boolean batchJob) throws GramException, org.ietf.jgss.GSSException
Submits a GramJob to specified gatekeeper as a interactive or batch job. Performs limited delegation.- Parameters:
resourceManagerContact
- resource manager contactjob
- gram jobbatchJob
- true if batch job, interactive otherwise- Throws:
GramException
- if an error occurs during submissonorg.ietf.jgss.GSSException
-
request
public static void request(java.lang.String resourceManagerContact, GramJob job, boolean batchJob, boolean limitedDelegation) throws GramException, org.ietf.jgss.GSSException
Submits a GramJob to specified gatekeeper as a interactive or batch job.- Parameters:
resourceManagerContact
- resource manager contactjob
- gram jobbatchJob
- 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 submissonorg.ietf.jgss.GSSException
-
jmConnect
private static GatekeeperReply jmConnect(org.ietf.jgss.GSSCredential cred, GlobusURL jobURL, java.lang.String msg) throws GramException, org.ietf.jgss.GSSException
- Throws:
GramException
org.ietf.jgss.GSSException
-
produceRenewToken
private static byte[] produceRenewToken(ExtendedGSSContext c, byte[] token) throws org.ietf.jgss.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 tokentoken
- The unaltered output of the context's initDelegation- Returns:
- a wrapped, framed token to send to globus job manager
- Throws:
org.ietf.jgss.GSSException
- if an error occurs during token wrapping or if context is insufficient
-
consumeRenewToken
private static byte[] consumeRenewToken(ExtendedGSSContext c, byte[] wrappedToken) throws org.ietf.jgss.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 tokenwrappedToken
- Token received from job manager during GSI handshake- Returns:
- a token that can be passed to the context's next initDelegation
- Throws:
org.ietf.jgss.GSSException
- if an error occurs during token wrapping or if context is insufficient
-
renewDelegationHandshake
private static GatekeeperReply renewDelegationHandshake(ExtendedGSSContext context, org.ietf.jgss.GSSCredential newCred, GSIGssOutputStream out, GSIGssInputStream in) throws org.ietf.jgss.GSSException, java.io.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 managernewCred
- The credential used to generate a new delegated proxyout
- Stream used to send messages to job managerin
- Stream used to receive messages from job manager- Returns:
- the GRAM response message indicating delegation status
- Throws:
org.ietf.jgss.GSSException
- if an error occurs during token wrapping/unwrappingjava.io.IOException
- if a communication error occurs
-
renew
public static void renew(GramJob job, org.ietf.jgss.GSSCredential newCred) throws GramException, org.ietf.jgss.GSSException
Requests that a globus job manager accept newly delegated credentials. Uses limited delegation.- Parameters:
job
- The job whose credentials are to be renewed/refreshednewCred
- The credentials to use in the delegation process- Throws:
org.ietf.jgss.GSSException
- if a GSSAPI error occursGramException
- if a connection/communication error occurs or if delegation failed
-
renew
public static void renew(GramJob job, org.ietf.jgss.GSSCredential newCred, boolean limitedDelegation) throws GramException, org.ietf.jgss.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/refreshednewCred
- The credentials to use in the delegation processlimitedDelegation
- Whether to use a full or limited proxy- Throws:
org.ietf.jgss.GSSException
- if a GSSAPI error occursGramException
- if a connection/communication error occurs or if delegation failed
-
cancel
public static void cancel(GramJob job) throws GramException, org.ietf.jgss.GSSException
This function cancels an already running job.- Parameters:
job
- job to be canceled- Throws:
GramException
- if an error occurs during cancelorg.ietf.jgss.GSSException
-
jobStatus
public static void jobStatus(GramJob job) throws GramException, org.ietf.jgss.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.org.ietf.jgss.GSSException
-
jobSignal
public static int jobSignal(GramJob job, int signal, java.lang.String arg) throws GramException, org.ietf.jgss.GSSException
This function sends a signal to a job.- Parameters:
job
- the signaled jobsignal
- type of the signalarg
- argument of the signal- Throws:
GramException
- if an error occurs during cancelorg.ietf.jgss.GSSException
-
registerListener
public static void registerListener(GramJob job) throws GramException, org.ietf.jgss.GSSException
This function registers the job for status updates.- Parameters:
job
- the job- Throws:
GramException
- if an error occurs during registrationorg.ietf.jgss.GSSException
-
registerListener
public static void registerListener(GramJob job, CallbackHandler handler) throws GramException, org.ietf.jgss.GSSException
- Throws:
GramException
org.ietf.jgss.GSSException
-
unregisterListener
public static void unregisterListener(GramJob job) throws GramException, org.ietf.jgss.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 unregisteringorg.ietf.jgss.GSSException
-
unregisterListener
public static void unregisterListener(GramJob job, CallbackHandler handler) throws GramException, org.ietf.jgss.GSSException
- Throws:
GramException
org.ietf.jgss.GSSException
-
deactivateAllCallbackHandlers
public static void deactivateAllCallbackHandlers()
Deactivates all callback handlers.
-
deactivateCallbackHandler
public static CallbackHandler deactivateCallbackHandler(org.ietf.jgss.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(org.ietf.jgss.GSSCredential cred) throws org.ietf.jgss.GSSException, GramException
- Throws:
org.ietf.jgss.GSSException
GramException
-
getJobCredentials
private static org.ietf.jgss.GSSCredential getJobCredentials(GramJob job) throws org.ietf.jgss.GSSException
- Throws:
org.ietf.jgss.GSSException
-
debug
private static void debug(java.lang.String header, GatekeeperReply reply)
Debug function for displaying the gatekeeper reply.
-
debug
private static void debug(java.lang.String header, HttpResponse response)
Debug function for displaying HTTP responses.
-
debug
private static void debug(java.lang.String header, java.lang.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 printedmsg
- The message to be printed
-
-