Evaluating Software Design Patterns
— the "Gang of Four" patterns implemented in Java 6

dk.rode.thesis.templatemethod
Class ZipSequence

java.lang.Object
  extended by dk.rode.thesis.meta.model.AbstractSequence<E>
      extended by dk.rode.thesis.templatemethod.SequenceTemplate<ZipEntry,InputStream>
          extended by dk.rode.thesis.templatemethod.ZipSequence
All Implemented Interfaces:
Sequence<InputStream>, Copyable<Sequence<InputStream>>, StrictCopyable<Sequence<InputStream>>, Stringable<Sequence<InputStream>>, Closeable

@Participant(value="ConcreteClass")
public class ZipSequence
extends SequenceTemplate<ZipEntry,InputStream>

A zip sequence delivers input streams as sequence values, where each stream correspond to the current zip file entry.

Note, that since sequences always have a current value, a zip stream sequence cannot describe zip files with no zip entries.

Implementation notes:
A zip sequence utilises a single internal zip input stream to deliver all sequence values until reset or restart, where it is discarded, and a new one created and so forth. The returned input streams are protection proxies to ensure that the underlying stream cannot be closed or reset.

Author:
Gunni Rode / rode.dk

Nested Class Summary
(package private)  class ZipSequence.ReadOnlyInputStream
          A read-only input stream is a protection proxy (decorator) that ensures that a given input stream cannot be closed or reset by an external context.
 
Nested classes/interfaces inherited from interface dk.rode.thesis.meta.model.Sequence
Sequence.State
 
Field Summary
private  File file
          The file representing the physical zip file.
private  ZipInputStream stream
          The zip input stream used to read the zip entries from the zip archive represented by file.
 
Fields inherited from class dk.rode.thesis.templatemethod.SequenceTemplate
POLICY
 
Fields inherited from class dk.rode.thesis.meta.model.AbstractSequence
state
 
Constructor Summary
ZipSequence(File file)
          Constructor.
ZipSequence(File directory, String filename)
          Constructor.
ZipSequence(ZipSequence sequence)
          Copy constructor.
 
Method Summary
private  void closeStream()
          Closes the current internal zip stream used by this sequence.
 boolean consistent()
          Returns true if this sequence is consistent, i.e. deliver the same values, in order, after restart or reset.
 ZipSequence copy()
          Returns a copy of this sequence that will start at the same sequence index as this sequence.
protected  InputStream nextValue(ZipEntry key, InputStream current)
          Creates and returns a new input stream to be delivered as the sequence value.
protected  ZipEntry nextValueOpen(InputStream current)
          Prepares this sequence for the next sequence value to be delivered based on the current value supplied as current.
private  void openStream()
          Opens a new internal zip stream based on the physical zip file used by this zip sequence.
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.
protected  void sequenceReset()
          Performs sub-class specific reset of this sequence before sequence values will be delivered.
 
Methods inherited from class dk.rode.thesis.templatemethod.SequenceTemplate
bounded, close, current, ensureOpen, finalize, index, isClosed, next, nextValueClose, reset, 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

file

private File file
The file representing the physical zip file.

Never null.


stream

private ZipInputStream stream
The zip input stream used to read the zip entries from the zip archive represented by file.

Can be null.

Constructor Detail

ZipSequence

public ZipSequence(File file)
            throws SequenceValueException
Constructor.

Parameters:
file - The file representing the physical zip file; cannot be null.
Throws:
NullPointerException - If file is null.
SequenceValueException - If file does not exist, or if it represents a directory, or if the initialisation fails otherwise.

ZipSequence

public ZipSequence(File directory,
                   String filename)
            throws SequenceValueException
Constructor.

Parameters:
directory - The directory where the zip file is to be found; can be null, i.e. "current" directory.
filename - The zip file name; cannot be null.
Throws:
NullPointerException - If name is null.
SequenceValueException - If a zip file with name does not exist in directory, or if it represents a directory, or if the initialisation fails otherwise.

ZipSequence

public ZipSequence(ZipSequence 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
Closes the current internal zip stream used by this sequence.

Throws:
IOException - If the zip entry corresponding to the current value cannot be closed, or if the zip stream cannot be closed.

consistent

public boolean consistent()
Description copied from interface: Sequence
Returns true if this sequence is consistent, i.e. deliver the same values, in order, after restart or reset.

Only bounded consistent sequences will restart. Consistent sequences need not deliver unique sequence values.

Instances of the same type of sequences are always consistent or inconsistent; it is determined at design time, not construction time.

Specified by:
consistent in interface Sequence<InputStream>
Overrides:
consistent in class SequenceTemplate<ZipEntry,InputStream>
Returns:
Default implementation returns true.

copy

public ZipSequence 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 InputStream nextValue(ZipEntry key,
                                InputStream current)
Creates and returns a new input stream to be delivered as the sequence value.

Specified by:
nextValue in class SequenceTemplate<ZipEntry,InputStream>
Parameters:
key - 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.

nextValueOpen

protected ZipEntry nextValueOpen(InputStream 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<ZipEntry,InputStream>
Parameters:
current - The current (soon to be previous) sequence value; never null unless initialising this sequence (once).
Returns:
The next ZipEntry in the zip stream; can be null in case the stream has no more entries (restart).
Throws:
Exception - If the zip stream entry represented by current cannot be closed, or if the next zip entry cannot be fetched.

openStream

private final void openStream()
                       throws IOException
Opens a new internal zip stream based on the physical zip file used by this zip sequence.

Throws:
FileNotFoundException - If the file supplied at construction time does not exist, or if it represents a directory.
IOException - If the stream cannot be opened otherwise.

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<ZipEntry,InputStream>
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<ZipEntry,InputStream>
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 file is supplied at construction time.
Exception - If the file supplied at construction time does not exist; if it represents a directory; or if the stream cannot be opened otherwise.
See Also:
SequenceTemplate.sequenceReset(), SequenceTemplate.sequenceClose()

sequenceReset

protected void sequenceReset()
                      throws Exception
Description copied from class: SequenceTemplate
Performs sub-class specific reset of this sequence before sequence values will be delivered.

Default implementation does nothing.

Overrides:
sequenceReset in class SequenceTemplate<ZipEntry,InputStream>
Throws:
Exception - Not thrown by the default implementation.
See Also:
SequenceTemplate.sequenceOpen(Object...), SequenceTemplate.sequenceClose()

Gunni Rode / rode.dk

Feel free to use and/or modify the Java 6 source code developed for this thesis AT YOUR OWN RISK, but note that the source code comes WITHOUT ANY — and I do mean WITHOUT ANY — form of warranty WHAT SO EVER!

The original thesis and source code are available at rode.dk/thesis.