commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject svn commit: r291743 - in /jakarta/commons/proper/io/trunk: project.properties xdocs/bestpractices.xml xdocs/description.xml xdocs/index.xml xdocs/tasks.xml
Date Mon, 26 Sep 2005 20:45:20 GMT
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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message