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