|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.jdesktop.jdnc.DataLoader
public abstract class DataLoader
Base class for implementing objects which asynchronously load data from an input stream into a model, ensuring that the potentially lengthy operation does not block the user-interface.
Swing requires that all operations which directly affect the user-interface component hierarchy execute on a single thread, the event dispatch thread ( Swing's single-threaded GUI rule). Because of this, the task of streaming data (potentially over the network) should not be performed on the event dispatch thread because it would cause the user-interface to freeze and become unresponsive. And yet, while the reading of the data should be off-loaded to a separate thread, it is desirable to incrementally load portions of that data into the model as it's read so that the user can see more immediate results than if he/she had to wait for the entire data stream to be read before seeing any data at all.
This class implements all the required thread and object synchronization to support this asynchronous, incremental load operation. It does this by splitting the operation into three distinct steps:
startLoading
method.
public void loadMetaData(Object model, InputStream is)
public void readData(Object model, InputStream is)
public void loadData(Object model)
An application using a DataLoader instance may only invoke
initializeMetaData
and startLoading
directly.
startLoading
will cause readData
and
loadData
to invoked during the load operation.
Field Summary | |
---|---|
static java.lang.String |
READER_PRIORITY_KEY
|
Constructor Summary | |
---|---|
protected |
DataLoader()
|
Method Summary | |
---|---|
void |
addMessageListener(MessageListener l)
Adds the specified message listener to this data loader. |
void |
addProgressListener(ProgressListener l)
Adds the specified progress listener to this data loader. |
protected void |
fireException(java.lang.Throwable t)
|
protected void |
fireMessage(java.lang.String message)
|
protected void |
fireProgressEnded()
Fires event indicating that the load operation has completed |
protected void |
fireProgressIncremented(int progress)
Fires event indicating that an increment of progress has occured. |
protected void |
fireProgressStarted(int minimum,
int maximum)
Fires event indicating that the load operation has started. |
MessageListener[] |
getMessageListeners()
Returns an array of listeners. |
ProgressListener[] |
getProgressListeners()
Returns an array of listeners. |
protected int |
getReaderThreadPriority()
|
protected abstract void |
loadData(java.lang.Object model)
Invoked internally once the readData method calls
scheduleLoad to schedule the loading of an increment of
data to the model. |
abstract void |
loadMetaData(java.lang.Object model,
java.io.InputStream is)
Initializes the model with any meta-data available in the input stream. |
protected abstract void |
readData(java.io.InputStream is)
Invoked by the startLoading method. |
void |
removeMessageListener(MessageListener l)
Removes the specified message listener from this data loader. |
void |
removeProgressListener(ProgressListener l)
Removes the specified progress listener from this data loader. |
protected void |
scheduleLoad()
Invoked by the readData method from the "reader"
thread to schedule a subsequent call to loadData on the
event dispatch thread. |
void |
startLoading(java.lang.Object model,
java.io.InputStream is)
Starts the asynchronous load operation by spinning up a separate thread that will read the data from the input stream. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String READER_PRIORITY_KEY
Constructor Detail |
---|
protected DataLoader()
Method Detail |
---|
public void addProgressListener(ProgressListener l)
addProgressListener
in interface ProgressSource
l
- progress listener to be notified as data is loaded or errors occurpublic void removeProgressListener(ProgressListener l)
removeProgressListener
in interface ProgressSource
l
- progress listener to be notified as data is loaded or errors occurpublic ProgressListener[] getProgressListeners()
ProgressSource
getProgressListeners
in interface ProgressSource
public void addMessageListener(MessageListener l)
addMessageListener
in interface MessageSource
l
- message listener to be notified as data is loaded or errors occurpublic void removeMessageListener(MessageListener l)
removeMessageListener
in interface MessageSource
l
- message listener to be notified as data is loaded or errors occurpublic MessageListener[] getMessageListeners()
MessageSource
getMessageListeners
in interface MessageSource
public abstract void loadMetaData(java.lang.Object model, java.io.InputStream is) throws java.io.IOException
model
- the data model being loaded from the input streamis
- the input stream containing the meta-data
java.io.IOException
public void startLoading(java.lang.Object model, java.io.InputStream is)
startLoading
is called and must not be modified while the load operation executes,
otherwise synchronization errors will occur.
model
- the data model being loaded from the input streamis
- the input stream containing the dataaddProgressListener(org.jdesktop.swingx.event.ProgressListener)
protected int getReaderThreadPriority()
protected abstract void readData(java.io.InputStream is) throws java.io.IOException, ConversionException
startLoading
method. This method will be
called on a separate "reader" thread. Subclasses must implement
this method to read the data from the stream and place it in a data
structure which is disconnected from the data model. When
increments of data are ready to be loaded into the model, this method
should invoke scheduleLoad
, which will cause
loadData
to be called on the event dispatch thread, where
the model may be safely updated. Progress events must not be fired from
this method.
is
- the input stream containing the data
java.io.IOException
- if errors occur while reading data from the input stream
ConversionException
- if errors occur while converting data values from string to
objectscheduleLoad()
protected abstract void loadData(java.lang.Object model)
readData
method calls
scheduleLoad
to schedule the loading of an increment of
data to the model. This method is called on the event dispatch
thread, therefore it is safe to mutate the model from this method.
Subclasses must implement this method to load the current contents of the
disconnected data structure into the data model. Note that because
there is an unpredictable delay between the time scheduleLoad
is called from the "reader" thread and loadData
executes on the event dispatch thread, there may be more data available
for loading than was available when scheduleLoad
was
invoked. All available data should be loaded from this method.
This method should fire an appropriate progress event to notify progress listeners when:
model
- the data model being loaded from the input streamfireProgressStarted(int, int)
,
fireProgressEnded()
,
fireException(java.lang.Throwable)
protected void scheduleLoad()
readData
method from the "reader"
thread to schedule a subsequent call to loadData
on the
event dispatch thread. If readData
invokes
scheduleLoad
multiple times before loadData
has the opportunity to execute on the event dispatch thread, those
requests will be collapsed, resulting in only a single call to
loadData
.
readData(java.io.InputStream)
,
loadData(java.lang.Object)
protected void fireProgressStarted(int minimum, int maximum)
minimum
- the minimum value of the progress operationmaximum
- the maximum value of the progress operationprotected void fireProgressIncremented(int progress)
progress
- total value of the progress operation. This
value should be between the minimum and maximum valuesprotected void fireProgressEnded()
protected void fireException(java.lang.Throwable t)
protected void fireMessage(java.lang.String message)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |