dk.rode.thesis.templatemethod
Class FileSequence

java.lang.Object
  dk.rode.thesis.meta.model.AbstractSequence<E>
      dk.rode.thesis.templatemethod.SequenceTemplate<File,byte[]>
          dk.rode.thesis.templatemethod.FileSequence

All Implemented Interfaces:

Sequence<byte[]>, Copyable<Sequence<byte[]>>, StrictCopyable<Sequence<byte[]>>, Stringable<Sequence<byte[]>>, Closeable

@Participant(value="ConcreteClass")
public class FileSequence
extends SequenceTemplate<File,byte[]>

A file sequence delivers byte arrays as sequence values, where each array corresponds to the contents of the current file or directory in a given directory.

Implementation notes:
Returning a byte array instead of an input stream is done to illustrate the use of nextValueClose(File, byte[]).

Author:

Gunni Rode / rode.dk

Nested Class Summary

Nested classes/interfaces inherited from interface dk.rode.thesis.meta.model.Sequence

Sequence.State

Field Summary

private File	directory The directory where the files are read from.
private File[]	files The matching files.
private FileFilter	filter A filter to filter the files in directory.
private FileInputStream	stream The current file input stream.

Fields inherited from class dk.rode.thesis.templatemethod.SequenceTemplate

POLICY

Fields inherited from class dk.rode.thesis.meta.model.AbstractSequence

state

Constructor Summary

FileSequence(File directory, FileFilter filter)
Constructor.

FileSequence(FileSequence sequence)
Copy constructor.

Method Summary

private void	closeStream()
FileSequence	copy() Returns a copy of this sequence that will start at the same sequence index as this sequence.
protected byte[]	nextValue(File file, byte[] current) Creates a new input stream based on file and reads and returns the data.
protected void	nextValueClose(File key, byte[] value) Closes the current stream.
protected File	nextValueOpen(byte[] current) Prepares this sequence for the next sequence value to be delivered based on the current value supplied as current.
private FileInputStream	openStream(File file) Opens a new file input stream based on the file supplied as file.
protected void	sequenceClose() Performs sub-class specific procedures for closing this sequence.
protected boolean	sequenceOpen(Object... arguments) Performs sub-class specific initialisation of this sequence before sequence values will be delivered, and returns true upon success.

Methods inherited from class dk.rode.thesis.templatemethod.SequenceTemplate

bounded, close, consistent, current, ensureOpen, finalize, index, isClosed, next, reset, sequenceReset, size, unique

Methods inherited from class dk.rode.thesis.meta.model.AbstractSequence

getStringablePolicy, state, toString, toString

Methods inherited from class java.lang.Object

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

Field Detail

directory

private File directory

The directory where the files are read from.

Never null.

files

private File[] files

The matching files.

Never null, and never empty as this sequence must always have a current value.

filter

private FileFilter filter

A filter to filter the files in directory.

Can be null, in which case all files are fetched.

stream

private FileInputStream stream

The current file input stream.

Constructor Detail

FileSequence

public FileSequence(File directory,
                    FileFilter filter)
             throws SequenceValueException

Constructor.

Parameters:

directory - The directory to deliver the files and/or directories; cannot be null.

filter - A filter to filter the files in directory; can be null, in which case all files and directories are returned.

Throws:

NullPointerException - If directory is null.

SequenceValueException - If directory does not exist, or if it represents a file, or if the initialisation fails otherwise.

FileSequence

public FileSequence(FileSequence sequence)
             throws SequenceValueException

Copy constructor.

If sequence is closed, this sequence will be closed as well.

Parameters:

sequence - The sequence to copy; cannot be null.

Throws:

NullPointerException - If sequence is null.

SequenceValueException - If the initialisation fails, or if the current value of this sequence cannot be fetched.

Method Detail

closeStream

private final void closeStream()
                        throws IOException

Throws:

IOException - If the closing fails.

copy

public FileSequence copy()

Description copied from interface: Sequence

Returns a copy of this sequence that will start at the same sequence index as this sequence.

Returns:

A copy of this sequence; never null.

nextValue

protected byte[] nextValue(File file,
                           byte[] current)
                    throws Exception

Creates a new input stream based on file and reads and returns the data.

Specified by:

nextValue in class SequenceTemplate<File,byte[]>

Parameters:

file - The correlation key just created by nextValueOpen(E); can be null.

current - The current (soon to be previous) sequence value; never null unless initialising this sequence (once).

Returns:

The next sequence value, which will be set as the new current value once SequenceTemplate.next() returns; null means sequence restart, which is only allowed if this sequence is bounded.

Throws:

Exception - In case value construction fails.

nextValueClose

protected void nextValueClose(File key,
                              byte[] value)
                       throws Exception

Closes the current stream.

Overrides:

nextValueClose in class SequenceTemplate<File,byte[]>

Parameters:

key - The correlation key just created by nextValueOpen(E); can be null.

value - The sequence value just created by nextValue(K, E); never null.

Throws:

Exception - In case the closing fails; not thrown by the default implementation

nextValueOpen

protected File nextValueOpen(byte[] current)
                      throws Exception

Description copied from class: SequenceTemplate

Prepares this sequence for the next sequence value to be delivered based on the current value supplied as current. This is step 1/3 in value creation, where the next steps are nextValue(K, E) and nextValueClose(K, E).

The returned correlation key will be used to identify the same creation process in subsequent calls to nextValue and nextValueClose.

Specified by:

nextValueOpen in class SequenceTemplate<File,byte[]>

Parameters:

current - The current (soon to be previous) sequence value; never null unless initialising this sequence (once).

Returns:

The next File in the file stream; can be null in case the stream has no more files (restart).

Throws:

Exception - In case the opening fails.

openStream

private final FileInputStream openStream(File file)
                                  throws IOException

Opens a new file input stream based on the file supplied as file.

Parameters:

file - The file to open the stream for; never null.

Returns:

A new stream; never null.

Throws:

IOException - If the stream cannot be opened.

sequenceClose

protected void sequenceClose()
                      throws Exception

Description copied from class: SequenceTemplate

Performs sub-class specific procedures for closing this sequence. Once this sequence is closed, sequence values can no longer be delivered.

Default implementation does nothing.

Overrides:

sequenceClose in class SequenceTemplate<File,byte[]>

Throws:

Exception - If the super sequence close method throws an exception.

See Also:

SequenceTemplate.sequenceReset(), SequenceTemplate.sequenceOpen(Object...)

sequenceOpen

protected boolean sequenceOpen(Object... arguments)
                        throws Exception

Description copied from class: SequenceTemplate

Performs sub-class specific initialisation of this sequence before sequence values will be delivered, and returns true upon success. In case the initialisation could not be performed, this method returns false, or alternatively throws an exception. If the initialisation fails, this sequences is considered closed.

Initialisation is performed upon construction of new sequences and when copying existing sequences, if needed. The arguments supplied to this (abstract) operation is the varargs arguments supplied at construction time (e.g. via sub-class implementations).

Specified by:

sequenceOpen in class SequenceTemplate<File,byte[]>

Parameters:

arguments - Arguments required by the initialisation, if any; never null, but can be empty.

Returns:

True if the initialisation succeeded, false if it failed.

Throws:

NullPointerException - If no directory is supplied at construction time.

IllegalArgumentException - If the buffer size supplied at construction time is illegal, or the file supplied does not exist, or if not a directory, or if the directly is empty.

Exception - If the super sequence open method throws an exception.

See Also:

SequenceTemplate.sequenceReset(), SequenceTemplate.sequenceClose()