ClientProtocol (Apache Hadoop Main 2.2.0 API)

All Known Subinterfaces:

NamenodeProtocols

All Known Implementing Classes:

ClientNamenodeProtocolTranslatorPB
```
@InterfaceAudience.Private
@InterfaceStability.Evolving
public interface ClientProtocol
```
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.

Field Summary

Fields
Modifier and Type	Field and Description
`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` Until version 69, this class ClientProtocol served as both the client interface to the NN AND the RPC protocol used to communicate with the NN.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`abandonBlock(ExtendedBlock b, String src, String holder)` The client can give up on a block by calling abandonBlock().
`LocatedBlock`	`addBlock(String src, String clientName, ExtendedBlock previous, DatanodeInfo[] excludeNodes, long fileId, String[] favoredNodes)` A client that wants to write an additional block to the indicated filename (which must currently be open for writing) should call addBlock().
`void`	`allowSnapshot(String snapshotRoot)` Allow snapshot on a directory.
`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, ExtendedBlock last, long fileId)` 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
`HdfsFileStatus`	`create(String src, FsPermission masked, String clientName, EnumSetWritable<CreateFlag> flag, boolean createParent, short replication, long blockSize)` Create a new file entry in the namespace.
`String`	`createSnapshot(String snapshotRoot, String snapshotName)` Create a snapshot
`void`	`createSymlink(String target, String link, FsPermission dirPerm, boolean createParent)` Create symlink to a file or directory.
`boolean`	`delete(String src, boolean recursive)` Delete the given file or directory from the file system.
`void`	`deleteSnapshot(String snapshotRoot, String snapshotName)` Delete a specific snapshot of a snapshottable directory
`void`	`disallowSnapshot(String snapshotRoot)` Disallow snapshot on a directory.
`void`	`finalizeUpgrade()` Finalize previous upgrade.
`void`	`fsync(String src, String client, long lastBlockLength)` Write all metadata for this file into persistent storage.
`LocatedBlock`	`getAdditionalDatanode(String src, ExtendedBlock blk, DatanodeInfo[] existings, DatanodeInfo[] excludes, int numAdditionalNodes, String clientName)` Get a datanode for an existing pipeline.
`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.
`DataEncryptionKey`	`getDataEncryptionKey()`
`DatanodeInfo[]`	`getDatanodeReport(HdfsConstants.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.
`HdfsFileStatus`	`getFileLinkInfo(String src)` Get the file info for a specific file or directory.
`String`	`getLinkTarget(String path)` Return the target of the given symlink.
`DirectoryListing`	`getListing(String src, byte[] startAfter, boolean needLocation)` Get a partial listing of the indicated directory
`long`	`getPreferredBlockSize(String filename)` Get the block size for the given file.
`FsServerDefaults`	`getServerDefaults()` Get server default values for a number of configuration params.
`SnapshotDiffReport`	`getSnapshotDiffReport(String snapshotRoot, String fromSnapshot, String toSnapshot)` Get the difference between two snapshots, or between a snapshot and the current tree of a directory.
`SnapshottableDirectoryStatus[]`	`getSnapshottableDirListing()` Get listing of all the snapshottable directories
`long[]`	`getStats()` Get a set of statistics about the filesystem.
`boolean`	`isFileClosed(String src)` Get the close status of a file
`CorruptFileBlocks`	`listCorruptFileBlocks(String path, String cookie)`
`void`	`metaSave(String filename)` Dumps namenode data structures into specified file.
`boolean`	`mkdirs(String src, FsPermission masked, boolean createParent)` 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.
`void`	`rename2(String src, String dst, Options.Rename... options)` Rename src to dst.
`void`	`renameSnapshot(String snapshotRoot, String snapshotOldName, String snapshotNewName)` Rename a snapshot
`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).
`boolean`	`restoreFailedStorage(String arg)` Enable/Disable restore failed storage.
`long`	`rollEdits()` Roll the edit log.
`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.
`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(HdfsConstants.SafeModeAction action, boolean isChecked)` 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.
`LocatedBlock`	`updateBlockForPipeline(ExtendedBlock block, String clientName)` Get a new generation stamp together with an access token for a block under construction This method is called only when a client needs to recover a failed pipeline or set up a pipeline for appending to a block.
`void`	`updatePipeline(String clientName, ExtendedBlock oldBlock, ExtendedBlock newBlock, DatanodeID[] newNodes)` Update a pipeline for a block under construction

- Field Detail
  - versionID
```
static final long versionID
```
    Until version 69, this class ClientProtocol served as both the client interface to the NN AND the RPC protocol used to communicate with the NN. This class is used by both the DFSClient and the NN server side to insulate from the protocol serialization. If you are adding/changing this interface then you need to change both this class and ALSO related protocol buffer wire protocol definition in ClientNamenodeProtocol.proto. For more details on protocol buffer wire protocol, please see .../org/apache/hadoop/hdfs/protocolPB/overview.html The log of historical changes can be retrieved from the svn). 69: Eliminate overloaded method names. 69L is the last version id when this class was used for protocols serialization. DO not update this version any further.
    
    See Also:
    Constant Field Values
  - GET_STATS_CAPACITY_IDX
