com.luciad.util

LuciadLightspeedClass TLcdStatusEvent<T>

java.lang.Object

java.util.EventObject

com.luciad.util.TLcdStatusEvent<T>

All Implemented Interfaces:

Serializable

public class TLcdStatusEvent<T>
extends EventObject

An EventObject that is sent out to ILcdStatusListener objects whenever the status of a process changes. It has the following properties:

• the source references the sender of the event message
• the ID indicates the type of event (e.g. a message)
• the task indicates the process for which the status changes (e.g. "JPEG decoding" or "Terrain analysis task #44")
• optionally, a progress value indicating how far the process has progressed

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TLcdStatusEvent.Progress<T> Helper object for sending out status events for a particular task.
static class	TLcdStatusEvent.Severity Enumeration representing the severity of the TLcdStatusEvent

Field Summary

Fields

Modifier and Type	Field and Description
static int	END_BUSY Indicates that the process has ended.
static int	MESSAGE Indicates that the event contains a message.
static int	PROGRESS Indicates that the process is in progress.
static int	START_BUSY Indicates that the process has started.

Fields inherited from class java.util.EventObject

source

Constructor Summary

Constructors

Constructor and Description
TLcdStatusEvent(T aSource, int aID, String aMessage) Deprecated. Use one of the factory methods available on this class instead.
TLcdStatusEvent(T aSource, int aID, String aMessage, double aProgress) Deprecated. Use one of the factory methods available on this class instead.
TLcdStatusEvent(T aSource, int aID, String aMessage, double aProgress, boolean aBlockingHint) Deprecated. Use one of the factory methods available on this class instead.

Method Summary

Modifier and Type	Method and Description
static <T> TLcdStatusEvent<T>	cloneAs(T aSource, TLcdStatusEvent<?> aStatusEvent) Returns a clone of aStatusEvent where the source is replaced by aSource.
int	getID() Returns the ID of this TLcdStatusEvent.
String	getMessage() Returns the message of this TLcdStatusEvent.
double	getProgress() Returns the progress value of this TLcdStatusEvent.
TLcdStatusEvent.Severity	getSeverity() Returns the severity of this message
T	getSource()
String	getTaskID() Returns an identifier for the task this update pertains to.
double	getValue() Returns the progress value of this TLcdStatusEvent.
boolean	isBlockingHint() Returns the blocking hint.
boolean	isProgressIndeterminate() Returns true if the progress is indeterminate.
static <T> void	sendMessage(ILcdStatusListener<T> aStatusListener, T aSource, String aMessage, TLcdStatusEvent.Severity aSeverity) Sends a new message status event.
void	setBlockingHint(boolean aBlockingHint) Sets the blocking hint.
void	setMessage(String aMessage) Sets the message of this event to aMessage.
static <T> TLcdStatusEvent.Progress<T>	startIndeterminateProgress(ILcdStatusListener<T> aListener, T aSource, String aMessage) Starts reporting of a new task where the progress is not known.
static <T> TLcdStatusEvent.Progress<T>	startProgress(ILcdStatusListener<T> aListener, T aSource, String aMessage) Starts reporting of a new task where the progress is known.
String	toString() Returns a human readable description of this event, including all its properties.

Methods inherited from class java.lang.Object

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

Field Detail

MESSAGE

public static final int MESSAGE

Indicates that the event contains a message.

See Also:

Constant Field Values

START_BUSY

public static final int START_BUSY

Indicates that the process has started.

See Also:

Constant Field Values

END_BUSY

public static final int END_BUSY

Indicates that the process has ended.

See Also:

Constant Field Values

PROGRESS

public static final int PROGRESS

Indicates that the process is in progress.

See Also:

Constant Field Values

Constructor Detail

TLcdStatusEvent

@Deprecated
public TLcdStatusEvent(T aSource,
                                   int aID,
                                   String aMessage)

Deprecated. Use one of the factory methods available on this class instead.

Creates a new TLcdStatusEvent with the given information. This event will return true for isProgressIndeterminate() because the progress value was not specified. This constructor should only be used when the progress cannot be predicted, for instance when waiting for a connection over the internet. When progress can be predicted, TLcdStatusEvent(Object, int, String, double) should be used.

getValue() will return 0.5.

Parameters:

aSource - the sender of the event.

aID - the ID of the event: MESSAGE, START_BUSY, END_BUSY, PROGRESS.

aMessage - a message describing the event.

TLcdStatusEvent

@Deprecated
public TLcdStatusEvent(T aSource,
                                   int aID,
                                   String aMessage,
                                   double aProgress)

Deprecated. Use one of the factory methods available on this class instead.

Creates a new TLcdStatusEvent with the given information. The given value must lie in the range [0,1] or be NaN. If the value lies outside this range it will be clamped to this range. If the value is not NaN isProgressIndeterminate() will return false. Otherwise isProgressIndeterminate() will return true.

Parameters:

aSource - the sender of the event.

aID - the ID of the event: MESSAGE, START_BUSY, END_BUSY, PROGRESS.

aMessage - a message describing the event.

aProgress - the progress of the event. This value must lie in the range [0,1] or be NaN.

TLcdStatusEvent

@Deprecated
public TLcdStatusEvent(T aSource,
                                   int aID,
                                   String aMessage,
                                   double aProgress,
                                   boolean aBlockingHint)

Deprecated. Use one of the factory methods available on this class instead.

Creates a new TLcdStatusEvent with the given information. The given value must lie in the range [0,1] or be NaN. If the value lies outside this range it will be clamped to this range. If the value is not NaN isProgressIndeterminate() will return false. Otherwise isProgressIndeterminate() will return true.

Parameters:

