src/site/xdoc/description.xml - platform/external/apache-commons-io - Git at Google

 <?xml version="1.0"?>
 <!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 -->
 <document>
  <properties>
   <title>User guide</title>
   <author email="[email protected]">Commons Documentation Team</author>
  </properties>
   <body>

     <section name="User guide">
         <p>
             Commons-IO contains
             <a href="#Utility classes">utility classes</a>,
             <a href="#Endian classes">endian classes</a>,
             <a href="#Line iterator">line iterator</a>,
             <a href="#File filters">file filters</a>,
             <a href="#File comparators">file comparators</a> and
             <a href="#Streams">stream implementations</a>.
         </p>

         <p>
             For a more detailed descriptions, take a look at the
             <a href="api-release/index.html">Javadocs</a>.
         </p>
     </section>

     <section name="Utility classes">
         <subsection name="IOUtils">
             <p>
                 <a href="apidocs/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>
             <p>
                 As an example, consider the task of reading bytes
                 from a URL, and printing them. This would typically be done like this:
             </p>

             <source>
  InputStream in = new URL( "https://commons.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 IOUtils class, that could be done with:
             </p>

             <source>
  InputStream in = new URL( "https://commons.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. 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 <a href="apidocs/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 <a href="apidocs/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 <a href="apidocs/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="Endian classes">
         <p>
             Different computer architectures adopt different
             conventions for byte ordering. In so-called
             "Little Endian" architectures (eg Intel), the low-order
             byte is stored in memory at the lowest address, and
             subsequent bytes at higher addresses. For "Big Endian"
             architectures (eg Motorola), the situation is reversed.
         </p>

         <p>
         There are two classes in this package of relevance:
         </p>

         <ul>
            <li>
            The <a href="apidocs/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 <a href="apidocs/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>
         </ul>

         <p>
             For more information, see
             <a
                 href="http://www.cs.umass.edu/~verts/cs32/endian.html">http://www.cs.umass.edu/~verts/cs32/endian.html</a>
          </p>

     </section>

     <section name="Line iterator">
         <p>
             The <code>org.apache.commons.io.LineIterator</code> class
             provides a flexible way for working with a line-based file.
             An instance can be created directly, or via factory methods on
             <code>FileUtils</code> or <code>IOUtils</code>.
             The recommended usage pattern is:
         </p>
         <source>
  LineIterator it = FileUtils.lineIterator(file, "UTF-8");
  try {
    while (it.hasNext()) {
      String line = it.nextLine();
      /// do something with line
    }
  } finally {
    LineIterator.closeQuietly(iterator);
  }</source>
     </section>

     <section name="File filters">
         <p>
             The <code>org.apache.commons.io.filefilter</code>
             package defines an interface
             (<a href="apidocs/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="apidocs/index.html?org/apache/commons/io/filefilter/package-summary.html">filefilter</a>
             package javadoc for more details.
         </p>
     </section>

     <section name="File comparators">
         <p>
             The <code>org.apache.commons.io.comparator</code>
             package provides a number of <code>java.util.Comparator</code>
             implementations for <code>java.io.File</code>.

             These comparators can be used to sort lists and arrays of files, for example.
         </p>
         <p>
             See the
             <a href="apidocs/index.html?org/apache/commons/io/comparator/package-summary.html">comparator</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="apidocs/index.html?org/apache/commons/io/input/package-summary.html">input</a> or
             <a href="apidocs/index.html?org/apache/commons/io/output/package-summary.html">output</a>
             package javadoc for more details.
         </p>
     </section>

   </body>

 </document>
	<?xml version="1.0"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<document>
	<properties>
	<title>User guide</title>
	<author email="[email protected]">Commons Documentation Team</author>
	</properties>
	<body>

	<section name="User guide">
	<p>
	Commons-IO contains
	<a href="#Utility classes">utility classes</a>,
	<a href="#Endian classes">endian classes</a>,
	<a href="#Line iterator">line iterator</a>,
	<a href="#File filters">file filters</a>,
	<a href="#File comparators">file comparators</a> and
	<a href="#Streams">stream implementations</a>.
	</p>

	<p>
	For a more detailed descriptions, take a look at the
	<a href="api-release/index.html">Javadocs</a>.
	</p>
	</section>

	<section name="Utility classes">
	<subsection name="IOUtils">
	<p>
	<a href="apidocs/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>
	<p>
	As an example, consider the task of reading bytes
	from a URL, and printing them. This would typically be done like this:
	</p>

	<source>
	InputStream in = new URL( "https://commons.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 IOUtils class, that could be done with:
	</p>

	<source>
	InputStream in = new URL( "https://commons.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. 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 <a href="apidocs/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 <a href="apidocs/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 <a href="apidocs/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="Endian classes">
	<p>
	Different computer architectures adopt different
	conventions for byte ordering. In so-called
	"Little Endian" architectures (eg Intel), the low-order
	byte is stored in memory at the lowest address, and
	subsequent bytes at higher addresses. For "Big Endian"
	architectures (eg Motorola), the situation is reversed.
	</p>

	<p>
	There are two classes in this package of relevance:
	</p>

	<ul>
	<li>
	The <a href="apidocs/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 <a href="apidocs/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>
	</ul>

	<p>
	For more information, see
	<a
	href="http://www.cs.umass.edu/~verts/cs32/endian.html">http://www.cs.umass.edu/~verts/cs32/endian.html</a>
	</p>

	</section>

	<section name="Line iterator">
	<p>
	The <code>org.apache.commons.io.LineIterator</code> class
	provides a flexible way for working with a line-based file.
	An instance can be created directly, or via factory methods on
	<code>FileUtils</code> or <code>IOUtils</code>.
	The recommended usage pattern is:
	</p>
	<source>
	LineIterator it = FileUtils.lineIterator(file, "UTF-8");
	try {
	while (it.hasNext()) {
	String line = it.nextLine();
	/// do something with line
	}
	} finally {
	LineIterator.closeQuietly(iterator);
	}</source>
	</section>

	<section name="File filters">
	<p>
	The <code>org.apache.commons.io.filefilter</code>
	package defines an interface
	(<a href="apidocs/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="apidocs/index.html?org/apache/commons/io/filefilter/package-summary.html">filefilter</a>
	package javadoc for more details.
	</p>
	</section>

	<section name="File comparators">
	<p>
	The <code>org.apache.commons.io.comparator</code>
	package provides a number of <code>java.util.Comparator</code>
	implementations for <code>java.io.File</code>.

	These comparators can be used to sort lists and arrays of files, for example.
	</p>
	<p>
	See the
	<a href="apidocs/index.html?org/apache/commons/io/comparator/package-summary.html">comparator</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="apidocs/index.html?org/apache/commons/io/input/package-summary.html">input</a> or
	<a href="apidocs/index.html?org/apache/commons/io/output/package-summary.html">output</a>
	package javadoc for more details.
	</p>
	</section>

	</body>

	</document>