Return-Path: X-Original-To: apmail-hadoop-hdfs-commits-archive@minotaur.apache.org Delivered-To: apmail-hadoop-hdfs-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 1E0D099D8 for ; Tue, 22 Nov 2011 20:05:36 +0000 (UTC) Received: (qmail 68354 invoked by uid 500); 22 Nov 2011 20:05:36 -0000 Delivered-To: apmail-hadoop-hdfs-commits-archive@hadoop.apache.org Received: (qmail 68309 invoked by uid 500); 22 Nov 2011 20:05:35 -0000 Mailing-List: contact hdfs-commits-help@hadoop.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: hdfs-dev@hadoop.apache.org Delivered-To: mailing list hdfs-commits@hadoop.apache.org Received: (qmail 68300 invoked by uid 99); 22 Nov 2011 20:05:35 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 22 Nov 2011 20:05:35 +0000 X-ASF-Spam-Status: No, hits=-1998.0 required=5.0 tests=ALL_TRUSTED,FB_GET_MEDS X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 22 Nov 2011 20:05:21 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 3D96A238897A; Tue, 22 Nov 2011 20:04:59 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1205146 - in /hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs: CHANGES.txt src/main/docs/src/documentation/content/xdocs/site.xml src/main/docs/src/documentation/content/xdocs/webhdfs.xml Date: Tue, 22 Nov 2011 20:04:58 -0000 To: hdfs-commits@hadoop.apache.org From: szetszwo@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20111122200459.3D96A238897A@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: szetszwo Date: Tue Nov 22 20:04:58 2011 New Revision: 1205146 URL: http://svn.apache.org/viewvc?rev=1205146&view=rev Log: HDFS-2552. Add Forrest doc for WebHDFS REST API. Added: hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/webhdfs.xml Modified: hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/site.xml Modified: hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt URL: http://svn.apache.org/viewvc/hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt?rev=1205146&r1=1205145&r2=1205146&view=diff ============================================================================== --- hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt (original) +++ hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/CHANGES.txt Tue Nov 22 20:04:58 2011 @@ -153,6 +153,8 @@ Release 0.23.1 - UNRELEASED HDFS-2566. Move BPOfferService to be a non-inner class. (todd) + HDFS-2552. Add Forrest doc for WebHDFS REST API. (szetszwo) + OPTIMIZATIONS HDFS-2130. Switch default checksum to CRC32C. (todd) Modified: hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/site.xml URL: http://svn.apache.org/viewvc/hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/site.xml?rev=1205146&r1=1205145&r2=1205146&view=diff ============================================================================== --- hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/site.xml (original) +++ hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/site.xml Tue Nov 22 20:04:58 2011 @@ -43,6 +43,7 @@ See http://forrest.apache.org/docs/linki + @@ -120,7 +121,40 @@ See http://forrest.apache.org/docs/linki + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/webhdfs.xml URL: http://svn.apache.org/viewvc/hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/webhdfs.xml?rev=1205146&view=auto ============================================================================== --- hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/webhdfs.xml (added) +++ hadoop/common/trunk/hadoop-hdfs-project/hadoop-hdfs/src/main/docs/src/documentation/content/xdocs/webhdfs.xml Tue Nov 22 20:04:58 2011 @@ -0,0 +1,1558 @@ + + + + + + +
+ WebHDFS REST API +
+ + +
+ Document Conventions + + + + + +
MonospacedUsed for commands, HTTP request and responses and code blocks.
<Monospaced>User entered values.
[Monospaced]Optional values. When the value is not specified, the default value is used.
ItalicsImportant phrases and words.
+
+ +
+ Introduction +

+ The HTTP REST API supports the complete FileSystem interface for HDFS. + The operations and the corresponding FileSystem methods are shown in the next section. + The Section HTTP Query Parameter Dictionary specifies the parameter details + such as the defaults and the valid values. +

+
+ Operations + + + +
+ +
+ FileSystem URIs vs HTTP URLs +

+ The FileSystem scheme of WebHDFS is "webhdfs://". + A WebHDFS FileSystem URI has the following format. +

+ + webhdfs://<HOST>:<HTTP_PORT>/<PATH> + +

