org.glite.data.transfer.fts
Interface FileTransfer

All Superinterfaces:
ServiceBase

public interface FileTransfer
extends ServiceBase

The service interface of the File Transfer component. It exposes all the required functionality to submit, manage and query transfer jobs, each containing one or many file transfers.


Method Summary
 void addVOManager(java.lang.String VOName, java.lang.String principal)
          Adds a manager to the given VO.
 void cancel(java.lang.String[] requestIDs)
          Attempt to cancel the given jobs on the service.
 FileTransferStatus[] getFileStatus(java.lang.String requestID, int offset, int limit)
          Return the statuses of all the files with the given requestID.
 Roles getRoles()
          Returns the roles of the client on this service.
 JobStatus getTransferJobStatus(java.lang.String requestID)
          Get the summary state for the whole job.
 TransferJobSummary getTransferJobSummary(java.lang.String requestID)
          Returns a summary status of the job.
 JobStatus[] listRequests(java.lang.String[] inGivenStates, java.lang.String channelName)
          Return a list of jobIDs matching the given states on the given channel.
 java.lang.String[] listVOManagers(java.lang.String VOName)
          Lists managers of a given VO
 java.lang.String placementSubmit(PlacementJob job)
          Submits the placement job to the service.
 void removeVOManager(java.lang.String VOName, java.lang.String principal)
          Removes a manager from the given VO.
 void setJobPriority(java.lang.String requestID, int priority)
          Update the priority of the job in the queue.
 java.lang.String submit(TransferJob job)
          Deprecated. Renamed transferSubmit(TransferJob). Placement (logical) jobs should go through the placementSubmit(PlacementJob) method.

Semantic description of the method:
The following steps are performed for each entry:
 java.lang.String transferSubmit(TransferJob job)
          Submits the transfer job to the service.
 
Methods inherited from interface org.glite.data.transfer.ServiceBase
getInterfaceVersion, getSchemaVersion, getServiceMetadata, getVersion
 

Method Detail

placementSubmit

public java.lang.String placementSubmit(PlacementJob job)
                                 throws InvalidArgumentException,
                                        AuthorizationException,
                                        ServiceBusyException,
                                        InternalException
Submits the placement job to the service. The job may be rejected because the service has stopped accepting transfer jobs, because the job description is malformed, or because the client is not authorized for some of the files. The job's state is updated to SUBMITTED upon the service.

Parameters:
job - The description of the files to transfer.
Returns:
The request ID (the same as input parameter).
Throws:
InvalidArgumentException - in the case of job being malformed.
AuthorizationException - in the case of the user not being authorized to submit a job.
InternalException - in the case of internal server errors (like the database being offline)
ServiceBusyException - in the case of the service being temporarily unable to handle the request (queue full, being drained).

Semantic description of the method:
The following steps are performed for each entry:

transferSubmit

public java.lang.String transferSubmit(TransferJob job)
                                throws InvalidArgumentException,
                                       AuthorizationException,
                                       ServiceBusyException,
                                       InternalException
Submits the transfer job to the service. The job may be rejected because the service has stopped accepting transfer jobs, because the job description is malformed, or because the client is not authorized for some of the files. The job's state is updated to SUBMITTED upon the service.

Parameters:
job - The description of the files to transfer.
Returns:
The request ID (the same as input parameter).
Throws:
InvalidArgumentException - in the case of job being malformed.
AuthorizationException - in the case of the user not being authorized to submit a job.
InternalException - in the case of internal server errors (like the database being offline)
ServiceBusyException - in the case of the service being temporarily unable to handle the request (queue full, being drained).

Semantic description of the method:
The following steps are performed for each entry:

submit

public java.lang.String submit(TransferJob job)
                        throws InvalidArgumentException,
                               AuthorizationException,
                               ServiceBusyException,
                               InternalException
Deprecated. Renamed transferSubmit(TransferJob). Placement (logical) jobs should go through the placementSubmit(PlacementJob) method.

Semantic description of the method:
The following steps are performed for each entry:

Submits the transfer job to the service. The job may be rejected because the service has stopped accepting transfer jobs, because the job description is malformed, or because the client is not authorized for some of the files. The job's state is updated to SUBMITTED upon the service.

Parameters:
job - The description of the files to transfer.
Returns:
The request ID (the same as input parameter).
Throws:
InvalidArgumentException - in the case of job being malformed.
AuthorizationException - in the case of the user not being authorized to submit a job.
InternalException - in the case of internal server errors (like the database being offline)
ServiceBusyException - in the case of the service being temporarily unable to handle the request (queue full, being drained).

listRequests

public JobStatus[] listRequests(java.lang.String[] inGivenStates,
                                java.lang.String channelName)
                         throws InvalidArgumentException,
                                AuthorizationException,
                                ServiceBusyException,
                                InternalException
Return a list of jobIDs matching the given states on the given channel.

Parameters:
inGivenStates - states to match
channelName - the channel name to match, if null, empty, or 'any', any channel will be matched.
Returns:
JobState listing the jobIDs and their associated states
Throws:
InvalidArgumentException - in the case of an unknow state request
AuthorizationException - in the case of the user not being authorized to request the state.
InternalException - in the case of internal server errors (like the database being offline)
ServiceBusyException - in the case of the service being temporarily unable to handle the request.
See Also:
JobStatus

getFileStatus

public FileTransferStatus[] getFileStatus(java.lang.String requestID,
                                          int offset,
                                          int limit)
                                   throws NotExistsException,
                                          ServiceBusyException,
                                          InternalException,
                                          AuthorizationException
Return the statuses of all the files with the given requestID. It has a limit and offset to allow chunked iteration through the file statuses for large jobs.

