| <!-- |
| 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="adammurdoch@apache.org">Adam Murdoch</author> |
| <author email="imario@apache.org">Mario Ivankovits</author> |
| </properties> |
| |
| <body> |
| <section name="Supported File Systems"> |
| <p>Commons VFS currently supports the following file systems:</p> |
| <ul> |
| <li> |
| <a href="#FTP">FTP</a> |
| </li> |
| <li> |
| <a href="#Local Files">Local Files</a> |
| </li> |
| <li> |
| <a href="#HTTP and HTTPS">HTTP and HTTPS</a> |
| </li> |
| <li> |
| <a href="#SFTP">SFTP</a> |
| </li> |
| <li> |
| <a href="#Temporary Files">Temporary Files</a> |
| </li> |
| <li> |
| <a href="#Zip, Jar and Tar">Zip, Jar and Tar (uncompressed, tgz or tbz2)</a> |
| </li> |
| <li> |
| <a href="#gzip and bzip2">gzip and bzip2</a> |
| </li> |
| <li> |
| <a href="#res">res</a> |
| </li> |
| <li> |
| <a href="#ram">ram</a> |
| </li> |
| <li> |
| <a href="#mime">mime</a> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="Things from the sandbox"> |
| <p>The following file systems are in development:</p> |
| <ul> |
| <li> |
| <a href="#WebDAV">WebDAV</a><br /> |
| We can't release WebDAV as we depend on an snapshot, thus it is in our sandbox. |
| </li> |
| <li> |
| <a href="#CIFS">CIFS</a> |
| </li> |
| <li> |
| <a href="#mime">mime</a> |
| </li> |
| </ul> |
| </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 needet. 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> |
| |
| </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 ! 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="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>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.</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>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>absolute-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>ftp://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>absolute-path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| <ul> |
| <li> |
| <code>sftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz</code> |
| </li> |
| </ul> |
| |
| </section> |
| |
| <section name="CIFS"> |
| |
| <p> |
| Provides access to the files on 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="res"> |
| |
| <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. |
| You can configure the max size and a predicate (FileSelector). The predicate will be used to check if |
| it is allowed to add a given file. |
| </p> |
| |
| <p> |
| <b>URI Format</b> |
| </p> |
| |
| <p> |
| <code>ram://[ |
| <i>path</i>] |
| </code> |
| </p> |
| |
| <p> |
| <b>Examples</b> |
| </p> |
| |
| <ul> |
| <li> |
| <code>ram:///any/path/to/file.txt</code> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="mime"> |
| |
| <p> |
| This 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> |
