Mark Murphy - Beginning Android

• bin/yourapp.ap_holds your application’s resources, packaged as a ZIP file (where yourappis the name of your application)

• bin/yourapp-debug.apkor bin/yourapp-unsigned.apkis the actual Android application (where yourappis the name of your application)

The .apkfile is a ZIP archive containing the .dexfile, the compiled edition of your resources ( resources.arsc), any un-compiled resources (such as what you put in res/raw/) and the AndroidManifest.xmlfile. It is also digitally signed, with the -debugportion of the filename indicating it has been signed using a debug key that works with the emulator, or -unsignedindicating that you built your application for release (ant release), but the APK still needs to be signed using jarsignerand an official key.

The foundation for any Android application is the manifest file: AndroidManifest.xmlin the root of your project. Here is where you declare what is inside your application — the activities, the services, and so on. You also indicate how these pieces attach themselves to the overall Android system; for example, you indicate which activity (or activities) should appear on the device’s main menu (aka the launcher).

When you create your application, you will get a starter manifest generated for you. For a simple application, offering a single activity and nothing else, the auto-generated manifest will probably work out fine, or perhaps require a few minor modifications. On the other end of the spectrum, the manifest file for the Android API demo suite is over 1,000 lines long. Your production Android applications will probably fall somewhere in the middle.

Most of the interesting bits of the manifest will be described in greater detail in the chapters on their associated Android features. For example, the serviceelement is described in greater detail in Chapter 30. For now, you just need to understand what the role of the manifest is and its general construction.

The root of all manifest files is, not surprisingly, a manifestelement:

package="com.commonsware.android.search">

...

Note the namespace declaration. Curiously, the generated manifests apply it only on the attributes, not the elements (e.g., it’s manifest, not android:manifest). However, that pattern works, so unless Android changes, stick with their pattern.

The biggest piece of information you need to supply on the manifest element is the packageattribute (also curiously not namespaced). Here you can provide the name of the Java package that will be considered the “base” of your application. Then, everywhere else in the manifest file that needs a class name, you can just substitute a leading dot as shorthand for the package. For example, if you needed to refer to com.commonsware.android.search.Snicklefritzin our example manifest, you could just use .Snicklefritzsince com.commonsware.android.searchis defined as the application’s package.

Underneath the manifest element, you will find the following:

• uses-permissionelements to indicate what permissions your application will need in order to function properly. See Chapter 29 for more details.

• permissionelements to declare permissions that activities or services might require other applications hold in order to use your application’s data or logic. Again, more details are forthcoming in Chapter 29.

• instrumentationelements to indicate code that should be invoked on key system events, such as starting up activities, for the purposes of logging or monitoring.

• uses-libraryelements to hook in optional Android components, such as mapping services

• Possibly a uses-sdkelement to indicate what version of the Android SDK the application was built for.

• An applicationelement defining the guts of the application that the manifest describes.

In the following example the manifest has uses-permission elements to indicate some device capabilities the application will need — in this case, permissions to allow the application to determine its current location. And there is the application element, whose contents will describe the activities, services, and whatnot that make up the bulk of the application itself.

package="com.commonsware.android">

android:name="android.permission.ACCESS_LOCATION" />

android:name="android.permission.ACCESS_GPS" />

android:name="android.permission.ACCESS_ASSISTED_GPS" />

android:name="android.permission.ACCESS_CELL_ID" />

...

The real meat of the manifest file is the children of the applicationelement.

By default, when you create a new Android project, you get a single activityelement:

package="com.commonsware.android.skeleton">

This element supplies android:namefor the class implementing the activity, android:labelfor the display name of the activity, and (frequently) an intent-filterchild element describing under what conditions this activity will be displayed. The stock activityelement sets up your activity to appear in the launcher, so users can choose to run it. As you’ll see later in this book, you can have several activities in one project if you so choose.

You may also have one or more receiver elements indicating non-activities that should be triggered under certain conditions, such as when an SMS message comes in. These are called intent receivers and are described in Chapter 23.

You may have one or more provider elements indicating content providers — components that supply data to your activities and, with your permission, other activities in other applications on the device. These wrap up databases or other data stores into a single API that any application can use. Later you’ll see how to create content providers and how to use content providers that you or others create.

Finally, you may have one or more service elements describing services — long-running pieces of code that can operate independent of any activity. The quintessential example is the MP3 player, where you want the music to keep playing even if the user pops open other activities and the MP3 player’s user interface is “misplaced.” Chapters 30 and 31 cover how to create and use services.

Android, like most operating systems, goes through various revisions, versions, and changes. Some of these affect the Android SDK, meaning there are new classes, methods, or parameters you can use that you could not in previous versions of the SDK.

If you want to ensure your application is run only on devices that have a certain version (or higher) of the Android environment, you will want to add a uses-sdk element as a child of the root manifestelement in your AndroidManifest.xmlfile. The uses-sdkelement has one attribute, minSdkVersion, indicating which SDK version your application requires:

package="com.commonsware.android.search">