1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
|
<!--
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>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>
In some cases you might want to explicitely free resources allocated by the filesystem.
You can do this by calling
<a href="apidocs/org/apache/commons/vfs/FileSystemManager.html#closeFileSystem">VFS.getManager().closeFileSystem(fs)</a>.
If you use VFS as singleton (as described above) you should take care that this will close the filesystem for
all threads.<br />
In other words, do not close any globally used filesystem like the one for local files.
</p>
<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>
<p>
There is also a internal cache of each file object avoid the need to access the network layer. Now its possible
to configure this behviour through the use of <a href="apidocs/org/apache/commons/vfs/CacheStrategy.html">CacheStrategy</a>.
<br />
Do this on the DefaultFileSystemManager. For example:
<code>
((DefaultFileSystemManager) VFS.getManager()).setCacheStrategy(CacheStrategy.ON_CALL)
</code>
</p>
</subsection>
<subsection name="User Authentication">
<p>
You cann put the credentials into th url, but the drawback here is, that it is easily possible to get access to the password.
</p>
<p>
To solve you can use the <a href="apidocs/org/apache/commons/vfs/UserAuthenticator.html">UserAuthenticator</a>
</p>
<p>
For example:
<code>
StaticUserAuthenticator auth = new StaticUserAuthenticator("username", "password", null);
FileSystemOptions opts = new FileSystemOptions();
DefaultFileSystemConfigBuilder.getInstance().setUserAuthenticator(opts, auth);
FileObject fo = VFS.getManager().resolveFile("smb://host/anyshare/dir", opts);
</code>
</p>
<p>
Internally the UserAuthenticator uses char arrays which will be zeroed before its freed for garbage collection.
Unhappily none of the current libraries use char arrays and so VFS has to create a string. Thus, the main advantage
of this solution - security - is lost, but hey, thats not VFS fault ;-)
</p>
<p>
VFS calls <code>UserAuthenticator.requestAuthentication</code> each time it requires credentials, it depends on the
filesystem implementation how often this might be. For example, with FTP this is on every connection, in SMB/JCIFS
this is for EVERY OBJECT. It is up to you how long you will cache credentials of if you would like to provide a
"save credentials" checkbox.
</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>
|