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>Upgrade from 1.2 to 1.3</title> 21 <author email="[email protected]">Commons Documentation Team</author> 22 </properties> 23<body> 24 25<section name="Upgrade"> 26<p> 27These are the release notes and advice for upgrading Commons-IO from 28version 1.2 to version 1.3. 29<source> 30Commons IO is a package of Java utility classes for java.io's hierarchy. 31Classes in this package are considered to be so standard and of such high 32reuse as to justify existence in java.io. 33 34Commons IO contains utility classes, stream implementations, file filters, 35and endian transformation classes. 36 37 38Compatibility with 1.2 39---------------------- 40Binary compatible - Yes 41 42Source compatible - Yes 43 44Semantic compatible - Yes 45 Check the bug fixes section for semantic bug fixes 46 47 48Deprecations from 1.2 49--------------------- 50- WildcardFilter deprecated, replaced by WildcardFileFilter 51 - old class only accepted files, thus had a confusing dual purpose 52 53- FileSystemUtils.freeSpace deprecated, replaced by freeSpaceKb 54 - freeSpace returns a result that varies by operating system and 55 thus isn't that useful 56 - freeSpaceKb returns much better and more consistent results 57 - freeSpaceKb existed in v1.2, so this is a gentle cutover 58 59 60Bug fixes from 1.2 61------------------ 62- LineIterator now implements Iterator 63 - It was always supposed to... 64 65- FileSystemUtils.freeSpace/freeSpaceKb [IO-83] 66 - These should now work on AIX and HP-UX 67 68- FileSystemUtils.freeSpace/freeSpaceKb [IO-90] 69 - Avoid infinite looping in Windows 70 - Catch more errors with nice messages 71 72- FileSystemUtils.freeSpace [IO-91] 73 - This is now documented not to work on SunOS 5 74 75- FileSystemUtils [IO-93] 76 - Fixed resource leak leading to 'Too many open files' error 77 - Previously did not destroy Process instances (as JDK Javadoc is so poor) 78 - http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4801027 79 80- FileUtils.touch [IO-100] 81 - The touch method previously gave no indication when the file could not 82 be touched successfully (such as due to access restrictions) - it now 83 throws an IOException if the last modified date cannot be changed 84 85- FileCleaner 86 - This now handles the situation where an error occurs when deleting the file 87 88- IOUtils.copy [IO-84] 89 - Copy methods could return inaccurate byte/char count for large streams 90 - The copy(InputStream, OutputStream) method now returns -1 if the count is greater than an int 91 - The copy(Reader, Writer) method now returns -1 if the count is greater than an int 92 - Added a new copyLarge(InputStream, OutputStream) method that returns a long 93 - Added a new copyLarge(Reader, Writer) method that returns a long 94 95- CountingInputStream/CountingOutputStream [IO-84] 96 - Methods were declared as int thus the count was inaccurate for large streams 97 - new long based methods getByteCount()/resetByteCount() added 98 - existing methods changed to throw an exception if the count is greater than an int 99 100- FileBasedTestCase 101 - Fixed bug in compare content methods identified by GNU classpath 102 103- EndianUtils.writeSwappedLong(byte[], int) [IO-101] 104 - An int overrun in the bit shifting when it should have been a long 105 106- EndianUtils.writeSwappedLong(InputStream) [IO-102] 107 - The return of input.read(byte[]) was not being checked to ensure all 8 bytes were read 108 109Enhancements from 1.2 110--------------------- 111- DirectoryWalker [IO-86] 112 - New class designed for subclassing to walk through a set of files. 113 DirectoryWalker provides the walk of the directories, filtering of 114 directories and files, and cancellation support. The subclass must provide 115 the specific behavior, such as text searching or image processing. 116 117- IOCase 118 - New class/enumeration for case-sensitivity control 119 120- FilenameUtils 121 - New methods to handle case-sensitivity 122 - wildcardMatch - new method that has IOCase as a parameter 123 - equals - new method that has IOCase as a parameter 124 125- FileUtils [IO-108] - new default encoding methods for: 126 - readFileToString(File) 127 - readLines(File) 128 - lineIterator(File) 129 - writeStringToFile(File, String) 130 - writeLines(File, Collection) 131 - writeLines(File, Collection, String) 132 133- FileUtils.openOutputStream [IO-107] 134 - new method to open a FileOutputStream, creating parent directories if required 135- FileUtils.touch 136- FileUtils.copyURLToFile 137- FileUtils.writeStringToFile 138- FileUtils.writeByteArrayToFile 139- FileUtils.writeLines 140 - enhanced to create parent directories if required 141- FileUtils.openInputStream [IO-107] 142 - new method to open a FileInputStream, providing better error messages than the JDK 143 144- FileUtils.isFileOlder 145 - new methods to check if a file is older (i.e. isFileOlder()) - counterparts 146 to the existing isFileNewer() methods. 147 148- FileUtils.checksum, FileUtils.checksumCRC32 149 - new methods to create a checksum of a file 150 151- FileUtils.copyFileToDirectory [IO-104] 152 - new variant that optionally retains the file date 153 154- FileDeleteStrategy 155- FileCleaner [IO-56,IO-70] 156 - FileDeleteStrategy is a strategy for handling file deletion 157 - This can be used as a callback in FileCleaner 158 - Together these allow FileCleaner to do a forceDelete to kill directories 159 160- FileCleaner.exitWhenFinished [IO-99] 161 - A new method that allows the internal cleaner thread to be cleanly terminated 162 163- WildcardFileFilter 164 - Replacement for WildcardFilter 165 - Accepts both files and directories 166 - Ability to control case-sensitivity 167 168- NameFileFilter 169 - Ability to control case-sensitivity 170 171- FileFileFilter 172 - New IOFileFilter implementation 173 - Accepts files where File.isFile() is true 174 - In other words it filters out directories 175 - Singleton instance provided (FILE) 176 177- CanReadFileFilter 178 - New IOFileFilter implementation 179 - Accepts files where File.canRead() is true 180 - Singleton instances provided (CAN_READ/CANNOT_READ/READ_ONLY) 181 182- CanWriteFileFilter 183 - New IOFileFilter implementation 184 - Accepts files where File.canWrite() is true 185 - Singleton instances provided (CAN_WRITE/CANNOT_WRITE) 186 187- HiddenFileFilter 188 - New IOFileFilter implementation 189 - Accepts files where File.isHidden() is true 190 - Singleton instances provided (HIDDEN/VISIBLE) 191 192- EmptyFileFilter 193 - New IOFileFilter implementation 194 - Accepts files or directories that are empty 195 - Singleton instances provided (EMPTY/NOT_EMPTY) 196 197- TrueFileFilter/FalseFileFilter/DirectoryFileFilter 198 - New singleton instance constants (TRUE/FALSE/DIRECTORY) 199 - The new constants are more JDK 1.5 friendly with regards to static imports 200 (whereas if everything uses INSTANCE, then they just clash) 201 - The old INSTANCE constants are still present and have not been deprecated 202 203- FileFilterUtils.sizeRangeFileFilter 204 - new sizeRangeFileFilter(long minimumSize, long maximumSize) method which 205 creates a filter that accepts files within the specified size range. 206 207- FileFilterUtils.makeDirectoryOnly/makeFileOnly 208 - two new methods that decorate a file filter to make it apply to 209 directories only or files only 210 211- NullWriter 212 - New writer that acts as a sink for all data, as per /dev/null 213 214- NullInputStream 215 - New input stream that emulates a stream of a specified size 216 217- NullReader 218 - New reader that emulates a reader of a specified size 219 220- ByteArrayOutputStream [IO-97] 221 - Performance enhancements 222 223</source> 224</p> 225</section> 226 227</body> 228</document> 229