1.1. srmPrepareToGet
1.1.1. NAME
In order to satisfy the requirements of the functional specifications with the SOAP based RPC protocol we made the following decisions on the srmPrepareToGet function:
srmPrepareToGet Requests will be created with the srmPrepareToGet SOAP operation described bellow. File Request desired lifetime will be specified as one of the parameters of the srmPrepareToGet call. Once the call is made, the user will get back RequestToken, which can used with srmStatusOfGetRequest operation to get the status of the request and file requests contained therein. Once the client received a status of file request that contains Transfer URL and performed the data transfer it can terminate the File Request with srmReleaseFiles operation. Client can extend the lifetime of the request with srmExtendLifetime operation. Client can abort whole request or some of the file requests anytime with srmAbortRequest and srmAbortFiles requests.
1.1.2. SYNOPSIS
srmPrepareToGet request is defined as a complex type in the XML Schema definition language.
|
Input |
srmPrepareToGetRequest |
|
Output |
srmPrepareToGetResponse |
<complexType name="srmPrepareToGetRequest">
������� <sequence>
�������� elements from the following table go in here�
��� </sequence>
</complexType>
<complexType name="srmPrepareToGetResponse">
������� <sequence>
�������� elements from the following table go in here�
��� </sequence>
</complexType>
|
Name |
type |
Min |
Max |
|
srmPrepareToGetRequest |
xsd:string�������� ���������� arrayOfGetFileRequest xsd:string������������������� authorizationID TArrayOfString��������� arrayOfTransferProtocols xsd:string������������������� userRequestDescription xsd:long��������������������� totalRetryTime xsd:boolean���������������� streaming TOverwriteMode������� overwriteMode xsd:long�������������������� �desiredLifetime TFileStorageType����� �sourceFileStorageType xsd:string� ������������������sourceStorageSystemInfo xsd:boolean������������� ��checksum |
1 0 0 0 0 0 0 0 0 0 0 |
1 1 1 1 1 1 1 1 1 1 1 |
|
srmPrepareToGetResponse |
TRequestStatus���������� requestStatus xsd:string������������������� requestToken |
1 0 |
1 1 |
�� <complexType name="TArrayOfString">
��� <sequence>
���� <element name="stringArray" minOccurs="0" maxOccurs="unbound" type="xsd:string"/>
��� </sequence>
�� </complexType>
�� <simpleType name="TOverwriteMode">
��� <restriction base="xsd:string">
���� <enumeration value="Never"/>
���� <enumeration value="Always"/>
���� <enumeration value="WhenFilesAreDifferent"/>
��� </restriction>
�� </simpleType>
�� <simpleType name="TFileStorageType">
��� <restriction base="xsd:string">
���� <enumeration value="Volatile"/>
���� <enumeration value="Durable"/>
���� <enumeration value="Permanent"/>
��� </restriction>
�� </simpleType>
arrayOfGetFileRequest is defined as a type in XSD Schema definition, and is passed as a string and parsed with schema definition. This format makes input strings flexible, and makes a room for site specific extra information as well as leaving out non-necessary information when they are not required. XSD schema for GetFileRequest is following:
<xs:element name="TGetFileRequests">
� <xs:complexType>
��� <xs:sequence>
������ <xs:element name="sourceSURL" type='xs:string'
����������� minOccurs="1" maxOccurs="1"/>
������ <xs:element name="desiredLifetime" type='xs:long'
����������� minOccurs="0" maxOccurs="1"/>
������ <xs:element name="sourceStorageSystemInfo" type='xs:string'
����������� minOccurs="0" maxOccurs="1"/>
������ <xs:element name="knownFileSize" type='xs:long'
����������� minOccurs="0" maxOccurs="1"/>
������ <xs:element name="IsSourceDirectory" type='xs:boolean'
����� ������minOccurs="0" maxOccurs="1"/>
����� �<xs:element name="recursiveDirectory" type='xs:boolean'
����������� minOccurs="0" maxOccurs="1"/>
������ <xs:element name="numDirectoryLevel" type='xs:long'
����������� minOccurs="0" maxOccurs="1"/>
��� </xs:sequence>
� </xs:complexType>
</xs:element>
The response from the srmPrepareToGet:
<xs:element name="TRequestStatus">
� <xs:complexType>
��� <xs:sequence>
����� <xs:element name="statusCode" minOccurs="1" maxOccurs="1"� ref="TStatusCode"/>
����� <xs:element name="explanation" type="xs:string" minOccurs="0" maxOccurs="1"/>
����� <xs:element name="errorCode" minOccurs="0" maxOccurs="1" ref="TErrorCode"/>
��� </xs:sequence>
� </xs:complexType>
</xs:element>
<xs:element name="TStatusCode">
�� <xs:simpleType>
���� <xs:restriction base="xs:string">
�������� <xs:enumeration value="SRM_SUCCESS"/>
�������� <xs:enumeration value="SRM_FAILURE"/>
�������� <xs:enumeration value="SRM_PARTIAL_SUCCESS"/>
�������� <xs:enumeration value="SRM_REQUEST_QUEUED"/>
�������� <xs:enumeration value="SRM_REQUEST_INPROGRESS"/>
�������� <xs:enumeration value="SRM_REQUEST_ FINISHED"/>
�������� <xs:enumeration value="SRM_REQUEST_ SUSPENDED"/>
�������� <xs:enumeration value="SRM_ABORTED"/>
�������� <xs:enumeration value="SRM_RELEASED"/>
�� ������<xs:enumeration value="SRM_FILE_PINNED"/>
�������� <xs:enumeration value="SRM_FILE_IN_SPACE"/>
�������� <xs:enumeration value="SRM_FILE_IN_ CACHE"/>
�������� <xs:enumeration value="SRM_FILE_IN_ USE"/>
�������� <xs:enumeration value="SRM_FILE_ REMOVED"/>
�������� <xs:enumeration value="SRM_CUSTOM_STATUS"/>
�������� <xs:enumeration value="SRM_SPACE_AVAILABLE"/>
�������� <xs:enumeration value="SRM_LOWER_SPACE_GRANTED"/>
���� </xs:restriction>
�� </xs:simpleType>
</xs:element>
<xs:element name="TErrorCode">
�� <xs:simpleType>
���� <xs:restriction base="xs:string">
�������� <xs:enumeration value="SRM_NOT_SUPPORTED"/>
�������� <xs:enumeration value="SRM_INVALID_REQUEST"/>
�������� <xs:enumeration value="SRM_INVALID_PATH"/>
�������� <xs:enumeration value="SRM_INVALID_REQUEST_TOKEN"/>
�������� <xs:enumeration value="SRM_INVALID_SPACE_TOKEN"/>
�������� <xs:enumeration value="SRM_FILE_LIFETIME_EXPIRED"/>
�������� <xs:enumeration value="SRM_EXCEED_ALLOCATION"/>
�������� <xs:enumeration value="SRM_NO_USER_SPACE"/>
�������� <xs:enumeration value="SRM_NO_FREE_SPACE"/>
�������� <xs:enumeration value="SRM_DUPLICATION_ERROR"/>
�������� <xs:enumeration value="SRM_TOO_MANY_RESULTS"/>
�������� <xs:enumeration value="SRM_INTERNAL_ERROR"/>
�������� <xs:enumeration value="SRM_FATAL_INTERNAL_ERROR"/>
�������� <xs:enumeration value="SRM_AUTHENTICATION_FAILURE"/>
�������� <xs:enumeration value="SRM_AUTHORIZATION_FAILURE"/>
�������� <xs:enumeration value="SRM_SPACE_LIFETIME_EXPIRED"/>
�������� <xs:enumeration value="SRM_NON_EMPTY_DIRECTORY"/>
���� </xs:restriction>
�� </xs:simpleType>
</xs:element>
1.1.3. DESCRIPTION
srmPrepareToGet() allows clients to retrieve files from the local space of SRM. The status of the request may be retrieved asynchronously through srmStatusOfGetRequest().
1.1.3.1. Input Parameters
� user ID (required)
����������� [corresponds to user ID from the functional specification]
user ID is collected from the connection with GSI
� authorizationID
[corresponds to authorization ID from the functional specification]
Client authorization information can be provided explicitly, or as a part of the connection with SAML insertion. This information is understood by the SRM server, and not expected to be interoperable among different SRMs.
� arrayOfTransferProtocols
����������� [corresponds to list of transfer Protocols from the functional specification]
List of the transfer protocols that client can support.
� userRequestDescription �
[corresponds to user Request Description from the functional specification]
String description of the request. It may be used for later retrieval of the request token.
� totalRetryTime
[corresponds to total Retry Time from the functional specification]
totalRetryTime is the amount of time in seconds that SRM should try to transfer failed files, if some file transfers fail.
� streaming
[corresponds to flag for streaming from the functional specification]
Boolean indication of streaming mode. When streaming mode is on, full space does not have to be prepared to hold all files in the request.
� overwriteMode
[corresponds to overwrite Option from the functional specification]
In case SRM stages requested files for the user, SRM needs to stage the file according to the overwriteModeon the target that SRM brings the files into. Overwrite Modes are defined in section 1.
� ArrayOfGetFileRequest (required)
[corresponds to Get File Requests from the functional specification]
It consists of SURL information that client wants to retrieve, in an unordered set.
� sourceSURL (required)
[corresponds to source SURL from the functional specification]
SURL that client desires to retrieve
� desiredLifetime
[corresponds to desired Lifetime from the functional specification]
Desired life time of the file in seconds once when the file is ready. SRM may assign default lifetime based on the policy. In the status call, expiration time in UTCtime� on Transfer URL must be returned.
� sourceStorageSystemInfo
[corresponds to Storage System Info for source SURL from the functional specification]
information specific to the underlying storage system associated with the source SURL.
� knownfileSize
[corresponds to known file Size from the functional specification]
File size of the source SURL if known.
� isSourceDirectory
[corresponds to flag if Source is a directory from the functional specification]
An advanced option when Directory Management feature is
supported.
Boolean indicator if source SURL is a directory. Default is false.
� recursiveDirectory
[corresponds to flag for recursive directory from the functional specification]
An advanced option when Directory Management feature is
supported.
Boolean indicator if source SURL is a directory and all files under the source
SURL must be retrieved. Default is false.
� numDirectoryLevels
[corresponds to num Of Directory Levels from the functional specification]
An advanced option when Directory Management feature is
supported.
Positive integer indicator for how many levels of the recursive
directory must be browsed and all files in those directories to be retrieved.
Default is 1, indicating no recursive, flat directory.
� desiredLifetime
����� [corresponds to desired Lifetime from the functional specification]
Desired life time of the file in seconds once when the file is ready. Default is 0, and SRM assigns default lifetime. This is request level option. If file level option (desiredLifetime) in the arrayOfGetFileRequest is set, it takes the priority.
� sourceFileStorageType
����������� [corresponds to File Storage Type for sources from the functional specification]
sourceFileStorageType indicates which type of source SURLs are.
� SourceStorageSystemInfo
����� [corresponds to Storage System Info for sources from the functional specification]
String containing information specific to the underlying storage system that is associated with the �source SURLs or sourceFileStorageType.
� checksum
[corresponds to flag for performing Checksum from the functional specification]
xsd:boolean indicates that checksum calculation for all files in the request needs to be performed when SRM server brings files into its space. Default is false.
1.1.3.2. Output Parameters
� requestToken (required)
[corresponds to request Token from the functional specification]
Output token is associated with the request for the later asynchronous status request. This is required only if request submission is successful.
� RequestStatus (required)
[corresponds to Request Status from the functional specification]
Output reporting the success or failure of the request. Textual description of explanation for what happened to the request, specially in case of any failures, would help client diagnose the case. statuCode is required and it is separated as status code and error code, so that when client is a non-human program, response to the status information can be pre-programmed.
1.1.4. RETURN CODE
On successful abort, the statusCode is set to SRM_SUCCESS.
On failure, the statusCode is set to SRM_FAILURE and the errorCode is set.
1.1.5. ERROR CODE
When status is failure, errorCode is set to one of the following:
SRM_AUTHENTICATION_FAILURE
� SRM server failed to authenticate the client
SRM_AUTHORIZATION_FAILURE
� client is not authorized to submit the request
SRM_INVALID_REQUEST
� input parameters do not conform the SRM. For example, client requested negative� totalRetryTime and SRM cannot honor the number.
SRM_NOT_SUPPORTED
� SRM server does not support the given input parameters. For example, client requested bbftp for the only transfer protocol, but SRM cannot support that.
1.1.6. NOTES on the Core Behavior
a) Upon successful request submition, SRM server holds a status of the request during the life time of the request. Client is given with the request token that references the request, and the request token may be used for the status call.
b) This is an asynchronous (non-blocking) call. To get status and results, separate calls may be made with the requestToken.
c) sourceSURL must be local to SRM.
d) The user Request Description is a client designated name for the request.� It can be used in the srmGetRequestToken() function to get back the request tokens for requests made by the client.
e) StorageSystemInfo, FileStorageType or desiredLifetime may be provided at the request level and the file level. In that case, SRM uses the one provided at the file level.
f) After the file is brought into the SRM cache, it is pinned, the lifetime clock starts at that time, and the expiration time on Transfer URL gets returned to the client.
g) When the streaming option is true, and only part of the files fit into the space, the SRM wait until files are released and continues to bring files in. When the streaming option is false, and only part of the files fit into the space, SRM must return failure for the request.
h) If some file transfers fail, and all the other files transferred successfully, then totalRetryTime is the amount of time in seconds that SRM should try to transfer failed files.
i) In case that the retries fail, the return values in status call include an explanation of why the retries failed.
j) srmReleaseFile() or srmReleaseRequestedFiles() is expected for files that are no longer needed. Otherwise, file lifetime expires. If lifetime of all the files in the space expires, then the request is terminated and the status of the request is set to SRM_REQUEST_FINISHED.
1.1.7. NOTES on the Advanced Behavior with Directory Management Feature
a) NumDirectoryLevels must be a valid input parameter, and must be a positive integer. Single level of directory (no recursive) may be the default.
b) recursiveDirectory may be false by default.
1.1.8. SEE ALSO
srmStatusOfGetRequest, srmPrepareToPut, srmRemoteCopy