[
https://issues.apache.org/jira/browse/IO-222?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
David Armstrong updated IO-222:
-------------------------------
Description:
This is a proposal to add a feature to new releases of Commons IO.
The new functionality is a class that copies files, called FileCopier and some
helper classes. This class goes beyond the functionality of the static methods
included in the FileUtils class. It has the following functionality:
It uses an extension to an abstract class, FileCopyHelper. FileCopyHelper
provides callback methods to FileCopier's copy methods. Extensions to
FileCopyHelper provide methods to define behavior for handling destination
files that exist, handling exceptions, reporting the status of copy operations,
and enables clients to cancel copies after they have begun.
There are several extensions to FileCopyHelper that I have created.
FileCopyHelper and all of its extensions are included in a new package,
org.apache.commons.io.filecopyhelper to avoid cluttering up
org.apache.commons.io. FileCopier uses a default FileCopyHelper extension,
SafeFileCopyHelper. This extension skips all destination files that already
exist. OverwriteFileCopyHelper overwrites all files that exist.
RenameAppendFileCopyHelper appends text to the names of all files that exist.
RenameAppendTimestampFileCopyHelper appends the existing file's last modified
date to its name. There are a few other FileCopyHelper extensions included,
also. All of the FileCopyHelper extensions that I created print the status of
copy operations and report exceptions to standard out. Any behavior of the
included FileCopyHelper extensions that are not wanted can be avoided by
extending FileCopyHelper with custom implementations.
FileCopyHelper also allows clients to send a cancel request to FileCopier to
cancel subsequent copy operations. FIleCopier will throw a runtime exception,
FileCopyCancelException, when it receives a request to cancel copy operations.
When copying directories, FileCopier gives clients the ability to "flatten"
directories if they so choose. They can flatten by directory level or by name,
using an IOFileFilter. Flattening means the directory itself is not copied;
only its contents are copied. It likewise gives clients the ability to "merge"
directories that exist. They can merge directories by level or by name, using
an IOFileFilter. Merge is applicable when FileCopier is using a FileCopyHelper
object that renames destination files that already exist. If a directory is to
be merged, it means that the directory is not renamed. The contents of the
source directory are merged with the contents of the already existing
destination directory. Destination directories that are not to be merged are
renamed. FileCopier's default behavior is to not merge or flatten any
directories.
FileCopier is immutable and uses an inner Builder class to create instances of
it.
I made a small change to FileUtils.java. I changed the access for doCopyFile()
from private to protected so that FileCopier could make use of its
functionality.
Included is a FileCopierTestCase class and all of its tests pass.
I've attached a gzipped tar file of Commons IO with the changes I made. If you
generate javadocs, it should create them for the classes I introduced.
Hopefully, they will answer any questions about the functionality that I did
not address here.
Also attached is a diff file of the project's source code after I svn added my
source code.
The estimate I put for this effort is 8 hours, just for the time that would be
spent deciding whether or not to implement the new feature and possibly any
changes that should be made to it.
Please let me know what you think of the new functionality and any suggestions
for improvement that you have. If there is anything that I added that you would
like me to implement differently, please let me know. I hope that you will
agree that FileCopier will provide added value to the Commons IO suite of
services.
Best Regards,
David Armstrong
was:
This is a proposal to add a feature to new releases of Commons IO.
The new functionality is a class that copies files, called FileCopier and some
helper classes. This class goes beyond the functionality of the static methods
included in the FileUtils class. It has the following functionality:
It uses an extension to an abstract class, FileCopyHelper. FileCopyHelper
provides callback methods to FileCopier's copy methods. Extensions to
FileCopyHelper provide methods to define behavior for handling destination
files that exist, handling exceptions, reporting the status of copy operations,
and enables clients to cancel copies after they have begun.
There are several extensions to FileCopyHelper that I have created.
FileCopyHelper and all of its extensions are included in a new package,
org.apache.commons.io.filecopyhelper to avoid cluttering up
org.apache.commons.io. FileCopier uses a default FileCopyHelper extension,
SafeFileCopyHelper. This extension skips all destination files that already
exist. OverwriteFileCopyHelper overwrites all files that exist.
RenameAppendFileCopyHelper appends text to the names of all files that exist.
RenameAppendTimestampFileCopyHelper appends the existing file's last modified
date to its name. There are a few other FileCopyHelper extensions included,
also. All of the FileCopyHelper extensions that I created print the status of
copy operations and report exceptions to standard out.
FileCopyHelper also allows clients to send a cancel request to FileCopier to
cancel subsequent copy operations. FIleCopier will throw a runtime exception,
FileCopyCancelException, when it receives a request to cancel copy operations.
When copying directories, FileCopier gives clients the ability to "flatten"
directories if they so choose. They can flatten by directory level or by name,
using an IOFileFilter. Flattening means the directory itself is not copied;
only its contents are copied. It likewise gives clients the ability to "merge"
directories that exist. They can merge directories by level or by name, using
an IOFileFilter. Merge is applicable when FileCopier is using a FileCopyHelper
object that renames destination files that already exist. If a directory is to
be merged, it means that the directory is not renamed. The contents of the
source directory are merged with the contents of the already existing
destination directory. Destination directories that are not to be merged are
renamed. FileCopier's default behavior is to not merge or flatten any
directories.
FileCopier is immutable and uses an inner Builder class to create instances of
it.
I made a small change to FileUtils.java. I changed the access for doCopyFile()
from private to protected so that FileCopier could make use of its
functionality.
Included is a FileCopierTestCase class and all of its tests pass.
I've attached a gzipped tar file of Commons IO with the changes I made. If you
generate javadocs, it should create them for the classes I introduced.
Hopefully, they will answer any questions about the functionality that I did
not address here.
Also attached is a diff file of the project's source code after I svn added my
source code.
The estimate I put for this effort is 8 hours, just for the time that would be
spent deciding whether or not to implement the new feature and possibly any
changes that should be made to it.
Please let me know what you think of the new functionality and any suggestions
for improvement that you have. If there is anything that I added that you would
like me to implement differently, please let me know. I hope that you will
agree that FileCopier will provide added value to the Commons IO suite of
services.
Best Regards,
David Armstrong
> New Functionality: FileCopier object to facilitate copying of files and
> directories with ability to customize treatment of existing destination files
> and report copy status
> ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
>
> Key: IO-222
> URL: https://issues.apache.org/jira/browse/IO-222
> Project: Commons IO
> Issue Type: New Feature
> Components: Utilities
> Affects Versions: 2.0
> Environment: any
> Reporter: David Armstrong
> Priority: Minor
> Fix For: 2.0
>
> Attachments: commons-io-1.5-SNAPSHOT-javadocs.tar.gz,
> commons-io-1.5-SNAPSHOT.diff, commons-io-1.5-SNAPSHOT.tar.gz
>
> Original Estimate: 8h
> Remaining Estimate: 8h
>
> This is a proposal to add a feature to new releases of Commons IO.
> The new functionality is a class that copies files, called FileCopier and
> some helper classes. This class goes beyond the functionality of the static
> methods included in the FileUtils class. It has the following functionality:
> It uses an extension to an abstract class, FileCopyHelper. FileCopyHelper
> provides callback methods to FileCopier's copy methods. Extensions to
> FileCopyHelper provide methods to define behavior for handling destination
> files that exist, handling exceptions, reporting the status of copy
> operations, and enables clients to cancel copies after they have begun.
> There are several extensions to FileCopyHelper that I have created.
> FileCopyHelper and all of its extensions are included in a new package,
> org.apache.commons.io.filecopyhelper to avoid cluttering up
> org.apache.commons.io. FileCopier uses a default FileCopyHelper extension,
> SafeFileCopyHelper. This extension skips all destination files that already
> exist. OverwriteFileCopyHelper overwrites all files that exist.
> RenameAppendFileCopyHelper appends text to the names of all files that exist.
> RenameAppendTimestampFileCopyHelper appends the existing file's last modified
> date to its name. There are a few other FileCopyHelper extensions included,
> also. All of the FileCopyHelper extensions that I created print the status of
> copy operations and report exceptions to standard out. Any behavior of the
> included FileCopyHelper extensions that are not wanted can be avoided by
> extending FileCopyHelper with custom implementations.
> FileCopyHelper also allows clients to send a cancel request to FileCopier to
> cancel subsequent copy operations. FIleCopier will throw a runtime exception,
> FileCopyCancelException, when it receives a request to cancel copy operations.
> When copying directories, FileCopier gives clients the ability to "flatten"
> directories if they so choose. They can flatten by directory level or by
> name, using an IOFileFilter. Flattening means the directory itself is not
> copied; only its contents are copied. It likewise gives clients the ability
> to "merge" directories that exist. They can merge directories by level or by
> name, using an IOFileFilter. Merge is applicable when FileCopier is using a
> FileCopyHelper object that renames destination files that already exist. If a
> directory is to be merged, it means that the directory is not renamed. The
> contents of the source directory are merged with the contents of the already
> existing destination directory. Destination directories that are not to be
> merged are renamed. FileCopier's default behavior is to not merge or flatten
> any directories.
> FileCopier is immutable and uses an inner Builder class to create instances
> of it.
> I made a small change to FileUtils.java. I changed the access for
> doCopyFile() from private to protected so that FileCopier could make use of
> its functionality.
> Included is a FileCopierTestCase class and all of its tests pass.
> I've attached a gzipped tar file of Commons IO with the changes I made. If
> you generate javadocs, it should create them for the classes I introduced.
> Hopefully, they will answer any questions about the functionality that I did
> not address here.
> Also attached is a diff file of the project's source code after I svn added
> my source code.
> The estimate I put for this effort is 8 hours, just for the time that would
> be spent deciding whether or not to implement the new feature and possibly
> any changes that should be made to it.
> Please let me know what you think of the new functionality and any
> suggestions for improvement that you have. If there is anything that I added
> that you would like me to implement differently, please let me know. I hope
> that you will agree that FileCopier will provide added value to the Commons
> IO suite of services.
> Best Regards,
> David Armstrong
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
