<document>
    <properties>
        <title>Using The API</title>
        <author email="adammurdoch@apache.org">Adam Murdoch</author>
    </properties>

    <body>
        <section name="Using The API">
            <p>
                The
                <a href="apidocs/org/apache/commons/vfs/FileSystemManager.html">FileSystemManager</a>
                interface provides access to Commons VFS.  Using this interface
                you can locate files and create file systems.
                There are a
                <a href="#Configuring Commons VFS">number of ways</a>
                to obtain a
                <code>FileSystemManager</code> instance.
                The simplest is to use the static
                <a href="apidocs/org/apache/commons/vfs/VFS.html#getManager()">VFS.getManager()</a>
                method, which returns the default Commons VFS implementation.
            </p>

            <p>
                Once you have a
                <code>FileSystemManager</code>, you can use its
                <code>resolveFile()</code> methods to locate a file by name.
                For example:
            </p>

            <source><![CDATA[
FileSystemManager fsManager = VFS.getManager();
FileObject jarFile = fsManager.resolveFile( "jar:lib/aJarFile.jar" );
                ]]></source>

            <p>
                Each file is represented by a
                <a href="apidocs/org/apache/commons/vfs/FileObject.html">FileObject</a>
                instance.  Using this interface you can create or delete the
                file, list its children, read or write its content, and so on.
                For example:
            </p>

            <source><![CDATA[
// Locate the Jar file
FileSystemManager fsManager = VFS.getManager();
FileObject jarFile = fsManager.resolveFile( "jar:lib/aJarFile.jar" );

// List the children of the Jar file
FileObject[] children = jarFile.getChildren();
System.out.println( "Children of " + jarFile.getName().getURI() );
for ( int i = 0; i < children.length; i++ )
{
    System.out.println( children[ i ].getName().getBaseName() );
}
                ]]></source>

            <p>
                See the
                <a href="apidocs/org/apache/commons/vfs/FileObject.html">FileObject</a>
                Javadocs for more detail.
            </p>

            <subsection name="Cache">
                <p>
                    Commons VFS uses a <a href="apidocs/org/apache/commons/vfs/cache/SoftRefFilesCache.html">SoftRefFilesCache</a> to release memory if a file is no longer used by the application.
                </p>
                <p>
                    This cache will return the same instance for a file as long as it is "strongly reachable" e.g. you
                    hold a reference to this object. If the FileObject is no longer reachable, and the jvm needs some memory,
                    it will be released.
                </p>
            </subsection>

            <subsection name="Examples">
                <p>
                    For an example of using the API, take a look at the classes
                    in the
                    <a href="apidocs/org/apache/commons/vfs/example/package-summary.html">example</a>
                    package.
                </p>
            </subsection>

        </section>

        <section name="Configuring Commons VFS">
            <p>
                Commons VFS is represented using the
                <a href="apidocs/org/apache/commons/vfs/FileSystemManager.html">FileSystemManager</a>
                interface.  There are a number of ways to create and configure a
                <code>FileSystemManager</code> instance.
            </p>
            <p>
                The simplest method is to use the static
                <a href="apidocs/org/apache/commons/vfs/VFS.html#getManager()">VFS.getManager()</a>
                method, which returns the default Commons VFS implementation.
            </p>
            <p>
                This method will also automatically scan the classpath for a /META-INF/vfs-providers.xml file
                (also in jar files).
                If such a file is found Commons VFS uses it in <u>addition</u> to the default providers.xml.
                This allows you to start using a new filesystem by simply drop its implementation into the classpath.
                The configuration file format is described below.<br />
                <b>Notice:</b> Currently it is not allowed to override a already configured filesystem. Commons VFS throws
                an exception if there is already a filesystem for a scheme.
            </p>

            <p>
                To configure Commons VFS programatically, you can create an
                instance of
                <a href="apidocs/org/apache/commons/vfs/impl/DefaultFileSystemManager.html">DefaultFileSystemManager</a>
                and configure it manually.  The default constructor
                <code>DefaultFileSystemManager</code> creates a manager that
                is completely empty.  You will have to add file providers to it
                to make it do anything useful.
            </p>
            <p>
                Here are the steps for using
                <code>DefaultFileSystemManager</code>:
            </p>
            <ol>
                <li>Create a new instance.</li>
                <li>
                    Set the logger for the manager and all its components,
                    using
                    <code>setLogger()</code>.  This step is
                    optional, and if skipped, the manager will use the default
                    logger provided by Commons Logging.
                </li>
                <li>
                    Add file providers, using
                    <code>addProvider()</code>.
                </li>
                <li>
                    Set the default provider, using
                    <code>setDefaultProvider()</code>.  This step is optional.
                    See
                    <a href="apidocs/org/apache/commons/vfs/provider/url/UrlFileProvider.html">UrlFileProvider</a>
                    for a useful default provider.
                </li>
                <li>
                    Set the file replicator, using
                    <code>setReplicator()</code>.
                    This step is optional.
                </li>
                <li>
                    Set the temporary file store, using
                    <code>setTemporaryFileStore()</code>.
                    This step is optional.
                </li>
                <li>
                    Set the base file using
                    <code>setBaseFile()</code>.  The
                    base file is used to resolve relative URI passed to
                    <code>resolveFile()</code>.  This step is optional.
                </li>
                <li>
                    Initialise the manager using
                    <code>init()</code>.
                </li>
            </ol>
            <p>
                You should make sure that you call
                <code>close()</code> on the
                manager when you are finished with it.
            </p>

            <p>
                The third method for configuring Commons VFS, is to configure
                it from a file.  Create an instance of
                <a href="apidocs/org/apache/commons/vfs/impl/StandardFileSystemManager.html">StandardFileSystemManager</a>,
                and use its
                <code>setConfiguration()</code> method to set the
                location of the configuration file to use.  The configuration
                file format is described below.
            </p>

            <p>
                <code>StandardFileSystemManager</code> is a subclass of
                <code>DefaultFileSystemManager</code>, so you can also
                configure it programmatically, as described above.
            </p>
            <subsection name="Configuration File">
                <p>
                    The configuration file is an XML file.  The root element
                    of the configuration file should be a
                    <code>&lt;providers&gt;</code> element.
                    The
                    <code>&lt;providers&gt;</code> element may contain:
                </p>
                <ul>
                    <li>Zero or more
                        <code>&lt;provider&gt;</code> elements.
                    </li>
                    <li>An optional
                        <code>&lt;default-provider&gt;</code> element.
                    </li>
                    <li>Zero or more
                        <code>&lt;extension-map&gt;</code> elements.
                    </li>
                    <li>Zero or more
                        <code>&lt;mime-type-map&gt;</code> elements.
                    </li>
                </ul>

                <p>
                    <b>
                        <code>&lt;provider&gt;</code>
                    </b>
                </p>
                <p>
                    The
                    <code>&lt;provider&gt;</code> element defines a file
                    provider.   It must have a
                    <code>class-name</code> attribute,
                    which specifies the fully-qualified name of the provider
                    class.  The provider class must be public, and must have a
                    public constructor with an FileSystemManager argument which
                    allows the systems to pass the used filesystem manager.
                </p>
                <p>
                    The
                    <code>&lt;provider&gt;</code> element may contain
                    zero or more
                    <code>&lt;scheme&gt;</code> elements,
                    and zero or more
                    <code>&lt;if-available&gt;</code> elements.
                </p>
                <p>
                    The
                    <code>&lt;scheme&gt;</code> element defines a URI scheme
                    that the provider will handle.  It must have a
                    <code>name</code> attribute, which specifies the URI scheme.
                </p>
                <p>
                    The
                    <code>&lt;if-available&gt;</code> elements is used to
                    disable the provider if certain classes are not present in
                    the class-path.
                    It must have a
                    <code>class-name</code> attribute, which
                    specifies the fully qualified name of a class to test for.
                    If the class cannot be found, the provider is not registered.
                </p>

                <p>
                    <b>
                        <code>&lt;default-provider&gt;</code>
                    </b>
                </p>
                <p>
                    The
                    <code>&lt;default-provider&gt;</code> element defines
                    the default provider.  It has the same format as the
                    <code>&lt;provider&gt;</code> element.
                </p>

                <p>
                    <b>
                        <code>&lt;extension-map&gt;</code>
                    </b>
                </p>
                <p>
                    The
                    <code>&lt;extension-map&gt;</code> element defines
                    a mapping from a file's extension to the provider that
                    should handle files with that extension.
                    It must have an
                    <code>extension</code> attribute, which
                    specifies the extension, and a
                    <code>scheme</code> attribute,
                    which specifies the URI scheme of the provider.
                </p>

                <p>
                    <b>
                        <code>&lt;mime-type-map&gt;</code>
                    </b>
                </p>
                <p>
                    The
                    <code>&lt;mime-type-map&gt;</code> element defines
                    a mapping from a file's MIME type to the provider that
                    should handle files with that MIME type.
                    It must have an
                    <code>mime-type</code> attribute, which
                    specifies the MIME type, and a
                    <code>scheme</code> attribute,
                    which specified the URI scheme of the provider.
                </p>

                <p>
                    Below is an example configuration file:
                </p>
                <source><![CDATA[
<providers>
    <provider class-name="org.apache.commons.vfs.provider.zip.ZipFileProvider">
        <scheme name="zip"/>
    </provider>
    <extension-map extension="zip" scheme="zip"/>
    <mime-type-map mime-type="application/zip" scheme="zip"/>
    <provider class-name="org.apache.commons.vfs.provider.ftp.FtpFileProvider">
        <scheme name="ftp"/>
        <if-available class-name="org.apache.commons.net.ftp.FTPFile"/>
    </provider>
    <default-provider class-name="org.apache.commons.vfs.provider.url.UrlFileProvider"/>
</providers>
                    ]]></source>
            </subsection>
        </section>
    </body>
</document>