Apex コントローラの JavaScript Remoting

Visualforce ページへの JavaScript Remoting の追加

1[namespace.]controller.method(
2    [parameters...,]
3    callbackFunction,
4    [configuration]
5);

リモートメソッドコールは同期して実行されますが、応答が返されるのを待機しません。応答が返されると、コールバック関数は非同期で応答を処理します。詳細は、「リモート応答の処理」を参照してください。

JavaScript Remoting 要求の設定

1{ buffer: true, escape: true, timeout: 30000 }

1<script type="text/javascript">
2
3    Visualforce.remoting.timeout = 120000; // Set timeout at page level
4
5    function getRemoteAccount() {
6        var accountName = document.getElementById('acctSearch').value;
7
8        // This remoting call will use the page's timeout value
9        Visualforce.remoting.Manager.invokeAction(
10            '{!$RemoteAction.AccountRemoter.getAccount}',
11            accountName, 
12            handleResult
13        );
14    }
15
16    function handleResult(result, event) { ... }
17</script>

ページレベルのタイムアウト設定を要求単位で上書きするには、その要求の設定オブジェクトのタイムアウトを、上記の説明に従って設定します。

JavaScript Remoting の OAuth 2.0 認証

JavaScript Remoting 要求では、認証に標準のユーザ名とパスワードによるログインプロセスではなく、OAuth 2.0 を使用できます。OAuth では、標準の認証ではセキュアに実行できないアプリケーション間および組織間統合が可能です。

Visualforce ページでは、認証用の OAuth がページレベルで設定され、すべての JavaScript Remoting 要求に OAuth が使用されます。設定を除き、JavaScript Remoting の使用法はまったく同じです。

1<script type="text/javascript">
2
3    Visualforce.remoting.oauthAccessToken = <access_token>;
4
5    // ...
6</script>

oauthAccessToken は、ページのコードで取得される OAuth 認証トークンです。アクセストークンの取得と更新は簡単な OAuth で直接行われ、追加部分が 1 つあります。JavaScript Remoting の OAuth 認証では "visualforce" スコープが要求されるため、このスコープを使用するか、これを含むスコープ ("web" や "full") を使用してトークンを生成する必要があります。OAuth 要求で、scope=visualforce (あるいは "web" または "full") と設定します。

アクセストークンの取得および Force.com プラットフォームでの OAuth の使用についての詳細は、Salesforce オンラインヘルプの「リモートアクセスアプリケーションの認証」、および developer.salesforce.com/page/Digging_Deeper_into_OAuth_2.0_on_Force.com を参照してください。

名前空間および JavaScript Remoting

1Visualforce.remoting.Manager.invokeAction(
2    'fully_qualified_remote_action', 
3     invocation_parameters
4);

完全修飾リモートアクションは、namespace[.BaseClass][.ContainingClass].ConcreteClass.Method のように、名前空間、ベースクラスなどを含むリモートアクションメソッドへの完全なパスを表す文字列です。名前空間を自動的に解決するには、たとえば、{!$RemoteAction.MyController.getAccount} のように、式に $RemoteAction を使用します。

1<script type="text/javascript">
2function getRemoteAccount() {
3    var accountName = document.getElementById('acctSearch').value;
4
5    Visualforce.remoting.Manager.invokeAction(
6        '{!$RemoteAction.MyController.getAccount}', 
7        accountName, 
8        function(result, event){
9            if (event.status) {
10                document.getElementById('acctId').innerHTML = result.Id
11                document.getElementById('acctName').innerHTML = result.Name;
12            } else if (event.type === 'exception') {
13                document.getElementById("responseErrors").innerHTML = event.message;
14            } else {
15                document.getElementById("responseErrors").innerHTML = event.message;
16            }
17        }, 
18        {escape: true}
19    );
20}
21</script>

リモートメソッドの宣言

1@RemoteAction
2global static String getItemId(String objectName) { ... }

���ソッドでは、引数として、Apex プリミティブ、コレクション、型指定された sObject、汎用 sObject、ユーザ定義された Apex クラスおよびインターフェースを取ることができます。汎用 sObject では、実際の型を特定するために ID または sobjectType の値を指定する必要があります。インターフェースパラメータでは、実際の型を特定するために apexType を指定する必要があります。

メソッドでは Apex プリミティブ、sObject、コレクション、ユーザ定義された Apex クラスおよび列挙、SaveResult、UpsertResult、DeleteResult、SelectOption、または PageReference を返すことができます。

リモートメソッドと継承

@RemoteAction メソッドが検索またはコールされる場合、Visualforce ではページコントローラの継承階層を調べ、コントローラの上位階層のクラス内で @RemoteAction メソッドを検索します。

