Hadoop DataNodeProtocol、NameNodeProtocol和ClientProtocol接口说明(2)

3、ClientProtocol

用户代码使用此协议，通过org.apache.hadoop.hdfs.DistributedFileSystem类实现与NameNode的沟通

 。用户代码可以操纵目录命名空间，打开/关闭文件流等等。

a、实例域

public static final long versionID = 61L;

61：org.apache.hadoop.hdfs.security.token.block.BlockTokenIdentifier的序列化格式改变为：在一个

单一的BlockTokenIdentifier包含多个块。

b、方法：

File contents：

1）public LocatedBlocks getBlockLocations(String src,
                                          long offset,
                                          long length) throws IOException;

在指定范围内，获取指定的文件的blocks的位置，每个块所在的Datanode节点进行排序，根据其位置

距client的距离排序。返回值是一个LocatedBlocks，包含文件大小、所在block以及block的位置。然后用户

就必须与指示的Datanode进行连接从而获得实际的数据。

2） public voidcreate(String src, 
                     FsPermission masked,
                             String clientName, 
                             boolean overwrite, 
                            （ boolean createParent,）
                             short replication,
                             long blockSize
                             ) throws IOException;

在命名空间内创建以文件入口，根据指定的源路径创建一个空的文件，此路径是一个完整的从root产生

出来的。一旦创建，此文件对于其他client就是可见和可读的，但是其他clients不能删除、重命名、再建，除非

此文件创建完成或者确信leese终结。如果client创建的是一个占用多块的文件，还要使用addBlock(String, String)

3）public LocatedBlock addBlock(String src, String clientName,
                               DatanodeInfo[] excludedNodes) throws IOException;

分配一个新的block以及此block的副本应该在的datanode，如果用户想将一个额外的block写入指定的文件

命名空间（当前必须处于写打开状态）

4） public LocatedBlockappend(String src, String clientName) throws IOException;

追加内容到指定文件的末尾，参数src表将要创建文件的路径，clientName表当前的client的名称

5）public boolean recoverLease(String src, String clientName) throws IOException;

启动lease修复，参数src表要进行lease修复的文件路径，如果文件已经关闭则返回true

6）public booleansetReplication(String src, 
                                short replication
                                ) throws IOException;

为一个存在的文件设置副本数replication，NameNode设置新的副本数和并返回。调用此方法后，block replication就

不再是默认的数值。在进行块的维护过程中，增加或者删减这些块的副本。

7）public voidsetPermission(String src, FsPermission permission
       ) throws IOException;

对一个存在的src（文件或者目录）设置访问权限，权限类型有：（org.apache.hadoop.fs.permission.FsPermission.java）useraction、groupaction、otheraction

8） public voidsetOwner(String src, String username, String groupname
      ) throws IOException;

对于src（文件或者目录）设置owner，参数username和groupname不能为空

9）public voidabandonBlock(Block b, String src, String holder

      ) throws IOException;

client可以调用此方法来放弃一个block，client就可以获得一个新的block，或完成或放弃文件，block上的内容会被丢弃。

10） public booleancomplete(String src, String clientName) throws IOException;

client在向filename写入数据时，需要结束这个写操作。此函数返回文件是否成功关闭，如果返回false，则要再调用。

此方法的调用只用在文件对应的所有的block都已经复制副本完成才返回true，因此datanode的失败会导致client多次调用此方法。

11）public void reportBadBlocks(LocatedBlock[] blocks) throws IOException;

client端报告有毁坏的block（在datanode上指定位置的block）

Namespace management：

12）public boolean rename(String src, String dst) throws IOException;

文件系统中的文件或者目录改名

13）public booleandelete(String src，（boolean recursive）) throws IOException;

删除文件系统中的文件或者文件名，如果不是一个空的目录，需要增加参数recursive进行递归删除

14）public booleanmkdirs(String src, FsPermission masked) throws IOException;

创建一个目录

15）public DirectoryListinggetListing(String src, byte[] startAfter)
  throws IOException;

获得部分指定目录列表，参数startAfter表示client端收到的最后入口处，从startAfter之后开始返回部分列表

System issues and management：

  16）public voidrenewLease(String clientName) throws IOException;

client端程序可能导致NameNode的状态的变化从而影响其他client。其中一

个client可能会得到一个文件，既不abandon也不complete它。client端可能保持锁的序列，以防止其他客户端访

