1*0c4d7b72SSadaf Ebrahimi<?xml version="1.0"?> 2*0c4d7b72SSadaf Ebrahimi<!-- 3*0c4d7b72SSadaf EbrahimiLicensed to the Apache Software Foundation (ASF) under one or more 4*0c4d7b72SSadaf Ebrahimicontributor license agreements. See the NOTICE file distributed with 5*0c4d7b72SSadaf Ebrahimithis work for additional information regarding copyright ownership. 6*0c4d7b72SSadaf EbrahimiThe ASF licenses this file to You under the Apache License, Version 2.0 7*0c4d7b72SSadaf Ebrahimi(the "License"); you may not use this file except in compliance with 8*0c4d7b72SSadaf Ebrahimithe License. You may obtain a copy of the License at 9*0c4d7b72SSadaf Ebrahimi 10*0c4d7b72SSadaf Ebrahimi http://www.apache.org/licenses/LICENSE-2.0 11*0c4d7b72SSadaf Ebrahimi 12*0c4d7b72SSadaf EbrahimiUnless required by applicable law or agreed to in writing, software 13*0c4d7b72SSadaf Ebrahimidistributed under the License is distributed on an "AS IS" BASIS, 14*0c4d7b72SSadaf EbrahimiWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15*0c4d7b72SSadaf EbrahimiSee the License for the specific language governing permissions and 16*0c4d7b72SSadaf Ebrahimilimitations under the License. 17*0c4d7b72SSadaf Ebrahimi--> 18*0c4d7b72SSadaf Ebrahimi<document> 19*0c4d7b72SSadaf Ebrahimi <properties> 20*0c4d7b72SSadaf Ebrahimi <title>User guide</title> 21*0c4d7b72SSadaf Ebrahimi <author email="[email protected]">Commons Documentation Team</author> 22*0c4d7b72SSadaf Ebrahimi </properties> 23*0c4d7b72SSadaf Ebrahimi <body> 24*0c4d7b72SSadaf Ebrahimi 25*0c4d7b72SSadaf Ebrahimi <section name="User guide"> 26*0c4d7b72SSadaf Ebrahimi <p> 27*0c4d7b72SSadaf Ebrahimi Commons-IO contains 28*0c4d7b72SSadaf Ebrahimi <a href="#Utility classes">utility classes</a>, 29*0c4d7b72SSadaf Ebrahimi <a href="#Endian classes">endian classes</a>, 30*0c4d7b72SSadaf Ebrahimi <a href="#Line iterator">line iterator</a>, 31*0c4d7b72SSadaf Ebrahimi <a href="#File filters">file filters</a>, 32*0c4d7b72SSadaf Ebrahimi <a href="#File comparators">file comparators</a> and 33*0c4d7b72SSadaf Ebrahimi <a href="#Streams">stream implementations</a>. 34*0c4d7b72SSadaf Ebrahimi </p> 35*0c4d7b72SSadaf Ebrahimi 36*0c4d7b72SSadaf Ebrahimi <p> 37*0c4d7b72SSadaf Ebrahimi For a more detailed descriptions, take a look at the 38*0c4d7b72SSadaf Ebrahimi <a href="api-release/index.html">Javadocs</a>. 39*0c4d7b72SSadaf Ebrahimi </p> 40*0c4d7b72SSadaf Ebrahimi </section> 41*0c4d7b72SSadaf Ebrahimi 42*0c4d7b72SSadaf Ebrahimi <section name="Utility classes"> 43*0c4d7b72SSadaf Ebrahimi <subsection name="IOUtils"> 44*0c4d7b72SSadaf Ebrahimi <p> 45*0c4d7b72SSadaf Ebrahimi <a href="apidocs/index.html?org/apache/commons/io/IOUtils.html">IOUtils</a> 46*0c4d7b72SSadaf Ebrahimi contains utility methods dealing with reading, writing and copying. 47*0c4d7b72SSadaf Ebrahimi The methods work on InputStream, OutputStream, Reader and Writer. 48*0c4d7b72SSadaf Ebrahimi </p> 49*0c4d7b72SSadaf Ebrahimi <p> 50*0c4d7b72SSadaf Ebrahimi As an example, consider the task of reading bytes 51*0c4d7b72SSadaf Ebrahimi from a URL, and printing them. This would typically be done like this: 52*0c4d7b72SSadaf Ebrahimi </p> 53*0c4d7b72SSadaf Ebrahimi 54*0c4d7b72SSadaf Ebrahimi <source> 55*0c4d7b72SSadaf Ebrahimi InputStream in = new URL( "https://commons.apache.org" ).openStream(); 56*0c4d7b72SSadaf Ebrahimi try { 57*0c4d7b72SSadaf Ebrahimi InputStreamReader inR = new InputStreamReader( in ); 58*0c4d7b72SSadaf Ebrahimi BufferedReader buf = new BufferedReader( inR ); 59*0c4d7b72SSadaf Ebrahimi String line; 60*0c4d7b72SSadaf Ebrahimi while ( ( line = buf.readLine() ) != null ) { 61*0c4d7b72SSadaf Ebrahimi System.out.println( line ); 62*0c4d7b72SSadaf Ebrahimi } 63*0c4d7b72SSadaf Ebrahimi } finally { 64*0c4d7b72SSadaf Ebrahimi in.close(); 65*0c4d7b72SSadaf Ebrahimi }</source> 66*0c4d7b72SSadaf Ebrahimi 67*0c4d7b72SSadaf Ebrahimi <p> 68*0c4d7b72SSadaf Ebrahimi With the IOUtils class, that could be done with: 69*0c4d7b72SSadaf Ebrahimi </p> 70*0c4d7b72SSadaf Ebrahimi 71*0c4d7b72SSadaf Ebrahimi <source> 72*0c4d7b72SSadaf Ebrahimi InputStream in = new URL( "https://commons.apache.org" ).openStream(); 73*0c4d7b72SSadaf Ebrahimi try { 74*0c4d7b72SSadaf Ebrahimi System.out.println( IOUtils.toString( in ) ); 75*0c4d7b72SSadaf Ebrahimi } finally { 76*0c4d7b72SSadaf Ebrahimi IOUtils.closeQuietly(in); 77*0c4d7b72SSadaf Ebrahimi }</source> 78*0c4d7b72SSadaf Ebrahimi 79*0c4d7b72SSadaf Ebrahimi <p> 80*0c4d7b72SSadaf Ebrahimi In certain application domains, such IO operations are 81*0c4d7b72SSadaf Ebrahimi common, and this class can save a great deal of time. And you can 82*0c4d7b72SSadaf Ebrahimi rely on well-tested code. 83*0c4d7b72SSadaf Ebrahimi </p> 84*0c4d7b72SSadaf Ebrahimi <p> 85*0c4d7b72SSadaf Ebrahimi For utility code such as this, flexibility and speed are of primary importance. 86*0c4d7b72SSadaf Ebrahimi However you should also understand the limitations of this approach. 87*0c4d7b72SSadaf Ebrahimi Using the above technique to read a 1GB file would result in an 88*0c4d7b72SSadaf Ebrahimi attempt to create a 1GB String object! 89*0c4d7b72SSadaf Ebrahimi </p> 90*0c4d7b72SSadaf Ebrahimi 91*0c4d7b72SSadaf Ebrahimi </subsection> 92*0c4d7b72SSadaf Ebrahimi 93*0c4d7b72SSadaf Ebrahimi <subsection name="FileUtils"> 94*0c4d7b72SSadaf Ebrahimi <p> 95*0c4d7b72SSadaf Ebrahimi The <a href="apidocs/index.html?org/apache/commons/io/FileUtils.html">FileUtils</a> 96*0c4d7b72SSadaf Ebrahimi class contains utility methods for working with File objects. 97*0c4d7b72SSadaf Ebrahimi These include reading, writing, copying and comparing files. 98*0c4d7b72SSadaf Ebrahimi </p> 99*0c4d7b72SSadaf Ebrahimi <p> 100*0c4d7b72SSadaf Ebrahimi For example to read an entire file line by line you could use: 101*0c4d7b72SSadaf Ebrahimi </p> 102*0c4d7b72SSadaf Ebrahimi <source> 103*0c4d7b72SSadaf Ebrahimi File file = new File("/commons/io/project.properties"); 104*0c4d7b72SSadaf Ebrahimi List lines = FileUtils.readLines(file, "UTF-8");</source> 105*0c4d7b72SSadaf Ebrahimi </subsection> 106*0c4d7b72SSadaf Ebrahimi 107*0c4d7b72SSadaf Ebrahimi <subsection name="FilenameUtils"> 108*0c4d7b72SSadaf Ebrahimi <p> 109*0c4d7b72SSadaf Ebrahimi The <a href="apidocs/index.html?org/apache/commons/io/FilenameUtils.html">FilenameUtils</a> 110*0c4d7b72SSadaf Ebrahimi class contains utility methods for working with filenames <i>without</i> 111*0c4d7b72SSadaf Ebrahimi using File objects. The class aims to be consistent 112*0c4d7b72SSadaf Ebrahimi between Unix and Windows, to aid transitions between these 113*0c4d7b72SSadaf Ebrahimi environments (such as moving from development to production). 114*0c4d7b72SSadaf Ebrahimi </p> 115*0c4d7b72SSadaf Ebrahimi <p> 116*0c4d7b72SSadaf Ebrahimi For example to normalize a filename removing double dot segments: 117*0c4d7b72SSadaf Ebrahimi </p> 118*0c4d7b72SSadaf Ebrahimi <source> 119*0c4d7b72SSadaf Ebrahimi String filename = "C:/commons/io/../lang/project.xml"; 120*0c4d7b72SSadaf Ebrahimi String normalized = FilenameUtils.normalize(filename); 121*0c4d7b72SSadaf Ebrahimi // result is "C:/commons/lang/project.xml"</source> 122*0c4d7b72SSadaf Ebrahimi </subsection> 123*0c4d7b72SSadaf Ebrahimi 124*0c4d7b72SSadaf Ebrahimi <subsection name="FileSystemUtils"> 125*0c4d7b72SSadaf Ebrahimi <p> 126*0c4d7b72SSadaf Ebrahimi The <a href="apidocs/index.html?org/apache/commons/io/FileSystemUtils.html">FileSystemUtils</a> 127*0c4d7b72SSadaf Ebrahimi class contains 128*0c4d7b72SSadaf Ebrahimi utility methods for working with the file system 129*0c4d7b72SSadaf Ebrahimi to access functionality not supported by the JDK. 130*0c4d7b72SSadaf Ebrahimi Currently, the only method is to get the free space on a drive. 131*0c4d7b72SSadaf Ebrahimi Note that this uses the command line, not native code. 132*0c4d7b72SSadaf Ebrahimi </p> 133*0c4d7b72SSadaf Ebrahimi <p> 134*0c4d7b72SSadaf Ebrahimi For example to find the free space on a drive: 135*0c4d7b72SSadaf Ebrahimi </p> 136*0c4d7b72SSadaf Ebrahimi <source> 137*0c4d7b72SSadaf Ebrahimi long freeSpace = FileSystemUtils.freeSpace("C:/");</source> 138*0c4d7b72SSadaf Ebrahimi </subsection> 139*0c4d7b72SSadaf Ebrahimi 140*0c4d7b72SSadaf Ebrahimi </section> 141*0c4d7b72SSadaf Ebrahimi 142*0c4d7b72SSadaf Ebrahimi <section name="Endian classes"> 143*0c4d7b72SSadaf Ebrahimi <p> 144*0c4d7b72SSadaf Ebrahimi Different computer architectures adopt different 145*0c4d7b72SSadaf Ebrahimi conventions for byte ordering. In so-called 146*0c4d7b72SSadaf Ebrahimi "Little Endian" architectures (eg Intel), the low-order 147*0c4d7b72SSadaf Ebrahimi byte is stored in memory at the lowest address, and 148*0c4d7b72SSadaf Ebrahimi subsequent bytes at higher addresses. For "Big Endian" 149*0c4d7b72SSadaf Ebrahimi architectures (eg Motorola), the situation is reversed. 150*0c4d7b72SSadaf Ebrahimi </p> 151*0c4d7b72SSadaf Ebrahimi 152*0c4d7b72SSadaf Ebrahimi <p> 153*0c4d7b72SSadaf Ebrahimi There are two classes in this package of relevance: 154*0c4d7b72SSadaf Ebrahimi </p> 155*0c4d7b72SSadaf Ebrahimi 156*0c4d7b72SSadaf Ebrahimi <ul> 157*0c4d7b72SSadaf Ebrahimi <li> 158*0c4d7b72SSadaf Ebrahimi The <a href="apidocs/index.html?org/apache/commons/io/EndianUtils.html">EndianUtils</a> 159*0c4d7b72SSadaf Ebrahimi class contains static methods for swapping the Endian-ness 160*0c4d7b72SSadaf Ebrahimi of Java primitives and streams. 161*0c4d7b72SSadaf Ebrahimi </li> 162*0c4d7b72SSadaf Ebrahimi 163*0c4d7b72SSadaf Ebrahimi <li> 164*0c4d7b72SSadaf Ebrahimi The <a href="apidocs/index.html?org/apache/commons/io/input/SwappedDataInputStream.html">SwappedDataInputStream</a> 165*0c4d7b72SSadaf Ebrahimi class is an implementation of the <code>DataInput</code> interface. With 166*0c4d7b72SSadaf Ebrahimi this, one can read data from files of non-native Endian-ness. 167*0c4d7b72SSadaf Ebrahimi </li> 168*0c4d7b72SSadaf Ebrahimi </ul> 169*0c4d7b72SSadaf Ebrahimi 170*0c4d7b72SSadaf Ebrahimi <p> 171*0c4d7b72SSadaf Ebrahimi For more information, see 172*0c4d7b72SSadaf Ebrahimi <a 173*0c4d7b72SSadaf Ebrahimi href="http://www.cs.umass.edu/~verts/cs32/endian.html">http://www.cs.umass.edu/~verts/cs32/endian.html</a> 174*0c4d7b72SSadaf Ebrahimi </p> 175*0c4d7b72SSadaf Ebrahimi 176*0c4d7b72SSadaf Ebrahimi </section> 177*0c4d7b72SSadaf Ebrahimi 178*0c4d7b72SSadaf Ebrahimi <section name="Line iterator"> 179*0c4d7b72SSadaf Ebrahimi <p> 180*0c4d7b72SSadaf Ebrahimi The <code>org.apache.commons.io.LineIterator</code> class 181*0c4d7b72SSadaf Ebrahimi provides a flexible way for working with a line-based file. 182*0c4d7b72SSadaf Ebrahimi An instance can be created directly, or via factory methods on 183*0c4d7b72SSadaf Ebrahimi <code>FileUtils</code> or <code>IOUtils</code>. 184*0c4d7b72SSadaf Ebrahimi The recommended usage pattern is: 185*0c4d7b72SSadaf Ebrahimi </p> 186*0c4d7b72SSadaf Ebrahimi <source> 187*0c4d7b72SSadaf Ebrahimi LineIterator it = FileUtils.lineIterator(file, "UTF-8"); 188*0c4d7b72SSadaf Ebrahimi try { 189*0c4d7b72SSadaf Ebrahimi while (it.hasNext()) { 190*0c4d7b72SSadaf Ebrahimi String line = it.nextLine(); 191*0c4d7b72SSadaf Ebrahimi /// do something with line 192*0c4d7b72SSadaf Ebrahimi } 193*0c4d7b72SSadaf Ebrahimi } finally { 194*0c4d7b72SSadaf Ebrahimi LineIterator.closeQuietly(iterator); 195*0c4d7b72SSadaf Ebrahimi }</source> 196*0c4d7b72SSadaf Ebrahimi </section> 197*0c4d7b72SSadaf Ebrahimi 198*0c4d7b72SSadaf Ebrahimi <section name="File filters"> 199*0c4d7b72SSadaf Ebrahimi <p> 200*0c4d7b72SSadaf Ebrahimi The <code>org.apache.commons.io.filefilter</code> 201*0c4d7b72SSadaf Ebrahimi package defines an interface 202*0c4d7b72SSadaf Ebrahimi (<a href="apidocs/index.html?org/apache/commons/io/filefilter/IOFileFilter.html">IOFileFilter</a>) 203*0c4d7b72SSadaf Ebrahimi that combines both <code>java.io.FileFilter</code> and 204*0c4d7b72SSadaf Ebrahimi <code>java.io.FilenameFilter</code>. Besides 205*0c4d7b72SSadaf Ebrahimi that the package offers a series of ready-to-use 206*0c4d7b72SSadaf Ebrahimi implementations of the <code>IOFileFilter</code> 207*0c4d7b72SSadaf Ebrahimi interface including 208*0c4d7b72SSadaf Ebrahimi implementation that allow you to combine other such filters. 209*0c4d7b72SSadaf Ebrahimi 210*0c4d7b72SSadaf Ebrahimi These filters can be used to list files or in FileDialog, for example. 211*0c4d7b72SSadaf Ebrahimi </p> 212*0c4d7b72SSadaf Ebrahimi <p> 213*0c4d7b72SSadaf Ebrahimi See the 214*0c4d7b72SSadaf Ebrahimi <a href="apidocs/index.html?org/apache/commons/io/filefilter/package-summary.html">filefilter</a> 215*0c4d7b72SSadaf Ebrahimi package javadoc for more details. 216*0c4d7b72SSadaf Ebrahimi </p> 217*0c4d7b72SSadaf Ebrahimi </section> 218*0c4d7b72SSadaf Ebrahimi 219*0c4d7b72SSadaf Ebrahimi <section name="File comparators"> 220*0c4d7b72SSadaf Ebrahimi <p> 221*0c4d7b72SSadaf Ebrahimi The <code>org.apache.commons.io.comparator</code> 222*0c4d7b72SSadaf Ebrahimi package provides a number of <code>java.util.Comparator</code> 223*0c4d7b72SSadaf Ebrahimi implementations for <code>java.io.File</code>. 224*0c4d7b72SSadaf Ebrahimi 225*0c4d7b72SSadaf Ebrahimi These comparators can be used to sort lists and arrays of files, for example. 226*0c4d7b72SSadaf Ebrahimi </p> 227*0c4d7b72SSadaf Ebrahimi <p> 228*0c4d7b72SSadaf Ebrahimi See the 229*0c4d7b72SSadaf Ebrahimi <a href="apidocs/index.html?org/apache/commons/io/comparator/package-summary.html">comparator</a> 230*0c4d7b72SSadaf Ebrahimi package javadoc for more details. 231*0c4d7b72SSadaf Ebrahimi </p> 232*0c4d7b72SSadaf Ebrahimi </section> 233*0c4d7b72SSadaf Ebrahimi 234*0c4d7b72SSadaf Ebrahimi <section name="Streams"> 235*0c4d7b72SSadaf Ebrahimi <p> 236*0c4d7b72SSadaf Ebrahimi The <code>org.apache.commons.io.input</code> and 237*0c4d7b72SSadaf Ebrahimi <code>org.apache.commons.io.output</code> packages 238*0c4d7b72SSadaf Ebrahimi contain various useful implementations of streams. 239*0c4d7b72SSadaf Ebrahimi These include: 240*0c4d7b72SSadaf Ebrahimi <ul> 241*0c4d7b72SSadaf Ebrahimi <li>Null output stream - that silently absorbs all data sent to it</li> 242*0c4d7b72SSadaf Ebrahimi <li>Tee output stream - that sends output data to two streams instead of one</li> 243*0c4d7b72SSadaf Ebrahimi <li>Byte array output stream - that is a faster version of the JDK class</li> 244*0c4d7b72SSadaf Ebrahimi <li>Counting streams - that count the number of bytes passed</li> 245*0c4d7b72SSadaf Ebrahimi <li>Proxy streams - that delegate to the correct method in the proxy</li> 246*0c4d7b72SSadaf Ebrahimi <li>Lockable writer - that provides synchronization of writes using a lock file</li> 247*0c4d7b72SSadaf Ebrahimi </ul> 248*0c4d7b72SSadaf Ebrahimi </p> 249*0c4d7b72SSadaf Ebrahimi <p> 250*0c4d7b72SSadaf Ebrahimi See the 251*0c4d7b72SSadaf Ebrahimi <a href="apidocs/index.html?org/apache/commons/io/input/package-summary.html">input</a> or 252*0c4d7b72SSadaf Ebrahimi <a href="apidocs/index.html?org/apache/commons/io/output/package-summary.html">output</a> 253*0c4d7b72SSadaf Ebrahimi package javadoc for more details. 254*0c4d7b72SSadaf Ebrahimi </p> 255*0c4d7b72SSadaf Ebrahimi </section> 256*0c4d7b72SSadaf Ebrahimi 257*0c4d7b72SSadaf Ebrahimi </body> 258*0c4d7b72SSadaf Ebrahimi 259*0c4d7b72SSadaf Ebrahimi</document> 260