| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You 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. |
| --> |
| <document> |
| |
| <properties> |
| <title>Supported File Systems</title> |
| <author email="dev@commons.apache.org">Apache Commons Developers</author> |
| </properties> |
| |
| <body> |
| <section name="Supported File Systems"> |
| <p>Commons VFS directly supports the following file systems with the listed |
| <a href="apidocs/org/apache/commons/vfs2/Capability.html">capabilities</a>:</p> |
| <table> |
| <tr> |
| <th>File System</th> |
| <th>Directory Contents</th> |
| <th>Authentication</th> |
| <th>Read</th> |
| <th>Write</th> |
| <th>Create/Delete</th> |
| <th>Random</th> |
| <th>Version</th> |
| <th>Rename</th> |
| </tr> |
| <tr> |
| <td><a href="#gzip and bzip2">BZIP2</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="#Local Files">File</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Read/Write</td> |
| <td>No</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><a href="#FTP">FTP</a></td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Read</td> |
| <td>No</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><a href="#FTPS">FTPS</a></td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Read</td> |
| <td>No</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><a href="#gzip and bzip2">GZIP</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="#HDFS">HDFS</a></td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>No</td> |
| <td>Read</td> |
| <td>No</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="#HTTP and HTTPS">HTTP</a></td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>No</td> |
| <td>Read</td> |
| <td>No</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="#HTTP and HTTPS">HTTPS</a></td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>No</td> |
| <td>Read</td> |
| <td>No</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="#Zip, Jar and Tar">Jar</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="#ram">RAM</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Read/Write</td> |
| <td>No</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><a href="#res">RES</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Read/Write</td> |
| <td>No</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><a href="#SFTP">SFTP</a></td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Read</td> |
| <td>No</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><a href="#Zip, Jar and Tar">Tar</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><a href="#Temporary Fils">Temp</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Read/Write</td> |
| <td>No</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><a href="#WebDAV">WebDAV</a></td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Read/Write</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><a href="#Zip, Jar and Tar">Zip</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| </tr> |
| </table> |
| </section> |
| |
| <section name="Things from the sandbox"> |
| <p>The following file systems are in development:</p> |
| <table> |
| <tr> |
| <th>File System</th> |
| <th>Directory Contents</th> |
| <th>Authentication</th> |
| <th>Read</th> |
| <th>Write</th> |
| <th>Create/Delete</th> |
| <th>Random</th> |
| <th>Version</th> |
| <th>Rename</th> |
| </tr> |
| <tr> |
| <td><a href="#CIFS">CIFS</a></td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Read/Write</td> |
| <td>No</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><a href="#mime">mime</a></td> |
| <td>No</td> |
| <td>No</td> |
| <td>Yes</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| <td>No</td> |
| </tr> |
| </table> |
| </section> |
| |
| <section name="Naming"> |
| |
| <p>All filenames are treated as URIs. One of the consequences of this is you have to encode the '%' |
| character using <code>%25</code>. <br /> |
| Depending on the filesystem additional characters are encoded if needed. This is done automatically, but |
| might be reflected in the filename. |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>file:///somedir/some%25file.txt</code> |
| </li> |
| </ul> |
| <p> |
| Many file systems accept a userid and password as part of the url. However, storing |
| a password in clear text in a file is usually unacceptable. To help with that |
| Commons VFS provides a mechanism to encrypt the password. It should be noted though, |
| that this is not completely secure since the password needs to be unencrypted |
| before Commons VFS can use it. |
| </p> |
| <p> |
| To create an encrypted password do: |
| </p> |
| <code> java -cp commons-vfs-2.0.jar org.apache.commons.vfs2.util.EncryptUtil encrypt mypassword |
| </code> |
| <p> |
| where <i>mypassword</i> is the password you want to encrypt. The result of this will be a |
| single line of output containing uppercase hex characters. For example, |
| </p> |
| <code> |
| java -cp commons-vfs-2.0.jar org.apache.commons.vfs2.util.EncryptUtil encrypt WontUBee9 |
| D7B82198B272F5C93790FEB38A73C7B8 |
| </code> |
| <p> |
| Then cut the output returned and paste it into the URL as: |
| </p> |
| <code> |
| https://testuser:{D7B82198B272F5C93790FEB38A73C7B8}@myhost.com/svn/repos/vfstest/trunk |
| </code> |
| <p> |
| VFS treats a password enclosed in {} as being encrypted and will decrypt the password |
| before using it. |
| </p> |
| </section> |
| |
| <section name="Local Files"> |
| |
| <p>Provides access to the files on the local physical file system.</p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>[file://] |
| <i>absolute-path</i> |
| </code> |
| </p> |
| |
| <p> |
| Where |
| <code> |
| <i>absolute-path</i> |
| </code> is a valid absolute |
| file name for the local platform. UNC names are supported |
| under Windows. |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>file:///home/someuser/somedir</code> |
| </li> |
| <li> |
| <code>file:///C:/Documents and Settings</code> |
| </li> |
| <li> |
| <code>file://///somehost/someshare/afile.txt</code> |
| </li> |
| <li> |
| <code>/home/someuser/somedir</code> |
| </li> |
| <li> |
| <code>c:\program files\some dir</code> |
| </li> |
| <li> |
| <code>c:/program files/some dir</code> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="Zip, Jar and Tar"> |
| |
| <p>Provides read-only access to the contents of Zip, Jar and Tar files.</p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>zip:// |
| <i>arch-file-uri</i>[! |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| <p> |
| <code>jar:// |
| <i>arch-file-uri</i>[! |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| <p> |
| <code>tar:// |
| <i>arch-file-uri</i>[! |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| <p> |
| <code>tgz:// |
| <i>arch-file-uri</i>[! |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| <p> |
| <code>tbz2:// |
| <i>arch-file-uri</i>[! |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| Where |
| <code>arch-file-uri</code> refers to a file of any |
| supported type, including other zip files. Note: if you would like |
| to use the ! as normal character it must be escaped |
| using <code>%21</code>.<br /> |
| <code>tgz</code> and <code>tbz2</code> are convenience for <code>tar:gz</code> and <code>tar:bz2</code>. |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>jar:../lib/classes.jar!/META-INF/manifest.mf</code> |
| </li> |
| <li> |
| <code>zip:http://somehost/downloads/somefile.zip</code> |
| </li> |
| <li> |
| <code>jar:zip:outer.zip!/nested.jar!/somedir</code> |
| </li> |
| <li> |
| <code>jar:zip:outer.zip!/nested.jar!/some%21dir</code> |
| </li> |
| <li> |
| <code>tar:gz:http://anyhost/dir/mytar.tar.gz!/mytar.tar!/path/in/tar/README.txt</code> |
| </li> |
| <li> |
| <code>tgz:file://anyhost/dir/mytar.tgz!/somepath/somefile</code> |
| </li> |
| </ul> |
| |
| </section> |
| |
| <section name="gzip and bzip2"> |
| |
| <p>Provides read-only access to the contents of gzip and bzip2 files.</p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>gz:// |
| <i>compressed-file-uri</i> |
| </code> |
| </p> |
| <p> |
| <code>bz2:// |
| <i>compressed-file-uri</i> |
| </code> |
| </p> |
| |
| <p> |
| Where |
| <code>compressed-file-uri</code> refers to a file of any |
| supported type. There is no need to add a <code>!</code> part to the URI if |
| you read the content of the file you always will get the uncompressed |
| version. |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>gz:/my/gz/file.gz</code> |
| </li> |
| </ul> |
| |
| </section> |
| |
| <section name="HDFS"> |
| |
| <p> |
| Provides (read-only) access to files in an Apache Hadoop File System (HDFS). |
| On Windows the <a href="testing.html">integration test</a> is disabled by default, as it |
| requires binaries. |
| </p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>hdfs:// |
| <i>hostname</i>[: |
| <i>port</i>][ |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>hdfs://somehost:8080/downloads/some_dir</code> |
| </li> |
| <li> |
| <code>hdfs://somehost:8080/downloads/some_file.ext</code> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="HTTP and HTTPS"> |
| |
| <p>Provides access to files on an HTTP server.</p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>http://[ |
| <i>username</i>[: |
| <i>password</i>]@] |
| <i>hostname</i>[: |
| <i>port</i>][ |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| <p> |
| <code>https://[ |
| <i>username</i>[: |
| <i>password</i>]@] |
| <i>hostname</i>[: |
| <i>port</i>][ |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| <p> |
| <b>File System Options</b> |
| <ul> |
| <li><b>proxyHost</b> The proxy host to connect through.</li> |
| <li><b>proxyPort</b> The proxy port to use.</li> |
| <li><b>proxyScheme</b> The proxy scheme (http/https) to use.</li> |
| <li><b>cookies</b> An array of Cookies to add to the request.</li> |
| <li><b>maxConnectionsPerHost</b> The maximum number of connections allowed to |
| a specific host and port. The default is 5.</li> |
| <li><b>maxTotalConnections</b> The maximum number of connections allowed to |
| all hosts. The default is 50.</li> |
| <li><b>keystoreFile</b> The keystore file for SSL connections.</li> |
| <li><b>keystorePass</b> The keystore password.</li> |
| <li><b>keystoreType</b> The keystore type.</li> |
| </ul> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>http://somehost:8080/downloads/somefile.jar</code> |
| </li> |
| <li> |
| <code>http://myusername@somehost/index.html</code> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="WebDAV"> |
| |
| <p> |
| Provides access to files on a WebDAV server through the modules |
| <a href="commons-vfs2-jackrabbit1/index.html"><code>commons-vfs2-jackrabbit1</code></a> |
| and |
| <a href="commons-vfs2-jackrabbit2/index.html"><code>commons-vfs2-jackrabbit2</code></a>. |
| </p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>webdav://[ |
| <i>username</i>[: |
| <i>password</i>]@] |
| <i>hostname</i>[: |
| <i>port</i>][ |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>File System Options</b> |
| <ul> |
| <li><b>versioning</b> true if versioning should be enabled</li> |
| <li><b>creatorName</b> the user name to be identified with changes to a file. If |
| not set the user name used to authenticate will be used.</li> |
| </ul> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>webdav://somehost:8080/dist</code> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="FTP"> |
| |
| <p>Provides access to the files on an FTP server.</p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>ftp://[ |
| <i>username</i>[: |
| <i>password</i>]@] |
| <i>hostname</i>[: |
| <i>port</i>][ |
| <i>relative-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>ftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz</code> |
| </li> |
| </ul> |
| |
| <p> |
| By default, the path is relative to the user's home directory. This can be changed with: |
| </p> |
| <p> |
| <code>FtpFileSystemConfigBuilder.getInstance().setUserDirIsRoot(options, false);</code> |
| </p> |
| |
| </section> |
| |
| <section name="FTPS"> |
| |
| <p>Provides access to the files on an FTP server over SSL.</p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>ftps://[ |
| <i>username</i>[: |
| <i>password</i>]@] |
| <i>hostname</i>[: |
| <i>port</i>][ |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>ftps://myusername:mypassword@somehost/pub/downloads/somefile.tgz</code> |
| </li> |
| </ul> |
| |
| </section> |
| |
| <section name="SFTP"> |
| |
| <p> |
| Provides access to the files on an SFTP server (that is, an SSH |
| or SCP server). |
| </p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>sftp://[ |
| <i>username</i>[: |
| <i>password</i>]@] |
| <i>hostname</i>[: |
| <i>port</i>][ |
| <i>relative-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>sftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz</code> |
| </li> |
| </ul> |
| |
| <p> |
| By default, the path is relative to the user's home directory. This can be changed with: |
| </p> |
| <p> |
| <code>FtpFileSystemConfigBuilder.getInstance().setUserDirIsRoot(options, false);</code> |
| </p> |
| |
| </section> |
| |
| <section name="CIFS"> |
| |
| <p> |
| The CIFS (sandbox) filesystem provides access to a CIFS server, such as |
| a Samba server, or a Windows share. |
| </p> |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>smb://[ |
| <i>username</i>[: |
| <i>password</i>]@] |
| <i>hostname</i>[: |
| <i>port</i>][ |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| |
| <ul> |
| <li> |
| <code>smb://somehost/home</code> |
| </li> |
| </ul> |
| |
| </section> |
| |
| <section name="Temporary Files"> |
| |
| <p> |
| Provides access to a temporary file system, or scratchpad, |
| that is deleted when Commons VFS shuts down. The temporary file |
| system is backed by a local file system. |
| </p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>tmp://[ |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| |
| <ul> |
| <li> |
| <code>tmp://dir/somefile.txt</code> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="Resource"> |
| |
| <p> |
| This is not really a filesystem, it just tries to lookup a resource using javas <code>ClassLoader.getResource()</code> |
| and creates a VFS url for further processing. |
| </p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>res://[ |
| <i>path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| |
| <ul> |
| <li> |
| <code>res://path/in/classpath/image.png</code><br/> |
| might result in |
| <code>jar:file://my/path/to/images.jar!/path/in/classpath/image.png</code><br/> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="RAM"> |
| |
| <p> |
| A filesystem which stores all the data in memory (one byte array for each file content). |
| </p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>ram://[ |
| <i>path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>File System Options</b> |
| <ul> |
| <li><b>maxsize</b> Maximum filesystem size (total bytes of all file contents).</li> |
| </ul> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| |
| <ul> |
| <li> |
| <code>ram:///any/path/to/file.txt</code> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="MIME"> |
| |
| <p> |
| This (sandbox) filesystem can read mails and its attachements like archives.<br /> |
| If a part in the parsed mail has no name, a dummy name will be generated. |
| The dummy name is: _body_part_X where X will be replaced by the part number. |
| </p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>mime:// |
| <i>mime-file-uri</i>[! |
| <i>absolute-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| |
| <ul> |
| <li> |
| <code>mime:file:///your/path/mail/anymail.mime!/</code> |
| </li> |
| <li> |
| <code>mime:file:///your/path/mail/anymail.mime!/filename.pdf</code> |
| </li> |
| <li> |
| <code>mime:file:///your/path/mail/anymail.mime!/_body_part_0</code> |
| </li> |
| </ul> |
| </section> |
| |
| </body> |
| </document> |