+ The above WebHDFS URI corresponds to the below HDFS URI. +

+ + hdfs://<HOST>:<RPC_PORT>/<PATH> + +

+ In the REST API, the prefix "/webhdfs/v1" is inserted in the path and a query is appended at the end. + Therefore, the corresponding HTTP URL has the following format. +

+ + http://<HOST>:<HTTP_PORT>/webhdfs/v1/<PATH>?op=... + +
+
+ +
+ Authentication +

+ When security is off, the authenticated user is the username specified in the user.name query parameter. + If the user.name parameter is not set, + the server may either set the authenticated user to a default web user, if there is any, or return error response. +

+

+ When security is on, authentication is performed by either Hadoop delegation token or Kerberos SPNEGO. + If a token is set in the delegation query parameter, the authenticated user is the user encoded in the token. + If the delegation parameter is not set, the user is authenticated by Kerberos SPNEGO. +

+

+Below are examples using the curl command tool. +

+
    +
  1. + Authentication when security is off: + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?[user.name=<USER>&]op=..." + +
  2. + Authentication using Kerberos SPNEGO when security is on: + +curl -i --negotiate -u : "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=..." + +
  3. + Authentication using Hadoop delegation token when security is on: + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?delegation=<TOKEN>&op=..." + +
    4. +
+
+ +
+ Proxy Users +

+ When the proxy user feature is enabled, a proxy user P may submit a request on behalf of another user U. + The username of U must be specified in the doas query parameter unless a delegation token is presented in authentication. + In such case, the information of both users P and U must be encoded in the delegation token. +

+
    +
  1. + A proxy request when security is off: + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?[user.name=<USER>&]doas=<USER>&op=..." + +
  2. + A proxy request using Kerberos SPNEGO when security is on: + +curl -i --negotiate -u : "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?doas=<USER>&op=..." + +
  3. + A proxy request using Hadoop delegation token when security is on: + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?delegation=<TOKEN>&op=..." + +
    4. +
+
+ + +
+ File and Directory Operations +
+ Create and Write to a File +
    +
  • Step 1: Submit a HTTP PUT request without automatically following redirects and without sending the file data. + +curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=CREATE + [&overwrite=<true|false>][&blocksize=<LONG>][&replication=<SHORT>] + [&permission=<OCTAL>][&buffersize=<INT>]" + +The request is redirected to a datanode where the file data is to be written: + +HTTP/1.1 307 TEMPORARY_REDIRECT +Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=CREATE... +Content-Length: 0 + +
    • +
  • Step 2: Submit another HTTP PUT request using the URL in the Location header with the file data to be written. + +curl -i -X PUT -T <LOCAL_FILE> "http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=CREATE..." + +The client receives a 201 Created response with zero content length +and the WebHDFS URI of the file in the Location header: + +HTTP/1.1 201 Created +Location: webhdfs://<HOST>:<PORT>/<PATH> +Content-Length: 0 + +
    • +
+

+ Note that the reason of having two-step create/append is + for preventing clients to send out data before the redirect. + This issue is addressed by the "Expect: 100-continue" header in HTTP/1.1; + see RFC 2616, Section 8.2.3. + Unfortunately, there are software library bugs (e.g. Jetty 6 HTTP server and Java 6 HTTP client), + which do not correctly implement "Expect: 100-continue". + The two-step create/append is a temporary workaround for the software library bugs. +

+

+ See also: + overwrite, + blocksize, + replication, + permission, + buffersize, + DistributedFileSystem.create +

+
+ +
+ Append to a File +
    +
  • Step 1: Submit a HTTP POST request without automatically following redirects and without sending the file data. + +curl -i -X POST "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=APPEND[&buffersize=<INT>]" + +The request is redirected to a datanode where the file data is to be appended: + +HTTP/1.1 307 TEMPORARY_REDIRECT +Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=APPEND... +Content-Length: 0 + +
    • +
  • Step 2: Submit another HTTP POST request using the URL in the Location header with the file data to be appended. + +curl -i -X POST -T <LOCAL_FILE> "http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=APPEND..." + +The client receives a response with zero content length: + +HTTP/1.1 200 OK +Content-Length: 0 + +
    • +
