omero.cmd

Class CmdCallbackI

java.lang.Object

Ice.ObjectImpl

omero.cmd._CmdCallbackDisp

omero.cmd.CmdCallbackI

All Implemented Interfaces:

Ice.Object, java.io.Serializable, java.lang.Cloneable, _CmdCallbackOperations, _CmdCallbackOperationsNC, CmdCallback

Direct Known Subclasses:

ImportLibrary.ImportCallback

public class CmdCallbackI
extends _CmdCallbackDisp

Callback servant used to wait until a HandlePrx would return non-null on getReponse. The server will notify of completion to prevent constantly polling on getResponse. Subclasses can override methods for handling based on the completion status. Example usage:

      cb = new CmdCallbackI(client, handle);
      response = null;
      while (response == null) {
          response = cb.block(500);
      }

      // or

      response = cb.loop(5, 500);
 

Subclasses which depend on the proper ordering of either initialization or calls to onFinished(Response, Status, Current) should make use of the initializationDone() and waitOnInitialization(), or the onFinishedDone() and waitOnFinishedDone() methods.

Since:

Beta4.4

See Also:

initializationDone(), onFinishedDone(), Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected HandlePrx	handle Proxy passed to this instance on creation.

Fields inherited from class omero.cmd._CmdCallbackDisp

__ids

Fields inherited from interface omero.cmd.CmdCallback

ice_staticId

Constructor Summary

Constructors

Constructor and Description
CmdCallbackI(client client, HandlePrx handle)
CmdCallbackI(CmdCallbackI ccb)
CmdCallbackI(Ice.ObjectAdapter adapter, java.lang.String category, HandlePrx handle)

Method Summary

Modifier and Type	Method and Description
boolean	block(long ms) Blocks for the given number of milliseconds unless finished(Response, Status, Current) has been called in which case it returns immediately with true.
void	close(boolean closeHandle) First removes self from the adapter so as to no longer receive notifications, and the calls close on the remote handle if requested.
void	finished(Response rsp, Status status, Ice.Current __current) Called when the command has completed.
Response	getResponse() Returns possibly null Response value.
Status	getStatus() Returns possibly null Status value.
protected Status	getStatusOrThrow()
protected void	initializationDone() Subclasses which must perform their own initialization before onFinished(Response, Status, Current) is called should call initializationDone() once that setup is complete.
protected void	initialPoll() Called at the end of construction to check a race condition.
boolean	isCancelled() Returns whether Status::CANCELLED is contained in the flags variable of the Status instance.
boolean	isFailure() Returns whether Status::FAILURE is contained in the flags variable of the Status instance.
Response	loop(int loops, long ms) Calls block(long) "loops" number of times with the "ms" argument.
void	onFinished(Response rsp, Status status, Ice.Current __current) Method intended to be overridden by subclasses.
protected void	onFinishedDone()
void	poll() Calls HandlePrx.getResponse() in order to check for a non-null value.
void	step(int complete, int total, Ice.Current __current) Called periodically by the server to signal that processing is moving forward.
protected void	waitOnFinishedDone()
protected void	waitOnInitialization() Subclasses which must perform their own initialization before onFinished(Response, Status, Current) is called should call waitOnInitialization() before accessing any initialized state.

Methods inherited from class omero.cmd._CmdCallbackDisp

___finished, ___step, __dispatch, __readImpl, __writeImpl, finished, ice_copyStateFrom, ice_id, ice_id, ice_ids, ice_ids, ice_isA, ice_isA, ice_staticId, step

Methods inherited from class Ice.ObjectImpl

___ice_id, ___ice_ids, ___ice_isA, ___ice_ping, __checkMode, __read, __read, __readImpl, __write, __write, __writeImpl, clone, ice_dispatch, ice_dispatch, ice_operationAttributes, ice_ping, ice_ping, ice_postUnmarshal, ice_preMarshal

Methods inherited from class java.lang.Object

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

Methods inherited from interface Ice.Object

__read, __read, __write, __write, clone, ice_dispatch, ice_dispatch, ice_operationAttributes, ice_ping, ice_ping, ice_postUnmarshal, ice_preMarshal

Field Detail

handle

protected final HandlePrx handle

