Simple Method

Server

The methods that should be accessible from JavaScript need to be annotated with @ExtDirectMethod. Such an annotated method has to be a member of a Spring managed bean.

@Service
public class TestAction {

  @ExtDirectMethod
  public String doEcho(String message) {
    return message;
  }

  @ExtDirectMethod
  public int anotherAction() {
    return 1;
  }
}

If the methods need access to server objects, like request and response, add the parameters to the method signature.

  @ExtDirectMethod
  public String doEcho(String message, HttpServletRequest request) {
    //do something with the request
    return message;
  }

ExtDirectSpring supports these server object parameters:

• HttpServletResponse
• HttpServletRequest
• HttpSession
• Locale
• Principal
• Parameters annotated with @RequestHeader (since 1.1.0)

Server object parameters may be added in any order.

  @ExtDirectMethod
  public String doSomething(HttpServletResponse response, int fromClient1,
                            HttpServletRequest request, int fromClient2, 
                            Locale locale, int fromClient3) {
    //do something here
  }

The client does not see these server object parameters and calls the doSomething method like this testAction.doSomething(1, 2, 3, callback);

The library also supports @DateTimeFormat and @NumberFormat annotation.

  @ExtDirectMethod
  public Map<String, Object> aMethod(@DateTimeFormat(iso = ISO.DATE_TIME) Date aDate, 
                                     @NumberFormat(style = NumberFormat.Style.PERCENT) BigDecimal percent) {
    ...
  }

Client

The name of the Spring bean is the action name on the client side. This statement testAction.doEcho('ping', callback) will call the method doEcho in the Spring bean testAction on the server. Calls from the client are asynchronous therefore the applications needs to provide a callback function if it expects a response. The callback function is the parameter after the values in the method call. If the server method does not expect any parameters the callback can be the first parameter testAction.anotherAction(callback). There is no need to provide a callback function if the client does not expect any response from the server (fire and forget call). The next parameter after the callback function is the scope in which the callback should run in: testAction.doSomething(1, 2, 3, callback, this). As the last parameter it is possible to provide an option object. Right now the only supported config parameter is 'timeout'. If this option is set it will disable buffering for this call only. testAction.doSomething(1, 2, 3, callback, this, {timeout: 10000}) (docs)

The order and number of the parameters is important and has to match the method signature on the server side (without the server objects).

Callback function, scope and option object parameters are optional. testAction.doEcho('ping') is a perfect valid method call if the server method expects one String argument.

Callback function

  var callback = function(result, e) {
    // do something with the result
  }; 

The function is called when the server returns a result or throws an exception. A Ext.Direct callback function is called with two arguments:

• result - this argument contains the data the server method returned
• e - is a Ext.Direct.RemotingEvent (Ext JS 3) or Ext.direct.RemotingEvent (Ext JS 4.x and Sencha Touch 2)

The event object has some useful properties and methods:

• status - true if the call was successful, false if something went wrong.
• result - contains the same data as the first parameter
• type - is 'rpc' or 'exception' if an error occurred
• action - the name of the bean. In this example 'testAction'
• method - the name of the method ('doEcho')
• tid - a transaction number
• getTransaction() - retrieves the transaction used in this server call. This object contains some more information about the call. e.g. transaction.args contains the arguments the method was originally called with.

Events

The Direct Manager supports two events event and exception. The event is fired every time a direct call is returned to the client. The exception is fired when an exception occurred. A program can simply listen to those events by adding listeners to the Ext.direct.Manager

  //Ext JS 4.x and Sencha Touch 2
  
  Ext.direct.Manager.on('event', function(e) {
    //do something here
  });

  Ext.direct.Manager.on('exception', function(e) {	
    //do something here
  });