Skip to content

Commit ca59df8

Browse files
author
Niall Pemberton
committed
JavaDoc improvements
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/io/trunk@1005099 13f79535-47bb-0310-9956-ffa450edef68
1 parent ede1a5e commit ca59df8

21 files changed

Lines changed: 249 additions & 10 deletions

‎src/main/java/org/apache/commons/io/ByteOrderMark.java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@
1919
import java.io.Serializable;
2020

2121
/**
22-
* Byte Order Mark (BOM) representation.
22+
* Byte Order Mark (BOM) representation -
23+
* see {@link org.apache.commons.io.input.BOMInputStream}.
2324
*
2425
* @see org.apache.commons.io.input.BOMInputStream
2526
* @see <a href="http://en.wikipedia.org/wiki/Byte_order_mark">Wikipedia - Byte Order Mark</a>

‎src/main/java/org/apache/commons/io/comparator/DirectoryFileComparator.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
import java.util.Comparator;
2222

2323
/**
24-
* Compare two files using the <b>default</b> {@link File#isDirectory()} method.
24+
* Compare two files using the {@link File#isDirectory()} method.
2525
* <p>
2626
* This comparator can be used to sort lists or arrays by directories and files.
2727
* <p>

‎src/main/java/org/apache/commons/io/comparator/package.html‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,169 @@
2020
<p>This package provides various {@link java.util.Comparator} implementations
2121
for {@link java.io.File}s.
2222
</p>
23+
<h3>Sorting</h3>
24+
<p>
25+
All the compartors include <i>convenience</i> utility <code>sort(File...)</code> and
26+
<code>sort(List)</code> methods.
27+
</p>
28+
<p>
29+
For example, to sort the files in a directory by name:
30+
</p>
31+
<pre>
32+
File[] files = dir.listFiles();
33+
NameFileComparator.NAME_COMPARATOR.sort(files);
34+
</pre>
35+
<p>
36+
...alternatively you can do this in one line:
37+
</p>
38+
<p>
39+
<pre>
40+
File[] files = NameFileComparator.NAME_COMPARATOR.sort(dir.listFiles());
41+
</pre>
42+
</p>
43+
44+
<h3>Composite Comparator</h3>
45+
<p>
46+
The <a href="CompositeFileComparator.html">CompositeFileComparator</a> can be used
47+
to compare (and sort lists or arrays of files) by combining a number other comparators.
48+
</p>
49+
<p>
50+
For example, to sort an array of files by type (i.e. directory or file)
51+
and then by name:
52+
</p>
53+
<p>
54+
<pre>
55+
CompositeFileComparator comparator =
56+
new CompositeFileComparator(
57+
DirectoryFileComparator.DIRECTORY_COMPARATOR,
58+
NameFileComparator.NAME_COMPARATOR);
59+
File[] files = dir.listFiles();
60+
comparator.sort(files);
61+
</pre>
62+
</p>
63+
64+
<h3>Singleton Instances (thread-safe)</h3>
65+
<p>
66+
The {@link java.util.Comparator} implementations have some <i>convenience</i>
67+
singleton(<i>thread-safe</i>) instances ready to use:
68+
<ul>
69+
<li><a href="DefaultFileComparator.html">DefaultFileComparator</a> - default file compare:
70+
<ul>
71+
<li><a href="DefaultFileComparator.html#DEFAULT_COMPARATOR">DEFAULT_COMPARATOR</a>
72+
- Compare using <code>File.compareTo(File)</code> method.
73+
</li>
74+
<li><a href="DefaultFileComparator.html#DEFAULT_REVERSE">DEFAULT_REVERSE</a>
75+
- Reverse compare of <code>File.compareTo(File)</code> method.
76+
</li>
77+
</ul>
78+
</li>
79+
<li><a href="DirectoryFileComparator.html">DirectoryFileComparator</a> - compare by type (directory or file):
80+
<ul>
81+
<li><a href="DirectoryFileComparator.html#DIRECTORY_COMPARATOR">DIRECTORY_COMPARATOR</a>
82+
- Compare using <code>File.isDirectory()</code> method (directories < files).
83+
</li>
84+
<li><a href="DirectoryFileComparator.html#DIRECTORY_REVERSE">DIRECTORY_REVERSE</a>
85+
- Reverse compare of <code>File.isDirectory()</code> method (directories > files).
86+
</li>
87+
</ul>
88+
</li>
89+
<li><a href="ExtensionFileComparator.html">ExtensionFileComparator</a> - compare file extenstions:
90+
<ul>
91+
<li><a href="ExtensionFileComparator.html#EXTENSION_COMPARATOR">EXTENSION_COMPARATOR</a>
92+
- Compare using <code>FilenameUtils.getExtension(String)</code> method.
93+
</li>
94+
<li><a href="ExtensionFileComparator.html#EXTENSION_REVERSE">EXTENSION_REVERSE</a>
95+
- Reverse compare of <code>FilenameUtils.getExtension(String)</code> method.
96+
</li>
97+
<li><a href="ExtensionFileComparator.html#EXTENSION_INSENSITIVE_COMPARATOR">EXTENSION_INSENSITIVE_COMPARATOR</a>
98+
- Case-insensitive compare using <code>FilenameUtils.getExtension(String)</code> method.
99+
</li>
100+
<li><a href="ExtensionFileComparator.html#EXTENSION_INSENSITIVE_REVERSE">EXTENSION_INSENSITIVE_REVERSE</a>
101+
- Reverse case-insensitive compare of <code>FilenameUtils.getExtension(String)</code> method.
102+
</li>
103+
<li><a href="ExtensionFileComparator.html#EXTENSION_SYSTEM_COMPARATOR">EXTENSION_SYSTEM_COMPARATOR</a>
104+
- System sensitive compare using <code>FilenameUtils.getExtension(String)</code> method.
105+
</li>
106+
<li><a href="ExtensionFileComparator.html#EXTENSION_SYSTEM_REVERSE">EXTENSION_SYSTEM_REVERSE</a>
107+
- Reverse system sensitive compare of <code>FilenameUtils.getExtension(String)</code> method.
108+
</li>
109+
</ul>
110+
</li>
111+
<li><a href="LastModifiedFileComparator.html">LastModifiedFileComparator</a>
112+
- compare the file's last modified date/time:
113+
<ul>
114+
<li><a href="LastModifiedFileComparator.html#LASTMODIFIED_COMPARATOR">LASTMODIFIED_COMPARATOR</a>
115+
- Compare using <code>File.lastModified()</code> method.
116+
</li>
117+
<li><a href="LastModifiedFileComparator.html#LASTMODIFIED_REVERSE">LASTMODIFIED_REVERSE</a>
118+
- Reverse compare of <code>File.lastModified()</code> method.
119+
</li>
120+
</ul>
121+
</li>
122+
<li><a href="NameFileComparator.html">NameFileComparator</a> - compare file names:
123+
<ul>
124+
<li><a href="NameFileComparator.html#NAME_COMPARATOR">NAME_COMPARATOR</a>
125+
- Compare using <code>File.getName()</code> method.
126+
</li>
127+
<li><a href="NameFileComparator.html#NAME_REVERSE">NAME_REVERSE</a>
128+
- Reverse compare of <code>File.getName()</code> method.
129+
</li>
130+
<li><a href="NameFileComparator.html#NAME_INSENSITIVE_COMPARATOR">NAME_INSENSITIVE_COMPARATOR</a>
131+
- Case-insensitive compare using <code>File.getName()</code> method.
132+
</li>
133+
<li><a href="NameFileComparator.html#NAME_INSENSITIVE_REVERSE">NAME_INSENSITIVE_REVERSE</a>
134+
- Reverse case-insensitive compare of <code>File.getName()</code> method.
135+
</li>
136+
<li><a href="NameFileComparator.html#NAME_SYSTEM_COMPARATOR">NAME_SYSTEM_COMPARATOR</a>
137+
- System sensitive compare using <code>File.getName()</code> method.
138+
</li>
139+
<li><a href="NameFileComparator.html#NAME_SYSTEM_REVERSE">NAME_SYSTEM_REVERSE</a>
140+
- Reverse system sensitive compare of <code>File.getName()</code> method.
141+
</li>
142+
</ul>
143+
</li>
144+
<li><a href="PathFileComparator.html">PathFileComparator</a> - compare file paths:
145+
<ul>
146+
<li><a href="PathFileComparator.html#PATH_COMPARATOR">PATH_COMPARATOR</a>
147+
- Compare using <code>File.getPath()</code> method.
148+
</li>
149+
<li><a href="PathFileComparator.html#PATH_REVERSE">PATH_REVERSE</a>
150+
- Reverse compare of <code>File.getPath()</code> method.
151+
</li>
152+
<li><a href="PathFileComparator.html#PATH_INSENSITIVE_COMPARATOR">PATH_INSENSITIVE_COMPARATOR</a>
153+
- Case-insensitive compare using <code>File.getPath()</code> method.
154+
</li>
155+
<li><a href="PathFileComparator.html#PATH_INSENSITIVE_REVERSE">PATH_INSENSITIVE_REVERSE</a>
156+
- Reverse case-insensitive compare of <code>File.getPath()</code> method.
157+
</li>
158+
<li><a href="PathFileComparator.html#PATH_SYSTEM_COMPARATOR">PATH_SYSTEM_COMPARATOR</a>
159+
- System sensitive compare using <code>File.getPath()</code> method.
160+
</li>
161+
<li><a href="PathFileComparator.html#PATH_SYSTEM_REVERSE">PATH_SYSTEM_REVERSE</a>
162+
- Reverse system sensitive compare of <code>File.getPath()</code> method.
163+
</li>
164+
</ul>
165+
</li>
166+
<li><a href="SizeFileComparator.html">SizeFileComparator</a> - compare the file's size:
167+
<ul>
168+
<li><a href="SizeFileComparator.html#SIZE_COMPARATOR">SIZE_COMPARATOR</a>
169+
- Compare using <code>File.length()</code> method (directories treated as zero length).
170+
</li>
171+
<li><a href="SizeFileComparator.html#SIZE_REVERSE">LASTMODIFIED_REVERSE</a>
172+
- Reverse compare of <code>File.length()</code> method (directories treated as zero length).
173+
</li>
174+
<li><a href="SizeFileComparator.html#SIZE_SUMDIR_COMPARATOR">SIZE_SUMDIR_COMPARATOR</a>
175+
- Compare using <code>FileUtils.sizeOfDirectory(File)</code> method
176+
(sums the size of a directory's contents).
177+
</li>
178+
<li><a href="SizeFileComparator.html#SIZE_SUMDIR_REVERSE">SIZE_SUMDIR_REVERSE</a>
179+
- Reverse compare of <code>FileUtils.sizeOfDirectory(File)</code> method
180+
(sums the size of a directory's contents).
181+
</li>
182+
</ul>
183+
</li>
184+
</ul>
185+
</p>
23186

24187
</body>
25188
</html>

‎src/main/java/org/apache/commons/io/filefilter/AgeFileFilter.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,12 @@
4141
*
4242
* @author Rahul Akolkar
4343
* @version $Id$
44+
* @see FileFilterUtils#ageFileFilter(Date)
45+
* @see FileFilterUtils#ageFileFilter(File)
46+
* @see FileFilterUtils#ageFileFilter(long)
47+
* @see FileFilterUtils#ageFileFilter(Date, boolean)
48+
* @see FileFilterUtils#ageFileFilter(File, boolean)
49+
* @see FileFilterUtils#ageFileFilter(long, boolean)
4450
* @since Commons IO 1.2
4551
*/
4652
public class AgeFileFilter extends AbstractFileFilter implements Serializable {

‎src/main/java/org/apache/commons/io/filefilter/AndFileFilter.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
* @version $Revision$ $Date$
3434
*
3535
* @author Steven Caswell
36+
* @see FileFilterUtils#and(IOFileFilter...)
3637
*/
3738
public class AndFileFilter
3839
extends AbstractFileFilter

‎src/main/java/org/apache/commons/io/filefilter/DelegateFileFilter.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@
2828
* @version $Revision$ $Date$
2929
*
3030
* @author Stephen Colebourne
31+
* @see FileFilterUtils#asFileFilter(FileFilter)
32+
* @see FileFilterUtils#asFileFilter(FilenameFilter)
3133
*/
3234
public class DelegateFileFilter extends AbstractFileFilter implements Serializable {
3335

‎src/main/java/org/apache/commons/io/filefilter/DirectoryFileFilter.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
*
3939
* @author Stephen Colebourne
4040
* @author Peter Donald
41+
* @see FileFilterUtils#directoryFileFilter()
4142
*/
4243
public class DirectoryFileFilter extends AbstractFileFilter implements Serializable {
4344

‎src/main/java/org/apache/commons/io/filefilter/FalseFileFilter.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
* @version $Revision$ $Date$
2727
*
2828
* @author Stephen Colebourne
29+
* @see FileFilterUtils#falseFileFilter()
2930
*/
3031
public class FalseFileFilter implements IOFileFilter, Serializable {
3132

‎src/main/java/org/apache/commons/io/filefilter/FileFileFilter.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
*
3636
* @since Commons IO 1.3
3737
* @version $Revision:587916 $ $Date$
38+
* @see FileFilterUtils#fileFileFilter()
3839
*/
3940
public class FileFileFilter extends AbstractFileFilter implements Serializable {
4041

0 commit comments

Comments
 (0)