```
static final int GET_STATS_CAPACITY_IDX
```
    See Also:
    Constant Field Values
  - GET_STATS_USED_IDX
```
static final int GET_STATS_USED_IDX
```
    See Also:
    Constant Field Values
  - GET_STATS_REMAINING_IDX
```
static final int GET_STATS_REMAINING_IDX
```
    See Also:
    Constant Field Values
  - GET_STATS_UNDER_REPLICATED_IDX
```
static final int GET_STATS_UNDER_REPLICATED_IDX
```
    See Also:
    Constant Field Values
  - GET_STATS_CORRUPT_BLOCKS_IDX
```
static final int GET_STATS_CORRUPT_BLOCKS_IDX
```
    See Also:
    Constant Field Values
  - GET_STATS_MISSING_BLOCKS_IDX
```
static final int GET_STATS_MISSING_BLOCKS_IDX
```
    See Also:
    Constant Field Values
- Method Detail
  - getBlockLocations
```
LocatedBlocks getBlockLocations(String src,
                              long offset,
                              long length)
                                throws AccessControlException,
                                       FileNotFoundException,
                                       UnresolvedLinkException,
                                       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.
    
    Parameters:
    src - file name
    offset - range start offset
    length - range length
    
    Returns:
    file length and array of blocks with their locations
    
    Throws:
    
    AccessControlException - If access is denied
    
    FileNotFoundException - If file src does not exist
    
    UnresolvedLinkException - If src contains a symlink
    
    IOException - If an I/O error occurred
  - getServerDefaults
```
FsServerDefaults getServerDefaults()
                                   throws IOException
```
    Get server default values for a number of configuration params.
    
    Returns:
    a set of server default configuration values
    
    Throws:
    
    IOException
  - create
```
HdfsFileStatus create(String src,
                    FsPermission masked,
                    String clientName,
                    EnumSetWritable<CreateFlag> flag,
                    boolean createParent,
                    short replication,
                    long blockSize)
                      throws AccessControlException,
                             AlreadyBeingCreatedException,
                             DSQuotaExceededException,
                             FileAlreadyExistsException,
                             FileNotFoundException,
                             NSQuotaExceededException,
                             ParentNotDirectoryException,
                             SafeModeException,
                             UnresolvedLinkException,
                             SnapshotAccessControlException,
                             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, boolean), 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(java.lang.String, java.lang.String, org.apache.hadoop.hdfs.protocol.ExtendedBlock, org.apache.hadoop.hdfs.protocol.DatanodeInfo[], long, java.lang.String[])
    
    Parameters:
    src - path of the file being created.
    masked - masked permission.
    clientName - name of the current client.
    flag - indicates whether the file should be overwritten if it already exists or create if it does not exist or append.
    createParent - create missing parent directory if true
    replication - block replication factor.
    blockSize - maximum block size.
    
    Returns:
    the status of the created file, it could be null if the server doesn't support returning the file status
    
    Throws:
    
    AccessControlException - If access is denied
    
    AlreadyBeingCreatedException - if the path does not exist.
    
    DSQuotaExceededException - If file creation violates disk space quota restriction
    
    FileAlreadyExistsException - If file src already exists
    
    FileNotFoundException - If parent of src does not exist and createParent is false
    
    ParentNotDirectoryException - If parent of src is not a directory.
    
    NSQuotaExceededException - If file creation violates name space quota restriction
    
    SafeModeException - create not allowed in safemode
    
    UnresolvedLinkException - If src contains a symlink
    
    SnapshotAccessControlException - if path is in RO snapshot
    
    IOException - If an I/O error occurred RuntimeExceptions:
    
    InvalidPathException - Path src is invalid
    Note that create with CreateFlag.OVERWRITE is idempotent.
  - append
