Have you ever downloaded an application’s source code, excited to get access to all that code, but found it overwhelming to navigate? You want to make your own changes, to put your own spin on the code, but you unzip the file into all the various subdirectories, and you don’t know where to start. Before we jump directly into exam- ining the source code, we need to pay attention to the architecture, in particular the flow from one screen to the next.
12.2.1 Mapping out the field service application
In this section, we’ll examine the application flow to better understand the relation among the application’s functionality, the UI, and the classes used to deliver this func- tionality. Doing this process up-front helps ensure that the application delivers the needed functionality and assists in defining which classes we require when it comes time to start coding (which is soon)! Figure 12.3 shows the relation between the high- level classes in the application, which are implemented as an Android Activity, as well as interaction with other services available in Android.
Here’s the procession of steps in the application:
1 The application is selected from the application launch screen on the Android device.
2 The application splash screen displays. Why? Some applications require setup time to get data structures initialized. As a practical matter, such time- consuming behavior is discouraged on a mobile device, but it’s an important aspect to application design, so we include it in this sample application.
MySQL
Distributed dispatchers
getjoblist.php
closejob.php
Dispatch functions WWW Server (Apache or IIS)
with PHP
Figure 12.2 The field service application and dispatchers both leverage server-side transactions.
3 The main screen displays the currently configured user and server settings, along with three easy-to-hit-with-your-finger buttons.
4 The Refresh Jobs button initiates a download procedure to fetch the currently available jobs for this mobile worker from the configured server. The download includes a ProgressDialog, which we discuss in section 12.3.5.
5 The Settings button brings up a screen that allows you to configure the user and server settings.
6 Selecting Manage Jobs lets our mobile worker review the available jobs assigned to him and proceed with further steps specific to a chosen job.
7 Selecting a job from the list of jobs on the Manage Jobs screen brings up the Show Job Details screen with the specific job information listed. This screen lists the available information about the job and presents three additional buttons.
8 The Map Job Location button initiates a geo query on the device using an Intent. The default handler for this Intent is the Maps application.
9 Because our mobile worker may not know much about the product he’s being asked to service, each job includes a product information URL. Clicking this button brings up the built-in browser and takes the mobile worker to a (hope- fully) helpful internet resource. This resource may be an online manual or an instructional video.
#1 #2
#3
#4 #6 #5
#7
#8 #9 #10 #11
#12
No
Yes
Application launch Splash screen #
(Splash Activity)
#4
Refresh jobs (RefreshJobs Activity)
#6
Manage jobs (ManageJobs Activity)
#5 Settings (ShowSettings Activity)
#8
Map job location (Launch Google Maps)
#9
Look up product info (Launch browser)
#11
Capture signature (CloseJob Activity)
#12
Display signature (Launch browser) Main screen #3
(FieldService Activity)
Show job details (ShowJob Activity)
#10
# No
Yes Job closed?
Figure 12.3 This figure depicts the basic flow of the field service application.
10 The behavior of the third button depends on the current status of the job. If the job is still marked OPEN, this button is used to initiate the closeout or com- pletion of this job.
11 When the close procedure is selected, the application presents an empty canvas upon which the customer can take the stylus (assuming a touch screen–capable Android device) and sign that the work is complete. A menu on that screen presents two options: Sign & Close and Cancel. If the user selects Sign & Close option, the application submits the signature as a JPEG image to the server, and the server marks the job as CLOSED. In addition, the local copy of the job is marked as CLOSED. The Cancel button causes the Show Job Details screen to be restored.
12 If the job being viewed has already been closed, the browser window is opened to a page displaying the previously captured signature.
Now that you have a feel for what the requirements are and how you’re going to tackle the problem from a functionality and application-flow perspective, let’s examine the code that delivers this functionality.
12.2.2 List of source files
The source code for this application consists of 12 Java source files, one of which is the R.java file, which you’ll recall is automatically generated based on the resources in the application. This section presents a quick introduction to each of these files. We won’t explain any code yet; we want you to know a bit about each file, and then it’ll be time to jump into the application, step by step. Table 12.1 lists the source files in the Android field service application.
Table 12.1 Source files used to implement the field service application
Source filename Description
Splash.java Activity provides splash screen functionality.
ShowSettings.java Activity provides management of the username and server URL address.
FieldService.java Activity provides the main screen of the application.
RefreshJobs.java Activity interacts with the server to obtain an updated list of jobs.
ManageJobs.java Activity provides access to the list of jobs.
ShowJob.java Activity provides detailed information on a specific job, such as an address lookup, or initiates the signature-capture process.
CloseJob.java Activity collects an electronic signature and interacts with the server to upload images and mark jobs as CLOSED.
R.java Automatically generated source file representing identifiers in the resources.
Prefs.java Helper class encapsulating SharedPreferences.
JobEntry.java Class that represents a job. Includes helpful methods used when passing JobEntry objects from one Activity to another.
The application also relies on layout resources to define the visual aspect of the UI. In addition to the layoutXML files, an image used by the SplashActivity is placed in the drawable subfolder of the res folder along with the stock Android icon image.
This icon is used for the home application launch screen. Figure 12.4 depicts the resources used in the application.
In an effort to make navigating the code as easy as possible, table 2.2 shows the field service application resource files. Note that each is clearly seen in figure 12.4, which is a screen- shot from our project open in Eclipse.
Examining the source files in this applica- tion tells us that we have more than one Activity in use. To enable navigation between one Activity and the next, our application must inform Android of the existence of these Activity classes. Recall from chapter 1 that this registration step is accomplished with the AndroidManifest.xml file.
JobList.java Class representing the complete list of JobEntry objects. Includes methods for marshaling and unmarshaling to nonvolatile storage.
JobListHandler.java Class used for parsing the XML document containing job data.
Table 12.2 Resource files used in the sample application
Filename Description
android.jpg Image used in the Splash Activity.
icon.jpg Image used in the application launcher.
fieldservice.xml Layout for the main application screen, FieldService Activity.
managejobs.xml Layout for the list of jobs, ManageJobs Activity.
refreshjobs.xml Layout for the screen shown when refreshing the job list, RefreshJobs Activity.
showjob.xml Layout for the job detail screen, ShowJob Activity.
showsettings.xml Layout for the configuration/settings screen, ShowSettings Activity. splash.xml Layout for the splash screen, Splash Activity.
strings.xml Strings file containing extracted strings. Ideally, all text is contained in a strings file for ease of localization. This application’s file contains only the application title.
Table 12.1 Source files used to implement the field service application (continued)
Source filename Description
Figure 12.4 Resource files used in the sample application
12.2.3 Field service application’s AndroidManifest.xml
Every Android application requires a manifest file to let Android properly “wire things up” when an Intent is handled and needs to be dispatched. Take a look at the AndroidManifest.xml file used by our application, shown in the following listing.
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.msi.manning.UnlockingAndroid">
<application android:icon="@drawable/icon">
<activity android:name=".Splash"
android:label="@string/app_name">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity android:name=".FieldService" >
</activity>
<activity android:name=".RefreshJobs" >
</activity>
<activity android:name=".ManageJobs" >
</activity>
<activity android:name=".ShowJob" >
</activity>
<activity android:name=".CloseJob" >
</activity>
<activity android:name=".ShowSettings" >
</activity>
</application>
<uses-sdk android:minSdkVersion="6"/>
<uses-permission android:name="android.permission.INTERNET">
</uses-permission>
</manifest>