Author: scolebourne
Date: Mon Sep 26 13:45:14 2005
New Revision: 291743
URL: http://svn.apache.org/viewcvs?rev=291743&view=rev
Log:
Prepare documentation for 1.1 release
Modified:
jakarta/commons/proper/io/trunk/project.properties
jakarta/commons/proper/io/trunk/xdocs/bestpractices.xml
jakarta/commons/proper/io/trunk/xdocs/description.xml
jakarta/commons/proper/io/trunk/xdocs/index.xml
jakarta/commons/proper/io/trunk/xdocs/tasks.xml
Modified: jakarta/commons/proper/io/trunk/project.properties
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/io/trunk/project.properties?rev=291743&r1=291742&r2=291743&view=diff
==============================================================================
--- jakarta/commons/proper/io/trunk/project.properties (original)
+++ jakarta/commons/proper/io/trunk/project.properties Mon Sep 26 13:45:14 2005
@@ -19,11 +19,24 @@
maven.xdoc.version=${pom.currentVersion}
maven.xdoc.developmentProcessUrl=http://jakarta.apache.org/commons/charter.html
maven.xdoc.poweredby.image=maven-feather.png
+maven.xdoc.copy.excludes=images/file.gif,images/folder-closed.gif,images/folder-open.gif,images/icon_alert.gif,images/icon_alertsml.gif,images/icon_arrowfolder1_sml.gif,images/icon_arrowfolder2_sml.gif,images/icon_arrowmembers1_sml.gif,images/icon_arrowmembers2_sml.gif,images/icon_arrowusergroups1_sml.gif,images/icon_arrowusergroups2_sml.gif,images/icon_confirmsml.gif,images/icon_help_lrg.gif,images/icon_infosml.gif,images/icon_members_sml.gif,images/icon_sortleft.gif,images/icon_sortright.gif,images/icon_usergroups_sml.gif,images/icon_waste_lrg.gif,images/icon_waste_sml.gif,images/none.png,images/nw_maj.gif,images/nw_maj_hi.gif,images/nw_med.gif,images/nw_med_hi.gif,images/nw_med_rond.gif,images/nw_min.gif,images/nw_min_036.gif,images/nw_min_hi.gif,images/poweredby_036.gif,images/product_logo.gif,images/se_maj_rond.gif,images/sw_min.gif,images/logos/**
+maven.xdoc.copy.excludes.classic=images/external-classic.png,images/help_logo.gif,images/icon_arrowfolderclosed1_sml.gif,images/icon_arrowwaste1_sml.gif,images/icon_arrowwaste2_sml.gif,images/icon_doc_lrg.gif,images/icon_doc_sml.gif,images/icon_error_lrg.gif,images/icon_folder_lrg.gif,images/icon_folder_sml.gif,images/icon_help_sml.gif,images/icon_info_lrg.gif,images/icon_members_lrg.gif,images/icon_sortdown.gif,images/icon_sortup.gif,images/icon_success_lrg.gif,images/icon_usergroups_lrg.gif,images/icon_arrowfolderopen2_sml.gif,images/icon_warning_lrg.gif,images/newwindow-classic.png,images/nw_maj_rond.gif,images/strich.gif,images/sw_maj_rond.gif,images/sw_med_rond.gif
maven.javadoc.author=false
maven.javadoc.links=http://java.sun.com/j2se/1.4/docs/api/
+maven.javadoc.source=1.3
maven.javadoc.additionalparam=-tag todo:a:"To Do:"
maven.jdiff.old.tag=IO_1_0
-maven.xdoc.copy.excludes=images/file.gif,images/folder-closed.gif,images/folder-open.gif,images/icon_alert.gif,images/icon_alertsml.gif,images/icon_arrowfolder1_sml.gif,images/icon_arrowfolder2_sml.gif,images/icon_arrowmembers1_sml.gif,images/icon_arrowmembers2_sml.gif,images/icon_arrowusergroups1_sml.gif,images/icon_arrowusergroups2_sml.gif,images/icon_confirmsml.gif,images/icon_help_lrg.gif,images/icon_infosml.gif,images/icon_members_sml.gif,images/icon_sortleft.gif,images/icon_sortright.gif,images/icon_usergroups_sml.gif,images/icon_waste_lrg.gif,images/icon_waste_sml.gif,images/none.png,images/nw_maj.gif,images/nw_maj_hi.gif,images/nw_med.gif,images/nw_med_hi.gif,images/nw_med_rond.gif,images/nw_min.gif,images/nw_min_036.gif,images/nw_min_hi.gif,images/poweredby_036.gif,images/product_logo.gif,images/se_maj_rond.gif,images/sw_min.gif,images/logos/**
-maven.xdoc.copy.excludes.classic=images/external-classic.png,images/help_logo.gif,images/icon_arrowfolderclosed1_sml.gif,images/icon_arrowwaste1_sml.gif,images/icon_arrowwaste2_sml.gif,images/icon_doc_lrg.gif,images/icon_doc_sml.gif,images/icon_error_lrg.gif,images/icon_folder_lrg.gif,images/icon_folder_sml.gif,images/icon_help_sml.gif,images/icon_info_lrg.gif,images/icon_members_lrg.gif,images/icon_sortdown.gif,images/icon_sortup.gif,images/icon_success_lrg.gif,images/icon_usergroups_lrg.gif,images/icon_arrowfolderopen2_sml.gif,images/icon_warning_lrg.gif,images/newwindow-classic.png,images/nw_maj_rond.gif,images/strich.gif,images/sw_maj_rond.gif,images/sw_med_rond.gif
+
+# Generate class files for specific VM version (e.g., 1.1 or 1.2).
+# Note that the default value depends on the JVM that is running Ant.
+# In particular, if you use JDK 1.4+ the generated classes will not be usable
+# for a 1.1 Java VM unless you explicitly set this attribute to the value 1.1
+# (which is the default value for JDK 1.1 to 1.3).
+maven.compile.target = 1.1
+
+# Specifies the source version for the Java compiler.
+# Corresponds to the source attribute for the ant javac task.
+# Valid values are 1.3, 1.4, 1.5.
+maven.compile.source = 1.3
Modified: jakarta/commons/proper/io/trunk/xdocs/bestpractices.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/io/trunk/xdocs/bestpractices.xml?rev=291743&r1=291742&r2=291743&view=diff
==============================================================================
--- jakarta/commons/proper/io/trunk/xdocs/bestpractices.xml (original)
+++ jakarta/commons/proper/io/trunk/xdocs/bestpractices.xml Mon Sep 26 13:45:14
2005
@@ -21,9 +21,9 @@
</properties>
<body>
- <section name="Overview">
+ <section name="Best practices">
<p>
- This document presents a number of "best practices" in the IO area.
+ This document presents a number of 'best practices' in the IO area.
</p>
</section>
@@ -40,20 +40,26 @@
<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.
+ These are good reasons not to work with filenames as Strings.
+ Using java.io.File instead handles many of the above cases nicely.
+ Thus, our best practice recommendation is to use java.io.File
+ instead of String for filenames to avoid platform dependencies.
</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.
+ <i>
+ Version 1.1 of commons-io now includes a dedicated filename
+ handling class - <a
href="api-release/index.html?org/apache/commons/io/FilenameUtils.html">FilenameUtils</a>.
+ This does handle many of these filename issues, however we still
+ recommend, wherever possible, that you use java.io.File objects.
+ </i>
+ </p>
+ <p>
+ Let's look at an example.
</p>
<source>
public static String getExtension(String filename) {
int index = filename.lastIndexOf('.');
-
- if (-1 == index) {
+ if (index == -1) {
return "";
} else {
return filename.substring(index + 1);
@@ -62,12 +68,15 @@
<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"
+ "C:\Temp\documentation.new\README".
+ The method as defined above would return "new\README" - definitely
+ not what you wanted.
</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.
+ 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:
Modified: jakarta/commons/proper/io/trunk/xdocs/description.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/io/trunk/xdocs/description.xml?rev=291743&r1=291742&r2=291743&view=diff
==============================================================================
--- jakarta/commons/proper/io/trunk/xdocs/description.xml (original)
+++ jakarta/commons/proper/io/trunk/xdocs/description.xml Mon Sep 26 13:45:14
2005
@@ -21,23 +21,25 @@
</properties>
<body>
- <section name="Commons IO">
+ <section name="User guide">
<p>
- Commons-IO contains <a href="#Utility classes">utility classes</a>,
- stream implementations, <a href="#File filters">file filters</a>,
and
- <a href="#Endian classes">endian classes</a>.
+ Commons-IO contains
+ <a href="#Utility classes">utility classes</a>,
+ <a href="#Endian classes">endian classes</a>,
+ <a href="#File filters">file filters</a> and
+ <a href="#Streams">stream implementations</a>.
</p>
<p>
For a more detailed descriptions, take a look at the
- <a href="apidocs/index.html">JavaDocs</a>.
+ <a href="api-release/index.html">javadocs</a>.
</p>
</section>
<section name="Utility classes">
<subsection name="IOUtils">
<p>
- <code>org.apache.commons.io.IOUtils</code>
+ <a
href="api-release/index.html?org/apache/commons/io/IOUtils.html">IOUtils</a>
contains utility methods dealing with reading, writing and
copying.
The methods work on InputStream, OutputStream, Reader and
Writer.
</p>
@@ -57,8 +59,7 @@
}
} finally {
in.close();
- }
- </source>
+ }</source>
<p>
With the IOUtils class, that could be done with:
@@ -70,64 +71,71 @@
System.out.println( IOUtils.toString( in ) );
} finally {
IOUtils.closeQuietly(in);
- }
- </source>
+ }</source>
<p>
In certain application domains, such IO operations are
common, and this class can save a great deal of time. And you
can
rely on well-tested code.
-
+ </p>
+ <p>
For utility code such as this, flexibility and speed are of
primary importance.
+ However you should also understand the limitations of this
approach.
+ Using the above technique to read a 1GB file would result in an
+ attempt to create a 1GB String object!
</p>
</subsection>
<subsection name="FileUtils">
<p>
- The <code>org.apache.commons.io.FileUtils</code> class contains
- utility methods for working with File objects.
+ The <a
href="api-release/index.html?org/apache/commons/io/FileUtils.html">FileUtils</a>
+ class contains utility methods for working with File objects.
These include reading, writing, copying and comparing files.
</p>
+ <p>
+ For example to read an entire file line by line you could use:
+ </p>
+ <source>
+ File file = new File("/commons/io/project.properties");
+ List lines = FileUtils.readLines(file, "UTF-8");</source>
</subsection>
<subsection name="FilenameUtils">
<p>
- The <code>org.apache.commons.io.FilenameUtils</code> class
contains
- utility methods for working with filenames <i>without</i>
+ The <a
href="api-release/index.html?org/apache/commons/io/FilenameUtils.html">FilenameUtils</a>
+ class contains utility methods for working with filenames
<i>without</i>
using File objects. The class aims to be consistent
between Unix and Windows, to aid transitions between these
environments (such as moving from development to production).
</p>
+ <p>
+ For example to normalize a filename removing double dot
segments:
+ </p>
+ <source>
+ String filename = "C:/commons/io/../lang/project.xml";
+ String normalized = FilenameUtils.normalize(filename);
+ // result is "C:/commons/lang/project.xml"</source>
</subsection>
<subsection name="FileSystemUtils">
<p>
- The <code>org.apache.commons.io.FileSystemUtils</code> class
contains
+ The <a
href="api-release/index.html?org/apache/commons/io/FileSystemUtils.html">FileSystemUtils</a>
+ class contains
utility methods for working with the file system
to access functionality not supported by the JDK.
Currently, the only method is to get the free space on a drive.
Note that this uses the command line, not native code.
</p>
+ <p>
+ For example to find the free space on a drive:
+ </p>
+ <source>
+ long freeSpace = FileSystemUtils.freeSpace("C:/");</source>
</subsection>
</section>
- <section name="File filters">
- <p>
- The <code>org.apache.commons.io.filefilter</code>
- package defines an interface (<code>IOFileFilter</code>) that
- combines both <code>java.io.FileFilter</code> and
- <code>java.io.FilenameFilter</code>. Besides
- that the package offers a series of ready-to-use
- implementations of the <code>IOFileFilter</code>
- interface including
- implementation that allow you to combine other such filters.
-
- These filter can be used to list files or in FileDialog, for
example.
- </p>
- </section>
-
<section name="Endian classes">
<p>
Different computer architectures adopt different
@@ -144,13 +152,13 @@
<ul>
<li>
- The <code>org.apache.commons.io.EndianUtils</code>
+ The <a
href="api-release/index.html?org/apache/commons/io/EndianUtils.html">EndianUtils</a>
class contains static methods for swapping the Endian-ness
of Java primitives and streams.
</li>
<li>
- The <code>org.apache.commons.io.input.SwappedDataInputStream</code>
+ The <a
href="api-release/index.html?org/apache/commons/io/input/SwappedDataInputStream.html">SwappedDataInputStream</a>
class is an implementation of the <code>DataInput</code> interface.
With
this, one can read data from files of non-native Endian-ness.
</li>
@@ -162,6 +170,50 @@
href="http://www.cs.umass.edu/~verts/cs32/endian.html";>http://www.cs.umass.edu/~verts/cs32/endian.html</a>
</p>
+ </section>
+
+ <section name="File filters">
+ <p>
+ The <code>org.apache.commons.io.filefilter</code>
+ package defines an interface
+ (<a
href="api-release/index.html?org/apache/commons/io/filefilter/IOFileFilter.html">IOFileFilter</a>)
+ that combines both <code>java.io.FileFilter</code> and
+ <code>java.io.FilenameFilter</code>. Besides
+ that the package offers a series of ready-to-use
+ implementations of the <code>IOFileFilter</code>
+ interface including
+ implementation that allow you to combine other such filters.
+
+ These filters can be used to list files or in FileDialog, for
example.
+ </p>
+ <p>
+ See the
+ <a
href="api-release/index.html?org/apache/commons/io/filefilter/package-summary.html">filefilter</a>
+ package javadoc for more details.
+ </p>
+ </section>
+
+ <section name="Streams">
+ <p>
+ The <code>org.apache.commons.io.input</code> and
+ <code>org.apache.commons.io.output</code> packages
+ contain various useful implementations of streams.
+ These include:
+ <ul>
+ <li>Null output stream - that silently absorbs all data sent to
it</li>
+ <li>Tee output stream - that sends output data to two streams
instead of one</li>
+ <li>Byte array output stream - that is a faster version of the JDK
class</li>
+ <li>Counting streams - that count the number of bytes passed</li>
+ <li>Proxy streams - that delegate to the correct method in the
proxy</li>
+ <li>Lockable writer - that provides synchronization of writes
using a lock file</li>
+ </ul>
+ </p>
+ <p>
+ See the
+ <a
href="api-release/index.html?org/apache/commons/io/input/package-summary.html">input</a>
or
+ <a
href="api-release/index.html?org/apache/commons/io/output/package-summary.html">output</a>
+ package javadoc for more details.
+ </p>
</section>
</body>
Modified: jakarta/commons/proper/io/trunk/xdocs/index.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/io/trunk/xdocs/index.xml?rev=291743&r1=291742&r2=291743&view=diff
==============================================================================
--- jakarta/commons/proper/io/trunk/xdocs/index.xml (original)
+++ jakarta/commons/proper/io/trunk/xdocs/index.xml Mon Sep 26 13:45:14 2005
@@ -24,6 +24,8 @@
<section name="Commons IO">
<p>
Commons IO is a library of utilities to assist with developing IO
functionality.
+</p>
+<p>
There are three main areas included:
<ul>
<li>Utility classes - with static methods to perform common tasks</li>
@@ -35,7 +37,8 @@
<!-- ================================================== -->
<section name="Documentation">
<p>
-A getting started <a href="description.html">user guide</a> is available.
+A getting started <a href="description.html">user guide</a> is available,
+as are some IO <a href="bestpractices.html">best practices</a>.
</p>
<p>
The JavaDoc API documents are available online:
Modified: jakarta/commons/proper/io/trunk/xdocs/tasks.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/io/trunk/xdocs/tasks.xml?rev=291743&r1=291742&r2=291743&view=diff
==============================================================================
--- jakarta/commons/proper/io/trunk/xdocs/tasks.xml (original)
+++ jakarta/commons/proper/io/trunk/xdocs/tasks.xml Mon Sep 26 13:45:14 2005
@@ -25,7 +25,8 @@
The following are some of the proposed ideas and tasks for commons-io:
</p>
<ul>
- <li>A proper user guide.</li>
+ <li>A proper user guide</li>
+ <li>An iterator through the lines of a file</li>
<li>FilePoller for telling when a file changes. Look in Tomcat, or
GenJava[bayard]</li>
<li>A "hot folder" handler which triggers an action when a new file
has been uploaded to an FTP directory, for example.</li>
<li>JoinReader/ConcatReader. One in GenJava, one submitted to
Bayard</li>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