1global with sharing class ChildRemoteController 
2    extends ParentRemoteController { }
3global virtual with sharing class ParentRemoteController 
4    extends GrandparentRemoteController { }
5
6global virtual with sharing class GrandparentRemoteController {
7    @RemoteAction
8    global static String sayHello(String helloTo) {
9        return 'Hello ' + helloTo + ' from the Grandparent.';
10    }
11}

1swfobject.registerObject("clippy.codeblock-8", "9");<apex:page controller="ChildRemoteController" >
2    <script type="text/javascript">
3        function sayHello(helloTo) {
4            ChildRemoteController.sayHello(helloTo, function(result, event){
5                if(event.status) {
6                    document.getElementById("result").innerHTML = result;
7                }
8            });
9        }
10    </script>
11
12    <button onclick="sayHello('Jude');">Say Hello</button><br/>
13    <div id="result">[Results]</div>
14    
15</apex:page>

インターフェースパラメータによるリモートメソッドの宣言

具象クラスに制限するのではなく、インターフェースパラメータと戻り値のデータ型を使用して @RemoteAction メソッドを宣言できます。これにより、たとえば、パッケージプロバイダは、リモートメソッドと関連付けられたインターフェースをパッケージ化できます。登録者組織は、パッケージ化されたインターフェースを実装する独自のクラスに渡すことによって、Visualforce ページからコールできます。

1public class RemoteController {
2    public interface MyInterface { String getMyString(); }
3    public class MyClass implements MyInterface { 
4        private String myString; 
5        public String getMyString() { return myString; }
6        public void setMyString(String s) { myString = s; }
7    }
8    
9    @RemoteAction
10    public static MyInterface setMessage(MyInterface i) {
11        MyClass myC = new MyClass();
12        myC.setMyString('MyClassified says "' + i.getMyString() + '".');
13        return myC;
14    }
15}

1Visualforce.remoting.Manager.invokeAction(
2    '{!$RemoteAction.RemoteController.setMessage}',
3    {'apexType':'thenamespace.RemoteController.MyClass', 'myString':'Lumos!'}, 
4    handleResult
5);

1RemoteController.setMessage(
2    {'apexType':'c.RemoteController.MyClass', 'myString':'Lumos!'}, 
3    handleResult
4);

リモート応答の処理

リモートメソッドコールに対する応答は、リモートメソッドコールで提供されているコールバック関数によって非同期に処理されます。コールバック関数は、リモートコールの状況を表す event オブジェクト、およびリモート Apex メソッドで返される result オブジェクトをパラメータとして取得します。関数は返されるデータに基づいてページの情報およびユーザインターフェース要素を更新できます。

string または number など、result によって返される Apex プリミティブデータ型は対応する JavaScript に変換されます。返される Apex オブジェクトは JavaScript オブジェクトに変換され、コレクションは JavaScript 配列に変換されます。JavaScript は大文字と小文字を区別することに注意してください。そのため、id、Id、および ID は異なる項目であるとみなされます。

JavaScript リモートコールの一部として、Apex メソッド応答に同じオブジェクトに対する参照が含まれる場合、そのオブジェクトは返される JavaScript オブジェクトには複製されません。代わりに、表示される JavaScript オブジェクトには同じオブジェクトへの参照が含まれます。たとえば、同一オブジェクトを 2 回含むリストを返す Apex メソッドです。

デフォルトでは、リモートコールの応答は、30 秒以内に返される必要があります。これを超えると、コールはタイムアウトになります。要求の完了にこれ以上の時間を必要とする場合は、長いタイムアウトを 120 秒以内で設定します。

リモートコールの応答の最大サイズは 15 MB です。

1swfobject.registerObject("clippy.codeblock-12", "9");<script type="text/javascript">
2function getRemoteAccount() {
3    var accountName = document.getElementById('acctSearch').value;
4
5    Visualforce.remoting.Manager.invokeAction(
6        '{!$RemoteAction.MyController.getAccount}', 
7        accountName, 
8        function(result, event){
9            if (event.status) {
10                document.getElementById('acctId').innerHTML = result.Id
11                document.getElementById('acctName').innerHTML = result.Name;
12            } else if (event.type === 'exception') {
13                document.getElementById("responseErrors").innerHTML = 
14                    event.message + "<br/>\n<pre>" + event.where + "</pre>";
15            } else {
16                document.getElementById("responseErrors").innerHTML = event.message;
17            }
18        }
19    );
20}
21</script>

JavaScript Remoting および <apex:actionFunction>

通常、<apex:actionFunction> の方が使いやすく、必要なコードも少なくなります。一方、JavaScript では、より高度な柔軟性を提供できます。