Skip to content

Commit 5e0fd95

Browse files
jmaerkijmaerki
committed
Corrections and additions to the IO website.
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/io/trunk@140491 13f79535-47bb-0310-9956-ffa450edef68
1 parent d194ef8 commit 5e0fd95

5 files changed

Lines changed: 195 additions & 22 deletions

File tree

‎xdocs/bestpractices.xml‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
<?xml version="1.0"?>
2+
3+
<!--
4+
Building IO
5+
$Id: bestpractices.xml,v 1.1 2004/01/16 17:05:03 jeremias Exp $
6+
-->
7+
8+
<document>
9+
<body>
10+
11+
<section name="Overview">
12+
<p>
13+
This document presents a number of "best practices" in the IO area.
14+
</p>
15+
</section>
16+
17+
<section name="java.io.File">
18+
19+
<p>
20+
Often, you have to deal with files and filenames. There are many
21+
things that can go wrong:
22+
</p>
23+
<ul>
24+
<li>A class works in Unix but doesn't on Windows (or vice versa)</li>
25+
<li>Invalid filenames due to double or missing path separators</li>
26+
<li>UNC filenames (on Windows) don't work with my home-grown filename utility function</li>
27+
<li>etc. etc.</li>
28+
</ul>
29+
<p>
30+
These are good reasons not to work with filenames as Strings. Use
31+
java.io.File instead which handles many of the above cases nicely. Too
32+
many people are still always using Strings for filenames and risk
33+
platform dependencies, for example.
34+
</p>
35+
<p>
36+
Let's look at an example. BTW, it's one of the functions that made us
37+
skip the class FilenameUtils for the initial release of Commons IO.
38+
</p>
39+
<source>
40+
public static String getExtension(String filename) {
41+
int index = filename.lastIndexOf('.');
42+
43+
if (-1 == index) {
44+
return "";
45+
} else {
46+
return filename.substring(index + 1);
47+
}
48+
}</source>
49+
<p>
50+
Easy enough? Right, but what happens if someone passes in a full path
51+
instead of only a filename? Consider the following, perfectly legal path:
52+
"C:\Temp\documentation.new\README"
53+
</p>
54+
<p>
55+
Please use java.io.File for filenames instead of Strings. The functionality
56+
that the class provides is well tested. In FileUtils you will find other
57+
useful utility functions around java.io.File.
58+
</p>
59+
<p>
60+
Instead of:
61+
</p>
62+
<source>
63+
String tmpdir = "/var/tmp";
64+
String tmpfile = tmpdir + System.getProperty("file.separator") + "test.tmp";
65+
InputStream in = new java.io.FileInputStream(tmpfile);</source>
66+
<p>
67+
...write:
68+
</p>
69+
<source>
70+
File tmpdir = new File("/var/tmp");
71+
File tmpfile = new File(tmpdir, "test.tmp");
72+
InputStream in = new java.io.FileInputStream(tmpfile);</source>
73+
74+
</section>
75+
76+
<section name="Buffering streams">
77+
<p>
78+
IO performance depends a lot from the buffering strategy. Usually, it's
79+
quite fast to read packets with the size of 512 or 1024 bytes because
80+
these sizes match well with the packet sizes used on harddisks in
81+
file systems or file system caches. But as soon as you have to read only
82+
a few bytes and that many times performance drops significantly.
83+
</p>
84+
<p>
85+
Make sure you're properly buffering streams when reading or writing
86+
streams, especially when working with files. Just decorate your
87+
FileInputStream with a BufferedInputStream:
88+
</p>
89+
<source>
90+
InputStream in = new java.io.FileInputStream(myfile);
91+
try {
92+
in = new java.io.BufferedInputStream(in);
93+
94+
in.read(.....
95+
} finally {
96+
IOUtils.closeQuietly(in);
97+
}
98+
</source>
99+
<p>
100+
Pay attention that you're not buffering an already buffered stream. Some
101+
components like XML parsers may do their own buffering so decorating
102+
the InputStream you pass to the XML parser does nothing but slowing down
103+
your code. If you use our CopyUtils or IOUtils you don't need to
104+
additionally buffer the streams you use as the code in there already
105+
buffers the copy process. Always check the Javadocs for information.
106+
Another case where buffering is unnecessary is when you write to a
107+
ByteArrayOutputStream since you're writing to memory only.
108+
</p>
109+
</section>
110+
111+
</body>
112+
113+
</document>

‎xdocs/building.xml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<?xml version="1.0"?>
2+
3+
<!--
4+
Building IO
5+
$Id: building.xml,v 1.1 2004/01/16 17:05:03 jeremias Exp $
6+
-->
7+
8+
<document>
9+
<body>
10+
11+
<section name="Overview">
12+
<p>
13+
Jakarta Commons IO uses <a href="http://maven.apache.org">Maven</a> as
14+
build system. Please install Maven prior to attempting a build of IO.
15+
</p>
16+
</section>
17+
18+
<section name="Maven Goals">
19+
20+
<subsection name="Building a JAR file">
21+
<p>
22+
Change into IO's root directory and run "maven jar" to build the JAR
23+
file. After a successful build you will find it in the "target"
24+
subdirectory.
25+
</p>
26+
</subsection>
27+
28+
<subsection name="Other Goals">
29+
<p>
30+
To build the Javadocs, run "maven javadoc". The result will be in
31+
"target/docs/apidocs".
32+
</p>
33+
<p>
34+
To build the full website, run "maven site". The result will be in
35+
"target/docs".
36+
</p>
37+
</subsection>
38+
39+
</section>
40+
41+
</body>
42+
43+
</document>

‎xdocs/index.xml‎

Lines changed: 30 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
<!--
44
Main index
5-
$Id: index.xml,v 1.1 2003/12/21 00:53:41 matth Exp $
5+
$Id: index.xml,v 1.2 2004/01/16 17:05:03 jeremias Exp $
66
-->
77

88
<document>
@@ -23,12 +23,17 @@
2323

2424
<a name="utilities"/>
2525
<section name="Utility classes">
26-
<subsection name="CopyUtils">
26+
<subsection name="CopyUtils and IOUtils">
2727
<p>
2828
<code>org.apache.commons.io.CopyUtils</code>
2929
contains a comprehensive set of static methods for copying
3030
from String, byte[], InputStream, Reader
31-
to String, byte[], OutputStream, Writer.
31+
to OutputStream, Writer.
32+
</p>
33+
<p>
34+
<code>org.apache.commons.io.IOUtils</code>
35+
contains additional IO-related tools for safely closing streams
36+
and creating Strings and byte arrays from streams and Readers.
3237
</p>
3338

3439
<p>
@@ -37,34 +42,38 @@
3742
</p>
3843

3944
<source>
40-
InputStream in = new URL( "http://jakarta.apache.org" ).openStream();
41-
InputStreamReader inR = new InputStreamReader( in );
42-
BufferedReader buf = new BufferedReader( inR );
43-
String line;
44-
while ( ( line = buf.readLine() ) != null ) {
45-
System.out.println( line );
46-
}
47-
in.close();
45+
InputStream in = new URL( "http://jakarta.apache.org" ).openStream();
46+
try {
47+
InputStreamReader inR = new InputStreamReader( in );
48+
BufferedReader buf = new BufferedReader( inR );
49+
String line;
50+
while ( ( line = buf.readLine() ) != null ) {
51+
System.out.println( line );
52+
}
53+
} finally {
54+
in.close();
55+
}
4856
</source>
4957

5058
<p>
51-
With the CopyUtils class, that could be done with:
59+
With the IOUtils class, that could be done with:
5260
</p>
5361

5462
<source>
55-
InputStream in = new URL( "http://jakarta.apache.org" ).openStream();
56-
System.out.println( IOUtils.toString( in ) );
57-
in.close();
63+
InputStream in = new URL( "http://jakarta.apache.org" ).openStream();
64+
try {
65+
System.out.println( IOUtils.toString( in ) );
66+
} finally {
67+
IOUtils.closeQuietly(in);
68+
}
5869
</source>
5970

6071
<p>
6172
In certain application domains, such IO operations are
62-
common, and this class can save a great deal of time.
73+
common, and this class can save a great deal of time. And you can
74+
rely on well-tested code.
6375

6476
For utility code such as this, flexibility and speed are of primary importance.
65-
In CopyUtils, each kind of copy method has a variant which allows the
66-
buffer size to be set. For method that convert bytes to chars, the encoding
67-
method may also be set.
6877
</p>
6978

7079
</subsection>
@@ -75,8 +84,8 @@
7584
class contains methods for retrieving different components of a file path
7685
(directory name, file base name, file extension), methods
7786
for copying files to other files and directories, and methods
78-
for deleting and cleaning directories. For more information,
79-
see the class description
87+
for querying, deleting and cleaning directories. For more information,
88+
see the class description.
8089
</p>
8190
</subsection>
8291

‎xdocs/navigation.xml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616

1717
<menu name="Commons IO">
1818
<item name="Home" href="index.html"/>
19+
<item name="Best Practices" href="bestpractices.html"/>
20+
<item name="Building" href="building.html"/>
1921
<item name="Tasks" href="tasks.html"/>
2022
</menu>
2123

‎xdocs/tasks.xml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
release of this component:
88
</p>
99
<ul>
10-
<li>FilenameUtils: This class is a big mess ATM. We need to clean it up.</li>
1110
<li>IOUtilsTestCase: Handle unit tests that test an IOUtils method and a CopyUtils method at the same time. [Hen]</li>
1211
<li>Write TestCases for:
1312
<ul>
@@ -21,9 +20,16 @@
2120
<li>More Javadocs!!!</li>
2221
<li>Improve site!!!</li>
2322
</ul>
23+
<p>
24+
The following classes will be excluded from the initial release:
25+
</p>
26+
<ul>
27+
<li>FilenameUtils: This class is still a big mess with many methods not working properly.</li>
28+
</ul>
2429
</section>
2530
<section name="Post 1.0 release">
2631
<ul>
32+
<li>FilenameUtils: This class is a big mess ATM. We need to clean it up.</li>
2733
<li>A CsvReader/Writer set of classes in a csv sub-package</li>
2834
<li>FilePoller for telling when a file changes. Look in Tomcat, or GenJava[bayard]</li>
2935
<li>JoinReader/ConcatReader. One in GenJava, one submitted to Bayard</li>

0 commit comments

Comments
 (0)