Add JavaDoc for CordovaResourceApi
[cordova-android.git] / framework / src / org / apache / cordova / api / Plugin.java
1 /*
2        Licensed to the Apache Software Foundation (ASF) under one
3        or more contributor license agreements.  See the NOTICE file
4        distributed with this work for additional information
5        regarding copyright ownership.  The ASF licenses this file
6        to you under the Apache License, Version 2.0 (the
7        "License"); you may not use this file except in compliance
8        with the License.  You may obtain a copy of the License at
9
10          http://www.apache.org/licenses/LICENSE-2.0
11
12        Unless required by applicable law or agreed to in writing,
13        software distributed under the License is distributed on an
14        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15        KIND, either express or implied.  See the License for the
16        specific language governing permissions and limitations
17        under the License.
18 */
19 package org.apache.cordova.api;
20
21 import org.json.JSONArray;
22 import org.json.JSONObject;
23
24 import android.content.Intent;
25 import android.webkit.WebView;
26
27 /**
28  * Plugin interface must be implemented by any plugin classes.
29  *
30  * The execute method is called by the PluginManager.
31  */
32 public abstract class Plugin implements IPlugin {
33
34         public String id;
35     public WebView webView;                                     // WebView object
36     public CordovaInterface ctx;                        // CordovaActivity object
37
38         /**
39          * Executes the request and returns PluginResult.
40          * 
41          * @param action                The action to execute.
42          * @param args                  JSONArry of arguments for the plugin.
43          * @param callbackId    The callback id used when calling back into JavaScript.
44          * @return                              A PluginResult object with a status and message.
45          */
46         public abstract PluginResult execute(String action, JSONArray args, String callbackId);
47
48         /**
49          * Identifies if action to be executed returns a value and should be run synchronously.
50          * 
51          * @param action        The action to execute
52          * @return                      T=returns value
53          */
54         public boolean isSynch(String action) {
55                 return false;
56         }
57
58         /**
59          * Sets the context of the Plugin. This can then be used to do things like
60          * get file paths associated with the Activity.
61          * 
62          * @param ctx The context of the main Activity.
63          */
64         public void setContext(CordovaInterface ctx) {
65                 this.ctx = ctx;
66         }
67
68         /**
69          * Sets the main View of the application, this is the WebView within which 
70          * a Cordova app runs.
71          * 
72          * @param webView The Cordova WebView
73          */
74         public void setView(WebView webView) {
75                 this.webView = webView;
76         }
77         
78     /**
79      * Called when the system is about to start resuming a previous activity. 
80      * 
81      * @param multitasking              Flag indicating if multitasking is turned on for app
82      */
83     public void onPause(boolean multitasking) {
84     }
85
86     /**
87      * Called when the activity will start interacting with the user. 
88      * 
89      * @param multitasking              Flag indicating if multitasking is turned on for app
90      */
91     public void onResume(boolean multitasking) {
92     }
93     
94     /**
95      * Called when the activity receives a new intent. 
96      */
97     public void onNewIntent(Intent intent) {
98     }
99     
100     /**
101      * The final call you receive before your activity is destroyed. 
102      */
103     public void onDestroy() {
104     }
105         
106     /**
107      * Called when a message is sent to plugin. 
108      * 
109      * @param id            The message id
110      * @param data          The message data
111      */
112     public void onMessage(String id, Object data) {
113     }
114
115     /**
116      * Called when an activity you launched exits, giving you the requestCode you started it with,
117      * the resultCode it returned, and any additional data from it. 
118      * 
119      * @param requestCode               The request code originally supplied to startActivityForResult(), 
120      *                                                  allowing you to identify who this result came from.
121      * @param resultCode                The integer result code returned by the child activity through its setResult().
122      * @param data                              An Intent, which can return result data to the caller (various data can be attached to Intent "extras").
123      */
124     public void onActivityResult(int requestCode, int resultCode, Intent intent) {
125     }
126
127     /**
128      * By specifying a <url-filter> in plugins.xml you can map a URL (using startsWith atm) to this method.
129      * 
130      * @param url                               The URL that is trying to be loaded in the Cordova webview.
131      * @return                                  Return true to prevent the URL from loading. Default is false.
132      */
133     public boolean onOverrideUrlLoading(String url) {
134         return false;
135     }
136
137     /**
138      * Send generic JavaScript statement back to JavaScript.
139      * success(...) and error(...) should be used instead where possible.
140      * 
141      * @param statement
142      */
143     public void sendJavascript(String statement) {
144         this.ctx.sendJavascript(statement);
145     }
146
147     /**
148      * Call the JavaScript success callback for this plugin.
149      * 
150      * This can be used if the execute code for the plugin is asynchronous meaning
151      * that execute should return null and the callback from the async operation can
152      * call success(...) or error(...)
153      * 
154      * @param pluginResult              The result to return.
155          * @param callbackId            The callback id used when calling back into JavaScript.
156      */
157     public void success(PluginResult pluginResult, String callbackId) {
158         this.ctx.sendJavascript(pluginResult.toSuccessCallbackString(callbackId));
159     }
160
161     /**
162      * Helper for success callbacks that just returns the Status.OK by default
163      * 
164      * @param message                   The message to add to the success result.
165      * @param callbackId                The callback id used when calling back into JavaScript.
166      */
167     public void success(JSONObject message, String callbackId) {
168         this.ctx.sendJavascript(new PluginResult(PluginResult.Status.OK, message).toSuccessCallbackString(callbackId));
169     }
170
171     /**
172      * Helper for success callbacks that just returns the Status.OK by default
173      * 
174      * @param message                   The message to add to the success result.
175      * @param callbackId                The callback id used when calling back into JavaScript.
176      */
177     public void success(String message, String callbackId) {
178         this.ctx.sendJavascript(new PluginResult(PluginResult.Status.OK, message).toSuccessCallbackString(callbackId));
179     }
180     
181     /**
182      * Call the JavaScript error callback for this plugin.
183      * 
184      * @param pluginResult              The result to return.
185          * @param callbackId            The callback id used when calling back into JavaScript.
186      */
187     public void error(PluginResult pluginResult, String callbackId) {
188         this.ctx.sendJavascript(pluginResult.toErrorCallbackString(callbackId));
189     }
190
191     /**
192      * Helper for error callbacks that just returns the Status.ERROR by default
193      * 
194      * @param message                   The message to add to the error result.
195      * @param callbackId                The callback id used when calling back into JavaScript.
196      */
197     public void error(JSONObject message, String callbackId) {
198         this.ctx.sendJavascript(new PluginResult(PluginResult.Status.ERROR, message).toErrorCallbackString(callbackId));
199     }
200
201     /**
202      * Helper for error callbacks that just returns the Status.ERROR by default
203      * 
204      * @param message                   The message to add to the error result.
205      * @param callbackId                The callback id used when calling back into JavaScript.
206      */
207     public void error(String message, String callbackId) {
208         this.ctx.sendJavascript(new PluginResult(PluginResult.Status.ERROR, message).toErrorCallbackString(callbackId));
209     }
210 }