jeremias 2004/01/16 09:05:03
Modified: io/xdocs index.xml navigation.xml tasks.xml
Added: io/xdocs bestpractices.xml building.xml
Log:
Corrections and additions to the IO website.
Revision Changes Path
1.2 +30 -21 jakarta-commons-sandbox/io/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/io/xdocs/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 21 Dec 2003 00:53:41 -0000 1.1
+++ index.xml 16 Jan 2004 17:05:03 -0000 1.2
@@ -23,12 +23,17 @@
<a name="utilities"/>
<section name="Utility classes">
- <subsection name="CopyUtils">
+ <subsection name="CopyUtils and IOUtils">
<p>
<code>org.apache.commons.io.CopyUtils</code>
contains a comprehensive set of static methods for copying
from String, byte[], InputStream, Reader
- to String, byte[], OutputStream, Writer.
+ to OutputStream, Writer.
+ </p>
+ <p>
+ <code>org.apache.commons.io.IOUtils</code>
+ contains additional IO-related tools for safely closing streams
+ and creating Strings and byte arrays from streams and Readers.
</p>
<p>
@@ -37,34 +42,38 @@
</p>
<source>
- InputStream in = new URL( "http://jakarta.apache.org";
).openStream();
- InputStreamReader inR = new InputStreamReader( in );
- BufferedReader buf = new BufferedReader( inR );
- String line;
- while ( ( line = buf.readLine() ) != null ) {
- System.out.println( line );
- }
- in.close();
+ InputStream in = new URL( "http://jakarta.apache.org"; ).openStream();
+ try {
+ InputStreamReader inR = new InputStreamReader( in );
+ BufferedReader buf = new BufferedReader( inR );
+ String line;
+ while ( ( line = buf.readLine() ) != null ) {
+ System.out.println( line );
+ }
+ } finally {
+ in.close();
+ }
</source>
<p>
- With the CopyUtils class, that could be done with:
+ With the IOUtils class, that could be done with:
</p>
<source>
- InputStream in = new URL( "http://jakarta.apache.org";
).openStream();
- System.out.println( IOUtils.toString( in ) );
- in.close();
+ InputStream in = new URL( "http://jakarta.apache.org"; ).openStream();
+ try {
+ System.out.println( IOUtils.toString( in ) );
+ } finally {
+ IOUtils.closeQuietly(in);
+ }
</source>
<p>
In certain application domains, such IO operations are
- common, and this class can save a great deal of time.
+ common, and this class can save a great deal of time. And you can
+ rely on well-tested code.
For utility code such as this, flexibility and speed are of primary
importance.
- In CopyUtils, each kind of copy method has a variant which allows
the
- buffer size to be set. For method that convert bytes to chars, the
encoding
- method may also be set.
</p>
</subsection>
@@ -75,8 +84,8 @@
class contains methods for retrieving different components of a
file path
(directory name, file base name, file extension), methods
for copying files to other files and directories, and methods
- for deleting and cleaning directories. For more information,
- see the class description
+ for querying, deleting and cleaning directories. For more
information,
+ see the class description.
</p>
</subsection>
1.4 +2 -0 jakarta-commons-sandbox/io/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/io/xdocs/navigation.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- navigation.xml 21 Dec 2003 00:53:41 -0000 1.3
+++ navigation.xml 16 Jan 2004 17:05:03 -0000 1.4
@@ -16,6 +16,8 @@
<menu name="Commons IO">
<item name="Home" href="index.html"/>
+ <item name="Best Practices" href="bestpractices.html"/>
+ <item name="Building" href="building.html"/>
<item name="Tasks" href="tasks.html"/>
</menu>
1.16 +7 -1 jakarta-commons-sandbox/io/xdocs/tasks.xml
Index: tasks.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/io/xdocs/tasks.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- tasks.xml 2 Jan 2004 07:54:03 -0000 1.15
+++ tasks.xml 16 Jan 2004 17:05:03 -0000 1.16
@@ -7,7 +7,6 @@
release of this component:
</p>
<ul>
- <li>FilenameUtils: This class is a big mess ATM. We need to clean it
up.</li>
<li>IOUtilsTestCase: Handle unit tests that test an IOUtils method and a
CopyUtils method at the same time. [Hen]</li>
<li>Write TestCases for:
<ul>
@@ -21,9 +20,16 @@
<li>More Javadocs!!!</li>
<li>Improve site!!!</li>
</ul>
+ <p>
+ The following classes will be excluded from the initial release:
+ </p>
+ <ul>
+ <li>FilenameUtils: This class is still a big mess with many methods not
working properly.</li>
+ </ul>
</section>
<section name="Post 1.0 release">
<ul>
+ <li>FilenameUtils: This class is a big mess ATM. We need to clean it
up.</li>
<li>A CsvReader/Writer set of classes in a csv sub-package</li>
<li>FilePoller for telling when a file changes. Look in Tomcat, or
GenJava[bayard]</li>
<li>JoinReader/ConcatReader. One in GenJava, one submitted to Bayard</li>
1.1 jakarta-commons-sandbox/io/xdocs/bestpractices.xml
Index: bestpractices.xml
===================================================================
<?xml version="1.0"?>
<!--
Building IO
$Id: bestpractices.xml,v 1.1 2004/01/16 17:05:03 jeremias Exp $
-->
<document>
<body>
<section name="Overview">
<p>
This document presents a number of "best practices" in the IO area.
</p>
</section>
<section name="java.io.File">
<p>
Often, you have to deal with files and filenames. There are many
things that can go wrong:
</p>
<ul>
<li>A class works in Unix but doesn't on Windows (or vice versa)</li>
<li>Invalid filenames due to double or missing path separators</li>
<li>UNC filenames (on Windows) don't work with my home-grown filename
utility function</li>
<li>etc. etc.</li>
</ul>
<p>
These are good reasons not to work with filenames as Strings. Use
java.io.File instead which handles many of the above cases nicely. Too
many people are still always using Strings for filenames and risk
platform dependencies, for example.
</p>
<p>
Let's look at an example. BTW, it's one of the functions that made us
skip the class FilenameUtils for the initial release of Commons IO.
</p>
<source>
public static String getExtension(String filename) {
int index = filename.lastIndexOf('.');
if (-1 == index) {
return "";
} else {
return filename.substring(index + 1);
}
}</source>
<p>
Easy enough? Right, but what happens if someone passes in a full path
instead of only a filename? Consider the following, perfectly legal path:
"C:\Temp\documentation.new\README"
</p>
<p>
Please use java.io.File for filenames instead of Strings. The
functionality
that the class provides is well tested. In FileUtils you will find other
useful utility functions around java.io.File.
</p>
<p>
Instead of:
</p>
<source>
String tmpdir = "/var/tmp";
String tmpfile = tmpdir + System.getProperty("file.separator") + "test.tmp";
InputStream in = new java.io.FileInputStream(tmpfile);</source>
<p>
...write:
</p>
<source>
File tmpdir = new File("/var/tmp");
File tmpfile = new File(tmpdir, "test.tmp");
InputStream in = new java.io.FileInputStream(tmpfile);</source>
</section>
<section name="Buffering streams">
<p>
IO performance depends a lot from the buffering strategy. Usually, it's
quite fast to read packets with the size of 512 or 1024 bytes because
these sizes match well with the packet sizes used on harddisks in
file systems or file system caches. But as soon as you have to read only
a few bytes and that many times performance drops significantly.
</p>
<p>
Make sure you're properly buffering streams when reading or writing
streams, especially when working with files. Just decorate your
FileInputStream with a BufferedInputStream:
</p>
<source>
InputStream in = new java.io.FileInputStream(myfile);
try {
in = new java.io.BufferedInputStream(in);
in.read(.....
} finally {
IOUtils.closeQuietly(in);
}
</source>
<p>
Pay attention that you're not buffering an already buffered stream. Some
components like XML parsers may do their own buffering so decorating
the InputStream you pass to the XML parser does nothing but slowing down
your code. If you use our CopyUtils or IOUtils you don't need to
additionally buffer the streams you use as the code in there already
buffers the copy process. Always check the Javadocs for information.
Another case where buffering is unnecessary is when you write to a
ByteArrayOutputStream since you're writing to memory only.
</p>
</section>
</body>
</document>
1.1 jakarta-commons-sandbox/io/xdocs/building.xml
Index: building.xml
===================================================================
<?xml version="1.0"?>
<!--
Building IO
$Id: building.xml,v 1.1 2004/01/16 17:05:03 jeremias Exp $
-->
<document>
<body>
<section name="Overview">
<p>
Jakarta Commons IO uses <a href="http://maven.apache.org";>Maven</a> as
build system. Please install Maven prior to attempting a build of IO.
</p>
</section>
<section name="Maven Goals">
<subsection name="Building a JAR file">
<p>
Change into IO's root directory and run "maven jar" to build the JAR
file. After a successful build you will find it in the "target"
subdirectory.
</p>
</subsection>
<subsection name="Other Goals">
<p>
To build the Javadocs, run "maven javadoc". The result will be in
"target/docs/apidocs".
</p>
<p>
To build the full website, run "maven site". The result will be in
"target/docs".
</p>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
