|
| 1 | +<?xml version="1.0"?> |
| 2 | +<!-- |
| 3 | +Licensed to the Apache Software Foundation (ASF) under one or more |
| 4 | +contributor license agreements. See the NOTICE file distributed with |
| 5 | +this work for additional information regarding copyright ownership. |
| 6 | +The 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 |
| 8 | +the License. You may obtain a copy of the License at |
| 9 | +
|
| 10 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | +
|
| 12 | +Unless required by applicable law or agreed to in writing, software |
| 13 | +distributed under the License is distributed on an "AS IS" BASIS, |
| 14 | +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 15 | +See the License for the specific language governing permissions and |
| 16 | +limitations under the License. |
| 17 | +--> |
| 18 | +<document> |
| 19 | + <properties> |
| 20 | + <title>Upgrade from 1.2 to 1.3</title> |
| 21 | + <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author> |
| 22 | + </properties> |
| 23 | +<body> |
| 24 | + |
| 25 | +<section name="Upgrade"> |
| 26 | +<p> |
| 27 | +These are the release notes and advice for upgrading Commons-IO from |
| 28 | +version 1.2 to version 1.3. |
| 29 | +<source> |
| 30 | +Commons IO is a package of Java utility classes for java.io's hierarchy. |
| 31 | +Classes in this package are considered to be so standard and of such high |
| 32 | +reuse as to justify existence in java.io. |
| 33 | + |
| 34 | +Commons IO contains utility classes, stream implementations, file filters, |
| 35 | +and endian transformation classes. |
| 36 | + |
| 37 | + |
| 38 | +Compatibility with 1.2 |
| 39 | +---------------------- |
| 40 | +Binary compatible - Yes |
| 41 | + |
| 42 | +Source compatible - Yes |
| 43 | + |
| 44 | +Semantic compatible - Yes |
| 45 | + Check the bug fixes section for semantic bug fixes |
| 46 | + |
| 47 | + |
| 48 | +Deprecations 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 | + |
| 60 | +Bug 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 throws 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 innacurate 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 | + |
| 109 | +Enhancements 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 behaviour, 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 calback 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> |
0 commit comments