+

+ See the note in the previous section for the description of why this operation requires two steps. +

+

+ See also: + buffersize, + DistributedFileSystem.append +

+
+ +
+ Open and Read a File +
    +
  • Submit a HTTP GET request with automatically following redirects. + +curl -i -L "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=OPEN + [&offset=<LONG>][&length=<LONG>][&buffersize=<INT>]" + +The request is redirected to a datanode where the file data can be read: + +HTTP/1.1 307 TEMPORARY_REDIRECT +Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=OPEN... +Content-Length: 0 + +The client follows the redirect to the datanode and receives the file data: + +HTTP/1.1 200 OK +Content-Type: application/octet-stream +Content-Length: 22 + +Hello, webhdfs user! + +
    • +
+

+ See also: + offset, + length, + buffersize, + DistributedFileSystem.open +

+
+ +
+ Make a Directory +
    +
  • Submit a HTTP PUT request. + +curl -i -X PUT "http://<HOST>:<PORT>/<PATH>?op=MKDIRS[&permission=<OCTAL>]" + +The client receives a response with a boolean JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{"boolean": true} + +
    • +
+

+ See also: + permission, + DistributedFileSystem.mkdirs +

+
+ +
+ Rename a File/Directory +
    +
  • Submit a HTTP PUT request. + +curl -i -X PUT "<HOST>:<PORT>/webhdfs/v1/<PATH>?op=RENAME&destination=<PATH>" + +The client receives a response with a boolean JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{"boolean": true} + +
    • +
+

+ See also: + destination, + DistributedFileSystem.rename +

+
+ +
+ Delete a File/Directory +
    +
  • Submit a HTTP DELETE request. + +curl -i -X DELETE "http://<host>:<port>/webhdfs/v1/<path>?op=DELETE + [&recursive=<true|false>]" + +The client receives a response with a boolean JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{"boolean": true} + +
    • +
+

+ See also: + recursive, + DistributedFileSystem.delete +

+
+ +
+ Status of a File/Directory +
    +
  • Submit a HTTP GET request. + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETFILESTATUS" + +The client receives a response with a FileStatus JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{ + "FileStatus": + { + "accessTime" : 0, + "blockSize" : 0, + "group" : "supergroup", + "length" : 0, //in bytes, zero for directories + "modificationTime": 1320173277227, + "owner" : "webuser", + "pathSuffix" : "", + "permission" : "777", + "replication" : 0, + "type" : "DIRECTORY" //enum {FILE, DIRECTORY, SYMLINK} + } +} + +
    • +
+

+ See also: + DistributedFileSystem.getFileStatus +

+
+ +
+ List a Directory +
    +
  • Submit a HTTP GET request. + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=LISTSTATUS" + +The client receives a response with a FileStatuses JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Content-Length: 427 + +{ + "FileStatuses": + { + "FileStatus": + [ + { + "accessTime" : 1320171722771, + "blockSize" : 33554432, + "group" : "supergroup", + "length" : 24930, + "modificationTime": 1320171722771, + "owner" : "webuser", + "pathSuffix" : "a.patch", + "permission" : "644", + "replication" : 1, + "type" : "FILE" + }, + { + "accessTime" : 0, + "blockSize" : 0, + "group" : "supergroup", + "length" : 0, + "modificationTime": 1320895981256, + "owner" : "szetszwo", + "pathSuffix" : "bar", + "permission" : "711", + "replication" : 0, + "type" : "DIRECTORY" + }, + ... + ] + } +} + +
    • +
+

+ See also: + DistributedFileSystem.listStatus +

+
+
+ + +
+ Other File System Operations +
+ Get Content Summary of a Directory +
    +
  • Submit a HTTP GET request. + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETCONTENTSUMMARY" + +The client receives a response with a ContentSummary JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{ + "ContentSummary": + { + "directoryCount": 2, + "fileCount" : 1, + "length" : 24930, + "quota" : -1, + "spaceConsumed" : 24930, + "spaceQuota" : -1 + } +} + +
    • +
+

+ See also: + DistributedFileSystem.getContentSummary +

