qx.io.remote
Class Rpc

java.lang.Object
  qx.core.Object
      qx.core.Target
          qx.io.remote.Rpc

public class Rpc
extends Target

Provides a Remote Procedure Call (RPC) implementation.

Each instance of this class represents a “Service”. These services can correspond to various concepts on the server side (depending on the programming language/environment being used), but usually, a service means a class on the server.

In case multiple instances of the same service are needed, they can be distinguished by ids. If such an id is specified, the server routes all calls to a service that have the same id to the same server-side instance.

When calling a server-side method, the parameters and return values are converted automatically. Supported types are int (and Integer), double (and Double), String, Date, Map, and JavaBeans. Beans must have a default constructor on the server side and are represented by simple JavaScript objects on the client side (used as associative arrays with keys matching the server-side properties). Beans can also be nested, but be careful not to create circular references! There are no checks to detect these (which would be expensive), so you as the user are responsible for avoiding them.

A simple example:

  function callRpcServer ()
  {
    var rpc = new qx.io.remote.Rpc();
    rpc.setTimeout(10000);
    rpc.setUrl("http://127.0.0.1:8007");
    rpc.setServiceName("qooxdoo.admin");

    // call a remote procedure -- takes no arguments, returns a string
    var that = this;
    this.RpcRunning = rpc.callAsync(
      function(result, ex, id)
      {
        that.RpcRunning = null;
        if (ex == null) {
            alert(result);
        } else {
            alert("Async(" + id + ") exception: " + ex);
        }
      },
      "fss.getBaseDir");
  }

fss.getBaseDir is the remote procedure in this case, potential arguments would be listed after the procedure name.

Constructor Summary

Rpc()

Rpc(java.lang.String url)

Rpc(java.lang.String url, java.lang.String serviceName)

Method Summary

java.lang.Object	_callInternal(java.lang.Object args, java.lang.Integer callType, boolean refreshSession) Internal RPC call method
void	abort(java.lang.Object opaqueCallRef) Aborts an asynchronous server call.
java.lang.Object	callAsync(java.lang.Object handler, java.lang.String methodName) Makes an asynchronous server call.
java.lang.Object	callAsyncListeners(boolean coalesce, java.lang.String methodName) Makes an asynchronous server call and dispatch an event upon completion or failure.
java.lang.Object	callSync(java.lang.String methodName) Makes a synchronous server call.
java.lang.String	fixUrl(java.lang.String url) Helper method to rewrite a URL with a stale session id (so that it includes the correct session id afterwards).
boolean	getCrossDomain() Returns the (computed) value of the property crossDomain.
java.lang.String	getPassword() Returns the (computed) value of the property password.
java.lang.Object	getServerData() Returns the (computed) value of the property serverData.
java.lang.String	getServiceName() Returns the (computed) value of the property serviceName.
java.lang.Integer	getTimeout() Returns the (computed) value of the property timeout.
java.lang.String	getUrl() Returns the (computed) value of the property url.
boolean	getUseBasicHttpAuth() Returns the (computed) value of the property useBasicHttpAuth.
java.lang.String	getUsername() Returns the (computed) value of the property username.
void	initCrossDomain(boolean arg) Calls the apply method and dispatches the change event of the property crossDomain with the default value defined by the class developer.
void	initPassword(java.lang.String arg) Calls the apply method and dispatches the change event of the property password with the default value defined by the class developer.
void	initServerData(java.lang.Object arg) Calls the apply method and dispatches the change event of the property serverData with the default value defined by the class developer.
void	initServiceName(java.lang.String arg) Calls the apply method and dispatches the change event of the property serviceName with the default value defined by the class developer.
void	initTimeout(java.lang.Integer arg) Calls the apply method and dispatches the change event of the property timeout with the default value defined by the class developer.
void	initUrl(java.lang.String arg) Calls the apply method and dispatches the change event of the property url with the default value defined by the class developer.
void	initUseBasicHttpAuth(boolean arg) Calls the apply method and dispatches the change event of the property useBasicHttpAuth with the default value defined by the class developer.
void	initUsername(java.lang.String arg) Calls the apply method and dispatches the change event of the property username with the default value defined by the class developer.
boolean	isCrossDomain() Check whether the (computed) value of the boolean property crossDomain equals true.
boolean	isUseBasicHttpAuth() Check whether the (computed) value of the boolean property useBasicHttpAuth equals true.
void	refreshSession(java.lang.Object handler) Refreshes a server session by retrieving the session id again from the server.
void	resetCrossDomain() Resets the user value of the property crossDomain.
void	resetPassword() Resets the user value of the property password.
void	resetServerData() Resets the user value of the property serverData.
void	resetServiceName() Resets the user value of the property serviceName.
void	resetTimeout() Resets the user value of the property timeout.
void	resetUrl() Resets the user value of the property url.
void	resetUseBasicHttpAuth() Resets the user value of the property useBasicHttpAuth.
void	resetUsername() Resets the user value of the property username.
void	setCrossDomain(boolean arg) Sets the user value of the property crossDomain.
void	setPassword(java.lang.String arg) Sets the user value of the property password.
void	setServerData(java.lang.Object arg) Sets the user value of the property serverData.
void	setServiceName(java.lang.String arg) Sets the user value of the property serviceName.
void	setTimeout(java.lang.Integer arg) Sets the user value of the property timeout.
void	setUrl(java.lang.String arg) Sets the user value of the property url.
void	setUseBasicHttpAuth(boolean arg) Sets the user value of the property useBasicHttpAuth.
void	setUsername(java.lang.String arg) Sets the user value of the property username.
boolean	toggleCrossDomain() Toggles the (computed) value of the boolean property crossDomain.
boolean	toggleUseBasicHttpAuth() Toggles the (computed) value of the boolean property useBasicHttpAuth.