```
LocatedBlock append(String src,
                  String clientName)
                    throws AccessControlException,
                           DSQuotaExceededException,
                           FileNotFoundException,
                           SafeModeException,
                           UnresolvedLinkException,
                           SnapshotAccessControlException,
                           IOException
```
    Append to the end of the file.
    
    Parameters:
    src - path of the file being created.
    clientName - name of the current client.
    
    Returns:
    information about the last partial block if any.
    
    Throws:
    
    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.append set to true, otherwise throws an IOException.
    
    AccessControlException - If permission to append to file is denied
    
    FileNotFoundException - If file src is not found
    
    DSQuotaExceededException - If append violates disk space quota restriction
    
    SafeModeException - append not allowed in safemode
    
    UnresolvedLinkException - If src contains a symlink
    
    SnapshotAccessControlException - if path is in RO snapshot
    
    IOException - If an I/O error occurred. RuntimeExceptions:
    
    UnsupportedOperationException - if append is not supported
  - setReplication
```
boolean setReplication(String src,
                     short replication)
                       throws AccessControlException,
                              DSQuotaExceededException,
                              FileNotFoundException,
                              SafeModeException,
                              UnresolvedLinkException,
                              SnapshotAccessControlException,
                              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.
    
    Parameters:
    src - file name
    replication - new replication
    
    Returns:
    true if successful; false if file does not exist or is a directory
    
    Throws:
    
    AccessControlException - If access is denied
    
    DSQuotaExceededException - If replication violates disk space quota restriction
    
    FileNotFoundException - If file src is not found
    
    SafeModeException - not allowed in safemode
    
    UnresolvedLinkException - if src contains a symlink
    
    SnapshotAccessControlException - if path is in RO snapshot
    
    IOException - If an I/O error occurred
  - setPermission
```
void setPermission(String src,
                 FsPermission permission)
                   throws AccessControlException,
                          FileNotFoundException,
                          SafeModeException,
                          UnresolvedLinkException,
                          SnapshotAccessControlException,
                          IOException
```
    Set permissions for an existing file/directory.
    
    Throws:
    
    AccessControlException - If access is denied
    
    FileNotFoundException - If file src is not found
    
    SafeModeException - not allowed in safemode
    
    UnresolvedLinkException - If src contains a symlink
    
    SnapshotAccessControlException - if path is in RO snapshot
    
    IOException - If an I/O error occurred
  - setOwner
```
void setOwner(String src,
            String username,
            String groupname)
              throws AccessControlException,
                     FileNotFoundException,
                     SafeModeException,
                     UnresolvedLinkException,
                     SnapshotAccessControlException,
                     IOException
```
    Set Owner of a path (i.e. a file or a directory). The parameters username and groupname cannot both be null.
    
    Parameters:
    src -
    username - If it is null, the original username remains unchanged.
    groupname - If it is null, the original groupname remains unchanged.
    
    Throws:
    
    AccessControlException - If access is denied
    
    FileNotFoundException - If file src is not found
    
    SafeModeException - not allowed in safemode
    
    UnresolvedLinkException - If src contains a symlink
    
    SnapshotAccessControlException - if path is in RO snapshot
    
    IOException - If an I/O error occurred
  - abandonBlock
```
void abandonBlock(ExtendedBlock b,
                String src,
                String holder)
                  throws AccessControlException,
                         FileNotFoundException,
                         UnresolvedLinkException,
                         IOException
