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
10
http://www.apache.org/licenses/LICENSE-2.0
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.
20
<title>Upgrade from 1.2 to 1.3</title>
21
<author email="dev@commons.apache.org">Commons Documentation Team</author>
25
<section name="Upgrade">
27
These are the release notes and advice for upgrading Commons-IO from
28
version 1.2 to version 1.3.
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.
34
Commons IO contains utility classes, stream implementations, file filters,
35
and endian transformation classes.
38
Compatibility with 1.2
39
----------------------
40
Binary compatible - Yes
42
Source compatible - Yes
44
Semantic compatible - Yes
45
Check the bug fixes section for semantic bug fixes
50
- WildcardFilter deprecated, replaced by WildcardFileFilter
51
- old class only accepted files, thus had a confusing dual purpose
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
62
- LineIterator now implements Iterator
63
- It was always supposed to...
65
- FileSystemUtils.freeSpace/freeSpaceKb [IO-83]
66
- These should now work on AIX and HP-UX
68
- FileSystemUtils.freeSpace/freeSpaceKb [IO-90]
69
- Avoid infinite looping in Windows
70
- Catch more errors with nice messages
72
- FileSystemUtils.freeSpace [IO-91]
73
- This is now documented not to work on SunOS 5
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
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
86
- This now handles the situation where an error occurs when deleting the file
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
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
101
- Fixed bug in compare content methods identified by GNU classpath
103
- EndianUtils.writeSwappedLong(byte[], int) [IO-101]
104
- An int overrun in the bit shifting when it should have been a long
106
- EndianUtils.writeSwappedLong(InputStream) [IO-102]
107
- The return of input.read(byte[]) was not being checked to ensure all 8 bytes were read
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.
118
- New class/enumeration for case-sensitivity control
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
125
- FileUtils [IO-108] - new default encoding methods for:
126
- readFileToString(File)
129
- writeStringToFile(File, String)
130
- writeLines(File, Collection)
131
- writeLines(File, Collection, String)
133
- FileUtils.openOutputStream [IO-107]
134
- new method to open a FileOutputStream, creating parent directories if required
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
144
- FileUtils.isFileOlder
145
- new methods to check if a file is older (i.e. isFileOlder()) - counterparts
146
to the existing isFileNewer() methods.
148
- FileUtils.checksum, FileUtils.checksumCRC32
149
- new methods to create a checksum of a file
151
- FileUtils.copyFileToDirectory [IO-104]
152
- new variant that optionally retains the file date
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
160
- FileCleaner.exitWhenFinished [IO-99]
161
- A new method that allows the internal cleaner thread to be cleanly terminated
164
- Replacement for WildcardFilter
165
- Accepts both files and directories
166
- Ability to control case-sensitivity
169
- Ability to control case-sensitivity
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)
178
- New IOFileFilter implementation
179
- Accepts files where File.canRead() is true
180
- Singleton instances provided (CAN_READ/CANNOT_READ/READ_ONLY)
183
- New IOFileFilter implementation
184
- Accepts files where File.canWrite() is true
185
- Singleton instances provided (CAN_WRITE/CANNOT_WRITE)
188
- New IOFileFilter implementation
189
- Accepts files where File.isHidden() is true
190
- Singleton instances provided (HIDDEN/VISIBLE)
193
- New IOFileFilter implementation
194
- Accepts files or directories that are empty
195
- Singleton instances provided (EMPTY/NOT_EMPTY)
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
203
- FileFilterUtils.sizeRangeFileFilter
204
- new sizeRangeFileFilter(long minimumSize, long maximumSize) method which
205
creates a filter that accepts files within the specified size range.
207
- FileFilterUtils.makeDirectoryOnly/makeFileOnly
208
- two new methods that decorate a file filter to make it apply to
209
directories only or files only
212
- New writer that acts as a sink for all data, as per /dev/null
215
- New input stream that emulates a stream of a specified size
218
- New reader that emulates a reader of a specified size
220
- ByteArrayOutputStream [IO-97]
221
- Performance enhancements
added
removed
xdocs/upgradeto1_3.xml