Proxy passed to this instance on creation. Can be used by subclasses freely. The object will not be nulled, but may be closed server-side.

Constructor Detail

CmdCallbackI

public CmdCallbackI(client client,
                    HandlePrx handle)
             throws ServerError

Throws:

ServerError

CmdCallbackI

public CmdCallbackI(CmdCallbackI ccb)
             throws ServerError

Throws:

ServerError

CmdCallbackI

public CmdCallbackI(Ice.ObjectAdapter adapter,
                    java.lang.String category,
                    HandlePrx handle)
             throws ServerError

Throws:

ServerError

Method Detail

initialPoll

protected void initialPoll()

Called at the end of construction to check a race condition. If HandlePrx finishes its execution before the CmdCallbackPrx has been sent set via addCallback, then there's a chance that this implementation will never receive a call to finished, leading to perceived hangs. By default, this method starts a background thread and calls poll(). An ObjectNotExistException implies that another caller has already closed the HandlePrx.

initializationDone

protected void initializationDone()

Subclasses which must perform their own initialization before onFinished(Response, Status, Current) is called should call initializationDone() once that setup is complete.

waitOnInitialization

protected void waitOnInitialization()

Subclasses which must perform their own initialization before onFinished(Response, Status, Current) is called should call waitOnInitialization() before accessing any initialized state.

onFinishedDone

protected void onFinishedDone()

waitOnFinishedDone

protected void waitOnFinishedDone()

getResponse

public Response getResponse()

Returns possibly null Response value. If null, then neither has the remote server nor the local poll method called finish with non-null values.

Returns:

the response, may be null

getStatus

public Status getStatus()

Returns possibly null Status value. If null, then neither has the remote server nor the local poll method called finish with non-null values.

Returns:

the status, may be null

getStatusOrThrow

protected Status getStatusOrThrow()

isCancelled

public boolean isCancelled()

Returns whether Status::CANCELLED is contained in the flags variable of the Status instance. If no Status is available, a ClientError will be thrown.

Returns:

if State.CANCELLED has been flagged

isFailure

public boolean isFailure()

Returns whether Status::FAILURE is contained in the flags variable of the Status instance. If no Status is available, a ClientError will be thrown.

Returns:

if State.FAILURE has been flagged

loop

public Response loop(int loops,
                     long ms)
              throws java.lang.InterruptedException,
                     LockTimeout

Calls block(long) "loops" number of times with the "ms" argument. This means the total wait time for the action to occur is: loops X ms. Sensible values might be 10 loops for 500 ms, or 5 seconds.

Parameters:

loops - Number of times to call block(long)

ms - Number of milliseconds to pass to block(long

Returns:

the response

Throws:

java.lang.InterruptedException - if the thread was interrupted

LockTimeout - if block(long) does not return a non-null value after loops calls.

block

public boolean block(long ms)
              throws java.lang.InterruptedException

Blocks for the given number of milliseconds unless finished(Response, Status, Current) has been called in which case it returns immediately with true. If false is returned, then the timeout was reached.

Parameters:

ms - Milliseconds which this method should block for.

Returns:

if the the thread finished before the timeout was reached

Throws:

java.lang.InterruptedException - if the thread was interrupted

poll

public void poll()

Calls HandlePrx.getResponse() in order to check for a non-null value. If so, _HandleOperations.getStatus(Ice.Current) is also called, and the two non-null values are passed to finished(Response, Status, Current). This should typically not be used. Instead, favor the use of block and loop.

step

public void step(int complete,
                 int total,
                 Ice.Current __current)

Called periodically by the server to signal that processing is moving forward. Default implementation does nothing.

__current - The Current object for the invocation.

finished

public final void finished(Response rsp,
                           Status status,
                           Ice.Current __current)

Called when the command has completed.

__current - The Current object for the invocation.

onFinished

public void onFinished(Response rsp,
                       Status status,
                       Ice.Current __current)

Method intended to be overridden by subclasses. Default logic does nothing.

Parameters:

rsp - the response

status - the status

__current - regarding the current method invocation

close

public void close(boolean closeHandle)

First removes self from the adapter so as to no longer receive notifications, and the calls close on the remote handle if requested.

Parameters:

closeHandle - if the handle should be closed