<!--
    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>
                <li>
					          <a href="#WebDAV">WebDAV</a><br />
			        	</li>
            </ul>
        </section>

		<section name="Things from the sandbox">
			<p>The following file systems are in development:</p>
			<ul>
				<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>
            <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.vfs.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.vfs.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 ! 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>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>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>
                 </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.</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>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>