3
Licensed to the Apache Software Foundation (ASF) under one or more
4
contributor license agreements. See the NOTICE file distributed with
5
this work for additional information regarding copyright ownership.
6
The ASF licenses this file to You under the Apache License, Version 2.0
7
(the "License"); you may not use this file except in compliance with
8
the License. You may obtain a copy of the License at
10
http://www.apache.org/licenses/LICENSE-2.0
12
Unless required by applicable law or agreed to in writing, software
13
distributed under the License is distributed on an "AS IS" BASIS,
14
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15
See the License for the specific language governing permissions and
16
limitations under the License.
20
<title>User guide</title>
21
<author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
25
<section name="User guide">
28
<a href="#Utility classes">utility classes</a>,
29
<a href="#Endian classes">endian classes</a>,
30
<a href="#Line iterator">line iterator</a>,
31
<a href="#File filters">file filters</a> and
32
<a href="#Streams">stream implementations</a>.
36
For a more detailed descriptions, take a look at the
37
<a href="api-release/index.html">javadocs</a>.
41
<section name="Utility classes">
42
<subsection name="IOUtils">
44
<a href="api-release/index.html?org/apache/commons/io/IOUtils.html">IOUtils</a>
45
contains utility methods dealing with reading, writing and copying.
46
The methods work on InputStream, OutputStream, Reader and Writer.
49
As an example, consider the task of reading bytes
50
from a URL, and printing them. This would typically done like this:
54
InputStream in = new URL( "http://jakarta.apache.org" ).openStream();
56
InputStreamReader inR = new InputStreamReader( in );
57
BufferedReader buf = new BufferedReader( inR );
59
while ( ( line = buf.readLine() ) != null ) {
60
System.out.println( line );
67
With the IOUtils class, that could be done with:
71
InputStream in = new URL( "http://jakarta.apache.org" ).openStream();
73
System.out.println( IOUtils.toString( in ) );
75
IOUtils.closeQuietly(in);
79
In certain application domains, such IO operations are
80
common, and this class can save a great deal of time. And you can
81
rely on well-tested code.
84
For utility code such as this, flexibility and speed are of primary importance.
85
However you should also understand the limitations of this approach.
86
Using the above technique to read a 1GB file would result in an
87
attempt to create a 1GB String object!
92
<subsection name="FileUtils">
94
The <a href="api-release/index.html?org/apache/commons/io/FileUtils.html">FileUtils</a>
95
class contains utility methods for working with File objects.
96
These include reading, writing, copying and comparing files.
99
For example to read an entire file line by line you could use:
102
File file = new File("/commons/io/project.properties");
103
List lines = FileUtils.readLines(file, "UTF-8");</source>
106
<subsection name="FilenameUtils">
108
The <a href="api-release/index.html?org/apache/commons/io/FilenameUtils.html">FilenameUtils</a>
109
class contains utility methods for working with filenames <i>without</i>
110
using File objects. The class aims to be consistent
111
between Unix and Windows, to aid transitions between these
112
environments (such as moving from development to production).
115
For example to normalize a filename removing double dot segments:
118
String filename = "C:/commons/io/../lang/project.xml";
119
String normalized = FilenameUtils.normalize(filename);
120
// result is "C:/commons/lang/project.xml"</source>
123
<subsection name="FileSystemUtils">
125
The <a href="api-release/index.html?org/apache/commons/io/FileSystemUtils.html">FileSystemUtils</a>
127
utility methods for working with the file system
128
to access functionality not supported by the JDK.
129
Currently, the only method is to get the free space on a drive.
130
Note that this uses the command line, not native code.
133
For example to find the free space on a drive:
136
long freeSpace = FileSystemUtils.freeSpace("C:/");</source>
141
<section name="Endian classes">
143
Different computer architectures adopt different
144
conventions for byte ordering. In so-called
145
"Little Endian" architectures (eg Intel), the low-order
146
byte is stored in memory at the lowest address, and
147
subsequent bytes at higher addresses. For "Big Endian"
148
architectures (eg Motorola), the situation is reversed.
152
There are two classes in this package of relevance:
157
The <a href="api-release/index.html?org/apache/commons/io/EndianUtils.html">EndianUtils</a>
158
class contains static methods for swapping the Endian-ness
159
of Java primitives and streams.
163
The <a href="api-release/index.html?org/apache/commons/io/input/SwappedDataInputStream.html">SwappedDataInputStream</a>
164
class is an implementation of the <code>DataInput</code> interface. With
165
this, one can read data from files of non-native Endian-ness.
170
For more information, see
172
href="http://www.cs.umass.edu/~verts/cs32/endian.html">http://www.cs.umass.edu/~verts/cs32/endian.html</a>
177
<section name="Line iterator">
179
The <code>org.apache.commons.io.LineIterator</code> class
180
provides a flexible way for working with a line-based file.
181
An instance can be created directly, or via factory methods on
182
<code>FileUtils</code> or <code>IOUtils</code>.
183
The recommended usage pattern is:
186
LineIterator it = FileUtils.lineIterator(file, "UTF-8");
188
while (it.hasNext()) {
189
String line = it.nextLine();
190
/// do something with line
193
LineIterator.closeQuietly(iterator);
197
<section name="File filters">
199
The <code>org.apache.commons.io.filefilter</code>
200
package defines an interface
201
(<a href="api-release/index.html?org/apache/commons/io/filefilter/IOFileFilter.html">IOFileFilter</a>)
202
that combines both <code>java.io.FileFilter</code> and
203
<code>java.io.FilenameFilter</code>. Besides
204
that the package offers a series of ready-to-use
205
implementations of the <code>IOFileFilter</code>
207
implementation that allow you to combine other such filters.
209
These filters can be used to list files or in FileDialog, for example.
213
<a href="api-release/index.html?org/apache/commons/io/filefilter/package-summary.html">filefilter</a>
214
package javadoc for more details.
218
<section name="Streams">
220
The <code>org.apache.commons.io.input</code> and
221
<code>org.apache.commons.io.output</code> packages
222
contain various useful implementations of streams.
225
<li>Null output stream - that silently absorbs all data sent to it</li>
226
<li>Tee output stream - that sends output data to two streams instead of one</li>
227
<li>Byte array output stream - that is a faster version of the JDK class</li>
228
<li>Counting streams - that count the number of bytes passed</li>
229
<li>Proxy streams - that delegate to the correct method in the proxy</li>
230
<li>Lockable writer - that provides synchronization of writes using a lock file</li>
235
<a href="api-release/index.html?org/apache/commons/io/input/package-summary.html">input</a> or
236
<a href="api-release/index.html?org/apache/commons/io/output/package-summary.html">output</a>
237
package javadoc for more details.
added
removed
xdocs/description.xml
