Java Device Test Suite Developer’s Guide Table Of ContentsPrevious ChapterNext ChapterBook Index

C H A P T E R  11
Developing an Over-the-Air Test Package

This chapter describes how to create an over-the-air (OTA) provisioning test package. It contains the following sections:

Test pack development is an iterative, non-linear process that varies according to local practices and preferences. As you read the following sections, remember that when developing tests you might perform some steps many times, and you might perform the steps in a different sequence than they are described in this chapter. You might also choose to build and test your developing test pack more frequently than this chapter suggests. If you use a source code control system, you might have to modify some instructions, such as “make the file writable.”

OTA Test Pack Development

OTA test pack development is quite different from runtime or benchmark test pack development. OTA test source files are essentially empty except for Javadoc tool class and case documentation and other markup (see Chapter 4). The Java Device Test Suite provides all OTA test code, which is driven by properties you specify. The test code does not run on a test device. It runs on the Relay.

In OTA tests, the Relay acts as a provisioning server. It performs these services:

Each test has at least one associated MIDlet that the user downloads to the test device. You write these test MIDlets.

Program logic is different in OTA tests compared to other test types (where the test logic runs predominately within the test device). In OTA tests, the program logic is an interplay between the following.

1. The test MIDlet, installed successfully (or not) onto the test device, and executed in the device.

2. The installation procedure. The tester reads test instructions and interacts with the test device and the MIDlet.

3. The AMS, a part of the test device that manages the installation and launching of the MIDlet. For example, the AMS sends an installation status report to the relay after MIDlet installation.

To develop an OTA test pack, you must also know how to modify Ant build scripts.


Note - Compared to earlier releases of JDTS, OTA test development is different after JDTS version 2.0. However tests, written for earlier releases can run on a 2.0 harness with minor modifications. Follow the instructions in this chapter to develop new OTA tests after JDTS version 2.0.

Writing an OTA Test

An OTA test has two sets of files:

See the property MIDletSourcesDir in the file devKitHome/ota/testsuite.info for an example of good paths to MIDlet source files. It is important to structure the paths to avoid namespace conflicts, and this is reflected in the directory structure of the OTA examples.

You can create the file sets in any order. This section describes how to write the files in a test package. Writing Application Files describes how to write application files.

Writing OTA Source Files

An OTA test source file is only a container for online test documentation and properties. It has no executable statements. The OTA servlet and, for some tests, the associated test MIDlet, do the work of the test. For a sample interactive test, see devKitHome/tests/ota/src/client/com/sun/samples/interactive/Interactive.java. Interactive and semi-automated test source files have the same format.

Security Certificates for a Test Class

Tests that use protected APIs must be granted permission to call methods in those interfaces. This is done by digital certificates in the test device which are associated with protection domains.

OTA test developers must specify the protection domain for the users of applications that use protected APIs. The available domains are specified in the MIDP specification.

Use the following syntax in a source file comment (see Test Class and Case Comment Blocks) to make a domain available to testers:

* @card.property SecurityDomain=DomainID

The SecurityDomain property value is the domain name (DomainID).

The DomainID is one of four OTA pre-defined domains or a custom domain (described later in this section):

For example: 

* @card.property SecurityDomain=ThirdPartyTrusted

The preceding example means the OTA MIDlet packs associated with this test case are signed with a key setup user interface (using the Manage Keystores command and corresponding Configuration Editor pane) for the specified protection domain, so that the MIDlet suite are associated with this protection domain in the device where the MIDlet is installed.

In addition to the pre-defined domains previously mentioned, you can create custom domains. Custom domains map to specific certificates in their respective keystores. Custom domains as well as the default domains must be made apparent to the tester. The tester enters the domains in the harness Configuration Editor in the left pane under Over The Air Test MIDlets. Custom domain names have the following restrictions:

For more information about protection domains, certificates, and keystores, see the Java Device Test Suite Test Notes and the administrator harness online help.

Writing Application Files

Every OTA test case has an associated application (MIDlet, technically a MIDlet suite). The test case’s evaluation file typically instructs the user to download the associated MIDlet to the test device.

Directory Structure

FIGURE 11-1 shows, on the left, a directory containing one test class that has two test cases. On the right, the figure shows the application files you must create for this example in which both test cases use the same application (MIDlet.java).

FIGURE 11-1 Test and Application File Correspondence


Test and Application File Correspondence

An application source file is a MIDlet, as defined by the MIDP 1.0 and 2.0 specifications. For an example used with an interactive OTA test, see devKitHome/tests/ota/src/apps/samples/interactive/PropExample.java. Multiple tests can use the same application if their source file comments name the shared application’s JAD file and JAR file (which are created by the build script). If a test requires its associated application to perform an operation on the test device, make sure that the application displays information that tells the user to click Passed or Failed in the evaluation window, and that the evaluation window instructs the user to launch the application.

In the same directory as the application, create a build.xml file. This file is application specific. See the samples in the subdirectories of devKitHome/tests/ota/src/apps/samples/ for examples. By default, all MIDlet JAD and JAR files are created in the directory specified by TestMIDletDir. You can have a MIDlet’s JAD file and JAR file created in a subdirectory by specifying a value for subDir in the following build.xml line: 

<mkdir dir=”${MIDlet.dest.dir}/subDir”/>

Correspondingly, add subDir to all build.xml lines that contain MIDlet.dest.dir.

The @card.property tags in the source file must name the same directory. Here is a hypothetical example line from a build.xml file: 

<mkdir dir=”${MIDlet.dest.dir}/mySubDir”/>

The corresponding source file lines are as follows: 

* @card.property=JADPath1=mySubDir/TestMIDletJADFile.jad
* @card.property=JARPath1=mySubDir/TestMIDletJARFile.jar

In the same directory as the application, create a manifest file named manifest. The MIDP 1.0 and MIDP 2.0 specifications define the manifest file format and contents. See devKitHome/tests/ota/src/apps/samples/interactive/color/manifest for an example.

For MIDlets that use protected APIs, code the permission requests in the MIDlet JAD file and JAR file manifest. To see how these files are built, inspect devKitHome/tests/ota/src/apps/samples/signed/build.xml.

Application Logging

An application can send timestamped log messages by HTTP. In the test results, these messages are identical to those that runtime tests can create as described in Logging. To generate a log message, add the following line to the application’s JAD file: 

logurl: ${URL_SIMPLE_LOG_RECEIVER}

CODE EXAMPLE 11-1 shows how to send a log message to the Relay. The class JdtsLogLevel defines the available log level constants, such as TRACE and DEBUG.


CODE EXAMPLE 11-1 Sending a Log Message 
...
String logUrl = getAppProperty("logurl");
Connection c = Connector.open(logUrl+"&LogLevel="+myMessageLevel);
HttpConnection hc = (HttpConnection)c;
hc.setRequestMethod(HttpConnection.POST);
OutputStream os = hc.openOutputStream();
os.write(myLogMessage.getBytes("UTF-8"));
os.flush();
os.close();
...

Additional Facilities for Interactive OTA Tests

The example in devKitHome/tests/ota/src/client/com/sun/samples/interactive/Interactive.java has test cases that illustrate several optional features of the interactive OTA test infrastructure:

 

ing HTML relocated fro