Methods inherited from class qx.core.Target

_dispatchEvent, addChangeSelectionListener, addChangeValueListener, addEventListener, addExecuteListener, addJavaEventListener, createDispatchChangeEvent, createDispatchDataEvent, createDispatchEvent, dispatchEvent, hasEventListeners, removeEventListener

Methods inherited from class qx.core.Object

_disposeFields, _disposeObjectDeep, _disposeObjects, base, dispose, get, getDisposed, isDisposed, reset, self, set, toHashCode, toString_

Methods inherited from class java.lang.Object

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

Constructor Detail

Rpc

public Rpc()

Rpc

public Rpc(java.lang.String url)

Rpc

public Rpc(java.lang.String url,
           java.lang.String serviceName)

Method Detail

_callInternal

public java.lang.Object _callInternal(java.lang.Object args,
                                      java.lang.Integer callType,
                                      boolean refreshSession)

Internal RPC call method

abort

public void abort(java.lang.Object opaqueCallRef)

Aborts an asynchronous server call. Consequently, the callback function provided to callAsync or callAsyncListeners will be called with an exception.

callAsync

public java.lang.Object callAsync(java.lang.Object handler,
                                  java.lang.String methodName)

Makes an asynchronous server call. The method arguments (if any) follow after the method name (as normal JavaScript arguments, separated by commas, not as an array).

When an answer from the server arrives, the handler function is called with the result of the call as the first, an exception as the second parameter, and the id (aka sequence number) of the invoking request as the third parameter. If the call was successful, the second parameter is null. If there was a problem, the second parameter contains an exception, and the first one is null.

The return value of this method is a call reference that you can store if you want to abort the request later on. This value should be treated as opaque and can change completely in the future! The only thing you can rely on is that the abort method will accept this reference and that you can retrieve the sequence number of the request by invoking the getSequenceNumber() method (see below).

If a specific method is being called, asynchronously, a number of times in succession, the getSequenceNumber() method may be used to disambiguate which request a response corresponds to. The sequence number value is a value which increments with each request.)

callAsyncListeners

public java.lang.Object callAsyncListeners(boolean coalesce,
                                           java.lang.String methodName)

Makes an asynchronous server call and dispatch an event upon completion or failure. The method arguments (if any) follow after the method name (as normal JavaScript arguments, separated by commas, not as an array).

When an answer from the server arrives (or fails to arrive on time), if an exception occurred, a “failed”, “timeout” or “aborted” event, as appropriate, is dispatched to any waiting event listeners. If no exception occurred, a “completed” event is dispatched.

When a “failed”, “timeout” or “aborted” event is dispatched, the event data contains an object with the properties ‘origin’, ‘code’, ‘message’ and ‘id’. The object has a toString() function which may be called to convert the exception to a string.

