<!--
    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>
			</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>