Package com.luciad.util

Class 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:

  • Field Details

    • MESSAGE

      public static final int MESSAGE
      Indicates that the event contains a message.
      See Also:

    • START_BUSY

      public static final int START_BUSY
      Indicates that the process has started.
      See Also:

    • END_BUSY

      public static final int END_BUSY
      Indicates that the process has ended.
      See Also:

    • PROGRESS

      public static final int PROGRESS
      Indicates that the process is in progress.
      See Also:

  • Constructor Details

    • 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 Details

    • 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:

    • 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:

    • 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

      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:

    • 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

      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

      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:

    • 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.