```
    The client can give up on a block 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.
    
    Throws:
    
    AccessControlException - If access is denied
    
    FileNotFoundException - file src is not found
    
    UnresolvedLinkException - If src contains a symlink
    
    IOException - If an I/O error occurred
  - addBlock
```
LocatedBlock addBlock(String src,
                    String clientName,
                    ExtendedBlock previous,
                    DatanodeInfo[] excludeNodes,
                    long fileId,
                    String[] favoredNodes)
                      throws AccessControlException,
                             FileNotFoundException,
                             NotReplicatedYetException,
                             SafeModeException,
                             UnresolvedLinkException,
                             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. addBlock() also commits the previous block by reporting to the name-node the actual generation stamp and the length of the block that the client has transmitted to data-nodes.
    
    Parameters:
    src - the file being created
    clientName - the name of the client that adds the block
    previous - previous block
    excludeNodes - a list of nodes that should not be allocated for the current block
    fileId - the id uniquely identifying a file
    favoredNodes - the list of nodes where the client wants the blocks. Nodes are identified by either host name or address.
    
    Returns:
    LocatedBlock allocated block information.
    
    Throws:
    
    AccessControlException - If access is denied
    
    FileNotFoundException - If file src is not found
    
    NotReplicatedYetException - previous blocks of the file are not replicated yet. Blocks cannot be added until replication completes.
    
    SafeModeException - create not allowed in safemode
    
    UnresolvedLinkException - If src contains a symlink
    
    IOException - If an I/O error occurred
  - getAdditionalDatanode
```
LocatedBlock getAdditionalDatanode(String src,
                                 ExtendedBlock blk,
                                 DatanodeInfo[] existings,
                                 DatanodeInfo[] excludes,
                                 int numAdditionalNodes,
                                 String clientName)
                                   throws AccessControlException,
                                          FileNotFoundException,
                                          SafeModeException,
                                          UnresolvedLinkException,
                                          IOException
```
    Get a datanode for an existing pipeline.
    
    Parameters:
    src - the file being written
    blk - the block being written
    existings - the existing nodes in the pipeline
    excludes - the excluded nodes
    numAdditionalNodes - number of additional datanodes
    clientName - the name of the client
    
    Returns:
    the located block.
    
    Throws:
    
    AccessControlException - If access is denied
    
    FileNotFoundException - If file src is not found
    
    SafeModeException - create not allowed in safemode
    
    UnresolvedLinkException - If src contains a symlink
    
    IOException - If an I/O error occurred
  - complete
```
boolean complete(String src,
               String clientName,
               ExtendedBlock last,
               long fileId)
                 throws AccessControlException,
                        FileNotFoundException,
                        SafeModeException,
                        UnresolvedLinkException,
                        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. close() also commits the last block of file by reporting to the name-node the actual generation stamp and the length of the block that the client has transmitted to data-nodes. 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.
    
    Parameters:
    src - the file being created
    clientName - the name of the client that adds the block
    last - the last block info
    fileId - the id uniquely identifying a file
    
    Returns:
    true if all file blocks are minimally replicated or false otherwise
    
    Throws:
    
    AccessControlException - If access is denied
    
    FileNotFoundException - If file src is not found
    
    SafeModeException - create not allowed in safemode
    
    UnresolvedLinkException - If src contains a symlink
    
    IOException - If an I/O error occurred
  - reportBadBlocks
```
void reportBadBlocks(LocatedBlock[] blocks)
                     throws IOException
```
    The client wants to report corrupted blocks (blocks with specified locations on datanodes).
    
    Parameters:
    blocks - Array of located blocks to report
    
    Throws:
    
    IOException
  - rename
```
boolean rename(String src,
             String dst)
               throws UnresolvedLinkException,
                      SnapshotAccessControlException,
                      IOException
```
    Rename an item in the file system namespace.
    
    Parameters:
    src - existing file or directory name.
    dst - new name.
    
    Returns:
    true if successful, or false if the old name does not exist or if the new name already belongs to the namespace.
    
    Throws:
    
    SnapshotAccessControlException - if path is in RO snapshot
    
    IOException - an I/O error occurred
    
    UnresolvedLinkException
  - concat
```
void concat(String trg,
          String[] srcs)
            throws IOException,
                   UnresolvedLinkException,
                   SnapshotAccessControlException
