サンプル実装の概要

ハンズオンの指示に従って構築するサンプル・アプリケーションは、モバイル・クライアント上でヘルパー・クラスを使用してリモートのREST/JSONサービスにアクセスし、JSONペイロードを解析してJavaオブジェクトに変換します。

このチュートリアルでは、REST/JSON Webサービスに基づくサンプルのOracle Mobile Application Framework（Oracle MAF）アプリケーションを作成する方法について順を追って説明します。

入力の手間を省いてモバイル・アプリケーションの構築に集中できるようにするため、ほとんどのJavaコンテンツは事前に構築されており、必要に応じてコードをコピー/貼付けできます。このチュートリアルでは、開発者の作業を簡素化し、MAFベスト・プラクティスに準拠した実用的なクライアント・インフラストラクチャを開発することに重点が置かれています。

以下に、このサンプルで使用するクラス階層図を示します。DeptEmpDCデータ・サービス・クラスは、部門および従業員データのコレクションと、作成、更新、削除といったデータ操作メソッドを提供します。このデータ・サービス・クラスはMAFデータ・コントロールとして公開されるため、ファイル名の末尾には"DC"が付いています。

DepartmentsEntityクラスとEmployeesEntityクラスは、エンティティと呼ばれるデータ・オブジェクトを表します。これらのクラスは部門および従業員の状態を保持し、データを表示、更新するためにMAF内で使用されます。

RESTサービスを使用したデータの読取りには、いくらかの追加処理が必要です。この例では、2つのヘルパー・クラス（DepartmentsResultArrayとEmployeesResultArray）を使用してJSON変換を実行します。各クラスが特定のJSONペイロードの構造を再現しているため、MAF固有のフレームワーク・クラスを使用してJSONペイロードの中身をJavaオブジェクト構造にコピーできます。

DepartmentsEntityToJsonクラスとこれに対応する従業員のエンティティ・クラスは、書込み操作用に、JavaオブジェクトをJSON形式に戻します。

最後に、DeptEmpURIクラスには、特定のRESTリクエスト（検索、更新、読取り、削除など）に対してリクエストURIを返すメソッドが含まれます。ヘルパー・クラスを使用することで、実際に開発者はサーバー側で使用可能なREST　URIについて把握する必要がなくなります。このクラスは、サーバー側のREST実装からモバイル・アプリケーション開発を抽象化します。

RestCallerUtilクラスはRESTサービスに対するMAFコールをラッピングすることで、RESTインタラクションをさらに簡素化するため、開発者は不要な定型挿入文を何度も書く必要がありません。

このチュートリアルはRESTサービスの作成方法を説明するものではなく、サービスの処理内容とローカルWebLogic Serverインスタンスへのデプロイ方法についてのみ説明します。

目的	所要時間	アプリケーション
このチュートリアルでは、Mobile Application FrameworkとREST/JSONサービスを使用してアプリケーションを開発する方法について説明します。このチュートリアルで作成するアプリケーションの完成版やスタータ・アプリケーション、コード・ファイルを確認するには、「Download」ボタンをクリックしてソリューション・アプリケーションのzipファイルをダウンロードし、JDeveloperのmyworkフォルダに解凍してください。パート2および3に対するソリューションは、各パートの冒頭部分でダウンロードできます。	2.5時間

 

はじめに、RESTサービスのソースを含むサンプル・ワークスペースを開き、各自のローカル・データベースとHRスキーマを指すデータベース接続を構成する必要があります。

1. Oracle JDeveloperをインストールしたマシンに、チュートリアルのmaf_rest_json_files zipファイルを解凍します。

2. MAF REST Tutorial/ MAF_REST_SRCディレクトリにあるTutorialHrRestServiceサンプル・リソース・フォルダを、名前に空白文字が含まれないローカル・ディレクトリ・パスにコピーします。コピーしない場合、AndroidエミュレータでのMAFモバイル・アプリケーションのテスト時に問題が発生する可能性があります。

3. Oracle JDeveloper 12.1.3を開きます。

4. メニューから「Application」→「Open」を選択します。

5. TutorialHrRestServiceフォルダをコピーした場所へ移動し、フォルダを開いて「TutorialHrRestService.jws」ワークスペース・ファイルを選択します。
   「OK」をクリックして、JDeveloperでこのファイルを開きます。

6. Oracle JDeveloperには2つのプロジェクトが表示されます。EjbHrModelはデータベースの問合せと更新を行うEJBプロジェクトです。RestServiceはJAX-RSアノテーションの付いたPOJOプロジェクトであり、EjbHrModelプロジェクトの機能をRESTサービスとして公開します。

RESTサービスによって公開されるEJBモデルは、Oracle HRサンプル・スキーマ内のDepartments表とEmployees表に基づいて構築されています。

