ローカルHTMLおよびアプリケーション・コンテナAPI

B ローカルHTMLおよびアプリケーション・コンテナAPI

この章では、MAF JavaScript API拡張機能、MAFコンテナ・ユーティリティAPI、およびカスタムHTML SpringboardアプリケーションなどのHTMLアプリケーション機能を対象としたAdfmfJavaUtilities APIの使用方法について説明します。

この章の内容は次のとおりです。

MAF APIを使用したカスタムHTML Springboardアプリケーション機能の作成

JavaScript API拡張機能をコールすることで、HTMLで作成されたカスタム・スプリングボード・ページにナビゲーション機能を追加します。

JavaScriptを使用してJavaScript API拡張機能をコールすることで、HTMLで作成されたカスタムSpringboardページにナビゲーション機能を追加できます。「HTMLコンテンツによるカスタムSpringboardアプリケーション機能に関する必知事項」で説明したように、JavaScript <script>タグにメソッドを追加することで、コールバックを有効にしてApache Cordovaを使用できます。次の例は、このタグを使用したCordovaのコール方法を示しています。

...
<script type="text/javascript">if (!window.adf) window.adf = {}; 
                                   adf.wwwPath = 
 "/~maf.device~/www/";</script> 
 <script type="text/javascript" src="/~maf.device~/www/js/base.js"></script>
...

base.jsのインクルード時に仮想パス/~maf.device~/を使用して、ブラウザがリクエストをリモート・サーバーではなくMAFリソースに対するものとして識別できるようにすることをお薦めします。このアプローチはリモートとローカルの両方のHTMLページで機能するので、(提供元にかかわらず) base.jsをHTML機能にインクルードする方法として最適です。「リモート・アプリケーションによるコンテナ・サービスへのアクセスの有効化」を参照してください。

ヒント:

www/jsディレクトリにアクセス(およびその場所を確認)するには、まずMAFアプリケーションをデプロイした後、deployディレクトリに移動する必要があります。www/jsディレクトリは、デプロイメントによって生成された、プラットフォーム固有のアーティファクト内にあります。iOSデプロイメントの場合、このディレクトリはtemporary_xcode_projectディレクトリ内にあります。Androidデプロイメントの場合、このディレクトリはAndroidアプリケーション・パッケージ(.apk)ファイルのassetsディレクトリ内にあります。リリース・モードでのWindowsのデプロイメントの場合、ディレクトリの場所はappLocationOnMachine\deploy\deploymentprofilename\release\MafTemplate\www\jsです。「HTMLコンテンツによるカスタムSpringboardアプリケーション機能に関する必知事項」も参照してください。

注意:

デザインタイムにはパスが存在しないので、JavaScriptインクルードは、JDeveloperによってソース・エディタ内ではエラーとして赤い波型の下線で強調表示されます。このパスは実行時に解決されます。

Cordova APIに対するMAF拡張機能では、モバイル・デバイスのAPIによってmaf-feature.xmlおよびmaf-application.xmlファイルの構成メタデータにアクセスできるようになります。これにより、モバイル・デバイスとMAFのインフラストラクチャ間の通信が確立します。これらの拡張機能は、アプリケーション機能の表示動作も指示します。

デフォルトのMAF Springboardページ、springboard.amx、およびカスタマイズされたSpringboardの構築に使用できるApplicationFeaturesデータ・コントロールの詳細は、「MAF AMXコンテンツによるカスタムSpringboardアプリケーション機能に関する必知事項」を参照してください。

カスタムHTMLページ内のコードの実行について

カスタムHTMLページでは、MAFによるロードの完了後に、handlePageShownコールバック関数のshowpagecompleteイベントをリスニングすることで、独自のコードを呼び出すことができます。

次の例は、handlePageShownコールバック関数のshowpagecompleteイベントを定義するスクリプトを示しています。カスタムHTMLページ(ログイン・ページなど)では、MAFによって初めてそのページがロードおよび表示された後、標準的なDOM (Document Object Model)イベント・リスニングを使用してこのイベントをリスニングすることによって、ページに含まれる独自のコードを呼び出すことができます。

<script>
        function handlePageShown()
        {
          console.log("Page is shown!");
        }
        document.addEventListener("showpagecomplete", handlePageShown, false);
</script>

注意:

showpagecompleteイベントを使用すると、MAFの適切な状態が保証されます。loadやCordovaのdevicereadyなど、他のブラウザやサード・パーティのイベントを使用した場合、この状態は保証されない可能性があります。これらは使用しないでください。

MAFコンテナ・ユーティリティAPI

MAFコンテナ・ユーティリティAPIのメソッドは、ナビゲーション・バーへの移動、Springboardの表示、アプリケーション機能の表示などの機能をMAFアプリケーションに提供します。これらのメソッドは、MAFのJavaおよびJavaScriptレイヤーで使用できます。