+
+ +
+ Get File Checksum +
    +
  • Submit a HTTP GET request. + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETFILECHECKSUM" + +The request is redirected to a datanode: + +HTTP/1.1 307 TEMPORARY_REDIRECT +Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=GETFILECHECKSUM... +Content-Length: 0 + +The client follows the redirect to the datanode and receives a FileChecksum JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{ + "FileChecksum": + { + "algorithm": "MD5-of-1MD5-of-512CRC32", + "bytes" : "eadb10de24aa315748930df6e185c0d ...", + "length" : 28 + } +} + +
    • +
+

+ See also: + DistributedFileSystem.getFileChecksum +

+
+ +
+ Get Home Directory +
    +
  • Submit a HTTP GET request. + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/?op=GETHOMEDIRECTORY" + +The client receives a response with a Path JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{"Path": "/user/szetszwo"} + +
    • +
+

+ See also: + DistributedFileSystem.getHomeDirectory +

+
+ +
+ Set Permission +
    +
  • Submit a HTTP PUT request. + +curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETPERMISSION + [&permission=<OCTAL>]" + +The client receives a response with zero content length: + +HTTP/1.1 200 OK +Content-Length: 0 + +
    • +
+

+ See also: + permission, + DistributedFileSystem.setPermission +

+
+ +
+ Set Owner +
    +
  • Submit a HTTP PUT request. + +curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETOWNER + [&owner=<USER>][&group=<GROUP>]" + +The client receives a response with zero content length: + +HTTP/1.1 200 OK +Content-Length: 0 + +
    • +
+

+ See also: + owner, + group, + DistributedFileSystem.setOwner +

+
+ +
+ Set Replication Factor +
    +
  • Submit a HTTP PUT request. + +curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETREPLICATION + [&replication=<SHORT>]" + +The client receives a response with a boolean JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{"boolean": true} + +
    • +
+

+ See also: + replication, + DistributedFileSystem.setReplication +

+
+ +
+ Set Access or Modification Time +
    +
  • Submit a HTTP PUT request. + +curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETTIMES + [&modificationtime=<TIME>][&accesstime=<TIME>]" + +The client receives a response with zero content length: + +HTTP/1.1 200 OK +Content-Length: 0 + +
    • +
+

+ See also: + modificationtime, + accesstime, + DistributedFileSystem.setTimes +

+
+
+ + +
+ Delegation Token Operations +
+ Get Delegation Token +
    +
  • Submit a HTTP GET request. + +curl -i "http://<HOST>:<PORT>/webhdfs/v1/?op=GETDELEGATIONTOKEN&renewer=<USER>" + +The client receives a response with a Token JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{ + "Token": + { + "urlString": "JQAIaG9y..." + } +} + +
    • +
+

+ See also: + renewer, + DistributedFileSystem.getDelegationToken +

+
+ +
+ Renew Delegation Token +
    +
  • Submit a HTTP PUT request. + +curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=RENEWDELEGATIONTOKEN&token=<TOKEN>" + +The client receives a response with a long JSON object: + +HTTP/1.1 200 OK +Content-Type: application/json +Transfer-Encoding: chunked + +{"long": 1320962673997} //the new expiration time + +
    • +
+

+ See also: + token, + DistributedFileSystem.renewDelegationToken +

+
+ +
+ Cancel Delegation Token +
    +
  • Submit a HTTP PUT request. + +curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=CANCELDELEGATIONTOKEN&token=<TOKEN>" + +The client receives a response with zero content length: + +HTTP/1.1 200 OK +Content-Length: 0 + +
    • +
+

+ See also: + token, + DistributedFileSystem.cancelDelegationToken +

+
+
+ + +
+ Error Responses +

+ When an operation fails, the server may throw an exception. + The JSON schema of error responses is defined in RemoteException JSON schema. + The table below shows the mapping from exceptions to HTTP response codes. +

+
+ HTTP Response Codes + + + + + + + + +
ExceptionsHTTP Response Codes
IllegalArgumentException 400 Bad Request
UnsupportedOperationException400 Bad Request
SecurityException 401 Unauthorized
IOException 403 Forbidden
FileNotFoundException 404 Not Found
RumtimeException 500 Internal Server Error
+

