Api

Client

To configure the remoting providers on the client side the program needs a configuration object with all the accessible methods from the server. A call to api.js will return such a configuration:

    <script type="text/javascript" src="action/api.js"></script>

action must match the url-pattern value of the DispatcherSerlvet in web.xml.

The output of this call will be created on the fly. api.js returns the output on one line. If you need a more readable output for debugging change the call to api-debug.js:

    <script type="text/javascript" src="action/api-debug.js"></script>

After the api configuration import add the object to Ext.Direct with the addProvider method.

      //Ext JS 3
      Ext.Direct.addProvider(Ext.app.REMOTING_API);

      //Ext JS 4.x and Sencha Touch 2
      Ext.direct.Manager.addProvider(Ext.app.REMOTING_API); 

After this statement the remote methods are accessible from JavaScript.

If there are remoting and polling methods in the configuration it's possible to add the providers in one call.

      //Ext JS 3
      Ext.Direct.addProvider(Ext.app.REMOTING_API, {
        id : 'messageProvider',
        type : 'polling',
        url : Ext.app.POLLING_URLS.message
      });

      //Ext JS 4.x and Sencha Touch 2
      Ext.direct.Manager.addProvider(Ext.app.REMOTING_API, {
        type: 'polling',
        url: Ext.app.POLLING_URLS.message
      });

Parameters

api.js supports these query parameters:

Request Parameter	Description	Default
apiNs	Namespace the remoting api variable will be created in	Ext.app
actionNs	Namespace the action beans will be created in	Browser global scope
remotingApiVar	Name of the remoting api variable	REMOTING_API
pollingUrlsVar	Name of the variable which contains the polling URLs	POLLING_URLS
group	Name of one or more api groups. Multiple groups separated with comma. Since 1.3.1: When group is an empty string api.js returns all methods that do not have a group attribute or do have a group attribute with an empty value
fullRouterUrl	true or false. If true the URL property contains the full router URL including protocol, server name, port number, and server path	false
baseRouterUrl (since 1.3.2)	If not null the ApiController does not use the url of the request to determine the router url instead he uses the value of this parameter and adds /router, /poll and /sse /controller/api.js?baseRouterUrl=myrouterurl //Output Ext.app.REMOTING_API = { "url" : "myrouterurl/router", ... }

Example

    <script type="text/javascript" src="action/api.js?apiNs=RemoteNs&actionNs=MyApp&remotingApiVar=REMOTEAPI&pollingUrlsVar=POLLURLS"></script>

The example above will create a RemoteNs.REMOTEAPI variable:

    //Ext JS 3
    Ext.Direct.addProvider(RemoteNs.REMOTEAPI);

    //Ext JS 4.x and Sencha Touch 2 
    Ext.direct.Manager.addProvider(RemoteNs.REMOTEAPI);

Actions are part of the MyApp namespace:

      MyApp.testAction.doEcho('test', function(result, e){...}); 

Polling URLs are part of the POLLURLS object:

    //Ext JS 3
    Ext.Direct.addProvider({
      type: 'polling',
      url: RemoteNs.POLLURLS.message
    });

    //Ext JS 4.x and Sencha Touch 2 
    Ext.direct.Manager.addProvider({
      type: 'polling',
      url: RemoteNs.POLLURLS.message
    });

Group

If an application consists of multiple HTML pages and the JavaScript code does not need to access all server methods on every page, it's possible to group the methods and expose only a subset of the server methods on a certain page.

Example
There are two server methods available and we only want to call the first method on one page and the second method on another page.

The first thing to do is add an attribute group to the @ExtDirectMethod annotation.

    @Component
    public class TestAction {
      @ExtDirectMethod(group = "group1")
      public long multiply(long num) {
        ...
      }
    
      @ExtDirectMethod(group = "group2")
      public String doEcho(String message) {
        ...
      }
    }

A method can be part of more than one group. The group names have to be separated with a comma @ExtDirectMethod(group = "group3,group4,group5")

On the first HTML page we add this script tag. The api.js will only import the configuration for the multiply method.

    <script type="text/javascript" src="action/api.js?group=group1"></script>

And on the second page we use this script tag. That call will only import the doEcho method.

    <script type="text/javascript" src="action/api.js?group=group2"></script>

The query parameter group can request more than one group. The following example imports both methods into the code.

    <script type="text/javascript" src="action/api.js?group=group1,group2"></script>

Since 1.3.1:
The value of the query parameter can be an empty string. The following example returns every method that does not have a group attribute specified on the @ExtDirectMethod annotation or does have a group attribute with an empty value group=""

    <script type="text/javascript" src="action/api.js?group="></script>

or without the equals sign (=)

    <script type="text/javascript" src="action/api.js?group"></script>

Caching (since 1.2.1)

When the request to api.js is fingerprinted the library adds the following http headers to the response:

• Vary
• Expires
• ETag
• Cache-Control

These headers should force the client to cache the response. A fingerprinted request looks like this:

      <script type="text/javascript" src="action/api-1.0.js"></script>

After the word 'api' a hyphen and after that any character follows.
More Examples: api-a.js, api-1.1.1.js, api-ac12e5f914.js, api-20120808101545.js

Example

Request to api.js

HTTP/1.1 200 OK
Date: Tue, 02 Oct 2012 06:06:22 GMT
Content-Type: application/javascript;charset=UTF-8
Vary: Accept-Encoding

Request to api-1.0.js

HTTP/1.1 200 OK
Date: Tue, 02 Oct 2012 06:05:40 GMT
Vary: Accept-Encoding
Expires: Sun, 31 Mar 2013 06:05:40 GMT
ETag: "04feffd452e5177c41d874defb0ae4a1c"
Cache-Control: public, max-age=15552000
Content-Type: application/javascript;charset=UTF-8