问。 显然，如果一个client保持一堆的锁而不abandon它们会导致不想要结果。如果client端意外die会产生这种情况。

Namenode如果认为client已经死亡的话会删除锁，并对于其他的client激活文件创建权限。此时client就要调用renewLease（）

告知namenode它依然是活着的，如果超过一定时间没有renewLease（），namenode就认为client已经死亡

17）public long[]getStats() throws IOException;

获取一组文件系统的统计信息，目前的统计信息包含只有三个值。使用下面的公共常量代替返回数组中的实际值：

public int GET_STATS_CAPACITY_IDX = 0;
  public int GET_STATS_USED_IDX = 1;
  public int GET_STATS_REMAINING_IDX = 2;
  public int GET_STATS_UNDER_REPLICATED_IDX = 3;
  public int GET_STATS_CORRUPT_BLOCKS_IDX = 4;
  public int GET_STATS_MISSING_BLOCKS_IDX = 5;      

    * <li> [0] contains the total storage capacity of the system, in bytes.</li>
    * <li> [1] contains the total used space of the system, in bytes.</li>
   * <li> [2] contains the available storage of the system, in bytes.</li>
    * <li> [3] contains number of under replicated blocks in the system.</li>
   * <li> [4] contains number of blocks with a corrupt replica. </li>
    * <li> [5] contains number of blocks without any good replicas left. </li>

18）public DatanodeInfo[] getDatanodeReport(FSConstants.DatanodeReportType type)
  throws IOException;

获取系统当前datanodes的报告，每个Datanode对应一个DatanodeInfo对象，参数type可以是：

LIVE、DEAD、ALL，分别返回相应的Datanode

19）public longgetPreferredBlockSize(String filename) throws IOException;

对于给定文件返回其占用block的大小

20)  public boolean setSafeMode(FSConstants.SafeModeAction action) throws IOException;

进入、离开或者得到安全模式，在安全模式下不能对文件系统进行修改，不能删除block和复制block

在Namenode启动后自动进入安全模式。参数action有以下选择

0： leave safe mode
                       1：  enter safe mode
                       2： get safe mode state

21）public voidsaveNamespace() throws IOException;

保存命名空间的image文件，保存命名空间的image文件到存储目录中并更新edit日志文件，要求在

安全模式下具有权限的Superuesr

22） public voidrefreshNodes() throws IOException;

23）public voidfinalizeUpgrade() throws IOException;

终结之前进行的更新，删除之前更新过程中保存的文件系统的状态，更新过程将变成不可逆转的。

24）public UpgradeStatusReportdistributedUpgradeProgress(UpgradeAction action) 
  throws IOException;

报告分布式的更新进程或强制执行当前的更新，返回更新的状态信息，如果没有更新则返回null

25）public voidmetaSave(String filename) throws IOException;

将namenode的数据结构写入到指定文件中，如果文件存在，则append入文件中

26）public voidsetBalancerBandwidth(long bandwidth) throws IOException;

告诉所有的datanode使用一个新的临时的bandwidth，这个参数是由dfs.balance.bandwidthPerSec指定的

27）public HdfsFileStatus getFileInfo(String src) throws IOException;

对于指定的文件或者目录获得文件信息，

28） public ContentSummarygetContentSummary(String path) throws IOException;

返回一个 ContentSummary类型，是指定的目录参数path的，ContentSummary存储了目录的摘要信息

29）public voidsetQuota(String path, long namespaceQuota, long diskspaceQuota)
                      throws IOException;

为指定的目录（path）总大小设置上限quota，namespaceQuota是指其包含子目录个数的上限

30）public void fsync(String src, String client) throws IOException;

将所有元数据写入这个文件（src）中进行持久化存储，该文件当前必须是打开的等待写入的状态

31）public void setTimes(String src, long mtime, long atime) throws IOException;

设置进行文件（src）访问和修改的时间为指定的时间（mtime、atime），mtime和atime都代表距

Jan 1, 1970的时间是多少ms，如果将mtime和atime设为-1，分别表示此方法不应该设置修改时间、不应该

设置访问时间

32）public Token<DelegationTokenIdentifier>getDelegationToken(Text renewer) throws IOException;

获取一个有效的授权token，

33） public long renewDelegationToken(Token<DelegationTokenIdentifier> token)

      throws IOException;

更新已经存在的授权token

34）public void cancelDelegationToken(Token<DelegationTokenIdentifier> token)
      throws IOException;

删除已经存在的授权token