```
    Moves blocks from srcs to trg and delete srcs
    
    Parameters:
    trg - existing file
    srcs - - list of existing files (same block size, same replication)
    
    Throws:
    
    IOException - if some arguments are invalid
    
    UnresolvedLinkException - if trg or srcs contains a symlink
    
    SnapshotAccessControlException - if path is in RO snapshot
  - rename2
```
void rename2(String src,
           String dst,
           Options.Rename... options)
             throws AccessControlException,
                    DSQuotaExceededException,
                    FileAlreadyExistsException,
                    FileNotFoundException,
                    NSQuotaExceededException,
                    ParentNotDirectoryException,
                    SafeModeException,
                    UnresolvedLinkException,
                    SnapshotAccessControlException,
                    IOException
```
    Rename src to dst.
    - Fails if src is a file and dst is a directory.
    - Fails if src is a directory and dst is a file.
    - Fails if the parent of dst does not exist or is a file.
    Without OVERWRITE option, rename fails if the dst already exists. With OVERWRITE option, rename overwrites the dst, if it is a file or an empty directory. Rename fails if dst is a non-empty directory.
    This implementation of rename is atomic.
    Parameters:
    src - existing file or directory name.
    dst - new name.
    options - Rename options
    
    Throws:
    
    AccessControlException - If access is denied
    
    DSQuotaExceededException - If rename violates disk space quota restriction
    
    FileAlreadyExistsException - If dst already exists and options has Options.Rename.OVERWRITE option false.
    FileNotFoundException - If src does not exist NSQuotaExceededException - If rename violates namespace quota restriction ParentNotDirectoryException - If parent of dst is not a directory SafeModeException - rename not allowed in safemode UnresolvedLinkException - If src or dst contains a symlink SnapshotAccessControlException - if path is in RO snapshot IOException - If an I/O error occurred
  delete boolean delete(String src, boolean recursive) throws AccessControlException, FileNotFoundException, SafeModeException, UnresolvedLinkException, SnapshotAccessControlException, 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. Parameters: src - existing name recursive - if true deletes a non empty directory recursively, else throws an exception. Returns: true only if the existing file or directory was actually removed from the file system. Throws: AccessControlException - If access is denied FileNotFoundException - If file src is not found SafeModeException - create not allowed in safemode UnresolvedLinkException - If src contains a symlink SnapshotAccessControlException - if path is in RO snapshot IOException - If an I/O error occurred mkdirs boolean mkdirs(String src, FsPermission masked, boolean createParent) throws AccessControlException, FileAlreadyExistsException, FileNotFoundException, NSQuotaExceededException, ParentNotDirectoryException, SafeModeException, UnresolvedLinkException, SnapshotAccessControlException, IOException Create a directory (or hierarchy of directories) with the given name and permission. Parameters: src - The path of the directory being created masked - The masked permission of the directory being created createParent - create missing parent directory if true Returns: True if the operation success. Throws: AccessControlException - If access is denied FileAlreadyExistsException - If src already exists FileNotFoundException - If parent of src does not exist and createParent is false NSQuotaExceededException - If file creation violates quota restriction ParentNotDirectoryException - If parent of src is not a directory SafeModeException - create not allowed in safemode UnresolvedLinkException - If src contains a symlink SnapshotAccessControlException - if path is in RO snapshot IOException - If an I/O error occurred. RunTimeExceptions: InvalidPathException - If src is invalid getListing DirectoryListing getListing(String src, byte[] startAfter, boolean needLocation) throws AccessControlException, FileNotFoundException, UnresolvedLinkException, IOException Get a partial listing of the indicated directory Parameters: src - the directory name startAfter - the name to start listing after encoded in java UTF8 needLocation - if the FileStatus should contain block locations Returns: a partial listing starting after startAfter Throws: AccessControlException - permission denied FileNotFoundException - file src is not found UnresolvedLinkException - If src contains a symlink IOException - If an I/O error occurred getSnapshottableDirListing SnapshottableDirectoryStatus[] getSnapshottableDirListing() throws IOException Get listing of all the snapshottable directories Returns: Information about all the current snapshottable directory Throws: IOException - If an I/O error occurred renewLease void renewLease(String clientName) throws AccessControlException, 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. Throws: AccessControlException - permission denied IOException - If an I/O error occurred recoverLease boolean recoverLease(String src, String clientName) throws IOException Start lease recovery. Lightweight NameNode operation to trigger lease recovery Parameters: src - path of the file to start lease recovery clientName - name of the current client Returns: true if the file is already closed Throws: IOException getStats long[] getStats() throws IOException Get a set of statistics about the filesystem. Right now, only seven 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. [6] contains the total used space of the block pool. Use public constants like GET_STATS_CAPACITY_IDX in place of actual numbers to index into the array. Throws: IOException getDatanodeReport DatanodeInfo[] getDatanodeReport(HdfsConstants.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. Throws: IOException getPreferredBlockSize long getPreferredBlockSize(String filename) throws IOException, UnresolvedLinkException Get the block size for the given file. Parameters: filename - The name of the file Returns: The number of bytes in each block Throws: IOException UnresolvedLinkException - if the path contains a symlink. setSafeMode boolean setSafeMode(HdfsConstants.SafeModeAction action, boolean isChecked) throws IOException Enter, leave or get safe mode. Safe mode is a name node state when it does not accept changes to name space (read-only), and 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_ENTER,false). 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.namenode.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,false) then the name node stays in safe mode until it is manually turned off using setSafeMode(SafeModeAction.SAFEMODE_LEAVE,false). Current state of the name node can be verified using setSafeMode(SafeModeAction.SAFEMODE_GET,false) Configuration parameters: dfs.safemode.threshold.pct is the threshold parameter. dfs.safemode.extension is the safe mode extension parameter. dfs.namenode.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. Parameters: action - 0 leave safe mode; 1 enter safe mode; 2 get safe mode state. isChecked - If true then action will be done only in ActiveNN. Returns: 0 if the safe mode is OFF or 1 if the safe mode is ON. Throws: IOException saveNamespace void saveNamespace() throws AccessControlException, IOException Save namespace image. Saves current namespace into storage directories and reset edits log. Requires superuser privilege and safe mode. Throws: AccessControlException - if the superuser privilege is violated. IOException - if image creation failed. rollEdits long rollEdits() throws AccessControlException, IOException Roll the edit log. Requires superuser privileges. Returns: the txid of the new segment Throws: AccessControlException - if the superuser privilege is violated IOException - if log roll fails restoreFailedStorage boolean restoreFailedStorage(String arg) throws AccessControlException, IOException Enable/Disable restore failed storage. sets flag to enable restore of failed storage replicas Throws: AccessControlException - if the superuser privilege is violated. IOException refreshNodes void refreshNodes() throws IOException Tells the namenode to reread the hosts and exclude files. Throws: IOException finalizeUpgrade void finalizeUpgrade() throws IOException Finalize previous upgrade. Remove file system state saved during the upgrade. The upgrade will become irreversible. Throws: IOException listCorruptFileBlocks CorruptFileBlocks listCorruptFileBlocks(String path, String cookie) throws IOException Returns: CorruptFileBlocks, containing a list of corrupt files (with duplicates if there is more than one corrupt block in a file) and a cookie Throws: IOException - Each call returns a subset of the corrupt files in the system. To obtain all corrupt files, call this method repeatedly and each time pass in the cookie returned from the previous call. metaSave void metaSave(String filename) throws IOException Dumps namenode data structures into specified file. If the file already exists, then append. Throws: IOException setBalancerBandwidth void setBalancerBandwidth(long bandwidth) throws IOException Tell all datanodes to use a new, non-persistent bandwidth value for dfs.balance.bandwidthPerSec. Parameters: bandwidth - Blanacer bandwidth in bytes per second for this datanode. Throws: IOException getFileInfo HdfsFileStatus getFileInfo(String src) throws AccessControlException, FileNotFoundException, UnresolvedLinkException, IOException Get the file info for a specific file or directory. Parameters: src - The string representation of the path to the file Returns: object containing information regarding the file or null if file not found Throws: AccessControlException - permission denied FileNotFoundException - file src is not found UnresolvedLinkException - if the path contains a symlink. IOException - If an I/O error occurred isFileClosed boolean isFileClosed(String src) throws AccessControlException, FileNotFoundException, UnresolvedLinkException, IOException Get the close status of a file Parameters: src - The string representation of the path to the file Returns: return true if file is closed Throws: AccessControlException - permission denied FileNotFoundException - file src is not found UnresolvedLinkException - if the path contains a symlink. IOException - If an I/O error occurred getFileLinkInfo HdfsFileStatus getFileLinkInfo(String src) throws AccessControlException, UnresolvedLinkException, IOException Get the file info for a specific file or directory. If the path refers to a symlink then the FileStatus of the symlink is returned. Parameters: src - The string representation of the path to the file Returns: object containing information regarding the file or null if file not found Throws: AccessControlException - permission denied UnresolvedLinkException - if src contains a symlink IOException - If an I/O error occurred getContentSummary ContentSummary getContentSummary(String path) throws AccessControlException, FileNotFoundException, UnresolvedLinkException, IOException Get ContentSummary rooted at the specified directory. Parameters: path - The string representation of the path Throws: AccessControlException - permission denied FileNotFoundException - file path is not found UnresolvedLinkException - if path contains a symlink. IOException - If an I/O error occurred setQuota void setQuota(String path, long namespaceQuota, long diskspaceQuota) throws AccessControlException, FileNotFoundException, UnresolvedLinkException, SnapshotAccessControlException, IOException Set the quota for a directory. Parameters: 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) HdfsConstants.QUOTA_DONT_SET implies the quota will not be changed, and (3) HdfsConstants.QUOTA_RESET implies the quota will be reset. Any other value is a runtime error. Throws: AccessControlException - permission denied FileNotFoundException - file path is not found QuotaExceededException - if the directory size is greater than the given quota UnresolvedLinkException - if the path contains a symlink. SnapshotAccessControlException - if path is in RO snapshot IOException - If an I/O error occurred fsync void fsync(String src, String client, long lastBlockLength) throws AccessControlException, FileNotFoundException, UnresolvedLinkException, IOException Write all metadata for this file into persistent storage. The file must be currently open for writing. Parameters: src - The string representation of the path client - The string representation of the client lastBlockLength - The length of the last block (under construction) to be reported to NameNode Throws: AccessControlException - permission denied FileNotFoundException - file src is not found UnresolvedLinkException - if src contains a symlink. IOException - If an I/O error occurred setTimes void setTimes(String src, long mtime, long atime) throws AccessControlException, FileNotFoundException, UnresolvedLinkException, SnapshotAccessControlException, IOException Sets the modification and access time of the file to the specified time. Parameters: 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. Throws: AccessControlException - permission denied FileNotFoundException - file src is not found UnresolvedLinkException - if src contains a symlink. SnapshotAccessControlException - if path is in RO snapshot IOException - If an I/O error occurred createSymlink void createSymlink(String target, String link, FsPermission dirPerm, boolean createParent) throws AccessControlException, FileAlreadyExistsException, FileNotFoundException, ParentNotDirectoryException, SafeModeException, UnresolvedLinkException, SnapshotAccessControlException, IOException Create symlink to a file or directory. Parameters: target - The path of the destination that the link points to. link - The path of the link being created. dirPerm - permissions to use when creating parent directories createParent - - if true then missing parent dirs are created if false then parent must exist Throws: AccessControlException - permission denied FileAlreadyExistsException - If file link already exists FileNotFoundException - If parent of link does not exist and createParent is false ParentNotDirectoryException - If parent of link is not a directory. UnresolvedLinkException - if link contains a symlink. SnapshotAccessControlException - if path is in RO snapshot IOException - If an I/O error occurred SafeModeException getLinkTarget String getLinkTarget(String path) throws AccessControlException, FileNotFoundException, IOException Return the target of the given symlink. If there is an intermediate symlink in the path (ie a symlink leading up to the final path component) then the given path is returned with this symlink resolved. Parameters: path - The path with a link that needs resolution. Returns: The path after resolving the first symbolic link in the path. Throws: AccessControlException - permission denied FileNotFoundException - If path does not exist IOException - If the given path does not refer to a symlink or an I/O error occurred updateBlockForPipeline LocatedBlock updateBlockForPipeline(ExtendedBlock block, String clientName) throws IOException Get a new generation stamp together with an access token for a block under construction This method is called only when a client needs to recover a failed pipeline or set up a pipeline for appending to a block. Parameters: block - a block clientName - the name of the client Returns: a located block with a new generation stamp and an access token Throws: IOException - if any error occurs updatePipeline void updatePipeline(String clientName, ExtendedBlock oldBlock, ExtendedBlock newBlock, DatanodeID[] newNodes) throws IOException Update a pipeline for a block under construction Parameters: clientName - the name of the client oldBlock - the old block newBlock - the new block containing new generation stamp and length newNodes - datanodes in the pipeline Throws: IOException - if any error occurs getDelegationToken Token<DelegationTokenIdentifier> getDelegationToken(Text renewer) throws IOException Get a valid Delegation Token. Parameters: renewer - the designated renewer for the token Returns: Token Throws: IOException renewDelegationToken long renewDelegationToken(Token<DelegationTokenIdentifier> token) throws IOException Renew an existing delegation token. Parameters: token - delegation token obtained earlier Returns: the new expiration time Throws: IOException cancelDelegationToken void cancelDelegationToken(Token<DelegationTokenIdentifier> token) throws IOException Cancel an existing delegation token. Parameters: token - delegation token Throws: IOException getDataEncryptionKey DataEncryptionKey getDataEncryptionKey() throws IOException Returns: encryption key so a client can encrypt data sent via the DataTransferProtocol to/from DataNodes. Throws: IOException createSnapshot String createSnapshot(String snapshotRoot, String snapshotName) throws IOException Create a snapshot Parameters: snapshotRoot - the path that is being snapshotted snapshotName - name of the snapshot created Returns: the snapshot path. Throws: IOException deleteSnapshot void deleteSnapshot(String snapshotRoot, String snapshotName) throws IOException Delete a specific snapshot of a snapshottable directory Parameters: snapshotRoot - The snapshottable directory snapshotName - Name of the snapshot for the snapshottable directory Throws: IOException renameSnapshot void renameSnapshot(String snapshotRoot, String snapshotOldName, String snapshotNewName) throws IOException Rename a snapshot Parameters: snapshotRoot - the directory path where the snapshot was taken snapshotOldName - old name of the snapshot snapshotNewName - new name of the snapshot Throws: IOException allowSnapshot void allowSnapshot(String snapshotRoot) throws IOException Allow snapshot on a directory. Parameters: snapshotRoot - the directory to be snapped Throws: IOException - on error disallowSnapshot void disallowSnapshot(String snapshotRoot) throws IOException Disallow snapshot on a directory. Parameters: snapshotRoot - the directory to disallow snapshot Throws: IOException - on error getSnapshotDiffReport SnapshotDiffReport getSnapshotDiffReport(String snapshotRoot, String fromSnapshot, String toSnapshot) throws IOException Get the difference between two snapshots, or between a snapshot and the current tree of a directory. Parameters: snapshotRoot - full path of the directory where snapshots are taken fromSnapshot - snapshot name of the from point. Null indicates the current tree toSnapshot - snapshot name of the to point. Null indicates the current tree. Returns: The difference report represented as a SnapshotDiffReport. Throws: IOException - on error

Interface ClientProtocol

Field Summary

Method Summary

Field Detail

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

Method Detail

getBlockLocations

getServerDefaults

create

append

setReplication

setPermission

setOwner

abandonBlock

addBlock

getAdditionalDatanode

complete

reportBadBlocks

rename

concat

rename2

delete

mkdirs

getListing

getSnapshottableDirListing

renewLease

recoverLease

getStats

getDatanodeReport

getPreferredBlockSize

setSafeMode

Configuration parameters:

Special cases:

saveNamespace

rollEdits

restoreFailedStorage

refreshNodes

finalizeUpgrade

listCorruptFileBlocks

metaSave

setBalancerBandwidth

getFileInfo

isFileClosed

getFileLinkInfo

getContentSummary

setQuota

fsync

setTimes

createSymlink

getLinkTarget

updateBlockForPipeline

updatePipeline

getDelegationToken

renewDelegationToken

cancelDelegationToken

getDataEncryptionKey

createSnapshot

deleteSnapshot

renameSnapshot

allowSnapshot

disallowSnapshot

getSnapshotDiffReport