com.partnersoft.io.AbstractIterableInput<T>
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
T - type of object returned from getFetched() and the iterator's
next() methodpublic abstract class AbstractIterableInput<T>
Convenience implementation of several aspects of IterableInput. Primarily it provides the implementation of the Iterable portion by mapping Iterator methods to the fetch() and getFetched() methods.
Implementations should override the various protected *Imp methods rather
than the public methods. These allow you to throw whatever exceptions are
appropriate, which are then caught in the public methods and assigned to the
exception variable to supply the getException() method.
Copyright 2006-2008 Partner Software, Inc.
| Nested Class Summary |
|---|
| Nested classes/interfaces inherited from interface com.partnersoft.io.IterableInput |
|---|
IterableInput.Status |
| Constructor Summary | |
|---|---|
AbstractIterableInput()
|
|
| Method Summary | |
|---|---|
void |
close()
Performs any housekeeping measures required to release the underlying input, closing files or connections or what-have-you). |
protected abstract void |
closeImp()
Subclass implementation of guts of close() method. |
boolean |
fetch()
Attempts to fetch the next item from the input source. |
protected abstract boolean |
fetchImp()
Subclass implementation of guts of fetch() method. |
java.lang.Exception |
getException()
Returns the last exception encountered during IterableInput.open(),
IterableInput.fetch(), or IterableInput.close() (or other methods that call these,
like the Iterator implementation). |
IterableInput.Status |
getStatus()
Returns the current status of this input. |
boolean |
isFetchValid()
Returns true if the last call to fetch() was successful and got a valid result. |
java.util.Iterator<T> |
iterator()
This is the same as the super-interface's method, but it has the side effect of opening (via IterableInput.open() the IterableInput if it is
currently closed. |
void |
open()
Initialize the input, opening the underlying file or other resource. |
protected abstract void |
openImp()
Subclass implementation of guts of open() method. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Methods inherited from interface com.partnersoft.io.IterableInput |
|---|
getFetched |
| Constructor Detail |
|---|
public AbstractIterableInput()
| Method Detail |
|---|
public IterableInput.Status getStatus()
IterableInput
getStatus in interface IterableInput<T>public java.lang.Exception getException()
IterableInputIterableInput.open(),
IterableInput.fetch(), or IterableInput.close() (or other methods that call these,
like the Iterator implementation). Returns null if no exception has
occurred.
The exception is cleared by other calls to these methods; thus an exception that occurred during a fetch is cleared by closing and reopening the input.
getException in interface IterableInput<T>public boolean isFetchValid()
IterableInputIterableInput.getFetched()).
This method may only be called when the input is in the FETCHING or END_OF_INPUT statuses. Calling it from any other status will result in an IllegalStateException. In fact, isFetchValid() is always true when the status is FETCHING and always false if it is END_OF_INPUT.
isFetchValid in interface IterableInput<T>public java.util.Iterator<T> iterator()
IterableInputIterableInput.open() the IterableInput if it is
currently closed. This makes it just a bit more convenient to use in
scripts by eliminating the open() step.
Another unusual behavior is that the Iterator returned will start at the current position in the input - in other words, it does NOT necessarily start at the beginning of input, and multiple calls to this method will return Iterators that are identical in behavior and state (and may even be the same object). The only way to restart at the beginning is to call close().
Remember, after looping through this Iterator's contents, to call close() and free any underlying resources. You should ALWAYS call close, or risk having hanging file handles or other resources.
iterator in interface IterableInput<T>iterator in interface java.lang.Iterable<T>public void open()
IterableInputThis method can only be called if the current status is CLOSED. Calling it in any other state will result in an IllegalStateException.
If the input is opened successfully, the status is changed to OPENED.
If an exception occurs during the open, the exception is made available via getException(), and the status is changed to END_OF_INPUT. This means close() should still be called.
open in interface IterableInput<T>public boolean fetch()
IterableInputThis method may only be called when the status is CLOSED, OPENED or FETCHING. Calling it in any other status will result in an IllegalStateException.
If the current status is CLOSED, calling this method will automatically call open(), then it will start the fetch.
If the current status is OPENED, calling this method will automatically start the fetch.
If the fetch is successful, this method will return true, and
isFetchValid() will return true afterward. The item fetched is made
available via IterableInput.getFetched(). The status will then be
FETCHING.
If the fetch fails, either due to running out of input or an exception, this method will return false, as will isFetchValid() afterward. The status will then be END_OF_INPUT. Any exception occurring will be available via getException().
Does not throw any checked or common unchecked exceptions (e.g. NullPointerException). May throw Errors or other low-level unchecked exceptions.
fetch in interface IterableInput<T>public void close()
IterableInputThis method may be called from any status, since client code may abandon a fetch before even opening the input, and since we want to encourage client code to call close() defensively to prevent memory or file handle leaks. Calling it when the status is CLOSED simply does nothing.
Status after calling is always CLOSED.
No exceptions are thrown; if any occur they are made available via getException().
Once the IterableInput has been closed, it may be re-used for another fetch pass.
You should ALWAYS call close() if there is ANY chance this input was opened. Not doing so risks generating memory leaks, locked files, and other resource-exhaustion bugs because the input is unable to release them.
close in interface IterableInput<T>
protected abstract void openImp()
throws java.lang.Exception
Subclasses must implement this to do the actual work required by open(). Feel free to throw exceptions; these are caught inside the open() itself and applied to the exception variable. Thus, you can focus on the actual task instead of paperwork.
java.lang.Exception
protected abstract void closeImp()
throws java.lang.Exception
Subclasses must implement this to do the actual work required by close(). Feel free to throw exceptions; these are caught inside the close() itself and applied to the exception variable. Thus, you can focus on the actual task instead of paperwork.
java.lang.Exception
protected abstract boolean fetchImp()
throws java.lang.Exception
Subclasses must implement this to do the actual work required by fetch(). Feel free to throw exceptions; these are caught inside the fetch() itself and applied to the exception variable. Thus, you can focus on the actual task instead of paperwork.
java.lang.Exception
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||