1. JDeveloperメニューから「Window」→「Database」→「Databases」を選択して、データベース接続ブラウザ・ウィンドウを開きます。

2. JDeveloperのApplicationsウィンドウで「Databases」タブをクリックします。
   次に、TutorialHrRestServiceノードを開き、「hrconn」エントリを右クリックします。



3. 表示されるメニューで「Properties」を選択します。

4. 表示されるEdit Database Connectionsダイアログで、Username、Password、Host Name、JDBC Port、SIDの設定を、ローカル・データベースの設定とインストールしたHRスキーマに合わせて変更します。XEデータベースを実行している場合は、事前設定された構成を変更する必要はありません。



5. 「Test Connection」ボタンをクリックしてデータベース接続の動作を確認します。
   接続に成功したら、「OK」をクリックします。



.

このチュートリアルでは、RESTサービスをデプロイしてテストするために、Oracle JDeveloper内の統合Oracle WLSを使用します。

1. 「Run」→「Start Server Instance (IntegratedWebLogicServer)」を選択して、Oracle WLSを起動します。

2. 統合Oracle WLSを初めて実行する場合は、Create Default Domain ダイアログ・ボックスが開きます。デフォルトのOracle WLSドメインを作成して、パスワードを設定します。
   
   注：統合Oracle　Web Logic Serverで、使用するマシンを指すすべてのエイリアス（"localhost"やコンピュータのIPアドレスを含む）をリスニングする場合は、Listen Addressからいずれのアドレスも選択しないでください。

3. 「OK」をクリックして変更を保存し、Oracle ADFのデフォルト・ドメインの作成と構成を実行します。Oracle WebLogic Serverによってデフォルト・ドメインが作成され、サーバーが起動されます。

4. 統合Oracle WLSが起動するまで待ってから、次の手順に進みます。サーバーを初めて起動する場合は、WLSドメインが構築されます。この処理には数分かかる場合があります。
   
   

RESTを使用することは、Uniform Resource Locator（URL）で指定されたリソースを使用することにほかなりません。RESTにおけるリソースという用語は抽象的であり、人物や注文、予約から従業員やデータベース表から取得した行リストまで多岐にわたります。

このチュートリアルのサービスで公開されるリソースは、HRスキーマから取得されるDepartmentsデータとEmployeesデータです。データに問合せを実行するEJB/Toplinkモデルは、JAX-RSアノテーション付きPOJOクラスを使用して開発されたRESTサービスを介して、モバイル・クライアントに公開されています。ここでは、Oracle JDeveloperのHTTP Analyzerを使用して、RESTサービスの調査とテストを行うことで、構成されたREST URIとその使用方法について学習します。

1. Oracle JDeveloperで「Applications」タブに切り替えて、RestServiceプロジェクト・ノードを開きます。

2. Application Resourcesノードからmaf.code.corner.sample.rsパッケージを開くと、
   4つのパッケージが表示されます。



lists ：JavaオブジェクトをXMLとJSONに変換するためのJAXBを使用するヘルパー・クラスを含みます。

resources ：部門リソースと従業員リソースの実装クラスを含みます。ここで、メソッドの構成とREST URIへのマッピングを行うためのJAX-RSアノテーションが追加されます。読みやすく、管理を容易にするため、EJBレイヤーにアクセスする実際のコードはbaseパッケージのクラス内に定義されています。resourcesパッケージ内の2つのクラスに含まれるのは、REST固有のコードとアノテーションのみです。

services ：シングル・ルート・サービスであるHrRestServiceからアクセスできる部門リソースと従業員リソースを含みます。HrRestServiceクラスはルートURIアノテーションを含み、resourcesパッケージ内の2つのクラスに対してディスパッチします。HrRestService.javaクラスが、このチュートリアルで実際に実行してテストするRESTサービスです。

xsd ：XMLペイロードを使用するRESTサービスをMAF内に構成する場合、XSDスキーマ・ファイルが必要になります。これにより、REST URIコールによってどのペイロード構造が返される（または期待される）かをJDeveloper IDEが把握できるため、適切なデータ・コントロール構造が自動的に生成されます。



3. servicesパッケージ・ノードを開き、「HrRestService」エントリを右クリックします。
   コンテキスト・メニューから「Test Web Service」を選択して、JDeveloperのHTTP Analyzer内でRESTサービスを実行します。

   

