org.jdesktop.ws
[Java] Class BaseService

java.lang.Object
  org.jdesktop.beans.AbstractBean
      org.jdesktop.ws.BaseService

public abstract class BaseService
extends org.jdesktop.beans.AbstractBean

An abstact class useful as a base for asynchronous data service classes. For example, HttpService is a useful subclass for executing REST like webservice calls at a low level. WebService is a useful class which embodies one or more Operations (which are instances of BaseService) and which is useful for executing SOAP requests.

One could also imagine the creation of FtpService, SshService, SftpService, DatabaseService, and other such non http-based services.

BaseService serves as a base class for creating asynchronous Swing-friendly web service APIs. All events fired from BaseService are fired on the EDT, and it is assumed that all methods invoked on BaseService are likewise invoked on the Event Dispatching Thread (EDT).

Authors:

Richard

eventInProgress

private AtomicBoolean eventInProgress

Indicates that an event is in progress, and that there should therefore not be another SwingUtilities.invokeLater call. This is the primary mechanism for limiting the number of invokeLater calls to the minimum necessary.

events

private LinkedBlockingQueue events

This LinkedBlockingQueue holds PropertyChangeListener/PropertyChangeEvent pairs which have not yet been fired on the EDT. This queue is updated whenever new events are fired, or when events are taken out of the queue and processed on the EDT.

listeners

private EventListenerList listeners

A list of listeners which are notified whenever the BaseService finishes, aborts, or fails.

progress

private float progress

The progress of the state. When State is SENDING this is the progress of the upload, or -1 if it is not known. When State is RECEIVING this is the progress of the download, or -1 if it is not known. In the READY and CONNECTING states it is -1 indicating an indeterminate value. In the SENT state it still reflects the amount of data sent. When DONE it represents the amount of data downloaded. When FAILED or ABORTED it is -1 since a reliable value may not be avialable for what it means.

state

private State state

The state that this BaseService is in

BaseService

protected BaseService()

Creates a new BaseService.

abort

public final void abort()

Aborts the current request. If called when in a state that is not abortable (such as Ready or Done) then nothing happens. The final state may not be set to ABORTED, but the aborted function of any AbortListeners will be invoked.

addAbortListener

public void addAbortListener(AbortListener listener)

Adds a FailureListener

Parameters:

listener

addDoneListener

public final void addDoneListener(DoneListener listener)

Adds a DoneListener.

Parameters:

listener

addFailureListener

public void addFailureListener(FailureListener listener)

doAbort

protected void doAbort()

doSend

protected void doSend()

Invoked by this AbstractHttpService, this method performs the actual send operation. This method must not block.

throws:

java.lang.Exception

done

protected final void done()

fail

public void fail(Throwable th)

Invoke this method from subclasses to force the connection to fail. Note that this only works if the current state is CONNECTING, SENDING, SENT, or RECEIVING. In all other states invoking this method has no effect. TODO This method should be protected, but the FX-Script class needs access to it. Not sure what the right choice is here. Do not invoke this method directly. In particular, it doesn't abort first, so if the task hasn't already completed then don't even bother calling this method until it does because there will be problems.

Parameters:

th

fireAbort

private void fireAbort()

Fires the aborted event, but does not change the state. Only fires the event. It is fired on the EDT. The event is only fired if the number of AbortListeners is > 0. If invoked and the Status is not ABORTED, then an IllegalStateException is thrown.

fireDone

private void fireDone()

fireFailure

private void fireFailure(Throwable th)

Fires the failure event, but does not change the state. Only fires the event. It is fired on the EDT. The event is only fired if the number of FailureListeners is > 0. If invoked and the Status is not FAILED, then an IllegalStateException is thrown.

fireOnEDT

protected final void fireOnEDT(String prop, Object oldv, Object newv)

Fires the given property change event on the EDT in a manner that avoids calling invokeLater for every property change event. This can greatly improve performance in cases where many events happen very quickly.

Parameters:

prop

oldv

newv

getProgress

public final float getProgress()

Property indicating the upload or download progress. This is updated automatically based on the state of the service. A value of -1 indicates that progress is not trackable, either because it is indeterminate or because the State is not Sending or Receiving. All states other than Sending or Receiving will always indicate a value of -1, except for SENT and DONE. This is a float value between 0-1 when it is valid.

getState

public final State getState()

Property indicating the state of the service. PropertyChange events will be fired whenever this state changes

removeAbortListener

public void removeAbortListener(AbortListener listener)

Removes a FailureListener

Parameters:

listener

removeDoneListener

public final void removeDoneListener(DoneListener listener)

Removes an AbortListener

Parameters:

listener

removeFailureListener

public void removeFailureListener(FailureListener listener)

send

public final void send()

Initiates the request/response cycle by sending a request to the remote service. This call returns immediately. Either use a property change listener for the state property or add one or more of DoneListener, FailureListener, AbortListener.

setProgress

protected void setProgress(float p)

Sets the progress. If values are < -1 or > 1, then they are clamped to -1 and 1 respectively. A property change event is fired on the EDT.

Parameters:

p

setState

protected void setState(State s)

Sets the local state property, firing a property change event on the EventDispatchThread if necessary. The value of the progress property is set according to the rules outlined in the field javadocs for progress.

Parameters:

s

Groovy Documentation