Javaでは、コンテナ・ユーティリティAPIは、静的メソッドとしてAdfmfContainerUtilitiesクラスに実装されます。このクラスはoracle.adfmf.framework.apiパッケージにあります。次の例では、gotoSpringboardメソッドをコールしています。oracle.adfmf.framework.api.AdfmfContainerUtilitiesの詳細は、Oracle Mobile Application Framework Java APIリファレンスを参照してください。

import oracle.adfmf.framework.api.AdfmfContainerUtilities;
...
AdfmfContainerUtilities.gotoSpringboard();
...

JavaScriptコールバックの使用方法

非同期のJavaScriptでは、どの関数にも結果を返すsuccessコールバックと例外を返すfailedコールバックの2つのコールバック関数が追加されています。

JavaとJavaScriptのシグネチャは一致します。Javaでは、シグネチャは同期化され、直接結果が戻されます。JavaScriptは非同期なので、結果を返すsuccessコールバックと、スローされた例外を戻すfailedコールバック2つのコールバック関数が各関数に追加されます。Javaメソッドでは、success値は関数またはメソッドから戻され、例外はメソッドから直接スローされます。次の例の疑似コードは、引数を使用しないコールpublic static functionName() throwsが、Java内でtryおよびcatchブロックを使用してどのように実行されるかを示しています。

...
 try {
    result = AdfmfContainerUtilities.functionName();
 }
 catch() {
    ...
 }

...

JavaScriptのコールは非同期なので、関数の実行が完了した時点で、コールバック・メカニズムを通して戻す必要があります。次の例の疑似コードは、JavaScriptコールのシグネチャを示しています。