aSource - the sender of the event.

aID - the ID of the event: MESSAGE, START_BUSY, END_BUSY, PROGRESS.

aMessage - a message describing the event.

aProgress - the progress of the event. This value must lie in the range [0,1] or be NaN.

aBlockingHint - the blocking hint value.

Method Detail

sendMessage

public static <T> void sendMessage(ILcdStatusListener<T> aStatusListener,
                                   T aSource,
                                   String aMessage,
                                   TLcdStatusEvent.Severity aSeverity)

Sends a new message status event.

Parameters:

aStatusListener - The listener to which the event must be send

aSource - The source of the event

aMessage - The message

aSeverity - The severity of the message

Since:

2016.1

startProgress

public static <T> TLcdStatusEvent.Progress<T> startProgress(ILcdStatusListener<T> aListener,
                                                            T aSource,
                                                            String aMessage)

Starts reporting of a new task where the progress is known. The start event is immediately dispatched. Use startIndeterminateProgress(ILcdStatusListener, Object, String) when the progress is unknown.

Parameters:

aListener - The listener to inform of the status

aSource - The source of the event

aMessage - The message

Returns:

a new progress object

Since:

2016.1

See Also:

TLcdStatusEvent.Progress

startIndeterminateProgress

public static <T> TLcdStatusEvent.Progress<T> startIndeterminateProgress(ILcdStatusListener<T> aListener,
                                                                         T aSource,
                                                                         String aMessage)

Starts reporting of a new task where the progress is not known. The start event is immediately dispatched. Use startProgress(ILcdStatusListener, Object, String) when the progress is known.

Parameters:

aListener - The listener to inform of the status

aSource - The source of the event

aMessage - The message

Returns:

a new progress object

Since:

2016.1

See Also:

TLcdStatusEvent.Progress

cloneAs

public static <T> TLcdStatusEvent<T> cloneAs(T aSource,
                                             TLcdStatusEvent<?> aStatusEvent)

Returns a clone of aStatusEvent where the source is replaced by aSource. A typical use case for this method is if you have to forward status events from a delegate object, e.g. when writing a decorator.

Parameters:

aSource - The source for the returned status event

aStatusEvent - The event to clone

Returns:

A clone of aStatusEvent where the source has been replaced by aSource

Since:

2016.1

getSource

public T getSource()

Overrides:

getSource in class EventObject

getTaskID

public String getTaskID()

Returns an identifier for the task this update pertains to. The identifier is used to link an event chain (e.g. a start-progress-end sequence) to the same task, allowing to track multiple concurrent tasks. No two ongoing tasks should use the same task id. An appropriate task ID is auto-generated when calling (startProgress(ILcdStatusListener, Object, String) and startIndeterminateProgress(ILcdStatusListener, Object, String), and reused when calling methods on the progress objects. In all other cases, the name of the thread that created the event is returned.

Returns:

an identifier for the task this event applies to. The string is not meant to be displayed to an end-user.

isProgressIndeterminate

public boolean isProgressIndeterminate()

Returns true if the progress is indeterminate. This means the sender of the event has no clue about what progress has been made, and therefore getValue() does not return a truly meaningful value. This can happen for instance when waiting for a connection over the internet.

Returns false if the progress is defined. This means getValue() returns a meaningful value.

Returns:

True if progress is indeterminate, false otherwise.

getMessage

public String getMessage()

Returns the message of this TLcdStatusEvent.

Returns:

the message of this TLcdStatusEvent.

See Also:

setMessage(java.lang.String)

setMessage

public void setMessage(String aMessage)

Sets the message of this event to aMessage. This is useful for using the event multiple times.

Parameters:

aMessage - the message of this TLcdStatusEvent.

See Also:

getMessage()

getValue

public double getValue()

Returns the progress value of this TLcdStatusEvent. This value is guaranteed to lie in the range [0,1].

Before using this method, it is useful to use isProgressIndeterminate() to find out if the value is truly meaningful.

Returns:

the progress value of this TLcdStatusEvent.

See Also:

getProgress()

getProgress

public double getProgress()

Returns the progress value of this TLcdStatusEvent. This value lies in the range [0,1] if isProgressIndeterminate() returns false. Otherwise the returned value will be NaN.

Returns:

the progress value of this TLcdStatusEvent.

getID

public int getID()

Returns the ID of this TLcdStatusEvent.

Returns:

the ID of this TLcdStatusEvent. This can be one of MESSAGE, START_BUSY, END_BUSY, PROGRESS.

isBlockingHint

public boolean isBlockingHint()

Returns the blocking hint. If the blocking hint is true, the application receiving this event is suggested to block the user interface. If the blocking hint is false, the application is suggested to continue in a non-blocking mode.

Note that this is only a hint; no assumptions can be made that the receiver of this event sticks to this hint.

Default is true.

Returns:

the blocking hint.

See Also:

setBlockingHint(boolean)

setBlockingHint

public void setBlockingHint(boolean aBlockingHint)

Sets the blocking hint. true means the receiver of the event is suggested to block the user interface. If false, the receiver of the event is suggested not to block the user interface, so to perform the task on the background.

Note that this is only a hint; no assumptions can be made that the receiver of this event sticks to this hint.

Parameters:

aBlockingHint - True to suggest blocking, false to suggest non-blocking.

See Also:

isBlockingHint()

getSeverity

public TLcdStatusEvent.Severity getSeverity()

Returns the severity of this message

Returns:

the severity of this message

Since:

2016.1

toString

public String toString()

Returns a human readable description of this event, including all its properties. This method should only be used for debugging purposes.

Overrides:

toString in class EventObject

Returns:

A human readable description of the event.