Parameters:
requestID - The requestID to obtain an Iterator over.
offset - the offset from the first file to return
limit - the number of files to return
Returns:
An array of FileTransferStatuses, one for each file
Throws:
NotExistsException - in the case of unknown requestID.
ServiceBusyException - in the case of the service being temporarily unable to handle the request.
AuthorizationException - in the case of unauthorized use.
InternalException - in the case of the service not being available for some internal reason.
See Also:
FileTransferStatus

getTransferJobStatus

public JobStatus getTransferJobStatus(java.lang.String requestID)
                               throws NotExistsException,
                                      InternalException,
                                      AuthorizationException,
                                      ServiceBusyException
Get the summary state for the whole job.

Parameters:
requestID - The job request ID.
Returns:
The state of the job.
Throws:
NotExistsException - in the case of unknown requestID.
AuthorizationException - in the case of unauthorized use.
InternalException - in the case of the service not being available for some internal reason.
ServiceBusyException - in the case of the service being temporarily unable to handle the request.
See Also:

Semantic description of the method:
The following steps are performed for each entry:
  • Check if the user is authorized to query the job;
    if permission is not granted, throws {@link org.glite.data.transfer.AuthorizationException}.
  • Checks if TransferJob ID is there;
    if it is not, throws {@link org.glite.data.transfer.NotExistsException}
  • Query the job state, return state.

getTransferJobSummary

public TransferJobSummary getTransferJobSummary(java.lang.String requestID)
                                         throws NotExistsException,
                                                InternalException,
                                                AuthorizationException,
                                                ServiceBusyException
Returns a summary status of the job. Including the job state and some summary statistics.

Parameters:
requestID - The job request ID.
Returns:
The summary of the job.
Throws:
NotExistsException - in the case of unknown requestID.
AuthorizationException - in the case of unauthorized use.
InternalException - in the case of the service not being available for some internal reason.
ServiceBusyException - in the case of the service being temporarily unable to handle the request.
See Also:

Semantic description of the method:
The following steps are performed for each entry:
  • Check if the user is authorized to query the job;
    if permission is not granted, throws {@link org.glite.data.transfer.AuthorizationException}.
  • Checks if TransferJob ID is there;
    if it is not, throws {@link org.glite.data.transfer.NotExistsException}
  • Query the job, return summary.

cancel

public void cancel(java.lang.String[] requestIDs)
            throws NotExistsException,
                   InternalException,
                   AuthorizationException,
                   ServiceBusyException,
                   CannotCancelException
Attempt to cancel the given jobs on the service.

The only semantics defined are 'best effort':
a) no roll back. Any file already transferred will be kept and not deleted;
b) any file currently transferring will complete and will not be deleted.
c) Any files pending will be cancelled and will not be transferred. Cancel has different semantics in case of the current job state:

Parameters:
requestIDs - The job request IDs.
Throws:
NotExistsException - in the case of unknown requestID.
AuthorizationException - in the case of unauthorized use.
CannotCancelException - in the case of the job state being not cancellable.
InternalException - in the case of the service not being available for some internal reason.
ServiceBusyException - in the case of the service being temporarily unable to handle the request.

Semantic description of the method:
The following steps are performed for each entry:
  • Check if the user is authorized to query the job;
    if permission is not granted, throws AuthorizationException.
  • Checks if TransferJob ID is there;
    if it is not, throws NotExistsException
  • Query the job, return summary.

setJobPriority

public void setJobPriority(java.lang.String requestID,
                           int priority)
                    throws AuthorizationException,
                           NotExistsException,
                           InvalidArgumentException,
                           ServiceBusyException,
                           InternalException
Update the priority of the job in the queue. This operation should be performed by ADMIN and VO MANAGER users. The priority value should be between 0 and 5.

Parameters:
requestID - The id of the job to set the priority
priority - The new priority for the job (value between 0 and 5)
Throws:
NotExistsException - in the case of unknown requestID.
AuthorizationException - in the case of unauthorized use.
InvalidArgumentException - in the case of an invalid priority being given.
InternalException - in the case of the service not being available for some internal reason.
ServiceBusyException - in the case of the service being temporarily unable to handle the request.

addVOManager

public void addVOManager(java.lang.String VOName,
                         java.lang.String principal)
                  throws AuthorizationException,
                         InvalidArgumentException,
                         NotExistsException,
                         ExistsException,
                         InternalException
Adds a manager to the given VO.

Parameters:
VOName - the name of the vo on which to add the manager
principal - the principal to be added as a manager
Throws:
AuthorizationException
InvalidArgumentException
NotExistsException
ExistsException
InternalException

removeVOManager

public void removeVOManager(java.lang.String VOName,
                            java.lang.String principal)
                     throws AuthorizationException,
                            InvalidArgumentException,
                            NotExistsException,
                            InternalException
Removes a manager from the given VO.

Parameters:
VOName - the name of the vo from which to remove the manager
principal - the principal to be removed
Throws:
AuthorizationException
InvalidArgumentException
NotExistsException
InternalException

listVOManagers

public java.lang.String[] listVOManagers(java.lang.String VOName)
                                  throws AuthorizationException,
                                         InvalidArgumentException,
                                         NotExistsException,
                                         InternalException
Lists managers of a given VO

Parameters:
VOName - the name of the vo for which to list managers
Throws:
AuthorizationException
InvalidArgumentException
NotExistsException
InternalException

getRoles

public Roles getRoles()
               throws AuthorizationException,
                      InternalException
Returns the roles of the client on this service.

Returns:
A Roles object.
Throws:
AuthorizationException
InternalException


Copyright © 2004 EU-EGEE