diff options
Diffstat (limited to 'docs/html/guide')
| -rw-r--r-- | docs/html/guide/google/gcm/adv.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/google/gcm/c2dm.jd | 6 | ||||
| -rw-r--r-- | docs/html/guide/google/gcm/demo.jd | 4 | ||||
| -rw-r--r-- | docs/html/guide/google/gcm/gcm.jd | 36 | ||||
| -rw-r--r-- | docs/html/guide/google/gcm/gs.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/google/play/expansion-files.jd | 31 | ||||
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 19 | ||||
| -rw-r--r-- | docs/html/guide/practices/app-design/performance.jd | 410 | ||||
| -rw-r--r-- | docs/html/guide/practices/app-design/responsiveness.jd | 140 | ||||
| -rw-r--r-- | docs/html/guide/practices/jni.jd | 719 | ||||
| -rw-r--r-- | docs/html/guide/practices/performance.jd | 413 | ||||
| -rw-r--r-- | docs/html/guide/practices/responsiveness.jd | 140 | ||||
| -rw-r--r-- | docs/html/guide/practices/security.jd | 767 | ||||
| -rw-r--r-- | docs/html/guide/topics/appwidgets/index.jd | 117 | ||||
| -rw-r--r-- | docs/html/guide/topics/renderscript/compute.jd | 123 | ||||
| -rw-r--r-- | docs/html/guide/topics/resources/more-resources.jd | 4 |
16 files changed, 239 insertions, 2694 deletions
diff --git a/docs/html/guide/google/gcm/adv.jd b/docs/html/guide/google/gcm/adv.jd index 356ee1d..1360624 100644 --- a/docs/html/guide/google/gcm/adv.jd +++ b/docs/html/guide/google/gcm/adv.jd @@ -257,7 +257,7 @@ registerReceiver(mRetryReceiver, filter); <h2 id="multi-senders">Receiving Messages from Multiple Senders</h2> <p>GCM allows multiple parties to send messages to the same application. For example, suppose your application is an articles aggregator with multiple contributors, and you want each of them to be able to send a message when they publish a new article. This message might contain a URL so that the application can download the article. Instead of having to centralize all sending activity in one location, GCM gives you the ability to let each of these contributors send its own messages.</p> -<p>To make this possible, all you need to do is have each sender generate its own project ID. Then include those IDs in the sender field, separated by commas, when requesting a registration. Finally, share the registration ID with your partners, and they'll be able to send messages to your application using their own authentication keys.</p> +<p>To make this possible, all you need to do is have each sender generate its own project number. Then include those IDs in the sender field, separated by commas, when requesting a registration. Finally, share the registration ID with your partners, and they'll be able to send messages to your application using their own authentication keys.</p> <p>This code snippet illustrates this feature. Senders are passed as an intent extra in a comma-separated list:</p> <pre class="prettyprint pretty-java">Intent intent = new Intent(GCMConstants.INTENT_TO_GCM_REGISTRATION); intent.setPackage(GSF_PACKAGE); diff --git a/docs/html/guide/google/gcm/c2dm.jd b/docs/html/guide/google/gcm/c2dm.jd index ecc08c1..e80a41f 100644 --- a/docs/html/guide/google/gcm/c2dm.jd +++ b/docs/html/guide/google/gcm/c2dm.jd @@ -55,7 +55,7 @@ page.title=Migration <dd>To use the GCM service, you need to obtain a Simple API Key from Google APIs console page. For more information, see <a href="gs.html">Getting Started</a>. Note that GCM <em>only</em> accepts Simple API Key—using ClientLogin or OAuth2 tokens will not work. </dd> <dt><strong>Sender ID</strong></dt> -<dd>In C2DM, the Sender ID is an email address. In GCM, the Sender ID is a project ID that you acquire from the API console, as described in <a href="gs.html#create-proj">Getting Started</a>. </dd> +<dd>In C2DM, the Sender ID is an email address. In GCM, the Sender ID is a project number that you acquire from the API console, as described in <a href="gs.html#create-proj">Getting Started</a>. </dd> <dt><strong>JSON format</strong></dt> <dd>GCM HTTP requests support JSON format in addition to plain text. For more information, see the <a href="gcm.html#send-msg">Architectural Overview</a>.</dd> @@ -82,12 +82,12 @@ page.title=Migration <p>C2DM and GCM are not interoperable. For example, you cannot post notifications from GCM to C2DM registration IDs, nor can you use C2DM registration IDs as GCM registration IDs. From your server-side application, you must keep keep track of whether a registration ID is from C2DM or GCM and use the proper endpoint. </p> <p>As you transition from C2DM to GCM, your server needs to be aware of whether a given registration ID -contains an old C2DM sender or a new GCM project ID. This is the approach we recommend: have the new app version (the one that uses GCM) send a bit along with the registration ID. This bit tells your server that this registration ID is for GCM. If you don't get the extra bit, you mark the registration ID as C2DM. Once no more valid registration IDs are marked as C2DM, you can complete the migration.</p> +contains an old C2DM sender or a new GCM project number. This is the approach we recommend: have the new app version (the one that uses GCM) send a bit along with the registration ID. This bit tells your server that this registration ID is for GCM. If you don't get the extra bit, you mark the registration ID as C2DM. Once no more valid registration IDs are marked as C2DM, you can complete the migration.</p> <h2 id="migrating">Migrating Your Apps</h2> <p>This section describes how to move existing C2DM apps to GCM.</p> <h3 id="client">Client changes</h3> -<p>Migration is simple! The only change required in the application is replacing the email account passed in the sender parameter of the registration intent with the project ID generated when signing up for the new service. For example:</p> +<p>Migration is simple! The only change required in the application is replacing the email account passed in the sender parameter of the registration intent with the project number generated when signing up for the new service. For example:</p> <pre class="prettyprint pretty-java">Intent registrationIntent = new Intent("com.google.android.c2dm.intent.REGISTER"); // sets the app name in the intent registrationIntent.putExtra("app", PendingIntent.getBroadcast(this, 0, new Intent(), 0)); diff --git a/docs/html/guide/google/gcm/demo.jd b/docs/html/guide/google/gcm/demo.jd index d66cbbc..7e35fd6 100644 --- a/docs/html/guide/google/gcm/demo.jd +++ b/docs/html/guide/google/gcm/demo.jd @@ -62,7 +62,7 @@ page.title=GCM Demo Application <p>For the Android application:</p> <ul> <li>Emulator (or device) running Android 2.2 with Google APIs.</li> - <li>The Google API project ID of the account registered to use GCM.</li> + <li>The Google API project number of the account registered to use GCM.</li> </ul> <h2 id="gcm-setup">Setting Up GCM</h2> <p>Before proceeding with the server and client setup, it's necessary to register a Google account with the Google API Console, enable Google Cloud Messaging in GCM, and obtain an API key from the <a href="https://code.google.com/apis/console">Google API Console</a>.</p> @@ -175,7 +175,7 @@ runserver: <pre class="prettyprint pretty-java"> static final String SERVER_URL = "http://192.168.1.10:8080/gcm-demo"; static final String SENDER_ID = "4815162342";</pre> -<p>Note that the <code>SERVER_URL</code> is the URL for the server and the application's context (or just server, if you are using App Engine), and it does not include the forward slash (<code>/</code>). Also note that <code>SENDER_ID</code> is the Google API project ID you obtained in the server setup steps above.</p> +<p>Note that the <code>SERVER_URL</code> is the URL for the server and the application's context (or just server, if you are using App Engine), and it does not include the forward slash (<code>/</code>). Also note that <code>SENDER_ID</code> is the Google API project number you obtained in the server setup steps above.</p> <li>In a shell window, go to the <code>gcm-demo-client</code> directory.</li> <li>Use the SDK's <code>android</code> tool to generate the <code>ant</code> build files:</li> diff --git a/docs/html/guide/google/gcm/gcm.jd b/docs/html/guide/google/gcm/gcm.jd index a47ceb9..1762e12 100644 --- a/docs/html/guide/google/gcm/gcm.jd +++ b/docs/html/guide/google/gcm/gcm.jd @@ -80,7 +80,6 @@ Messaging (GCM):</p> <ul> <li>It allows 3rd-party application servers to send messages to their Android applications.</li> - <li>GCM makes no guarantees about delivery or the order of messages.</li> <li>An Android application on an Android device doesn't need to be running to receive messages. The system will wake up the Android application via Intent broadcast when the message arrives, as long as the application is set up with the proper broadcast receiver and permissions.</li> @@ -133,7 +132,7 @@ application server and sending them to the device. </td> </tr> <tr> <td><strong>Sender ID</strong></td> - <td>A project ID you acquire from the API console, as described in <a href="gs.html#create-proj">Getting Started</a>. The sender + <td>A project number you acquire from the API console, as described in <a href="gs.html#create-proj">Getting Started</a>. The sender ID is used in the <a href="#registering">registration process</a> to identify an Android application that is permitted to send messages to the device.</td> </tr> @@ -360,7 +359,7 @@ could not run properly. </li> </p> <ul> - <li><code>sender</code> is the project ID of the account authorized to send messages + <li><code>sender</code> is the project number of the account authorized to send messages to the Android application. </li> <li><code>app</code> is the Android application's ID, set with a <code>PendingIntent</code> to allow the registration service to extract Android application information. </li> @@ -675,6 +674,16 @@ sent. Optional. The default value is <code>false</code>, and must be a JSON bool <td><code>time_to_live</code></td> <td>How long (in seconds) the message should be kept on GCM storage if the device is offline. Optional (default time-to-live is 4 weeks, and must be set as a JSON number).</td> </tr> +<tr> + <td><code>restricted_package_name</code></td> + <td>A string containing the package name of your application. When set, messages will only be sent to registration IDs that match the package name. Optional. + </td> +</tr> +<tr> + <td><code>dry_run</code></td> + <td>If included, allows developers to test their request without actually sending a message. Optional. The default value is <code>false</code>, and must be a JSON boolean. + </td> +</tr> </table> <p>If you are using plain text instead of JSON, the message fields must be set as HTTP parameters sent in the body, and their syntax is slightly different, as described below: @@ -706,9 +715,19 @@ sent. Optional. The default value is <code>false</code>, and must be a JSON bool <td><code>time_to_live</code></td> <td>Same as JSON (see previous table). Optional.</td> </tr> +<tr> + <td><code>restricted_package_name</code></td> + <td>Same as JSON (see previous table). Optional. + </td> +</tr> +<tr> + <td><code>dry_run</code></td> + <td>Same as JSON (see previous table). Optional. + </td> +</tr> </table> - +<p>If you want to test your request (either JSON or plain text) without delivering the message to the devices, you can set an optional HTTP or JSON parameter called <code>dry_run</code> with the value <code>true</code>. The result will be almost identical to running the request without this parameter, except that the message will not be delivered to the devices. Consequently, the response will contain fake IDs for the message and multicast fields (see <a href="#response">Response format</a>).</p> <h4 id="example-requests">Example requests</h4> <p>Here is the smallest possible request (a message without any parameters and just one recipient) using JSON:</p> @@ -889,7 +908,7 @@ Happens when the error code is <code>InvalidDataKey</code>.</dd> <dt id="auth_error"><strong>Authentication Error</strong></dt> <dd>The sender account that you're trying to use to send a message couldn't be authenticated. Possible causes are: <ul> <li>Authorization header missing or with invalid syntax.</li> -<li>Invalid project ID sent as key.</li> +<li>Invalid project number sent as key.</li> <li>Key valid but with GCM service disabled.</li> <li>Request originated from a server not whitelisted in the Server Key IPs.</li> @@ -944,6 +963,13 @@ Happens when the HTTP status code is 500, or when the <code>error</code> field o object in the results array is <code>InternalServerError</code>. </dd> +<dt id="restricted_package_name"><strong>Invalid Package Name</strong></dt> + +<dd> +A message was addressed to a registration ID whose package name did not match the value passed in the request. Happens when error code is +<code>InvalidPackageName</code>. +</dd> + </dl> <h4>Example responses</h4> diff --git a/docs/html/guide/google/gcm/gs.jd b/docs/html/guide/google/gcm/gs.jd index 8d132d8..fc5c4a2 100644 --- a/docs/html/guide/google/gcm/gs.jd +++ b/docs/html/guide/google/gcm/gs.jd @@ -41,7 +41,7 @@ page.title=GCM: Getting Started <pre> https://code.google.com/apis/console/#project:<strong>4815162342</strong></pre> - <li> Take note of the value after <code>#project:</code> (4815162342 in this example). This is your project ID, and it will be used later on as the GCM sender ID.</li> + <li> Take note of the value after <code>#project:</code> (4815162342 in this example). This is your project number, and it will be used later on as the GCM sender ID.</li> </ol> <h2 id="gcm-service">Enabling the GCM Service</h2> diff --git a/docs/html/guide/google/play/expansion-files.jd b/docs/html/guide/google/play/expansion-files.jd index f5cda06..9cd1bb1 100644 --- a/docs/html/guide/google/play/expansion-files.jd +++ b/docs/html/guide/google/play/expansion-files.jd @@ -114,9 +114,10 @@ yourself or be able to distinguish between the two files.</p> <h3 id="Filename">File name format</h3> -<p>Each expansion file you upload can be any format you choose (ZIP, PDF, MP4, etc.). Regardless of -the file type, Google Play considers them opaque binary blobs and renames the files -using the following scheme:</p> +<p>Each expansion file you upload can be any format you choose (ZIP, PDF, MP4, etc.). You can also +use the <a href="{@docRoot}tools/help/jobb.html">JOBB</a> tool to encapsulate and encrypt a set +of resource files and subsequent patches for that set. Regardless of the file type, Google Play +considers them opaque binary blobs and renames the files using the following scheme:</p> <pre class="classic no-pretty-print"> [main|patch].<expansion-version>.<package-name>.obb @@ -136,7 +137,7 @@ value). <p>"First" is emphasized because although the Developer Console allows you to re-use an uploaded expansion file with a new APK, the expansion file's name does not change—it retains the version applied to it when you first uploaded the file.</p></dd> - <dt>{@code <package-name>}</dt> + <dt>{@code <package-name>}</dt> <dd>Your application's Java-style package name.</dd> </dl> @@ -253,7 +254,7 @@ expansion file, you can use the patch file for the rest of your assets.</p> <li>Develop your application such that it uses the resources from your expansion files in the device's <a href="#StorageLocation">shared storage location</a>. <p>Remember that you must not delete, move, or rename the expansion files.</p> - <p>If your application doesn't demand a specific format, we suggest you create ZIP files for + <p>If your application doesn't demand a specific format, we suggest you create ZIP files for your expansion files, then read them using the <a href="#ZipLib">APK Expansion Zip Library</a>.</p> </li> @@ -347,7 +348,7 @@ href="#StorageLocation">shared storage location</a> (in the <ol> <li>Perform a request using Google Play's <a href="{@docRoot}guide/google/play/licensing/index.html">Application Licensing</a> to get your -app's expansion file names, sizes, and URLs.</li> +app's expansion file names, sizes, and URLs.</li> <li>Use the URLs provided by Google Play to download the expansion files and save the expansion files. You <strong>must</strong> save the files to the <a href="#StorageLocation">shared storage location</a> @@ -651,7 +652,7 @@ public class SampleAlarmReceiver extends BroadcastReceiver { SampleDownloaderService.class); } catch (NameNotFoundException e) { e.printStackTrace(); - } + } } } </pre> @@ -698,7 +699,7 @@ boolean expansionFilesDelivered() { return false; } return true; -} +} </pre> <p>In this case, each {@code XAPKFile} object holds the version number and file size of a known expansion file and a boolean as to whether it's the main expansion file. (See the sample @@ -749,7 +750,7 @@ public void onCreate(Bundle savedInstanceState) { ... PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, notifierIntent, PendingIntent.FLAG_UPDATE_CURRENT); - + // Start the download service (if required) int startResult = DownloaderClientMarshaller.startDownloadServiceIfRequired(this, pendingIntent, SampleDownloaderService.class); @@ -1050,9 +1051,9 @@ your ZIP expansion files as a virtual file system.</p> <dl> <dt>{@code APKExpansionSupport}</dt> <dd>Provides some methods to access expansion file names and ZIP files: - + <dl style="margin-top:1em"> - <dt>{@code getAPKExpansionFiles()}</dt> + <dt>{@code getAPKExpansionFiles()}</dt> <dd>The same method shown above that returns the complete file path to both expansion files.</dd> <dt>{@code getAPKExpansionZipFile(Context ctx, int mainVersion, int @@ -1063,7 +1064,7 @@ patch file. That is, if you specify both the <code>mainVersion</code> and the all the data, with the patch file's data merged on top of the main file.</dd> </dl> </dd> - + <dt>{@code ZipResourceFile}</dt> <dd>Represents a ZIP file on the shared storage and performs all the work to provide a virtual file system based on your ZIP files. You can get an instance using {@code @@ -1083,7 +1084,7 @@ the root of the ZIP file contents. This is useful for certain Android APIs that android.content.res.AssetFileDescriptor}, such as some {@link android.media.MediaPlayer} APIs.</dd> </dl> </dd> - + <dt>{@code APEZProvider}</dt> <dd>Most applications don't need to use this class. This class defines a {@link android.content.ContentProvider} that marshals the data from the ZIP files through a content @@ -1101,7 +1102,7 @@ following:</p> // Get a ZipResourceFile representing a merger of both the main and patch files ZipResourceFile expansionFile = APKExpansionSupport.getAPKExpansionZipFile(appContext, mainVersion, patchVersion); - + // Get an input stream for a known file inside the expansion file ZIPs InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip); </pre> @@ -1254,7 +1255,7 @@ you can easily read all the expansion file data.</li> <!-- Tools are not ready. - + <h3>Using OBB tool and APIs</h3> <pre> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 46c4398..d875f47 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -529,25 +529,6 @@ <li><a href="<?cs var:toroot ?>guide/practices/tablets-and-handsets.html"> <span class="en">Supporting Tablets and Handsets</span> </a></li> - <li class="nav-section"> - <div class="nav-section-header"><a href="<?cs var:toroot ?>guide/practices/performance.html"> - <span class="en">Designing for Performance</span> - </a></div> - <ul> - <li><a href="<?cs var:toroot ?>guide/practices/jni.html"> - <span class="en">JNI Tips</span> - </a></li> - </ul> - </li> - <li><a href="<?cs var:toroot ?>guide/practices/responsiveness.html"> - <span class="en">Designing for Responsiveness</span> - </a></li> - <li><a href="<?cs var:toroot ?>guide/practices/seamlessness.html"> - <span class="en">Designing for Seamlessness</span> - </a></li> - <li><a href="<?cs var:toroot ?>guide/practices/security.html"> - <span class="en">Designing for Security</span> - </a></li> </ul> </li> diff --git a/docs/html/guide/practices/app-design/performance.jd b/docs/html/guide/practices/app-design/performance.jd deleted file mode 100644 index 078999b..0000000 --- a/docs/html/guide/practices/app-design/performance.jd +++ /dev/null @@ -1,410 +0,0 @@ -page.title=Designing for Performance -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> - <li><a href="#intro">Introduction</a></li> - <li><a href="#optimize_judiciously">Optimize Judiciously</a></li> - <li><a href="#object_creation">Avoid Creating Unnecessary Objects</a></li> - <li><a href="#myths">Performance Myths</a></li> - <li><a href="#prefer_static">Prefer Static Over Virtual</a></li> - <li><a href="#internal_get_set">Avoid Internal Getters/Setters</a></li> - <li><a href="#use_final">Use Static Final For Constants</a></li> - <li><a href="#foreach">Use Enhanced For Loop Syntax</a></li> - <li><a href="#package_inner">Consider Package Instead of Private Access with Inner Classes</a></li> - <li><a href="#avoidfloat">Use Floating-Point Judiciously</a> </li> - <li><a href="#library">Know And Use The Libraries</a></li> - <li><a href="#native_methods">Use Native Methods Judiciously</a></li> - <li><a href="#closing_notes">Closing Notes</a></li> -</ol> - -</div> -</div> - -<p>An Android application will run on a mobile device with limited computing -power and storage, and constrained battery life. Because of -this, it should be <em>efficient</em>. Battery life is one reason you might -want to optimize your app even if it already seems to run "fast enough". -Battery life is important to users, and Android's battery usage breakdown -means users will know if your app is responsible draining their battery.</p> - -<p>Note that although this document primarily covers micro-optimizations, -these will almost never make or break your software. Choosing the right -algorithms and data structures should always be your priority, but is -outside the scope of this document.</p> - -<a name="intro" id="intro"></a> -<h2>Introduction</h2> - -<p>There are two basic rules for writing efficient code:</p> -<ul> - <li>Don't do work that you don't need to do.</li> - <li>Don't allocate memory if you can avoid it.</li> -</ul> - -<h2 id="optimize_judiciously">Optimize Judiciously</h2> - -<p>This document is about Android-specific micro-optimization, so it assumes -that you've already used profiling to work out exactly what code needs to be -optimized, and that you already have a way to measure the effect (good or bad) -of any changes you make. You only have so much engineering time to invest, so -it's important to know you're spending it wisely. - -<p>(See <a href="#closing_notes">Closing Notes</a> for more on profiling and -writing effective benchmarks.) - -<p>This document also assumes that you made the best decisions about data -structures and algorithms, and that you've also considered the future -performance consequences of your API decisions. Using the right data -structures and algorithms will make more difference than any of the advice -here, and considering the performance consequences of your API decisions will -make it easier to switch to better implementations later (this is more -important for library code than for application code). - -<p>(If you need that kind of advice, see Josh Bloch's <em>Effective Java</em>, -item 47.)</p> - -<p>One of the trickiest problems you'll face when micro-optimizing an Android -app is that your app is pretty much guaranteed to be running on multiple -hardware platforms. Different versions of the VM running on different -processors running at different speeds. It's not even generally the case -that you can simply say "device X is a factor F faster/slower than device Y", -and scale your results from one device to others. In particular, measurement -on the emulator tells you very little about performance on any device. There -are also huge differences between devices with and without a JIT: the "best" -code for a device with a JIT is not always the best code for a device -without.</p> - -<p>If you want to know how your app performs on a given device, you need to -test on that device.</p> - -<a name="object_creation"></a> -<h2>Avoid Creating Unnecessary Objects</h2> - -<p>Object creation is never free. A generational GC with per-thread allocation -pools for temporary objects can make allocation cheaper, but allocating memory -is always more expensive than not allocating memory.</p> - -<p>If you allocate objects in a user interface loop, you will force a periodic -garbage collection, creating little "hiccups" in the user experience. The -concurrent collector introduced in Gingerbread helps, but unnecessary work -should always be avoided.</p> - -<p>Thus, you should avoid creating object instances you don't need to. Some -examples of things that can help:</p> - -<ul> - <li>If you have a method returning a string, and you know that its result - will always be appended to a StringBuffer anyway, change your signature - and implementation so that the function does the append directly, - instead of creating a short-lived temporary object.</li> - <li>When extracting strings from a set of input data, try - to return a substring of the original data, instead of creating a copy. - You will create a new String object, but it will share the char[] - with the data. (The trade-off being that if you're only using a small - part of the original input, you'll be keeping it all around in memory - anyway if you go this route.)</li> -</ul> - -<p>A somewhat more radical idea is to slice up multidimensional arrays into -parallel single one-dimension arrays:</p> - -<ul> - <li>An array of ints is a much better than an array of Integers, - but this also generalizes to the fact that two parallel arrays of ints - are also a <strong>lot</strong> more efficient than an array of (int,int) - objects. The same goes for any combination of primitive types.</li> - <li>If you need to implement a container that stores tuples of (Foo,Bar) - objects, try to remember that two parallel Foo[] and Bar[] arrays are - generally much better than a single array of custom (Foo,Bar) objects. - (The exception to this, of course, is when you're designing an API for - other code to access; in those cases, it's usually better to trade - good API design for a small hit in speed. But in your own internal - code, you should try and be as efficient as possible.)</li> -</ul> - -<p>Generally speaking, avoid creating short-term temporary objects if you -can. Fewer objects created mean less-frequent garbage collection, which has -a direct impact on user experience.</p> - -<a name="avoid_enums" id="avoid_enums"></a> -<a name="myths" id="myths"></a> -<h2>Performance Myths</h2> - -<p>Previous versions of this document made various misleading claims. We -address some of them here.</p> - -<p>On devices without a JIT, it is true that invoking methods via a -variable with an exact type rather than an interface is slightly more -efficient. (So, for example, it was cheaper to invoke methods on a -<code>HashMap map</code> than a <code>Map map</code>, even though in both -cases the map was a <code>HashMap</code>.) It was not the case that this -was 2x slower; the actual difference was more like 6% slower. Furthermore, -the JIT makes the two effectively indistinguishable.</p> - -<p>On devices without a JIT, caching field accesses is about 20% faster than -repeatedly accesssing the field. With a JIT, field access costs about the same -as local access, so this isn't a worthwhile optimization unless you feel it -makes your code easier to read. (This is true of final, static, and static -final fields too.) - -<a name="prefer_static" id="prefer_static"></a> -<h2>Prefer Static Over Virtual</h2> - -<p>If you don't need to access an object's fields, make your method static. -Invocations will be about 15%-20% faster. -It's also good practice, because you can tell from the method -signature that calling the method can't alter the object's state.</p> - -<a name="internal_get_set" id="internal_get_set"></a> -<h2>Avoid Internal Getters/Setters</h2> - -<p>In native languages like C++ it's common practice to use getters (e.g. -<code>i = getCount()</code>) instead of accessing the field directly (<code>i -= mCount</code>). This is an excellent habit for C++, because the compiler can -usually inline the access, and if you need to restrict or debug field access -you can add the code at any time.</p> - -<p>On Android, this is a bad idea. Virtual method calls are expensive, -much more so than instance field lookups. It's reasonable to follow -common object-oriented programming practices and have getters and setters -in the public interface, but within a class you should always access -fields directly.</p> - -<p>Without a JIT, direct field access is about 3x faster than invoking a -trivial getter. With the JIT (where direct field access is as cheap as -accessing a local), direct field access is about 7x faster than invoking a -trivial getter. This is true in Froyo, but will improve in the future when -the JIT inlines getter methods.</p> - -<p>Note that if you're using ProGuard, you can have the best -of both worlds because ProGuard can inline accessors for you.</p> - -<a name="use_final" id="use_final"></a> -<h2>Use Static Final For Constants</h2> - -<p>Consider the following declaration at the top of a class:</p> - -<pre>static int intVal = 42; -static String strVal = "Hello, world!";</pre> - -<p>The compiler generates a class initializer method, called -<code><clinit></code>, that is executed when the class is first used. -The method stores the value 42 into <code>intVal</code>, and extracts a -reference from the classfile string constant table for <code>strVal</code>. -When these values are referenced later on, they are accessed with field -lookups.</p> - -<p>We can improve matters with the "final" keyword:</p> - -<pre>static final int intVal = 42; -static final String strVal = "Hello, world!";</pre> - -<p>The class no longer requires a <code><clinit></code> method, -because the constants go into static field initializers in the dex file. -Code that refers to <code>intVal</code> will use -the integer value 42 directly, and accesses to <code>strVal</code> will -use a relatively inexpensive "string constant" instruction instead of a -field lookup. (Note that this optimization only applies to primitive types and -<code>String</code> constants, not arbitrary reference types. Still, it's good -practice to declare constants <code>static final</code> whenever possible.)</p> - -<a name="foreach" id="foreach"></a> -<h2>Use Enhanced For Loop Syntax</h2> - -<p>The enhanced for loop (also sometimes known as "for-each" loop) can be used -for collections that implement the Iterable interface and for arrays. -With collections, an iterator is allocated to make interface calls -to hasNext() and next(). With an ArrayList, a hand-written counted loop is -about 3x faster (with or without JIT), but for other collections the enhanced -for loop syntax will be exactly equivalent to explicit iterator usage.</p> - -<p>There are several alternatives for iterating through an array:</p> - -<pre> static class Foo { - int mSplat; - } - Foo[] mArray = ... - - public void zero() { - int sum = 0; - for (int i = 0; i < mArray.length; ++i) { - sum += mArray[i].mSplat; - } - } - - public void one() { - int sum = 0; - Foo[] localArray = mArray; - int len = localArray.length; - - for (int i = 0; i < len; ++i) { - sum += localArray[i].mSplat; - } - } - - public void two() { - int sum = 0; - for (Foo a : mArray) { - sum += a.mSplat; - } - } -</pre> - -<p><strong>zero()</strong> is slowest, because the JIT can't yet optimize away -the cost of getting the array length once for every iteration through the -loop.</p> - -<p><strong>one()</strong> is faster. It pulls everything out into local -variables, avoiding the lookups. Only the array length offers a performance -benefit.</p> - -<p><strong>two()</strong> is fastest for devices without a JIT, and -indistinguishable from <strong>one()</strong> for devices with a JIT. -It uses the enhanced for loop syntax introduced in version 1.5 of the Java -programming language.</p> - -<p>To summarize: use the enhanced for loop by default, but consider a -hand-written counted loop for performance-critical ArrayList iteration.</p> - -<p>(See also <em>Effective Java</em> item 46.)</p> - -<a name="package_inner" id="package_inner"></a> -<h2>Consider Package Instead of Private Access with Private Inner Classes</h2> - -<p>Consider the following class definition:</p> - -<pre>public class Foo { - private class Inner { - void stuff() { - Foo.this.doStuff(Foo.this.mValue); - } - } - - private int mValue; - - public void run() { - Inner in = new Inner(); - mValue = 27; - in.stuff(); - } - - private void doStuff(int value) { - System.out.println("Value is " + value); - } -}</pre> - -<p>The key things to note here are that we define a private inner class -(<code>Foo$Inner</code>) that directly accesses a private method and a private -instance field in the outer class. This is legal, and the code prints "Value is -27" as expected.</p> - -<p>The problem is that the VM considers direct access to <code>Foo</code>'s -private members from <code>Foo$Inner</code> to be illegal because -<code>Foo</code> and <code>Foo$Inner</code> are different classes, even though -the Java language allows an inner class to access an outer class' private -members. To bridge the gap, the compiler generates a couple of synthetic -methods:</p> - -<pre>/*package*/ static int Foo.access$100(Foo foo) { - return foo.mValue; -} -/*package*/ static void Foo.access$200(Foo foo, int value) { - foo.doStuff(value); -}</pre> - -<p>The inner class code calls these static methods whenever it needs to -access the <code>mValue</code> field or invoke the <code>doStuff</code> method -in the outer class. What this means is that the code above really boils down to -a case where you're accessing member fields through accessor methods. -Earlier we talked about how accessors are slower than direct field -accesses, so this is an example of a certain language idiom resulting in an -"invisible" performance hit.</p> - -<p>If you're using code like this in a performance hotspot, you can avoid the -overhead by declaring fields and methods accessed by inner classes to have -package access, rather than private access. Unfortunately this means the fields -can be accessed directly by other classes in the same package, so you shouldn't -use this in public API.</p> - -<a name="avoidfloat" id="avoidfloat"></a> -<h2>Use Floating-Point Judiciously</h2> - -<p>As a rule of thumb, floating-point is about 2x slower than integer on -Android devices. This is true on a FPU-less, JIT-less G1 and a Nexus One with -an FPU and the JIT. (Of course, absolute speed difference between those two -devices is about 10x for arithmetic operations.)</p> - -<p>In speed terms, there's no difference between <code>float</code> and -<code>double</code> on the more modern hardware. Space-wise, <code>double</code> -is 2x larger. As with desktop machines, assuming space isn't an issue, you -should prefer <code>double</code> to <code>float</code>.</p> - -<p>Also, even for integers, some chips have hardware multiply but lack -hardware divide. In such cases, integer division and modulus operations are -performed in software — something to think about if you're designing a -hash table or doing lots of math.</p> - -<a name="library" id="library"></a> -<h2>Know And Use The Libraries</h2> - -<p>In addition to all the usual reasons to prefer library code over rolling -your own, bear in mind that the system is at liberty to replace calls -to library methods with hand-coded assembler, which may be better than the -best code the JIT can produce for the equivalent Java. The typical example -here is <code>String.indexOf</code> and friends, which Dalvik replaces with -an inlined intrinsic. Similarly, the <code>System.arraycopy</code> method -is about 9x faster than a hand-coded loop on a Nexus One with the JIT.</p> - -<p>(See also <em>Effective Java</em> item 47.)</p> - -<a name="native_methods" id="native_methods"></a> -<h2>Use Native Methods Judiciously</h2> - -<p>Native code isn't necessarily more efficient than Java. For one thing, -there's a cost associated with the Java-native transition, and the JIT can't -optimize across these boundaries. If you're allocating native resources (memory -on the native heap, file descriptors, or whatever), it can be significantly -more difficult to arrange timely collection of these resources. You also -need to compile your code for each architecture you wish to run on (rather -than rely on it having a JIT). You may even have to compile multiple versions -for what you consider the same architecture: native code compiled for the ARM -processor in the G1 can't take full advantage of the ARM in the Nexus One, and -code compiled for the ARM in the Nexus One won't run on the ARM in the G1.</p> - -<p>Native code is primarily useful when you have an existing native codebase -that you want to port to Android, not for "speeding up" parts of a Java app.</p> - -<p>If you do need to use native code, you should read our -<a href="{@docRoot}guide/practices/jni.html">JNI Tips</a>.</p> - -<p>(See also <em>Effective Java</em> item 54.)</p> - -<a name="closing_notes" id="closing_notes"></a> -<h2>Closing Notes</h2> - -<p>One last thing: always measure. Before you start optimizing, make sure you -have a problem. Make sure you can accurately measure your existing performance, -or you won't be able to measure the benefit of the alternatives you try.</p> - -<p>Every claim made in this document is backed up by a benchmark. The source -to these benchmarks can be found in the <a href="http://code.google.com/p/dalvik/source/browse/#svn/trunk/benchmarks">code.google.com "dalvik" project</a>.</p> - -<p>The benchmarks are built with the -<a href="http://code.google.com/p/caliper/">Caliper</a> microbenchmarking -framework for Java. Microbenchmarks are hard to get right, so Caliper goes out -of its way to do the hard work for you, and even detect some cases where you're -not measuring what you think you're measuring (because, say, the VM has -managed to optimize all your code away). We highly recommend you use Caliper -to run your own microbenchmarks.</p> - -<p>You may also find -<a href="{@docRoot}tools/debugging/debugging-tracing.html">Traceview</a> useful -for profiling, but it's important to realize that it currently disables the JIT, -which may cause it to misattribute time to code that the JIT may be able to win -back. It's especially important after making changes suggested by Traceview -data to ensure that the resulting code actually runs faster when run without -Traceview. diff --git a/docs/html/guide/practices/app-design/responsiveness.jd b/docs/html/guide/practices/app-design/responsiveness.jd deleted file mode 100644 index a00e3aa..0000000 --- a/docs/html/guide/practices/app-design/responsiveness.jd +++ /dev/null @@ -1,140 +0,0 @@ -page.title=Designing for Responsiveness -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> - <li><a href="#anr">What Triggers ANR?</a></li> - <li><a href="#avoiding">How to Avoid ANR</a></li> - <li><a href="#reinforcing">Reinforcing Responsiveness</a></li> -</ol> - -</div> -</div> - -<div class="figure"> -<img src="{@docRoot}images/anr.png" alt="Screenshot of ANR dialog box" width="240" height="320"/> -<p><strong>Figure 1.</strong> An ANR dialog displayed to the user.</p> -</div> - -<p>It's possible to write code that wins every performance test in the world, -but still sends users in a fiery rage when they try to use the application. -These are the applications that aren't <em>responsive</em> enough — the -ones that feel sluggish, hang or freeze for significant periods, or take too -long to process input. </p> - -<p>In Android, the system guards against applications that are insufficiently -responsive for a period of time by displaying a dialog to the user, called the -Application Not Responding (ANR) dialog, shown at right in Figure 1. The user -can choose to let the application continue, but the user won't appreciate having -to act on this dialog every time he or she uses your application. It's critical -to design responsiveness into your application, so that the system never has -cause to display an ANR dialog to the user. </p> - -<p>Generally, the system displays an ANR if an application cannot respond to -user input. For example, if an application blocks on some I/O operation -(frequently a network access), then the main application thread won't be able to -process incoming user input events. After a time, the system concludes that the -application is frozen, and displays the ANR to give the user the option to kill -it. </p> - -<p>Similarly, if your application spends too much time building an elaborate in-memory -structure, or perhaps computing the next move in a game, the system will -conclude that your application has hung. It's always important to make -sure these computations are efficient using the techniques above, but even the -most efficient code still takes time to run.</p> - -<p>In both of these cases, the recommended approach is to create a child thread and do -most of your work there. This keeps the main thread (which drives the user -interface event loop) running and prevents the system from concluding that your code -has frozen. Since such threading usually is accomplished at the class -level, you can think of responsiveness as a <em>class</em> problem. (Compare -this with basic performance, which was described above as a <em>method</em>-level -concern.)</p> - -<p>This document describes how the Android system determines whether an -application is not responding and provides guidelines for ensuring that your -application stays responsive. </p> - -<h2 id="anr">What Triggers ANR?</h2> - -<p>In Android, application responsiveness is monitored by the Activity Manager -and Window Manager system services. Android will display the ANR dialog -for a particular application when it detects one of the following -conditions:</p> -<ul> - <li>No response to an input event (e.g. key press, screen touch) - within 5 seconds</li> - <li>A {@link android.content.BroadcastReceiver BroadcastReceiver} - hasn't finished executing within 10 seconds</li> -</ul> - -<h2 id="avoiding">How to Avoid ANR</h2> - -<p>Given the above definition for ANR, let's examine why this can occur in -Android applications and how best to structure your application to avoid ANR.</p> - -<p>Android applications normally run entirely on a single (i.e. main) thread. -This means that anything your application is doing in the main thread that -takes a long time to complete can trigger the ANR dialog because your -application is not giving itself a chance to handle the input event or Intent -broadcast.</p> - -<p>Therefore any method that runs in the main thread should do as little work -as possible. In particular, Activities should do as little as possible to set -up in key life-cycle methods such as <code>onCreate()</code> and -<code>onResume()</code>. Potentially long running operations such as network -or database operations, or computationally expensive calculations such as -resizing bitmaps should be done in a child thread (or in the case of databases -operations, via an asynchronous request). However, this does not mean that -your main thread should block while waiting for the child thread to -complete — nor should you call <code>Thread.wait()</code> or -<code>Thread.sleep()</code>. Instead of blocking while waiting for a child -thread to complete, your main thread should provide a {@link -android.os.Handler Handler} for child threads to post back to upon completion. -Designing your application in this way will allow your main thread to remain -responsive to input and thus avoid ANR dialogs caused by the 5 second input -event timeout. These same practices should be followed for any other threads -that display UI, as they are also subject to the same timeouts.</p> - -<p>You can use {@link android.os.StrictMode} to help find potentially -long running operations such as network or database operations that -you might accidentally be doing your main thread.</p> - -<p>The specific constraint on IntentReceiver execution time emphasizes what -they were meant to do: small, discrete amounts of work in the background such -as saving a setting or registering a Notification. So as with other methods -called in the main thread, applications should avoid potentially long-running -operations or calculations in BroadcastReceivers. But instead of doing intensive -tasks via child threads (as the life of a BroadcastReceiver is short), your -application should start a {@link android.app.Service Service} if a -potentially long running action needs to be taken in response to an Intent -broadcast. As a side note, you should also avoid starting an Activity from an -Intent Receiver, as it will spawn a new screen that will steal focus from -whatever application the user is currently has running. If your application -has something to show the user in response to an Intent broadcast, it should -do so using the {@link android.app.NotificationManager Notification -Manager}.</p> - -<h2 id="reinforcing">Reinforcing Responsiveness</h2> - -<p>Generally, 100 to 200ms is the threshold beyond which users will perceive -lag (or lack of "snappiness," if you will) in an application. As such, here -are some additional tips beyond what you should do to avoid ANR that will help -make your application seem responsive to users.</p> - -<ul> - <li>If your application is doing work in the background in response to - user input, show that progress is being made ({@link - android.widget.ProgressBar ProgressBar} and {@link - android.app.ProgressDialog ProgressDialog} are useful for this).</li> - <li>For games specifically, do calculations for moves in a child - thread.</li> - <li>If your application has a time-consuming initial setup phase, consider - showing a splash screen or rendering the main view as quickly as possible - and filling in the information asynchronously. In either case, you should - indicate somehow that progress is being made, lest the user perceive that - the application is frozen.</li> -</ul> diff --git a/docs/html/guide/practices/jni.jd b/docs/html/guide/practices/jni.jd deleted file mode 100644 index ddfa0e3..0000000 --- a/docs/html/guide/practices/jni.jd +++ /dev/null @@ -1,719 +0,0 @@ -page.title=JNI Tips -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> - <li><a href="#JavaVM_and_JNIEnv">JavaVM and JNIEnv</a></li> - <li><a href="#threads">Threads</a></li> - <li><a href="#jclass_jmethodID_and_jfieldID">jclass, jmethodID, and jfieldID</a></li> - <li><a href="#local_and_global_references">Local and Global References</a></li> - <li><a href="#UTF_8_and_UTF_16_strings">UTF-8 and UTF-16 Strings</a></li> - <li><a href="#arrays">Primitive Arrays</a></li> - <li><a href="#region_calls">Region Calls</a></li> - <li><a href="#exceptions">Exceptions</a></li> - <li><a href="#extended_checking">Extended Checking</a> </li> - <li><a href="#native_libraries">Native Libraries</a></li> - <li><a href="#64_bit">64-bit Considerations</a></li> - <li><a href="#unsupported">Unsupported Features/Backwards Compatibility</a></li> - <li><a href="#faq_ULE">FAQ: Why do I get <code>UnsatisfiedLinkError</code></a></li> - <li><a href="#faq_FindClass">FAQ: Why didn't <code>FindClass</code> find my class?</a></li> - <li><a href="#faq_sharing">FAQ: How do I share raw data with native code?</a></li> -</ol> - -</div> -</div> - -<p>JNI is the Java Native Interface. It defines a way for managed code -(written in the Java programming language) to interact with native -code (written in C/C++). It's vendor-neutral, has support for loading code from -dynamic shared libraries, and while cumbersome at times is reasonably efficient.</p> - -<p>You really should read through the -<a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/jniTOC.html">JNI spec for J2SE 6</a> -to get a sense for how JNI works and what features are available. Some -aspects of the interface aren't immediately obvious on -first reading, so you may find the next few sections handy. -There's a more detailed <a href="http://java.sun.com/docs/books/jni/html/jniTOC.html">JNI Programmer's Guide and Specification</a>.</p> - - -<a name="JavaVM_and_JNIEnv" id="JavaVM_and_JNIEnv"></a> -<h2>JavaVM and JNIEnv</h2> - -<p>JNI defines two key data structures, "JavaVM" and "JNIEnv". Both of these are essentially -pointers to pointers to function tables. (In the C++ version, they're classes with a -pointer to a function table and a member function for each JNI function that indirects through -the table.) The JavaVM provides the "invocation interface" functions, -which allow you to create and destroy a JavaVM. In theory you can have multiple JavaVMs per process, -but Android only allows one.</p> - -<p>The JNIEnv provides most of the JNI functions. Your native functions all receive a JNIEnv as -the first argument.</p> - -<p>The JNIEnv is used for thread-local storage. For this reason, <strong>you cannot share a JNIEnv between threads</strong>. -If a piece of code has no other way to get its JNIEnv, you should share -the JavaVM, and use <code>GetEnv</code> to discover the thread's JNIEnv. (Assuming it has one; see <code>AttachCurrentThread</code> below.)</p> - -<p>The C declarations of JNIEnv and JavaVM are different from the C++ -declarations. The <code>"jni.h"</code> include file provides different typedefs -depending on whether it's included into C or C++. For this reason it's a bad idea to -include JNIEnv arguments in header files included by both languages. (Put another way: if your -header file requires <code>#ifdef __cplusplus</code>, you may have to do some extra work if anything in -that header refers to JNIEnv.)</p> - -<a name="threads" id="threads"></a> -<h2>Threads</h2> - -<p>All threads are Linux threads, scheduled by the kernel. They're usually -started from managed code (using <code>Thread.start</code>), -but they can also be created elsewhere and then attached to the JavaVM. For -example, a thread started with <code>pthread_create</code> can be attached -with the JNI <code>AttachCurrentThread</code> or -<code>AttachCurrentThreadAsDaemon</code> functions. Until a thread is -attached, it has no JNIEnv, and <strong>cannot make JNI calls</strong>.</p> - -<p>Attaching a natively-created thread causes a <code>java.lang.Thread</code> -object to be constructed and added to the "main" <code>ThreadGroup</code>, -making it visible to the debugger. Calling <code>AttachCurrentThread</code> -on an already-attached thread is a no-op.</p> - -<p>Android does not suspend threads executing native code. If -garbage collection is in progress, or the debugger has issued a suspend -request, Android will pause the thread the next time it makes a JNI call.</p> - -<p>Threads attached through JNI <strong>must call -<code>DetachCurrentThread</code> before they exit</strong>. -If coding this directly is awkward, in Android 2.0 (Eclair) and higher you -can use <code>pthread_key_create</code> to define a destructor -function that will be called before the thread exits, and -call <code>DetachCurrentThread</code> from there. (Use that -key with <code>pthread_setspecific</code> to store the JNIEnv in -thread-local-storage; that way it'll be passed into your destructor as -the argument.)</p> - - -<a name="jclass_jmethodID_and_jfieldID" id="jclass_jmethodID_and_jfieldID"></a> -<h2>jclass, jmethodID, and jfieldID</h2> - -<p>If you want to access an object's field from native code, you would do the following:</p> - -<ul> -<li> Get the class object reference for the class with <code>FindClass</code></li> -<li> Get the field ID for the field with <code>GetFieldID</code></li> -<li> Get the contents of the field with something appropriate, such as -<code>GetIntField</code></li> -</ul> - -<p>Similarly, to call a method, you'd first get a class object reference and then a method ID. The IDs are often just -pointers to internal runtime data structures. Looking them up may require several string -comparisons, but once you have them the actual call to get the field or invoke the method -is very quick.</p> - -<p>If performance is important, it's useful to look the values up once and cache the results -in your native code. Because there is a limit of one JavaVM per process, it's reasonable -to store this data in a static local structure.</p> - -<p>The class references, field IDs, and method IDs are guaranteed valid until the class is unloaded. Classes -are only unloaded if all classes associated with a ClassLoader can be garbage collected, -which is rare but will not be impossible in Android. Note however that -the <code>jclass</code> -is a class reference and <strong>must be protected</strong> with a call -to <code>NewGlobalRef</code> (see the next section).</p> - -<p>If you would like to cache the IDs when a class is loaded, and automatically re-cache them -if the class is ever unloaded and reloaded, the correct way to initialize -the IDs is to add a piece of code that looks like this to the appropriate class:</p> - -<pre> /* - * We use a class initializer to allow the native code to cache some - * field offsets. This native function looks up and caches interesting - * class/field/method IDs. Throws on failure. - */ - private static native void nativeInit(); - - static { - nativeInit(); - }</pre> - -<p>Create a <code>nativeClassInit</code> method in your C/C++ code that performs the ID lookups. The code -will be executed once, when the class is initialized. If the class is ever unloaded and -then reloaded, it will be executed again.</p> - -<a name="local_and_global_references" id="local_and_global_references"></a> -<h2>Local and Global References</h2> - -<p>Every argument passed to a native method, and almost every object returned -by a JNI function is a "local reference". This means that it's valid for the -duration of the current native method in the current thread. -<strong>Even if the object itself continues to live on after the native method -returns, the reference is not valid.</strong> -<p>This applies to all sub-classes of <code>jobject</code>, including -<code>jclass</code>, <code>jstring</code>, and <code>jarray</code>. -(The runtime will warn you about most reference mis-uses when extended JNI -checks are enabled.)</p> -<p>The only way to get non-local references is via the functions -<code>NewGlobalRef</code> and <code>NewWeakGlobalRef</code>. - -<p>If you want to hold on to a reference for a longer period, you must use -a "global" reference. The <code>NewGlobalRef</code> function takes the -local reference as an argument and returns a global one. -The global reference is guaranteed to be valid until you call -<code>DeleteGlobalRef</code>.</p> - -<p>This pattern is commonly used when caching a jclass returned -from <code>FindClass</code>, e.g.:</p> -<pre>jclass localClass = env->FindClass("MyClass"); -jclass globalClass = reinterpret_cast<jclass>(env->NewGlobalRef(localClass));</pre> - -<p>All JNI methods accept both local and global references as arguments. -It's possible for references to the same object to have different values. -For example, the return values from consecutive calls to -<code>NewGlobalRef</code> on the same object may be different. -<strong>To see if two references refer to the same object, -you must use the <code>IsSameObject</code> function.</strong> Never compare -references with <code>==</code> in native code.</p> - -<p>One consequence of this is that you -<strong>must not assume object references are constant or unique</strong> -in native code. The 32-bit value representing an object may be different -from one invocation of a method to the next, and it's possible that two -different objects could have the same 32-bit value on consecutive calls. Do -not use <code>jobject</code> values as keys.</p> - -<p>Programmers are required to "not excessively allocate" local references. In practical terms this means -that if you're creating large numbers of local references, perhaps while running through an array of -objects, you should free them manually with -<code>DeleteLocalRef</code> instead of letting JNI do it for you. The -implementation is only required to reserve slots for -16 local references, so if you need more than that you should either delete as you go or use -<code>EnsureLocalCapacity</code>/<code>PushLocalFrame</code> to reserve more.</p> - -<p>Note that <code>jfieldID</code>s and <code>jmethodID</code>s are opaque -types, not object references, and should not be passed to -<code>NewGlobalRef</code>. The raw data -pointers returned by functions like <code>GetStringUTFChars</code> -and <code>GetByteArrayElements</code> are also not objects. (They may be passed -between threads, and are valid until the matching Release call.)</p> - -<p>One unusual case deserves separate mention. If you attach a native -thread with <code>AttachCurrentThread</code>, the code you are running will -never automatically free local references until the thread detaches. Any local -references you create will have to be deleted manually. In general, any native -code that creates local references in a loop probably needs to do some manual -deletion.</p> - -<a name="UTF_8_and_UTF_16_strings" id="UTF_8_and_UTF_16_strings"></a> -<h2>UTF-8 and UTF-16 Strings</h2> - -<p>The Java programming language uses UTF-16. For convenience, JNI provides methods that work with <a href="http://en.wikipedia.org/wiki/UTF-8#Modified_UTF-8">Modified UTF-8</a> as well. The -modified encoding is useful for C code because it encodes \u0000 as 0xc0 0x80 instead of 0x00. -The nice thing about this is that you can count on having C-style zero-terminated strings, -suitable for use with standard libc string functions. The down side is that you cannot pass -arbitrary UTF-8 data to JNI and expect it to work correctly.</p> - -<p>If possible, it's usually faster to operate with UTF-16 strings. Android -currently does not require a copy in <code>GetStringChars</code>, whereas -<code>GetStringUTFChars</code> requires an allocation and a conversion to -UTF-8. Note that -<strong>UTF-16 strings are not zero-terminated</strong>, and \u0000 is allowed, -so you need to hang on to the string length as well as -the jchar pointer.</p> - -<p><strong>Don't forget to <code>Release</code> the strings you <code>Get</code></strong>. The -string functions return <code>jchar*</code> or <code>jbyte*</code>, which -are C-style pointers to primitive data rather than local references. They -are guaranteed valid until <code>Release</code> is called, which means they are not -released when the native method returns.</p> - -<p><strong>Data passed to NewStringUTF must be in Modified UTF-8 format</strong>. A -common mistake is reading character data from a file or network stream -and handing it to <code>NewStringUTF</code> without filtering it. -Unless you know the data is 7-bit ASCII, you need to strip out high-ASCII -characters or convert them to proper Modified UTF-8 form. If you don't, -the UTF-16 conversion will likely not be what you expect. The extended -JNI checks will scan strings and warn you about invalid data, but they -won't catch everything.</p> - -<a name="arrays" id="arrays"></a> -<h2>Primitive Arrays</h2> - -<p>JNI provides functions for accessing the contents of array objects. -While arrays of objects must be accessed one entry at a time, arrays of -primitives can be read and written directly as if they were declared in C.</p> - -<p>To make the interface as efficient as possible without constraining -the VM implementation, the <code>Get<PrimitiveType>ArrayElements</code> -family of calls allows the runtime to either return a pointer to the actual elements, or -allocate some memory and make a copy. Either way, the raw pointer returned -is guaranteed to be valid until the corresponding <code>Release</code> call -is issued (which implies that, if the data wasn't copied, the array object -will be pinned down and can't be relocated as part of compacting the heap). -<strong>You must <code>Release</code> every array you <code>Get</code>.</strong> Also, if the <code>Get</code> -call fails, you must ensure that your code doesn't try to <code>Release</code> a NULL -pointer later.</p> - -<p>You can determine whether or not the data was copied by passing in a -non-NULL pointer for the <code>isCopy</code> argument. This is rarely -useful.</p> - -<p>The <code>Release</code> call takes a <code>mode</code> argument that can -have one of three values. The actions performed by the runtime depend upon -whether it returned a pointer to the actual data or a copy of it:</p> - -<ul> - <li><code>0</code> - <ul> - <li>Actual: the array object is un-pinned. - <li>Copy: data is copied back. The buffer with the copy is freed. - </ul> - <li><code>JNI_COMMIT</code> - <ul> - <li>Actual: does nothing. - <li>Copy: data is copied back. The buffer with the copy - <strong>is not freed</strong>. - </ul> - <li><code>JNI_ABORT</code> - <ul> - <li>Actual: the array object is un-pinned. Earlier - writes are <strong>not</strong> aborted. - <li>Copy: the buffer with the copy is freed; any changes to it are lost. - </ul> -</ul> - -<p>One reason for checking the <code>isCopy</code> flag is to know if -you need to call <code>Release</code> with <code>JNI_COMMIT</code> -after making changes to an array — if you're alternating between making -changes and executing code that uses the contents of the array, you may be -able to -skip the no-op commit. Another possible reason for checking the flag is for -efficient handling of <code>JNI_ABORT</code>. For example, you might want -to get an array, modify it in place, pass pieces to other functions, and -then discard the changes. If you know that JNI is making a new copy for -you, there's no need to create another "editable" copy. If JNI is passing -you the original, then you do need to make your own copy.</p> - -<p>It is a common mistake (repeated in example code) to assume that you can skip the <code>Release</code> call if -<code>*isCopy</code> is false. This is not the case. If no copy buffer was -allocated, then the original memory must be pinned down and can't be moved by -the garbage collector.</p> - -<p>Also note that the <code>JNI_COMMIT</code> flag does <strong>not</strong> release the array, -and you will need to call <code>Release</code> again with a different flag -eventually.</p> - - -<a name="region_calls" id="region_calls"></a> -<h2>Region Calls</h2> - -<p>There is an alternative to calls like <code>Get<Type>ArrayElements</code> -and <code>GetStringChars</code> that may be very helpful when all you want -to do is copy data in or out. Consider the following:</p> - -<pre> jbyte* data = env->GetByteArrayElements(array, NULL); - if (data != NULL) { - memcpy(buffer, data, len); - env->ReleaseByteArrayElements(array, data, JNI_ABORT); - }</pre> - -<p>This grabs the array, copies the first <code>len</code> byte -elements out of it, and then releases the array. Depending upon the -implementation, the <code>Get</code> call will either pin or copy the array -contents. -The code copies the data (for perhaps a second time), then calls <code>Release</code>; in this case -<code>JNI_ABORT</code> ensures there's no chance of a third copy.</p> - -<p>One can accomplish the same thing more simply:</p> -<pre> env->GetByteArrayRegion(array, 0, len, buffer);</pre> - -<p>This has several advantages:</p> -<ul> - <li>Requires one JNI call instead of 2, reducing overhead. - <li>Doesn't require pinning or extra data copies. - <li>Reduces the risk of programmer error — no risk of forgetting - to call <code>Release</code> after something fails. -</ul> - -<p>Similarly, you can use the <code>Set<Type>ArrayRegion</code> call -to copy data into an array, and <code>GetStringRegion</code> or -<code>GetStringUTFRegion</code> to copy characters out of a -<code>String</code>. - - -<a name="exceptions" id="exceptions"></a> -<h2>Exceptions</h2> - -<p><strong>You must not call most JNI functions while an exception is pending.</strong> -Your code is expected to notice the exception (via the function's return value, -<code>ExceptionCheck</code>, or <code>ExceptionOccurred</code>) and return, -or clear the exception and handle it.</p> - -<p>The only JNI functions that you are allowed to call while an exception is -pending are:</p> -<ul> - <li><code>DeleteGlobalRef</code> - <li><code>DeleteLocalRef</code> - <li><code>DeleteWeakGlobalRef</code> - <li><code>ExceptionCheck</code> - <li><code>ExceptionClear</code> - <li><code>ExceptionDescribe</code> - <li><code>ExceptionOccurred</code> - <li><code>MonitorExit</code> - <li><code>PopLocalFrame</code> - <li><code>PushLocalFrame</code> - <li><code>Release<PrimitiveType>ArrayElements</code> - <li><code>ReleasePrimitiveArrayCritical</code> - <li><code>ReleaseStringChars</code> - <li><code>ReleaseStringCritical</code> - <li><code>ReleaseStringUTFChars</code> -</ul> - -<p>Many JNI calls can throw an exception, but often provide a simpler way -of checking for failure. For example, if <code>NewString</code> returns -a non-NULL value, you don't need to check for an exception. However, if -you call a method (using a function like <code>CallObjectMethod</code>), -you must always check for an exception, because the return value is not -going to be valid if an exception was thrown.</p> - -<p>Note that exceptions thrown by interpreted code do not unwind native stack -frames, and Android does not yet support C++ exceptions. -The JNI <code>Throw</code> and <code>ThrowNew</code> instructions just -set an exception pointer in the current thread. Upon returning to managed -from native code, the exception will be noted and handled appropriately.</p> - -<p>Native code can "catch" an exception by calling <code>ExceptionCheck</code> or -<code>ExceptionOccurred</code>, and clear it with -<code>ExceptionClear</code>. As usual, -discarding exceptions without handling them can lead to problems.</p> - -<p>There are no built-in functions for manipulating the <code>Throwable</code> object -itself, so if you want to (say) get the exception string you will need to -find the <code>Throwable</code> class, look up the method ID for -<code>getMessage "()Ljava/lang/String;"</code>, invoke it, and if the result -is non-NULL use <code>GetStringUTFChars</code> to get something you can -hand to <code>printf(3)</code> or equivalent.</p> - - -<a name="extended_checking" id="extended_checking"></a> -<h2>Extended Checking</h2> - -<p>JNI does very little error checking. Errors usually result in a crash. Android also offers a mode called CheckJNI, where the JavaVM and JNIEnv function table pointers are switched to tables of functions that perform an extended series of checks before calling the standard implementation.</p> - -<p>The additional checks include:</p> - -<ul> -<li>Arrays: attempting to allocate a negative-sized array.</li> -<li>Bad pointers: passing a bad jarray/jclass/jobject/jstring to a JNI call, or passing a NULL pointer to a JNI call with a non-nullable argument.</li> -<li>Class names: passing anything but the “java/lang/String” style of class name to a JNI call.</li> -<li>Critical calls: making a JNI call between a “critical” get and its corresponding release.</li> -<li>Direct ByteBuffers: passing bad arguments to <code>NewDirectByteBuffer</code>.</li> -<li>Exceptions: making a JNI call while there’s an exception pending.</li> -<li>JNIEnv*s: using a JNIEnv* from the wrong thread.</li> -<li>jfieldIDs: using a NULL jfieldID, or using a jfieldID to set a field to a value of the wrong type (trying to assign a StringBuilder to a String field, say), or using a jfieldID for a static field to set an instance field or vice versa, or using a jfieldID from one class with instances of another class.</li> -<li>jmethodIDs: using the wrong kind of jmethodID when making a <code>Call*Method</code> JNI call: incorrect return type, static/non-static mismatch, wrong type for ‘this’ (for non-static calls) or wrong class (for static calls).</li> -<li>References: using <code>DeleteGlobalRef</code>/<code>DeleteLocalRef</code> on the wrong kind of reference.</li> -<li>Release modes: passing a bad release mode to a release call (something other than <code>0</code>, <code>JNI_ABORT</code>, or <code>JNI_COMMIT</code>).</li> -<li>Type safety: returning an incompatible type from your native method (returning a StringBuilder from a method declared to return a String, say).</li> -<li>UTF-8: passing an invalid <a href="http://en.wikipedia.org/wiki/UTF-8#Modified_UTF-8">Modified UTF-8</a> byte sequence to a JNI call.</li> -</ul> - -<p>(Accessibility of methods and fields is still not checked: access restrictions don't apply to native code.)</p> - -<p>There are several ways to enable CheckJNI.</p> - -<p>If you’re using the emulator, CheckJNI is on by default.</p> - -<p>If you have a rooted device, you can use the following sequence of commands to restart the runtime with CheckJNI enabled:</p> - -<pre>adb shell stop -adb shell setprop dalvik.vm.checkjni true -adb shell start</pre> - -<p>In either of these cases, you’ll see something like this in your logcat output when the runtime starts:</p> - -<pre>D AndroidRuntime: CheckJNI is ON</pre> - -<p>If you have a regular device, you can use the following command:</p> - -<pre>adb shell setprop debug.checkjni 1</pre> - -<p>This won’t affect already-running apps, but any app launched from that point on will have CheckJNI enabled. (Change the property to any other value or simply rebooting will disable CheckJNI again.) In this case, you’ll see something like this in your logcat output the next time an app starts:</p> - -<pre>D Late-enabling CheckJNI</pre> - - - - -<a name="native_libraries" id="native_libraries"></a> -<h2>Native Libraries</h2> - -<p>You can load native code from shared libraries with the standard -<code>System.loadLibrary</code> call. The -preferred way to get at your native code is:</p> - -<ul> -<li> Call <code>System.loadLibrary</code> from a static class -initializer. (See the earlier example, where one is used to call -<code>nativeClassInit</code>.) The argument is the "undecorated" -library name, so to load "libfubar.so" you would pass in "fubar".</li> -<li> Provide a native function: <code><strong>jint JNI_OnLoad(JavaVM* vm, void* reserved)</strong></code></li> -<li>In <code>JNI_OnLoad</code>, register all of your native methods. You -should declare -the methods "static" so the names don't take up space in the symbol table -on the device.</li> -</ul> - -<p>The <code>JNI_OnLoad</code> function should look something like this if -written in C++:</p> -<pre>jint JNI_OnLoad(JavaVM* vm, void* reserved) -{ - JNIEnv* env; - if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) { - return -1; - } - - // Get jclass with env->FindClass. - // Register methods with env->RegisterNatives. - - return JNI_VERSION_1_6; -}</pre> - -<p>You can also call <code>System.load</code> with the full path name of the -shared library. For Android apps, you may find it useful to get the full -path to the application's private data storage area from the context object.</p> - -<p>This is the recommended approach, but not the only approach. Explicit -registration is not required, nor is it necessary that you provide a -<code>JNI_OnLoad</code> function. -You can instead use "discovery" of native methods that are named in a -specific way (see <a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp615">the JNI spec</a> for details), though this is less desirable because if a method signature is wrong you won't know -about it until the first time the method is actually used.</p> - -<p>One other note about <code>JNI_OnLoad</code>: any <code>FindClass</code> -calls you make from there will happen in the context of the class loader -that was used to load the shared library. Normally <code>FindClass</code> -uses the loader associated with the method at the top of the interpreted -stack, or if there isn't one (because the thread was just attached) it uses -the "system" class loader. This makes -<code>JNI_OnLoad</code> a convenient place to look up and cache class -object references.</p> - - -<a name="64_bit" id="64_bit"></a> -<h2>64-bit Considerations</h2> - -<p>Android is currently expected to run on 32-bit platforms. In theory it -could be built for a 64-bit system, but that is not a goal at this time. -For the most part this isn't something that you will need to worry about -when interacting with native code, -but it becomes significant if you plan to store pointers to native -structures in integer fields in an object. To support architectures -that use 64-bit pointers, <strong>you need to stash your native pointers in a -<code>long</code> field rather than an <code>int</code></strong>. - - -<a name="unsupported" id="unsupported"></a> -<h2>Unsupported Features/Backwards Compatibility</h2> - -<p>All JNI 1.6 features are supported, with the following exception:</p> -<ul> - <li><code>DefineClass</code> is not implemented. Android does not use - Java bytecodes or class files, so passing in binary class data - doesn't work.</li> -</ul> - -<p>For backward compatibility with older Android releases, you may need to -be aware of:</p> -<ul> - <li><b>Dynamic lookup of native functions</b> - <p>Until Android 2.0 (Eclair), the '$' character was not properly - converted to "_00024" during searches for method names. Working - around this requires using explicit registration or moving the - native methods out of inner classes. - <li><b>Detaching threads</b> - <p>Until Android 2.0 (Eclair), it was not possible to use a <code>pthread_key_create</code> - destructor function to avoid the "thread must be detached before - exit" check. (The runtime also uses a pthread key destructor function, - so it'd be a race to see which gets called first.) - <li><b>Weak global references</b> - <p>Until Android 2.2 (Froyo), weak global references were not implemented. - Older versions will vigorously reject attempts to use them. You can use - the Android platform version constants to test for support. - <p>Until Android 4.0 (Ice Cream Sandwich), weak global references could only - be passed to <code>NewLocalRef</code>, <code>NewGlobalRef</code>, and - <code>DeleteWeakGlobalRef</code>. (The spec strongly encourages - programmers to create hard references to weak globals before doing - anything with them, so this should not be at all limiting.) - <p>From Android 4.0 (Ice Cream Sandwich) on, weak global references can be - used like any other JNI references.</li> - <li><b>Local references</b> - <p>Until Android 4.0 (Ice Cream Sandwich), local references were - actually direct pointers. Ice Cream Sandwich added the indirection - necessary to support better garbage collectors, but this means that lots - of JNI bugs are undetectable on older releases. See - <a href="http://android-developers.blogspot.com/2011/11/jni-local-reference-changes-in-ics.html">JNI Local Reference Changes in ICS</a> for more details. - <li><b>Determining reference type with <code>GetObjectRefType</code></b> - <p>Until Android 4.0 (Ice Cream Sandwich), as a consequence of the use of - direct pointers (see above), it was impossible to implement - <code>GetObjectRefType</code> correctly. Instead we used a heuristic - that looked through the weak globals table, the arguments, the locals - table, and the globals table in that order. The first time it found your - direct pointer, it would report that your reference was of the type it - happened to be examining. This meant, for example, that if - you called <code>GetObjectRefType</code> on a global jclass that happened - to be the same as the jclass passed as an implicit argument to your static - native method, you'd get <code>JNILocalRefType</code> rather than - <code>JNIGlobalRefType</code>. -</ul> - - -<a name="faq_ULE" id="faq_ULE"></a> -<h2>FAQ: Why do I get <code>UnsatisfiedLinkError</code>?</h2> - -<p>When working on native code it's not uncommon to see a failure like this:</p> -<pre>java.lang.UnsatisfiedLinkError: Library foo not found</pre> - -<p>In some cases it means what it says — the library wasn't found. In -other cases the library exists but couldn't be opened by <code>dlopen(3)</code>, and -the details of the failure can be found in the exception's detail message.</p> - -<p>Common reasons why you might encounter "library not found" exceptions:</p> -<ul> - <li>The library doesn't exist or isn't accessible to the app. Use - <code>adb shell ls -l <path></code> to check its presence - and permissions. - <li>The library wasn't built with the NDK. This can result in - dependencies on functions or libraries that don't exist on the device. -</ul> - -<p>Another class of <code>UnsatisfiedLinkError</code> failures looks like:</p> -<pre>java.lang.UnsatisfiedLinkError: myfunc - at Foo.myfunc(Native Method) - at Foo.main(Foo.java:10)</pre> - -<p>In logcat, you'll see:</p> -<pre>W/dalvikvm( 880): No implementation found for native LFoo;.myfunc ()V</pre> - -<p>This means that the runtime tried to find a matching method but was -unsuccessful. Some common reasons for this are:</p> -<ul> - <li>The library isn't getting loaded. Check the logcat output for - messages about library loading. - <li>The method isn't being found due to a name or signature mismatch. This - is commonly caused by: - <ul> - <li>For lazy method lookup, failing to declare C++ functions - with <code>extern "C"</code> and appropriate - visibility (<code>JNIEXPORT</code>). Note that prior to Ice Cream - Sandwich, the JNIEXPORT macro was incorrect, so using a new GCC with - an old <code>jni.h</code> won't work. - You can use <code>arm-eabi-nm</code> - to see the symbols as they appear in the library; if they look - mangled (something like <code>_Z15Java_Foo_myfuncP7_JNIEnvP7_jclass</code> - rather than <code>Java_Foo_myfunc</code>), or if the symbol type is - a lowercase 't' rather than an uppercase 'T', then you need to - adjust the declaration. - <li>For explicit registration, minor errors when entering the - method signature. Make sure that what you're passing to the - registration call matches the signature in the log file. - Remember that 'B' is <code>byte</code> and 'Z' is <code>boolean</code>. - Class name components in signatures start with 'L', end with ';', - use '/' to separate package/class names, and use '$' to separate - inner-class names (<code>Ljava/util/Map$Entry;</code>, say). - </ul> -</ul> - -<p>Using <code>javah</code> to automatically generate JNI headers may help -avoid some problems. - - -<a name="faq_FindClass" id="faq_FindClass"></a> -<h2>FAQ: Why didn't <code>FindClass</code> find my class?</h2> - -<p>Make sure that the class name string has the correct format. JNI class -names start with the package name and are separated with slashes, -such as <code>java/lang/String</code>. If you're looking up an array class, -you need to start with the appropriate number of square brackets and -must also wrap the class with 'L' and ';', so a one-dimensional array of -<code>String</code> would be <code>[Ljava/lang/String;</code>.</p> - -<p>If the class name looks right, you could be running into a class loader -issue. <code>FindClass</code> wants to start the class search in the -class loader associated with your code. It examines the call stack, -which will look something like: -<pre> Foo.myfunc(Native Method) - Foo.main(Foo.java:10) - dalvik.system.NativeStart.main(Native Method)</pre> - -<p>The topmost method is <code>Foo.myfunc</code>. <code>FindClass</code> -finds the <code>ClassLoader</code> object associated with the <code>Foo</code> -class and uses that.</p> - -<p>This usually does what you want. You can get into trouble if you -create a thread yourself (perhaps by calling <code>pthread_create</code> -and then attaching it with <code>AttachCurrentThread</code>). -Now the stack trace looks like this:</p> -<pre> dalvik.system.NativeStart.run(Native Method)</pre> - -<p>The topmost method is <code>NativeStart.run</code>, which isn't part of -your application. If you call <code>FindClass</code> from this thread, the -JavaVM will start in the "system" class loader instead of the one associated -with your application, so attempts to find app-specific classes will fail.</p> - -<p>There are a few ways to work around this:</p> -<ul> - <li>Do your <code>FindClass</code> lookups once, in - <code>JNI_OnLoad</code>, and cache the class references for later - use. Any <code>FindClass</code> calls made as part of executing - <code>JNI_OnLoad</code> will use the class loader associated with - the function that called <code>System.loadLibrary</code> (this is a - special rule, provided to make library initialization more convenient). - If your app code is loading the library, <code>FindClass</code> - will use the correct class loader. - <li>Pass an instance of the class into the functions that need - it, by declaring your native method to take a Class argument and - then passing <code>Foo.class</code> in. - <li>Cache a reference to the <code>ClassLoader</code> object somewhere - handy, and issue <code>loadClass</code> calls directly. This requires - some effort. -</ul> - - -<a name="faq_sharing" id="faq_sharing"></a> -<h2>FAQ: How do I share raw data with native code?</h2> - -<p>You may find yourself in a situation where you need to access a large -buffer of raw data from both managed and native code. Common examples -include manipulation of bitmaps or sound samples. There are two -basic approaches.</p> - -<p>You can store the data in a <code>byte[]</code>. This allows very fast -access from managed code. On the native side, however, you're -not guaranteed to be able to access the data without having to copy it. In -some implementations, <code>GetByteArrayElements</code> and -<code>GetPrimitiveArrayCritical</code> will return actual pointers to the -raw data in the managed heap, but in others it will allocate a buffer -on the native heap and copy the data over.</p> - -<p>The alternative is to store the data in a direct byte buffer. These -can be created with <code>java.nio.ByteBuffer.allocateDirect</code>, or -the JNI <code>NewDirectByteBuffer</code> function. Unlike regular -byte buffers, the storage is not allocated on the managed heap, and can -always be accessed directly from native code (get the address -with <code>GetDirectBufferAddress</code>). Depending on how direct -byte buffer access is implemented, accessing the data from managed code -can be very slow.</p> - -<p>The choice of which to use depends on two factors:</p> -<ol> - <li>Will most of the data accesses happen from code written in Java - or in C/C++? - <li>If the data is eventually being passed to a system API, what form - must it be in? (For example, if the data is eventually passed to a - function that takes a byte[], doing processing in a direct - <code>ByteBuffer</code> might be unwise.) -</ol> - -<p>If there's no clear winner, use a direct byte buffer. Support for them -is built directly into JNI, and performance should improve in future releases.</p> diff --git a/docs/html/guide/practices/performance.jd b/docs/html/guide/practices/performance.jd deleted file mode 100644 index 3e2714c..0000000 --- a/docs/html/guide/practices/performance.jd +++ /dev/null @@ -1,413 +0,0 @@ -page.title=Designing for Performance -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> - <li><a href="#intro">Introduction</a></li> - <li><a href="#optimize_judiciously">Optimize Judiciously</a></li> - <li><a href="#object_creation">Avoid Creating Unnecessary Objects</a></li> - <li><a href="#myths">Performance Myths</a></li> - <li><a href="#prefer_static">Prefer Static Over Virtual</a></li> - <li><a href="#internal_get_set">Avoid Internal Getters/Setters</a></li> - <li><a href="#use_final">Use Static Final For Constants</a></li> - <li><a href="#foreach">Use Enhanced For Loop Syntax</a></li> - <li><a href="#package_inner">Consider Package Instead of Private Access with Inner Classes</a></li> - <li><a href="#avoidfloat">Use Floating-Point Judiciously</a> </li> - <li><a href="#library">Know And Use The Libraries</a></li> - <li><a href="#native_methods">Use Native Methods Judiciously</a></li> - <li><a href="#closing_notes">Closing Notes</a></li> -</ol> - -</div> -</div> - -<p>An Android application will run on a mobile device with limited computing -power and storage, and constrained battery life. Because of -this, it should be <em>efficient</em>. Battery life is one reason you might -want to optimize your app even if it already seems to run "fast enough". -Battery life is important to users, and Android's battery usage breakdown -means users will know if your app is responsible draining their battery.</p> - -<p>Note that although this document primarily covers micro-optimizations, -these will almost never make or break your software. Choosing the right -algorithms and data structures should always be your priority, but is -outside the scope of this document.</p> - -<a name="intro" id="intro"></a> -<h2>Introduction</h2> - -<p>There are two basic rules for writing efficient code:</p> -<ul> - <li>Don't do work that you don't need to do.</li> - <li>Don't allocate memory if you can avoid it.</li> -</ul> - -<h2 id="optimize_judiciously">Optimize Judiciously</h2> - -<p>This document is about Android-specific micro-optimization, so it assumes -that you've already used profiling to work out exactly what code needs to be -optimized, and that you already have a way to measure the effect (good or bad) -of any changes you make. You only have so much engineering time to invest, so -it's important to know you're spending it wisely. - -<p>(See <a href="#closing_notes">Closing Notes</a> for more on profiling and -writing effective benchmarks.) - -<p>This document also assumes that you made the best decisions about data -structures and algorithms, and that you've also considered the future -performance consequences of your API decisions. Using the right data -structures and algorithms will make more difference than any of the advice -here, and considering the performance consequences of your API decisions will -make it easier to switch to better implementations later (this is more -important for library code than for application code). - -<p>(If you need that kind of advice, see Josh Bloch's <em>Effective Java</em>, -item 47.)</p> - -<p>One of the trickiest problems you'll face when micro-optimizing an Android -app is that your app is pretty much guaranteed to be running on multiple -hardware platforms. Different versions of the VM running on different -processors running at different speeds. It's not even generally the case -that you can simply say "device X is a factor F faster/slower than device Y", -and scale your results from one device to others. In particular, measurement -on the emulator tells you very little about performance on any device. There -are also huge differences between devices with and without a JIT: the "best" -code for a device with a JIT is not always the best code for a device -without.</p> - -<p>If you want to know how your app performs on a given device, you need to -test on that device.</p> - -<a name="object_creation"></a> -<h2>Avoid Creating Unnecessary Objects</h2> - -<p>Object creation is never free. A generational GC with per-thread allocation -pools for temporary objects can make allocation cheaper, but allocating memory -is always more expensive than not allocating memory.</p> - -<p>If you allocate objects in a user interface loop, you will force a periodic -garbage collection, creating little "hiccups" in the user experience. The -concurrent collector introduced in Gingerbread helps, but unnecessary work -should always be avoided.</p> - -<p>Thus, you should avoid creating object instances you don't need to. Some -examples of things that can help:</p> - -<ul> - <li>If you have a method returning a string, and you know that its result - will always be appended to a StringBuffer anyway, change your signature - and implementation so that the function does the append directly, - instead of creating a short-lived temporary object.</li> - <li>When extracting strings from a set of input data, try - to return a substring of the original data, instead of creating a copy. - You will create a new String object, but it will share the char[] - with the data. (The trade-off being that if you're only using a small - part of the original input, you'll be keeping it all around in memory - anyway if you go this route.)</li> -</ul> - -<p>A somewhat more radical idea is to slice up multidimensional arrays into -parallel single one-dimension arrays:</p> - -<ul> - <li>An array of ints is a much better than an array of Integers, - but this also generalizes to the fact that two parallel arrays of ints - are also a <strong>lot</strong> more efficient than an array of (int,int) - objects. The same goes for any combination of primitive types.</li> - <li>If you need to implement a container that stores tuples of (Foo,Bar) - objects, try to remember that two parallel Foo[] and Bar[] arrays are - generally much better than a single array of custom (Foo,Bar) objects. - (The exception to this, of course, is when you're designing an API for - other code to access; in those cases, it's usually better to trade - good API design for a small hit in speed. But in your own internal - code, you should try and be as efficient as possible.)</li> -</ul> - -<p>Generally speaking, avoid creating short-term temporary objects if you -can. Fewer objects created mean less-frequent garbage collection, which has -a direct impact on user experience.</p> - -<a name="avoid_enums" id="avoid_enums"></a> -<a name="myths" id="myths"></a> -<h2>Performance Myths</h2> - -<p>Previous versions of this document made various misleading claims. We -address some of them here.</p> - -<p>On devices without a JIT, it is true that invoking methods via a -variable with an exact type rather than an interface is slightly more -efficient. (So, for example, it was cheaper to invoke methods on a -<code>HashMap map</code> than a <code>Map map</code>, even though in both -cases the map was a <code>HashMap</code>.) It was not the case that this -was 2x slower; the actual difference was more like 6% slower. Furthermore, -the JIT makes the two effectively indistinguishable.</p> - -<p>On devices without a JIT, caching field accesses is about 20% faster than -repeatedly accesssing the field. With a JIT, field access costs about the same -as local access, so this isn't a worthwhile optimization unless you feel it -makes your code easier to read. (This is true of final, static, and static -final fields too.) - -<a name="prefer_static" id="prefer_static"></a> -<h2>Prefer Static Over Virtual</h2> - -<p>If you don't need to access an object's fields, make your method static. -Invocations will be about 15%-20% faster. -It's also good practice, because you can tell from the method -signature that calling the method can't alter the object's state.</p> - -<a name="internal_get_set" id="internal_get_set"></a> -<h2>Avoid Internal Getters/Setters</h2> - -<p>In native languages like C++ it's common practice to use getters (e.g. -<code>i = getCount()</code>) instead of accessing the field directly (<code>i -= mCount</code>). This is an excellent habit for C++, because the compiler can -usually inline the access, and if you need to restrict or debug field access -you can add the code at any time.</p> - -<p>On Android, this can be a bad idea. Virtual method calls can be more -expensive than instance field lookups. It's reasonable to follow -common object-oriented programming practices and have getters and setters -in the public interface, but within a class you might want to access -fields directly.</p> - -<p>Without a JIT, direct field access is about 3x faster than invoking a -trivial getter (one that simply returns the value of a field, without -any dereferencing or array indexing). With the Froyo JIT, direct field -access was about 7x faster than invoking a trivial getter. Since -Gingerbread, though, the JIT inlines trivial getter methods, making -that particular optimization obsolete. Manual inlining guided by -profiling can still be a useful technique in general, though.</a> - -<p>Note that if you're using ProGuard, you can have the best -of both worlds even with non-trival accessors, because ProGuard can inline -for you.</p> - -<a name="use_final" id="use_final"></a> -<h2>Use Static Final For Constants</h2> - -<p>Consider the following declaration at the top of a class:</p> - -<pre>static int intVal = 42; -static String strVal = "Hello, world!";</pre> - -<p>The compiler generates a class initializer method, called -<code><clinit></code>, that is executed when the class is first used. -The method stores the value 42 into <code>intVal</code>, and extracts a -reference from the classfile string constant table for <code>strVal</code>. -When these values are referenced later on, they are accessed with field -lookups.</p> - -<p>We can improve matters with the "final" keyword:</p> - -<pre>static final int intVal = 42; -static final String strVal = "Hello, world!";</pre> - -<p>The class no longer requires a <code><clinit></code> method, -because the constants go into static field initializers in the dex file. -Code that refers to <code>intVal</code> will use -the integer value 42 directly, and accesses to <code>strVal</code> will -use a relatively inexpensive "string constant" instruction instead of a -field lookup. (Note that this optimization only applies to primitive types and -<code>String</code> constants, not arbitrary reference types. Still, it's good -practice to declare constants <code>static final</code> whenever possible.)</p> - -<a name="foreach" id="foreach"></a> -<h2>Use Enhanced For Loop Syntax</h2> - -<p>The enhanced for loop (also sometimes known as "for-each" loop) can be used -for collections that implement the Iterable interface and for arrays. -With collections, an iterator is allocated to make interface calls -to hasNext() and next(). With an ArrayList, a hand-written counted loop is -about 3x faster (with or without JIT), but for other collections the enhanced -for loop syntax will be exactly equivalent to explicit iterator usage.</p> - -<p>There are several alternatives for iterating through an array:</p> - -<pre> static class Foo { - int mSplat; - } - Foo[] mArray = ... - - public void zero() { - int sum = 0; - for (int i = 0; i < mArray.length; ++i) { - sum += mArray[i].mSplat; - } - } - - public void one() { - int sum = 0; - Foo[] localArray = mArray; - int len = localArray.length; - - for (int i = 0; i < len; ++i) { - sum += localArray[i].mSplat; - } - } - - public void two() { - int sum = 0; - for (Foo a : mArray) { - sum += a.mSplat; - } - } -</pre> - -<p><strong>zero()</strong> is slowest, because the JIT can't yet optimize away -the cost of getting the array length once for every iteration through the -loop.</p> - -<p><strong>one()</strong> is faster. It pulls everything out into local -variables, avoiding the lookups. Only the array length offers a performance -benefit.</p> - -<p><strong>two()</strong> is fastest for devices without a JIT, and -indistinguishable from <strong>one()</strong> for devices with a JIT. -It uses the enhanced for loop syntax introduced in version 1.5 of the Java -programming language.</p> - -<p>To summarize: use the enhanced for loop by default, but consider a -hand-written counted loop for performance-critical ArrayList iteration.</p> - -<p>(See also <em>Effective Java</em> item 46.)</p> - -<a name="package_inner" id="package_inner"></a> -<h2>Consider Package Instead of Private Access with Private Inner Classes</h2> - -<p>Consider the following class definition:</p> - -<pre>public class Foo { - private class Inner { - void stuff() { - Foo.this.doStuff(Foo.this.mValue); - } - } - - private int mValue; - - public void run() { - Inner in = new Inner(); - mValue = 27; - in.stuff(); - } - - private void doStuff(int value) { - System.out.println("Value is " + value); - } -}</pre> - -<p>The key things to note here are that we define a private inner class -(<code>Foo$Inner</code>) that directly accesses a private method and a private -instance field in the outer class. This is legal, and the code prints "Value is -27" as expected.</p> - -<p>The problem is that the VM considers direct access to <code>Foo</code>'s -private members from <code>Foo$Inner</code> to be illegal because -<code>Foo</code> and <code>Foo$Inner</code> are different classes, even though -the Java language allows an inner class to access an outer class' private -members. To bridge the gap, the compiler generates a couple of synthetic -methods:</p> - -<pre>/*package*/ static int Foo.access$100(Foo foo) { - return foo.mValue; -} -/*package*/ static void Foo.access$200(Foo foo, int value) { - foo.doStuff(value); -}</pre> - -<p>The inner class code calls these static methods whenever it needs to -access the <code>mValue</code> field or invoke the <code>doStuff</code> method -in the outer class. What this means is that the code above really boils down to -a case where you're accessing member fields through accessor methods. -Earlier we talked about how accessors are slower than direct field -accesses, so this is an example of a certain language idiom resulting in an -"invisible" performance hit.</p> - -<p>If you're using code like this in a performance hotspot, you can avoid the -overhead by declaring fields and methods accessed by inner classes to have -package access, rather than private access. Unfortunately this means the fields -can be accessed directly by other classes in the same package, so you shouldn't -use this in public API.</p> - -<a name="avoidfloat" id="avoidfloat"></a> -<h2>Use Floating-Point Judiciously</h2> - -<p>As a rule of thumb, floating-point is about 2x slower than integer on -Android devices. This is true on a FPU-less, JIT-less G1 and a Nexus One with -an FPU and the JIT. (Of course, absolute speed difference between those two -devices is about 10x for arithmetic operations.)</p> - -<p>In speed terms, there's no difference between <code>float</code> and -<code>double</code> on the more modern hardware. Space-wise, <code>double</code> -is 2x larger. As with desktop machines, assuming space isn't an issue, you -should prefer <code>double</code> to <code>float</code>.</p> - -<p>Also, even for integers, some chips have hardware multiply but lack -hardware divide. In such cases, integer division and modulus operations are -performed in software — something to think about if you're designing a -hash table or doing lots of math.</p> - -<a name="library" id="library"></a> -<h2>Know And Use The Libraries</h2> - -<p>In addition to all the usual reasons to prefer library code over rolling -your own, bear in mind that the system is at liberty to replace calls -to library methods with hand-coded assembler, which may be better than the -best code the JIT can produce for the equivalent Java. The typical example -here is <code>String.indexOf</code> and friends, which Dalvik replaces with -an inlined intrinsic. Similarly, the <code>System.arraycopy</code> method -is about 9x faster than a hand-coded loop on a Nexus One with the JIT.</p> - -<p>(See also <em>Effective Java</em> item 47.)</p> - -<a name="native_methods" id="native_methods"></a> -<h2>Use Native Methods Judiciously</h2> - -<p>Native code isn't necessarily more efficient than Java. For one thing, -there's a cost associated with the Java-native transition, and the JIT can't -optimize across these boundaries. If you're allocating native resources (memory -on the native heap, file descriptors, or whatever), it can be significantly -more difficult to arrange timely collection of these resources. You also -need to compile your code for each architecture you wish to run on (rather -than rely on it having a JIT). You may even have to compile multiple versions -for what you consider the same architecture: native code compiled for the ARM -processor in the G1 can't take full advantage of the ARM in the Nexus One, and -code compiled for the ARM in the Nexus One won't run on the ARM in the G1.</p> - -<p>Native code is primarily useful when you have an existing native codebase -that you want to port to Android, not for "speeding up" parts of a Java app.</p> - -<p>If you do need to use native code, you should read our -<a href="{@docRoot}guide/practices/jni.html">JNI Tips</a>.</p> - -<p>(See also <em>Effective Java</em> item 54.)</p> - -<a name="closing_notes" id="closing_notes"></a> -<h2>Closing Notes</h2> - -<p>One last thing: always measure. Before you start optimizing, make sure you -have a problem. Make sure you can accurately measure your existing performance, -or you won't be able to measure the benefit of the alternatives you try.</p> - -<p>Every claim made in this document is backed up by a benchmark. The source -to these benchmarks can be found in the <a href="http://code.google.com/p/dalvik/source/browse/#svn/trunk/benchmarks">code.google.com "dalvik" project</a>.</p> - -<p>The benchmarks are built with the -<a href="http://code.google.com/p/caliper/">Caliper</a> microbenchmarking -framework for Java. Microbenchmarks are hard to get right, so Caliper goes out -of its way to do the hard work for you, and even detect some cases where you're -not measuring what you think you're measuring (because, say, the VM has -managed to optimize all your code away). We highly recommend you use Caliper -to run your own microbenchmarks.</p> - -<p>You may also find -<a href="{@docRoot}tools/debugging/debugging-tracing.html">Traceview</a> useful -for profiling, but it's important to realize that it currently disables the JIT, -which may cause it to misattribute time to code that the JIT may be able to win -back. It's especially important after making changes suggested by Traceview -data to ensure that the resulting code actually runs faster when run without -Traceview. diff --git a/docs/html/guide/practices/responsiveness.jd b/docs/html/guide/practices/responsiveness.jd deleted file mode 100644 index a00e3aa..0000000 --- a/docs/html/guide/practices/responsiveness.jd +++ /dev/null @@ -1,140 +0,0 @@ -page.title=Designing for Responsiveness -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> - <li><a href="#anr">What Triggers ANR?</a></li> - <li><a href="#avoiding">How to Avoid ANR</a></li> - <li><a href="#reinforcing">Reinforcing Responsiveness</a></li> -</ol> - -</div> -</div> - -<div class="figure"> -<img src="{@docRoot}images/anr.png" alt="Screenshot of ANR dialog box" width="240" height="320"/> -<p><strong>Figure 1.</strong> An ANR dialog displayed to the user.</p> -</div> - -<p>It's possible to write code that wins every performance test in the world, -but still sends users in a fiery rage when they try to use the application. -These are the applications that aren't <em>responsive</em> enough — the -ones that feel sluggish, hang or freeze for significant periods, or take too -long to process input. </p> - -<p>In Android, the system guards against applications that are insufficiently -responsive for a period of time by displaying a dialog to the user, called the -Application Not Responding (ANR) dialog, shown at right in Figure 1. The user -can choose to let the application continue, but the user won't appreciate having -to act on this dialog every time he or she uses your application. It's critical -to design responsiveness into your application, so that the system never has -cause to display an ANR dialog to the user. </p> - -<p>Generally, the system displays an ANR if an application cannot respond to -user input. For example, if an application blocks on some I/O operation -(frequently a network access), then the main application thread won't be able to -process incoming user input events. After a time, the system concludes that the -application is frozen, and displays the ANR to give the user the option to kill -it. </p> - -<p>Similarly, if your application spends too much time building an elaborate in-memory -structure, or perhaps computing the next move in a game, the system will -conclude that your application has hung. It's always important to make -sure these computations are efficient using the techniques above, but even the -most efficient code still takes time to run.</p> - -<p>In both of these cases, the recommended approach is to create a child thread and do -most of your work there. This keeps the main thread (which drives the user -interface event loop) running and prevents the system from concluding that your code -has frozen. Since such threading usually is accomplished at the class -level, you can think of responsiveness as a <em>class</em> problem. (Compare -this with basic performance, which was described above as a <em>method</em>-level -concern.)</p> - -<p>This document describes how the Android system determines whether an -application is not responding and provides guidelines for ensuring that your -application stays responsive. </p> - -<h2 id="anr">What Triggers ANR?</h2> - -<p>In Android, application responsiveness is monitored by the Activity Manager -and Window Manager system services. Android will display the ANR dialog -for a particular application when it detects one of the following -conditions:</p> -<ul> - <li>No response to an input event (e.g. key press, screen touch) - within 5 seconds</li> - <li>A {@link android.content.BroadcastReceiver BroadcastReceiver} - hasn't finished executing within 10 seconds</li> -</ul> - -<h2 id="avoiding">How to Avoid ANR</h2> - -<p>Given the above definition for ANR, let's examine why this can occur in -Android applications and how best to structure your application to avoid ANR.</p> - -<p>Android applications normally run entirely on a single (i.e. main) thread. -This means that anything your application is doing in the main thread that -takes a long time to complete can trigger the ANR dialog because your -application is not giving itself a chance to handle the input event or Intent -broadcast.</p> - -<p>Therefore any method that runs in the main thread should do as little work -as possible. In particular, Activities should do as little as possible to set -up in key life-cycle methods such as <code>onCreate()</code> and -<code>onResume()</code>. Potentially long running operations such as network -or database operations, or computationally expensive calculations such as -resizing bitmaps should be done in a child thread (or in the case of databases -operations, via an asynchronous request). However, this does not mean that -your main thread should block while waiting for the child thread to -complete — nor should you call <code>Thread.wait()</code> or -<code>Thread.sleep()</code>. Instead of blocking while waiting for a child -thread to complete, your main thread should provide a {@link -android.os.Handler Handler} for child threads to post back to upon completion. -Designing your application in this way will allow your main thread to remain -responsive to input and thus avoid ANR dialogs caused by the 5 second input -event timeout. These same practices should be followed for any other threads -that display UI, as they are also subject to the same timeouts.</p> - -<p>You can use {@link android.os.StrictMode} to help find potentially -long running operations such as network or database operations that -you might accidentally be doing your main thread.</p> - -<p>The specific constraint on IntentReceiver execution time emphasizes what -they were meant to do: small, discrete amounts of work in the background such -as saving a setting or registering a Notification. So as with other methods -called in the main thread, applications should avoid potentially long-running -operations or calculations in BroadcastReceivers. But instead of doing intensive -tasks via child threads (as the life of a BroadcastReceiver is short), your -application should start a {@link android.app.Service Service} if a -potentially long running action needs to be taken in response to an Intent -broadcast. As a side note, you should also avoid starting an Activity from an -Intent Receiver, as it will spawn a new screen that will steal focus from -whatever application the user is currently has running. If your application -has something to show the user in response to an Intent broadcast, it should -do so using the {@link android.app.NotificationManager Notification -Manager}.</p> - -<h2 id="reinforcing">Reinforcing Responsiveness</h2> - -<p>Generally, 100 to 200ms is the threshold beyond which users will perceive -lag (or lack of "snappiness," if you will) in an application. As such, here -are some additional tips beyond what you should do to avoid ANR that will help -make your application seem responsive to users.</p> - -<ul> - <li>If your application is doing work in the background in response to - user input, show that progress is being made ({@link - android.widget.ProgressBar ProgressBar} and {@link - android.app.ProgressDialog ProgressDialog} are useful for this).</li> - <li>For games specifically, do calculations for moves in a child - thread.</li> - <li>If your application has a time-consuming initial setup phase, consider - showing a splash screen or rendering the main view as quickly as possible - and filling in the information asynchronously. In either case, you should - indicate somehow that progress is being made, lest the user perceive that - the application is frozen.</li> -</ul> diff --git a/docs/html/guide/practices/security.jd b/docs/html/guide/practices/security.jd deleted file mode 100644 index 36eeff8..0000000 --- a/docs/html/guide/practices/security.jd +++ /dev/null @@ -1,767 +0,0 @@ -page.title=Designing for Security -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> -<h2>In this document</h2> -<ol> -<li><a href="#Dalvik">Using Dalvik Code</a></li> -<li><a href="#Native">Using Native Code</a></li> -<li><a href="#Data">Storing Data</a></li> -<li><a href="#IPC">Using IPC</a></li> -<li><a href="#Permissions">Using Permissions</a></li> -<li><a href="#Networking">Using Networking</a></li> -<li><a href="#DynamicCode">Dynamically Loading Code</a></li> -<li><a href="#Input">Performing Input Validation</a></li> -<li><a href="#UserData">Handling User Data</a></li> -<li><a href="#Crypto">Using Cryptography</a></li> -</ol> -<h2>See also</h2> -<ol> -<li><a href="http://source.android.com/tech/security/index.html">Android -Security Overview</a></li> -<li><a href="{@docRoot}guide/topics/security/permissions.html">Permissions</a></li> -</ol> -</div></div> -<p>Android was designed so that most developers will be able to build -applications using the default settings and not be confronted with difficult -decisions about security. Android also has a number of security features built -into the operating system that significantly reduce the frequency and impact of -application security issues.</p> - -<p>Some of the security features that help developers build secure applications -include: -<ul> -<li>The Android Application Sandbox that isolates data and code execution on a -per-application basis.</li> -<li>Android application framework with robust implementations of common -security functionality such as cryptography, permissions, and secure IPC.</li> -<li>Technologies like ASLR, NX, ProPolice, safe_iop, OpenBSD dlmalloc, OpenBSD -calloc, and Linux mmap_min_addr to mitigate risks associated with common memory -management errors</li> -<li>An encrypted filesystem that can be enabled to protect data on lost or -stolen devices.</li> -</ul></p> - -<p>Nevertheless, it is important for developers to be familiar with Android -security best practices to make sure they take advantage of these capabilities -and to reduce the likelihood of inadvertently introducing security issues that -can affect their applications.</p> - -<p>This document is organized around common APIs and development techniques -that can have security implications for your application and its users. As -these best practices are constantly evolving, we recommend you check back -occasionally throughout your application development process.</p> - -<a name="Dalvik"></a> -<h2>Using Dalvik Code</h2> -<p>Writing secure code that runs in virtual machines is a well-studied topic -and many of the issues are not specific to Android. Rather than attempting to -rehash these topics, we’d recommend that you familiarize yourself with the -existing literature. Two of the more popular resources are: -<ul> -<li><a href="http://www.securingjava.com/toc.html"> -http://www.securingjava.com/toc.html</a></li> -<li><a -href="https://www.owasp.org/index.php/Java_Security_Resources"> -https://www.owasp.org/index.php/Java_Security_Resources</a></li> -</ul></p> - -<p>This document is focused on the areas which are Android specific and/or -different from other environments. For developers experienced with VM -programming in other environments, there are two broad issues that may be -different about writing apps for Android: -<ul> -<li>Some virtual machines, such as the JVM or .net runtime, act as a security -boundary, isolating code from the underlying operating system capabilities. On -Android, the Dalvik VM is not a security boundary -- the application sandbox is -implemented at the OS level, so Dalvik can interoperate with native code in the -same application without any security constraints.</li> -<li>Given the limited storage on mobile devices, it’s common for developers -to want to build modular applications and use dynamic class loading. When -doing this consider both the source where you retrieve your application logic -and where you store it locally. Do not use dynamic class loading from sources -that are not verified, such as unsecured network sources or external storage, -since that code can be modified to include malicious behavior.</li> -</ul></p> - -<a name="Native"></a> -<h2>Using Native Code</h2> - -<p>In general, we encourage developers to use the Android SDK for most -application development, rather than using native code. Applications built -with native code are more complex, less portable, and more like to include -common memory corruption errors such as buffer overflows.</p> - -<p>Android is built using the Linux kernel and being familiar with Linux -development security best practices is especially useful if you are going to -use native code. This document is too short to discuss all of those best -practices, but one of the most popular resources is “Secure Programming for -Linux and Unix HOWTO”, available at <a -href="http://www.dwheeler.com/secure-programs"> -http://www.dwheeler.com/secure-programs</a>.</p> - -<p>An important difference between Android and most Linux environments is the -Application Sandbox. On Android, all applications run in the Application -Sandbox, including those written with native code. At the most basic level, a -good way to think about it for developers familiar with Linux is to know that -every application is given a unique UID with very limited permissions. This is -discussed in more detail in the <a -href="http://source.android.com/tech/security/index.html">Android Security -Overview</a> and you should be familiar with application permissions even if -you are using native code.</p> - -<a name="Data"></a> -<h2>Storing Data</h2> - -<h3>Using internal files</h3> - -<p>By default, files created on <a -href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal -storage</a> are only accessible to the application that created the file. This -protection is implemented by Android and is sufficient for most -applications.</p> - -<p>Use of <a -href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_WRITEABLE"> -world writable</a> or <a -href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_READABLE">world -readable</a> files for IPC is discouraged because it does not provide -the ability to limit data access to particular applications, nor does it -provide any control on data format. As an alternative, you might consider using -a ContentProvider which provides read and write permissions, and can make -dynamic permission grants on a case-by-case basis.</p> - -<p>To provide additional protection for sensitive data, some applications -choose to encrypt local files using a key that is not accessible to the -application. (For example, a key can be placed in a {@link java.security.KeyStore} -and protected with a user password that is not stored on the device). While this -does not protect data from a root compromise that can monitor the user -inputting the password, it can provide protection for a lost device without <a -href="http://source.android.com/tech/encryption/index.html">file system -encryption</a>.</p> - -<h3>Using external storage</h3> - -<p>Files created on <a -href="{@docRoot}guide/topics/data/data-storage.html#filesExternal">external -storage</a>, such as SD Cards, are globally readable and writable. Since -external storage can be removed by the user and also modified by any -application, applications should not store sensitive information using -external storage.</p> - -<p>As with data from any untrusted source, applications should perform input -validation when handling data from external storage (see Input Validation -section). We strongly recommend that applications not store executables or -class files on external storage prior to dynamic loading. If an application -does retrieve executable files from external storage they should be signed and -cryptographically verified prior to dynamic loading.</p> - -<h3>Using content providers</h3> - -<p>ContentProviders provide a structured storage mechanism that can be limited -to your own application, or exported to allow access by other applications. By -default, a <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code> is -<a href="{@docRoot}guide/topics/manifest/provider-element.html#exported">exported -</a> for use by other applications. If you do not intend to provide other -applications with access to your<code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code>, mark them as <code><a -href="{@docRoot}guide/topics/manifest/provider-element.html#exported"> -android:exported=false</a></code> in the application manifest.</p> - -<p>When creating a <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html">ContentProvider -</a></code> that will be exported for use by other applications, you can specify -a single -<a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission -</a> for reading and writing, or distinct permissions for reading and writing -within the manifest. We recommend that you limit your permissions to those -required to accomplish the task at hand. Keep in mind that it’s usually -easier to add permissions later to expose new functionality than it is to take -them away and break existing users.</p> - -<p>If you are using a <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code> for sharing data between applications built by the -same developer, it is preferable to use -<a href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature -level permissions</a>. Signature permissions do not require user confirmation, -so they provide a better user experience and more controlled access to the -<code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code>.</p> - -<p>ContentProviders can also provide more granular access by declaring the <a -href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> -grantUriPermissions</a> element and using the <code><a -href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_READ_URI_PERMISSION">FLAG_GRANT_READ_URI_PERMISSION</a></code> -and <code><a -href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_WRITE_URI_PERMISSION">FLAG_GRANT_WRITE_URI_PERMISSION</a></code> -flags in the Intent object -that activates the component. The scope of these permissions can be further -limited by the <code><a -href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> -grant-uri-permission element</a></code>.</p> - -<p>When accessing a <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code>, use parameterized query methods such as <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html#query(android.net.Uri,%20java.lang.String[],%20java.lang.String,%20java.lang.String[],%20java.lang.String)">query()</a></code>, <code><a -href="{@docRoot}reference/android/content/ContentProvider.html#update(android.net.Uri,%20android.content.ContentValues,%20java.lang.String,%20java.lang.String[])">update()</a></code>, and <code><a -href="{@docRoot}reference/android/content/ContentProvider.html#delete(android.net.Uri,%20java.lang.String,%20java.lang.String[])">delete()</a></code> to avoid -potential <a href="http://en.wikipedia.org/wiki/SQL_injection">SQL -Injection</a> from untrusted data. Note that using parameterized methods is not -sufficient if the <code>selection</code> is built by concatenating user data -prior to submitting it to the method.</p> - -<p>Do not have a false sense of security about the write permission. Consider -that the write permission allows SQL statements which make it possible for some -data to be confirmed using creative <code>WHERE</code> clauses and parsing the -results. For example, an attacker might probe for presence of a specific phone -number in a call-log by modifying a row only if that phone number already -exists. If the content provider data has predictable structure, the write -permission may be equivalent to providing both reading and writing.</p> - -<a name="IPC"></a> -<h2>Using Interprocess Communication (IPC)</h2> - -<p>Some Android applications attempt to implement IPC using traditional Linux -techniques such as network sockets and shared files. We strongly encourage the -use of Android system functionality for IPC such as Intents, Binders, Services, -and Receivers. The Android IPC mechanisms allow you to verify the identity of -the application connecting to your IPC and set security policy for each IPC -mechanism.</p> - -<p>Many of the security elements are shared across IPC mechanisms. <a -href="{@docRoot}reference/android/content/BroadcastReceiver.html"> -Broadcast Receivers</a>, <a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity"> -Activities</a>, and <a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService"> -Services</a> are all declared in the application manifest. If your IPC mechanism is -not intended for use by other applications, set the <a -href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a> -property to false. This is useful for applications that consist of multiple processes -within the same UID, or if you decide late in development that you do not -actually want to expose functionality as IPC but you don’t want to rewrite -the code.</p> - -<p>If your IPC is intended to be accessible to other applications, you can -apply a security policy by using the <a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestPermission"> -Permission</a> tag. If IPC is between applications built by the same developer, -it is preferable to use <a -href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature -level permissions</a>. Signature permissions do not require user confirmation, -so they provide a better user experience and more controlled access to the IPC -mechanism.</p> - -<p>One area that can introduce confusion is the use of intent filters. Note -that Intent filters should not be considered a security feature -- components -can be invoked directly and may not have data that would conform to the intent -filter. You should perform input validation within your intent receiver to -confirm that it is properly formatted for the invoked receiver, service, or -activity.</p> - -<h3>Using intents</h3> - -<p>Intents are the preferred mechanism for asynchronous IPC in Android. -Depending on your application requirements, you might use <code><a -href="{@docRoot}reference/android/content/Context.html#sendBroadcast(android.content.Intent)">sendBroadcast()</a></code>, -<code><a -href="{@docRoot}reference/android/content/Context.html#sendOrderedBroadcast(android.content.Intent,%20java.lang.String)">sendOrderedBroadcast()</a></code>, -or direct an intent to a specific application component.</p> - -<p>Note that ordered broadcasts can be “consumed” by a recipient, so they -may not be delivered to all applications. If you are sending an Intent where -delivery to a specific receiver is required, the intent must be delivered -directly to the receiver.</p> - -<p>Senders of an intent can verify that the recipient has a permission -specifying a non-Null Permission upon sending. Only applications with that -Permission will receive the intent. If data within a broadcast intent may be -sensitive, you should consider applying a permission to make sure that -malicious applications cannot register to receive those messages without -appropriate permissions. In those circumstances, you may also consider -invoking the receiver directly, rather than raising a broadcast.</p> - -<h3>Using binder and AIDL interfaces</h3> - -<p><a href="{@docRoot}reference/android/os/Binder.html">Binders</a> are the -preferred mechanism for RPC-style IPC in Android. They provide a well-defined -interface that enables mutual authentication of the endpoints, if required.</p> - -<p>We strongly encourage designing interfaces in a manner that does not require -interface specific permission checks. Binders are not declared within the -application manifest, and therefore you cannot apply declarative permissions -directly to a Binder. Binders generally inherit permissions declared in the -application manifest for the Service or Activity within which they are -implemented. If you are creating an interface that requires authentication -and/or access controls on a specific binder interface, those controls must be -explicitly added as code in the interface.</p> - -<p>If providing an interface that does require access controls, use <code><a -href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> -to verify whether the -caller of the Binder has a required permission. This is especially important -before accessing a Service on behalf of the caller, as the identify of your -application is passed to other interfaces. If invoking an interface provided -by a Service, the <code><a -href="{@docRoot}reference/android/content/Context.html#bindService(android.content.Intent,%20android.content.ServiceConnection,%20int)">bindService()</a></code> - invocation may fail if you do not have permission to access the given Service. - If calling an interface provided locally by your own application, it may be -useful to use the <code><a -href="{@docRoot}reference/android/os/Binder.html#clearCallingIdentity()"> -clearCallingIdentity()</a></code> to satisfy internal security checks.</p> - -<h3>Using broadcast receivers</h3> - -<p>Broadcast receivers are used to handle asynchronous requests initiated via -an intent.</p> - -<p>By default, receivers are exported and can be invoked by any other -application. If your <code><a -href="{@docRoot}reference/android/content/BroadcastReceiver.html"> -BroadcastReceivers</a></code> is intended for use by other applications, you -may want to apply security permissions to receivers using the <code><a -href="{@docRoot}guide/topics/manifest/receiver-element.html"> -<receiver></a></code> element within the application manifest. This will -prevent applications without appropriate permissions from sending an intent to -the <code><a -href="{@docRoot}reference/android/content/BroadcastReceiver.html"> -BroadcastReceivers</a></code>.</p> - -<h3>Using Services</h3> - -<p>Services are often used to supply functionality for other applications to -use. Each service class must have a corresponding <service> declaration in its -package's AndroidManifest.xml.</p> - -<p>By default, Services are exported and can be invoked by any other -application. Services can be protected using the <a -href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">{@code android:permission}</a> -attribute -within the manifest’s <code><a -href="{@docRoot}guide/topics/manifest/service-element.html"> -<service></a></code> tag. By doing so, other applications will need to declare -a corresponding <code><a -href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a> -</code> element in their own manifest to be -able to start, stop, or bind to the service.</p> - -<p>A Service can protect individual IPC calls into it with permissions, by -calling <code><a -href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> -before executing -the implementation of that call. We generally recommend using the -declarative permissions in the manifest, since those are less prone to -oversight.</p> - -<h3>Using Activities</h3> - -<p>Activities are most often used for providing the core user-facing -functionality of an application. By default, Activities are exported and -invokable by other applications only if they have an intent filter or binder -declared. In general, we recommend that you specifically declare a Receiver or -Service to handle IPC, since this modular approach reduces the risk of exposing -functionality that is not intended for use by other applications.</p> - -<p>If you do expose an Activity for purposes of IPC, the <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">android:permission</a></code> -attribute in the <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html"> -<activity></a></code> declaration in the application manifest can be used to -restrict access to only those applications which have the stated -permissions.</p> - -<a name="Permissions"></a> -<h2>Using Permissions</h2> - -<h3>Requesting Permissions</h3> - -<p>We recommend minimizing the number of permissions requested by an -application. Not having access to sensitive permissions reduces the risk of -inadvertently misusing those permissions, can improve user adoption, and makes -applications less attractive targets for attackers.</p> - -<p>If it is possible to design your application in a way that does not require -a permission, that is preferable. For example, rather than requesting access -to device information to create an identifier, create a <a -href="{@docRoot}reference/java/util/UUID.html">GUID</a> for your application. -(This specific example is also discussed in Handling User Data) Or, rather than -using external storage, store data in your application directory.</p> - -<p>If a permission is not required, do not request it. This sounds simple, but -there has been quite a bit of research into the frequency of over-requesting -permissions. If you’re interested in the subject you might start with this -research paper published by U.C. Berkeley: <a -href="http://www.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-48.pdf"> -http://www.eecs.berkeley.edu/Pubs/TechRpts/2011/EECS-2011-48.pdf</a></p> - -<p>In addition to requesting permissions, your application can use <a -href="{@docRoot}guide/topics/manifest/permission-element.html">permissions</a> -to protect IPC that is security sensitive and will be exposed to other -applications -- such as a <code><a -href="{@docRoot}reference/android/content/ContentProvider.html"> -ContentProvider</a></code>. In general, we recommend using access controls -other than user confirmed permissions where possible since permissions can -be confusing for users. For example, consider using the <a -href="{@docRoot}guide/topics/manifest/permission-element.html#plevel">signature -protection level</a> on permissions for IPC communication between applications -provided by a single developer.</p> - -<p>Do not cause permission re-delegation. This occurs when an app exposes data -over IPC that is only available because it has a specific permission, but does -not require that permission of any clients of it’s IPC interface. More -details on the potential impacts, and frequency of this type of problem is -provided in this research paper published at USENIX: <a -href="http://www.cs.berkeley.edu/~afelt/felt_usenixsec2011.pdf">http://www.cs.be -rkeley.edu/~afelt/felt_usenixsec2011.pdf</a></p> - -<h3>Creating Permissions</h3> - -<p>Generally, you should strive to create as few permissions as possible while -satisfying your security requirements. Creating a new permission is relatively -uncommon for most applications, since <a -href="{@docRoot}reference/android/Manifest.permission.html">system-defined -permissions</a> cover many situations. Where appropriate, -perform access checks using existing permissions.</p> - -<p>If you must create a new permission, consider whether you can accomplish -your task with a Signature permission. Signature permissions are transparent -to the user and only allow access by applications signed by the same developer -as application performing the permission check. If you create a Dangerous -permission, then the user needs to decide whether to install the application. -This can be confusing for other developers, as well as for users.</p> - -<p>If you create a Dangerous permission, there are a number of complexities -that you need to consider. -<ul> -<li>The permission must have a string that concisely expresses to a user the -security decision they will be required to make.</li> -<li>The permission string must be localized to many different languages.</li> -<li>Uses may choose not to install an application because a permission is -confusing or perceived as risky.</li> -<li>Applications may request the permission when the creator of the permission -has not been installed.</li> -</ul></p> - -<p>Each of these poses a significant non-technical challenge for an application -developer, which is why we discourage the use of Dangerous permission.</p> - -<a name="Networking"></a> -<h2>Using Networking</h2> - -<h3>Using IP Networking</h3> - -<p>Networking on Android is not significantly different from Linux -environments. The key consideration is making sure that appropriate protocols -are used for sensitive data, such as <a -href="{@docRoot}reference/javax/net/ssl/HttpsURLConnection.html">HTTPS</a> for -web traffic. We prefer use of HTTPS over HTTP anywhere that HTTPS is -supported on the server, since mobile devices frequently connect on networks -that are not secured, such as public WiFi hotspots.</p> - -<p>Authenticated, encrypted socket-level communication can be easily -implemented using the <code><a -href="{@docRoot}reference/javax/net/ssl/SSLSocket.html">SSLSocket</a></code> -class. Given the frequency with which Android devices connect to unsecured -wireless networks using WiFi, the use of secure networking is strongly -encouraged for all applications.</p> - -<p>We have seen some applications use <a -href="http://en.wikipedia.org/wiki/Localhost">localhost</a> network ports for -handling sensitive IPC. We discourage this approach since these interfaces are -accessible by other applications on the device. Instead, use an Android IPC -mechanism where authentication is possible such as a Service and Binder. (Even -worse than using loopback is to bind to INADDR_ANY since then your application -may receive requests from anywhere. We’ve seen that, too.)</p> - -<p>Also, one common issue that warrants repeating is to make sure that you do -not trust data downloaded from HTTP or other insecure protocols. This includes -validation of input in <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> and -any responses to intents issued against HTTP.</p> - -<h3>Using Telephony Networking</h3> - -<p>SMS is the telephony protocol most frequently used by Android developers. -Developers should keep in mind that this protocol was primarily designed for -user-to-user communication and is not well-suited for some application -purposes. Due to the limitations of SMS, we strongly recommend the use of <a -href="http://code.google.com/android/c2dm/">C2DM</a> and IP networking for -sending data messages to devices.</p> - -<p>Many developers do not realize that SMS is not encrypted or strongly -authenticated on the network or on the device. In particular, any SMS receiver -should expect that a malicious user may have sent the SMS to your application --- do not rely on unauthenticated SMS data to perform sensitive commands. -Also, you should be aware that SMS may be subject to spoofing and/or -interception on the network. On the Android-powered device itself, SMS -messages are transmitted as Broadcast intents, so they may be read or captured -by other applications that have the READ_SMS permission.</p> - -<a name="DynamicCode"></a> -<h2>Dynamically Loading Code</h2> - -<p>We strongly discourage loading code from outside of the application APK. -Doing so significantly increases the likelihood of application compromise due -to code injection or code tampering. It also adds complexity around version -management and application testing. Finally, it can make it impossible to -verify the behavior of an application, so it may be prohibited in some -environments.</p> - -<p>If your application does dynamically load code, the most important thing to -keep in mind about dynamically loaded code is that it runs with the same -security permissions as the application APK. The user made a decision to -install your application based on your identity, and they are expecting that -you provide any code run within the application, including code that is -dynamically loaded.</p> - -<p>The major security risk associated with dynamically loading code is that the -code needs to come from a verifiable source. If the modules are included -directly within your APK, then they cannot be modified by other applications. -This is true whether the code is a native library or a class being loaded using -<a href="{@docRoot}reference/dalvik/system/DexClassLoader.html"> -<code>DexClassLoader</code></a>. We have seen many instances of applications -attempting to load code from insecure locations, such as downloaded from the -network over unencrypted protocols or from world writable locations such as -external storage. These locations could allow someone on the network to modify -the content in transit, or another application on a users device to modify the -content, respectively.</p> - - -<h3>Using WebView</h3> - -<p>Since WebView consumes web content that can include HTML and JavaScript, -improper use can introduce common web security issues such as <a -href="http://en.wikipedia.org/wiki/Cross_site_scripting">cross-site-scripting</a -> (JavaScript injection). Android includes a number of mechanisms to reduce -the scope of these potential issues by limiting the capability of WebView to -the minimum functionality required by your application.</p> - -<p>If your application does not directly use JavaScript within a <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, do -not call -<a href="{@docRoot}reference/android/webkit/WebSettings.html#setJavaScriptEnabled(boolean)"> -<code>setJavaScriptEnabled()</code></a>. We have seen this method invoked -in sample code that might be repurposed in production application -- so -remove it if necessary. By default, <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> does -not execute JavaScript so cross-site-scripting is not possible.</p> - -<p>Use <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> with -particular care because it allows JavaScript to invoke operations that are -normally reserved for Android applications. Only expose <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to -sources from which all input is trustworthy. If untrusted input is allowed, -untrusted JavaScript may be able to invoke Android methods. In general, we -recommend only exposing <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to -JavaScript that is contained within your application APK.</p> - -<p>Do not trust information downloaded over HTTP, use HTTPS instead. Even if -you are connecting only to a single website that you trust or control, HTTP is -subject to <a -href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">MiTM</a> attacks -and interception of data. Sensitive capabilities using <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> should -not ever be exposed to unverified script downloaded over HTTP. Note that even -with the use of HTTPS, -<code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> -increases the attack surface of your application to include the server -infrastructure and all CAs trusted by the Android-powered device.</p> - -<p>If your application accesses sensitive data with a <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, you -may want to use the <code><a -href="{@docRoot}reference/android/webkit/WebView.html#clearCache(boolean)"> -clearCache()</a></code> method to delete any files stored locally. Server side -headers like no-cache can also be used to indicate that an application should -not cache particular content.</p> - -<a name="Input"></a> -<h2>Performing Input Validation</h2> - -<p>Insufficient input validation is one of the most common security problems -affecting applications, regardless of what platform they run on. Android does -have platform-level countermeasures that reduce the exposure of applications to -input validation issues, you should use those features where possible. Also -note that selection of type-safe languages tends to reduce the likelihood of -input validation issues. We strongly recommend building your applications with -the Android SDK.</p> - -<p>If you are using native code, then any data read from files, received over -the network, or received from an IPC has the potential to introduce a security -issue. The most common problems are <a -href="http://en.wikipedia.org/wiki/Buffer_overflow">buffer overflows</a>, <a -href="http://en.wikipedia.org/wiki/Double_free#Use_after_free">use after -free</a>, and <a -href="http://en.wikipedia.org/wiki/Off-by-one_error">off-by-one errors</a>. -Android provides a number of technologies like ASLR and DEP that reduce the -exploitability of these errors, but they do not solve the underlying problem. -These can be prevented by careful handling of pointers and managing of -buffers.</p> - -<p>Dynamic, string based languages such as JavaScript and SQL are also subject -to input validation problems due to escape characters and <a -href="http://en.wikipedia.org/wiki/Code_injection">script injection</a>.</p> - -<p>If you are using data within queries that are submitted to SQL Database or a -Content Provider, SQL Injection may be an issue. The best defense is to use -parameterized queries, as is discussed in the ContentProviders section. -Limiting permissions to read-only or write-only can also reduce the potential -for harm related to SQL Injection.</p> - -<p>If you are using <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, then -you must consider the possibility of XSS. If your application does not -directly use JavaScript within a <code><a -href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code>, do -not call setJavaScriptEnabled() and XSS is no longer possible. If you must -enable JavaScript then the WebView section provides other security best -practices.</p> - -<p>If you cannot use the security features above, we strongly recommend the use -of well-structured data formats and verifying that the data conforms to the -expected format. While blacklisting of characters or character-replacement can -be an effective strategy, these techniques are error-prone in practice and -should be avoided when possible.</p> - -<a name="UserData"></a> -<h2>Handling User Data</h2> - -<p>In general, the best approach is to minimize use of APIs that access -sensitive or personal user data. If you have access to data and can avoid -storing or transmitting the information, do not store or transmit the data. -Finally, consider if there is a way that your application logic can be -implemented using a hash or non-reversible form of the data. For example, your -application might use the hash of an an email address as a primary key, to -avoid transmitting or storing the email address. This reduces the chances of -inadvertently exposing data, and it also reduces the chance of attackers -attempting to exploit your application.</p> - -<p>If your application accesses personal information such as passwords or -usernames, keep in mind that some jurisdictions may require you to provide a -privacy policy explaining your use and storage of that data. So following the -security best practice of minimizing access to user data may also simplify -compliance.</p> - -<p>You should also consider whether your application might be inadvertently -exposing personal information to other parties such as third-party components -for advertising or third-party services used by your application. If you don't -know why a component or service requires a personal information, don’t -provide it. In general, reducing the access to personal information by your -application will reduce the potential for problems in this area.</p> - -<p>If access to sensitive data is required, evaluate whether that information -must be transmitted to a server, or whether the operation can be performed on -the client. Consider running any code using sensitive data on the client to -avoid transmitting user data.</p> - -<p>Also, make sure that you do not inadvertently expose user data to other -application on the device through overly permissive IPC, world writable files, -or network sockets. This is a special case of permission redelegation, -discussed in the Requesting Permissions section.</p> - -<p>If a GUID is required, create a large, unique number and store it. Do not -use phone identifiers such as the phone number or IMEI which may be associated -with personal information. This topic is discussed in more detail in the <a -href="http://android-developers.blogspot.com/2011/03/identifying-app-installations.html">Android Developer Blog</a>.</p> - -<p>Application developers should be careful writing to on-device logs. -In Android, logs are a shared resource, and are available -to an application with the -<a href="{@docRoot}reference/android/Manifest.permission.html#READ_LOGS"> -<code>READ_LOGS</code></a> permission. Even though the phone log data -is temporary and erased on reboot, inappropriate logging of user information -could inadvertently leak user data to other applications.</p> - - -<h3>Handling Credentials</h3> - -<p>In general, we recommend minimizing the frequency of asking for user -credentials -- to make phishing attacks more conspicuous, and less likely to be -successful. Instead use an authorization token and refresh it.</p> - -<p>Where possible, username and password should not be stored on the device. -Instead, perform initial authentication using the username and password -supplied by the user, and then use a short-lived, service-specific -authorization token.</p> - -<p>Services that will be accessible to multiple applications should be accessed -using <code> -<a href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code>. If possible, use the <code><a -href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code> class to invoke a cloud-based service and do not store -passwords on the device.</p> - -<p>After using <code><a -href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code> to retrieve an Account, check the <code><a -href="{@docRoot}reference/android/accounts/Account.html#CREATOR">CREATOR</a> -</code> before passing in any credentials, so that you do not inadvertently pass -credentials to the wrong application.</p> - -<p>If credentials are to be used only by applications that you create, then you -can verify the application which accesses the <code><a -href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code> using <code><a -href="{@docRoot}reference/android/content/pm/PackageManager.html#checkSignatures(java.lang.String,%20java.lang.String)">checkSignature()</a></code>. -Alternatively, if only one application will use the credential, you might use a -{@link java.security.KeyStore} for -storage.</p> - -<a name="Crypto"></a> -<h2>Using Cryptography</h2> - -<p>In addition to providing data isolation, supporting full-filesystem -encryption, and providing secure communications channels Android provides a -wide array of algorithms for protecting data using cryptography.</p> - -<p>In general, try to use the highest level of pre-existing framework -implementation that can support your use case. If you need to securely -retrieve a file from a known location, a simple HTTPS URI may be adequate and -require no knowledge of cryptography on your part. If you need a secure -tunnel, consider using -<a href="{@docRoot}reference/javax/net/ssl/HttpsURLConnection.html"> -<code>HttpsURLConnection</code></a> or <code><a -href="{@docRoot}reference/javax/net/ssl/SSLSocket.html">SSLSocket</a></code>, -rather than writing your own protocol.</p> - -<p>If you do find yourself needing to implement your own protocol, we strongly -recommend that you not implement your own cryptographic algorithms. Use -existing cryptographic algorithms such as those in the implementation of AES or -RSA provided in the <code><a -href="{@docRoot}reference/javax/crypto/Cipher.html">Cipher</a></code> class.</p> - -<p>Use a secure random number generator ( -<a href="{@docRoot}reference/java/security/SecureRandom.html"> -<code>SecureRandom</code></a>) to initialize any cryptographic keys (<a -href="{@docRoot}reference/javax/crypto/KeyGenerator.html"> -<code>KeyGenerator</code></a>). Use of a key that is not generated with a secure random -number generator significantly weakens the strength of the algorithm, and may -allow offline attacks.</p> - -<p>If you need to store a key for repeated use, use a mechanism like - {@link java.security.KeyStore} that -provides a mechanism for long term storage and retrieval of cryptographic -keys.</p> - -<h2>Conclusion</h2> - -<p>Android provides developers with the ability to design applications with a -broad range of security requirements. These best practices will help you make -sure that your application takes advantage of the security benefits provided by -the platform.</p> - -<p>You can receive more information on these topics and discuss security best -practices with other developers in the <a -href="http://groups.google.com/group/android-security-discuss">Android Security -Discuss</a> Google Group</p> diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd index 7e031d9..6e6fa28 100644 --- a/docs/html/guide/topics/appwidgets/index.jd +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -3,14 +3,6 @@ page.title=App Widgets <div id="qv-wrapper"> <div id="qv"> - <h2>Quickview</h2> - <ul> - <li>App Widgets provide users access to some of your application features -directly from the Home screen (without the need to launch an activity)</li> - <li>App Widgets are backed by a special kind of broadcast receiver that -handles the App -Widget lifecycle</li> - </ul> <h2>In this document</h2> <ol> @@ -33,6 +25,11 @@ from </ol> </li> <li><a href="#preview">Setting a Preview Image</a></li> + <li><a href="#lockscreen">Enabling App Widgets on the Lockscreen + <ol> + <li><a href="#lockscreen-sizing">Sizing guidelines</li> + </ol> + </li> <li><a href="#collections">Using App Widgets with Collections</a> <ol> <li><a href="#collection_sample">Sample application</a></li> @@ -50,18 +47,6 @@ collections <li>{@link android.appwidget.AppWidgetProviderInfo}</li> <li>{@link android.appwidget.AppWidgetManager}</li> </ol> - - <h2>See also</h2> - <ol> - <li><a -href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">App Widget -Design - Guidelines</a></li> - <li><a -href="http://android-developers.blogspot.com/2009/04/introducing-home-screen- -widgets-and.html">Introducing - home screen widgets and the AppWidget framework »</a></li> - </ol> </div> </div> @@ -77,11 +62,17 @@ able to hold other App Widgets is called an App Widget host. The screenshot below shows the Music App Widget.</p> -<img src="{@docRoot}images/appwidget.png" alt="" /> +<img src="{@docRoot}images/appwidgets/appwidget.png" alt="" /> <p>This document describes how to publish an App Widget using an App Widget provider.</p> +<div class="note design"> +<p><strong>Widget Design</strong></p> + <p>For information about how to design your app widget, read the <a +href="{@docRoot}design/patterns/widgets.html">Widgets</a> design guide.</p> +</div> + <h2 id="Basics">The Basics</h2> @@ -179,7 +170,9 @@ folder.</p> android:previewImage="@drawable/preview" android:initialLayout="@layout/example_appwidget" android:configure="com.example.android.ExampleAppWidgetConfigure" - android:resizeMode="horizontal|vertical"> + android:resizeMode="horizontal|vertical" + android:widgetCategory="home_screen|keyguard" + android:initialKeyguardLayout="@layout/example_keyguard"> </appwidget-provider> </pre> @@ -274,7 +267,21 @@ widget to show its resize handles, then drag the horizontal and/or vertical handles to change the size on the layout grid. Values for the <code>resizeMode</code> attribute include "horizontal", "vertical", and "none". To declare a widget as resizeable horizontally and vertically, supply the value -"horizontal|vertical". Introduced in Android 3.1.</li> </ul> +"horizontal|vertical". Introduced in Android 3.1.</li> + +<li>The <code>widgetCategory</code> attribute declares whether your App Widget can be displayed on the home screen, +the lock screen (keyguard), or both. Values for this attribute include "home_screen" and "keyguard". A widget that +is displayed on both needs to ensure that it follows the design guidelines for both widget classes. For more +information, see <a href="#lockscreen">Enabling App Widgets on the Lockscreen</a>. The default value is "home_screen". Introduced in Android 4.2. +</li> + +<li>The <code>initialKeyguardLayout</code> attribute points to the layout resource +that defines the lock screen App Widget layout. This works the same way as the +{@link android.appwidget.AppWidgetProviderInfo#initialLayout android:initialLayout}, +in that it provides a layout that can appear immediately until your app widget is initialized and able to update +the layout. Introduced in Android 4.2.</li> + +</ul> <p>See the {@link android.appwidget.AppWidgetProviderInfo} class for more information on the @@ -731,6 +738,66 @@ preview image, launch this application, select the app widget for your application and set it up how you'd like your preview image to appear, then save it and place it in your application's drawable resources.</p> +<h2 id="lockscreen">Enabling App Widgets on the Lockscreen</h2> + +<p>Android 4.2 introduces the ability for users to add widgets to the lock screen. To indicate that your app widget is available for use on the lock screen, declare the {@link android.appwidget.AppWidgetProviderInfo#widgetCategory android:widgetCategory} attribute in the XML file that specifies your {@link android.appwidget.AppWidgetProviderInfo}. This attribute supports two values: "home_screen" and "keyguard". An app widget can declare support for one or both.</p> + +<p>By default, every app widget supports placement on the Home screen, so "home_screen" is the default value for the +{@link android.appwidget.AppWidgetProviderInfo#widgetCategory android:widgetCategory} attribute. If you want your app widget to be available for the lock screen, add the "keyguard" value:</p> +<pre> +<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" + ... + android:widgetCategory="keyguard|home_screen"> +</appwidget-provider> +</pre> + +<p>If you declare a widget to be displayable on both keyguard (lockscreen) and home, it's likely that you'll want to customize the widget depending on where it is displayed. For example, you might create a separate layout file for keyguard vs. home. The next step is to detect the widget category at runtime and respond accordingly. + +You can detect whether your widget is on the lockscreen or home screen by calling +{@link android.appwidget.AppWidgetManager#getAppWidgetOptions getAppWidgetOptions()} +to get the widget's options as a {@link android.os.Bundle}. The returned bundle will include the key +{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_HOST_CATEGORY}, whose value will be one of {@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_HOME_SCREEN} or +{@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_KEYGUARD}. This value is determined by the host into which the widget is bound. In the {@link android.appwidget.AppWidgetProvider}, you can then check the widget's category, for example:</p> + +<pre> +AppWidgetManager appWidgetManager; +int widgetId; +Bundle myOptions = appWidgetManager.getAppWidgetOptions (widgetId); + +// Get the value of OPTION_APPWIDGET_HOST_CATEGORY +int category = myOptions.getInt(AppWidgetManager.OPTION_APPWIDGET_HOST_CATEGORY, -1); + +// If the value is WIDGET_CATEGORY_KEYGUARD, it's a lockscreen widget +boolean isKeyguard = category == AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD; +</pre> + +<p>Once you know the widget's category, you can optionally load a different base layout, set different properties, and so on. For example:</p> + +<pre> +int baseLayout = isKeyguard ? R.layout.keyguard_widget_layout : R.layout.widget_layout; +</pre> + + +<p>You should also specify an initial layout for your app widget when on the lock screen with the +{@link android.appwidget.AppWidgetProviderInfo#initialKeyguardLayout android:initialKeyguardLayout} attribute. This works the same way as the +{@link android.appwidget.AppWidgetProviderInfo#initialLayout android:initialLayout}, in that it provides a layout that can appear immediately until your app widget is initialized and able to update the layout.</p> + +<h3 id="lockscreen-sizing">Sizing guidelines</h3> + +<p>When a widget is hosted on the lockscreen, the framework ignores the {@code minWidth}, {@code minHeight}, {@code minResizeWidth}, and {@code minResizeHeight} fields. If a widget is also a home screen widget, these parameters are still needed as they're still used on home, but they will be ignored for purposes of the lockscreen.</p> + +<p>The width of a lockscreen widget always fills the provided space. For the height of a lockscreen widget, you have the following options:</p> + +<ul> + <li>If the widget does not mark itself as vertically resizable ({@code android:resizeMode="vertical"}), then the widget height will always be "small": + <ul> + <li>On a phone in portrait mode, "small" is defined as the space remaining when an unlock UI is being displayed.</li> + <li>On tablets and landscape phones, "small" is set on a per-device basis.</li> + </ul> + </li> + <li>If the widget marks itself as vertically resizable, then the widget height shows up as "small" on portrait phones displaying an unlock UI. In all other cases, the widget sizes to fill the available height.</li> +</ul> + <h2 id="collections">Using App Widgets with Collections</h2> <p>Android 3.0 introduces App Widgets with collections. These kinds of App @@ -815,7 +882,7 @@ href="{@docRoot}resources/samples/StackWidget/index.html">StackView Widget sample</a>:</p> <p> -<img src="{@docRoot}resources/images/StackWidget.png" alt="" /> +<img src="{@docRoot}images/appwidgets/StackWidget.png" alt="" /> </p> <p>This sample consists of a stack of 10 views, which display the values @@ -1318,7 +1385,7 @@ collections when updates occur. It shows how the App Widget code interacts with the {@link android.widget.RemoteViewsService.RemoteViewsFactory RemoteViewsFactory}, and how you can trigger updates:</p> -<img src="{@docRoot}images/appwidget_collections.png" alt="" /> +<img src="{@docRoot}images/appwidgets/appwidget_collections.png" alt="" /> <p>One feature of App Widgets that use collections is the ability to provide users with up-to-date content. For example, consider the Android 3.0 Gmail diff --git a/docs/html/guide/topics/renderscript/compute.jd b/docs/html/guide/topics/renderscript/compute.jd index d464c90..5f466ce 100644 --- a/docs/html/guide/topics/renderscript/compute.jd +++ b/docs/html/guide/topics/renderscript/compute.jd @@ -10,12 +10,11 @@ parent.link=index.html <ol> <li><a href="#overview">Renderscript System Overview</a></li> + <li><a href="#filterscript">Filterscript</a></li> <li> <a href="#creating-renderscript">Creating a Computation Renderscript</a> - <ol> <li><a href="#creating-rs-file">Creating the Renderscript file</a></li> - <li><a href="#calling">Calling the Renderscript code</a></li> </ol> </li> @@ -111,16 +110,34 @@ code, like with the NDK.</li> <p>For a more detailed explanation of how all of these layers work together, see <a href="{@docRoot}guide/topics/renderscript/advanced.html">Advanced Renderscript</a>.<p> +<h2 id="filterscript">Filterscript</h2> + +<p>Introduced in Android 4.2 (API Level 17), Filterscript defines a subset of Renderscript +that focuses on image processing operations, such as those +that you would typically write with an OpenGL ES fragment shader. You still write your scripts +using the standard Renderscript runtime APIs, but within stricter +constraints that ensure wider compatibility and improved optimization across +CPUs, GPUs, and DSPs. At compile time, the precompiler evaluates Filterscript files and +applies a more stringent set of warnings and errors than +it does for standard Renderscript files. The following list describes the major constraints +of Filterscript when compared to Renderscript:</p> + +<ul> +<li>Inputs and return values of root functions cannot contain pointers. The default root function +signature contains pointers, so you must use the <code>__attribute__((kernel))</code> attribute to declare a custom +root function when using Filterscript.</li> +<li>Built-in types cannot exceed 32-bits.</li> +<li>Filterscript must always use relaxed floating point precision by using the +<code>rs_fp_relaxed</code> pragma.</li> +<li>Filterscript files must end with an <code>.fs</code> extension, instead of an <code>.rs</code> extension.</li> +</ul> <h2 id="creating-renderscript">Creating a Renderscript</h2> -<p>Renderscripts scale to the amount of +<p>Renderscript scales to the amount of processing cores available on the device. This is enabled through a function named <code>rsForEach()</code> (or the <code>forEach_root()</code> method at the Android framework level). -that automatically partitions work across available processing cores on the device. -For now, Renderscript can only take advantage of CPU -cores, but in the future, they can potentially run on other types of processors such as GPUs and -DSPs.</p> +that automatically partitions work across available processing cores on the device.</p> <p>Implementing a Renderscript involves creating a <code>.rs</code> file that contains your Renderscript code and calling it at the Android framework level with the @@ -149,10 +166,9 @@ Every <code>.rs</code> file generally contains the following items:</p> <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of Renderscript that you are using (1 is the only value for now).</li> - - <li><p>A <code>root()</code> function that is the main worker function. The root function is - called by the <code>rsForEach</code> function, which allows the Renderscript code to be called and - executed on multiple cores if they are available. The <code>root()</code> function must return + + <li><p>A root function (or kernel) that is the main entry point to your Renderscript. + The default <code>root()</code> function must return <code>void</code> and accept the following arguments:</p> <ul> @@ -172,10 +188,22 @@ Every <code>.rs</code> file generally contains the following items:</p> <li>The size of the user-defined data.</li> </ul> + + <p>Starting in Android 4.1 (API Level 16), you can choose to define your own root function arguments + without adhering to the default root function signature described previously. In addition, + you can declare multiple root functions in the same Renderscript. To do this, use the <code>__attribute__((kernel))</code> + attribute to define a custom root function. For example, here's a root function + that returns a <code>uchar4</code> and accepts two <code>uint32_t</code> types: </p> + + <pre> + uchar4 __attribute__((kernel)) root(uint32_t x, uint32_t y) { + ... + } + </pre> </li> <li>An optional <code>init()</code> function. This allows you to do any initialization - before the <code>root()</code> function runs, such as initializing variables. This + before the root function runs, such as initializing variables. This function runs once and is called automatically when the Renderscript starts, before anything else in your Renderscript.</li> @@ -203,6 +231,46 @@ void root(const uchar4 *v_in, uchar4 *v_out) { } </pre> +<h4>Setting floating point precision</h4> +<p>You can define the floating point precision required by your compute algorithms. This is useful if you + require less precision than the IEEE 754-2008 standard (used by default). You can define +the floating-point precision level of your script with the following pragmas:</p> + +<ul> + <li><code>#pragma rs_fp_full</code> (default if nothing is specified): For apps that + require floating point precision as outlined by the IEEE 754-2008 standard. +</li> + <li><code>#pragma rs_fp_relaxed</code> - For apps that don’t require + strict IEEE 754-2008 compliance and can tolerate less precision. This mode enables + flush-to-zero for denorms and round-towards-zero. +</li> + <li><code>#pragma rs_fp_imprecise</code> - For apps that don’t have stringent precision requirements. This mode enables + everything in <code>rs_fp_relaxed</code> along with the following: +<ul> + <li>Operations resulting in -0.0 can return +0.0 instead.</li> + <li>Operations on INF and NAN are undefined.</li> +</ul> +</li> +</ul> + +<h4>Script intrinsics</h4> +<p>Renderscript adds support for a set of script intrinsics, which are pre-implemented +filtering primitives that reduce the amount of +code that you need to write. They also are implemented to ensure that your app gets the +maximum performance gain possible.</p> + +<p> +Intrinsics are available for the following: +<ul> + <li>{@link android.renderscript.ScriptIntrinsicBlend Blends}</li> + <li>{@link android.renderscript.ScriptIntrinsicBlur Blur}</li> + <li>{@link android.renderscript.ScriptIntrinsicColorMatrix Color matrix}</li> + <li>{@link android.renderscript.ScriptIntrinsicConvolve3x3 3x3 convolve}</li> + <li>{@link android.renderscript.ScriptIntrinsicConvolve5x5 5x5 convolve}</li> + <li>{@link android.renderscript.ScriptIntrinsicLUT Per-channel lookup table}</li> + <li>{@link android.renderscript.ScriptIntrinsicYuvToRGB Converting an Android YUV buffer to RGB}</li> +</ul> + <h3 id="calling">Calling the Renderscript code</h3> <p>You can call the Renderscript from your Android framework code by @@ -317,24 +385,15 @@ declared previously. Passing a pointer to a struct and the size of the struct to is optional, but useful if your Renderscript requires additional information other than the necessary memory allocations.</p> -<h3>Setting floating point precision</h3> -<p>You can define the floating point precision required by your compute algorithms. This is useful if you - require less precision than the IEEE 754-2008 standard (used by default). You can define -the floating-point precision level of your script with the following pragmas:</p> -<ul> - <li><code>#pragma rs_fp_full</code> (default if nothing is specified): For apps that - require floating point precision as outlined by the IEEE 754-2008 standard. -</li> - <li><code>#pragma rs_fp_relaxed</code> - For apps that don’t require - strict IEEE 754-2008 compliance and can tolerate less precision. This mode enables - flush-to-zero for denorms and round-towards-zero. -</li> - <li><code>#pragma rs_fp_imprecise</code> - For apps that don’t have stringent precision requirements. This mode enables - everything in <code>rs_fp_relaxed</code> along with the following: -<ul> - <li>Operations resulting in -0.0 can return +0.0 instead.</li> - <li>Operations on INF and NAN are undefined.</li> -</ul> -</li> -</ul>
\ No newline at end of file +<h4>Script groups</h4> + +<p>You can group Renderscript scripts together and execute them all with a single call as though +they were part of a single script. This allows Renderscript to optimize execution of the scripts +in ways that it could not do if the scripts were executed individually.</p> + +<p>To build a script groupm, use the {@link android.renderscript.ScriptGroup.Builder} class to create a {@link android.renderscript.ScriptGroup} +defining the operations. At execution time, Renderscript optimizes the run order and the connections between these +operations for best performance. + +<p class="note"><strong>Important:</strong> The script group must be a direct acyclic graph for this feature to work.</p> diff --git a/docs/html/guide/topics/resources/more-resources.jd b/docs/html/guide/topics/resources/more-resources.jd index d37b9f8..9fa1a2d 100644 --- a/docs/html/guide/topics/resources/more-resources.jd +++ b/docs/html/guide/topics/resources/more-resources.jd @@ -540,7 +540,7 @@ resource ID.</dd> <dt>resource reference:</dt> <dd> -In Java: <code>R.array.<em>string_array_name</em></code><br/> +In Java: <code>R.array.<em>integer_array_name</em></code><br/> In XML: <code>@[<em>package</em>:]array.<em>integer_array_name</em></code> </dd> @@ -565,7 +565,7 @@ In XML: <code>@[<em>package</em>:]array.<em>integer_array_name</em></code> <dd><strong>Required.</strong> This must be the root node. <p>No attributes.</p> </dd> - <dt id="integer-array-element"><code><string-array></code></dt> + <dt id="integer-array-element"><code><integer-array></code></dt> <dd>Defines an array of integers. Contains one or more child {@code <item>} elements. <p class="caps">attributes:</p> <dl class="atn-list"> |