When a “completed” event is dispatched, the event data contains the JSON-RPC result.

The return value of this method is a call reference that you can store if you want to abort the request later on. This value should be treated as opaque and can change completely in the future! The only thing you can rely on is that the abort method will accept this reference and that you can retrieve the sequence number of the request by invoking the getSequenceNumber() method (see below).

If a specific method is being called, asynchronously, a number of times in succession, the getSequenceNumber() method may be used to disambiguate which request a response corresponds to. The sequence number value is a value which increments with each request.)

callSync

public java.lang.Object callSync(java.lang.String methodName)

Makes a synchronous server call. The method arguments (if any) follow after the method name (as normal JavaScript arguments, separated by commas, not as an array).

If a problem occurs when making the call, an exception is thrown.

WARNING. With some browsers, the synchronous interface causes the browser to hang while awaiting a response! If the server decides to pause for a minute or two, your browser may do nothing (including refreshing following window changes) until the response is received. Instead, use the asynchronous interface.

YOU HAVE BEEN WARNED.

fixUrl

public java.lang.String fixUrl(java.lang.String url)

Helper method to rewrite a URL with a stale session id (so that it includes the correct session id afterwards).

getCrossDomain

public boolean getCrossDomain()

Returns the (computed) value of the property crossDomain.

For further details take a look at the property definition: crossDomain.

getPassword

public java.lang.String getPassword()

Returns the (computed) value of the property password.

For further details take a look at the property definition: password.

getServerData

public java.lang.Object getServerData()

Returns the (computed) value of the property serverData.

For further details take a look at the property definition: serverData.

getServiceName

public java.lang.String getServiceName()

Returns the (computed) value of the property serviceName.

For further details take a look at the property definition: serviceName.

getTimeout

public java.lang.Integer getTimeout()

Returns the (computed) value of the property timeout.

For further details take a look at the property definition: timeout.

getUrl

public java.lang.String getUrl()

Returns the (computed) value of the property url.

For further details take a look at the property definition: url.

getUseBasicHttpAuth

public boolean getUseBasicHttpAuth()

Returns the (computed) value of the property useBasicHttpAuth.

For further details take a look at the property definition: useBasicHttpAuth.

getUsername

public java.lang.String getUsername()

Returns the (computed) value of the property username.

For further details take a look at the property definition: username.

initCrossDomain

public void initCrossDomain(boolean arg)

Calls the apply method and dispatches the change event of the property crossDomain with the default value defined by the class developer. This function can only be called from the constructor of a class.

For further details take a look at the property definition: crossDomain.

initPassword

public void initPassword(java.lang.String arg)

Calls the apply method and dispatches the change event of the property password with the default value defined by the class developer. This function can only be called from the constructor of a class.

For further details take a look at the property definition: password.

initServerData

public void initServerData(java.lang.Object arg)

Calls the apply method and dispatches the change event of the property serverData with the default value defined by the class developer. This function can only be called from the constructor of a class.

For further details take a look at the property definition: serverData.

initServiceName

public void initServiceName(java.lang.String arg)

Calls the apply method and dispatches the change event of the property serviceName with the default value defined by the class developer. This function can only be called from the constructor of a class.

For further details take a look at the property definition: serviceName.

initTimeout

public void initTimeout(java.lang.Integer arg)

Calls the apply method and dispatches the change event of the property timeout with the default value defined by the class developer. This function can only be called from the constructor of a class.

For further details take a look at the property definition: timeout.

initUrl

public void initUrl(java.lang.String arg)

Calls the apply method and dispatches the change event of the property url with the default value defined by the class developer. This function can only be called from the constructor of a class.

For further details take a look at the property definition: url.

initUseBasicHttpAuth

public void initUseBasicHttpAuth(boolean arg)

Calls the apply method and dispatches the change event of the property useBasicHttpAuth with the default value defined by the class developer. This function can only be called from the constructor of a class.

For further details take a look at the property definition: useBasicHttpAuth.

initUsername

public void initUsername(java.lang.String arg)

Calls the apply method and dispatches the change event of the property username with the default value defined by the class developer. This function can only be called from the constructor of a class.