+ Below are examples of exception response. +

+ +
+ Illegal Argument Exception + +HTTP/1.1 400 Bad Request +Content-Type: application/json +Transfer-Encoding: chunked + +{ + "RemoteException": + { + "exception" : "IllegalArgumentException", + "javaClassName": "java.lang.IllegalArgumentException", + "message" : "Invalid value for webhdfs parameter \"permission\": ..." + } +} + +
+ +
+ Security Exception + +HTTP/1.1 401 Unauthorized +Content-Type: application/json +Transfer-Encoding: chunked + +{ + "RemoteException": + { + "exception" : "SecurityException", + "javaClassName": "java.lang.SecurityException", + "message" : "Failed to obtain user group information: ..." + } +} + +
+ +
+ Access Control Exception + +HTTP/1.1 403 Forbidden +Content-Type: application/json +Transfer-Encoding: chunked + +{ + "RemoteException": + { + "exception" : "AccessControlException", + "javaClassName": "org.apache.hadoop.security.AccessControlException", + "message" : "Permission denied: ..." + } +} + +
+ +
+ File Not Found Exception + +HTTP/1.1 404 Not Found +Content-Type: application/json +Transfer-Encoding: chunked + +{ + "RemoteException": + { + "exception" : "FileNotFoundException", + "javaClassName": "java.io.FileNotFoundException", + "message" : "File does not exist: /foo/a.patch" + } +} + +
+
+
+ + +
+ JSON Schemas +

+All operations, except for OPEN, +either return a zero-length response or a JSON response . +For OPEN, the response is an octet-stream. +The JSON schemas are shown below. +See draft-zyp-json-schema-03 +for the syntax definitions of the JSON schemas. +

+
+ Boolean JSON Schema + +{ + "name" : "boolean", + "properties": + { + "boolean": + { + "description": "A boolean value", + "type" : "boolean", + "required" : true + } + } +} + +

+ See also: + MKDIRS, + RENAME, + DELETE, + SETREPLICATION +

+
+ +
+ ContentSummary JSON Schema + +{ + "name" : "ContentSummary", + "properties": + { + "ContentSummary": + { + "type" : "object", + "properties": + { + "directoryCount": + { + "description": "The number of directories.", + "type" : "integer", + "required" : true + }, + "fileCount": + { + "description": "The number of files.", + "type" : "integer", + "required" : true + }, + "length": + { + "description": "The number of bytes used by the content.", + "type" : "integer", + "required" : true + }, + "quota": + { + "description": "The namespace quota of this directory.", + "type" : "integer", + "required" : true + }, + "spaceConsumed": + { + "description": "The disk space consumed by the content.", + "type" : "integer", + "required" : true + }, + "spaceQuota": + { + "description": "The disk space quota.", + "type" : "integer", + "required" : true + } + } + } + } +} + +

+ See also: + GETCONTENTSUMMARY +

+
+ +
+ FileChecksum JSON Schema + +{ + "name" : "FileChecksum", + "properties": + { + "FileChecksum": + { + "type" : "object", + "properties": + { + "algorithm": + { + "description": "The name of the checksum algorithm.", + "type" : "string", + "required" : true + }, + "bytes": + { + "description": "The byte sequence of the checksum in hexadecimal.", + "type" : "string", + "required" : true + }, + "length": + { + "description": "The length of the bytes (not the length of the string).", + "type" : "integer", + "required" : true + } + } + } + } +} + +

+ See also: + GETFILECHECKSUM +

