HDFS-2393. Mark appropriate methods of ClientProtocol with the idempotent annotation. (atm)

git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/branches/HDFS-1623@1190088 13f79535-47bb-0310-9956-ffa450edef68

hadoop-hdfs-project/hadoop-hdfs/CHANGES.HDFS-1623.txt

@@ -17,3 +17,5 @@ HDFS-2301. Start/stop appropriate namenode services when transition to active an
 HDFS-2231. Configuration changes for HA namenode. (suresh)
 
 HDFS-2418. Change ConfiguredFailoverProxyProvider to take advantage of HDFS-2231. (atm)
+
+HDFS-2393. Mark appropriate methods of ClientProtocol with the idempotent annotation. (atm)

hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/protocol/ClientProtocol.java

@@ -112,6 +112,7 @@ public LocatedBlocks getBlockLocations(String src,
    * @return a set of server default configuration values
    * @throws IOException
    */
+  @Idempotent
   public FsServerDefaults getServerDefaults() throws IOException;
 
   /**
@@ -215,6 +216,7 @@ public LocatedBlock append(String src, String clientName)
    * @throws UnresolvedLinkException if <code>src</code> contains a symlink
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public boolean setReplication(String src, short replication)
       throws AccessControlException, DSQuotaExceededException,
       FileNotFoundException, SafeModeException, UnresolvedLinkException,
@@ -229,6 +231,7 @@ public boolean setReplication(String src, short replication)
    * @throws UnresolvedLinkException If <code>src</code> contains a symlink
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public void setPermission(String src, FsPermission permission)
       throws AccessControlException, FileNotFoundException, SafeModeException,
       UnresolvedLinkException, IOException;
@@ -246,6 +249,7 @@ public void setPermission(String src, FsPermission permission)
    * @throws UnresolvedLinkException If <code>src</code> contains a symlink
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public void setOwner(String src, String username, String groupname)
       throws AccessControlException, FileNotFoundException, SafeModeException,
       UnresolvedLinkException, IOException;
@@ -318,6 +322,7 @@ public LocatedBlock addBlock(String src, String clientName,
    * @throws UnresolvedLinkException If <code>src</code> contains a symlink
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public LocatedBlock getAdditionalDatanode(final String src, final ExtendedBlock blk,
       final DatanodeInfo[] existings, final DatanodeInfo[] excludes,
       final int numAdditionalNodes, final String clientName
@@ -355,6 +360,7 @@ public boolean complete(String src, String clientName, ExtendedBlock last)
    * locations on datanodes).
    * @param blocks Array of located blocks to report
    */
+  @Idempotent
   public void reportBadBlocks(LocatedBlock[] blocks) throws IOException;
 
   ///////////////////////////////////////
@@ -472,6 +478,7 @@ public boolean delete(String src, boolean recursive)
    * RunTimeExceptions:
    * @throws InvalidPathException If <code>src</code> is invalid
    */
+  @Idempotent
   public boolean mkdirs(String src, FsPermission masked, boolean createParent)
       throws AccessControlException, FileAlreadyExistsException,
       FileNotFoundException, NSQuotaExceededException,
@@ -492,6 +499,7 @@ public boolean mkdirs(String src, FsPermission masked, boolean createParent)
    * @throws UnresolvedLinkException If <code>src</code> contains a symlink
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public DirectoryListing getListing(String src,
                                      byte[] startAfter,
                                      boolean needLocation)
@@ -521,6 +529,7 @@ public DirectoryListing getListing(String src,
    * @throws AccessControlException permission denied
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public void renewLease(String clientName) throws AccessControlException,
       IOException;
 
@@ -533,6 +542,7 @@ public void renewLease(String clientName) throws AccessControlException,
    * @return true if the file is already closed
    * @throws IOException
    */
+  @Idempotent
   public boolean recoverLease(String src, String clientName) throws IOException;
 
   public int GET_STATS_CAPACITY_IDX = 0;
@@ -544,7 +554,7 @@ public void renewLease(String clientName) throws AccessControlException,
   
   /**
    * Get a set of statistics about the filesystem.
-   * Right now, only three values are returned.
+   * Right now, only seven values are returned.
    * <ul>
    * <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>
@@ -557,6 +567,7 @@ public void renewLease(String clientName) throws AccessControlException,
    * Use public constants like {@link #GET_STATS_CAPACITY_IDX} in place of 
    * actual numbers to index into the array.
    */
+  @Idempotent
   public long[] getStats() throws IOException;
 
   /**
@@ -565,6 +576,7 @@ public void renewLease(String clientName) throws AccessControlException,
    * Return live datanodes if type is LIVE; dead datanodes if type is DEAD;
    * otherwise all datanodes if type is ALL.
    */
+  @Idempotent
   public DatanodeInfo[] getDatanodeReport(HdfsConstants.DatanodeReportType type)
       throws IOException;
 
@@ -575,6 +587,7 @@ public DatanodeInfo[] getDatanodeReport(HdfsConstants.DatanodeReportType type)
    * @throws IOException
    * @throws UnresolvedLinkException if the path contains a symlink. 
    */
+  @Idempotent
   public long getPreferredBlockSize(String filename) 
       throws IOException, UnresolvedLinkException;
 
@@ -667,6 +680,7 @@ public boolean setSafeMode(HdfsConstants.SafeModeAction action)
    * 
    * @throws IOException
    */
+  //TODO(HA): Should this be @Idempotent?
   public void finalizeUpgrade() throws IOException;
 
   /**
@@ -677,6 +691,7 @@ public boolean setSafeMode(HdfsConstants.SafeModeAction action)
    * @throws IOException
    */
   @Nullable
+  //TODO(HA): Should this be @Idempotent?
   public UpgradeStatusReport distributedUpgradeProgress(UpgradeAction action) 
       throws IOException;
 
@@ -690,9 +705,9 @@ public UpgradeStatusReport distributedUpgradeProgress(UpgradeAction action)
    * all corrupt files, call this method repeatedly and each time pass in the
    * cookie returned from the previous call.
    */
-  public CorruptFileBlocks
+  @Idempotent
-    listCorruptFileBlocks(String path, String cookie)
+  public CorruptFileBlocks listCorruptFileBlocks(String path, String cookie)
-    throws IOException;
+      throws IOException;
   
   /**
    * Dumps namenode data structures into specified file. If the file
@@ -709,6 +724,7 @@ public UpgradeStatusReport distributedUpgradeProgress(UpgradeAction action)
    * @param bandwidth Blanacer bandwidth in bytes per second for this datanode.
    * @throws IOException
    */
+  //TODO(HA): Should this be @Idempotent?
   public void setBalancerBandwidth(long bandwidth) throws IOException;
   
   /**
@@ -739,6 +755,7 @@ public HdfsFileStatus getFileInfo(String src) throws AccessControlException,
    * @throws UnresolvedLinkException if <code>src</code> contains a symlink
    * @throws IOException If an I/O error occurred        
    */
+  @Idempotent
   public HdfsFileStatus getFileLinkInfo(String src)
       throws AccessControlException, UnresolvedLinkException, IOException;
   
@@ -751,6 +768,7 @@ public HdfsFileStatus getFileLinkInfo(String src)
    * @throws UnresolvedLinkException if <code>path</code> contains a symlink. 
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public ContentSummary getContentSummary(String path)
       throws AccessControlException, FileNotFoundException,
       UnresolvedLinkException, IOException;
@@ -776,6 +794,7 @@ public ContentSummary getContentSummary(String path)
    * @throws UnresolvedLinkException if the <code>path</code> contains a symlink. 
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public void setQuota(String path, long namespaceQuota, long diskspaceQuota)
       throws AccessControlException, FileNotFoundException,
       UnresolvedLinkException, IOException;
@@ -791,6 +810,7 @@ public void setQuota(String path, long namespaceQuota, long diskspaceQuota)
    * @throws UnresolvedLinkException if <code>src</code> contains a symlink. 
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public void fsync(String src, String client) 
       throws AccessControlException, FileNotFoundException, 
       UnresolvedLinkException, IOException;
@@ -810,6 +830,7 @@ public void fsync(String src, String client)
    * @throws UnresolvedLinkException if <code>src</code> contains a symlink. 
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public void setTimes(String src, long mtime, long atime)
       throws AccessControlException, FileNotFoundException, 
       UnresolvedLinkException, IOException;
@@ -848,6 +869,7 @@ public void createSymlink(String target, String link, FsPermission dirPerm,
    * @throws FileNotFoundException If <code>path</code> does not exist
    * @throws IOException If an I/O error occurred
    */
+  @Idempotent
   public String getLinkTarget(String path) throws AccessControlException,
       FileNotFoundException, IOException; 
   
@@ -863,6 +885,7 @@ public String getLinkTarget(String path) throws AccessControlException,
    * @return a located block with a new generation stamp and an access token
    * @throws IOException if any error occurs
    */
+  @Idempotent
   public LocatedBlock updateBlockForPipeline(ExtendedBlock block,
       String clientName) throws IOException;
 
@@ -886,6 +909,7 @@ public void updatePipeline(String clientName, ExtendedBlock oldBlock,
    * @return Token<DelegationTokenIdentifier>
    * @throws IOException
    */
+  @Idempotent
   public Token<DelegationTokenIdentifier> getDelegationToken(Text renewer) 
       throws IOException;
 
@@ -896,6 +920,7 @@ public Token<DelegationTokenIdentifier> getDelegationToken(Text renewer)
    * @return the new expiration time
    * @throws IOException
    */
+  @Idempotent
   public long renewDelegationToken(Token<DelegationTokenIdentifier> token)
       throws IOException;