ClientProtocol.java
上传用户:quxuerui
上传日期:2018-01-08
资源大小:41811k
文件大小:19k
源码类别:

网格计算

开发平台:

Java

  1. /**
  2.  * Licensed to the Apache Software Foundation (ASF) under one
  3.  * or more contributor license agreements.  See the NOTICE file
  4.  * distributed with this work for additional information
  5.  * regarding copyright ownership.  The ASF licenses this file
  6.  * to you under the Apache License, Version 2.0 (the
  7.  * "License"); you may not use this file except in compliance
  8.  * with the License.  You may obtain a copy of the License at
  9.  *
  10.  *     http://www.apache.org/licenses/LICENSE-2.0
  11.  *
  12.  * Unless required by applicable law or agreed to in writing, software
  13.  * distributed under the License is distributed on an "AS IS" BASIS,
  14.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15.  * See the License for the specific language governing permissions and
  16.  * limitations under the License.
  17.  */
  18. package org.apache.hadoop.hdfs.protocol;
  19. import java.io.*;
  20. import org.apache.hadoop.ipc.VersionedProtocol;
  21. import org.apache.hadoop.security.AccessControlException;
  22. import org.apache.hadoop.hdfs.protocol.FSConstants.UpgradeAction;
  23. import org.apache.hadoop.hdfs.server.common.UpgradeStatusReport;
  24. import org.apache.hadoop.fs.permission.*;
  25. import org.apache.hadoop.fs.ContentSummary;
  26. import org.apache.hadoop.fs.FileStatus;
  27. /**********************************************************************
  28.  * ClientProtocol is used by user code via 
  29.  * {@link org.apache.hadoop.hdfs.DistributedFileSystem} class to communicate 
  30.  * with the NameNode.  User code can manipulate the directory namespace, 
  31.  * as well as open/close file streams, etc.
  32.  *
  33.  **********************************************************************/
  34. public interface ClientProtocol extends VersionedProtocol {
  35.   /**
  36.    * Compared to the previous version the following changes have been introduced:
  37.    * (Only the latest change is reflected.
  38.    * The log of historical changes can be retrieved from the svn).
  39.    * 41: saveNamespace introduced.
  40.    */
  41.   public static final long versionID = 41L;
  42.   
  43.   ///////////////////////////////////////
  44.   // File contents
  45.   ///////////////////////////////////////
  46.   /**
  47.    * Get locations of the blocks of the specified file within the specified range.
  48.    * DataNode locations for each block are sorted by
  49.    * the proximity to the client.
  50.    * <p>
  51.    * Return {@link LocatedBlocks} which contains
  52.    * file length, blocks and their locations.
  53.    * DataNode locations for each block are sorted by
  54.    * the distance to the client's address.
  55.    * <p>
  56.    * The client will then have to contact 
  57.    * one of the indicated DataNodes to obtain the actual data.
  58.    * 
  59.    * @param src file name
  60.    * @param offset range start offset
  61.    * @param length range length
  62.    * @return file length and array of blocks with their locations
  63.    * @throws IOException
  64.    */
  65.   public LocatedBlocks  getBlockLocations(String src,
  66.                                           long offset,
  67.                                           long length) throws IOException;
  68.   /**
  69.    * Create a new file entry in the namespace.
  70.    * <p>
  71.    * This will create an empty file specified by the source path.
  72.    * The path should reflect a full path originated at the root.
  73.    * The name-node does not have a notion of "current" directory for a client.
  74.    * <p>
  75.    * Once created, the file is visible and available for read to other clients.
  76.    * Although, other clients cannot {@link #delete(String)}, re-create or 
  77.    * {@link #rename(String, String)} it until the file is completed
  78.    * or explicitly as a result of lease expiration.
  79.    * <p>
  80.    * Blocks have a maximum size.  Clients that intend to
  81.    * create multi-block files must also use {@link #addBlock(String, String)}.
  82.    *
  83.    * @param src path of the file being created.
  84.    * @param masked masked permission.
  85.    * @param clientName name of the current client.
  86.    * @param overwrite indicates whether the file should be 
  87.    * overwritten if it already exists.
  88.    * @param replication block replication factor.
  89.    * @param blockSize maximum block size.
  90.    * 
  91.    * @throws AccessControlException if permission to create file is 
  92.    * denied by the system. As usually on the client side the exception will 
  93.    * be wrapped into {@link org.apache.hadoop.ipc.RemoteException}.
  94.    * @throws QuotaExceededException if the file creation violates 
  95.    *                                any quota restriction
  96.    * @throws IOException if other errors occur.
  97.    */
  98.   public void create(String src, 
  99.                      FsPermission masked,
  100.                              String clientName, 
  101.                              boolean overwrite, 
  102.                              short replication,
  103.                              long blockSize
  104.                              ) throws IOException;
  105.   /**
  106.    * Append to the end of the file. 
  107.    * @param src path of the file being created.
  108.    * @param clientName name of the current client.
  109.    * @return information about the last partial block if any.
  110.    * @throws AccessControlException if permission to append file is 
  111.    * denied by the system. As usually on the client side the exception will 
  112.    * be wrapped into {@link org.apache.hadoop.ipc.RemoteException}.
  113.    * Allows appending to an existing file if the server is
  114.    * configured with the parameter dfs.support.append set to true, otherwise
  115.    * throws an IOException.
  116.    * @throws IOException if other errors occur.
  117.    */
  118.   public LocatedBlock append(String src, String clientName) throws IOException;
  119.   /**
  120.    * Set replication for an existing file.
  121.    * <p>
  122.    * The NameNode sets replication to the new value and returns.
  123.    * The actual block replication is not expected to be performed during  
  124.    * this method call. The blocks will be populated or removed in the 
  125.    * background as the result of the routine block maintenance procedures.
  126.    * 
  127.    * @param src file name
  128.    * @param replication new replication
  129.    * @throws IOException
  130.    * @return true if successful;
  131.    *         false if file does not exist or is a directory
  132.    */
  133.   public boolean setReplication(String src, 
  134.                                 short replication
  135.                                 ) throws IOException;
  136.   /**
  137.    * Set permissions for an existing file/directory.
  138.    */
  139.   public void setPermission(String src, FsPermission permission
  140.       ) throws IOException;
  141.   /**
  142.    * Set owner of a path (i.e. a file or a directory).
  143.    * The parameters username and groupname cannot both be null.
  144.    * @param src
  145.    * @param username If it is null, the original username remains unchanged.
  146.    * @param groupname If it is null, the original groupname remains unchanged.
  147.    */
  148.   public void setOwner(String src, String username, String groupname
  149.       ) throws IOException;
  150.   /**
  151.    * The client can give up on a blcok by calling abandonBlock().
  152.    * The client can then
  153.    * either obtain a new block, or complete or abandon the file.
  154.    * Any partial writes to the block will be discarded.
  155.    */
  156.   public void abandonBlock(Block b, String src, String holder
  157.       ) throws IOException;
  158.   /**
  159.    * A client that wants to write an additional block to the 
  160.    * indicated filename (which must currently be open for writing)
  161.    * should call addBlock().  
  162.    *
  163.    * addBlock() allocates a new block and datanodes the block data
  164.    * should be replicated to.
  165.    * 
  166.    * @return LocatedBlock allocated block information.
  167.    */
  168.   public LocatedBlock addBlock(String src, String clientName) throws IOException;
  169.   /**
  170.    * The client is done writing data to the given filename, and would 
  171.    * like to complete it.  
  172.    *
  173.    * The function returns whether the file has been closed successfully.
  174.    * If the function returns false, the caller should try again.
  175.    *
  176.    * A call to complete() will not return true until all the file's
  177.    * blocks have been replicated the minimum number of times.  Thus,
  178.    * DataNode failures may cause a client to call complete() several
  179.    * times before succeeding.
  180.    */
  181.   public boolean complete(String src, String clientName) throws IOException;
  182.   /**
  183.    * The client wants to report corrupted blocks (blocks with specified
  184.    * locations on datanodes).
  185.    * @param blocks Array of located blocks to report
  186.    */
  187.   public void reportBadBlocks(LocatedBlock[] blocks) throws IOException;
  188.   ///////////////////////////////////////
  189.   // Namespace management
  190.   ///////////////////////////////////////
  191.   /**
  192.    * Rename an item in the file system namespace.
  193.    * 
  194.    * @param src existing file or directory name.
  195.    * @param dst new name.
  196.    * @return true if successful, or false if the old name does not exist
  197.    * or if the new name already belongs to the namespace.
  198.    * @throws IOException if the new name is invalid.
  199.    * @throws QuotaExceededException if the rename would violate 
  200.    *                                any quota restriction
  201.    */
  202.   public boolean rename(String src, String dst) throws IOException;
  203.   /**
  204.    * Delete the given file or directory from the file system.
  205.    * <p>
  206.    * Any blocks belonging to the deleted files will be garbage-collected.
  207.    * 
  208.    * @param src existing name.
  209.    * @return true only if the existing file or directory was actually removed 
  210.    * from the file system. 
  211.    */
  212.   public boolean delete(String src) throws IOException;
  213.   /**
  214.    * Delete the given file or directory from the file system.
  215.    * <p>
  216.    * same as delete but provides a way to avoid accidentally 
  217.    * deleting non empty directories programmatically. 
  218.    * @param src existing name
  219.    * @param recursive if true deletes a non empty directory recursively,
  220.    * else throws an exception.
  221.    * @return true only if the existing file or directory was actually removed 
  222.    * from the file system. 
  223.    */
  224.   public boolean delete(String src, boolean recursive) throws IOException;
  225.   
  226.   /**
  227.    * Create a directory (or hierarchy of directories) with the given
  228.    * name and permission.
  229.    *
  230.    * @param src The path of the directory being created
  231.    * @param masked The masked permission of the directory being created
  232.    * @return True if the operation success.
  233.    * @throws {@link AccessControlException} if permission to create file is 
  234.    * denied by the system. As usually on the client side the exception will 
  235.    * be wraped into {@link org.apache.hadoop.ipc.RemoteException}.
  236.    * @throws QuotaExceededException if the operation would violate 
  237.    *                                any quota restriction.
  238.    */
  239.   public boolean mkdirs(String src, FsPermission masked) throws IOException;
  240.   /**
  241.    * Get a listing of the indicated directory
  242.    */
  243.   public FileStatus[] getListing(String src) throws IOException;
  244.   ///////////////////////////////////////
  245.   // System issues and management
  246.   ///////////////////////////////////////
  247.   /**
  248.    * Client programs can cause stateful changes in the NameNode
  249.    * that affect other clients.  A client may obtain a file and 
  250.    * neither abandon nor complete it.  A client might hold a series
  251.    * of locks that prevent other clients from proceeding.
  252.    * Clearly, it would be bad if a client held a bunch of locks
  253.    * that it never gave up.  This can happen easily if the client
  254.    * dies unexpectedly.
  255.    * <p>
  256.    * So, the NameNode will revoke the locks and live file-creates
  257.    * for clients that it thinks have died.  A client tells the
  258.    * NameNode that it is still alive by periodically calling
  259.    * renewLease().  If a certain amount of time passes since
  260.    * the last call to renewLease(), the NameNode assumes the
  261.    * client has died.
  262.    */
  263.   public void renewLease(String clientName) throws IOException;
  264.   public int GET_STATS_CAPACITY_IDX = 0;
  265.   public int GET_STATS_USED_IDX = 1;
  266.   public int GET_STATS_REMAINING_IDX = 2;
  267.   public int GET_STATS_UNDER_REPLICATED_IDX = 3;
  268.   public int GET_STATS_CORRUPT_BLOCKS_IDX = 4;
  269.   public int GET_STATS_MISSING_BLOCKS_IDX = 5;
  270.   
  271.   /**
  272.    * Get a set of statistics about the filesystem.
  273.    * Right now, only three values are returned.
  274.    * <ul>
  275.    * <li> [0] contains the total storage capacity of the system, in bytes.</li>
  276.    * <li> [1] contains the total used space of the system, in bytes.</li>
  277.    * <li> [2] contains the available storage of the system, in bytes.</li>
  278.    * <li> [3] contains number of under replicated blocks in the system.</li>
  279.    * <li> [4] contains number of blocks with a corrupt replica. </li>
  280.    * <li> [5] contains number of blocks without any good replicas left. </li>
  281.    * </ul>
  282.    * Use public constants like {@link #GET_STATS_CAPACITY_IDX} in place of 
  283.    * actual numbers to index into the array.
  284.    */
  285.   public long[] getStats() throws IOException;
  286.   /**
  287.    * Get a report on the system's current datanodes.
  288.    * One DatanodeInfo object is returned for each DataNode.
  289.    * Return live datanodes if type is LIVE; dead datanodes if type is DEAD;
  290.    * otherwise all datanodes if type is ALL.
  291.    */
  292.   public DatanodeInfo[] getDatanodeReport(FSConstants.DatanodeReportType type)
  293.   throws IOException;
  294.   /**
  295.    * Get the block size for the given file.
  296.    * @param filename The name of the file
  297.    * @return The number of bytes in each block
  298.    * @throws IOException
  299.    */
  300.   public long getPreferredBlockSize(String filename) throws IOException;
  301.   /**
  302.    * Enter, leave or get safe mode.
  303.    * <p>
  304.    * Safe mode is a name node state when it
  305.    * <ol><li>does not accept changes to name space (read-only), and</li>
  306.    * <li>does not replicate or delete blocks.</li></ol>
  307.    * 
  308.    * <p>
  309.    * Safe mode is entered automatically at name node startup.
  310.    * Safe mode can also be entered manually using
  311.    * {@link #setSafeMode(FSConstants.SafeModeAction) setSafeMode(SafeModeAction.SAFEMODE_GET)}.
  312.    * <p>
  313.    * At startup the name node accepts data node reports collecting
  314.    * information about block locations.
  315.    * In order to leave safe mode it needs to collect a configurable
  316.    * percentage called threshold of blocks, which satisfy the minimal 
  317.    * replication condition.
  318.    * The minimal replication condition is that each block must have at least
  319.    * <tt>dfs.replication.min</tt> replicas.
  320.    * When the threshold is reached the name node extends safe mode
  321.    * for a configurable amount of time
  322.    * to let the remaining data nodes to check in before it
  323.    * will start replicating missing blocks.
  324.    * Then the name node leaves safe mode.
  325.    * <p>
  326.    * If safe mode is turned on manually using
  327.    * {@link #setSafeMode(FSConstants.SafeModeAction) setSafeMode(SafeModeAction.SAFEMODE_ENTER)}
  328.    * then the name node stays in safe mode until it is manually turned off
  329.    * using {@link #setSafeMode(FSConstants.SafeModeAction) setSafeMode(SafeModeAction.SAFEMODE_LEAVE)}.
  330.    * Current state of the name node can be verified using
  331.    * {@link #setSafeMode(FSConstants.SafeModeAction) setSafeMode(SafeModeAction.SAFEMODE_GET)}
  332.    * <h4>Configuration parameters:</h4>
  333.    * <tt>dfs.safemode.threshold.pct</tt> is the threshold parameter.<br>
  334.    * <tt>dfs.safemode.extension</tt> is the safe mode extension parameter.<br>
  335.    * <tt>dfs.replication.min</tt> is the minimal replication parameter.
  336.    * 
  337.    * <h4>Special cases:</h4>
  338.    * The name node does not enter safe mode at startup if the threshold is 
  339.    * set to 0 or if the name space is empty.<br>
  340.    * If the threshold is set to 1 then all blocks need to have at least 
  341.    * minimal replication.<br>
  342.    * If the threshold value is greater than 1 then the name node will not be 
  343.    * able to turn off safe mode automatically.<br>
  344.    * Safe mode can always be turned off manually.
  345.    * 
  346.    * @param action  <ul> <li>0 leave safe mode;</li>
  347.    *                <li>1 enter safe mode;</li>
  348.    *                <li>2 get safe mode state.</li></ul>
  349.    * @return <ul><li>0 if the safe mode is OFF or</li> 
  350.    *         <li>1 if the safe mode is ON.</li></ul>
  351.    * @throws IOException
  352.    */
  353.   public boolean setSafeMode(FSConstants.SafeModeAction action) throws IOException;
  354.   /**
  355.    * Save namespace image.
  356.    * <p>
  357.    * Saves current namespace into storage directories and reset edits log.
  358.    * Requires superuser privilege and safe mode.
  359.    * 
  360.    * @throws AccessControlException if the superuser privilege is violated.
  361.    * @throws IOException if image creation failed.
  362.    */
  363.   public void saveNamespace() throws IOException;
  364.   /**
  365.    * Tells the namenode to reread the hosts and exclude files. 
  366.    * @throws IOException
  367.    */
  368.   public void refreshNodes() throws IOException;
  369.   /**
  370.    * Finalize previous upgrade.
  371.    * Remove file system state saved during the upgrade.
  372.    * The upgrade will become irreversible.
  373.    * 
  374.    * @throws IOException
  375.    */
  376.   public void finalizeUpgrade() throws IOException;
  377.   /**
  378.    * Report distributed upgrade progress or force current upgrade to proceed.
  379.    * 
  380.    * @param action {@link FSConstants.UpgradeAction} to perform
  381.    * @return upgrade status information or null if no upgrades are in progress
  382.    * @throws IOException
  383.    */
  384.   public UpgradeStatusReport distributedUpgradeProgress(UpgradeAction action) 
  385.   throws IOException;
  386.   /**
  387.    * Dumps namenode data structures into specified file. If file
  388.    * already exists, then append.
  389.    * @throws IOException
  390.    */
  391.   public void metaSave(String filename) throws IOException;
  392.   /**
  393.    * Get the file info for a specific file or directory.
  394.    * @param src The string representation of the path to the file
  395.    * @throws IOException if permission to access file is denied by the system 
  396.    * @return object containing information regarding the file
  397.    *         or null if file not found
  398.    */
  399.   public FileStatus getFileInfo(String src) throws IOException;
  400.   /**
  401.    * Get {@link ContentSummary} rooted at the specified directory.
  402.    * @param path The string representation of the path
  403.    */
  404.   public ContentSummary getContentSummary(String path) throws IOException;
  405.   /**
  406.    * Set the quota for a directory.
  407.    * @param path  The string representation of the path to the directory
  408.    * @param namespaceQuota Limit on the number of names in the tree rooted 
  409.    *                       at the directory
  410.    * @param diskspaceQuota Limit on disk space occupied all the files under
  411.    *                       this directory. 
  412.    * <br><br>
  413.    *                       
  414.    * The quota can have three types of values : (1) 0 or more will set 
  415.    * the quota to that value, (2) {@link FSConstants#QUOTA_DONT_SET}  implies 
  416.    * the quota will not be changed, and (3) {@link FSConstants#QUOTA_RESET} 
  417.    * implies the quota will be reset. Any other value is a runtime error.
  418.    *                        
  419.    * @throws FileNotFoundException if the path is a file or 
  420.    *                               does not exist 
  421.    * @throws QuotaExceededException if the directory size 
  422.    *                                is greater than the given quota
  423.    */
  424.   public void setQuota(String path, long namespaceQuota, long diskspaceQuota)
  425.                       throws IOException;
  426.   
  427.   /**
  428.    * Write all metadata for this file into persistent storage.
  429.    * The file must be currently open for writing.
  430.    * @param src The string representation of the path
  431.    * @param client The string representation of the client
  432.    */
  433.   public void fsync(String src, String client) throws IOException;
  434.   /**
  435.    * Sets the modification and access time of the file to the specified time.
  436.    * @param src The string representation of the path
  437.    * @param mtime The number of milliseconds since Jan 1, 1970.
  438.    *              Setting mtime to -1 means that modification time should not be set
  439.    *              by this call.
  440.    * @param atime The number of milliseconds since Jan 1, 1970.
  441.    *              Setting atime to -1 means that access time should not be set
  442.    *              by this call.
  443.    */
  444.   public void setTimes(String src, long mtime, long atime) throws IOException;
  445. }