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 20 import java.io.FileNotFoundException; 21 import java.io.IOException; 22 import java.util.EnumSet; 23 import java.util.List; 24 25 import org.apache.hadoop.classification.InterfaceAudience; 26 import org.apache.hadoop.classification.InterfaceStability; 27 import org.apache.hadoop.crypto.CryptoProtocolVersion; 28 import org.apache.hadoop.fs.BatchedRemoteIterator.BatchedEntries; 29 import org.apache.hadoop.fs.CacheFlag; 30 import org.apache.hadoop.fs.ContentSummary; 31 import org.apache.hadoop.fs.CreateFlag; 32 import org.apache.hadoop.fs.FileAlreadyExistsException; 33 import org.apache.hadoop.fs.FsServerDefaults; 34 import org.apache.hadoop.fs.InvalidPathException; 35 import org.apache.hadoop.fs.Options; 36 import org.apache.hadoop.fs.Options.Rename; 37 import org.apache.hadoop.fs.ParentNotDirectoryException; 38 import org.apache.hadoop.fs.StorageType; 39 import org.apache.hadoop.fs.UnresolvedLinkException; 40 import org.apache.hadoop.fs.XAttr; 41 import org.apache.hadoop.fs.XAttrSetFlag; 42 import org.apache.hadoop.fs.permission.AclEntry; 43 import org.apache.hadoop.fs.permission.AclStatus; 44 import org.apache.hadoop.fs.permission.FsAction; 45 import org.apache.hadoop.fs.permission.FsPermission; 46 import org.apache.hadoop.hdfs.DFSConfigKeys; 47 import org.apache.hadoop.hdfs.inotify.EventBatchList; 48 import org.apache.hadoop.hdfs.protocol.HdfsConstants.RollingUpgradeAction; 49 import org.apache.hadoop.hdfs.security.token.block.DataEncryptionKey; 50 import org.apache.hadoop.hdfs.security.token.delegation.DelegationTokenIdentifier; 51 import org.apache.hadoop.hdfs.security.token.delegation.DelegationTokenSelector; 52 import org.apache.hadoop.hdfs.server.namenode.NotReplicatedYetException; 53 import org.apache.hadoop.hdfs.server.namenode.SafeModeException; 54 import org.apache.hadoop.hdfs.server.protocol.DatanodeStorageReport; 55 import org.apache.hadoop.io.EnumSetWritable; 56 import org.apache.hadoop.io.Text; 57 import org.apache.hadoop.io.retry.AtMostOnce; 58 import org.apache.hadoop.io.retry.Idempotent; 59 import org.apache.hadoop.security.AccessControlException; 60 import org.apache.hadoop.security.KerberosInfo; 61 import org.apache.hadoop.security.token.Token; 62 import org.apache.hadoop.security.token.TokenInfo; 63 64 /********************************************************************** 65 * ClientProtocol is used by user code via 66 * {@link org.apache.hadoop.hdfs.DistributedFileSystem} class to communicate 67 * with the NameNode. User code can manipulate the directory namespace, 68 * as well as open/close file streams, etc. 69 * 70 **********************************************************************/ 71 @InterfaceAudience.Private 72 @InterfaceStability.Evolving 73 @KerberosInfo( 74 serverPrincipal = DFSConfigKeys.DFS_NAMENODE_KERBEROS_PRINCIPAL_KEY) 75 @TokenInfo(DelegationTokenSelector.class) 76 public interface ClientProtocol { 77 78 /** 79 * Until version 69, this class ClientProtocol served as both 80 * the client interface to the NN AND the RPC protocol used to 81 * communicate with the NN. 82 * 83 * This class is used by both the DFSClient and the 84 * NN server side to insulate from the protocol serialization. 85 * 86 * If you are adding/changing this interface then you need to 87 * change both this class and ALSO related protocol buffer 88 * wire protocol definition in ClientNamenodeProtocol.proto. 89 * 90 * For more details on protocol buffer wire protocol, please see 91 * .../org/apache/hadoop/hdfs/protocolPB/overview.html 92 * 93 * The log of historical changes can be retrieved from the svn). 94 * 69: Eliminate overloaded method names. 95 * 96 * 69L is the last version id when this class was used for protocols 97 * serialization. DO not update this version any further. 98 */ 99 public static final long versionID = 69L; 100 101 /////////////////////////////////////// 102 // File contents 103 /////////////////////////////////////// 104 /** 105 * Get locations of the blocks of the specified file within the specified range. 106 * DataNode locations for each block are sorted by 107 * the proximity to the client. 108 * <p> 109 * Return {@link LocatedBlocks} which contains 110 * file length, blocks and their locations. 111 * DataNode locations for each block are sorted by 112 * the distance to the client's address. 113 * <p> 114 * The client will then have to contact 115 * one of the indicated DataNodes to obtain the actual data. 116 * 117 * @param src file name 118 * @param offset range start offset 119 * @param length range length 120 * 121 * @return file length and array of blocks with their locations 122 * 123 * @throws AccessControlException If access is denied 124 * @throws FileNotFoundException If file <code>src</code> does not exist 125 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 126 * @throws IOException If an I/O error occurred 127 */ 128 @Idempotent getBlockLocations(String src, long offset, long length)129 public LocatedBlocks getBlockLocations(String src, 130 long offset, 131 long length) 132 throws AccessControlException, FileNotFoundException, 133 UnresolvedLinkException, IOException; 134 135 /** 136 * Get server default values for a number of configuration params. 137 * @return a set of server default configuration values 138 * @throws IOException 139 */ 140 @Idempotent getServerDefaults()141 public FsServerDefaults getServerDefaults() throws IOException; 142 143 /** 144 * Create a new file entry in the namespace. 145 * <p> 146 * This will create an empty file specified by the source path. 147 * The path should reflect a full path originated at the root. 148 * The name-node does not have a notion of "current" directory for a client. 149 * <p> 150 * Once created, the file is visible and available for read to other clients. 151 * Although, other clients cannot {@link #delete(String, boolean)}, re-create or 152 * {@link #rename(String, String)} it until the file is completed 153 * or explicitly as a result of lease expiration. 154 * <p> 155 * Blocks have a maximum size. Clients that intend to create 156 * multi-block files must also use 157 * {@link #addBlock} 158 * 159 * @param src path of the file being created. 160 * @param masked masked permission. 161 * @param clientName name of the current client. 162 * @param flag indicates whether the file should be 163 * overwritten if it already exists or create if it does not exist or append. 164 * @param createParent create missing parent directory if true 165 * @param replication block replication factor. 166 * @param blockSize maximum block size. 167 * @param supportedVersions CryptoProtocolVersions supported by the client 168 * 169 * @return the status of the created file, it could be null if the server 170 * doesn't support returning the file status 171 * @throws AccessControlException If access is denied 172 * @throws AlreadyBeingCreatedException if the path does not exist. 173 * @throws DSQuotaExceededException If file creation violates disk space 174 * quota restriction 175 * @throws FileAlreadyExistsException If file <code>src</code> already exists 176 * @throws FileNotFoundException If parent of <code>src</code> does not exist 177 * and <code>createParent</code> is false 178 * @throws ParentNotDirectoryException If parent of <code>src</code> is not a 179 * directory. 180 * @throws NSQuotaExceededException If file creation violates name space 181 * quota restriction 182 * @throws SafeModeException create not allowed in safemode 183 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 184 * @throws SnapshotAccessControlException if path is in RO snapshot 185 * @throws IOException If an I/O error occurred 186 * 187 * RuntimeExceptions: 188 * @throws InvalidPathException Path <code>src</code> is invalid 189 * <p> 190 * <em>Note that create with {@link CreateFlag#OVERWRITE} is idempotent.</em> 191 */ 192 @AtMostOnce create(String src, FsPermission masked, String clientName, EnumSetWritable<CreateFlag> flag, boolean createParent, short replication, long blockSize, CryptoProtocolVersion[] supportedVersions)193 public HdfsFileStatus create(String src, FsPermission masked, 194 String clientName, EnumSetWritable<CreateFlag> flag, 195 boolean createParent, short replication, long blockSize, 196 CryptoProtocolVersion[] supportedVersions) 197 throws AccessControlException, AlreadyBeingCreatedException, 198 DSQuotaExceededException, FileAlreadyExistsException, 199 FileNotFoundException, NSQuotaExceededException, 200 ParentNotDirectoryException, SafeModeException, UnresolvedLinkException, 201 SnapshotAccessControlException, IOException; 202 203 /** 204 * Append to the end of the file. 205 * @param src path of the file being created. 206 * @param clientName name of the current client. 207 * @param flag indicates whether the data is appended to a new block. 208 * @return wrapper with information about the last partial block and file 209 * status if any 210 * @throws AccessControlException if permission to append file is 211 * denied by the system. As usually on the client side the exception will 212 * be wrapped into {@link org.apache.hadoop.ipc.RemoteException}. 213 * Allows appending to an existing file if the server is 214 * configured with the parameter dfs.support.append set to true, otherwise 215 * throws an IOException. 216 * 217 * @throws AccessControlException If permission to append to file is denied 218 * @throws FileNotFoundException If file <code>src</code> is not found 219 * @throws DSQuotaExceededException If append violates disk space quota 220 * restriction 221 * @throws SafeModeException append not allowed in safemode 222 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 223 * @throws SnapshotAccessControlException if path is in RO snapshot 224 * @throws IOException If an I/O error occurred. 225 * 226 * RuntimeExceptions: 227 * @throws UnsupportedOperationException if append is not supported 228 */ 229 @AtMostOnce append(String src, String clientName, EnumSetWritable<CreateFlag> flag)230 public LastBlockWithStatus append(String src, String clientName, 231 EnumSetWritable<CreateFlag> flag) throws AccessControlException, 232 DSQuotaExceededException, FileNotFoundException, SafeModeException, 233 UnresolvedLinkException, SnapshotAccessControlException, IOException; 234 235 /** 236 * Set replication for an existing file. 237 * <p> 238 * The NameNode sets replication to the new value and returns. 239 * The actual block replication is not expected to be performed during 240 * this method call. The blocks will be populated or removed in the 241 * background as the result of the routine block maintenance procedures. 242 * 243 * @param src file name 244 * @param replication new replication 245 * 246 * @return true if successful; 247 * false if file does not exist or is a directory 248 * 249 * @throws AccessControlException If access is denied 250 * @throws DSQuotaExceededException If replication violates disk space 251 * quota restriction 252 * @throws FileNotFoundException If file <code>src</code> is not found 253 * @throws SafeModeException not allowed in safemode 254 * @throws UnresolvedLinkException if <code>src</code> contains a symlink 255 * @throws SnapshotAccessControlException if path is in RO snapshot 256 * @throws IOException If an I/O error occurred 257 */ 258 @Idempotent setReplication(String src, short replication)259 public boolean setReplication(String src, short replication) 260 throws AccessControlException, DSQuotaExceededException, 261 FileNotFoundException, SafeModeException, UnresolvedLinkException, 262 SnapshotAccessControlException, IOException; 263 264 /** 265 * Get all the available block storage policies. 266 * @return All the in-use block storage policies currently. 267 */ 268 @Idempotent getStoragePolicies()269 public BlockStoragePolicy[] getStoragePolicies() throws IOException; 270 271 /** 272 * Set the storage policy for a file/directory 273 * @param src Path of an existing file/directory. 274 * @param policyName The name of the storage policy 275 * @throws SnapshotAccessControlException If access is denied 276 * @throws UnresolvedLinkException if <code>src</code> contains a symlink 277 * @throws FileNotFoundException If file/dir <code>src</code> is not found 278 * @throws QuotaExceededException If changes violate the quota restriction 279 */ 280 @Idempotent setStoragePolicy(String src, String policyName)281 public void setStoragePolicy(String src, String policyName) 282 throws SnapshotAccessControlException, UnresolvedLinkException, 283 FileNotFoundException, QuotaExceededException, IOException; 284 285 /** 286 * Set permissions for an existing file/directory. 287 * 288 * @throws AccessControlException If access is denied 289 * @throws FileNotFoundException If file <code>src</code> is not found 290 * @throws SafeModeException not allowed in safemode 291 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 292 * @throws SnapshotAccessControlException if path is in RO snapshot 293 * @throws IOException If an I/O error occurred 294 */ 295 @Idempotent setPermission(String src, FsPermission permission)296 public void setPermission(String src, FsPermission permission) 297 throws AccessControlException, FileNotFoundException, SafeModeException, 298 UnresolvedLinkException, SnapshotAccessControlException, IOException; 299 300 /** 301 * Set Owner of a path (i.e. a file or a directory). 302 * The parameters username and groupname cannot both be null. 303 * @param src file path 304 * @param username If it is null, the original username remains unchanged. 305 * @param groupname If it is null, the original groupname remains unchanged. 306 * 307 * @throws AccessControlException If access is denied 308 * @throws FileNotFoundException If file <code>src</code> is not found 309 * @throws SafeModeException not allowed in safemode 310 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 311 * @throws SnapshotAccessControlException if path is in RO snapshot 312 * @throws IOException If an I/O error occurred 313 */ 314 @Idempotent setOwner(String src, String username, String groupname)315 public void setOwner(String src, String username, String groupname) 316 throws AccessControlException, FileNotFoundException, SafeModeException, 317 UnresolvedLinkException, SnapshotAccessControlException, IOException; 318 319 /** 320 * The client can give up on a block by calling abandonBlock(). 321 * The client can then either obtain a new block, or complete or abandon the 322 * file. 323 * Any partial writes to the block will be discarded. 324 * 325 * @param b Block to abandon 326 * @param fileId The id of the file where the block resides. Older clients 327 * will pass GRANDFATHER_INODE_ID here. 328 * @param src The path of the file where the block resides. 329 * @param holder Lease holder. 330 * 331 * @throws AccessControlException If access is denied 332 * @throws FileNotFoundException file <code>src</code> is not found 333 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 334 * @throws IOException If an I/O error occurred 335 */ 336 @Idempotent abandonBlock(ExtendedBlock b, long fileId, String src, String holder)337 public void abandonBlock(ExtendedBlock b, long fileId, 338 String src, String holder) 339 throws AccessControlException, FileNotFoundException, 340 UnresolvedLinkException, IOException; 341 342 /** 343 * A client that wants to write an additional block to the 344 * indicated filename (which must currently be open for writing) 345 * should call addBlock(). 346 * 347 * addBlock() allocates a new block and datanodes the block data 348 * should be replicated to. 349 * 350 * addBlock() also commits the previous block by reporting 351 * to the name-node the actual generation stamp and the length 352 * of the block that the client has transmitted to data-nodes. 353 * 354 * @param src the file being created 355 * @param clientName the name of the client that adds the block 356 * @param previous previous block 357 * @param excludeNodes a list of nodes that should not be 358 * allocated for the current block 359 * @param fileId the id uniquely identifying a file 360 * @param favoredNodes the list of nodes where the client wants the blocks. 361 * Nodes are identified by either host name or address. 362 * 363 * @return LocatedBlock allocated block information. 364 * 365 * @throws AccessControlException If access is denied 366 * @throws FileNotFoundException If file <code>src</code> is not found 367 * @throws NotReplicatedYetException previous blocks of the file are not 368 * replicated yet. Blocks cannot be added until replication 369 * completes. 370 * @throws SafeModeException create not allowed in safemode 371 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 372 * @throws IOException If an I/O error occurred 373 */ 374 @Idempotent addBlock(String src, String clientName, ExtendedBlock previous, DatanodeInfo[] excludeNodes, long fileId, String[] favoredNodes)375 public LocatedBlock addBlock(String src, String clientName, 376 ExtendedBlock previous, DatanodeInfo[] excludeNodes, long fileId, 377 String[] favoredNodes) 378 throws AccessControlException, FileNotFoundException, 379 NotReplicatedYetException, SafeModeException, UnresolvedLinkException, 380 IOException; 381 382 /** 383 * Get a datanode for an existing pipeline. 384 * 385 * @param src the file being written 386 * @param fileId the ID of the file being written 387 * @param blk the block being written 388 * @param existings the existing nodes in the pipeline 389 * @param excludes the excluded nodes 390 * @param numAdditionalNodes number of additional datanodes 391 * @param clientName the name of the client 392 * 393 * @return the located block. 394 * 395 * @throws AccessControlException If access is denied 396 * @throws FileNotFoundException If file <code>src</code> is not found 397 * @throws SafeModeException create not allowed in safemode 398 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 399 * @throws IOException If an I/O error occurred 400 */ 401 @Idempotent getAdditionalDatanode(final String src, final long fileId, final ExtendedBlock blk, final DatanodeInfo[] existings, final String[] existingStorageIDs, final DatanodeInfo[] excludes, final int numAdditionalNodes, final String clientName )402 public LocatedBlock getAdditionalDatanode(final String src, 403 final long fileId, final ExtendedBlock blk, 404 final DatanodeInfo[] existings, 405 final String[] existingStorageIDs, 406 final DatanodeInfo[] excludes, 407 final int numAdditionalNodes, final String clientName 408 ) throws AccessControlException, FileNotFoundException, 409 SafeModeException, UnresolvedLinkException, IOException; 410 411 /** 412 * The client is done writing data to the given filename, and would 413 * like to complete it. 414 * 415 * The function returns whether the file has been closed successfully. 416 * If the function returns false, the caller should try again. 417 * 418 * close() also commits the last block of file by reporting 419 * to the name-node the actual generation stamp and the length 420 * of the block that the client has transmitted to data-nodes. 421 * 422 * A call to complete() will not return true until all the file's 423 * blocks have been replicated the minimum number of times. Thus, 424 * DataNode failures may cause a client to call complete() several 425 * times before succeeding. 426 * 427 * @param src the file being created 428 * @param clientName the name of the client that adds the block 429 * @param last the last block info 430 * @param fileId the id uniquely identifying a file 431 * 432 * @return true if all file blocks are minimally replicated or false otherwise 433 * 434 * @throws AccessControlException If access is denied 435 * @throws FileNotFoundException If file <code>src</code> is not found 436 * @throws SafeModeException create not allowed in safemode 437 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 438 * @throws IOException If an I/O error occurred 439 */ 440 @Idempotent complete(String src, String clientName, ExtendedBlock last, long fileId)441 public boolean complete(String src, String clientName, 442 ExtendedBlock last, long fileId) 443 throws AccessControlException, FileNotFoundException, SafeModeException, 444 UnresolvedLinkException, IOException; 445 446 /** 447 * The client wants to report corrupted blocks (blocks with specified 448 * locations on datanodes). 449 * @param blocks Array of located blocks to report 450 */ 451 @Idempotent reportBadBlocks(LocatedBlock[] blocks)452 public void reportBadBlocks(LocatedBlock[] blocks) throws IOException; 453 454 /////////////////////////////////////// 455 // Namespace management 456 /////////////////////////////////////// 457 /** 458 * Rename an item in the file system namespace. 459 * @param src existing file or directory name. 460 * @param dst new name. 461 * @return true if successful, or false if the old name does not exist 462 * or if the new name already belongs to the namespace. 463 * 464 * @throws SnapshotAccessControlException if path is in RO snapshot 465 * @throws IOException an I/O error occurred 466 */ 467 @AtMostOnce rename(String src, String dst)468 public boolean rename(String src, String dst) 469 throws UnresolvedLinkException, SnapshotAccessControlException, IOException; 470 471 /** 472 * Moves blocks from srcs to trg and delete srcs 473 * 474 * @param trg existing file 475 * @param srcs - list of existing files (same block size, same replication) 476 * @throws IOException if some arguments are invalid 477 * @throws UnresolvedLinkException if <code>trg</code> or <code>srcs</code> 478 * contains a symlink 479 * @throws SnapshotAccessControlException if path is in RO snapshot 480 */ 481 @AtMostOnce concat(String trg, String[] srcs)482 public void concat(String trg, String[] srcs) 483 throws IOException, UnresolvedLinkException, SnapshotAccessControlException; 484 485 /** 486 * Rename src to dst. 487 * <ul> 488 * <li>Fails if src is a file and dst is a directory. 489 * <li>Fails if src is a directory and dst is a file. 490 * <li>Fails if the parent of dst does not exist or is a file. 491 * </ul> 492 * <p> 493 * Without OVERWRITE option, rename fails if the dst already exists. 494 * With OVERWRITE option, rename overwrites the dst, if it is a file 495 * or an empty directory. Rename fails if dst is a non-empty directory. 496 * <p> 497 * This implementation of rename is atomic. 498 * <p> 499 * @param src existing file or directory name. 500 * @param dst new name. 501 * @param options Rename options 502 * 503 * @throws AccessControlException If access is denied 504 * @throws DSQuotaExceededException If rename violates disk space 505 * quota restriction 506 * @throws FileAlreadyExistsException If <code>dst</code> already exists and 507 * <code>options</options> has {@link Rename#OVERWRITE} option 508 * false. 509 * @throws FileNotFoundException If <code>src</code> does not exist 510 * @throws NSQuotaExceededException If rename violates namespace 511 * quota restriction 512 * @throws ParentNotDirectoryException If parent of <code>dst</code> 513 * is not a directory 514 * @throws SafeModeException rename not allowed in safemode 515 * @throws UnresolvedLinkException If <code>src</code> or 516 * <code>dst</code> contains a symlink 517 * @throws SnapshotAccessControlException if path is in RO snapshot 518 * @throws IOException If an I/O error occurred 519 */ 520 @AtMostOnce rename2(String src, String dst, Options.Rename... options)521 public void rename2(String src, String dst, Options.Rename... options) 522 throws AccessControlException, DSQuotaExceededException, 523 FileAlreadyExistsException, FileNotFoundException, 524 NSQuotaExceededException, ParentNotDirectoryException, SafeModeException, 525 UnresolvedLinkException, SnapshotAccessControlException, IOException; 526 527 /** 528 * Truncate file src to new size. 529 * <ul> 530 * <li>Fails if src is a directory. 531 * <li>Fails if src does not exist. 532 * <li>Fails if src is not closed. 533 * <li>Fails if new size is greater than current size. 534 * </ul> 535 * <p> 536 * This implementation of truncate is purely a namespace operation if truncate 537 * occurs at a block boundary. Requires DataNode block recovery otherwise. 538 * <p> 539 * @param src existing file 540 * @param newLength the target size 541 * 542 * @return true if client does not need to wait for block recovery, 543 * false if client needs to wait for block recovery. 544 * 545 * @throws AccessControlException If access is denied 546 * @throws FileNotFoundException If file <code>src</code> is not found 547 * @throws SafeModeException truncate not allowed in safemode 548 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 549 * @throws SnapshotAccessControlException if path is in RO snapshot 550 * @throws IOException If an I/O error occurred 551 */ 552 @Idempotent truncate(String src, long newLength, String clientName)553 public boolean truncate(String src, long newLength, String clientName) 554 throws AccessControlException, FileNotFoundException, SafeModeException, 555 UnresolvedLinkException, SnapshotAccessControlException, IOException; 556 557 /** 558 * Delete the given file or directory from the file system. 559 * <p> 560 * same as delete but provides a way to avoid accidentally 561 * deleting non empty directories programmatically. 562 * @param src existing name 563 * @param recursive if true deletes a non empty directory recursively, 564 * else throws an exception. 565 * @return true only if the existing file or directory was actually removed 566 * from the file system. 567 * 568 * @throws AccessControlException If access is denied 569 * @throws FileNotFoundException If file <code>src</code> is not found 570 * @throws SafeModeException create not allowed in safemode 571 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 572 * @throws SnapshotAccessControlException if path is in RO snapshot 573 * @throws IOException If an I/O error occurred 574 */ 575 @AtMostOnce delete(String src, boolean recursive)576 public boolean delete(String src, boolean recursive) 577 throws AccessControlException, FileNotFoundException, SafeModeException, 578 UnresolvedLinkException, SnapshotAccessControlException, IOException; 579 580 /** 581 * Create a directory (or hierarchy of directories) with the given 582 * name and permission. 583 * 584 * @param src The path of the directory being created 585 * @param masked The masked permission of the directory being created 586 * @param createParent create missing parent directory if true 587 * 588 * @return True if the operation success. 589 * 590 * @throws AccessControlException If access is denied 591 * @throws FileAlreadyExistsException If <code>src</code> already exists 592 * @throws FileNotFoundException If parent of <code>src</code> does not exist 593 * and <code>createParent</code> is false 594 * @throws NSQuotaExceededException If file creation violates quota restriction 595 * @throws ParentNotDirectoryException If parent of <code>src</code> 596 * is not a directory 597 * @throws SafeModeException create not allowed in safemode 598 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 599 * @throws SnapshotAccessControlException if path is in RO snapshot 600 * @throws IOException If an I/O error occurred. 601 * 602 * RunTimeExceptions: 603 * @throws InvalidPathException If <code>src</code> is invalid 604 */ 605 @Idempotent mkdirs(String src, FsPermission masked, boolean createParent)606 public boolean mkdirs(String src, FsPermission masked, boolean createParent) 607 throws AccessControlException, FileAlreadyExistsException, 608 FileNotFoundException, NSQuotaExceededException, 609 ParentNotDirectoryException, SafeModeException, UnresolvedLinkException, 610 SnapshotAccessControlException, IOException; 611 612 /** 613 * Get a partial listing of the indicated directory 614 * 615 * @param src the directory name 616 * @param startAfter the name to start listing after encoded in java UTF8 617 * @param needLocation if the FileStatus should contain block locations 618 * 619 * @return a partial listing starting after startAfter 620 * 621 * @throws AccessControlException permission denied 622 * @throws FileNotFoundException file <code>src</code> is not found 623 * @throws UnresolvedLinkException If <code>src</code> contains a symlink 624 * @throws IOException If an I/O error occurred 625 */ 626 @Idempotent getListing(String src, byte[] startAfter, boolean needLocation)627 public DirectoryListing getListing(String src, 628 byte[] startAfter, 629 boolean needLocation) 630 throws AccessControlException, FileNotFoundException, 631 UnresolvedLinkException, IOException; 632 633 /** 634 * Get listing of all the snapshottable directories 635 * 636 * @return Information about all the current snapshottable directory 637 * @throws IOException If an I/O error occurred 638 */ 639 @Idempotent getSnapshottableDirListing()640 public SnapshottableDirectoryStatus[] getSnapshottableDirListing() 641 throws IOException; 642 643 /////////////////////////////////////// 644 // System issues and management 645 /////////////////////////////////////// 646 647 /** 648 * Client programs can cause stateful changes in the NameNode 649 * that affect other clients. A client may obtain a file and 650 * neither abandon nor complete it. A client might hold a series 651 * of locks that prevent other clients from proceeding. 652 * Clearly, it would be bad if a client held a bunch of locks 653 * that it never gave up. This can happen easily if the client 654 * dies unexpectedly. 655 * <p> 656 * So, the NameNode will revoke the locks and live file-creates 657 * for clients that it thinks have died. A client tells the 658 * NameNode that it is still alive by periodically calling 659 * renewLease(). If a certain amount of time passes since 660 * the last call to renewLease(), the NameNode assumes the 661 * client has died. 662 * 663 * @throws AccessControlException permission denied 664 * @throws IOException If an I/O error occurred 665 */ 666 @Idempotent renewLease(String clientName)667 public void renewLease(String clientName) throws AccessControlException, 668 IOException; 669 670 /** 671 * Start lease recovery. 672 * Lightweight NameNode operation to trigger lease recovery 673 * 674 * @param src path of the file to start lease recovery 675 * @param clientName name of the current client 676 * @return true if the file is already closed 677 * @throws IOException 678 */ 679 @Idempotent recoverLease(String src, String clientName)680 public boolean recoverLease(String src, String clientName) throws IOException; 681 682 public int GET_STATS_CAPACITY_IDX = 0; 683 public int GET_STATS_USED_IDX = 1; 684 public int GET_STATS_REMAINING_IDX = 2; 685 public int GET_STATS_UNDER_REPLICATED_IDX = 3; 686 public int GET_STATS_CORRUPT_BLOCKS_IDX = 4; 687 public int GET_STATS_MISSING_BLOCKS_IDX = 5; 688 public int GET_STATS_MISSING_REPL_ONE_BLOCKS_IDX = 6; 689 690 /** 691 * Get a set of statistics about the filesystem. 692 * Right now, only seven values are returned. 693 * <ul> 694 * <li> [0] contains the total storage capacity of the system, in bytes.</li> 695 * <li> [1] contains the total used space of the system, in bytes.</li> 696 * <li> [2] contains the available storage of the system, in bytes.</li> 697 * <li> [3] contains number of under replicated blocks in the system.</li> 698 * <li> [4] contains number of blocks with a corrupt replica. </li> 699 * <li> [5] contains number of blocks without any good replicas left. </li> 700 * <li> [6] contains number of blocks which have replication factor 701 * 1 and have lost the only replica. </li> 702 * </ul> 703 * Use public constants like {@link #GET_STATS_CAPACITY_IDX} in place of 704 * actual numbers to index into the array. 705 */ 706 @Idempotent getStats()707 public long[] getStats() throws IOException; 708 709 /** 710 * Get a report on the system's current datanodes. 711 * One DatanodeInfo object is returned for each DataNode. 712 * Return live datanodes if type is LIVE; dead datanodes if type is DEAD; 713 * otherwise all datanodes if type is ALL. 714 */ 715 @Idempotent getDatanodeReport(HdfsConstants.DatanodeReportType type)716 public DatanodeInfo[] getDatanodeReport(HdfsConstants.DatanodeReportType type) 717 throws IOException; 718 719 /** 720 * Get a report on the current datanode storages. 721 */ 722 @Idempotent getDatanodeStorageReport( HdfsConstants.DatanodeReportType type)723 public DatanodeStorageReport[] getDatanodeStorageReport( 724 HdfsConstants.DatanodeReportType type) throws IOException; 725 726 /** 727 * Get the block size for the given file. 728 * @param filename The name of the file 729 * @return The number of bytes in each block 730 * @throws IOException 731 * @throws UnresolvedLinkException if the path contains a symlink. 732 */ 733 @Idempotent getPreferredBlockSize(String filename)734 public long getPreferredBlockSize(String filename) 735 throws IOException, UnresolvedLinkException; 736 737 /** 738 * Enter, leave or get safe mode. 739 * <p> 740 * Safe mode is a name node state when it 741 * <ol><li>does not accept changes to name space (read-only), and</li> 742 * <li>does not replicate or delete blocks.</li></ol> 743 * 744 * <p> 745 * Safe mode is entered automatically at name node startup. 746 * Safe mode can also be entered manually using 747 * {@link #setSafeMode(HdfsConstants.SafeModeAction,boolean) setSafeMode(SafeModeAction.SAFEMODE_ENTER,false)}. 748 * <p> 749 * At startup the name node accepts data node reports collecting 750 * information about block locations. 751 * In order to leave safe mode it needs to collect a configurable 752 * percentage called threshold of blocks, which satisfy the minimal 753 * replication condition. 754 * The minimal replication condition is that each block must have at least 755 * <tt>dfs.namenode.replication.min</tt> replicas. 756 * When the threshold is reached the name node extends safe mode 757 * for a configurable amount of time 758 * to let the remaining data nodes to check in before it 759 * will start replicating missing blocks. 760 * Then the name node leaves safe mode. 761 * <p> 762 * If safe mode is turned on manually using 763 * {@link #setSafeMode(HdfsConstants.SafeModeAction,boolean) setSafeMode(SafeModeAction.SAFEMODE_ENTER,false)} 764 * then the name node stays in safe mode until it is manually turned off 765 * using {@link #setSafeMode(HdfsConstants.SafeModeAction,boolean) setSafeMode(SafeModeAction.SAFEMODE_LEAVE,false)}. 766 * Current state of the name node can be verified using 767 * {@link #setSafeMode(HdfsConstants.SafeModeAction,boolean) setSafeMode(SafeModeAction.SAFEMODE_GET,false)} 768 * <h4>Configuration parameters:</h4> 769 * <tt>dfs.safemode.threshold.pct</tt> is the threshold parameter.<br> 770 * <tt>dfs.safemode.extension</tt> is the safe mode extension parameter.<br> 771 * <tt>dfs.namenode.replication.min</tt> is the minimal replication parameter. 772 * 773 * <h4>Special cases:</h4> 774 * The name node does not enter safe mode at startup if the threshold is 775 * set to 0 or if the name space is empty.<br> 776 * If the threshold is set to 1 then all blocks need to have at least 777 * minimal replication.<br> 778 * If the threshold value is greater than 1 then the name node will not be 779 * able to turn off safe mode automatically.<br> 780 * Safe mode can always be turned off manually. 781 * 782 * @param action <ul> <li>0 leave safe mode;</li> 783 * <li>1 enter safe mode;</li> 784 * <li>2 get safe mode state.</li></ul> 785 * @param isChecked If true then action will be done only in ActiveNN. 786 * 787 * @return <ul><li>0 if the safe mode is OFF or</li> 788 * <li>1 if the safe mode is ON.</li></ul> 789 * 790 * @throws IOException 791 */ 792 @Idempotent setSafeMode(HdfsConstants.SafeModeAction action, boolean isChecked)793 public boolean setSafeMode(HdfsConstants.SafeModeAction action, boolean isChecked) 794 throws IOException; 795 796 /** 797 * Save namespace image. 798 * <p> 799 * Saves current namespace into storage directories and reset edits log. 800 * Requires superuser privilege and safe mode. 801 * 802 * @throws AccessControlException if the superuser privilege is violated. 803 * @throws IOException if image creation failed. 804 */ 805 @AtMostOnce saveNamespace()806 public void saveNamespace() throws AccessControlException, IOException; 807 808 809 /** 810 * Roll the edit log. 811 * Requires superuser privileges. 812 * 813 * @throws AccessControlException if the superuser privilege is violated 814 * @throws IOException if log roll fails 815 * @return the txid of the new segment 816 */ 817 @Idempotent rollEdits()818 public long rollEdits() throws AccessControlException, IOException; 819 820 /** 821 * Enable/Disable restore failed storage. 822 * <p> 823 * sets flag to enable restore of failed storage replicas 824 * 825 * @throws AccessControlException if the superuser privilege is violated. 826 */ 827 @Idempotent restoreFailedStorage(String arg)828 public boolean restoreFailedStorage(String arg) 829 throws AccessControlException, IOException; 830 831 /** 832 * Tells the namenode to reread the hosts and exclude files. 833 * @throws IOException 834 */ 835 @Idempotent refreshNodes()836 public void refreshNodes() throws IOException; 837 838 /** 839 * Finalize previous upgrade. 840 * Remove file system state saved during the upgrade. 841 * The upgrade will become irreversible. 842 * 843 * @throws IOException 844 */ 845 @Idempotent finalizeUpgrade()846 public void finalizeUpgrade() throws IOException; 847 848 /** 849 * Rolling upgrade operations. 850 * @param action either query, prepare or finalize. 851 * @return rolling upgrade information. On query, if no upgrade is in 852 * progress, returns null. 853 */ 854 @Idempotent rollingUpgrade(RollingUpgradeAction action)855 public RollingUpgradeInfo rollingUpgrade(RollingUpgradeAction action) 856 throws IOException; 857 858 /** 859 * @return CorruptFileBlocks, containing a list of corrupt files (with 860 * duplicates if there is more than one corrupt block in a file) 861 * and a cookie 862 * @throws IOException 863 * 864 * Each call returns a subset of the corrupt files in the system. To obtain 865 * all corrupt files, call this method repeatedly and each time pass in the 866 * cookie returned from the previous call. 867 */ 868 @Idempotent listCorruptFileBlocks(String path, String cookie)869 public CorruptFileBlocks listCorruptFileBlocks(String path, String cookie) 870 throws IOException; 871 872 /** 873 * Dumps namenode data structures into specified file. If the file 874 * already exists, then append. 875 * 876 * @throws IOException 877 */ 878 @Idempotent metaSave(String filename)879 public void metaSave(String filename) throws IOException; 880 881 /** 882 * Tell all datanodes to use a new, non-persistent bandwidth value for 883 * dfs.balance.bandwidthPerSec. 884 * 885 * @param bandwidth Blanacer bandwidth in bytes per second for this datanode. 886 * @throws IOException 887 */ 888 @Idempotent setBalancerBandwidth(long bandwidth)889 public void setBalancerBandwidth(long bandwidth) throws IOException; 890 891 /** 892 * Get the file info for a specific file or directory. 893 * @param src The string representation of the path to the file 894 * 895 * @return object containing information regarding the file 896 * or null if file not found 897 * @throws AccessControlException permission denied 898 * @throws FileNotFoundException file <code>src</code> is not found 899 * @throws UnresolvedLinkException if the path contains a symlink. 900 * @throws IOException If an I/O error occurred 901 */ 902 @Idempotent getFileInfo(String src)903 public HdfsFileStatus getFileInfo(String src) throws AccessControlException, 904 FileNotFoundException, UnresolvedLinkException, IOException; 905 906 /** 907 * Get the close status of a file 908 * @param src The string representation of the path to the file 909 * 910 * @return return true if file is closed 911 * @throws AccessControlException permission denied 912 * @throws FileNotFoundException file <code>src</code> is not found 913 * @throws UnresolvedLinkException if the path contains a symlink. 914 * @throws IOException If an I/O error occurred 915 */ 916 @Idempotent isFileClosed(String src)917 public boolean isFileClosed(String src) throws AccessControlException, 918 FileNotFoundException, UnresolvedLinkException, IOException; 919 920 /** 921 * Get the file info for a specific file or directory. If the path 922 * refers to a symlink then the FileStatus of the symlink is returned. 923 * @param src The string representation of the path to the file 924 * 925 * @return object containing information regarding the file 926 * or null if file not found 927 * 928 * @throws AccessControlException permission denied 929 * @throws UnresolvedLinkException if <code>src</code> contains a symlink 930 * @throws IOException If an I/O error occurred 931 */ 932 @Idempotent getFileLinkInfo(String src)933 public HdfsFileStatus getFileLinkInfo(String src) 934 throws AccessControlException, UnresolvedLinkException, IOException; 935 936 /** 937 * Get {@link ContentSummary} rooted at the specified directory. 938 * @param path The string representation of the path 939 * 940 * @throws AccessControlException permission denied 941 * @throws FileNotFoundException file <code>path</code> is not found 942 * @throws UnresolvedLinkException if <code>path</code> contains a symlink. 943 * @throws IOException If an I/O error occurred 944 */ 945 @Idempotent getContentSummary(String path)946 public ContentSummary getContentSummary(String path) 947 throws AccessControlException, FileNotFoundException, 948 UnresolvedLinkException, IOException; 949 950 /** 951 * Set the quota for a directory. 952 * @param path The string representation of the path to the directory 953 * @param namespaceQuota Limit on the number of names in the tree rooted 954 * at the directory 955 * @param storagespaceQuota Limit on storage space occupied all the files under 956 * this directory. 957 * @param type StorageType that the space quota is intended to be set on. 958 * It may be null when called by traditional space/namespace quota. 959 * When type is is not null, the storagespaceQuota parameter is for 960 * type specified and namespaceQuota must be 961 * {@link HdfsConstants#QUOTA_DONT_SET}. 962 * 963 * <br><br> 964 * 965 * The quota can have three types of values : (1) 0 or more will set 966 * the quota to that value, (2) {@link HdfsConstants#QUOTA_DONT_SET} implies 967 * the quota will not be changed, and (3) {@link HdfsConstants#QUOTA_RESET} 968 * implies the quota will be reset. Any other value is a runtime error. 969 * 970 * @throws AccessControlException permission denied 971 * @throws FileNotFoundException file <code>path</code> is not found 972 * @throws QuotaExceededException if the directory size 973 * is greater than the given quota 974 * @throws UnresolvedLinkException if the <code>path</code> contains a symlink. 975 * @throws SnapshotAccessControlException if path is in RO snapshot 976 * @throws IOException If an I/O error occurred 977 */ 978 @Idempotent setQuota(String path, long namespaceQuota, long storagespaceQuota, StorageType type)979 public void setQuota(String path, long namespaceQuota, long storagespaceQuota, 980 StorageType type) throws AccessControlException, FileNotFoundException, 981 UnresolvedLinkException, SnapshotAccessControlException, IOException; 982 983 /** 984 * Write all metadata for this file into persistent storage. 985 * The file must be currently open for writing. 986 * @param src The string representation of the path 987 * @param inodeId The inode ID, or GRANDFATHER_INODE_ID if the client is 988 * too old to support fsync with inode IDs. 989 * @param client The string representation of the client 990 * @param lastBlockLength The length of the last block (under construction) 991 * to be reported to NameNode 992 * @throws AccessControlException permission denied 993 * @throws FileNotFoundException file <code>src</code> is not found 994 * @throws UnresolvedLinkException if <code>src</code> contains a symlink. 995 * @throws IOException If an I/O error occurred 996 */ 997 @Idempotent fsync(String src, long inodeId, String client, long lastBlockLength)998 public void fsync(String src, long inodeId, String client, 999 long lastBlockLength) 1000 throws AccessControlException, FileNotFoundException, 1001 UnresolvedLinkException, IOException; 1002 1003 /** 1004 * Sets the modification and access time of the file to the specified time. 1005 * @param src The string representation of the path 1006 * @param mtime The number of milliseconds since Jan 1, 1970. 1007 * Setting mtime to -1 means that modification time should not be set 1008 * by this call. 1009 * @param atime The number of milliseconds since Jan 1, 1970. 1010 * Setting atime to -1 means that access time should not be set 1011 * by this call. 1012 * 1013 * @throws AccessControlException permission denied 1014 * @throws FileNotFoundException file <code>src</code> is not found 1015 * @throws UnresolvedLinkException if <code>src</code> contains a symlink. 1016 * @throws SnapshotAccessControlException if path is in RO snapshot 1017 * @throws IOException If an I/O error occurred 1018 */ 1019 @Idempotent setTimes(String src, long mtime, long atime)1020 public void setTimes(String src, long mtime, long atime) 1021 throws AccessControlException, FileNotFoundException, 1022 UnresolvedLinkException, SnapshotAccessControlException, IOException; 1023 1024 /** 1025 * Create symlink to a file or directory. 1026 * @param target The path of the destination that the 1027 * link points to. 1028 * @param link The path of the link being created. 1029 * @param dirPerm permissions to use when creating parent directories 1030 * @param createParent - if true then missing parent dirs are created 1031 * if false then parent must exist 1032 * 1033 * @throws AccessControlException permission denied 1034 * @throws FileAlreadyExistsException If file <code>link</code> already exists 1035 * @throws FileNotFoundException If parent of <code>link</code> does not exist 1036 * and <code>createParent</code> is false 1037 * @throws ParentNotDirectoryException If parent of <code>link</code> is not a 1038 * directory. 1039 * @throws UnresolvedLinkException if <code>link</target> contains a symlink. 1040 * @throws SnapshotAccessControlException if path is in RO snapshot 1041 * @throws IOException If an I/O error occurred 1042 */ 1043 @AtMostOnce createSymlink(String target, String link, FsPermission dirPerm, boolean createParent)1044 public void createSymlink(String target, String link, FsPermission dirPerm, 1045 boolean createParent) throws AccessControlException, 1046 FileAlreadyExistsException, FileNotFoundException, 1047 ParentNotDirectoryException, SafeModeException, UnresolvedLinkException, 1048 SnapshotAccessControlException, IOException; 1049 1050 /** 1051 * Return the target of the given symlink. If there is an intermediate 1052 * symlink in the path (ie a symlink leading up to the final path component) 1053 * then the given path is returned with this symlink resolved. 1054 * 1055 * @param path The path with a link that needs resolution. 1056 * @return The path after resolving the first symbolic link in the path. 1057 * @throws AccessControlException permission denied 1058 * @throws FileNotFoundException If <code>path</code> does not exist 1059 * @throws IOException If the given path does not refer to a symlink 1060 * or an I/O error occurred 1061 */ 1062 @Idempotent getLinkTarget(String path)1063 public String getLinkTarget(String path) throws AccessControlException, 1064 FileNotFoundException, IOException; 1065 1066 /** 1067 * Get a new generation stamp together with an access token for 1068 * a block under construction 1069 * 1070 * This method is called only when a client needs to recover a failed 1071 * pipeline or set up a pipeline for appending to a block. 1072 * 1073 * @param block a block 1074 * @param clientName the name of the client 1075 * @return a located block with a new generation stamp and an access token 1076 * @throws IOException if any error occurs 1077 */ 1078 @Idempotent updateBlockForPipeline(ExtendedBlock block, String clientName)1079 public LocatedBlock updateBlockForPipeline(ExtendedBlock block, 1080 String clientName) throws IOException; 1081 1082 /** 1083 * Update a pipeline for a block under construction 1084 * 1085 * @param clientName the name of the client 1086 * @param oldBlock the old block 1087 * @param newBlock the new block containing new generation stamp and length 1088 * @param newNodes datanodes in the pipeline 1089 * @throws IOException if any error occurs 1090 */ 1091 @AtMostOnce updatePipeline(String clientName, ExtendedBlock oldBlock, ExtendedBlock newBlock, DatanodeID[] newNodes, String[] newStorageIDs)1092 public void updatePipeline(String clientName, ExtendedBlock oldBlock, 1093 ExtendedBlock newBlock, DatanodeID[] newNodes, String[] newStorageIDs) 1094 throws IOException; 1095 1096 /** 1097 * Get a valid Delegation Token. 1098 * 1099 * @param renewer the designated renewer for the token 1100 * @return Token<DelegationTokenIdentifier> 1101 * @throws IOException 1102 */ 1103 @Idempotent getDelegationToken(Text renewer)1104 public Token<DelegationTokenIdentifier> getDelegationToken(Text renewer) 1105 throws IOException; 1106 1107 /** 1108 * Renew an existing delegation token. 1109 * 1110 * @param token delegation token obtained earlier 1111 * @return the new expiration time 1112 * @throws IOException 1113 */ 1114 @Idempotent renewDelegationToken(Token<DelegationTokenIdentifier> token)1115 public long renewDelegationToken(Token<DelegationTokenIdentifier> token) 1116 throws IOException; 1117 1118 /** 1119 * Cancel an existing delegation token. 1120 * 1121 * @param token delegation token 1122 * @throws IOException 1123 */ 1124 @Idempotent cancelDelegationToken(Token<DelegationTokenIdentifier> token)1125 public void cancelDelegationToken(Token<DelegationTokenIdentifier> token) 1126 throws IOException; 1127 1128 /** 1129 * @return encryption key so a client can encrypt data sent via the 1130 * DataTransferProtocol to/from DataNodes. 1131 * @throws IOException 1132 */ 1133 @Idempotent getDataEncryptionKey()1134 public DataEncryptionKey getDataEncryptionKey() throws IOException; 1135 1136 /** 1137 * Create a snapshot 1138 * @param snapshotRoot the path that is being snapshotted 1139 * @param snapshotName name of the snapshot created 1140 * @return the snapshot path. 1141 * @throws IOException 1142 */ 1143 @AtMostOnce createSnapshot(String snapshotRoot, String snapshotName)1144 public String createSnapshot(String snapshotRoot, String snapshotName) 1145 throws IOException; 1146 1147 /** 1148 * Delete a specific snapshot of a snapshottable directory 1149 * @param snapshotRoot The snapshottable directory 1150 * @param snapshotName Name of the snapshot for the snapshottable directory 1151 * @throws IOException 1152 */ 1153 @AtMostOnce deleteSnapshot(String snapshotRoot, String snapshotName)1154 public void deleteSnapshot(String snapshotRoot, String snapshotName) 1155 throws IOException; 1156 1157 /** 1158 * Rename a snapshot 1159 * @param snapshotRoot the directory path where the snapshot was taken 1160 * @param snapshotOldName old name of the snapshot 1161 * @param snapshotNewName new name of the snapshot 1162 * @throws IOException 1163 */ 1164 @AtMostOnce renameSnapshot(String snapshotRoot, String snapshotOldName, String snapshotNewName)1165 public void renameSnapshot(String snapshotRoot, String snapshotOldName, 1166 String snapshotNewName) throws IOException; 1167 1168 /** 1169 * Allow snapshot on a directory. 1170 * @param snapshotRoot the directory to be snapped 1171 * @throws IOException on error 1172 */ 1173 @Idempotent allowSnapshot(String snapshotRoot)1174 public void allowSnapshot(String snapshotRoot) 1175 throws IOException; 1176 1177 /** 1178 * Disallow snapshot on a directory. 1179 * @param snapshotRoot the directory to disallow snapshot 1180 * @throws IOException on error 1181 */ 1182 @Idempotent disallowSnapshot(String snapshotRoot)1183 public void disallowSnapshot(String snapshotRoot) 1184 throws IOException; 1185 1186 /** 1187 * Get the difference between two snapshots, or between a snapshot and the 1188 * current tree of a directory. 1189 * 1190 * @param snapshotRoot 1191 * full path of the directory where snapshots are taken 1192 * @param fromSnapshot 1193 * snapshot name of the from point. Null indicates the current 1194 * tree 1195 * @param toSnapshot 1196 * snapshot name of the to point. Null indicates the current 1197 * tree. 1198 * @return The difference report represented as a {@link SnapshotDiffReport}. 1199 * @throws IOException on error 1200 */ 1201 @Idempotent getSnapshotDiffReport(String snapshotRoot, String fromSnapshot, String toSnapshot)1202 public SnapshotDiffReport getSnapshotDiffReport(String snapshotRoot, 1203 String fromSnapshot, String toSnapshot) throws IOException; 1204 1205 /** 1206 * Add a CacheDirective to the CacheManager. 1207 * 1208 * @param directive A CacheDirectiveInfo to be added 1209 * @param flags {@link CacheFlag}s to use for this operation. 1210 * @return A CacheDirectiveInfo associated with the added directive 1211 * @throws IOException if the directive could not be added 1212 */ 1213 @AtMostOnce addCacheDirective(CacheDirectiveInfo directive, EnumSet<CacheFlag> flags)1214 public long addCacheDirective(CacheDirectiveInfo directive, 1215 EnumSet<CacheFlag> flags) throws IOException; 1216 1217 /** 1218 * Modify a CacheDirective in the CacheManager. 1219 * 1220 * @param flags {@link CacheFlag}s to use for this operation. 1221 * @throws IOException if the directive could not be modified 1222 */ 1223 @AtMostOnce modifyCacheDirective(CacheDirectiveInfo directive, EnumSet<CacheFlag> flags)1224 public void modifyCacheDirective(CacheDirectiveInfo directive, 1225 EnumSet<CacheFlag> flags) throws IOException; 1226 1227 /** 1228 * Remove a CacheDirectiveInfo from the CacheManager. 1229 * 1230 * @param id of a CacheDirectiveInfo 1231 * @throws IOException if the cache directive could not be removed 1232 */ 1233 @AtMostOnce removeCacheDirective(long id)1234 public void removeCacheDirective(long id) throws IOException; 1235 1236 /** 1237 * List the set of cached paths of a cache pool. Incrementally fetches results 1238 * from the server. 1239 * 1240 * @param prevId The last listed entry ID, or -1 if this is the first call to 1241 * listCacheDirectives. 1242 * @param filter Parameters to use to filter the list results, 1243 * or null to display all directives visible to us. 1244 * @return A batch of CacheDirectiveEntry objects. 1245 */ 1246 @Idempotent listCacheDirectives( long prevId, CacheDirectiveInfo filter)1247 public BatchedEntries<CacheDirectiveEntry> listCacheDirectives( 1248 long prevId, CacheDirectiveInfo filter) throws IOException; 1249 1250 /** 1251 * Add a new cache pool. 1252 * 1253 * @param info Description of the new cache pool 1254 * @throws IOException If the request could not be completed. 1255 */ 1256 @AtMostOnce addCachePool(CachePoolInfo info)1257 public void addCachePool(CachePoolInfo info) throws IOException; 1258 1259 /** 1260 * Modify an existing cache pool. 1261 * 1262 * @param req 1263 * The request to modify a cache pool. 1264 * @throws IOException 1265 * If the request could not be completed. 1266 */ 1267 @AtMostOnce modifyCachePool(CachePoolInfo req)1268 public void modifyCachePool(CachePoolInfo req) throws IOException; 1269 1270 /** 1271 * Remove a cache pool. 1272 * 1273 * @param pool name of the cache pool to remove. 1274 * @throws IOException if the cache pool did not exist, or could not be 1275 * removed. 1276 */ 1277 @AtMostOnce removeCachePool(String pool)1278 public void removeCachePool(String pool) throws IOException; 1279 1280 /** 1281 * List the set of cache pools. Incrementally fetches results from the server. 1282 * 1283 * @param prevPool name of the last pool listed, or the empty string if this is 1284 * the first invocation of listCachePools 1285 * @return A batch of CachePoolEntry objects. 1286 */ 1287 @Idempotent listCachePools(String prevPool)1288 public BatchedEntries<CachePoolEntry> listCachePools(String prevPool) 1289 throws IOException; 1290 1291 /** 1292 * Modifies ACL entries of files and directories. This method can add new ACL 1293 * entries or modify the permissions on existing ACL entries. All existing 1294 * ACL entries that are not specified in this call are retained without 1295 * changes. (Modifications are merged into the current ACL.) 1296 */ 1297 @Idempotent modifyAclEntries(String src, List<AclEntry> aclSpec)1298 public void modifyAclEntries(String src, List<AclEntry> aclSpec) 1299 throws IOException; 1300 1301 /** 1302 * Removes ACL entries from files and directories. Other ACL entries are 1303 * retained. 1304 */ 1305 @Idempotent removeAclEntries(String src, List<AclEntry> aclSpec)1306 public void removeAclEntries(String src, List<AclEntry> aclSpec) 1307 throws IOException; 1308 1309 /** 1310 * Removes all default ACL entries from files and directories. 1311 */ 1312 @Idempotent removeDefaultAcl(String src)1313 public void removeDefaultAcl(String src) throws IOException; 1314 1315 /** 1316 * Removes all but the base ACL entries of files and directories. The entries 1317 * for user, group, and others are retained for compatibility with permission 1318 * bits. 1319 */ 1320 @Idempotent removeAcl(String src)1321 public void removeAcl(String src) throws IOException; 1322 1323 /** 1324 * Fully replaces ACL of files and directories, discarding all existing 1325 * entries. 1326 */ 1327 @Idempotent setAcl(String src, List<AclEntry> aclSpec)1328 public void setAcl(String src, List<AclEntry> aclSpec) throws IOException; 1329 1330 /** 1331 * Gets the ACLs of files and directories. 1332 */ 1333 @Idempotent getAclStatus(String src)1334 public AclStatus getAclStatus(String src) throws IOException; 1335 1336 /** 1337 * Create an encryption zone 1338 */ 1339 @AtMostOnce createEncryptionZone(String src, String keyName)1340 public void createEncryptionZone(String src, String keyName) 1341 throws IOException; 1342 1343 /** 1344 * Get the encryption zone for a path. 1345 */ 1346 @Idempotent getEZForPath(String src)1347 public EncryptionZone getEZForPath(String src) 1348 throws IOException; 1349 1350 /** 1351 * Used to implement cursor-based batched listing of {@EncryptionZone}s. 1352 * 1353 * @param prevId ID of the last item in the previous batch. If there is no 1354 * previous batch, a negative value can be used. 1355 * @return Batch of encryption zones. 1356 */ 1357 @Idempotent listEncryptionZones( long prevId)1358 public BatchedEntries<EncryptionZone> listEncryptionZones( 1359 long prevId) throws IOException; 1360 1361 /** 1362 * Set xattr of a file or directory. 1363 * The name must be prefixed with the namespace followed by ".". For example, 1364 * "user.attr". 1365 * <p/> 1366 * Refer to the HDFS extended attributes user documentation for details. 1367 * 1368 * @param src file or directory 1369 * @param xAttr <code>XAttr</code> to set 1370 * @param flag set flag 1371 * @throws IOException 1372 */ 1373 @AtMostOnce setXAttr(String src, XAttr xAttr, EnumSet<XAttrSetFlag> flag)1374 public void setXAttr(String src, XAttr xAttr, EnumSet<XAttrSetFlag> flag) 1375 throws IOException; 1376 1377 /** 1378 * Get xattrs of a file or directory. Values in xAttrs parameter are ignored. 1379 * If xAttrs is null or empty, this is the same as getting all xattrs of the 1380 * file or directory. Only those xattrs for which the logged-in user has 1381 * permissions to view are returned. 1382 * <p/> 1383 * Refer to the HDFS extended attributes user documentation for details. 1384 * 1385 * @param src file or directory 1386 * @param xAttrs xAttrs to get 1387 * @return List<XAttr> <code>XAttr</code> list 1388 * @throws IOException 1389 */ 1390 @Idempotent getXAttrs(String src, List<XAttr> xAttrs)1391 public List<XAttr> getXAttrs(String src, List<XAttr> xAttrs) 1392 throws IOException; 1393 1394 /** 1395 * List the xattrs names for a file or directory. 1396 * Only the xattr names for which the logged in user has the permissions to 1397 * access will be returned. 1398 * <p/> 1399 * Refer to the HDFS extended attributes user documentation for details. 1400 * 1401 * @param src file or directory 1402 * @return List<XAttr> <code>XAttr</code> list 1403 * @throws IOException 1404 */ 1405 @Idempotent listXAttrs(String src)1406 public List<XAttr> listXAttrs(String src) 1407 throws IOException; 1408 1409 /** 1410 * Remove xattr of a file or directory.Value in xAttr parameter is ignored. 1411 * The name must be prefixed with the namespace followed by ".". For example, 1412 * "user.attr". 1413 * <p/> 1414 * Refer to the HDFS extended attributes user documentation for details. 1415 * 1416 * @param src file or directory 1417 * @param xAttr <code>XAttr</code> to remove 1418 * @throws IOException 1419 */ 1420 @AtMostOnce removeXAttr(String src, XAttr xAttr)1421 public void removeXAttr(String src, XAttr xAttr) throws IOException; 1422 1423 /** 1424 * Checks if the user can access a path. The mode specifies which access 1425 * checks to perform. If the requested permissions are granted, then the 1426 * method returns normally. If access is denied, then the method throws an 1427 * {@link AccessControlException}. 1428 * In general, applications should avoid using this method, due to the risk of 1429 * time-of-check/time-of-use race conditions. The permissions on a file may 1430 * change immediately after the access call returns. 1431 * 1432 * @param path Path to check 1433 * @param mode type of access to check 1434 * @throws AccessControlException if access is denied 1435 * @throws FileNotFoundException if the path does not exist 1436 * @throws IOException see specific implementation 1437 */ 1438 @Idempotent checkAccess(String path, FsAction mode)1439 public void checkAccess(String path, FsAction mode) throws IOException; 1440 1441 /** 1442 * Get the highest txid the NameNode knows has been written to the edit 1443 * log, or -1 if the NameNode's edit log is not yet open for write. Used as 1444 * the starting point for the inotify event stream. 1445 */ 1446 @Idempotent getCurrentEditLogTxid()1447 public long getCurrentEditLogTxid() throws IOException; 1448 1449 /** 1450 * Get an ordered list of batches of events corresponding to the edit log 1451 * transactions for txids equal to or greater than txid. 1452 */ 1453 @Idempotent getEditsFromTxid(long txid)1454 public EventBatchList getEditsFromTxid(long txid) throws IOException; 1455 } 1456