diff options
| author | Scott Main <smain@google.com> | 2012-06-21 17:14:39 -0700 |
|---|---|---|
| committer | Scott Main <smain@google.com> | 2012-06-21 21:27:30 -0700 |
| commit | 50e990c64fa23ce94efa76b9e72df7f8ec3cee6a (patch) | |
| tree | 52605cd25e01763596477956963fabcd087054b0 /docs/html/guide/practices | |
| parent | a2860267cad115659018d636bf9203a644c680a7 (diff) | |
| download | frameworks_base-50e990c64fa23ce94efa76b9e72df7f8ec3cee6a.zip frameworks_base-50e990c64fa23ce94efa76b9e72df7f8ec3cee6a.tar.gz frameworks_base-50e990c64fa23ce94efa76b9e72df7f8ec3cee6a.tar.bz2 | |
Massive clobber of all HTML files in developer docs for new site design
Change-Id: Idc55a0b368c1d2c1e7d4999601b739dd57f08eb3
Diffstat (limited to 'docs/html/guide/practices')
23 files changed, 1614 insertions, 53 deletions
diff --git a/docs/html/guide/practices/design/accessibility.html b/docs/html/guide/practices/app-design/accessibility.html index 0fa7b32..0fa7b32 100644 --- a/docs/html/guide/practices/design/accessibility.html +++ b/docs/html/guide/practices/app-design/accessibility.html diff --git a/docs/html/guide/practices/design/index.jd b/docs/html/guide/practices/app-design/index.jd index a818831..a818831 100644 --- a/docs/html/guide/practices/design/index.jd +++ b/docs/html/guide/practices/app-design/index.jd diff --git a/docs/html/guide/practices/design/jni.jd b/docs/html/guide/practices/app-design/jni.jd index ddfa0e3..ddfa0e3 100644 --- a/docs/html/guide/practices/design/jni.jd +++ b/docs/html/guide/practices/app-design/jni.jd diff --git a/docs/html/guide/practices/design/performance.jd b/docs/html/guide/practices/app-design/performance.jd index dd9b554..078999b 100644 --- a/docs/html/guide/practices/design/performance.jd +++ b/docs/html/guide/practices/app-design/performance.jd @@ -379,7 +379,7 @@ code compiled for the ARM in the Nexus One won't run on the ARM in the G1.</p> 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/design/jni.html">JNI Tips</a>.</p> +<a href="{@docRoot}guide/practices/jni.html">JNI Tips</a>.</p> <p>(See also <em>Effective Java</em> item 54.)</p> @@ -402,7 +402,7 @@ 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}guide/developing/debugging/debugging-tracing.html">Traceview</a> useful +<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 diff --git a/docs/html/guide/practices/design/responsiveness.jd b/docs/html/guide/practices/app-design/responsiveness.jd index a00e3aa..a00e3aa 100644 --- a/docs/html/guide/practices/design/responsiveness.jd +++ b/docs/html/guide/practices/app-design/responsiveness.jd diff --git a/docs/html/guide/practices/design/seamlessness.jd b/docs/html/guide/practices/app-design/seamlessness.jd index 6c73426..ec6b7fd 100644 --- a/docs/html/guide/practices/design/seamlessness.jd +++ b/docs/html/guide/practices/app-design/seamlessness.jd @@ -210,7 +210,7 @@ network connection. That's almost guaranteed to be much faster than a cell network, so you'll want to change the settings on the emulator that simulate slower network speeds. You can do this in Eclipse, in the "Emulator Settings" tab of your launch configuration or via a <a -href="{@docRoot}guide/developing/tools/emulator.html#netspeed">command-line +href="{@docRoot}tools/help/emulator.html#netspeed">command-line option</a> when starting the emulator.</p> <h2 id="keyboard">Don't Assume Touchscreen or Keyboard</h2> diff --git a/docs/html/guide/practices/compatibility.jd b/docs/html/guide/practices/compatibility.jd index 5e514c4..a2284bd 100644 --- a/docs/html/guide/practices/compatibility.jd +++ b/docs/html/guide/practices/compatibility.jd @@ -7,7 +7,7 @@ page.title=Android Compatibility <h2>See also</h2> <ol> <li><a -href="{@docRoot}guide/appendix/market-filters.html">Filtering on Google Play</a></li> +href="{@docRoot}guide/google/play/filters.html">Filtering on Google Play</a></li> <li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing Alternative Resources</a></li> <li><a @@ -54,7 +54,7 @@ but the single most important characteristic of a compatible device is the ability to install and correctly run an Android <code>.apk</code> file.</p> <p>There is exactly one Android API for each <a -href="{@docRoot}guide/appendix/api-levels.html">API level</a>, and it’s the same +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API level</a>, and it’s the same API no matter what kind of device it’s installed on. No parts of the API are optional, and you never have to worry about parts of the API missing on some devices. Every compatible Android device your app will land on will include @@ -119,7 +119,7 @@ device. <p style="margin-top:1em;">For information about other filters that you can use to control the availability of your apps, see the -<a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> +<a href="{@docRoot}guide/google/play/filters.html">Filters on Google Play</a> document.</p> </div> </div> diff --git a/docs/html/guide/practices/index.html b/docs/html/guide/practices/index.html deleted file mode 100644 index 4881acf..0000000 --- a/docs/html/guide/practices/index.html +++ /dev/null @@ -1,8 +0,0 @@ -<html> -<head> -<meta http-equiv="refresh" content="0;url=../index.html"> -</head> -<body> -<a href="../index.html">click here</a> if you are not redirected. -</body> -</html>
\ No newline at end of file diff --git a/docs/html/guide/practices/index.jd b/docs/html/guide/practices/index.jd new file mode 100644 index 0000000..e218b50 --- /dev/null +++ b/docs/html/guide/practices/index.jd @@ -0,0 +1,52 @@ +page.title=Best Practices +page.landing=true +page.landing.intro=Design and build apps the right way. Learn how to create apps that look great and perform well on as many devices as possible, from phones to tablets and more. +page.landing.image= + +@jd:body + +<div class="landing-docs"> + + <div class="col-12"> + <h3>Blog Articles</h3> + + <a href="android-developers.blogspot.com/2010/10/improving-app-quality.html"> + <h4>Improving App Quality</h4> + <p>One way of improving your app’s visibility in the ecosystem is by deploying well-targeted +mobile advertising campaigns and cross-app promotions. However, there’s another time-tested method +of fueling the impression-install-ranking cycle: improve the product!</p> + </a> + + <a href="http://android-developers.blogspot.com/2012/01/say-goodbye-to-menu-button.html"> + <h4>Say Goodbye to the Menu Button</h4> + <p>As Ice Cream Sandwich rolls out to more devices, it?s important that you begin to migrate +your designs to the action bar in order to promote a consistent Android user experience.</p> + </a> + + <a href="android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html"> + <h4>New Tools For Managing Screen Sizes</h4> + <p>Android 3.2 includes new tools for supporting devices with a wide range of screen sizes. +One important result is better support for a new size of screen; what is typically called a “7-inch” +tablet. This release also offers several new APIs to simplify developers’ work in adjusting to +different screen sizes.</p> + </a> + + <a href="android-developers.blogspot.com/2011/03/identifying-app-installations.html"> + <h4>Identifying App Installations</h4> + <p>It is very common, and perfectly reasonable, for a developer to want to track individual +installations of their apps. It sounds plausible just to call TelephonyManager.getDeviceId() and use +that value to identify the installation. There are problems with this</p> + </a> + + <a +href="http://android-developers.blogspot.com/2011/11/making-android-games-that-play-nice.html"> + <h4>Making Android Games that Play Nice</h4> + <p>Making a game on Android is easy. Making a <em>great</em> game for a mobile, multitasking, +often multi-core, multi-purpose system like Android is trickier. Even the best developers frequently +make mistakes in the way they interact with the Android system and with other applications</p> + </a> + + </div> + + +</div>
\ No newline at end of file diff --git a/docs/html/guide/practices/jni.jd b/docs/html/guide/practices/jni.jd new file mode 100644 index 0000000..ddfa0e3 --- /dev/null +++ b/docs/html/guide/practices/jni.jd @@ -0,0 +1,719 @@ +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/optimizing-for-3.0.jd b/docs/html/guide/practices/optimizing-for-3.0.jd index d6c621e..65c5674 100644 --- a/docs/html/guide/practices/optimizing-for-3.0.jd +++ b/docs/html/guide/practices/optimizing-for-3.0.jd @@ -53,7 +53,7 @@ onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> <li><a href="tablets-and-handsets.html">Supporting Tablets and Handsets</a></li> <li><a -href="{@docRoot}sdk/compatibility-library.html">Compatibility Library</a></li> +href="{@docRoot}tools/extras/support-library.html">Compatibility Library</a></li> <li><a href="http://code.google.com/p/iosched/">Google I/O App source code</a></li> </ol> @@ -108,7 +108,7 @@ SDK with the new platform:</p> SDK starter package now</a>.)</p> <ol> - <li><a href="{@docRoot}sdk/adding-components.html#launching">Launch the Android SDK + <li><a href="{@docRoot}sdk/exploring.html#launching">Launch the Android SDK Manager</a> and install the following: <ul> <li>SDK Platform Android 3.0</li> @@ -280,15 +280,15 @@ use techniques such as reflection to check for the availability of certain APIs to help you add features from Android 3.0 without requiring you to change your <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> or build target, we're providing a static library called the <a -href="{@docRoot}sdk/compatibility-library.html">Compatibility Library</a> +href="{@docRoot}tools/extras/support-library.html">Compatibility Library</a> (downloadable from the Android SDK Manager).</p> <p>This library includes APIs for <a -href="{@docRoot}guide/topics/fundamentals/fragments.html">fragments</a>, <a -href="{@docRoot}guide/topics/fundamentals/loaders.html">loaders</a>, and some updated classes. By +href="{@docRoot}guide/components/fragments.html">fragments</a>, <a +href="{@docRoot}guide/components/loaders.html">loaders</a>, and some updated classes. By simply adding this library to your Android project, you can use these APIs in your application and remain compatible with Android 1.6. For information about how to get the library and start using it in your application, see the <a -href="{@docRoot}sdk/compatibility-library.html">Compatibility Library</a> document.</p> +href="{@docRoot}tools/extras/support-library.html">Compatibility Library</a> document.</p> </div> </div> @@ -357,7 +357,7 @@ input events. Thus, instead of using one activity to select an article and anoth read the article, the user can select an article and read it all within the same activity.</p> <p>For more information, read the <a -href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> document.</p> +href="{@docRoot}guide/components/fragments.html">Fragments</a> document.</p> <h3>Use new animation APIs for transitions</h3> @@ -374,7 +374,7 @@ New transformations are made possible with a set of object properties that defin position, orientation, transparency and more.</p> <p>For more information, read the <a -href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a> document.</p> +href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a> document.</p> <h3>Enable hardware acceleration</h3> @@ -412,15 +412,15 @@ application, such as drag and drop APIs, new Bluetooth APIs, a system-wide clipb new graphics engine called Renderscript, and more.</p> <p>To learn more about the APIs mentioned above and more, see the <a -href="{@docRoot}sdk/android-3.0.html">Android 3.0 Platform</a> document.</p> +href="{@docRoot}about/versions/android-3.0.html">Android 3.0 Platform</a> document.</p> <h3>Look at some samples</h3> <p>Many of the new features and APIs that are described above and in the <a -href="{@docRoot}sdk/android-3.0.html#api">Android 3.0 Platform</a> document also have accompanying +href="{@docRoot}about/versions/android-3.0.html#api">Android 3.0 Platform</a> document also have accompanying samples that allow you to preview the effects and can help you understand how to use them. To get -the samples, download them from the SDK repository <a href="{@docRoot}sdk/adding-components.html" +the samples, download them from the SDK repository <a href="{@docRoot}sdk/exploring.html" >using the Android SDK Manager</a>. After downloading the samples ("Samples for SDK API 11"), you can find them in <code><sdk_root>/samples/android-11/</code>. The following list provides links to the browsable source code for some of the samples:</p> @@ -474,7 +474,7 @@ android:targetSdkVersion}</a> set to {@code "4"} or higher, then the Android sys application's layout and assets to fit the current device screen, whether the device screen is smaller or larger than the one for which you originally designed your application. As such, you should always test your application on real or <a -href="{@docRoot}guide/developing/devices/index.html">virtual devices</a> with various screen sizes +href="{@docRoot}tools/devices/index.html">virtual devices</a> with various screen sizes and densities.</p> <p>Although we recommend that you design your application to function properly on multiple @@ -641,7 +641,7 @@ orientation. When the user rotates the screen, the system restarts the current a onCreate()}) in immediate succession. You should design your activity to account for these changes in the lifecycle, so the activity can save and restore its state. You can learn about the necessary lifecycle callback methods and how to save and restore the activity state in the <a -href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activities</a> +href="{@docRoot}guide/components/activities.html#Lifecycle">Activities</a> document. If your activity state is more complex and cannot retain it using the normal lifecycle callback methods, you can use alternative techniques described in <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a>.</p> diff --git a/docs/html/guide/practices/performance.jd b/docs/html/guide/practices/performance.jd new file mode 100644 index 0000000..078999b --- /dev/null +++ b/docs/html/guide/practices/performance.jd @@ -0,0 +1,410 @@ +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/responsiveness.jd b/docs/html/guide/practices/responsiveness.jd new file mode 100644 index 0000000..a00e3aa --- /dev/null +++ b/docs/html/guide/practices/responsiveness.jd @@ -0,0 +1,140 @@ +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/screens-distribution.jd b/docs/html/guide/practices/screens-distribution.jd index a7c4a8e..90ac752 100644 --- a/docs/html/guide/practices/screens-distribution.jd +++ b/docs/html/guide/practices/screens-distribution.jd @@ -213,4 +213,4 @@ sizes, especially, is within reason using a single APK, as long as you follow th <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p> <p>If you need more information about how to publish multiple APKs on Google Play, read <a -href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> +href="{@docRoot}guide/google/play/publishing/multiple-apks.html">Multiple APK Support</a>.</p> diff --git a/docs/html/guide/practices/screens-support-1.5.jd b/docs/html/guide/practices/screens-support-1.5.jd index 4c6fb99..15f0695 100644 --- a/docs/html/guide/practices/screens-support-1.5.jd +++ b/docs/html/guide/practices/screens-support-1.5.jd @@ -59,7 +59,7 @@ below.</p> <p class="note"><strong>Note:</strong> Before you begin, you should first decide whether it's even necessary to support Android 1.5. To see the relative number of devices that are still running Android 1.5, see the <a -href="http://developer.android.com/resources/dashboard/platform-versions.html">Platform Versions +href="http://developer.android.com/about/dashboards/index.html">Platform Versions Dashboard</a>.</p> diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index a870b22..ca29589 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -57,7 +57,7 @@ href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResou Providing Alternative Resources</a></li> <li><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design Guidelines</a></li> - <li><a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a></li> + <li><a href="{@docRoot}tools/devices/index.html">Managing Virtual Devices</a></li> </ol> </div> @@ -1253,7 +1253,7 @@ Manager with a selection of AVDs, for testing various screen configurations.</p> to emulate some of the most common screen configurations.</p> <p>For more information about creating and using AVDs to test your application, see <a -href="{@docRoot}guide/developing/devices/managing-avds.html">Managing AVDs with AVD +href="{@docRoot}tools/devices/managing-avds.html">Managing AVDs with AVD Manager</a>.</p> @@ -1366,5 +1366,5 @@ the emulator with the <code>-scale</code> option. For example:</p> between 0.1 and 3 that represents the desired scaling factor.</p> <p>For more information about creating AVDs from the command line, see <a -href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing AVDs from the +href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from the Command Line</a></p> diff --git a/docs/html/guide/practices/seamlessness.jd b/docs/html/guide/practices/seamlessness.jd new file mode 100644 index 0000000..ec6b7fd --- /dev/null +++ b/docs/html/guide/practices/seamlessness.jd @@ -0,0 +1,249 @@ +page.title=Designing for Seamlessness +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>In this document</h2> +<ol> + <li><a href="#drop">Don't Drop Data</a></li> + <li><a href="#expose">Don't Expose Raw Data</a></li> + <li><a href="#interrupt">Don't Interrupt the User</a></li> + <li><a href="#threads">Got a Lot to Do? Do it in a Thread</a></li> + <li><a href="#multiple-activities">Don't Overload a Single Activity Screen</a></li> + <li><a href="#themes">Extend System Themes</a></li> + <li><a href="#flexui">Design Your UI to Work with Multiple Screen Resolutions</a></li> + <li><a href="#network">Assume the Network is Slow</a></li> + <li><a href="#keyboard">Don't Assume Touchscreen or Keyboard</a></li> + <li><a href="#battery">Do Conserve the Device Battery</a></li> +</ol> + +</div> +</div> + +<p>Even if your application is fast and responsive, certain design decisions can +still cause problems for users — because of unplanned interactions with +other applications or dialogs, inadvertent loss of data, unintended blocking, +and so on. To avoid these problems, it helps to understand the context in which +your applications run and the system interactions that can affect your +application. In short, you should strive to develop an application that +interacts seamlessly with the system and with other applications. </p> + +<p>A common seamlessness problem is when an application's background process +— for example, a service or broadcast receiver — pops up a dialog in +response to some event. This may seem like harmless behavior, especially when +you are building and testing your application in isolation, on the emulator. +However, when your application is run on an actual device, your application may +not have user focus at the time your background process displays the dialog. So +it could end up that your application would display it's dialog behind the +active application, or it could take focus from the current application and +display the dialog in front of whatever the user was doing (such as dialing a +phone call, for example). That behavior would not work for your application or +for the user. </p> + +<p>To avoid these problems, your application should use the proper system +facility for notifying the user — the +{@link android.app.Notification Notification} classes. Using +notifications, your application can signal the user that an event has +taken place, by displaying an icon in the status bar rather than taking +focus and interrupting the user.</p> + +<p>Another example of a seamlessness problem is when an activity inadvertently +loses state or user data because it doesn't correctly implement the onPause() +and other lifecycle methods. Or, if your application exposes data intended to be +used by other applications, you should expose it via a ContentProvider, rather +than (for example) doing so through a world-readable raw file or database.</p> + +<p>What those examples have in common is that they involve cooperating nicely +with the system and other applications. The Android system is designed to treat +applications as a sort of federation of loosely-coupled components, rather than +chunks of black-box code. This allows you as the developer to view the entire +system as just an even-larger federation of these components. This benefits you +by allowing you to integrate cleanly and seamlessly with other applications, and +so you should design your own code to return the favor.</p> + +<p>This document discusses common seamlessness problems and how to avoid them.</p> + +<h2 id="drop">Don't Drop Data</h2> + +<p>Always keep in mind that Android is a mobile platform. It may seem obvious to +say it, but it's important to remember that another Activity (such as the +"Incoming Phone Call" app) can pop up over your own Activity at any moment. +This will fire the onSaveInstanceState() and onPause() methods, and will likely result in +your application being killed.</p> + +<p>If the user was editing data in your application when the other Activity +appeared, your application will likely lose that data when your application is +killed. Unless, of course, you save the work in progress first. The "Android +Way" is to do just that: Android applications that accept or edit input should +override the onSaveInstanceState() method and save their state in some appropriate +fashion. When the user revisits the application, she should be able to +retrieve her data.</p> + +<p>A classic example of a good use of this behavior is a mail application. If the +user was composing an email when another Activity started up, the application +should save the in-process email as a draft.</p> + +<h2 id="expose">Don't Expose Raw Data</h2> + +<p>If you wouldn't walk down the street in your underwear, neither should your +data. While it's possible to expose certain kinds of application to the world +to read, this is usually not the best idea. Exposing raw data requires other +applications to understand your data format; if you change that format, you'll +break any other applications that aren't similarly updated.</p> + +<p>The "Android Way" is to create a ContentProvider to expose your data to other +applications via a clean, well-thought-out, and maintainable API. Using a +ContentProvider is much like inserting a Java language interface to split up and +componentize two tightly-coupled pieces of code. This means you'll be able to +modify the internal format of your data without changing the interface exposed +by the ContentProvider, and this without affecting other applications.</p> + +<h2 id="interrupt">Don't Interrupt the User</h2> + +<p>If the user is running an application (such as the Phone application during a +call) it's a pretty safe bet he did it on purpose. That's why you should avoid +spawning activities except in direct response to user input from the current +Activity.</p> + +<p>That is, don't call startActivity() from BroadcastReceivers or Services running in +the background. Doing so will interrupt whatever application is currently +running, and result in an annoyed user. Perhaps even worse, your Activity may +become a "keystroke bandit" and receive some of the input the user was in the +middle of providing to the previous Activity. Depending on what your +application does, this could be bad news.</p> + +<p>Instead of spawning Activity UIs directly from the background, you should +instead use the NotificationManager to set Notifications. These will appear in +the status bar, and the user can then click on them at his leisure, to see +what your application has to show him.</p> + +<p>(Note that all this doesn't apply to cases where your own Activity is already +in the foreground: in that case, the user expects to see your next Activity in +response to input.)</p> + +<h2 id="threads">Got a Lot to Do? Do it in a Thread</h2> + +<p>If your application needs to perform some expensive or long-running +computation, you should probably move it to a thread. This will prevent the +dreaded "Application Not Responding" dialog from being displayed to the user, +with the ultimate result being the fiery demise of your application.</p> + +<p>By default, all code in an Activity as well as all its Views run in the same +thread. This is the same thread that also handles UI events. For example, when +the user presses a key, a key-down event is added to the Activity's main +thread's queue. The event handler system needs to dequeue and handle that +event quickly; if it doesn't, the system concludes after a few seconds that +the application is hung and offers to kill it for the user.</p> + +<p>If you have long-running code, running it inline in your Activity will run it +on the event handler thread, effectively blocking the event handler. This will +delay input processing, and result in the ANR dialogs. To avoid this, move +your computations to a thread. This <a +href="responsiveness.html">Design for Responsiveness</a> document +discusses how to do that..</p> + +<h2 id="multiple-activities">Don't Overload a Single Activity Screen</h2> + +<p>Any application worth using will probably have several different screens. +When designing the screens of your UI, be sure to make use of multiple Activity +object instances.</p> + +<p>Depending on your development background, you may interpret an Activity as +similar to something like a Java Applet, in that it is the entry point for +your application. However, that's not quite accurate: where an Applet subclass +is the single entry point for a Java Applet, an Activity should be thought of +as one of potentially several entry points to your application. The only +difference between your "main" Activity and any others you might have is that +the "main" one just happens to be the only one that expressed an interest in +the "android.intent.action.MAIN" action in your AndroidManifest..xml file.</p> + +<p>So, when designing your application, think of your application as a federation +of Activity objects. This will make your code a lot more maintainable in the long +run, and as a nice side effect also plays nicely with Android's application +history and "backstack" model.</p> + +<h2 id="themes">Extend System Themes</h2> + +<p>When it comes to the look-and-feel of the user interface, it's important to +blend in nicely. Users are jarred by applications which contrast with the user +interface they've come to expect. When designing your UIs, you should try and +avoid rolling your own as much as possible. Instead, use a Theme. You +can override or extend those parts of the theme that you need to, but at least +you're starting from the same UI base as all the other applications. For all +the details, read <a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>.</p> + +<h2 id="flexui">Design Your UI to Work with Multiple Screen Resolutions</h2> + +<p>Different Android-powered devices will support different screen resolutions. +Some will even be able to change resolutions on the fly, such as by switching +to landscape mode. It's important to make sure your layouts and drawables +are flexible enough to display properly on a variety of device screens.</p> + +<p>Fortunately, this is very easy to do. In brief, what you must do is +provide different versions of your artwork (if you use any) for the key +resolutions, and then design your layout to accommodate various dimensions. +(For example, avoid using hard-coded positions and instead use relative +layouts.) If you do that much, the system handles the rest, and your +application looks great on any device.</p> + +<h2 id="network">Assume the Network is Slow</h2> + +<p>Android devices will come with a variety of network-connectivity options. All +will have some data-access provision, though some will be faster than others. +The lowest common denominator, however, is GPRS, the non-3G data service for +GSM networks. Even 3G-capable devices will spend lots of time on non-3G +networks, so slow networks will remain a reality for quite a long time to +come.</p> + +<p>That's why you should always code your applications to minimize network +accesses and bandwidth. You can't assume the network is fast, so you should +always plan for it to be slow. If your users happen to be on faster networks, +then that's great — their experience will only improve. You want to avoid the +inverse case though: applications that are usable some of the time, but +frustratingly slow the rest based on where the user is at any given moment are +likely to be unpopular.</p> + +<p>One potential gotcha here is that it's very easy to fall into this trap if +you're using the emulator, since the emulator uses your desktop computer's +network connection. That's almost guaranteed to be much faster than a cell +network, so you'll want to change the settings on the emulator that simulate +slower network speeds. You can do this in Eclipse, in the "Emulator Settings" +tab of your launch configuration or via a <a +href="{@docRoot}tools/help/emulator.html#netspeed">command-line +option</a> when starting the emulator.</p> + +<h2 id="keyboard">Don't Assume Touchscreen or Keyboard</h2> + +<p> +Android will support a variety of handset form-factors. That's a fancy way of +saying that some Android devices will have full "QWERTY" keyboards, while +others will have 40-key, 12-key, or even other key configurations. Similarly, +some devices will have touch-screens, but many won't. +</p><p> +When building your applications, keep that in mind. Don't make assumptions +about specific keyboard layouts -- unless, of course, you're really interested +in restricting your application so that it can only be used on those devices. +</p> + +<h2 id="battery">Do Conserve the Device Battery</h2> +<p> +A mobile device isn't very mobile if it's constantly plugged into the +wall. Mobile devices are battery-powered, and the longer we can make that +battery last on a charge, the happier everyone is — especially the user. +Two of the biggest consumers of battery power are the processor, and the +radio; that's why it's important to write your applications to do as little +work as possible, and use the network as infrequently as possible. +</p><p> +Minimizing the amount of processor time your application uses really comes +down to <a href="performance.html">writing efficient +code</a>. To minimize the power drain from using the radio, be sure to handle +error conditions gracefully, and only fetch what you need. For example, don't +constantly retry a network operation if one failed. If it failed once, it's +likely because the user has no reception, so it's probably going to fail again +if you try right away; all you'll do is waste battery power. +</p><p> +Users are pretty smart: if your program is power-hungry, you can count on +them noticing. The only thing you can be sure of at that point is that your +program won't stay installed very long. +</p> diff --git a/docs/html/guide/practices/security.jd b/docs/html/guide/practices/security.jd index eeaac44..48ccdeb 100644 --- a/docs/html/guide/practices/security.jd +++ b/docs/html/guide/practices/security.jd @@ -20,8 +20,7 @@ page.title=Designing for Security <ol> <li><a href="http://source.android.com/tech/security/index.html">Android Security Overview</a></li> -<li><a href="{@docRoot}guide/topics/security/security.html">Android Security -And Permissions</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 @@ -136,7 +135,7 @@ 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 <code><a -href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> and +href="{@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> 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 diff --git a/docs/html/guide/practices/tablets-and-handsets.jd b/docs/html/guide/practices/tablets-and-handsets.jd index 8e07a08..8d6d3dd 100644 --- a/docs/html/guide/practices/tablets-and-handsets.jd +++ b/docs/html/guide/practices/tablets-and-handsets.jd @@ -26,7 +26,7 @@ Gallery</a></li> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a></li> + <li><a href="{@docRoot}guide/components/fragments.html">Fragments</a></li> <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li> <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> </ol> @@ -85,7 +85,7 @@ activity), which has its own lifecycle and which you can add or remove while the running.</p> <p>If you haven't used fragments yet, start by reading the <a -href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> developer guide.</p> +href="{@docRoot}guide/components/fragments.html">Fragments</a> developer guide.</p> </li> @@ -141,16 +141,16 @@ bar below.</p> <h3>Remaining backward-compatible</h3> <p>If you want to use fragments in your application <em>and</em> remain compatible with versions of Android older than 3.0, you can do so by using the Android <a -href="{@docRoot}sdk/compatibility-library.html">Support Library</a> (downloadable from the +href="{@docRoot}tools/extras/support-library.html">Support Library</a> (downloadable from the SDK Manager).</p> <p>The support library includes APIs for <a -href="{@docRoot}guide/topics/fundamentals/fragments.html">fragments</a>, <a -href="{@docRoot}guide/topics/fundamentals/loaders.html">loaders</a>, and other APIs added in newer +href="{@docRoot}guide/components/fragments.html">fragments</a>, <a +href="{@docRoot}guide/components/loaders.html">loaders</a>, and other APIs added in newer versions of Android. By simply adding this library to your Android project, you can use backward-compatible versions of these APIs in your application and remain compatible with Android 1.6 (your <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> value can be as low as {@code "4"}). For information about how to get the -library and start using it, see the <a href="{@docRoot}sdk/compatibility-library.html">Support +library and start using it, see the <a href="{@docRoot}tools/extras/support-library.html">Support Library</a> document.</p> <p>The support library <em>does not</em> provide APIs for the action bar, but you can use diff --git a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd index 8e4528e..cb2bc37 100644 --- a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd +++ b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd @@ -19,7 +19,7 @@ parent.link=index.html for <a href="{@docRoot}design/patterns/app-structure.html">App Structure</a> and <a href="{@docRoot}design/patterns/navigation.html">Navigation</a>, or the developer guide about <a -href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>.</p> +href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a>.</p> <input style="margin-top:1em;padding:5px" type="button" value="That's nice, but I still want to read this document" @@ -88,7 +88,7 @@ need to</a></li> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/topics/fundamentals.html">Application Fundamentals</a></li> + <li><a href="{@docRoot}guide/components/fundamentals.html">Application Fundamentals</a></li> </ol> </div> @@ -121,9 +121,9 @@ need to</a></li> <p> Be sure to look at the <a href="#design_tips">Design Tips</a> section for guidelines, tips, and things to avoid. This document is a - complement to the <a href="{@docRoot}guide/topics/fundamentals.html">Application + complement to the <a href="{@docRoot}guide/components/fundamentals.html">Application Fundamentals</a> documentation (particularly the <a -href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a> +href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a> document), which covers the underlying mechanics for programmers. </p> @@ -189,7 +189,7 @@ document), <p> An activity handles a particular type of content (data) and accepts a set of related user actions. Each activity has a - <a href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">lifecycle</a> that is + <a href="{@docRoot}guide/components/activities.html#Lifecycle">lifecycle</a> that is independent of the other activities in its application or task — each activity is launched (started) independently, and the user or system can start, @@ -268,7 +268,7 @@ independent of the other An activity is the most prominent of four <em>components</em> of an application. The other components are service, content provider and broadcast receiver. For more details on activities, see the - <a href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a> document. + <a href="{@docRoot}guide/components/activities.html">Activities</a> document. </p> @@ -750,7 +750,7 @@ itself. <p> For more about intents, see <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a>. +href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. </p> @@ -947,7 +947,7 @@ href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Fi Home screen), or from a shortcut icon on the Home screen, or from the task switcher. (The mechanism for this is for the activity to have an - <a href={@docRoot}guide/topics/intents/intents-filters.html>intent filter</a> with action + <a href={@docRoot}guide/components/intents-filters.html>intent filter</a> with action MAIN and category LAUNCHER.) </li> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd b/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd index 4b6768f..28817fd 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd @@ -241,8 +241,8 @@ that launcher icons are legible across on any background color.</p> <h3 id="icons_in_market">Application Icons on Google Play</h3> -<p>If you are <a href="{@docRoot}guide/publishing/publishing.html">publishing your application on -Google Play</a>, you will also need to provide a 512 x 512 pixel, high-resolution application icon +<p>If you are publishing your app on +Google Play, you will also need to provide a 512 x 512 pixel, high-resolution application icon in the <a href="http://play.google.com/apps/publish">developer console</a> at upload time. This icon will be used in various locations on Google Play and does not replace your launcher icon.</p> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd b/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd index 85a3cc8..f6c2247 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd @@ -58,7 +58,7 @@ suggestions on how to work with multiple sets of icons.</p> <h2 id="market">Application Icons on Google Play</h2> -<p>If you are <a href="{@docRoot}guide/publishing/publishing.html">publishing +<p>If you are <a href="{@docRoot}tools/publishing/publishing.html">publishing your application on Google Play</a>, you will also need to provide a 512x512 pixel, high-resolution application icon in the <a href="http://play.google.com/apps/publish">developer console</a> at upload-time. diff --git a/docs/html/guide/practices/ui_guidelines/widget_design.jd b/docs/html/guide/practices/ui_guidelines/widget_design.jd index d789407..616f9ae 100644 --- a/docs/html/guide/practices/ui_guidelines/widget_design.jd +++ b/docs/html/guide/practices/ui_guidelines/widget_design.jd @@ -229,7 +229,7 @@ in the <em>Developer's Guide</em> for information on how to achieve this with la practice to define this shape using nine patches; one for each screen density (see <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> for details). Nine-patches can be created with the <a -href="{@docRoot}guide/developing/tools/draw9patch.html">draw9patch</a> tool, or simply with a +href="{@docRoot}tools/help/draw9patch.html">draw9patch</a> tool, or simply with a graphics editing program such as Adobe® Photoshop. This will allow the widget background shape to take up the entire available space. The nine-patch should be edge-to-edge with no transparent pixels providing extra margins, save for perhaps a few border pixels for <strong>subtle</strong> |