Simple Method

How to configure and call a simple remote method

Server

The methods that should be accessible from JavaScript need to be annotated with @ExtDirectMethod. The methods have to be members 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 needs 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 besides the parameters. @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 always asynchronous therefore they need a callback function, that gets called when the server returns a result. The callback function is the parameter after the values in the method call. If the server method does not have any parameters the callback is the only parameter {{{testAction.anotherAction(callback)}}}. As the last parameter it's possible to specify the scope in which the callback should run in: {{{testAction.doSomething(1, 2, 3, callback, this)}}}.

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

The callback function is not mandatory. If the program implements some sort of fire-and-forget messages omit the callback function.

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 is fired when an exception occurred. A program can simply listen to this 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
  });	

---

Examples

• http://eds.rasc.ch/demo/extjs3/simple.html

• http://eds.rasc.ch/demo/extjs3/direct.html

• http://eds.rasc.ch/demo/extjs4/direct.html

• http://eds.rasc.ch/demo/extjs41/direct.html