For further details take a look at the property definition: username.

isCrossDomain

public boolean isCrossDomain()

Check whether the (computed) value of the boolean property crossDomain equals true.

For further details take a look at the property definition: crossDomain.

isUseBasicHttpAuth

public boolean isUseBasicHttpAuth()

Check whether the (computed) value of the boolean property useBasicHttpAuth equals true.

For further details take a look at the property definition: useBasicHttpAuth.

refreshSession

public void refreshSession(java.lang.Object handler)

Refreshes a server session by retrieving the session id again from the server.

The specified handler function is called when the refresh is complete. The first parameter can be true (indicating that a refresh either wasn’t necessary at this time or it was successful) or false (indicating that a refresh would have been necessary but can’t be performed because the server backend doesn’t support it). If there is a non-null second parameter, it’s an exception indicating that there was an error when refreshing the session.

resetCrossDomain

public void resetCrossDomain()

Resets the user value of the property crossDomain.

The computed value falls back to the next available value e.g. appearance, init or inheritance value depeneding on the property configuration and value availability.

For further details take a look at the property definition: crossDomain.

resetPassword

public void resetPassword()

Resets the user value of the property password.

The computed value falls back to the next available value e.g. appearance, init or inheritance value depeneding on the property configuration and value availability.

For further details take a look at the property definition: password.

resetServerData

public void resetServerData()

Resets the user value of the property serverData.

The computed value falls back to the next available value e.g. appearance, init or inheritance value depeneding on the property configuration and value availability.

For further details take a look at the property definition: serverData.

resetServiceName

public void resetServiceName()

Resets the user value of the property serviceName.

The computed value falls back to the next available value e.g. appearance, init or inheritance value depeneding on the property configuration and value availability.

For further details take a look at the property definition: serviceName.

resetTimeout

public void resetTimeout()

Resets the user value of the property timeout.

The computed value falls back to the next available value e.g. appearance, init or inheritance value depeneding on the property configuration and value availability.

For further details take a look at the property definition: timeout.

resetUrl

public void resetUrl()

Resets the user value of the property url.

The computed value falls back to the next available value e.g. appearance, init or inheritance value depeneding on the property configuration and value availability.

For further details take a look at the property definition: url.

resetUseBasicHttpAuth

public void resetUseBasicHttpAuth()

Resets the user value of the property useBasicHttpAuth.

The computed value falls back to the next available value e.g. appearance, init or inheritance value depeneding on the property configuration and value availability.

For further details take a look at the property definition: useBasicHttpAuth.

resetUsername

public void resetUsername()

Resets the user value of the property username.

The computed value falls back to the next available value e.g. appearance, init or inheritance value depeneding on the property configuration and value availability.

For further details take a look at the property definition: username.

setCrossDomain

public void setCrossDomain(boolean arg)

Sets the user value of the property crossDomain.

For further details take a look at the property definition: crossDomain.

setPassword

public void setPassword(java.lang.String arg)

Sets the user value of the property password.

For further details take a look at the property definition: password.

setServerData

public void setServerData(java.lang.Object arg)

Sets the user value of the property serverData.

For further details take a look at the property definition: serverData.

setServiceName

public void setServiceName(java.lang.String arg)

Sets the user value of the property serviceName.

For further details take a look at the property definition: serviceName.

setTimeout

public void setTimeout(java.lang.Integer arg)

Sets the user value of the property timeout.

For further details take a look at the property definition: timeout.

setUrl

public void setUrl(java.lang.String arg)

Sets the user value of the property url.

For further details take a look at the property definition: url.

setUseBasicHttpAuth

public void setUseBasicHttpAuth(boolean arg)

Sets the user value of the property useBasicHttpAuth.

For further details take a look at the property definition: useBasicHttpAuth.

setUsername

public void setUsername(java.lang.String arg)

Sets the user value of the property username.

For further details take a look at the property definition: username.

toggleCrossDomain

public boolean toggleCrossDomain()

Toggles the (computed) value of the boolean property crossDomain.

For further details take a look at the property definition: crossDomain.

toggleUseBasicHttpAuth

public boolean toggleUseBasicHttpAuth()

Toggles the (computed) value of the boolean property useBasicHttpAuth.

For further details take a look at the property definition: useBasicHttpAuth.