| <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><providers></code> element. |
| The |
| <code><providers></code> element may contain: |
| </p> |
| <ul> |
| <li>Zero or more |
| <code><provider></code> elements. |
| </li> |
| <li>An optional |
| <code><default-provider></code> element. |
| </li> |
| <li>Zero or more |
| <code><extension-map></code> elements. |
| </li> |
| <li>Zero or more |
| <code><mime-type-map></code> elements. |
| </li> |
| </ul> |
| |
| <p> |
| <b> |
| <code><provider></code> |
| </b> |
| </p> |
| <p> |
| The |
| <code><provider></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><provider></code> element may contain |
| zero or more |
| <code><scheme></code> elements, |
| and zero or more |
| <code><if-available></code> elements. |
| </p> |
| <p> |
| The |
| <code><scheme></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><if-available></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><default-provider></code> |
| </b> |
| </p> |
| <p> |
| The |
| <code><default-provider></code> element defines |
| the default provider. It has the same format as the |
| <code><provider></code> element. |
| </p> |
| |
| <p> |
| <b> |
| <code><extension-map></code> |
| </b> |
| </p> |
| <p> |
| The |
| <code><extension-map></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><mime-type-map></code> |
| </b> |
| </p> |
| <p> |
| The |
| <code><mime-type-map></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> |