com.topcoder.file.split
Class FileSplitter

java.lang.Object
  com.topcoder.file.split.FileSplitter

public class FileSplitter
extends java.lang.Object

This class facilitates splitting a file into multiple smaller files. This may be useful when an application must store or transmit a very large file, and storage or transmission of a single large file is undesirable or impossible.

Methods here provide a means to:

• split a file into a fixed number of smaller files
• split a file into files of a given size

The pieces can be rejoined with a FileJoiner object. In addition, one can specify the format of the filename for each of the generated smaller files, and also the directoy in which they are created.

The first split file also contains a header with metadata:

• Signature identifying this as a split file: the four character sequence "SPLT" encoded with UTF-8 encoding (four bytes)
• Major and minor format version (each one unsigned byte)
• Length of the rest of the header (unsigned big-endian four-byte value)
• Length of original file name (unsigned big-endian two-byte value)
• Original file name without path (UTF-8 encoding)
• Length of the split format string (unsigned big-endian two-byte value)
• Split format string (UTF-8 encoding)
• Number of split files (unsigned big-endian two-byte value)

Version:

1.0

Author:

srowen, npe

Field Summary

static java.text.MessageFormat

DEFAULT_SPLIT_FILE_NAME_FORMAT Default split file name message format: {0}.{1}.

Constructor Summary

FileSplitter(java.io.File originalFile)
Creates a FileSplitter for splitting the given File.

FileSplitter(java.io.File originalFile, java.io.File splitFileDirectory, java.text.MessageFormat splitFileNameFormat)
Creates a FileSplitter for splitting the given File.

Method Summary

java.io.File	getOriginalFile()
java.io.File	getSplitFileDirectory()
java.text.MessageFormat	getSplitFileNameFormat()
java.io.File[]	splitByFileSize(long fileSize) Splits the joined file's data into files of the given size.
java.io.File[]	splitByNumFiles(int numFiles) Splits the file data into the given number of files.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_SPLIT_FILE_NAME_FORMAT

public static final java.text.MessageFormat DEFAULT_SPLIT_FILE_NAME_FORMAT

Default split file name message format: {0}.{1}.

Constructor Detail

FileSplitter

public FileSplitter(java.io.File originalFile)

Creates a FileSplitter for splitting the given File. Split files are created in the same directory as the given file. The split files are named according to the pattern DEFAULT_SPLIT_FILE_NAME_FORMAT.

An example should clarify - this FileSplitter:

 FileSplitter splitter = new FileSplitter(new File("bigfile"));
 

will produce files like "bigfile.000000", "bigfile.000001", and so on, in the same directory as "bigfile".

Parameters:

originalFile - original file to split

Throws:

java.lang.IllegalArgumentException - if argument is null

FileSplitter

public FileSplitter(java.io.File originalFile,
                    java.io.File splitFileDirectory,
                    java.text.MessageFormat splitFileNameFormat)

Creates a FileSplitter for splitting the given File. This constructor also allows the caller to specify the directory in which the split files are created.

It also allows the caller to specify the format of the filename using a MessageFormat object. The format's pattern must include a "{0}" argument placeholder for the split file's base name (name of the joined file), and a "{1}" argument placeholder for the index of the split file. This placeholder will be filled with the index of the split file, a number between 0 and one less than the total number of split files, padded with zeroes so that the string is six characters. That is, the index is of the form "000000", "000001", etc.

An example should clarify - this FileSplitter:

 MessageFormat format = new MessageFormat("{0}.part{1}");
 FileSplitter splitter = new FileSplitter(new File("bigfile"),
                                          new File("/tmp"),
                                          format);
 

will produce files like "/tmp/bigfile.part000000", "/tmp/bigfile.part000001", and so on.

Parameters:

originalFile - original file to split

splitFileDirectory - directory in which to place split files

splitFileNameFormat - format of split file names

Throws:

java.lang.IllegalArgumentException - if any argument is null, or if the "splitFileNameFormat" argument does not contain both a "{0}" and "{1}" argument placeholder.

See Also:

MessageFormat

Method Detail

getOriginalFile

public java.io.File getOriginalFile()

Returns:

File object representing original file

getSplitFileDirectory

public java.io.File getSplitFileDirectory()

Returns:

File object representing directory holding split files

getSplitFileNameFormat

public java.text.MessageFormat getSplitFileNameFormat()

Returns:

MessageFormat encapsulating the split file name format

splitByFileSize

public java.io.File[] splitByFileSize(long fileSize)
                               throws java.io.IOException

Splits the joined file's data into files of the given size.

The first split file has a header with metadata; see the class javadoc.

For example, if a 9,000 byte file is split into files of 3,000 bytes, then four files will be created. The first will contain a header, and something less than the first 3,000 bytes of the file, for a total of 3,000 bytes. The next two will have 3,000 bytes of data each, and the final file will have whatever data is leftover.

If an error occurs while splitting the file, and not all split files can be created successfully, this method attempts to delete all the split files that were created.

Throws:

java.lang.IllegalArgumentException - if file size is nonpositive

java.io.IOException - if an exception occurs while reading/writing file data, or if the one of the split file already exists or is not writable for any reason

splitByNumFiles

public java.io.File[] splitByNumFiles(int numFiles)
                               throws java.io.IOException

Splits the file data into the given number of files.

The first split file has a header with metadata; see the class javadoc.

Calling this method is like calling splitByFileSize with fileSize = ceiling( (total file data in bytes) / numFiles).

The same amount of file data is contained in each file; all but the last file has ceiling( (total file data in bytes) / numFiles) bytes of data, and the last has the remainder. In addition, the first file will be slightly larger because of the header.

For example, splitting a 10,000 byte file into three files will yield three files; two will have 3,334 bytes of file data (and the first will also have header data, and the last will have 3,332 bytes.

If an error occurs while splitting the file, and not all split files can be created successfully, this method attempts to delete all the split files that were created.

Throws:

java.lang.IllegalArgumentException - if number of files is nonpositive

java.io.IOException - if an exception occurs while reading/writing file data, or if the one of the split file already exists or is not writable for any reason