4. JDeveloperによってRESTサービスが統合Oracle WLSサーバー・インスタンスにデプロイされ、HTTP Analyzerが開きます。HTTP Analyzerでは、使用可能なREST URIマッピングを参照して、サービスを検証するためにこれらのマッピングを実行できます。
   
   あらかじめ表示されていない場合は、メニューから「Window」→「Log」を選んでJDeveloperのLogウィンドウを開きます。Logウィンドウには、RESTサービスのデプロイ進行状況と、RESTサービスのテスト中に発生する可能性のあるすべてのエラーが表示されます。
   デプロイが成功すると、ログ・メッセージの最後に2つのリンクが表示されます。WADL（Web Application Description Language）の参照とRESTサービスのルートURLを示すターゲットURLの参照です。このルートURL（http://127.0.0.1:7101/hrrest/resources/hrappsrvc）は、REST接続を作成するために、後からMAFで必要になります。WADLファイルはRESTサービスを記述したものであり、すべてのメソッドとレスポンスが含まれます。必要に応じて、WADLリンクをクリックし、そこからRESTサービスをテストできます。

   [Application TutorialHrRestService running on IntegratedWebLogicServer]
   Target Application WADL -- http://localhost:7101/hrrest/resources/application.wadl
   Target URL -- http://127.0.0.1:7101/hrrest/resources/hrappsrvc
   
   

5. デプロイの直後にHTTP Analyzerが開き、URL、WADL URI、使用可能な操作が表示されます。

   

6. Operationsプロパティで使用可能な操作のリストを開くと、メソッドとREST URIマッピングのリストが表示されます。
   departmentsノードを開き、「getDepartmentsList GET」エントリを選択します。
   
   ヒント：リストが表示されない場合は、HTTP Analyzerウィンドウの下部で「REST Structure」タブを選択します。

   

7. URLフィールドに表示されたhttp://localhost:7101/hrrest/resources/hrappsrvc/departmentsという値に注目します。このURLフィールドは、GETリクエストが使用するREST URLを示しています。getDepartmentsListはこのURIにマップされたメソッドです。このメソッドの詳しい実装はテスト中にHTTP Analyzerで確認できますが、後からMAF内で確認することはできません。

   「Send Request」ボタンをクリックして、デプロイ済みのサービスURLに対してGETリクエストを発行します。
   
   

8. 設定に基づいてJSONレスポンスが表示され、次の図のように部門リストが表示されます。

   
   

9. Send Requestボタンの上にあるRequest HTTP Headersセクションを開きます。

   
   

10. Acceptヘッダー・プロパティの値をapplication/xmlのみを含むように変更します。別のヘッダー・フィールドをクリックすると、Acceptヘッダーの変更が確定されます。

11. もう一度「Send Request」ボタンをクリックします。同じ部門リストがRESTサービスから返されますが、今回はXML形式で表示されます。

    
    

12. 次に、新しい部門を作成します。Operationsリストから「create PUT application/json」を選びます。これはJSON形式のRESTリクエスト・タイプです。

    先ほどと同様に、リクエストはhttp://localhost:7101/hrrest/resources/hrappsrvc/departmentsというREST URLに送信されます。ただし、今回使用するhttpメソッドはPUTであり、このメソッドはRESTのJava実装内の新部門作成メソッドにマップされています。
    
    下図に示すとおりに入力フォームに入力したら、「Send Request」ボタンをクリックします。レスポンスとして、HTTP Analyzerの右側にあるResponse HTTP Headersラベルの下にメッセージが表示されます。
    
    
    

13. JDeveloperのメニューから「Window」→「Database」→「Databases」を選択します。TutorialHrRestService →hrconn→Tablesノードを開きます。

    
    

14. 「Departments」表エントリをダブルクリックします。
    次に、表の概要エディタの下部にある「Data」タブをクリックし、新しく作成したレコードが見つかるまで下にスクロールします。
    「Departments」表タブを閉じて、HTTP Analyzerに戻ります。

    
    

15. Operationsリストで、departments→remove/{departmentId}ノードを開き、「delete DELETE」エントリを選択します。

    
    
    

16. URLフィールドの変化に注目します。

    http://localhost:7101/hrrest/resources/hrappsrvc/departments/remove/departmentId

    URLのdepartmentId部分を1234という値で置き換えると、URLは次のようになります。http://localhost:7101/hrrest/resources/hrappsrvc/departments/remove/1234

    URLの最後に付加されたdepartmentIdは、RESTサービスがDELETEメソッドに対して解析するURLパラメータです。
    
    
    
    

17. もう一度、「Send Request」ボタンをクリックすると、RESTサービスが部門1234を削除します。HTTP Analyzerタブに、DELETEメソッドに対するレスポンスとして、「200 OK」というメッセージが表示されます。これは、この行がデータベースから削除されたことを示しています。

    
    
    

    Departmentsタブ内のデータを確認すると、トレーニング部門が含まれていないことが分かります。

    
    

18. Operationsリストをもう一度開き、departments→{departmentId}/employeesノードを開きます。次に、「getEmployeesInDepartment GET」エントリを選択します。

    
    

