1992 lines
114 KiB
HTML
1992 lines
114 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<!--
|
|
| Generated by Apache Maven Doxia at 2023-03-02
|
|
| Rendered using Apache Maven Stylus Skin 1.5
|
|
-->
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Apache Hadoop 3.4.0-SNAPSHOT – class org.apache.hadoop.fs.FileSystem</title>
|
|
<style type="text/css" media="all">
|
|
@import url("../css/maven-base.css");
|
|
@import url("../css/maven-theme.css");
|
|
@import url("../css/site.css");
|
|
</style>
|
|
<link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
|
|
<meta name="Date-Revision-yyyymmdd" content="20230302" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|
</head>
|
|
<body class="composite">
|
|
<div id="banner">
|
|
<a href="http://hadoop.apache.org/" id="bannerLeft">
|
|
<img src="http://hadoop.apache.org/images/hadoop-logo.jpg" alt="" />
|
|
</a>
|
|
<a href="http://www.apache.org/" id="bannerRight">
|
|
<img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
|
|
</a>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
</div>
|
|
<div id="breadcrumbs">
|
|
|
|
<div class="xright"> <a href="http://wiki.apache.org/hadoop" class="externalLink">Wiki</a>
|
|
|
|
|
<a href="https://gitbox.apache.org/repos/asf/hadoop.git" class="externalLink">git</a>
|
|
|
|
|
<a href="http://hadoop.apache.org/" class="externalLink">Apache Hadoop</a>
|
|
|
|
| Last Published: 2023-03-02
|
|
| Version: 3.4.0-SNAPSHOT
|
|
</div>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
</div>
|
|
<div id="leftColumn">
|
|
<div id="navcolumn">
|
|
|
|
<h5>General</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../index.html">Overview</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/SingleCluster.html">Single Node Setup</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/ClusterSetup.html">Cluster Setup</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/CommandsManual.html">Commands Reference</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/FileSystemShell.html">FileSystem Shell</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/Compatibility.html">Compatibility Specification</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/DownstreamDev.html">Downstream Developer's Guide</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/AdminCompatibilityGuide.html">Admin Compatibility Guide</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/InterfaceClassification.html">Interface Classification</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/filesystem/index.html">FileSystem Specification</a>
|
|
</li>
|
|
</ul>
|
|
<h5>Common</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/CLIMiniCluster.html">CLI Mini Cluster</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/FairCallQueue.html">Fair Call Queue</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/NativeLibraries.html">Native Libraries</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/Superusers.html">Proxy User</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/RackAwareness.html">Rack Awareness</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/SecureMode.html">Secure Mode</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/ServiceLevelAuth.html">Service Level Authorization</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/HttpAuthentication.html">HTTP Authentication</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/CredentialProviderAPI.html">Credential Provider API</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-kms/index.html">Hadoop KMS</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/Tracing.html">Tracing</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/UnixShellGuide.html">Unix Shell Guide</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/registry/index.html">Registry</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/AsyncProfilerServlet.html">Async Profiler</a>
|
|
</li>
|
|
</ul>
|
|
<h5>HDFS</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsDesign.html">Architecture</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsUserGuide.html">User Guide</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSCommands.html">Commands Reference</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithQJM.html">NameNode HA With QJM</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithNFS.html">NameNode HA With NFS</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/ObserverNameNode.html">Observer NameNode</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/Federation.html">Federation</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/ViewFs.html">ViewFs</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/ViewFsOverloadScheme.html">ViewFsOverloadScheme</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsSnapshots.html">Snapshots</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsEditsViewer.html">Edits Viewer</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsImageViewer.html">Image Viewer</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsPermissionsGuide.html">Permissions and HDFS</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsQuotaAdminGuide.html">Quotas and HDFS</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/LibHdfs.html">libhdfs (C API)</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/WebHDFS.html">WebHDFS (REST API)</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-hdfs-httpfs/index.html">HttpFS</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/ShortCircuitLocalReads.html">Short Circuit Local Reads</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/CentralizedCacheManagement.html">Centralized Cache Management</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsNfsGateway.html">NFS Gateway</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsRollingUpgrade.html">Rolling Upgrade</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/ExtendedAttributes.html">Extended Attributes</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/TransparentEncryption.html">Transparent Encryption</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsMultihoming.html">Multihoming</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/ArchivalStorage.html">Storage Policies</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/MemoryStorage.html">Memory Storage Support</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/SLGUserGuide.html">Synthetic Load Generator</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSErasureCoding.html">Erasure Coding</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSDiskbalancer.html">Disk Balancer</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsUpgradeDomain.html">Upgrade Domain</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsDataNodeAdminGuide.html">DataNode Admin</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs-rbf/HDFSRouterFederation.html">Router Federation</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsProvidedStorage.html">Provided Storage</a>
|
|
</li>
|
|
</ul>
|
|
<h5>MapReduce</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapReduceTutorial.html">Tutorial</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapredCommands.html">Commands Reference</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapReduce_Compatibility_Hadoop1_Hadoop2.html">Compatibility with 1.x</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/EncryptedShuffle.html">Encrypted Shuffle</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/PluggableShuffleAndPluggableSort.html">Pluggable Shuffle/Sort</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/DistributedCacheDeploy.html">Distributed Cache Deploy</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/SharedCacheSupport.html">Support for YARN Shared Cache</a>
|
|
</li>
|
|
</ul>
|
|
<h5>MapReduce REST APIs</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapredAppMasterRest.html">MR Application Master</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-hs/HistoryServerRest.html">MR History Server</a>
|
|
</li>
|
|
</ul>
|
|
<h5>YARN</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/YARN.html">Architecture</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/YarnCommands.html">Commands Reference</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/CapacityScheduler.html">Capacity Scheduler</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/FairScheduler.html">Fair Scheduler</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/ResourceManagerRestart.html">ResourceManager Restart</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/ResourceManagerHA.html">ResourceManager HA</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/ResourceModel.html">Resource Model</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/NodeLabel.html">Node Labels</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/NodeAttributes.html">Node Attributes</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/WebApplicationProxy.html">Web Application Proxy</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/TimelineServer.html">Timeline Server</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/TimelineServiceV2.html">Timeline Service V.2</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/WritingYarnApplications.html">Writing YARN Applications</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/YarnApplicationSecurity.html">YARN Application Security</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/NodeManager.html">NodeManager</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/DockerContainers.html">Running Applications in Docker Containers</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/RuncContainers.html">Running Applications in runC Containers</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/NodeManagerCgroups.html">Using CGroups</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/SecureContainer.html">Secure Containers</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/ReservationSystem.html">Reservation System</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/GracefulDecommission.html">Graceful Decommission</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/OpportunisticContainers.html">Opportunistic Containers</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/Federation.html">YARN Federation</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/SharedCache.html">Shared Cache</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/UsingGpus.html">Using GPU</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/UsingFPGA.html">Using FPGA</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/PlacementConstraints.html">Placement Constraints</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/YarnUI2.html">YARN UI2</a>
|
|
</li>
|
|
</ul>
|
|
<h5>YARN REST APIs</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/WebServicesIntro.html">Introduction</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/ResourceManagerRest.html">Resource Manager</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/NodeManagerRest.html">Node Manager</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/TimelineServer.html#Timeline_Server_REST_API_v1">Timeline Server</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/TimelineServiceV2.html#Timeline_Service_v.2_REST_API">Timeline Service V.2</a>
|
|
</li>
|
|
</ul>
|
|
<h5>YARN Service</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/Overview.html">Overview</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/QuickStart.html">QuickStart</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/Concepts.html">Concepts</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/YarnServiceAPI.html">Yarn Service API</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/ServiceDiscovery.html">Service Discovery</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/SystemServices.html">System Services</a>
|
|
</li>
|
|
</ul>
|
|
<h5>Hadoop Compatible File Systems</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-aliyun/tools/hadoop-aliyun/index.html">Aliyun OSS</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-aws/tools/hadoop-aws/index.html">Amazon S3</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-azure/index.html">Azure Blob Storage</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-azure-datalake/index.html">Azure Data Lake Storage</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-cos/cloud-storage/index.html">Tencent COS</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-huaweicloud/cloud-storage/index.html">Huaweicloud OBS</a>
|
|
</li>
|
|
</ul>
|
|
<h5>Auth</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-auth/index.html">Overview</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-auth/Examples.html">Examples</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-auth/Configuration.html">Configuration</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-auth/BuildingIt.html">Building</a>
|
|
</li>
|
|
</ul>
|
|
<h5>Tools</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-streaming/HadoopStreaming.html">Hadoop Streaming</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-archives/HadoopArchives.html">Hadoop Archives</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-archive-logs/HadoopArchiveLogs.html">Hadoop Archive Logs</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-distcp/DistCp.html">DistCp</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-federation-balance/HDFSFederationBalance.html">HDFS Federation Balance</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-gridmix/GridMix.html">GridMix</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-rumen/Rumen.html">Rumen</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-resourceestimator/ResourceEstimator.html">Resource Estimator Service</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-sls/SchedulerLoadSimulator.html">Scheduler Load Simulator</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/Benchmarking.html">Hadoop Benchmarking</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-dynamometer/Dynamometer.html">Dynamometer</a>
|
|
</li>
|
|
</ul>
|
|
<h5>Reference</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/release/">Changelog and Release Notes</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../api/index.html">Java API docs</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/UnixShellAPI.html">Unix Shell API</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/Metrics.html">Metrics</a>
|
|
</li>
|
|
</ul>
|
|
<h5>Configuration</h5>
|
|
<ul>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/core-default.xml">core-default.xml</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs/hdfs-default.xml">hdfs-default.xml</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-hdfs-rbf/hdfs-rbf-default.xml">hdfs-rbf-default.xml</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/mapred-default.xml">mapred-default.xml</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-yarn/hadoop-yarn-common/yarn-default.xml">yarn-default.xml</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-kms/kms-default.html">kms-default.xml</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-hdfs-httpfs/httpfs-default.html">httpfs-default.xml</a>
|
|
</li>
|
|
<li class="none">
|
|
<a href="../../../hadoop-project-dist/hadoop-common/DeprecatedProperties.html">Deprecated Properties</a>
|
|
</li>
|
|
</ul>
|
|
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
|
|
<img alt="Built by Maven" src="../images/logos/maven-feather.png"/>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
<div id="bodyColumn">
|
|
<div id="contentBox">
|
|
<!---
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License. See accompanying LICENSE file.
|
|
-->
|
|
<!-- ============================================================= -->
|
|
<!-- CLASS: FileSystem -->
|
|
<!-- ============================================================= -->
|
|
<h1>class <code>org.apache.hadoop.fs.FileSystem</code></h1>
|
|
<ul>
|
|
<li><a href="#Invariants">Invariants</a></li>
|
|
<li><a href="#Feasible_features">Feasible features</a>
|
|
<ul>
|
|
<li><a href="#Protected_directories">Protected directories</a></li></ul></li>
|
|
<li><a href="#Predicates_and_other_state_access_operations">Predicates and other state access operations</a>
|
|
<ul>
|
|
<li><a href="#boolean_exists.28Path_p.29">boolean exists(Path p)</a></li>
|
|
<li><a href="#boolean_isDirectory.28Path_p.29">boolean isDirectory(Path p)</a></li>
|
|
<li><a href="#boolean_isFile.28Path_p.29">boolean isFile(Path p)</a></li>
|
|
<li><a href="#FileStatus_getFileStatus.28Path_p.29">FileStatus getFileStatus(Path p)</a></li>
|
|
<li><a href="#msync.28.29">msync()</a></li>
|
|
<li><a href="#Path_getHomeDirectory.28.29">Path getHomeDirectory()</a></li>
|
|
<li><a href="#FileStatus.5B.5D_listStatus.28Path_path.2C_PathFilter_filter.29">FileStatus[] listStatus(Path path, PathFilter filter)</a></li>
|
|
<li><a href="#FileStatus.5B.5D_listStatus.28Path_path.29">FileStatus[] listStatus(Path path)</a></li>
|
|
<li><a href="#FileStatus.5B.5D_listStatus.28Path.5B.5D_paths.2C_PathFilter_filter.29">FileStatus[] listStatus(Path[] paths, PathFilter filter)</a></li>
|
|
<li><a href="#RemoteIterator.3CFileStatus.3E_listStatusIterator.28Path_p.29">RemoteIterator<FileStatus> listStatusIterator(Path p)</a></li>
|
|
<li><a href="#FileStatus.5B.5D_listStatus.28Path.5B.5D_paths.29">FileStatus[] listStatus(Path[] paths)</a></li>
|
|
<li><a href="#RemoteIterator.5BLocatedFileStatus.5D_listLocatedStatus.28Path_path.2C_PathFilter_filter.29">RemoteIterator[LocatedFileStatus] listLocatedStatus(Path path, PathFilter filter)</a></li>
|
|
<li><a href="#RemoteIterator.5BLocatedFileStatus.5D_listLocatedStatus.28Path_path.29">RemoteIterator[LocatedFileStatus] listLocatedStatus(Path path)</a></li>
|
|
<li><a href="#RemoteIterator.5BLocatedFileStatus.5D_listFiles.28Path_path.2C_boolean_recursive.29">RemoteIterator[LocatedFileStatus] listFiles(Path path, boolean recursive)</a></li>
|
|
<li><a href="#Postconditions">Postconditions</a></li>
|
|
<li><a href="#ContentSummary_getContentSummary.28Path_path.29">ContentSummary getContentSummary(Path path)</a></li>
|
|
<li><a href="#BlockLocation.5B.5D_getFileBlockLocations.28FileStatus_f.2C_int_s.2C_int_l.29">BlockLocation[] getFileBlockLocations(FileStatus f, int s, int l)</a></li>
|
|
<li><a href="#BlockLocation.5B.5D_getFileBlockLocations.28Path_P.2C_int_S.2C_int_L.29">BlockLocation[] getFileBlockLocations(Path P, int S, int L)</a></li>
|
|
<li><a href="#long_getDefaultBlockSize.28.29">long getDefaultBlockSize()</a></li>
|
|
<li><a href="#long_getDefaultBlockSize.28Path_p.29">long getDefaultBlockSize(Path p)</a></li>
|
|
<li><a href="#long_getBlockSize.28Path_p.29">long getBlockSize(Path p)</a></li></ul></li>
|
|
<li><a href="#State_Changing_Operations"> State Changing Operations</a>
|
|
<ul>
|
|
<li><a href="#boolean_mkdirs.28Path_p.2C_FsPermission_permission.29">boolean mkdirs(Path p, FsPermission permission)</a></li>
|
|
<li><a href="#FSDataOutputStream_create.28Path.2C_....29"> FSDataOutputStream create(Path, ...)</a></li>
|
|
<li><a href="#FSDataOutputStreamBuilder_createFile.28Path_p.29">FSDataOutputStreamBuilder createFile(Path p)</a></li>
|
|
<li><a href="#FSDataOutputStream_append.28Path_p.2C_int_bufferSize.2C_Progressable_progress.29"> FSDataOutputStream append(Path p, int bufferSize, Progressable progress)</a></li>
|
|
<li><a href="#FSDataOutputStreamBuilder_appendFile.28Path_p.29">FSDataOutputStreamBuilder appendFile(Path p)</a></li>
|
|
<li><a href="#FSDataInputStream_open.28Path_f.2C_int_bufferSize.29">FSDataInputStream open(Path f, int bufferSize)</a></li>
|
|
<li><a href="#FSDataInputStreamBuilder_openFile.28Path_path.29">FSDataInputStreamBuilder openFile(Path path)</a></li>
|
|
<li><a href="#FSDataInputStreamBuilder_openFile.28PathHandle.29">FSDataInputStreamBuilder openFile(PathHandle)</a></li>
|
|
<li><a href="#PathHandle_getPathHandle.28FileStatus_stat.2C_HandleOpt..._options.29">PathHandle getPathHandle(FileStatus stat, HandleOpt... options)</a></li>
|
|
<li><a href="#FSDataInputStream_open.28PathHandle_handle.2C_int_bufferSize.29">FSDataInputStream open(PathHandle handle, int bufferSize)</a></li>
|
|
<li><a href="#boolean_delete.28Path_p.2C_boolean_recursive.29">boolean delete(Path p, boolean recursive)</a></li>
|
|
<li><a href="#Object_Stores:_root_directory_deletion"> Object Stores: root directory deletion</a></li>
|
|
<li><a href="#boolean_rename.28Path_src.2C_Path_d.29">boolean rename(Path src, Path d)</a></li>
|
|
<li><a href="#void_concat.28Path_p.2C_Path_sources.5B.5D.29">void concat(Path p, Path sources[])</a></li>
|
|
<li><a href="#boolean_truncate.28Path_p.2C_long_newLength.29">boolean truncate(Path p, long newLength)</a></li>
|
|
<li><a href="#boolean_copyFromLocalFile.28boolean_delSrc.2C_boolean_overwrite.2C_Path_src.2C_Path_dst.29">boolean copyFromLocalFile(boolean delSrc, boolean overwrite, Path src, Path dst)</a></li></ul></li>
|
|
<li><a href="#interface_RemoteIterator"> interface RemoteIterator</a>
|
|
<ul>
|
|
<li><a href="#boolean_hasNext.28.29">boolean hasNext()</a></li>
|
|
<li><a href="#E_next.28.29">E next()</a></li>
|
|
<li><a href="#Concurrency_and_the_Remote_Iterator">Concurrency and the Remote Iterator</a></li></ul></li>
|
|
<li><a href="#interface_StreamCapabilities"> interface StreamCapabilities</a>
|
|
<ul>
|
|
<li><a href="#boolean_hasCapability.28capability.29">boolean hasCapability(capability)</a></li></ul></li>
|
|
<li><a href="#Etag_probes_through_the_interface_EtagSource"> Etag probes through the interface EtagSource</a>
|
|
<ul>
|
|
<li><a href="#Etag_support_MUST_BE_across_all_list.2FgetFileStatus.28.29_calls.">Etag support MUST BE across all list/getFileStatus() calls.</a></li>
|
|
<li><a href="#FileStatus_instances_MUST_have_etags_whenever_the_remote_store_provides_them.">FileStatus instances MUST have etags whenever the remote store provides them.</a></li>
|
|
<li><a href="#Etags_of_files_MUST_BE_Consistent_across_all_list.2FgetFileStatus_operations.">Etags of files MUST BE Consistent across all list/getFileStatus operations.</a></li>
|
|
<li><a href="#Etags_MUST_BE_different_for_different_file_contents.">Etags MUST BE different for different file contents.</a></li>
|
|
<li><a href="#Etags_of_files_SHOULD_BE_preserved_across_rename_operations">Etags of files SHOULD BE preserved across rename operations</a></li>
|
|
<li><a href="#Directories_MAY_have_etags">Directories MAY have etags</a></li>
|
|
<li><a href="#All_etag-aware_FileStatus_subclass_MUST_BE_Serializable.3B_MAY_BE_Writable">All etag-aware FileStatus subclass MUST BE Serializable; MAY BE Writable</a></li>
|
|
<li><a href="#Appropriate_etag_Path_Capabilities_SHOULD_BE_declared">Appropriate etag Path Capabilities SHOULD BE declared</a></li>
|
|
<li><a href="#Non-requirements_of_etag_support">Non-requirements of etag support</a></li></ul></li></ul>
|
|
|
|
<p>The abstract <code>FileSystem</code> class is the original class to access Hadoop filesystems; non-abstract subclasses exist for all Hadoop-supported filesystems.</p>
|
|
<p>All operations that take a Path to this interface MUST support relative paths. In such a case, they must be resolved relative to the working directory defined by <code>setWorkingDirectory()</code>.</p>
|
|
<p>For all clients, therefore, we also add the notion of a state component PWD: this represents the present working directory of the client. Changes to this state are not reflected in the filesystem itself: they are unique to the instance of the client.</p>
|
|
<p><b>Implementation Note</b>: the static <code>FileSystem get(URI uri, Configuration conf)</code> method MAY return a pre-existing instance of a filesystem client class—a class that may also be in use in other threads. The implementations of <code>FileSystem</code> shipped with Apache Hadoop <i>do not make any attempt to synchronize access to the working directory field</i>.</p><section>
|
|
<h2><a name="Invariants"></a>Invariants</h2>
|
|
<p>All the requirements of a valid FileSystem are considered implicit preconditions and postconditions: all operations on a valid FileSystem MUST result in a new FileSystem that is also valid.</p></section><section>
|
|
<h2><a name="Feasible_features"></a>Feasible features</h2><section>
|
|
<h3><a name="Protected_directories"></a><a name="ProtectedDirectories"></a>Protected directories</h3>
|
|
<p>HDFS has the notion of <i>Protected Directories</i>, which are declared in the option <code>fs.protected.directories</code>. Any attempt to delete or rename such a directory or a parent thereof raises an <code>AccessControlException</code>. Accordingly, any attempt to delete the root directory SHALL, if there is a protected directory, result in such an exception being raised.</p></section></section><section>
|
|
<h2><a name="Predicates_and_other_state_access_operations"></a>Predicates and other state access operations</h2><section>
|
|
<h3><a name="boolean_exists.28Path_p.29"></a><code>boolean exists(Path p)</code></h3>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>def exists(FS, p) = p in paths(FS)
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h3><a name="boolean_isDirectory.28Path_p.29"></a><code>boolean isDirectory(Path p)</code></h3>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>def isDirectory(FS, p)= p in directories(FS)
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h3><a name="boolean_isFile.28Path_p.29"></a><code>boolean isFile(Path p)</code></h3>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>def isFile(FS, p) = p in files(FS)
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h3><a name="FileStatus_getFileStatus.28Path_p.29"></a><code>FileStatus getFileStatus(Path p)</code></h3>
|
|
<p>Get the status of a path</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not exists(FS, p) : raise FileNotFoundException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = stat: FileStatus where:
|
|
if isFile(FS, p) :
|
|
stat.length = len(FS.Files[p])
|
|
stat.isdir = False
|
|
stat.blockSize > 0
|
|
elif isDir(FS, p) :
|
|
stat.length = 0
|
|
stat.isdir = True
|
|
elif isSymlink(FS, p) :
|
|
stat.length = 0
|
|
stat.isdir = False
|
|
stat.symlink = FS.Symlinks[p]
|
|
stat.hasAcl = hasACL(FS, p)
|
|
stat.isEncrypted = inEncryptionZone(FS, p)
|
|
stat.isErasureCoded = isErasureCoded(FS, p)
|
|
</pre></div></div>
|
|
|
|
<p>The returned <code>FileStatus</code> status of the path additionally carries details on ACL, encryption and erasure coding information. <code>getFileStatus(Path p).hasAcl()</code> can be queried to find if the path has an ACL. <code>getFileStatus(Path p).isEncrypted()</code> can be queried to find if the path is encrypted. <code>getFileStatus(Path p).isErasureCoded()</code> will tell if the path is erasure coded or not.</p>
|
|
<p>YARN’s distributed cache lets applications add paths to be cached across containers and applications via <code>Job.addCacheFile()</code> and <code>Job.addCacheArchive()</code>. The cache treats world-readable resources paths added as shareable across applications, and downloads them differently, unless they are declared as encrypted.</p>
|
|
<p>To avoid failures during container launching, especially when delegation tokens are used, filesystems and object stores which not implement POSIX access permissions for both files and directories, MUST always return <code>true</code> to the <code>isEncrypted()</code> predicate. This can be done by setting the <code>encrypted</code> flag to true when creating the <code>FileStatus</code> instance.</p></section></section><section>
|
|
<h3><a name="msync.28.29"></a><code>msync()</code></h3>
|
|
<p>Synchronize metadata state of the client with the latest state of the metadata service of the FileSystem.</p>
|
|
<p>In highly available FileSystems standby service can be used as a read-only metadata replica. This call is essential to guarantee consistency of reads from the standby replica and to avoid stale reads.</p>
|
|
<p>It is currently only implemented for HDFS and others will just throw <code>UnsupportedOperationException</code>.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
<p>This call internally records the state of the metadata service at the time of the call. This guarantees consistency of subsequent reads from any metadata replica. It assures the client will never access the state of the metadata that preceded the recorded state.</p></section><section>
|
|
<h4><a name="HDFS_implementation_notes"></a>HDFS implementation notes</h4>
|
|
<p>HDFS supports <code>msync()</code> in HA mode by calling the Active NameNode and requesting its latest journal transaction ID. For more details see HDFS documentation <a class="externalLink" href="https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/ObserverNameNode.html">Consistent Reads from HDFS Observer NameNode</a></p></section></section><section>
|
|
<h3><a name="Path_getHomeDirectory.28.29"></a><code>Path getHomeDirectory()</code></h3>
|
|
<p>The function <code>getHomeDirectory</code> returns the home directory for the FileSystem and the current user account.</p>
|
|
<p>For some FileSystems, the path is <code>["/", "users", System.getProperty("user-name")]</code>.</p>
|
|
<p>However, for HDFS, the username is derived from the credentials used to authenticate the client with HDFS. This may differ from the local user account name.</p>
|
|
<p><b>It is the responsibility of the FileSystem to determine the actual home directory of the caller.</b></p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = p where valid-path(FS, p)
|
|
</pre></div></div>
|
|
|
|
<p>There is no requirement that the path exists at the time the method was called, or, if it exists, that it points to a directory. However, code tends to assume that <code>not isFile(FS, getHomeDirectory())</code> holds to the extent that follow-on code may fail.</p></section><section>
|
|
<h4><a name="Implementation_Notes"></a>Implementation Notes</h4>
|
|
<ul>
|
|
|
|
<li>The <code>FTPFileSystem</code> queries this value from the remote filesystem and may fail with a <code>RuntimeException</code> or subclass thereof if there is a connectivity problem. The time to execute the operation is not bounded.</li>
|
|
</ul></section></section><section>
|
|
<h3><a name="FileStatus.5B.5D_listStatus.28Path_path.2C_PathFilter_filter.29"></a><code>FileStatus[] listStatus(Path path, PathFilter filter)</code></h3>
|
|
<p>Lists entries under a path, <code>path</code>.</p>
|
|
<p>If <code>path</code> refers to a file and the filter accepts it, then that file’s <code>FileStatus</code> entry is returned in a single-element array.</p>
|
|
<p>If the path refers to a directory, the call returns a list of all its immediate child paths which are accepted by the filter —and does not include the directory itself.</p>
|
|
<p>A <code>PathFilter</code> <code>filter</code> is a class whose <code>accept(path)</code> returns true iff the path <code>path</code> meets the filter’s conditions.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
<p>Path <code>path</code> must exist:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not exists(FS, path) : raise FileNotFoundException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isFile(FS, path) and filter.accept(path) :
|
|
result = [ getFileStatus(path) ]
|
|
|
|
elif isFile(FS, path) and not filter.accept(P) :
|
|
result = []
|
|
|
|
elif isDir(FS, path):
|
|
result = [
|
|
getFileStatus(c) for c in children(FS, path) if filter.accepts(c)
|
|
]
|
|
</pre></div></div>
|
|
|
|
<p><b>Implicit invariant</b>: the contents of a <code>FileStatus</code> of a child retrieved via <code>listStatus()</code> are equal to those from a call of <code>getFileStatus()</code> to the same path:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>forall fs in listStatus(path) :
|
|
fs == getFileStatus(fs.path)
|
|
</pre></div></div>
|
|
|
|
<p><b>Ordering of results</b>: there is no guarantee of ordering of the listed entries. While HDFS currently returns an alphanumerically sorted list, neither the Posix <code>readdir()</code> nor Java’s <code>File.listFiles()</code> API calls define any ordering of returned values. Applications which require a uniform sort order on the results must perform the sorting themselves.</p>
|
|
<p><b>Null return</b>: Local filesystems prior to 3.0.0 returned null upon access error. It is considered erroneous. Expect IOException upon access error.</p></section><section>
|
|
<h4><a name="Atomicity_and_Consistency"></a>Atomicity and Consistency</h4>
|
|
<p>By the time the <code>listStatus()</code> operation returns to the caller, there is no guarantee that the information contained in the response is current. The details MAY be out of date, including the contents of any directory, the attributes of any files, and the existence of the path supplied.</p>
|
|
<p>The state of a directory MAY change during the evaluation process.</p>
|
|
<ul>
|
|
|
|
<li>
|
|
|
|
<p>After an entry at path <code>P</code> is created, and before any other changes are made to the filesystem, <code>listStatus(P)</code> MUST find the file and return its status.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>After an entry at path <code>P</code> is deleted, and before any other changes are made to the filesystem, <code>listStatus(P)</code> MUST raise a <code>FileNotFoundException</code>.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>After an entry at path <code>P</code> is created, and before any other changes are made to the filesystem, the result of <code>listStatus(parent(P))</code> SHOULD include the value of <code>getFileStatus(P)</code>.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>After an entry at path <code>P</code> is created, and before any other changes are made to the filesystem, the result of <code>listStatus(parent(P))</code> SHOULD NOT include the value of <code>getFileStatus(P)</code>.</p>
|
|
</li>
|
|
</ul>
|
|
<p>This is not a theoretical possibility, it is observable in HDFS when a directory contains many thousands of files.</p>
|
|
<p>Consider a directory <code>"/d"</code> with the contents:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>a
|
|
part-0000001
|
|
part-0000002
|
|
...
|
|
part-9999999
|
|
</pre></div></div>
|
|
|
|
<p>If the number of files is such that HDFS returns a partial listing in each response, then, if a listing <code>listStatus("/d")</code> takes place concurrently with the operation <code>rename("/d/a","/d/z"))</code>, the result may be one of:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>[a, part-0000001, ... , part-9999999]
|
|
[part-0000001, ... , part-9999999, z]
|
|
[a, part-0000001, ... , part-9999999, z]
|
|
[part-0000001, ... , part-9999999]
|
|
</pre></div></div>
|
|
|
|
<p>While this situation is likely to be a rare occurrence, it MAY happen. In HDFS these inconsistent views are only likely when listing a directory with many children.</p>
|
|
<p>Other filesystems may have stronger consistency guarantees, or return inconsistent data more readily.</p></section></section><section>
|
|
<h3><a name="FileStatus.5B.5D_listStatus.28Path_path.29"></a><code>FileStatus[] listStatus(Path path)</code></h3>
|
|
<p>This is exactly equivalent to <code>listStatus(Path, DEFAULT_FILTER)</code> where <code>DEFAULT_FILTER.accept(path) = True</code> for all paths.</p>
|
|
<p>The atomicity and consistency constraints are as for <code>listStatus(Path, DEFAULT_FILTER)</code>.</p></section><section>
|
|
<h3><a name="FileStatus.5B.5D_listStatus.28Path.5B.5D_paths.2C_PathFilter_filter.29"></a><code>FileStatus[] listStatus(Path[] paths, PathFilter filter)</code></h3>
|
|
<p>Enumerate all files found in the list of directories passed in, calling <code>listStatus(path, filter)</code> on each one.</p>
|
|
<p>As with <code>listStatus(path, filter)</code>, the results may be inconsistent. That is: the state of the filesystem changed during the operation.</p>
|
|
<p>There are no guarantees as to whether paths are listed in a specific order, only that they must all be listed, and, at the time of listing, exist.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
<p>All paths must exist. There is no requirement for uniqueness.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>forall p in paths :
|
|
exists(fs, p) else raise FileNotFoundException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
<p>The result is an array whose entries contain every status element found in the path listings, and no others.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = [listStatus(p, filter) for p in paths]
|
|
</pre></div></div>
|
|
|
|
<p>Implementations MAY merge duplicate entries; and/or optimize the operation by recoginizing duplicate paths and only listing the entries once.</p>
|
|
<p>The default implementation iterates through the list; it does not perform any optimizations.</p>
|
|
<p>The atomicity and consistency constraints are as for <code>listStatus(Path, PathFilter)</code>.</p></section></section><section>
|
|
<h3><a name="RemoteIterator.3CFileStatus.3E_listStatusIterator.28Path_p.29"></a><code>RemoteIterator<FileStatus> listStatusIterator(Path p)</code></h3>
|
|
<p>Return an iterator enumerating the <code>FileStatus</code> entries under a path. This is similar to <code>listStatus(Path)</code> except the fact that rather than returning an entire list, an iterator is returned. The result is exactly the same as <code>listStatus(Path)</code>, provided no other caller updates the directory during the listing. Having said that, this does not guarantee atomicity if other callers are adding/deleting the files inside the directory while listing is being performed. Different filesystems may provide a more efficient implementation, for example S3A does the listing in pages and fetches the next pages asynchronously while a page is getting processed.</p>
|
|
<p>Note that now since the initial listing is async, bucket/path existence exception may show up later during next() call.</p>
|
|
<p>Callers should prefer using listStatusIterator over listStatus as it is incremental in nature.</p></section><section>
|
|
<h3><a name="FileStatus.5B.5D_listStatus.28Path.5B.5D_paths.29"></a><code>FileStatus[] listStatus(Path[] paths)</code></h3>
|
|
<p>Enumerate all files found in the list of directories passed in, calling <code>listStatus(path, DEFAULT_FILTER)</code> on each one, where the <code>DEFAULT_FILTER</code> accepts all path names.</p></section><section>
|
|
<h3><a name="RemoteIterator.5BLocatedFileStatus.5D_listLocatedStatus.28Path_path.2C_PathFilter_filter.29"></a><code>RemoteIterator[LocatedFileStatus] listLocatedStatus(Path path, PathFilter filter)</code></h3>
|
|
<p>Return an iterator enumerating the <code>LocatedFileStatus</code> entries under a path. This is similar to <code>listStatus(Path)</code> except that the return value is an instance of the <code>LocatedFileStatus</code> subclass of a <code>FileStatus</code>, and that rather than return an entire list, an iterator is returned.</p>
|
|
<p>This is actually a <code>protected</code> method, directly invoked by <code>listLocatedStatus(Path path)</code>. Calls to it may be delegated through layered filesystems, such as <code>FilterFileSystem</code>, so its implementation MUST be considered mandatory, even if <code>listLocatedStatus(Path path)</code> has been implemented in a different manner. There are open JIRAs proposing making this method public; it may happen in future.</p>
|
|
<p>There is no requirement for the iterator to provide a consistent view of the child entries of a path. The default implementation does use <code>listStatus(Path)</code> to list its children, with its consistency constraints already documented. Other implementations may perform the enumeration even more dynamically. For example fetching a windowed subset of child entries, so avoiding building up large data structures and the transmission of large messages. In such situations, changes to the filesystem are more likely to become visible.</p>
|
|
<p>Callers MUST assume that the iteration operation MAY fail if changes to the filesystem take place between this call returning and the iteration being completely performed.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
<p>Path <code>path</code> must exist:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>exists(FS, path) : raise FileNotFoundException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
<p>The operation generates a set of results, <code>resultset</code>, equal to the result of <code>listStatus(path, filter)</code>:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isFile(FS, path) and filter.accept(path) :
|
|
resultset = [ getLocatedFileStatus(FS, path) ]
|
|
|
|
elif isFile(FS, path) and not filter.accept(path) :
|
|
resultset = []
|
|
|
|
elif isDir(FS, path) :
|
|
resultset = [
|
|
getLocatedFileStatus(FS, c)
|
|
for c in children(FS, path) where filter.accept(c)
|
|
]
|
|
</pre></div></div>
|
|
|
|
<p>The operation <code>getLocatedFileStatus(FS, path: Path): LocatedFileStatus</code> is defined as a generator of a <code>LocatedFileStatus</code> instance <code>ls</code> where:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>fileStatus = getFileStatus(FS, path)
|
|
|
|
bl = getFileBlockLocations(FS, path, 0, fileStatus.len)
|
|
|
|
locatedFileStatus = new LocatedFileStatus(fileStatus, bl)
|
|
</pre></div></div>
|
|
|
|
<p>The ordering in which the elements of <code>resultset</code> are returned in the iterator is undefined.</p>
|
|
<p>The atomicity and consistency constraints are as for <code>listStatus(Path, PathFilter)</code>.</p></section></section><section>
|
|
<h3><a name="RemoteIterator.5BLocatedFileStatus.5D_listLocatedStatus.28Path_path.29"></a><code>RemoteIterator[LocatedFileStatus] listLocatedStatus(Path path)</code></h3>
|
|
<p>The equivalent to <code>listLocatedStatus(path, DEFAULT_FILTER)</code>, where <code>DEFAULT_FILTER</code> accepts all path names.</p></section><section>
|
|
<h3><a name="RemoteIterator.5BLocatedFileStatus.5D_listFiles.28Path_path.2C_boolean_recursive.29"></a><code>RemoteIterator[LocatedFileStatus] listFiles(Path path, boolean recursive)</code></h3>
|
|
<p>Create an iterator over all files in/under a directory, potentially recursing into child directories.</p>
|
|
<p>The goal of this operation is to permit large recursive directory scans to be handled more efficiently by filesystems, by reducing the amount of data which must be collected in a single RPC call.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>exists(FS, path) else raise FileNotFoundException
|
|
</pre></div></div>
|
|
</section></section><section>
|
|
<h3><a name="Postconditions"></a>Postconditions</h3>
|
|
<p>The outcome is an iterator, whose output from the sequence of <code>iterator.next()</code> calls can be defined as the set <code>iteratorset</code>:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not recursive:
|
|
iteratorset == listStatus(path)
|
|
else:
|
|
iteratorset = [
|
|
getLocatedFileStatus(FS, d)
|
|
for d in descendants(FS, path)
|
|
]
|
|
</pre></div></div>
|
|
|
|
<p>The function <code>getLocatedFileStatus(FS, d)</code> is as defined in <code>listLocatedStatus(Path, PathFilter)</code>.</p>
|
|
<p>The atomicity and consistency constraints are as for <code>listStatus(Path, PathFilter)</code>.</p></section><section>
|
|
<h3><a name="ContentSummary_getContentSummary.28Path_path.29"></a><code>ContentSummary getContentSummary(Path path)</code></h3>
|
|
<p>Given a path return its content summary.</p>
|
|
<p><code>getContentSummary()</code> first checks if the given path is a file and if yes, it returns 0 for directory count and 1 for file count.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>exists(FS, path) else raise FileNotFoundException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
<p>Returns a <code>ContentSummary</code> object with information such as directory count and file count for a given path.</p>
|
|
<p>The atomicity and consistency constraints are as for <code>listStatus(Path, PathFilter)</code>.</p></section></section><section>
|
|
<h3><a name="BlockLocation.5B.5D_getFileBlockLocations.28FileStatus_f.2C_int_s.2C_int_l.29"></a><code>BlockLocation[] getFileBlockLocations(FileStatus f, int s, int l)</code></h3><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if s < 0 or l < 0 : raise {HadoopIllegalArgumentException, InvalidArgumentException}
|
|
</pre></div></div>
|
|
|
|
<ul>
|
|
|
|
<li>HDFS throws <code>HadoopIllegalArgumentException</code> for an invalid offset or length; this extends <code>IllegalArgumentException</code>.</li>
|
|
</ul></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
<p>If the filesystem is location aware, it must return the list of block locations where the data in the range <code>[s:s+l]</code> can be found.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if f == null :
|
|
result = null
|
|
elif f.getLen() <= s:
|
|
result = []
|
|
else result = [ locations(FS, b) for b in blocks(FS, p, s, s+l)]
|
|
</pre></div></div>
|
|
|
|
<p>Where</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre> def locations(FS, b) = a list of all locations of a block in the filesystem
|
|
|
|
def blocks(FS, p, s, s + l) = a list of the blocks containing data(FS, path)[s:s+l]
|
|
</pre></div></div>
|
|
|
|
<p>Note that as <code>length(FS, f)</code> is defined as <code>0</code> if <code>isDir(FS, f)</code>, the result of <code>getFileBlockLocations()</code> on a directory is <code>[]</code></p>
|
|
<p>If the filesystem is not location aware, it SHOULD return</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre> [
|
|
BlockLocation(["localhost:9866"] ,
|
|
["localhost"],
|
|
["/default/localhost"]
|
|
0, f.getLen())
|
|
] ;
|
|
</pre></div></div>
|
|
|
|
<p>*A bug in Hadoop 1.0.3 means that a topology path of the same number of elements as the cluster topology MUST be provided, hence Filesystems SHOULD return that <code>"/default/localhost"</code> path. While this is no longer an issue, the convention is generally retained.</p></section></section><section>
|
|
<h3><a name="BlockLocation.5B.5D_getFileBlockLocations.28Path_P.2C_int_S.2C_int_L.29"></a><code>BlockLocation[] getFileBlockLocations(Path P, int S, int L)</code></h3><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if p == null : raise NullPointerException
|
|
if not exists(FS, p) : raise FileNotFoundException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = getFileBlockLocations(getFileStatus(FS, P), S, L)
|
|
</pre></div></div>
|
|
</section></section><section>
|
|
<h3><a name="long_getDefaultBlockSize.28.29"></a><code>long getDefaultBlockSize()</code></h3>
|
|
<p>Get the “default” block size for a filesystem. This is often used during split calculations to divide work optimally across a set of worker processes.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = integer > 0
|
|
</pre></div></div>
|
|
|
|
<p>Although there is no defined minimum value for this result, as it is used to partition work during job submission, a block size that is too small will result in badly partitioned workload, or even the <code>JobSubmissionClient</code> and equivalent running out of memory as it calculates the partitions.</p>
|
|
<p>Any FileSystem that does not actually break files into blocks SHOULD return a number for this that results in efficient processing. A FileSystem MAY make this user-configurable (the object store connectors usually do this).</p></section></section><section>
|
|
<h3><a name="long_getDefaultBlockSize.28Path_p.29"></a><code>long getDefaultBlockSize(Path p)</code></h3>
|
|
<p>Get the “default” block size for a path –that is, the block size to be used when writing objects to a path in the filesystem.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = integer >= 0
|
|
</pre></div></div>
|
|
|
|
<p>The outcome of this operation is usually identical to <code>getDefaultBlockSize()</code>, with no checks for the existence of the given path.</p>
|
|
<p>Filesystems that support mount points may have different default values for different paths, in which case the specific default value for the destination path SHOULD be returned.</p>
|
|
<p>It is not an error if the path does not exist: the default/recommended value for that part of the filesystem MUST be returned.</p></section></section><section>
|
|
<h3><a name="long_getBlockSize.28Path_p.29"></a><code>long getBlockSize(Path p)</code></h3>
|
|
<p>This method is exactly equivalent to querying the block size of the <code>FileStatus</code> structure returned in <code>getFileStatus(p)</code>. It is deprecated in order to encourage users to make a single call to <code>getFileStatus(p)</code> and then use the result to examine multiple attributes of the file (e.g. length, type, block size). If more than one attribute is queried, This can become a significant performance optimization —and reduce load on the filesystem.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not exists(FS, p) : raise FileNotFoundException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if len(FS, P) > 0: getFileStatus(P).getBlockSize() > 0
|
|
result == getFileStatus(P).getBlockSize()
|
|
</pre></div></div>
|
|
|
|
<ol style="list-style-type: decimal">
|
|
|
|
<li>The outcome of this operation MUST be identical to the value of <code>getFileStatus(P).getBlockSize()</code>.</li>
|
|
<li>By inference, it MUST be > 0 for any file of length > 0.</li>
|
|
</ol></section></section></section><section>
|
|
<h2><a name="State_Changing_Operations"></a><a name="state_changing_operations"></a> State Changing Operations</h2><section>
|
|
<h3><a name="boolean_mkdirs.28Path_p.2C_FsPermission_permission.29"></a><code>boolean mkdirs(Path p, FsPermission permission)</code></h3>
|
|
<p>Create a directory and all its parents.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
<p>The path must either be a directory or not exist</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre> if exists(FS, p) and not isDir(FS, p) :
|
|
raise [ParentNotDirectoryException, FileAlreadyExistsException, IOException]
|
|
</pre></div></div>
|
|
|
|
<p>No ancestor may be a file</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>forall d = ancestors(FS, p) :
|
|
if exists(FS, d) and not isDir(FS, d) :
|
|
raise [ParentNotDirectoryException, FileAlreadyExistsException, IOException]
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>FS' where FS'.Directories' = FS.Directories + [p] + ancestors(FS, p)
|
|
result = True
|
|
</pre></div></div>
|
|
|
|
<p>The condition exclusivity requirement of a FileSystem’s directories, files and symbolic links must hold.</p>
|
|
<p>The probe for the existence and type of a path and directory creation MUST be atomic. The combined operation, including <code>mkdirs(parent(F))</code> MAY be atomic.</p>
|
|
<p>The return value is always true—even if a new directory is not created (this is defined in HDFS).</p></section></section><section>
|
|
<h3><a name="FSDataOutputStream_create.28Path.2C_....29"></a><a name="FileSystem.create"></a> <code>FSDataOutputStream create(Path, ...)</code></h3>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>FSDataOutputStream create(Path p,
|
|
FsPermission permission,
|
|
boolean overwrite,
|
|
int bufferSize,
|
|
short replication,
|
|
long blockSize,
|
|
Progressable progress) throws IOException;
|
|
</pre></div></div>
|
|
<section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
<p>The file must not exist for a no-overwrite create:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not overwrite and isFile(FS, p) : raise FileAlreadyExistsException
|
|
</pre></div></div>
|
|
|
|
<p>Writing to or overwriting a directory must fail.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(FS, p) : raise {FileAlreadyExistsException, FileNotFoundException, IOException}
|
|
</pre></div></div>
|
|
|
|
<p>No ancestor may be a file</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>forall d = ancestors(FS, p) :
|
|
if exists(FS, d) and not isDir(FS, d) :
|
|
raise [ParentNotDirectoryException, FileAlreadyExistsException, IOException]
|
|
</pre></div></div>
|
|
|
|
<p>FileSystems may reject the request for other reasons, such as the FS being read-only (HDFS), the block size being below the minimum permitted (HDFS), the replication count being out of range (HDFS), quotas on namespace or filesystem being exceeded, reserved names, etc. All rejections SHOULD be <code>IOException</code> or a subclass thereof and MAY be a <code>RuntimeException</code> or subclass. For instance, HDFS may raise an <code>InvalidPathException</code>.</p></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>FS' where :
|
|
FS'.Files'[p] == []
|
|
ancestors(p) is-subset-of FS'.Directories'
|
|
|
|
result = FSDataOutputStream
|
|
</pre></div></div>
|
|
|
|
<p>A zero byte file MUST exist at the end of the specified path, visible to all.</p>
|
|
<p>The updated (valid) FileSystem MUST contain all the parent directories of the path, as created by <code>mkdirs(parent(p))</code>.</p>
|
|
<p>The result is <code>FSDataOutputStream</code>, which through its operations may generate new filesystem states with updated values of <code>FS.Files[p]</code></p>
|
|
<p>The behavior of the returned stream is covered in <a href="outputstream.html">Output</a>.</p></section><section>
|
|
<h4><a name="Implementation_Notes"></a>Implementation Notes</h4>
|
|
<ul>
|
|
|
|
<li>
|
|
|
|
<p>Some implementations split the create into a check for the file existing from the actual creation. This means the operation is NOT atomic: it is possible for clients creating files with <code>overwrite==true</code> to fail if the file is created by another client between the two tests.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>The S3A and potentially other Object Stores connectors not currently change the <code>FS</code> state until the output stream <code>close()</code> operation is completed. This is a significant difference between the behavior of object stores and that of filesystems, as it allows >1 client to create a file with <code>overwrite=false</code>, and potentially confuse file/directory logic. In particular, using <code>create()</code> to acquire an exclusive lock on a file (whoever creates the file without an error is considered the holder of the lock) may not be a safe algorithm to use when working with object stores.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>Object stores may create an empty file as a marker when a file is created. However, object stores with <code>overwrite=true</code> semantics may not implement this atomically, so creating files with <code>overwrite=false</code> cannot be used as an implicit exclusion mechanism between processes.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>The Local FileSystem raises a <code>FileNotFoundException</code> when trying to create a file over a directory, hence it is listed as an exception that MAY be raised when this precondition fails.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>Not covered: symlinks. The resolved path of the symlink is used as the final path argument to the <code>create()</code> operation</p>
|
|
</li>
|
|
</ul></section></section><section>
|
|
<h3><a name="FSDataOutputStreamBuilder_createFile.28Path_p.29"></a><code>FSDataOutputStreamBuilder createFile(Path p)</code></h3>
|
|
<p>Make a <code>FSDataOutputStreamBuilder</code> to specify the parameters to create a file.</p>
|
|
<p>The behavior of the returned stream is covered in <a href="outputstream.html">Output</a>.</p><section>
|
|
<h4><a name="Implementation_Notes"></a>Implementation Notes</h4>
|
|
<p><code>createFile(p)</code> returns a <code>FSDataOutputStreamBuilder</code> only and does not make change on filesystem immediately. When <code>build()</code> is invoked on the <code>FSDataOutputStreamBuilder</code>, the builder parameters are verified and <a href="#FileSystem.create"><code>create(Path p)</code></a> is invoked on the underlying filesystem. <code>build()</code> has the same preconditions and postconditions as <a href="#FileSystem.create"><code>create(Path p)</code></a>.</p>
|
|
<ul>
|
|
|
|
<li>Similar to <a href="#FileSystem.create"><code>create(Path p)</code></a>, files are overwritten by default, unless specify <code>builder.overwrite(false)</code>.</li>
|
|
<li>Unlike <a href="#FileSystem.create"><code>create(Path p)</code></a>, missing parent directories are not created by default, unless specify <code>builder.recursive()</code>.</li>
|
|
</ul></section></section><section>
|
|
<h3><a name="FSDataOutputStream_append.28Path_p.2C_int_bufferSize.2C_Progressable_progress.29"></a><a name="FileSystem.append"></a> <code>FSDataOutputStream append(Path p, int bufferSize, Progressable progress)</code></h3>
|
|
<p>Implementations without a compliant call SHOULD throw <code>UnsupportedOperationException</code>.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not exists(FS, p) : raise FileNotFoundException
|
|
|
|
if not isFile(FS, p) : raise [FileAlreadyExistsException, FileNotFoundException, IOException]
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>FS' = FS
|
|
result = FSDataOutputStream
|
|
</pre></div></div>
|
|
|
|
<p>Return: <code>FSDataOutputStream</code>, which can update the entry <code>FS.Files[p]</code> by appending data to the existing list.</p>
|
|
<p>The behavior of the returned stream is covered in <a href="outputstream.html">Output</a>.</p></section></section><section>
|
|
<h3><a name="FSDataOutputStreamBuilder_appendFile.28Path_p.29"></a><code>FSDataOutputStreamBuilder appendFile(Path p)</code></h3>
|
|
<p>Make a <code>FSDataOutputStreamBuilder</code> to specify the parameters to append to an existing file.</p>
|
|
<p>The behavior of the returned stream is covered in <a href="outputstream.html">Output</a>.</p><section>
|
|
<h4><a name="Implementation_Notes"></a>Implementation Notes</h4>
|
|
<p><code>appendFile(p)</code> returns a <code>FSDataOutputStreamBuilder</code> only and does not make change on filesystem immediately. When <code>build()</code> is invoked on the <code>FSDataOutputStreamBuilder</code>, the builder parameters are verified and <a href="#FileSystem.append"><code>append()</code></a> is invoked on the underlying filesystem. <code>build()</code> has the same preconditions and postconditions as <a href="#FileSystem.append"><code>append()</code></a>.</p></section></section><section>
|
|
<h3><a name="FSDataInputStream_open.28Path_f.2C_int_bufferSize.29"></a><code>FSDataInputStream open(Path f, int bufferSize)</code></h3>
|
|
<p>Implementations without a compliant call SHOULD throw <code>UnsupportedOperationException</code>.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not isFile(FS, p)) : raise [FileNotFoundException, IOException]
|
|
</pre></div></div>
|
|
|
|
<p>This is a critical precondition. Implementations of some FileSystems (e.g. Object stores) could shortcut one round trip by postponing their HTTP GET operation until the first <code>read()</code> on the returned <code>FSDataInputStream</code>. However, much client code does depend on the existence check being performed at the time of the <code>open()</code> operation. Implementations MUST check for the presence of the file at the time of creation. This does not imply that the file and its data is still at the time of the following <code>read()</code> or any successors.</p></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = FSDataInputStream(0, FS.Files[p])
|
|
</pre></div></div>
|
|
|
|
<p>The result provides access to the byte array defined by <code>FS.Files[p]</code>; whether that access is to the contents at the time the <code>open()</code> operation was invoked, or whether and how it may pick up changes to that data in later states of FS is an implementation detail.</p>
|
|
<p>The result MUST be the same for local and remote callers of the operation.</p></section><section>
|
|
<h4><a name="HDFS_implementation_notes"></a>HDFS implementation notes</h4>
|
|
<ol style="list-style-type: decimal">
|
|
|
|
<li>
|
|
|
|
<p>HDFS MAY throw <code>UnresolvedPathException</code> when attempting to traverse symbolic links</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>HDFS throws <code>IOException("Cannot open filename " + src)</code> if the path exists in the metadata, but no copies of any its blocks can be located; -<code>FileNotFoundException</code> would seem more accurate and useful.</p>
|
|
</li>
|
|
</ol></section></section><section>
|
|
<h3><a name="FSDataInputStreamBuilder_openFile.28Path_path.29"></a><code>FSDataInputStreamBuilder openFile(Path path)</code></h3>
|
|
<p>See <a href="openfile.html">openFile()</a>.</p></section><section>
|
|
<h3><a name="FSDataInputStreamBuilder_openFile.28PathHandle.29"></a><code>FSDataInputStreamBuilder openFile(PathHandle)</code></h3>
|
|
<p>See <a href="openfile.html">openFile()</a>.</p></section><section>
|
|
<h3><a name="PathHandle_getPathHandle.28FileStatus_stat.2C_HandleOpt..._options.29"></a><code>PathHandle getPathHandle(FileStatus stat, HandleOpt... options)</code></h3>
|
|
<p>Implementations without a compliant call MUST throw <code>UnsupportedOperationException</code></p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>let stat = getFileStatus(Path p)
|
|
let FS' where:
|
|
(FS.Directories', FS.Files', FS.Symlinks')
|
|
p' in paths(FS') where:
|
|
exists(FS, stat.path) implies exists(FS', p')
|
|
</pre></div></div>
|
|
|
|
<p>The referent of a <code>FileStatus</code> instance, at the time it was resolved, is the same referent as the result of <code>getPathHandle(FileStatus)</code>. The <code>PathHandle</code> may be used in subsequent operations to ensure invariants hold between calls.</p>
|
|
<p>The <code>options</code> parameter specifies whether a subsequent call e.g., <code>open(PathHandle)</code> will succeed if the referent data or location changed. By default, any modification results in an error. The caller MAY specify relaxations that allow operations to succeed even if the referent exists at a different path and/or its data are changed.</p>
|
|
<p>An implementation MUST throw <code>UnsupportedOperationException</code> if it cannot support the semantics specified by the caller. The default set of options are as follows.</p>
|
|
<table border="0" class="bodyTable">
|
|
<thead>
|
|
|
|
<tr class="a">
|
|
<th align="right"> </th>
|
|
<th align="center"> Unmoved </th>
|
|
<th align="center"> Moved </th></tr>
|
|
</thead><tbody>
|
|
|
|
<tr class="b">
|
|
<td align="right"> Unchanged </td>
|
|
<td align="center"> EXACT </td>
|
|
<td align="center"> CONTENT </td></tr>
|
|
<tr class="a">
|
|
<td align="right"> Changed </td>
|
|
<td align="center"> PATH </td>
|
|
<td align="center"> REFERENCE </td></tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Changes to ownership, extended attributes, and other metadata are not required to match the <code>PathHandle</code>. Implementations can extend the set of <code>HandleOpt</code> parameters with custom constraints.</p><section>
|
|
<h5><a name="Examples"></a>Examples</h5>
|
|
<p>A client specifies that the <code>PathHandle</code> should track the entity across renames using <code>REFERENCE</code>. The implementation MUST throw an <code>UnsupportedOperationException</code> when creating the <code>PathHandle</code> unless failure to resolve the reference implies the entity no longer exists.</p>
|
|
<p>A client specifies that the <code>PathHandle</code> should resolve only if the entity is unchanged using <code>PATH</code>. The implementation MUST throw an <code>UnsupportedOperationException</code> when creating the <code>PathHandle</code> unless it can distinguish between an identical entity located subsequently at the same path.</p></section></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = PathHandle(p')
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Implementation_notes"></a>Implementation notes</h4>
|
|
<p>The referent of a <code>PathHandle</code> is the namespace when the <code>FileStatus</code> instance was created, <i>not</i> its state when the <code>PathHandle</code> is created. An implementation MAY reject attempts to create or resolve <code>PathHandle</code> instances that are valid, but expensive to service.</p>
|
|
<p>Object stores that implement rename by copying objects MUST NOT claim to support <code>CONTENT</code> and <code>REFERENCE</code> unless the lineage of the object is resolved.</p>
|
|
<p>It MUST be possible to serialize a <code>PathHandle</code> instance and reinstantiate it in one or more processes, on another machine, and arbitrarily far into the future without changing its semantics. The implementation MUST refuse to resolve instances if it can no longer guarantee its invariants.</p></section><section>
|
|
<h4><a name="HDFS_implementation_notes"></a>HDFS implementation notes</h4>
|
|
<p>HDFS does not support <code>PathHandle</code> references to directories or symlinks. Support for <code>CONTENT</code> and <code>REFERENCE</code> looks up files by INode. INodes are not unique across NameNodes, so federated clusters SHOULD include enough metadata in the <code>PathHandle</code> to detect references from other namespaces.</p></section></section><section>
|
|
<h3><a name="FSDataInputStream_open.28PathHandle_handle.2C_int_bufferSize.29"></a><code>FSDataInputStream open(PathHandle handle, int bufferSize)</code></h3>
|
|
<p>Implementaions without a compliant call MUST throw <code>UnsupportedOperationException</code></p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>let fd = getPathHandle(FileStatus stat)
|
|
if stat.isdir : raise IOException
|
|
let FS' where:
|
|
(FS.Directories', FS.Files', FS.Symlinks')
|
|
p' in FS.Files' where:
|
|
FS.Files'[p'] = fd
|
|
if not exists(FS', p') : raise InvalidPathHandleException
|
|
</pre></div></div>
|
|
|
|
<p>The implementation MUST resolve the referent of the <code>PathHandle</code> following the constraints specified at its creation by <code>getPathHandle(FileStatus)</code>.</p>
|
|
<p>Metadata necessary for the <code>FileSystem</code> to satisfy this contract MAY be encoded in the <code>PathHandle</code>.</p></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = FSDataInputStream(0, FS.Files'[p'])
|
|
</pre></div></div>
|
|
|
|
<p>The stream returned is subject to the constraints of a stream returned by <code>open(Path)</code>. Constraints checked on open MAY hold to hold for the stream, but this is not guaranteed.</p>
|
|
<p>For example, a <code>PathHandle</code> created with <code>CONTENT</code> constraints MAY return a stream that ignores updates to the file after it is opened, if it was unmodified when <code>open(PathHandle)</code> was resolved.</p></section><section>
|
|
<h4><a name="Implementation_notes"></a>Implementation notes</h4>
|
|
<p>An implementation MAY check invariants either at the server or before returning the stream to the client. For example, an implementation may open the file, then verify the invariants in the <code>PathHandle</code> using <code>getFileStatus(Path)</code> to implement <code>CONTENT</code>. This could yield false positives and it requires additional RPC traffic.</p></section></section><section>
|
|
<h3><a name="boolean_delete.28Path_p.2C_boolean_recursive.29"></a><code>boolean delete(Path p, boolean recursive)</code></h3>
|
|
<p>Delete a path, be it a file, symbolic link or directory. The <code>recursive</code> flag indicates whether a recursive delete should take place —if unset then a non-empty directory cannot be deleted.</p>
|
|
<p>Except in the special case of the root directory, if this API call completed successfully then there is nothing at the end of the path. That is: the outcome is desired. The return flag simply tells the caller whether or not any change was made to the state of the filesystem.</p>
|
|
<p><i>Note</i>: many uses of this method surround it with checks for the return value being false, raising exception if so. For example</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if (!fs.delete(path, true)) throw new IOException("Could not delete " + path);
|
|
</pre></div></div>
|
|
|
|
<p>This pattern is not needed. Code SHOULD just call <code>delete(path, recursive)</code> and assume the destination is no longer present —except in the special case of root directories, which will always remain (see below for special coverage of root directories).</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
<p>A directory with children and <code>recursive == False</code> cannot be deleted</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(FS, p) and not recursive and (children(FS, p) != {}) : raise IOException
|
|
</pre></div></div>
|
|
|
|
<p>(HDFS raises <code>PathIsNotEmptyDirectoryException</code> here.)</p></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4><section>
|
|
<h5><a name="Nonexistent_path"></a>Nonexistent path</h5>
|
|
<p>If the file does not exist the filesystem state does not change</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not exists(FS, p):
|
|
FS' = FS
|
|
result = False
|
|
</pre></div></div>
|
|
|
|
<p>The result SHOULD be <code>False</code>, indicating that no file was deleted.</p></section><section>
|
|
<h5><a name="Simple_File"></a>Simple File</h5>
|
|
<p>A path referring to a file is removed, return value: <code>True</code></p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isFile(FS, p) :
|
|
FS' = (FS.Directories, FS.Files - [p], FS.Symlinks)
|
|
result = True
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h5><a name="Empty_root_directory.2C_recursive_.3D.3D_False"></a>Empty root directory, <code>recursive == False</code></h5>
|
|
<p>Deleting an empty root does not change the filesystem state and may return true or false.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isRoot(p) and children(FS, p) == {} :
|
|
FS ' = FS
|
|
result = (undetermined)
|
|
</pre></div></div>
|
|
|
|
<p>There is no consistent return code from an attempt to delete the root directory.</p>
|
|
<p>Implementations SHOULD return true; this avoids code which checks for a false return value from overreacting.</p>
|
|
<p><i>Object Stores</i>: see <a href="#object-stores-rm-root">Object Stores: root directory deletion</a>.</p></section><section>
|
|
<h5><a name="Empty_.28non-root.29_directory_recursive_.3D.3D_False"></a>Empty (non-root) directory <code>recursive == False</code></h5>
|
|
<p>Deleting an empty directory that is not root will remove the path from the FS and return true.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(FS, p) and not isRoot(p) and children(FS, p) == {} :
|
|
FS' = (FS.Directories - [p], FS.Files, FS.Symlinks)
|
|
result = True
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h5><a name="Recursive_delete_of_non-empty_root_directory"></a>Recursive delete of non-empty root directory</h5>
|
|
<p>Deleting a root path with children and <code>recursive==True</code> can generally have three outcomes:</p>
|
|
<ol style="list-style-type: decimal">
|
|
|
|
<li>
|
|
|
|
<p>The POSIX model assumes that if the user has the correct permissions to delete everything, they are free to do so (resulting in an empty filesystem).</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(FS, p) and isRoot(p) and recursive :
|
|
FS' = ({["/"]}, {}, {}, {})
|
|
result = True
|
|
</pre></div></div>
|
|
</li>
|
|
<li>
|
|
|
|
<p>HDFS never permits the deletion of the root of a filesystem; the filesystem must be taken offline and reformatted if an empty filesystem is desired.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(FS, p) and isRoot(p) and recursive :
|
|
FS' = FS
|
|
result = False
|
|
</pre></div></div>
|
|
</li>
|
|
<li>
|
|
|
|
<p>Object Stores: see <a href="#object-stores-rm-root">Object Stores: root directory deletion</a>.</p>
|
|
</li>
|
|
</ol>
|
|
<p>This specification does not recommend any specific action. Do note, however, that the POSIX model assumes that there is a permissions model such that normal users do not have the permission to delete that root directory; it is an action which only system administrators should be able to perform.</p>
|
|
<p>Any filesystem client which interacts with a remote filesystem which lacks such a security model, MAY reject calls to <code>delete("/", true)</code> on the basis that it makes it too easy to lose data.</p></section></section></section><section>
|
|
<h3><a name="Object_Stores:_root_directory_deletion"></a><a name="object-stores-rm-root"></a> Object Stores: root directory deletion</h3>
|
|
<p>Some of the object store based filesystem implementations always return false when deleting the root, leaving the state of the store unchanged.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isRoot(p) :
|
|
FS ' = FS
|
|
result = False
|
|
</pre></div></div>
|
|
|
|
<p>This is irrespective of the recursive flag status or the state of the directory.</p>
|
|
<p>This is a simplification which avoids the inevitably non-atomic scan and delete of the contents of the store. It also avoids any confusion about whether the operation actually deletes that specific store/container itself, and adverse consequences of the simpler permissions models of stores.</p><section><section>
|
|
<h5><a name="Recursive_delete_of_non-root_directory"></a>Recursive delete of non-root directory</h5>
|
|
<p>Deleting a non-root path with children <code>recursive==true</code> removes the path and all descendants</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(FS, p) and not isRoot(p) and recursive :
|
|
FS' where:
|
|
not isDir(FS', p)
|
|
and forall d in descendants(FS, p):
|
|
not isDir(FS', d)
|
|
not isFile(FS', d)
|
|
not isSymlink(FS', d)
|
|
result = True
|
|
</pre></div></div>
|
|
</section></section><section>
|
|
<h4><a name="Atomicity"></a>Atomicity</h4>
|
|
<ul>
|
|
|
|
<li>
|
|
|
|
<p>Deleting a file MUST be an atomic action.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>Deleting an empty directory MUST be an atomic action.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>A recursive delete of a directory tree MUST be atomic.</p>
|
|
</li>
|
|
</ul></section><section>
|
|
<h4><a name="Implementation_Notes"></a>Implementation Notes</h4>
|
|
<ul>
|
|
|
|
<li>Object Stores and other non-traditional filesystems onto which a directory tree is emulated, tend to implement <code>delete()</code> as recursive listing and entry-by-entry delete operation. This can break the expectations of client applications for O(1) atomic directory deletion, preventing the stores’ use as drop-in replacements for HDFS.</li>
|
|
</ul></section></section><section>
|
|
<h3><a name="boolean_rename.28Path_src.2C_Path_d.29"></a><code>boolean rename(Path src, Path d)</code></h3>
|
|
<p>In terms of its specification, <code>rename()</code> is one of the most complex operations within a filesystem.</p>
|
|
<p>In terms of its implementation, it is the one with the most ambiguity regarding when to return false versus raising an exception.</p>
|
|
<p>Rename includes the calculation of the destination path. If the destination exists and is a directory, the final destination of the rename becomes the destination + the filename of the source path.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>let dest = if (isDir(FS, d) and d != src) :
|
|
d + [filename(src)]
|
|
else :
|
|
d
|
|
</pre></div></div>
|
|
<section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
<p>All checks on the destination path MUST take place after the final <code>dest</code> path has been calculated.</p>
|
|
<p>Source <code>src</code> must exist:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>exists(FS, src) else raise FileNotFoundException
|
|
</pre></div></div>
|
|
|
|
<p><code>dest</code> cannot be a descendant of <code>src</code>:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDescendant(FS, src, dest) : raise IOException
|
|
</pre></div></div>
|
|
|
|
<p>This implicitly covers the special case of <code>isRoot(FS, src)</code>.</p>
|
|
<p><code>dest</code> must be root, or have a parent that exists:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>isRoot(FS, dest) or exists(FS, parent(dest)) else raise IOException
|
|
</pre></div></div>
|
|
|
|
<p>The parent path of a destination must not be a file:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isFile(FS, parent(dest)) : raise IOException
|
|
</pre></div></div>
|
|
|
|
<p>This implicitly covers all the ancestors of the parent.</p>
|
|
<p>There must not be an existing file at the end of the destination path:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isFile(FS, dest) : raise FileAlreadyExistsException, IOException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4><section>
|
|
<h5><a name="Renaming_a_directory_onto_itself"></a>Renaming a directory onto itself</h5>
|
|
<p>Renaming a directory onto itself is no-op; return value is not specified.</p>
|
|
<p>In POSIX the result is <code>False</code>; in HDFS the result is <code>True</code>.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(FS, src) and src == dest :
|
|
FS' = FS
|
|
result = (undefined)
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h5><a name="Renaming_a_file_to_self"></a>Renaming a file to self</h5>
|
|
<p>Renaming a file to itself is a no-op; the result is <code>True</code>.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre> if isFile(FS, src) and src == dest :
|
|
FS' = FS
|
|
result = True
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h5><a name="Renaming_a_file_onto_a_nonexistent_path"></a>Renaming a file onto a nonexistent path</h5>
|
|
<p>Renaming a file where the destination is a directory moves the file as a child of the destination directory, retaining the filename element of the source path.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isFile(FS, src) and src != dest:
|
|
FS' where:
|
|
not exists(FS', src)
|
|
and exists(FS', dest)
|
|
and data(FS', dest) == data (FS, source)
|
|
result = True
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h5><a name="Renaming_a_directory_onto_a_directory"></a>Renaming a directory onto a directory</h5>
|
|
<p>If <code>src</code> is a directory then all its children will then exist under <code>dest</code>, while the path <code>src</code> and its descendants will no longer exist. The names of the paths under <code>dest</code> will match those under <code>src</code>, as will the contents:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(FS, src) and isDir(FS, dest) and src != dest :
|
|
FS' where:
|
|
not exists(FS', src)
|
|
and dest in FS'.Directories
|
|
and forall c in descendants(FS, src) :
|
|
not exists(FS', c))
|
|
and forall c in descendants(FS, src) where isDir(FS, c):
|
|
isDir(FS', dest + childElements(src, c)
|
|
and forall c in descendants(FS, src) where not isDir(FS, c):
|
|
data(FS', dest + childElements(s, c)) == data(FS, c)
|
|
result = True
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h5><a name="Renaming_into_a_path_where_the_parent_path_does_not_exist"></a>Renaming into a path where the parent path does not exist</h5>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre> not exists(FS, parent(dest))
|
|
</pre></div></div>
|
|
|
|
<p>There is no consistent behavior here.</p>
|
|
<p><i>HDFS</i></p>
|
|
<p>The outcome is no change to FileSystem state, with a return value of false.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>FS' = FS; result = False
|
|
</pre></div></div>
|
|
|
|
<p><i>Local Filesystem</i></p>
|
|
<p>The outcome is as a normal rename, with the additional (implicit) feature that the parent directories of the destination also exist.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>exists(FS', parent(dest))
|
|
</pre></div></div>
|
|
|
|
<p><i>S3A FileSystem</i></p>
|
|
<p>The outcome is as a normal rename, with the additional (implicit) feature that the parent directories of the destination then exist: <code>exists(FS', parent(dest))</code></p>
|
|
<p>There is a check for and rejection if the <code>parent(dest)</code> is a file, but no checks for any other ancestors.</p>
|
|
<p><i>Other Filesystems</i></p>
|
|
<p>Other filesystems strictly reject the operation, raising a <code>FileNotFoundException</code></p></section><section>
|
|
<h5><a name="Concurrency_requirements"></a>Concurrency requirements</h5>
|
|
<ul>
|
|
|
|
<li>
|
|
|
|
<p>The core operation of <code>rename()</code>—moving one entry in the filesystem to another—MUST be atomic. Some applications rely on this as a way to coordinate access to data.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>Some FileSystem implementations perform checks on the destination FileSystem before and after the rename. One example of this is <code>ChecksumFileSystem</code>, which provides checksummed access to local data. The entire sequence MAY NOT be atomic.</p>
|
|
</li>
|
|
</ul></section><section>
|
|
<h5><a name="Implementation_Notes"></a>Implementation Notes</h5>
|
|
<p><b>Files open for reading, writing or appending</b></p>
|
|
<p>The behavior of <code>rename()</code> on an open file is unspecified: whether it is allowed, what happens to later attempts to read from or write to the open stream</p>
|
|
<p><b>Renaming a directory onto itself</b></p>
|
|
<p>The return code of renaming a directory onto itself is unspecified.</p>
|
|
<p><b>Destination exists and is a file</b></p>
|
|
<p>Renaming a file atop an existing file is specified as failing, raising an exception.</p>
|
|
<ul>
|
|
|
|
<li>
|
|
|
|
<p>Local FileSystem : the rename succeeds; the destination file is replaced by the source file.</p>
|
|
</li>
|
|
<li>
|
|
|
|
<p>HDFS : The rename fails, no exception is raised. Instead the method call simply returns false.</p>
|
|
</li>
|
|
</ul>
|
|
<p><b>Missing source file</b></p>
|
|
<p>If the source file <code>src</code> does not exist, <code>FileNotFoundException</code> should be raised.</p>
|
|
<p>HDFS fails without raising an exception; <code>rename()</code> merely returns false.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>FS' = FS
|
|
result = false
|
|
</pre></div></div>
|
|
|
|
<p>The behavior of HDFS here should not be considered a feature to replicate. <code>FileContext</code> explicitly changed the behavior to raise an exception, and the retrofitting of that action to the <code>DFSFileSystem</code> implementation is an ongoing matter for debate.</p></section></section></section><section>
|
|
<h3><a name="void_concat.28Path_p.2C_Path_sources.5B.5D.29"></a><code>void concat(Path p, Path sources[])</code></h3>
|
|
<p>Joins multiple blocks together to create a single file. This is a little-used operation currently implemented only by HDFS.</p>
|
|
<p>Implementations without a compliant call SHOULD throw <code>UnsupportedOperationException</code>.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not exists(FS, p) : raise FileNotFoundException
|
|
|
|
if sources==[] : raise IllegalArgumentException
|
|
</pre></div></div>
|
|
|
|
<p>All sources MUST be in the same directory:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>for s in sources: if parent(S) != parent(p) raise IllegalArgumentException
|
|
</pre></div></div>
|
|
|
|
<p>All block sizes must match that of the target:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>for s in sources: getBlockSize(FS, S) == getBlockSize(FS, p)
|
|
</pre></div></div>
|
|
|
|
<p>No duplicate paths:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>not (exists p1, p2 in (sources + [p]) where p1 == p2)
|
|
</pre></div></div>
|
|
|
|
<p>HDFS: All source files except the final one MUST be a complete block:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>for s in (sources[0:length(sources)-1] + [p]):
|
|
(length(FS, s) mod getBlockSize(FS, p)) == 0
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>FS' where:
|
|
(data(FS', T) = data(FS, T) + data(FS, sources[0]) + ... + data(FS, srcs[length(srcs)-1]))
|
|
and for s in srcs: not exists(FS', S)
|
|
</pre></div></div>
|
|
|
|
<p>HDFS’s restrictions may be an implementation detail of how it implements <code>concat</code> by changing the inode references to join them together in a sequence. As no other filesystem in the Hadoop core codebase implements this method, there is no way to distinguish implementation detail from specification.</p></section></section><section>
|
|
<h3><a name="boolean_truncate.28Path_p.2C_long_newLength.29"></a><code>boolean truncate(Path p, long newLength)</code></h3>
|
|
<p>Truncate file <code>p</code> to the specified <code>newLength</code>.</p>
|
|
<p>Implementations without a compliant call SHOULD throw <code>UnsupportedOperationException</code>.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not exists(FS, p) : raise FileNotFoundException
|
|
|
|
if isDir(FS, p) : raise [FileNotFoundException, IOException]
|
|
|
|
if newLength < 0 || newLength > len(FS.Files[p]) : raise HadoopIllegalArgumentException
|
|
</pre></div></div>
|
|
|
|
<p>HDFS: The source file MUST be closed. Truncate cannot be performed on a file, which is open for writing or appending.</p></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>FS' where:
|
|
len(FS.Files[p]) = newLength
|
|
</pre></div></div>
|
|
|
|
<p>Return: <code>true</code>, if truncation is finished and the file can be immediately opened for appending, or <code>false</code> otherwise.</p>
|
|
<p>HDFS: HDFS returns <code>false</code> to indicate that a background process of adjusting the length of the last block has been started, and clients should wait for it to complete before they can proceed with further file updates.</p></section><section>
|
|
<h4><a name="Concurrency"></a>Concurrency</h4>
|
|
<p>If an input stream is open when truncate() occurs, the outcome of read operations related to the part of the file being truncated is undefined.</p></section></section><section>
|
|
<h3><a name="boolean_copyFromLocalFile.28boolean_delSrc.2C_boolean_overwrite.2C_Path_src.2C_Path_dst.29"></a><code>boolean copyFromLocalFile(boolean delSrc, boolean overwrite, Path src, Path dst)</code></h3>
|
|
<p>The source file or directory at <code>src</code> is on the local disk and is copied into the file system at destination <code>dst</code>. If the source must be deleted after the move then <code>delSrc</code> flag must be set to TRUE. If destination already exists, and the destination contents must be overwritten then <code>overwrite</code> flag must be set to TRUE.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
<p>Source and destination must be different</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if src = dest : raise FileExistsException
|
|
</pre></div></div>
|
|
|
|
<p>Destination and source must not be descendants one another</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDescendant(src, dest) or isDescendant(dest, src) : raise IOException
|
|
</pre></div></div>
|
|
|
|
<p>The source file or directory must exist locally:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if not exists(LocalFS, src) : raise FileNotFoundException
|
|
</pre></div></div>
|
|
|
|
<p>Directories cannot be copied into files regardless to what the overwrite flag is set to:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(LocalFS, src) and isFile(FS, dst) : raise PathExistsException
|
|
</pre></div></div>
|
|
|
|
<p>For all cases, except the one for which the above precondition throws, the overwrite flag must be set to TRUE for the operation to succeed if destination exists. This will also overwrite any files / directories at the destination:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if exists(FS, dst) and not overwrite : raise PathExistsException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Determining_the_final_name_of_the_copy"></a>Determining the final name of the copy</h4>
|
|
<p>Given a base path on the source <code>base</code> and a child path <code>child</code> where <code>base</code> is in <code>ancestors(child) + child</code>:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>def final_name(base, child, dest):
|
|
is base = child:
|
|
return dest
|
|
else:
|
|
return dest + childElements(base, child)
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Outcome_where_source_is_a_file_isFile.28LocalFS.2C_src.29"></a>Outcome where source is a file <code>isFile(LocalFS, src)</code></h4>
|
|
<p>For a file, data at destination becomes that of the source. All ancestors are directories.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isFile(LocalFS, src) and (not exists(FS, dest) or (exists(FS, dest) and overwrite)):
|
|
FS' = FS where:
|
|
FS'.Files[dest] = LocalFS.Files[src]
|
|
FS'.Directories = FS.Directories + ancestors(FS, dest)
|
|
LocalFS' = LocalFS where
|
|
not delSrc or (delSrc = true and delete(LocalFS, src, false))
|
|
else if isFile(LocalFS, src) and isDir(FS, dest):
|
|
FS' = FS where:
|
|
let d = final_name(src, dest)
|
|
FS'.Files[d] = LocalFS.Files[src]
|
|
LocalFS' = LocalFS where:
|
|
not delSrc or (delSrc = true and delete(LocalFS, src, false))
|
|
</pre></div></div>
|
|
|
|
<p>There are no expectations that the file changes are atomic for both local <code>LocalFS</code> and remote <code>FS</code>.</p></section><section>
|
|
<h4><a name="Outcome_where_source_is_a_directory_isDir.28LocalFS.2C_src.29"></a>Outcome where source is a directory <code>isDir(LocalFS, src)</code></h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>if isDir(LocalFS, src) and (isFile(FS, dest) or isFile(FS, dest + childElements(src))):
|
|
raise FileAlreadyExistsException
|
|
else if isDir(LocalFS, src):
|
|
if exists(FS, dest):
|
|
dest' = dest + childElements(src)
|
|
if exists(FS, dest') and not overwrite:
|
|
raise PathExistsException
|
|
else:
|
|
dest' = dest
|
|
|
|
FS' = FS where:
|
|
forall c in descendants(LocalFS, src):
|
|
not exists(FS', final_name(c)) or overwrite
|
|
and forall c in descendants(LocalFS, src) where isDir(LocalFS, c):
|
|
FS'.Directories = FS'.Directories + (dest' + childElements(src, c))
|
|
and forall c in descendants(LocalFS, src) where isFile(LocalFS, c):
|
|
FS'.Files[final_name(c, dest')] = LocalFS.Files[c]
|
|
LocalFS' = LocalFS where
|
|
not delSrc or (delSrc = true and delete(LocalFS, src, true))
|
|
</pre></div></div>
|
|
|
|
<p>There are no expectations of operation isolation / atomicity. This means files can change in source or destination while the operation is executing. No guarantees are made for the final state of the file or directory after a copy other than it is best effort. E.g.: when copying a directory, one file can be moved from source to destination but there’s nothing stopping the new file at destination being updated while the copy operation is still in place.</p></section><section>
|
|
<h4><a name="Implementation"></a>Implementation</h4>
|
|
<p>The default HDFS implementation, is to recurse through each file and folder, found at <code>src</code>, and copy them sequentially to their final destination (relative to <code>dst</code>).</p>
|
|
<p>Object store based file systems should be mindful of what limitations arise from the above implementation and could take advantage of parallel uploads and possible re-ordering of files copied into the store to maximize throughput.</p></section></section></section><section>
|
|
<h2><a name="interface_RemoteIterator"></a><a name="RemoteIterator"></a> interface <code>RemoteIterator</code></h2>
|
|
<p>The <code>RemoteIterator</code> interface is used as a remote-access equivalent to <code>java.util.Iterator</code>, allowing the caller to iterate through a finite sequence of remote data elements.</p>
|
|
<p>The core differences are</p>
|
|
<ol style="list-style-type: decimal">
|
|
|
|
<li><code>Iterator</code>’s optional <code>void remove()</code> method is not supported.</li>
|
|
<li>For those methods which are supported, <code>IOException</code> exceptions may be raised.</li>
|
|
</ol>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>public interface RemoteIterator<E> {
|
|
boolean hasNext() throws IOException;
|
|
E next() throws IOException;
|
|
}
|
|
</pre></div></div>
|
|
|
|
<p>The basic view of the interface is that <code>hasNext()</code> being true implies that <code>next()</code> will successfully return the next entry in the list:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>while hasNext(): next()
|
|
</pre></div></div>
|
|
|
|
<p>Equally, a successful call to <code>next()</code> implies that had <code>hasNext()</code> been invoked prior to the call to <code>next()</code>, it would have been true.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>boolean elementAvailable = hasNext();
|
|
try {
|
|
next();
|
|
assert elementAvailable;
|
|
} catch (NoSuchElementException e) {
|
|
assert !elementAvailable
|
|
}
|
|
</pre></div></div>
|
|
|
|
<p>The <code>next()</code> operator MUST iterate through the list of available results, <i>even if no calls to <code>hasNext()</code> are made</i>.</p>
|
|
<p>That is, it is possible to enumerate the results through a loop which only terminates when a <code>NoSuchElementException</code> exception is raised.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>try {
|
|
while (true) {
|
|
process(iterator.next());
|
|
}
|
|
} catch (NoSuchElementException ignored) {
|
|
// the end of the list has been reached
|
|
}
|
|
</pre></div></div>
|
|
|
|
<p>The output of the iteration is equivalent to the loop</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>while (iterator.hasNext()) {
|
|
process(iterator.next());
|
|
}
|
|
</pre></div></div>
|
|
|
|
<p>As raising exceptions is an expensive operation in JVMs, the <code>while(hasNext())</code> loop option is more efficient. (see also <a href="#RemoteIteratorConcurrency">Concurrency and the Remote Iterator</a> for a dicussion on this topic).</p>
|
|
<p>Implementors of the interface MUST support both forms of iterations; authors of tests SHOULD verify that both iteration mechanisms work.</p>
|
|
<p>The iteration is required to return a finite sequence; both forms of loop MUST ultimately terminate. All implementations of the interface in the Hadoop codebase meet this requirement; all consumers assume that it holds.</p><section>
|
|
<h3><a name="boolean_hasNext.28.29"></a><code>boolean hasNext()</code></h3>
|
|
<p>Returns true if-and-only-if a subsequent single call to <code>next()</code> would return an element rather than raise an exception.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4></section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = True ==> next() will succeed.
|
|
result = False ==> next() will raise an exception
|
|
</pre></div></div>
|
|
|
|
<p>Multiple calls to <code>hasNext()</code>, without any intervening <code>next()</code> calls, MUST return the same value.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>boolean has1 = iterator.hasNext();
|
|
boolean has2 = iterator.hasNext();
|
|
assert has1 == has2;
|
|
</pre></div></div>
|
|
</section></section><section>
|
|
<h3><a name="E_next.28.29"></a><code>E next()</code></h3>
|
|
<p>Return the next element in the iteration.</p><section>
|
|
<h4><a name="Preconditions"></a>Preconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>hasNext() else raise java.util.NoSuchElementException
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h4><a name="Postconditions"></a>Postconditions</h4>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>result = the next element in the iteration
|
|
</pre></div></div>
|
|
|
|
<p>Repeated calls to <code>next()</code> return subsequent elements in the sequence, until the entire sequence has been returned.</p></section></section><section>
|
|
<h3><a name="Concurrency_and_the_Remote_Iterator"></a><a name="RemoteIteratorConcurrency"></a>Concurrency and the Remote Iterator</h3>
|
|
<p>The primary use of <code>RemoteIterator</code> in the filesystem APIs is to list files on (possibly remote) filesystems. These filesystems are invariably accessed concurrently; the state of the filesystem MAY change between a <code>hasNext()</code> probe and the invocation of the <code>next()</code> call.</p>
|
|
<p>During iteration through a <code>RemoteIterator</code>, if the directory is deleted on remote filesystem, then <code>hasNext()</code> or <code>next()</code> call may throw <code>FileNotFoundException</code>.</p>
|
|
<p>Accordingly, a robust iteration through a <code>RemoteIterator</code> would catch and discard <code>NoSuchElementException</code> exceptions raised during the process, which could be done through the <code>while(true)</code> iteration example above, or through a <code>hasNext()/next()</code> sequence with an outer <code>try/catch</code> clause to catch a <code>NoSuchElementException</code> alongside other exceptions which may be raised during a failure (for example, a <code>FileNotFoundException</code>)</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>try {
|
|
while (iterator.hasNext()) {
|
|
process(iterator.next());
|
|
}
|
|
} catch (NoSuchElementException ignored) {
|
|
// the end of the list has been reached
|
|
}
|
|
</pre></div></div>
|
|
|
|
<p>It is notable that this is <i>not</i> done in the Hadoop codebase. This does not imply that robust loops are not recommended —more that the concurrency problems were not considered during the implementation of these loops.</p></section></section><section>
|
|
<h2><a name="interface_StreamCapabilities"></a><a name="StreamCapability"></a> interface <code>StreamCapabilities</code></h2>
|
|
<p>The <code>StreamCapabilities</code> provides a way to programmatically query the capabilities that <code>OutputStream</code>, <code>InputStream</code>, or other FileSystem class supports.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>public interface StreamCapabilities {
|
|
boolean hasCapability(String capability);
|
|
}
|
|
</pre></div></div>
|
|
<section>
|
|
<h3><a name="boolean_hasCapability.28capability.29"></a><code>boolean hasCapability(capability)</code></h3>
|
|
<p>Return true iff the <code>OutputStream</code>, <code>InputStream</code>, or other FileSystem class has the desired capability.</p>
|
|
<p>The caller can query the capabilities of a stream using a string value. Here is a table of possible string values:</p>
|
|
<table border="0" class="bodyTable">
|
|
<thead>
|
|
|
|
<tr class="a">
|
|
<th>String </th>
|
|
<th> Constant </th>
|
|
<th> Implements </th>
|
|
<th> Description</th></tr>
|
|
</thead><tbody>
|
|
|
|
<tr class="b">
|
|
<td>hflush </td>
|
|
<td> HFLUSH </td>
|
|
<td> Syncable </td>
|
|
<td> Flush out the data in client’s user buffer. After the return of this call, new readers will see the data.</td></tr>
|
|
<tr class="a">
|
|
<td>hsync </td>
|
|
<td> HSYNC </td>
|
|
<td> Syncable </td>
|
|
<td> Flush out the data in client’s user buffer all the way to the disk device (but the disk may have it in its cache). Similar to POSIX fsync.</td></tr>
|
|
<tr class="b">
|
|
<td>in:readahead </td>
|
|
<td> READAHEAD </td>
|
|
<td> CanSetReadahead </td>
|
|
<td> Set the readahead on the input stream.</td></tr>
|
|
<tr class="a">
|
|
<td>dropbehind </td>
|
|
<td> DROPBEHIND </td>
|
|
<td> CanSetDropBehind </td>
|
|
<td> Drop the cache.</td></tr>
|
|
<tr class="b">
|
|
<td>in:unbuffer </td>
|
|
<td> UNBUFFER </td>
|
|
<td> CanUnbuffer </td>
|
|
<td> Reduce the buffering on the input stream.</td></tr>
|
|
</tbody>
|
|
</table></section></section><section>
|
|
<h2><a name="Etag_probes_through_the_interface_EtagSource"></a><a name="etagsource"></a> Etag probes through the interface <code>EtagSource</code></h2>
|
|
<p>FileSystem implementations MAY support querying HTTP etags from <code>FileStatus</code> entries. If so, the requirements are as follows</p><section>
|
|
<h3><a name="Etag_support_MUST_BE_across_all_list.2FgetFileStatus.28.29_calls."></a>Etag support MUST BE across all list/<code>getFileStatus()</code> calls.</h3>
|
|
<p>That is: when adding etag support, all operations which return <code>FileStatus</code> or <code>ListLocatedStatus</code> entries MUST return subclasses which are instances of <code>EtagSource</code>.</p></section><section>
|
|
<h3><a name="FileStatus_instances_MUST_have_etags_whenever_the_remote_store_provides_them."></a>FileStatus instances MUST have etags whenever the remote store provides them.</h3>
|
|
<p>To support etags, they MUST BE to be provided in both <code>getFileStatus()</code> and list calls.</p>
|
|
<p>Implementors note: the core APIs which MUST BE overridden to achieve this are as follows:</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>FileStatus getFileStatus(Path)
|
|
FileStatus[] listStatus(Path)
|
|
RemoteIterator<FileStatus> listStatusIterator(Path)
|
|
RemoteIterator<LocatedFileStatus> listFiles([Path, boolean)
|
|
</pre></div></div>
|
|
</section><section>
|
|
<h3><a name="Etags_of_files_MUST_BE_Consistent_across_all_list.2FgetFileStatus_operations."></a>Etags of files MUST BE Consistent across all list/getFileStatus operations.</h3>
|
|
<p>The value of <code>EtagSource.getEtag()</code> MUST be the same for list* queries which return etags for calls of <code>getFileStatus()</code> for the specific object.</p>
|
|
|
|
<div class="source">
|
|
<div class="source">
|
|
<pre>((EtagSource)getFileStatus(path)).getEtag() == ((EtagSource)listStatus(path)[0]).getEtag()
|
|
</pre></div></div>
|
|
|
|
<p>Similarly, the same value MUST BE returned for <code>listFiles()</code>, <code>listStatusIncremental()</code> of the path and when listing the parent path, of all files in the listing.</p></section><section>
|
|
<h3><a name="Etags_MUST_BE_different_for_different_file_contents."></a>Etags MUST BE different for different file contents.</h3>
|
|
<p>Two different arrays of data written to the same path MUST have different etag values when probed. This is a requirement of the HTTP specification.</p></section><section>
|
|
<h3><a name="Etags_of_files_SHOULD_BE_preserved_across_rename_operations"></a>Etags of files SHOULD BE preserved across rename operations</h3>
|
|
<p>After a file is renamed, the value of <code>((EtagSource)getFileStatus(dest)).getEtag()</code> SHOULD be the same as the value of <code>((EtagSource)getFileStatus(source)).getEtag()</code> was before the rename took place.</p>
|
|
<p>This is an implementation detail of the store; it does not hold for AWS S3.</p>
|
|
<p>If and only if the store consistently meets this requirement, the filesystem SHOULD declare in <code>hasPathCapability()</code> that it supports <code>fs.capability.etags.preserved.in.rename</code></p></section><section>
|
|
<h3><a name="Directories_MAY_have_etags"></a>Directories MAY have etags</h3>
|
|
<p>Directory entries MAY return etags in listing/probe operations; these entries MAY be preserved across renames.</p>
|
|
<p>Equally, directory entries MAY NOT provide such entries, MAY NOT preserve them acrosss renames, and MAY NOT guarantee consistency over time.</p>
|
|
<p>Note: special mention of the root path “/”. As that isn’t a real “directory”, nobody should expect it to have an etag.</p></section><section>
|
|
<h3><a name="All_etag-aware_FileStatus_subclass_MUST_BE_Serializable.3B_MAY_BE_Writable"></a>All etag-aware <code>FileStatus</code> subclass MUST BE <code>Serializable</code>; MAY BE <code>Writable</code></h3>
|
|
<p>The base <code>FileStatus</code> class implements <code>Serializable</code> and <code>Writable</code> and marshalls its fields appropriately.</p>
|
|
<p>Subclasses MUST support java serialization (Some Apache Spark applications use it), preserving the etag. This is a matter of making the etag field non-static and adding a <code>serialVersionUID</code>.</p>
|
|
<p>The <code>Writable</code> support was used for marshalling status data over Hadoop IPC calls; in Hadoop 3 that is implemented through <code>org/apache/hadoop/fs/protocolPB/PBHelper.java</code>and the methods deprecated. Subclasses MAY override the deprecated methods to add etag marshalling. However -but there is no expectation of this and such marshalling is unlikely to ever take place.</p></section><section>
|
|
<h3><a name="Appropriate_etag_Path_Capabilities_SHOULD_BE_declared"></a>Appropriate etag Path Capabilities SHOULD BE declared</h3>
|
|
<ol style="list-style-type: decimal">
|
|
|
|
<li><code>hasPathCapability(path, "fs.capability.etags.available")</code> MUST return true iff the filesystem returns valid (non-empty etags) on file status/listing operations.</li>
|
|
<li><code>hasPathCapability(path, "fs.capability.etags.consistent.across.rename")</code> MUST return true if and only if etags are preserved across renames.</li>
|
|
</ol></section><section>
|
|
<h3><a name="Non-requirements_of_etag_support"></a>Non-requirements of etag support</h3>
|
|
<ul>
|
|
|
|
<li>There is no requirement/expectation that <code>FileSystem.getFileChecksum(Path)</code> returns a checksum value related to the etag of an object, if any value is returned.</li>
|
|
<li>If the same data is uploaded to the twice to the same or a different path, the etag of the second upload MAY NOT match that of the first upload.</li>
|
|
</ul></section></section>
|
|
</div>
|
|
</div>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
<div id="footer">
|
|
<div class="xright">
|
|
© 2008-2023
|
|
Apache Software Foundation
|
|
|
|
- <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
|
|
Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
|
|
</div>
|
|
<div class="clear">
|
|
<hr/>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|