ClientProtocol (Hadoop 1.2.2-SNAPSHOT API)

所有超级接口:

VersionedProtocol

所有已知实现类:

NameNode
```
public interface ClientProtocol
extends VersionedProtocol
```
ClientProtocol is used by user code via DistributedFileSystem class to communicate with the NameNode. User code can manipulate the directory namespace, as well as open/close file streams, etc.

字段概要

字段
限定符和类型	字段和说明
`static int`	`GET_STATS_CAPACITY_IDX`
`static int`	`GET_STATS_CORRUPT_BLOCKS_IDX`
`static int`	`GET_STATS_MISSING_BLOCKS_IDX`
`static int`	`GET_STATS_REMAINING_IDX`
`static int`	`GET_STATS_UNDER_REPLICATED_IDX`
`static int`	`GET_STATS_USED_IDX`
`static long`	`versionID` Compared to the previous version the following changes have been introduced: (Only the latest change is reflected.

方法概要

方法
限定符和类型	方法和说明
`void`	`abandonBlock(Block b, String src, String holder)` The client can give up on a blcok by calling abandonBlock().
`LocatedBlock`	`addBlock(String src, String clientName)` 已过时。 use the 3-arg form below
`LocatedBlock`	`addBlock(String src, String clientName, DatanodeInfo[] excludedNodes)` A client that wants to write an additional block to the indicated filename (which must currently be open for writing) should call addBlock().
`LocatedBlock`	`append(String src, String clientName)` Append to the end of the file.
`void`	`cancelDelegationToken(Token<DelegationTokenIdentifier> token)` Cancel an existing delegation token.
`boolean`	`complete(String src, String clientName)` The client is done writing data to the given filename, and would like to complete it.
`void`	`concat(String trg, String[] srcs)` Moves blocks from srcs to trg and delete srcs
`void`	`create(String src, FsPermission masked, String clientName, boolean overwrite, boolean createParent, short replication, long blockSize)` Create a new file entry in the namespace.
`void`	`create(String src, FsPermission masked, String clientName, boolean overwrite, short replication, long blockSize)` Create a new file entry in the namespace.
`boolean`	`delete(String src)` Delete the given file or directory from the file system.
`boolean`	`delete(String src, boolean recursive)` Delete the given file or directory from the file system.
`UpgradeStatusReport`	`distributedUpgradeProgress(FSConstants.UpgradeAction action)` Report distributed upgrade progress or force current upgrade to proceed.
`void`	`finalizeUpgrade()` Finalize previous upgrade.
`void`	`fsync(String src, String client)` Write all metadata for this file into persistent storage.
`LocatedBlocks`	`getBlockLocations(String src, long offset, long length)` Get locations of the blocks of the specified file within the specified range.
`ContentSummary`	`getContentSummary(String path)` Get `ContentSummary` rooted at the specified directory.
`DatanodeInfo[]`	`getDatanodeReport(FSConstants.DatanodeReportType type)` Get a report on the system's current datanodes.
`Token<DelegationTokenIdentifier>`	`getDelegationToken(Text renewer)` Get a valid Delegation Token.
`HdfsFileStatus`	`getFileInfo(String src)` Get the file info for a specific file or directory.
`DirectoryListing`	`getListing(String src, byte[] startAfter)` Get a partial listing of the indicated directory
`long`	`getPreferredBlockSize(String filename)` Get the block size for the given file.
`long[]`	`getStats()` Get a set of statistics about the filesystem.
`boolean`	`isFileClosed(String src)` Get the close status of a file
`void`	`metaSave(String filename)` Dumps namenode data structures into specified file.
`boolean`	`mkdirs(String src, FsPermission masked)` Create a directory (or hierarchy of directories) with the given name and permission.
`boolean`	`recoverLease(String src, String clientName)` Start lease recovery
`void`	`refreshNodes()` Tells the namenode to reread the hosts and exclude files.
`boolean`	`rename(String src, String dst)` Rename an item in the file system namespace.
`long`	`renewDelegationToken(Token<DelegationTokenIdentifier> token)` Renew an existing delegation token.
`void`	`renewLease(String clientName)` Client programs can cause stateful changes in the NameNode that affect other clients.
`void`	`reportBadBlocks(LocatedBlock[] blocks)` The client wants to report corrupted blocks (blocks with specified locations on datanodes).
`void`	`saveNamespace()` Save namespace image.
`void`	`setBalancerBandwidth(long bandwidth)` Tell all datanodes to use a new, non-persistent bandwidth value for dfs.balance.bandwidthPerSec.
`void`	`setOwner(String src, String username, String groupname)` Set owner of a path (i.e. a file or a directory).
`void`	`setPermission(String src, FsPermission permission)` Set permissions for an existing file/directory.
`void`	`setQuota(String path, long namespaceQuota, long diskspaceQuota)` Set the quota for a directory.
`boolean`	`setReplication(String src, short replication)` Set replication for an existing file.
`boolean`	`setSafeMode(FSConstants.SafeModeAction action)` Enter, leave or get safe mode.
`void`	`setTimes(String src, long mtime, long atime)` Sets the modification and access time of the file to the specified time.

从接口继承的方法 org.apache.hadoop.ipc.VersionedProtocol
getProtocolVersion

- 字段详细资料
  - versionID
```
static final long versionID
```
    Compared to the previous version the following changes have been introduced: (Only the latest change is reflected. The log of historical changes can be retrieved from the svn). 61: Serialized format of BlockTokenIdentifier changed to contain multiple blocks within a single BlockTokenIdentifier (bumped to 61 to bring in line with trunk) Added concat() and isFileClosed() - since this is addition of methods, it does not break compatibility and version number does not need to be changed.
    
    另请参阅:
    常量字段值
  - GET_STATS_CAPACITY_IDX
```
static final int GET_STATS_CAPACITY_IDX
```
    另请参阅:
    常量字段值
  - GET_STATS_USED_IDX
```
static final int GET_STATS_USED_IDX
```
    另请参阅:
    常量字段值
  - GET_STATS_REMAINING_IDX
```
static final int GET_STATS_REMAINING_IDX
```
    另请参阅:
    常量字段值
  - GET_STATS_UNDER_REPLICATED_IDX
```
static final int GET_STATS_UNDER_REPLICATED_IDX
```
    另请参阅:
    常量字段值
  - GET_STATS_CORRUPT_BLOCKS_IDX
```
static final int GET_STATS_CORRUPT_BLOCKS_IDX
```
    另请参阅:
    常量字段值
  - GET_STATS_MISSING_BLOCKS_IDX
```
static final int GET_STATS_MISSING_BLOCKS_IDX
```
    另请参阅:
    常量字段值
- 方法详细资料
  - getBlockLocations
```
LocatedBlocks getBlockLocations(String src,
                              long offset,
                              long length)
                                throws IOException
```
    Get locations of the blocks of the specified file within the specified range. DataNode locations for each block are sorted by the proximity to the client.
    Return LocatedBlocks which contains file length, blocks and their locations. DataNode locations for each block are sorted by the distance to the client's address.
    The client will then have to contact one of the indicated DataNodes to obtain the actual data.
    
    参数:
    src - file name
    offset - range start offset
    length - range length
    
    返回:
    file length and array of blocks with their locations
    
    抛出:
    
    IOException
  - create
```
void create(String src,
          FsPermission masked,
          String clientName,
          boolean overwrite,
          boolean createParent,
          short replication,
          long blockSize)
            throws IOException
```
    Create a new file entry in the namespace.
    This will create an empty file specified by the source path. The path should reflect a full path originated at the root. The name-node does not have a notion of "current" directory for a client.
    Once created, the file is visible and available for read to other clients. Although, other clients cannot delete(String), re-create or rename(String, String) it until the file is completed or explicitly as a result of lease expiration.
    Blocks have a maximum size. Clients that intend to create multi-block files must also use addBlock(String, String).
    
    参数:
    src - path of the file being created.
    masked - masked permission.
    clientName - name of the current client.
    overwrite - indicates whether the file should be overwritten if it already exists.
    createParent - create missing parent directory if true
    replication - block replication factor.
    blockSize - maximum block size.
    
    抛出:
    
    AccessControlException - if permission to create file is denied by the system. As usually on the client side the exception will be wrapped into RemoteException.
    
    QuotaExceededException - if the file creation violates any quota restriction
    
    IOException - if other errors occur.
  - create
```
void create(String src,
          FsPermission masked,
          String clientName,
          boolean overwrite,
          short replication,
          long blockSize)
            throws IOException
```
    Create a new file entry in the namespace.
    
    抛出:
    
    IOException
  - append
```
LocatedBlock append(String src,
                  String clientName)
                    throws IOException
```
    Append to the end of the file.
    
    参数:
    src - path of the file being created.
    clientName - name of the current client.
    
    返回:
    information about the last partial block if any.
    
    抛出:
    
    AccessControlException - if permission to append file is denied by the system. As usually on the client side the exception will be wrapped into RemoteException. Allows appending to an existing file if the server is configured with the parameter dfs.support.broken.append set to true, otherwise throws an IOException.
    
    IOException - if other errors occur.
  - recoverLease
```
boolean recoverLease(String src,
                   String clientName)
                     throws IOException
```
    Start lease recovery
    
    参数:
    src - path of the file to start lease recovery
    clientName - name of the current client
    
    返回:
    true if the file is already closed
    
    抛出:
    
    IOException
  - isFileClosed
```
boolean isFileClosed(String src)
                     throws AccessControlException,
                            FileNotFoundException,
                            IOException
```
    Get the close status of a file
    
    参数:
    src - The string representation of the path to the file
    
    返回:
    return true if file is closed
    
    抛出:
    
    AccessControlException - permission denied
    
    FileNotFoundException - file src is not found
    
    IOException - If an I/O error occurred
  - setReplication
```
boolean setReplication(String src,
                     short replication)
                       throws IOException
```
    Set replication for an existing file.
    The NameNode sets replication to the new value and returns. The actual block replication is not expected to be performed during this method call. The blocks will be populated or removed in the background as the result of the routine block maintenance procedures.
    
    参数:
    src - file name
    replication - new replication
    
    返回:
    true if successful; false if file does not exist or is a directory
    
    抛出:
    
    IOException
  - setPermission
```
void setPermission(String src,
                 FsPermission permission)
                   throws IOException
```
    Set permissions for an existing file/directory.
    
    抛出:
    
    IOException
  - setOwner
```
void setOwner(String src,
            String username,
            String groupname)
              throws IOException
```
    Set owner of a path (i.e. a file or a directory). The parameters username and groupname cannot both be null.
    
    参数:
    src -
    username - If it is null, the original username remains unchanged.
    groupname - If it is null, the original groupname remains unchanged.
    
    抛出:
    
    IOException
  - abandonBlock
```
void abandonBlock(Block b,
                String src,
                String holder)
                  throws IOException
```
    The client can give up on a blcok by calling abandonBlock(). The client can then either obtain a new block, or complete or abandon the file. Any partial writes to the block will be discarded.
    
    抛出:
    
    IOException
  - addBlock
```
LocatedBlock addBlock(String src,
                    String clientName)
                      throws IOException
```
    已过时。 use the 3-arg form below
    
    A client that wants to write an additional block to the indicated filename (which must currently be open for writing) should call addBlock(). addBlock() allocates a new block and datanodes the block data should be replicated to.
    
    返回:
    LocatedBlock allocated block information.
    
    抛出:
    
    IOException
  - addBlock
```
LocatedBlock addBlock(String src,
                    String clientName,
                    DatanodeInfo[] excludedNodes)
                      throws IOException
```
    A client that wants to write an additional block to the indicated filename (which must currently be open for writing) should call addBlock(). addBlock() allocates a new block and datanodes the block data should be replicated to.
    
    参数:
    excludedNodes - a list of nodes that should not be allocated
    
    返回:
    LocatedBlock allocated block information.
    
    抛出:
    
    IOException
  - complete
```
boolean complete(String src,
               String clientName)
                 throws IOException
```
    The client is done writing data to the given filename, and would like to complete it. The function returns whether the file has been closed successfully. If the function returns false, the caller should try again. A call to complete() will not return true until all the file's blocks have been replicated the minimum number of times. Thus, DataNode failures may cause a client to call complete() several times before succeeding.
    
    抛出:
    
    IOException
  - reportBadBlocks
```
void reportBadBlocks(LocatedBlock[] blocks)
                     throws IOException
```
    The client wants to report corrupted blocks (blocks with specified locations on datanodes).
    
    参数:
    blocks - Array of located blocks to report
    
    抛出:
    
    IOException
  - rename
```
boolean rename(String src,
             String dst)
               throws IOException
```
    Rename an item in the file system namespace.
    
    参数:
    src - existing file or directory name.
    dst - new name.
    
    返回:
    true if successful, or false if the old name does not exist or if the new name already belongs to the namespace.
    
    抛出:
    
    IOException - if the new name is invalid.
    
    QuotaExceededException - if the rename would violate any quota restriction
  - concat
```
void concat(String trg,
          String[] srcs)
            throws IOException
```
    Moves blocks from srcs to trg and delete srcs
    
    参数:
    trg - existing file
    srcs - - list of existing files (same block size, same replication)
    
    抛出:
    
    IOException - if some arguments are invalid
  - delete
```
boolean delete(String src)
               throws IOException
```
    Delete the given file or directory from the file system.
    Any blocks belonging to the deleted files will be garbage-collected.
    
    参数:
    src - existing name.
    
    返回:
    true only if the existing file or directory was actually removed from the file system.
    
    抛出:
    
    IOException
  - delete
```
boolean delete(String src,
             boolean recursive)
               throws IOException
```
    Delete the given file or directory from the file system.
    same as delete but provides a way to avoid accidentally deleting non empty directories programmatically.
    
    参数:
    src - existing name
    recursive - if true deletes a non empty directory recursively, else throws an exception.
    
    返回:
    true only if the existing file or directory was actually removed from the file system.
    
    抛出:
    
    IOException
  - mkdirs
```
boolean mkdirs(String src,
             FsPermission masked)
               throws IOException
```
    Create a directory (or hierarchy of directories) with the given name and permission.
    
    参数:
    src - The path of the directory being created
    masked - The masked permission of the directory being created
    
    返回:
    True if the operation success.
    
    抛出:
    
    {@link - AccessControlException} if permission to create file is denied by the system. As usually on the client side the exception will be wraped into RemoteException.
    
    QuotaExceededException - if the operation would violate any quota restriction.
    
    IOException
  - getListing
```
DirectoryListing getListing(String src,
                          byte[] startAfter)
                            throws IOException
```
    Get a partial listing of the indicated directory
    
    参数:
    src - the directory name
    startAfter - the name of the last entry received by the client
    
    返回:
    a partial listing starting after startAfter
    
    抛出:
    
    IOException
  - renewLease
```
void renewLease(String clientName)
                throws IOException
```
    Client programs can cause stateful changes in the NameNode that affect other clients. A client may obtain a file and neither abandon nor complete it. A client might hold a series of locks that prevent other clients from proceeding. Clearly, it would be bad if a client held a bunch of locks that it never gave up. This can happen easily if the client dies unexpectedly.
    So, the NameNode will revoke the locks and live file-creates for clients that it thinks have died. A client tells the NameNode that it is still alive by periodically calling renewLease(). If a certain amount of time passes since the last call to renewLease(), the NameNode assumes the client has died.
    
    抛出:
    
    IOException
  - getStats
```
long[] getStats()
                throws IOException
```
    Get a set of statistics about the filesystem. Right now, only three values are returned.
    - [0] contains the total storage capacity of the system, in bytes.
    - [1] contains the total used space of the system, in bytes.
    - [2] contains the available storage of the system, in bytes.
    - [3] contains number of under replicated blocks in the system.
    - [4] contains number of blocks with a corrupt replica.
    - [5] contains number of blocks without any good replicas left.
    Use public constants like GET_STATS_CAPACITY_IDX in place of actual numbers to index into the array.
    抛出:
    
    IOException
  - getDatanodeReport
```
DatanodeInfo[] getDatanodeReport(FSConstants.DatanodeReportType type)
                                 throws IOException
```
    Get a report on the system's current datanodes. One DatanodeInfo object is returned for each DataNode. Return live datanodes if type is LIVE; dead datanodes if type is DEAD; otherwise all datanodes if type is ALL.
    
    抛出:
    
    IOException
  - getPreferredBlockSize
```
long getPreferredBlockSize(String filename)
                           throws IOException
```
    Get the block size for the given file.
    
    参数:
    filename - The name of the file
    
    返回:
    The number of bytes in each block
    
    抛出:
    
    IOException
  - setSafeMode
```
boolean setSafeMode(FSConstants.SafeModeAction action)
                    throws IOException
```
    Enter, leave or get safe mode.
    Safe mode is a name node state when it
    1. does not accept changes to name space (read-only), and
    2. does not replicate or delete blocks.
    Safe mode is entered automatically at name node startup. Safe mode can also be entered manually using setSafeMode(SafeModeAction.SAFEMODE_GET).
    At startup the name node accepts data node reports collecting information about block locations. In order to leave safe mode it needs to collect a configurable percentage called threshold of blocks, which satisfy the minimal replication condition. The minimal replication condition is that each block must have at least dfs.replication.min replicas. When the threshold is reached the name node extends safe mode for a configurable amount of time to let the remaining data nodes to check in before it will start replicating missing blocks. Then the name node leaves safe mode.
    If safe mode is turned on manually using setSafeMode(SafeModeAction.SAFEMODE_ENTER) then the name node stays in safe mode until it is manually turned off using setSafeMode(SafeModeAction.SAFEMODE_LEAVE). Current state of the name node can be verified using setSafeMode(SafeModeAction.SAFEMODE_GET)
    Configuration parameters:
    dfs.safemode.threshold.pct is the threshold parameter.
    dfs.safemode.extension is the safe mode extension parameter.
    dfs.replication.min is the minimal replication parameter.
    Special cases:
    The name node does not enter safe mode at startup if the threshold is set to 0 or if the name space is empty.
    If the threshold is set to 1 then all blocks need to have at least minimal replication.
    If the threshold value is greater than 1 then the name node will not be able to turn off safe mode automatically.
    Safe mode can always be turned off manually.
    参数:
    action -
    
    0 leave safe mode;
    
    1 enter safe mode;
    
    2 get safe mode state.
    返回:
    0 if the safe mode is OFF or
    
    1 if the safe mode is ON.
    抛出:
    
    IOException
  - saveNamespace
```
void saveNamespace()
                   throws IOException
```
    Save namespace image.
    Saves current namespace into storage directories and reset edits log. Requires superuser privilege and safe mode.
    
    抛出:
    
    AccessControlException - if the superuser privilege is violated.
    
    IOException - if image creation failed.
  - refreshNodes
```
void refreshNodes()
                  throws IOException
```
    Tells the namenode to reread the hosts and exclude files.
    
    抛出:
    
    IOException
  - finalizeUpgrade
```
void finalizeUpgrade()
                     throws IOException
```
    Finalize previous upgrade. Remove file system state saved during the upgrade. The upgrade will become irreversible.
    
    抛出:
    
    IOException
  - distributedUpgradeProgress
```
UpgradeStatusReport distributedUpgradeProgress(FSConstants.UpgradeAction action)
                                               throws IOException
```
    Report distributed upgrade progress or force current upgrade to proceed.
    
    参数:
    action - FSConstants.UpgradeAction to perform
    
    返回:
    upgrade status information or null if no upgrades are in progress
    
    抛出:
    
    IOException
  - metaSave
```
void metaSave(String filename)
              throws IOException
```
    Dumps namenode data structures into specified file. If file already exists, then append.
    
    抛出:
    
    IOException
  - setBalancerBandwidth
```
void setBalancerBandwidth(long bandwidth)
                          throws IOException
```
    Tell all datanodes to use a new, non-persistent bandwidth value for dfs.balance.bandwidthPerSec.
    
    参数:
    bandwidth - Blanacer bandwidth in bytes per second for this datanode.
    
    抛出:
    
    IOException
  - getFileInfo
```
HdfsFileStatus getFileInfo(String src)
                           throws IOException
```
    Get the file info for a specific file or directory.
    
    参数:
    src - The string representation of the path to the file
    
    返回:
    object containing information regarding the file or null if file not found
    
    抛出:
    
    IOException - if permission to access file is denied by the system
  - getContentSummary
```
ContentSummary getContentSummary(String path)
                                 throws IOException
```
    Get ContentSummary rooted at the specified directory.
    
    参数:
    path - The string representation of the path
    
    抛出:
    
    IOException
  - setQuota
```
void setQuota(String path,
            long namespaceQuota,
            long diskspaceQuota)
              throws IOException
```
    Set the quota for a directory.
    
    参数:
    path - The string representation of the path to the directory
    namespaceQuota - Limit on the number of names in the tree rooted at the directory
    diskspaceQuota - Limit on disk space occupied all the files under this directory.
    
    The quota can have three types of values : (1) 0 or more will set the quota to that value, (2) FSConstants.QUOTA_DONT_SET implies the quota will not be changed, and (3) FSConstants.QUOTA_RESET implies the quota will be reset. Any other value is a runtime error.
    
    抛出:
    
    FileNotFoundException - if the path is a file or does not exist
    
    QuotaExceededException - if the directory size is greater than the given quota
    
    IOException
  - fsync
```
void fsync(String src,
         String client)
           throws IOException
```
    Write all metadata for this file into persistent storage. The file must be currently open for writing.
    
    参数:
    src - The string representation of the path
    client - The string representation of the client
    
    抛出:
    
    IOException
  - setTimes
```
void setTimes(String src,
            long mtime,
            long atime)
              throws IOException
```
    Sets the modification and access time of the file to the specified time.
    
    参数:
    src - The string representation of the path
    mtime - The number of milliseconds since Jan 1, 1970. Setting mtime to -1 means that modification time should not be set by this call.
    atime - The number of milliseconds since Jan 1, 1970. Setting atime to -1 means that access time should not be set by this call.
    
    抛出:
    
    IOException
  - getDelegationToken
```
Token<DelegationTokenIdentifier> getDelegationToken(Text renewer)
                                                    throws IOException
```
    Get a valid Delegation Token.
    
    参数:
    renewer - the designated renewer for the token
    
    返回:
    Token
    
    抛出:
    
    IOException
  - renewDelegationToken
```
long renewDelegationToken(Token<DelegationTokenIdentifier> token)
                          throws IOException
```
    Renew an existing delegation token.
    
    参数:
    token - delegation token obtained earlier
    
    返回:
    the new expiration time
    
    抛出:
    
    IOException
  - cancelDelegationToken
```
void cancelDelegationToken(Token<DelegationTokenIdentifier> token)
                           throws IOException
```
    Cancel an existing delegation token.
    
    参数:
    token - delegation token
    
    抛出:
    
    IOException

接口 ClientProtocol

字段概要

方法概要

从接口继承的方法 org.apache.hadoop.ipc.VersionedProtocol

字段详细资料

versionID

GET_STATS_CAPACITY_IDX

GET_STATS_USED_IDX

GET_STATS_REMAINING_IDX

GET_STATS_UNDER_REPLICATED_IDX

GET_STATS_CORRUPT_BLOCKS_IDX

GET_STATS_MISSING_BLOCKS_IDX

方法详细资料

getBlockLocations

create

create

append

recoverLease

isFileClosed

setReplication

setPermission

setOwner

abandonBlock

addBlock

addBlock

complete

reportBadBlocks

rename

concat

delete

delete

mkdirs

getListing

renewLease

getStats

getDatanodeReport

getPreferredBlockSize

setSafeMode

Configuration parameters:

Special cases:

saveNamespace

refreshNodes

finalizeUpgrade

distributedUpgradeProgress

metaSave

setBalancerBandwidth

getFileInfo

getContentSummary

setQuota

fsync

setTimes

getDelegationToken

renewDelegationToken

cancelDelegationToken