19. URLフィールドの値を

    http://localhost:7101/hrrest/resources/hrappsrvc/departments/departmentId/employees

    から以下に変更します。

    http://localhost:7101/hrrest/resources/hrappsrvc/departments/60/employees

    このURLは、IT部門（60）で働く全従業員を問い合わせます。「Send Request」ボタンをクリックします。その結果、下図のように、JSON形式のレスポンスが表示されます。
    
    
    
    注：レスポンスのペイロードがJSONになっているのは、JSONとXMLの両方に対応するリクエストに対するRESTサービスでの構成に従っているためです。
    このリクエストに対するAcceptヘッダーの値をapplication/xmlのみに変更すると、同じリクエストに対するレスポンス形式としてXMLが返されます。
    また、表示されるJSON文字列には、従業員のコレクションを含む“employees”文字列のほかに、最初には“{“が、最後には“}“が付けられています。
    
    JSONのコレクションは角かっこ（“[“と“]”）で囲まれ、さらにそれぞれのオブジェクトが中かっこ（“{“と“}“）で囲まれます。

    JSONペイロードはかなり柔軟であり、単一キーと値のペア、コレクション、オブジェクトの組合せを含めることができます。
    

20. （オプション）Logウィンドウに戻り、ログ出力に表示されたWADLリンクをクリックします。WADL概要エディタのレコードが表示されます。

    
    
    

    WADLダイアログを使用してRESTサービスを詳しく確認したら、このサービスをテストします（URIエントリの横にある「Test」ボタンをクリック）。「Test」ボタンをクリックすると、再度HTTP Analyzerが表示され、テスト対象のリクエストURIにURLが設定されています。

    
    

このステップでは、MAFモバイル・クライアント・ワークスペースを作成して、すべてのアプリケーション・コンポーネントを格納します。

1. JDeveloperのメニューから「File」→「New」→「Application」を選択し、New Galleryで、「General」→「Applications」→「Mobile Application Framework Application」を選択します。
   「OK」をクリックします。

2. Application NameにMAFRESTを指定し、Application Package Prefixにmaf.code.corner.hrを指定します。
   Directoryプロパティに空白文字が含まれないようにします。空白文字が含まれると、デプロイ中に問題が発生する場合があります。
   「Finish」をクリックします（こうすることで、このワークスペース・プロジェクトに対するApplicationControllerとViewControllerのデフォルト・ネーミング規則が採用されます）。




3. アプリケーションは、デバイスのネットワーク経由でWebサービスにアクセスする必要があります。
   Application Resourcesのmaf-application.xmlを開き、Device Accessで「Network」チェック・ボックスを選択します。

作成したMAFアプリケーションからRESTサービスにアクセスするための接続が必要です。実際の状況では、RESTサービスがリモート・サーバー上にあり、データベースが別のサーバー上に配置されることもあります。ただし、このチュートリアルでは、すべてが開発マシン上のローカルに存在します。RESTサービスにアクセスするためのルートURLは次のとおりです。

http://127.0.0.1:7101/hrrest/resources/hrappsrvc

注：デプロイしたRESTサービスのURLが変わった場合も、簡単にルートURLを変更できます。または、ホスト名またはIPアドレスを含むように設定することもできます。

この項では、RESTサービスにアクセスするための接続を作成します。

1. 「ViewController」プロジェクト・ノードを右クリックして、「New」→「From Gallery」を選択します。
   General→Connectionsノードを開き、「REST Connection」項目を選択します。
   「OK」をクリックします。

   

2. 次の値を使用して「Create REST Connection」ダイアログに入力し、「Test Connection」をクリックしてRESTサービスへのアクセスを確認します。

   Name	DeptEmpRestConn
   URL Endpoint	http://127.0.0.1:7101/hrrest/resources/hrappsrvc

   
   
   
   

   注：RESTサービスの接続情報を変更する場合は、Application Resources→Connections→RESTノードを開き、「DeptEmpRestConn」を右クリックして「Properties」メニュー・オプションを選択します。
   
   残りのチュートリアルでは、表示される物理的なREST URLではなく接続名を使用します。
   

3. Androidエミュレータをテストに使用する場合、localhost（127.0.0.1）は有効ではありません。代わりに、ホスト・アドレスとして10.0.2.2を使用する必要があります。これは、ホスト・ループバック・インタフェースに対する特別なエイリアスです。下図に示すとおりにREST接続を設定し、localhost（127.0.0.1）の参照部分を10.0.2.2に変更します。
   
   注：10.0.2.2の代わりに、コンピュータに割り当てられた実際のIPアドレスを使用することもできます（コンピュータがネットワーク上にある場合）。

これで、このチュートリアルのパート1が完了しました。パート2では、クラスを追加してクライアント・インフラストラクチャを実装します。