+
+ +
+ FileStatus JSON Schema + +{ + "name" : "FileStatus", + "properties": + { + "FileStatus": fileStatusProperties //See FileStatus Properties + } +} + +

+ See also: + GETFILESTATUS, + FileStatus +

+
+ FileStatus Properties +

+ JavaScript syntax is used to define fileStatusProperties + so that it can be referred in both FileStatus and FileStatuses JSON schemas. +

+ +var fileStatusProperties = +{ + "type" : "object", + "properties": + { + "accessTime": + { + "description": "The access time.", + "type" : "integer", + "required" : true + }, + "blockSize": + { + "description": "The block size of a file.", + "type" : "integer", + "required" : true + }, + "group": + { + "description": "The group owner.", + "type" : "string", + "required" : true + }, + "length": + { + "description": "The number of bytes in a file.", + "type" : "integer", + "required" : true + }, + "modificationTime": + { + "description": "The modification time.", + "type" : "integer", + "required" : true + }, + "owner": + { + "description": "The user who is the owner.", + "type" : "string", + "required" : true + }, + "pathSuffix": + { + "description": "The path suffix.", + "type" : "string", + "required" : true + }, + "permission": + { + "description": "The permission represented as a octal string.", + "type" : "string", + "required" : true + }, + "replication": + { + "description": "The number of replication of a file.", + "type" : "integer", + "required" : true + }, + "symlink": //an optional property + { + "description": "The link target of a symlink.", + "type" : "string" + }, + "type": + { + "description": "The type of the path object.", + "enum" : ["FILE", "DIRECTORY", "SYMLINK"], + "required" : true + } + } +}; + +
+
+ +
+ FileStatuses JSON Schema +

+ A FileStatuses JSON object represents an array of FileStatus JSON objects. +

+ +{ + "name" : "FileStatuses", + "properties": + { + "FileStatuses": + { + "type" : "object", + "properties": + { + "FileStatus": + { + "description": "An array of FileStatus", + "type" : "array", + "items" : fileStatusProperties //See FileStatus Properties + } + } + } + } +} + +

+ See also: + LISTSTATUS, + FileStatus +

+
+ +
+ Long JSON Schema + +{ + "name" : "long", + "properties": + { + "long": + { + "description": "A long integer value", + "type" : "integer", + "required" : true + } + } +} + +

+ See also: + RENEWDELEGATIONTOKEN, +

+
+ +
+ Path JSON Schema + +{ + "name" : "Path", + "properties": + { + "Path": + { + "description": "The string representation a Path.", + "type" : "string", + "required" : true + } + } +} + +

+ See also: + GETHOMEDIRECTORY, + Path +

+
+ +
+ RemoteException JSON Schema + +{ + "name" : "RemoteException", + "properties": + { + "RemoteException": + { + "type" : "object", + "properties": + { + "exception": + { + "description": "Name of the exception", + "type" : "string", + "required" : true + }, + "message": + { + "description": "Exception message", + "type" : "string", + "required" : true + }, + "javaClassName": //an optional property + { + "description": "Java class name of the exception", + "type" : "string", + } + } + } + } +} + +
+ +
+ Token JSON Schema + +{ + "name" : "Token", + "properties": + { + "Token": + { + "type" : "object", + "properties": + { + "urlString": + { + "description": "A delegation token encoded as a URL safe string.", + "type" : "string", + "required" : true + } + } + } + } +} + +

+ See also: + GETDELEGATIONTOKEN, + the note in Delegation. +

+
+
+ + +
+ HTTP Query Parameter Dictionary +
+ Access Time + + + + + + + +
Nameaccesstime
DescriptionThe access time of a file/directory.
Typelong
Default Value-1 (means keeping it unchanged)
Valid Values-1 or a timestamp
SyntaxAny integer.
+

+ See also: + SETTIMES +

+
+ +
+ Block Size + + + + + + + +
Nameblocksize
DescriptionThe block size of a file.
Typelong
Default ValueSpecified in the configuration.
Valid Values> 0
SyntaxAny integer.
+

+ See also: + CREATE +

+
+ +
+ Buffer Size + + + + + + + +
Namebuffersize
DescriptionThe size of the buffer used in transferring data.
Typeint
Default ValueSpecified in the configuration.
Valid Values> 0
SyntaxAny integer.
+

+ See also: + CREATE, + APPEND, + OPEN +

+
+ +
+ Delegation + + + + + + + +
Namedelegation
DescriptionThe delegation token used for authentication.
TypeString
Default Value<empty>
Valid ValuesAn encoded token.
SyntaxSee the note below.
+

+ Note that delegation tokens are encoded as a URL safe string; + see encodeToUrlString() + and decodeFromUrlString(String) + in org.apache.hadoop.security.token.Token for the details of the encoding. +

+

+ See also: + Authentication +

+
+ +
+ Destination + + + + + + + +
Namedestination
DescriptionThe destination path used in RENAME.
TypePath
Default Value<empty> (an invalid path)
Valid ValuesAn absolute FileSystem path without scheme and authority.
SyntaxAny path.
+

+ See also: + RENAME +

+
+ +
+ Do As + + + + + + + +
Namedoas
DescriptionAllowing a proxy user to do as another user.
TypeString
Default Valuenull
Valid ValuesAny valid username.
SyntaxAny string.
+

+ See also: + Proxy Users +

+
+ +
+ Group + + + + + + + +
Namegroup
DescriptionThe name of a group.
TypeString
Default Value<empty> (means keeping it unchanged)
Valid ValuesAny valid group name.
SyntaxAny string.
+

+ See also: + SETOWNER +

+
+ +
+ Length + + + + + + + +
Namelength
DescriptionThe number of bytes to be processed.
Typelong
Default Valuenull (means the entire file)
Valid Values>= 0 or null
SyntaxAny integer.
+

+ See also: + OPEN +

+
+ +
+ Modification Time + + + + + + + +
Namemodificationtime
DescriptionThe modification time of a file/directory.
Typelong
Default Value-1 (means keeping it unchanged)
Valid Values-1 or a timestamp
SyntaxAny integer.
+

+ See also: + SETTIMES +

+
+ +
+ Offset + + + + + + + +
Nameoffset
DescriptionThe starting byte position.
Typelong
Default Value0
Valid Values>= 0
SyntaxAny integer.
+

+ See also: + OPEN +

+
+ +
+ Op + + + + + + + +
Nameop
DescriptionThe name of the operation to be executed.
Typeenum
Default Valuenull (an invalid value)
Valid ValuesAny valid operation name.
SyntaxAny string.
+

+ See also: + Operations +

+
+ +
+ Overwrite + + + + + + + +
Nameoverwrite
DescriptionIf a file already exists, should it be overwritten?
Typeboolean
Default Valuefalse
Valid Valuestrue | false
Syntaxtrue | false
+

+ See also: + CREATE +

+
+ +
+ Owner + + + + + + + +
Nameowner
DescriptionThe username who is the owner of a file/directory.
TypeString
Default Value<empty> (means keeping it unchanged)
Valid ValuesAny valid username.
SyntaxAny string.
+

+ See also: + SETOWNER +

+
+ +
+ Permission + + + + + + + +
Namepermission
DescriptionThe permission of a file/directory.
TypeOctal
Default Value755
Valid Values0 - 1777
SyntaxAny radix-8 integer (leading zeros may be omitted.)
+

+ See also: + CREATE, + MKDIRS, + SETPERMISSION +

+
+ +
+ Recursive + + + + + + + +
Namerecursive
DescriptionShould the operation act on the content in the subdirectories?
Typeboolean
Default Valuefalse
Valid Valuestrue | false
Syntaxtrue | false
+

+ See also: + RENAME +

+
+ +
+ Renewer + + + + + + + +
Namerenewer
DescriptionThe username of the renewer of a delegation token.
TypeString
Default Value<empty> (means the current user)
Valid ValuesAny valid username.
SyntaxAny string.
+

+ See also: + GETDELEGATIONTOKEN +

+
+ +
+ Replication + + + + + + + +
Namereplication
DescriptionThe number of replications of a file.
Typeshort
Default ValueSpecified in the configuration.
Valid Values> 0
SyntaxAny integer.
+

+ See also: + CREATE, + SETREPLICATION +

+
+ +
+ Token + + + + + + + +
Nametoken
DescriptionThe delegation token used for the operation.
TypeString
Default Value<empty>
Valid ValuesAn encoded token.
SyntaxSee the note in Delegation.
+

+ See also: + RENEWDELEGATIONTOKEN, + CANCELDELEGATIONTOKEN +

+
+ +
+ Username + + + + + + + +
Nameuser.name
DescriptionThe authenticated user; see Authentication.
TypeString
Default Valuenull
Valid ValuesAny valid username.
SyntaxAny string.
+

+ See also: + Authentication +

+
+
+ +