adf.mf.api.functionName(
           function(successFunction, failureFunction ) { alert("functionName complete"); },
           function(successFunction, failureFunction ) { alert("functionName failed with " + 
                                                         adf.mf.util.stringify(failureFunction); }
);

JavaScriptのコールは非同期なので、結果を戻すことができません。そのかわりに、関数の実行の完了時にコールバック・メカニズムが必要になります。成功および失敗のコールバックのシグネチャは、どちらもfunction(request, response)です。ここでrequest引数は実際のリクエストのJSON表現です。responseはメソッドから戻されたもののJSON表現です(successコールバック関数の場合)。failedコールバック関数の場合は、スローされた例外のJSON表現になります。

注意:

JavaScriptコールを呼び出して、スタックの深度や競合状態などの問題を回避するには、その前にコールバック関数を呼び出す必要があります。

次の例の疑似コードは、public static <return value> <function name>(<arg0>, <arg1>, ...) throws <exceptions>など、1つ以上の引数を使用するコールが、Java内でtry-catchブロックを使用してどのように実行されるかを示しています。

try {
   result = AdfmfContainerUtilities.<function_name>(<arg0>, <arg1>, ...);
}
catch(<exception>) {
   ...
}

ローカルHTMLまたはリモートURLとして定義されたページからMAF JavaScript APIを起動する方法の詳細は、「リモート・アプリケーションによるコンテナ・サービスへのアクセスの有効化」を参照してください。

コンテナ・ユーティリティAPIの使用方法

リストに示されたメソッドを使用して、コンテナ・ユーティリティAPIを使用します。

コンテナ・ユーティリティAPIでは、次のメソッドが提供されます。

getApplicationInformation: MAFアプリケーションのメタデータを取得します。
gotoDefaultFeature: デフォルトのアプリケーション機能をアクティブ化します。
gotoFeature: 特定のアプリケーション機能をアクティブ化します。
getFeatures: アプリケーション機能を取得します。
getFeatureByName: アプリケーション機能の名前を使用して、アプリケーション機能に関する情報を取得します。
getFeatureById: IDを使用してアプリケーション機能を取得します。
resetFeature: アプリケーション機能をロード時の状態にリセットします。
resetApplication: アプリケーションをリセットします。
gotoSpringboard: Springboardをアクティブ化します。
showSpringboard: Springboardを表示します。
hideSpringboard: Springboardを非表示にします。
showNavigationBar: ナビゲーション・バーを表示します。
hideNavigationBar: ナビゲーション・バーを非表示にします。
showPreferences: プリファレンス・ページを表示します。
invokeMethod: Javaメソッドを起動します。
invokeContainerMethod: 特定の引数を使用して、指定されたクラス上でネイティブ・メソッドを起動します。
invokeContainerJavaScriptFunction: JavaScriptメソッドを起動します。
sendEmail: モバイル・デバイスの電子メール・インタフェースを表示します。
sendSMS: モバイル・デバイスのテキスト・メッセージ(SMS)インタフェースを表示します。

コンテナ・ユーティリティAPIには、アプリケーションにバッジおよびバッジ番号を設定するためのメソッドが含まれています。「アプリケーション・アイコンへのバッジ設定」を参照してください。

getApplicationInformation

getApplicationInformationメソッドは、ApplicationInformationオブジェクトを返します。このオブジェクトには、アプリケーションIDやアプリケーション名などのアプリケーションに関するメタデータが格納されています。

Javaでは、このメソッドは次のようにコールされます。

public static oracle.adfmf.framework.ApplicationInformation 
              getApplicationInformation()
              throws oracle.adfmf.framework.exception.AdfException

次の例は、このメソッドのコール方法を示しています。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
     try {
        ApplicationInformation ai = AdfmfContainerUtilities.getApplicationInformation();
        String applicationId = ai.getId();
        String applicationName = ai.getName();
        String vendor = ai.getVendor();
        String version = ai.getVersion();
        ...
     }
     catch(AdfException e) {
        // handle the exception
     }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void getApplicationInformation(success, failed)

successコールバックはfunction(request, response)という形式にする必要があります。このrequest引数には元のリクエストが格納され、response引数には関連するAdfmfContainerUtilitiesメソッドの戻り値が格納されます。この戻り値は、アプリケーション・レベルのメタデータを格納するApplicatiaonInformationオブジェクトです。ここには、アプリケーション名、ベンダー、バージョンおよびアプリケーションIDが含まれます。

failedコールバックはfunction(request, response)という形式にする必要があります。このrequestには元のリクエストが格納され、responseにはエラーが格納されます。

次の例は、これらのコールバック関数を使用してアプリケーション情報を取得する方法を示しています。

adf.mf.api.getApplicationInformation(
           function(req, res) { alert("getApplicationInformation complete"); },
           function(req, res) { alert("getApplicationInformation failed with " +
                                      adf.mf.util.stringify(res); }
);

gotoDefaultFeature

gotoDefaultFeatureメソッドは、MAFにデフォルトのアプリケーション機能を表示するようにリクエストします。この機能は、アプリケーションの起動時に表示されます。

注意:

認証関連または許可関連の問題が発生している場合、このメソッドではアプリケーション機能を表示できないことがあります。

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void gotoDefaultFeature(success, failed)

successコールバック関数はfunction(request, response)という形式にする必要があります。このrequest引数には元のリクエストが格納され、response引数には関連するAdfmfContainerUtilitiesメソッドの戻り値(void)が格納されます。

failedコールバック関数はfunction(request, response)という形式にする必要があります。このrequest引数には元のリクエストが格納され、response引数にはエラーが格納されます。

次の例は、これらのコールバック関数を使用してデフォルトのアプリケーション機能をコールする方法を示しています。

adf.mf.api.gotoDefaultFeature(
          function(req, res) { alert("gotoDefaultFeature complete"); },
          function(req, res) { alert("gotoDefaultFeature failed with " +
                                      adf.mf.util.stringify(res); }
);

gotoFeature

gotoFeatureメソッドは、MAFにIDで識別されるアプリケーション機能を表示するようにリクエストします。

注意:

認証関連または許可関連の問題が発生している場合、このメソッドではアプリケーション機能を表示できないことがあります。

Javaでは、このメソッドは次のようにコールされます。

public static void gotoFeature(java.lang.String featureId)
                   throws oracle.adfmf.framework.exception.AdfException

次の例に示すメソッドのパラメータは、アプリケーション機能のIDです。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.gotoFeature("feature.id");
   }
   catch(AdfException e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void gotoFeature(featureId, success, failed)

featureIdパラメータは、アプリケーション機能IDです。このパラメータはsuccessコールバック関数をアクティブ化します。このコールバック関数はfunction(request, response)という形式にする必要があります。このrequestには元のリクエストが格納され、responseには関連するAdfmfContainerUtilitiesメソッドの戻り値(void)が格納されます。

failedコールバック関数はfunction(request, response)という形式にする必要があります。このrequestには元のリクエストが格納され、responseにはエラーが格納されます。

次の例は、これらのコールバック関数を使用してアプリケーション機能をコールする方法を示しています。

adf.mf.api.gotoFeature("feature0",
          function(req, res) { alert("gotoFeature complete"); },
          function(req, res) { alert("gotoFeature failed with " +
                               adf.mf.util.stringify(res); }
);

getFeatures

getFeaturesメソッドは、使用可能なアプリケーション機能を表現するFeatureInformationオブジェクトの配列を返します。これらのオブジェクトは、カスタム・スプリングボードの実装で使用できます。

このメソッドは、使用可能なアプリケーション機能を表すFeatureInformationオブジェクトの配列を戻します。戻されるメタデータには、機能ID、アプリケーション機能名およびアプリケーション・アイコンに使用するイメージ・ファイルの場所が含まれます。このコールにより、カスタムSpringboardの実装は、制約の適用後に使用可能になるアプリケーション機能のリストにアクセスできるようになります。

注意:

これらのアプリケーション機能もデフォルトのSpringboardに表示されることがあります。

Javaでは、このメソッドは次のようにコールされます。

public static oracle.adfmf.framework.FeatureInformation[] getFeatures()
              throws oracle.adfmf.framework.exception.AdfException

次の例は、このメソッドの使用方法を示しています。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
  ...
   try {
      FeatureInformation[] fia = null;
      fia = AdfmfContainerUtilities.getFeatures();
 
      for(int f = 0; f < fia.length; ++f) {
           FeatureInformation fi = fia[i];
           String featureId = fi.getId();
           String featureName = fi.getName();
           String featureIconPath = = fi.getIcon();
           String featureImagePath = fi.getImage();
           ...
      }
   }
   catch(AdfException e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void getFeatures(success, failed)

successコールバック関数はfunction(request, response)という形式にする必要があります。このrequest引数には元のリクエストが格納され、response引数には関連するAdfmfContainerUtilitiesメソッドの戻り値(FeatureInformationオブジェクトの配列)が格納されます。

failedコールバック関数はfunction(request, response)という形式にする必要があります。このrequest引数には元のリクエストが格納され、response引数にはエラー(AdfException)が格納されます。

adf.mf.api.getFeatures(
          function(req, res) { alert("getFeatures complete"); },
          function(req, res) { alert("getFeatures failed with " +
                               adf.mf.util.stringify(res); }
);

getFeatureByName

getFeatureByNameメソッドは、渡されたアプリケーション機能の名前を使用して、アプリケーション機能に関する情報を返します。

Javaでは、このメソッドは次のようにコールされます。

public static oracle.adfmf.framework.FeatureInformation getFeatureByName(java.lang.String
                                                                         featureName)
                                     throws oracle.adfmf.framework.exception.AdfException

次の例に示すメソッドのパラメータは、アプリケーション機能の名前です。

   ...
   try {
        FeatureInformation fi = AdfmfContainerUtilities.getFeatureByName("feature.name");
        String featureId = fi.getId();
        String featureName = fi.getName();
        String featureIconPath = = fi.getIcon();
        String featureImagePath = fi.getImage();
   }
   catch(AdfException e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void getFeatureByName(featureName, success, failed)

featureNameパラメータは、アプリケーション機能の名前です。successコールバック関数はfunction(request, response)という形式にする必要があります。このrequestには元のリクエストが格納され、responseには関連するAdfmfContainerUtilitiesメソッドの戻り値(void)が格納されます。

次の例は、これらのコールバック関数の使用方法を示しています。

adf.mf.api.getFeatureByName("feature.name",
          function(req, res) { alert("getFeatureByName complete"); },
          function(req, res) { alert("getFeatureByName failed with " +
                                     adf.mf.util.stringify(res); }
);

getFeatureById

getFeatureByIdメソッドは、アプリケーションIDを使用してアプリケーション機能を取得します。

Javaでは、このメソッドは次のようにコールされます。

public static oracle.adfmf.framework.FeatureInformation getFeatureById(String featureId)
                                     throws oracle.adfmf.framework.exception.AdfException

次の例に示すメソッドのパラメータは、アプリケーション機能のIDです。

   try {
      FeatureInformation fi = AdfmfContainerUtilities.getFeatureById("feature.id");
   }
   catch(AdfException e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void getFeatureById(featureId, success, failed)

featureIdパラメータは、アプリケーション機能のIDです。successコールバック関数はfunction(request, response)という形式にする必要があります。このrequestには元のリクエストが格納され、responseには関連するAdfmfContainerUtilitiesメソッドの戻り値(void)が格納されます。

次の例は、これらのコールバック関数を使用してアプリケーション機能を取得する方法を示しています。

adf.mf.api.getFeatureById("feature.id",
          function(req, res) { alert("getFeatureById complete"); },
          function(req, res) { alert("getFeatureById failed with " +
                                     adf.mf.util.stringify(res); }
);

resetFeature

このメソッドは、アプリケーション機能の状態をリセットします。このメソッドでは、アプリケーション機能のJava側のモデルをリセットして、MAFアプリケーションがロードされ、最初にアプリケーション機能が表示されたときのようにユーザー・インタフェース・プレゼンテーションを再起動します。

アプリケーション機能のコンテンツ・タイプが「MAFタスク・フロー」の場合、MAFアプリケーションはタスク・フローを再起動し、タスク・フローでデフォルト・アクティビティとして指定したアクティビティにナビゲートします。

Java API AdfmfContainerUtilities.resetFeatureの2つの実装を使用できます。

resetFeature(String featureId)
resetFeature(String featureId, boolean gotoTheFeature)

どちらもfeatureIdパラメータで識別されるアプリケーション機能をリセットしますが、ブールgotoTheFeatureメソッド・パラメータを含むメソッド・シグネチャも、trueに設定されているときはアプリケーション機能にナビゲートします。アプリケーション機能にナビゲートする2番目のオプションは、アプリケーション機能のアクティブ化ライフサイクルのリスナー・メソッドから呼び出すことはできません。スタック・オーバーフロー・エラーを引き起こす可能性があるからです。

次の例で、setSkinFamilyメソッドにより指定された新しいスキンを使用するために、AdfmfContainerUtilities.resetFeatureを使用してMAFアプリケーションのすべてのアプリケーション機能をリセットする方法について示します。

...
public void switchSkinFamily(String family) {
   this.setSkinFamily(family);
   // reset all the features individually as follows to load the new skin
   FeatureInformation[] features = AdfmfContainerUtilities.getFeatures();
   for 
    (int i = 0; i < features.length; i++) {
    AdfmfContainerUtilities.resetFeature(features[i].getId());
}
...

MAFはまたJavaScript resetFeature APIも提供します。JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void resetFeature(featureId, success, failed)

successコールバック関数はfunction(request, response)という形式にする必要があります。このrequestには元のリクエストが格納され、responseには関連するメソッドの戻り値(アプリケーション機能のID)が格納されます。

次の例は、これらのコールバック関数を使用してアプリケーション機能をコールする方法を示しています。

adf.mf.api.resetFeature("feature0",
          function(req, res) { alert("resetFeature complete"); },
          function(req, res) { alert("resetFeature failed with " +
                                     adf.mf.util.stringify(res); }
);

resetApplication

resetApplicationメソッドは、実行中のアプリケーションをリセットします。個別のアプリケーション機能のリセットでは不十分な場合にのみ使用します。

このメソッドは、実行中のアプリケーションをリセットするので、個別のアプリケーション機能をリセットするだけでは不十分な場合にのみ使用してください。

Javaでは、このメソッドは次のようにコールされます。

public static void resetApplication(java.lang.String message)

メソッドのパラメータ(次の例を参照)は、アプリケーションを再起動する理由が記載されたメッセージか、null (メッセージが不要な場合)のいずれかです。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.resetApplication("New content is available");
   }
   catch(Exception e) {
      // handle the exception
}

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void resetApplication(message, success, failed)

次の例は、これらのコールバック関数を使用してアプリケーションをコールする方法を示しています。

adf.mf.api.resetApplication("message1",
          function(req, res) { alert("resetApplication complete"); },
          function(req, res) { alert("resetApplication failed with " +
                                     adf.mf.util.stringify(res); }
);

gotoSpringboard

gotoSpringboardメソッドは、MAFにスプリングボードをアクティブ化するようにリクエストします。

注意:

maf-application.xmlファイルで機能参照として指定されていない場合や、認証関連または許可関連の問題が発生している場合、このメソッドではSpringboardを表示できないことがあります。「アプリケーションのナビゲーションの構成」も参照してください。

Javaでは、このメソッドは次のようにコールされます。

public static void gotoSpringboard()

次の例は、このメソッドの使用方法を示しています。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.gotoSpringboard();
   }
   catch(AdfException e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void gotoSpringboard(success, failed)

successコールバック関数はfunction(request, response)という形式にする必要があります。このrequestには元のリクエストが格納され、responseには関連するメソッドの戻り値(void)が格納されます。

次の例は、これらのコールバック関数の使用方法を示しています。

adf.mf.api.gotoSpringboard(
    function(req, res) { alert("gotoSpringboard complete"); },
    function(req, res) { alert("gotoSpringboard failed with " +
                               adf.mf.util.stringify(res); }
);

showSpringboard

showSpringboardメソッドは、MAFにスプリングボードを表示するようにリクエストします。

このメソッドは、MAFがSpringboardを表示するようにリクエストします。

Javaでは、このメソッドは次のようにコールされます。

public static void showSpringboard()

次の例は、このメソッドの使用方法を示しています。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.showSpringboard();
   }
   catch(Exception e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void showSpringboard(success, failed)

次の例は、これらのコールバック関数の使用方法を示しています。

adf.mf.api.showSpringboard(
           function(req, res) { alert("showSpringboard complete"); },
           function(req, res) { alert("showSpringboard failed with " +
                                       adf.mf.util.stringify(res); }
);

hideSpringboard

hideSpringboardメソッドは、MAFにスプリングボードを非表示にするようにリクエストします。

Javaでは、このメソッドは次のようにコールされます。

public static void hideSpringboard()

次の例は、このメソッドの使用方法を示しています。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.hideSpringboard();
   }
   catch(Exception e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void hideSpringboard(success, failed)

次の例は、これらのコールバック関数の使用方法を示しています。

adf.mf.api.hideSpringboard(
       function(req, res) { alert("hideSpringboard complete"); },
       function(req, res) { alert("hideSpringboard failed with " +
                                   adf.mf.util.stringify(res); }
);

showNavigationBar

showNavigationBarメソッドは、MAFにナビゲーション・バーを表示するようにリクエストします。

このメソッドは、MAFがナビゲーション・バーを表示するようにリクエストします。

Javaでは、このメソッドは次のようにコールされます。

public static void showNavigationBar()

次の例は、このメソッドの使用方法を示しています。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.showNavigationBar();
   }
   catch(Exception e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void showNavigationBar(success, failed)

次の例は、これらのコールバック関数の使用方法を示しています。

adf.mf.api.showNavigationBar(
           function(req, res) { alert("showNavigationBar complete"); },
           function(req, res) { alert("showNavigationBar failed with " +
                                       adf.mf.util.stringify(res); }
);

hideNavigationBar

hideNavigationBarメソッドは、MAFにナビゲーション・バーを非表示にするようにリクエストします。

Javaでは、このメソッドは次のようにコールされます。

public static void hideNavigationBar()

次の例は、このメソッドの使用方法を示しています。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.hideNavigationBar();
   }
   catch(Exception e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void hideNavigationBar(success, failed)

次の例は、これらのコールバック関数の使用方法を示しています。

adf.mf.api.hideNavigationBar(
       function(req, res) { alert("hideNavigationBar complete"); },
       function(req, res) { alert("hideNavigationBar failed with " +
                                   adf.mf.util.stringify(res); }
);

showPreferences

showPreferencesメソッドは、MAFに「プリファレンス」ページを表示するようにリクエストします。

このメソッドは、MAFがプリファレンス・ページを表示するようにリクエストします。

Javaでは、このメソッドは次のようにコールされます。

public static void showPreferences()

次の例は、このメソッドの使用方法を示しています。

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.showPreferences();
   }
   catch(Exception e) {
      // handle the exception
   }

JavaScriptでは、次のように、successおよびfailedコールバック関数によって、戻り値と例外をJavaScriptのコール元コードに戻すことができます。

public void showPreferences(success, failed)

次の例は、これらのコールバック関数の使用方法を示しています。

adf.mf.api.showPreferences(
           function(req, res) { alert("showPreferences complete"); },
           function(req, res) { alert("showPreferences failed with " +
                                       adf.mf.util.stringify(res); }
);

invokeMethod

各例とリストに示したパラメータを使用して、invokeMethodをコールし(Javaでは使用できません)、クラスパス内の任意のクラスからJavaメソッドを呼び出します。

このメソッドは、Javaでは提供されません。次の例は、JavaScriptのコールバック・メソッドを使用して、クラスパスに含まれる任意のクラスからJavaメソッドを起動する方法を示しています。

adf.mf.api.invokeMethod(classname,
                        methodname,
                        param1,
                        param2,
                         ...
                        paramN,
                        successCallback,
                        failedCallback);

表B-1に、このメソッドによって取得されるパラメータを示します。

表B-1 invokeMethodに渡されるパラメータ

パラメータ	説明
`classname`	Javaメソッドのコール時にMAFがインスタンスを作成するために使用するクラス名(パッケージ情報を含む)
`methodname`	`classname`パラメータによって指定されたクラスのインスタンスで起動させるメソッドの名前

successコールバック関数はfunction(request, response)という形式にする必要があります。このrequestには元のリクエストが格納され、responseには関連するメソッドの戻り値が格納されます。

複数のパラメータによるこのメソッドの使用例は次のとおりです。

adf.mf.api.invokeMethod("TestBean", "setStringProp", "foo", success, failed);

adf.mf.api.invokeMethod("TestBean", "getStringProp", success, failed)

整数パラメータの使用例は次のとおりです。

adf.mf.api.invokeMethod("TestBean", "testSimpleIntMethod", "101", success, failed);

複合パラメータの使用方法は次のとおりです。

adf.mf.api.invokeMethod("TestBean", "testComplexMethod", 
           {"foo":"newfoo","baz":"newbaz",".type":"TestBeanComplexSubType"}, success, failed);

パラメータが存在しない場合の使用方法は次のとおりです。

adf.mf.api.invokeMethod("TestBean", "getComplexColl", success, failed);

Stringパラメータの使用方法は次のとおりです。

adf.mf.api.invokeMethod("TestBean", "testMethodStringStringString", "Hello ",
                        "World", success, failed);

invokeContainerMethod

リストに示したパラメータを使用して、invokeContainerMethodメソッドをコールし、特定の引数で指定されたクラスのネイティブ・メソッドを呼び出します。

invokeContainerMethodは、特定の引数を使用して、指定されたクラス上でネイティブ・メソッドを起動します。表B-2に、このメソッドによって渡されるパラメータを示します。

表B-2 invokeContainerMethodに渡されるパラメータ

パラメータ	説明
`className`	MAFがインスタンスを作成するために使用するクラス名(パッケージ情報を含む)。
`methodName`	起動させるメソッドの名前。
`args`	メソッドに渡される引数の配列。この配列内で、これらの引数はメソッドが期待する順序で並べられます。

このメソッドは、Objectを戻します。

public static java.lang.Object invokeContainerMethod(java.lang.String className,
                                                     java.lang.String methodName)
                                                     java.lang.Object[] args)

invokeContainerJavaScriptFunction

invokeContainerJavaScriptFunctionメソッドは、JavaScriptのメソッドを呼び出すために使用します。

invokeContainerJavaScriptFunctionは、JavaScriptメソッドを起動します。表B-3に、このメソッドによって渡されるパラメータを示します。

表B-3 invokeContainerJavaScriptFunctionに渡されるパラメータ

パラメータ	説明
`featureId`	JavaScriptの起動コンテキストを決定するためにMAFによって使用されるアプリケーション機能のID。このIDによって、このメソッドがコールされるWebビューが決まります。
`method`	起動させるメソッドの名前。
`args`	メソッドに渡される引数の配列。この配列内で、これらの引数はメソッドが期待する順序で並べられます。

このメソッドは、JSONオブジェクトを戻します。

注意:

invokeContainerJavaScriptFunction APIは、アプリケーションがAndroidデバイスまたはエミュレータ上で実行される場合、JavaScript関数が15秒以内に完了することを予期します。完了しなかった場合は、タイムアウト・エラーを戻します。

public static java.lang.Object invokeContainerJavaScriptFunction(java.lang.String featureId,
                                                                 java.lang.Object[] args)
                                throws oracle.adfmf.framework.exception.AdfException

次の例の疑似コードは、feature1という名前のアプリケーション機能に含まれるappFunctions.jsという名前のJavaScriptファイルを示しています。このファイル内で記述されているJavaScriptメソッド、application.testFunctionは、invokeContainerJavaScriptFunctionメソッドによってコールされます(次の例を参照)。

(function() 
    {
       if (!window.application) window.application = {};
 
       application.testFunction = function()
       {
          var args = arguments;
 
          alert("APP ALERT " + args.length + " ");
          return "application.testFunction - passed";
       };
    })();

アプリケーションには、この関数をコールするアクション・リスナーで構成されるコマンド・ボタンが含まれているので、エンド・ユーザーがこのボタンをクリックすると、次のようなアラートが表示されます。

APP ALERT 0
APP ALERT 1
APP ALERT 2

次の例の疑似コードは、invokeApplicationJavaScriptFunctionメソッドによって、前の例で記述されているJavaScriptメソッド(application.testFunction)をコールする方法を示しています。

invokeApplicationJavaScriptFuntions 
    public void invokeApplicationJavaScriptFuntions(ActionEvent actionEvent) {
        AdfmfContainerUtilities.invokeContainerJavaScriptFunction("feature1",
                                                                  "application.testFunction",
                                                                   new Object[] {} );
        AdfmfContainerUtilities.invokeContainerJavaScriptFunction("feature1",
                                                                  "application.testFunction",
                                                                   new Object[] {"P1"} );
        AdfmfContainerUtilities.invokeContainerJavaScriptFunction("feature1",
                                                                  "application.testFunction",
                                                                   new Object[] {"P1", "P2"} );
    }

Oracle Mobile Application Framework Java APIリファレンスおよびAPIDemoサンプル・アプリケーションを参照してください。このサンプル・アプリケーションは、開発用コンピュータのJDeveloperインストール・ディレクトリ内にある次の場所のPublicSamples.zipファイルに含まれています。

jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples

sendEmail

詳細は、「電子メールを有効にするためのsendEmailメソッドの使用方法」を参照してください。

sendSMS

詳細は、「テキスト・メッセージを有効にするためのSendSMSメソッドの使用方法」を参照してください。

アプリケーション・アイコンへのバッジ設定

iOSプラットフォームの場合は、リストに示したAdfmfContainerUtilitiesクラスのメソッドを使用して、MAFアプリケーション・アイコンにバッジ番号を配置するか、そのバッジ番号を取得します。

AdfmfContainerUtilitiesクラスには、MAFアプリケーション・アイコンにバッジ番号を設定したり、その番号を取得するためのメソッドが含まれています。表B-4に、これらのメソッドを示します。

表B-4 アイコンへのバッジ設定メソッド

メソッド	説明	パラメータ
`getApplicationIconBadgeNumber`	MAFアプリケーションのアイコンに現在設定されているバッジの値を取得します。アプリケーション・アイコンにバッジが設定されていない場合は、ゼロ(0)を戻します。	なし
`setApplicationIconBadgeNumber`	MAFアプリケーションのアイコンにバッジ番号を設定します。	バッジの値(`int badge`)。

注意:

アプリケーション・アイコンへのバッジ設定は、AndroidプラットフォームまたはWindowsプラットフォームのいずれでもサポートされていません。

getDirectoryPathRootメソッドを使用したファイル・アクセス

AdfmfJavaUtilties APIには、getDirectoryPathRootメソッドが含まれています。このメソッドはJavaレイヤーからのみコールでき、iOSシステム、AndroidシステムおよびWindowsシステム上のディレクトリへのアクセスを可能にします。

次の例に示すように、このメソッドを使用すると、デバイス上の一時、アプリケーション(iOSシステム上)およびキャッシュ・ディレクトリの場所に、TemporaryDirectory、ApplicationDirectoryおよびDeviceOnlyDirectory定数を使用してそれぞれアクセスできます。DeviceOnlyDirectoryの場所に格納されたファイルは、デバイスの接続時には同期されません。

注意:

アプリケーションからディレクトリまたはファイルへのアクセスを試みる前に、それらのディレクトリまたはファイルが存在することを確認してください。

oracle.adfmf.framework.api.AdfmfJavaUtilitiesに関する詳細は、Oracle Mobile Application Framework Java APIリファレンスを参照してください。

import oracle.adfmf.framework.api.AdfmfJavaUtilities;
 
...
 
public void getDirectoryPathRoot() {
   // returns the directory for storing temporary files
   String tempDir =
      AdfmfJavaUtilities.getDirectoryPathRoot(AdfmfJavaUtilities.TemporaryDirectory);
 
   // returns the directory for storing application files
   String appDir =
      AdfmfJavaUtilities.getDirectoryPathRoot(AdfmfJavaUtilities.ApplicationDirectory);
 
   // returns the directory for storing cache files
   String deviceDir =
      AdfmfJavaUtilities.getDirectoryPathRoot(AdfmfJavaUtilities.DeviceOnlyDirectory);
  
   // returns the directory for storing downloaded files
   String downloadDir =
      AdfmfJavaUtilities.getDirectoryPathRoot(AdfmfJavaUtilities.DownloadDirectory);
}

プラットフォームに依存しないダウンロード場所へのアクセス

getDirectoryPathRootメソッドを使用して、外部ストレージ・ディレクトリとデフォルトの添付ファイル・ディレクトリへのパスを取得します。

ファイル記憶域の要件は、プラットフォームによって異なります。Androidプラットフォームでは、アプリケーションからファイルへのアクセス元となる単一の場所が規定されていません。そのかわり、アプリケーションでは、権限が付与された任意の場所にファイルを書き込むことができます。一方、iOSプラットフォームでは通常、アプリケーション・ディレクトリ内にファイルを格納します。Windowsでは、アプリケーションは外部ファイルやディレクトリ・ファイルにはアクセスしません。ファイルはアプリケーション・パッケージ内に格納されています。このような違いにより、ApplicationDirectoryをgetDirectoryPathRootメソッドに渡すと、AndroidデバイスではなくiOSデバイスまたはWindowsデバイス上で実行されているアプリケーションの添付ファイルを表示するために必要なファイルの場所を戻すことができます。アプリケーションをiOSデバイスとAndroidデバイスの両方で実行する場合、プラットフォーム固有のコードを記述してこれらの場所を取得するのではなく、getDirectoryPathRootメソッドにDownloadDirectoryを渡すことによって、外部記憶域の場所とデフォルトの添付ファイル・ディレクトリへのパスを両方戻すことができます。この定数(列挙型)には、DeviceManager APIのdisplayFileメソッドで使用する場所が反映されます。このメソッドでは、プラットフォーム固有の機能を使用してこれらの場所を検索することによって、添付ファイルを表示します。

Androidの場合、DownloadDirectoryでは、android.os.Environment.getExternalStorageDirectoryメソッド(SDカードなどのAndroid用外部記憶域ディレクトリを取得する)によって戻されるパスを参照します。iOSデバイス上で実行されるMAFアプリケーションの場合は、ApplicationDirectoryと同じ場所が戻されます。getExternalStorageDirectoryの詳細は、Android開発者のWebサイト(http://developer.android.com/reference/packages.html)で入手できる、パッケージのリファレンス・ドキュメントを参照してください。また、iOS Developer Library (http://developer.apple.com/library/ios/navigation/)で入手できる『Files System Programming Guide』も参照してください。