Intel AppUpSM Java* Developer Guide

Contents:

• About This Document• Overview• Getting Started with Applications• Advanced Information • Developing Components• Using the Packaging Utility• Using the Package Validation Utility• Disclaimers and Legal Information

About This Document

This document is for developers getting started with the Intel AppUpTM Software Development Kit (SDK) for Java software SE 1.6 (or later) environments. The SDK includes programming libraries, documentation, and sample code to help developers create, test, and submit Java* applications and components intended fordistribution via the Intel AppUpSM center.

Intended Audience

This document is intended for experienced software developers who are developing applications and components for the Intel AppUp center, using Java. These can be new applications/components or existing applications/components being ported for the Intel AppUp center.

Using this Developer Guide

This developer guide contains the following sections:

• About this Document: introduces the contents and conventions of this document.

• Overview: introduces the Intel AppUpSM Developer Program, this SDK, and the general application/component development flow.

• Getting Started: provides the minimum steps for getting an existing Java SE 1.6 (or later) application ready to submit to the Intel AppUp developer program portal.

• Advanced Information: describes how to integrate the additional capabilities of the SDK library to build a more robust application that provides a better experience for users, and/or provides better usage feedback to developers.

• Developing Components: describes how to develop software components designed to be included in applications, and how to combine components and applications.

• Using the Packaging Utility: describes how to use the Intel AppUpTM Software Packaging Utility to create a single runnable jar file for submission to the Intel AppUp developer program portal.

• Using the Package Validation Utility: describes how to use the Intel AppUpTM Software Package Validation utility to pre-validate runnable jar file packages prior to submission to the Intel AppUp

developer program portal.

Conventions and Symbols

The following table shows the conventions used in this document.[FIGURE A]

Download the

AppUp Java SDK & SDK Plug-in

for Eclipse* Software

Intel AppUpSM developer program

Provides developers with

everything they need to create and

sell their apps to users of millions of

Intel® Atom™ processor-based devices.

Intel AppUpSM developer programPart of the Intel® Software Network

1

Published also at:http://appdeveloper.intel.com/en-us/article/intel-appup-software-development-kit-developer-guide-java-software

Related Information

Reference information for the Java SDK is provided in the Intel AppUpTM Software Development Kit API Reference for Java software document, which is located on the Intel AppUpSM developer program portal.

Overview

This section provides an overview of the following:

• About this Document: introduces the contents and conventions of this document.

• SDK Contents

• Application/Component Development Flow

Intel AppUp Developer Program

The Intel AppUp developer program provides developers with everything they need to create and then sell their applications/components to end users of Intel® AtomTM processor-based devices (netbooks, smartphones, and pads) through the Intel AppUp center. This allows you to earn money for your development efforts. Figure B shows a high-level view of how developers, Intel, and consumers interact.

The following paragraphs summarize this interaction:

• Developers prepare their applications/components for submission to the Intel AppUp developer program portal using existing tools and Intel-provided SDK

libraries, plug-ins, documentation, and support.

• Intel validates submitted applications/components and, when they are ready, publishes them in the Intel AppUp center for consumers.

• Consumers purchase (or download) published applications from the Intel AppUpSM center (delivery backend) and run them on their client platforms. Developers typically purchase (or download) components to include in the applications they develop.

• Information on downloads, usage, and ratings is provided to developers via the Intel AppUp developer program

dashboard (business back-end). The dashboard also displays payment information.

For more information on how the program works, including details on how payment is handled, visit the program portal at http://appdeveloper.intel.com.

SDK Contents

The Intel AppUpTM SDK for Java software includes the following major elements:

• Intel AppUpTM Software Libraries for Java SE 1.6 (or later)

• Tools such as the Intel AppUp Software Debugger to aid development

• Code examples to aid in the development of applications and components

• Documentation to show you how to incorporate the appropriate API calls into your applications/components

Figure C Shows the different elements of the SDK.

SDK Libraries

SDK libraries provide you with access to the Intel AppUp center Consumer Client for services such as Authorization, Error Handling, Instrumentation (metering), and Crash Reporting. Functionality will

This type style Indicates an element of syntax, reserved word, keyword, filename, computer output, or part of a program example. The text appears in lowercase unless uppercase is signifi-cant.

This type style Indicates the exact characters you type as input. Also used to highlight the elements of a graphical user interface such as buttons and menu names or filenames and labels when discussing program examples.

Hyperlink Indicates a hyperlink to internal or external information. Use CNTL+mouse click to navigate.

Notes, cautions, etc. Note: Indicates an important comment or side topic for the user.

[FIGURE A]

[FIGURE B]

Intel AppUpSM developer programPart of the Intel® Software Network

2

INTEL APPUP DEVELOPER PROGRAM—GETTING STARTED

In the Getting Started Guide you’ll find tools and tips to start developing your apps for the Intel AppUpSM center.

• Developer Guidelines

• Validation Process

• Submitting an Application

• Developer Challenge

• Porting to AppUp – Resources & Guides

increase over time with new library releases, as appropriate for each language and runtime.

SDK libraries are the only parts of the SDK that are redistributed with applications/components. There will be separate implementations of the library for each supported runtime and, in the case of native applications, for each supported operating system.

Intel AppUpTM Software Debugger

The Intel AppUp Software Debugger is a utility that emulates the Application Services of the Intel AppUpSM center Consumer Client. The Intel AppUp Software Debugger allows you to test and debug your application/component without requiring the full client stack or access to hardware.

Documentation

Three types of documentation are provided to help you develop applications/ components for the Intel AppUp developer program:

1. Sample code

2. Developer Guide (this document)

3. Online API Reference for a specific language/API.

Development Process Integration

Developer Process Integration allows you to quickly insert SDK library code into your existing applications, integrate the Intel AppUp Software Debugger into your debug flow, etc., from within your IDE. The Intel AppUpTM SDK Plug-in 1.1 for Eclipse software provides development process integration for Java.

Developer Portal Integration

Developer Portal Integration allows you to interact with the Intel AppUp developer program portal to view your Dashboard, interact with Developer Resources, etc., from within your IDE. The Intel AppUp SDK Plug-in 1.1 for Eclipse software provides development portal integration for Java.

Packaging Integration

Packaging Integration allows you to integrate and package application/component jar files, SDK library jar files and manifest into a single jar file for upload to the Intel AppUp developer program portal. The Intel AppUpTM Software Packaging Utility creates this single runnable jar file for submission to the Intel AppUp developer program portal.

Developer Platform

[FIGURE C]

Intel AppUpSM developer programPart of the Intel® Software Network

3

Validation Integration

Validation Integration allows you to determine whether or not an existing jar file complies with the requirements of the Intel AppUpTM Runnable Jar File Format. The Intel AppUpTM Software Package Utility analyzes runnable jar files to help determine this compliance prior to submission to the Intel AppUp developer program portal.

Development Flow

The figure below illustrates the high-level development flow for Intel AppUp developer program applications. The steps in this flow are as follows:

• Join the Intel AppUp developer program, by creating an account on the Intel AppUp developer program portal and then joining the program.

• Download the Intel AppUpTM SDK (Software Development Kit) for your target application/component development languages and runtime. In some cases, an IDE Plug-in package is available for an Integrated Development Environment to ease the development process. (It is important to keep your SDK up-to-date with periodic refreshes from the Intel AppUp developer program portal.)

• Insert the minimum SDK code into your existing application/component, as appropriate. This will always include the authorization code. For some languages, it may also include header, exception handling, and cleanup code or references

• Perform initial testing with the Intel AppUp Software Debugger to make sure the authorization code is working properly.

• Flesh out your existing application/component with other SDK code, as appropriate. You should consider advanced Error Handling, Instrumentation, and custom Crash Reporting. It is not required that you address these areas, but they can help your application/component provide a better user experience. In some cases,

[FIGURE D]

Intel AppUpSM developer programPart of the Intel® Software Network

4

they can provide you with more insight into usage of your application/component. Some languages/runtimes do not support all of the SDK capabilities..

• Perform additional testing with the Intel AppUp Software Debugger to make sure any additional SDK code is working properly.

• Replace the Debug GUID with a Production GUID. You must obtain the Production GUID from the Intel AppUp

developer program portal.

• Package your application/component into a jar file that meets Intel’s guidelines for runnable Java applications. Getting Started with Application provides more information on this topic. Details on the Intel AppUp Software Packaging Utility are provided in Using the Packaging Utility.

• Pre-Validate as much of the application/component as possible. Pre-validation can help smooth validation by Intel. Getting Started with Application provides more information on this topic. Details on the Intel AppUp Software Package Validation Utility are provided in Using the Validtion Utility.

• Submit your final installation package to the Intel AppUp developer program portal for validation by Intel.

Getting Started with Applications

This section describes the basic steps to get a Java application ready for the Intel AppUp developer program portal. The steps are described using the sample program AdpBasicSample.

Component development is covered in Developing Components.

AdpBasicSample in Java

The AdpBasicSample sample application is a minimal Java application that incorporates Intel AppUpTM SDK authorization code and code to demonstrate Crash Reporting. (AdpBasicSample is installed with the SDK and is located in the …Java/Samples folder.) Advanced Error Handling is not

included in the sample, but you should consider it for an actual application. The Crash Reporting code in the sample is not required either, and is not discussed in this section.

Assume that you have a working application like the sample, but that it does not have Intel AppUpTM SDK code included. Assume also that you have already installed the SDK. The following steps describe how to integrate Intel AppUpTM SDK code into the application:

Step 1: Add SDK Library to the Build Path

You must add the SDK library to Java Classpath. In Eclipse, use the Build Path item on the Project menu to add appupp_sdk_java_v1.1.jar to the project. (Or right click on the selected Project and use Build Path>Configure Build Path to open the Properties. Select the Libraries tab and click on Add External jars … to add the library to the Project). Browse to the directory where the SDK is installed.

Step 2: Insert SDK Authorization Code Using Authorized Debug ID

Locate the code that initializes the application and insert the SDK authorization code. The SDK authorization code is shown in the sample in step 3. The authorization code includes the Application Constructor call, which performs initialization and authorization, and catches exceptions. The application is derived from a core Application class. Only one instance of the Application class may exist in an application. (The Intel AppUp SDK Plug-in 1.1 for Eclipse* software can insert this code automatically.)

Note: A system is authorized to run an application if the application was purchased by the user on the current system or if the system is one of the five systems allowed by the licensing system. As the application developer, you are responsible for ensuring that the current system has a license to use your application; the OS or runtime does not enforce this automatically.

Note that an Authorized Application Debug ID is used. During development,

this Debug ID allows testing with the Intel AppUp Software Debugger. This Debug ID is a 128-bit number, expressed as a string using predefined constants. The value of the Debug ID is contained in the SDK library. You can also use the absolute value (all one’s). You must replace the Debug ID with a Production ID after testing. (The Production ID is discussed in detail later in this section.) There is also an Expired Application Debug ID to allow you to test the “expired” branch of your application.

Step 3: Insert SDK Shutdown Code

Locate the code that shuts down the application and insert the SDK shutdown code. The SDK shutdown code is shown in the sample below. The shutdown code performs SDK library shutdown. (The Intel AppUp SDK Plug-in 1.1 for Eclipse* software can insert this code automatically.)

public AdpHelloWorldWindow()

{

/// <ADP>

try {

com.intel.adp.Application app = new com.intel.adp.Application

(com.intel.adp.AdpConstants.ADP_DEBUG_APPLICATIONID) ;

}

catch( AdpErrorException e) {

e.printStackTrace();

}

finally {

if (app != null)

app.dispose();

}

/// </ADP>

}

Note: The library reference, authorization, and shutdown code described above are the only mandatory work to get a Java

Intel AppUpSM developer programPart of the Intel® Software Network

5

application running initially. Advanced Error Handling, Instrumentation, and Crash Reporting are not discussed here, but you should consider them for actual applications. Those topics are all covered in Advanced Information.

Step 4: Test Application with Intel AppUpTM Software Debugger

The SDK includes the Intel AppUp Software Debugger that emulates the Application Services of the Intel AppUp center Consumer Client on your system, without requiring the full client or access to hardware. The Intel AppUp Software Debugger allows testing of authorization, error handling, instrumentation, and crash reporting.

With the Intel AppUp SDK Plug-in 1.1 for Eclipse 3.5.2 installed and the Intel AppUpTM SDK code included, you can use the Eclipse debugger and Intel AppUpTM Software Debugger to debug your application. Intel AppUp Software Debugger trace information is included in the Intel AppUp Software Debugger window.

To start debugging, first start the Intel AppUp Software Debugger using one of the following methods:

• Intel AppUp Software Debugger Start icon in Eclipse

• Intel AppUp Software Debugger Start item from the Eclipse menu

Then start the Eclipse debugger using one of the following methods:

• Eclipse Start Debugger icon

• F11 key

• Eclipse Start Debugger menu item

This allows you to examine trace information. Then, stop the Intel AppUp Software Debugger using one of the following methods:

• Intel AppUp Software Debugger Stop icon in Eclipse

• Intel AppUp Software Debugger Stop item from the Eclipse menu

Step 5: Get and Swap in a Production ID

Once your application is working, you must replace the Authorized Application Debug ID with an Authorized Production Application ID before you can submit the application to the Intel AppUp developer program portal. Production IDs are obtained from the Intel AppUp developer Program portal, which requires that you enroll in the Intel AppUp developer Program. The Production ID is a 128-bit number organized as four integers in hex format. The following example shows part of the authorization code with a Production ID included.

Assume you are enrolled in the Intel AppUp developer program and have logged into the program portal. Start the application submission process and provide information that uniquely identifies your application. After entering that information, click on the Get a GUID button on the portal. The site displays a GUID, which is a Production ID. You can copy and paste this Production ID into your application, replacing the Debug ID. (You can also request that the portal email a Production ID to you.)

com.intel.adp.Application app = new com.intel.adp.Application(new

com.intel.adp.ApplicationId(0x12341234,0x56785678,0x12341234,0x56785678));

Note: While the Production ID is used, you can no longer use the Intel AppUp Software Debugger for normal testing and debugging. (The Application Constructor call will always return an ADP_NOT_AUTHORIZED error.) You can always return to using the Debug ID to perform broader testing and debugging using the Intel AppUp Software Debugger.

You can obtain a Production ID as early in your development cycle as you wish. Since submitting the name for an application is required to receive a Production ID, getting a Production ID early increases your chances that your desired application name will still be available.

Step 6: Create an Installation Package

Create a single JAR file that includes the Intel AppUpTM SDK library jar file, application jar file(s), and an application manifest file. The Intel AppUp Software Packaging Utility can help create these Java runnable jar packages. See Using the Packaging Utility, for information on using this utility. For general information on packaging requirements, refer to http://appdeveloper.intel.com/en-us/article/packaging-requirements.

Step 7: Pre-Validate the Installation Package

Intel validates application packages submitted to the Intel AppUp developer program portal prior to publishing them on the Intel AppUpSM center. You should become familiar with the validation process so you can pre-validate as many of the items as possible yourself prior to submission. This helps to smooth the approval process for your application. The Intel AppUp Software Package Validation Utility can help validate Java runnable jar packages. See Using the Validation Utility, for information on using this utility. For more information on the validation process, refer to http://appdeveloper.intel.com/en-us/article/troubleshooting-validation-failures.

Step 8: Submit the Application

Submit your application package by following the steps on the Intel AppUp

Developer Program portal. You can then monitor status of the application via the My Dashboard page on the portal. Alternately, with the Intel AppUpTM SDK Plug-in for Eclipse* software installed, you can use the Dashboard feature to monitor status.

Advanced Information

This section provides advanced information on the following topics:

• API Levels

• Advanced Error Handling

• Instrumentation

Intel AppUpSM developer programPart of the Intel® Software Network

6

• Crash Reporting

• Using the Intel AppUp Software Debugger

API Levels

The Intel AppUpTM SDK library provides a mechanism to determine compatibility of the API level of applications versus the API level of client systems.

Applications with API levels higher than that supported by the client system are not permitted to be downloaded to the client. If the API level on a client system is rolled back to a lower API level, applications with higher API levels already installed on the client system are not permitted to run. An Intel AppUp center Consumer Client can concurrently support applications with different API levels.

API level information for an application is displayed in the Intel AppUp Software Debugger output, as shown in the Figure F. This information can be useful when debugging potential issues.

Exception Handling

Exception handling in the AdpBasicSample program can be expanded to provide more robust handling of error and warning exceptions.

The Java SDK library includes includes three pre-defined exception classes for errors and one pre-defined exception class for warnings to provide greater granularity in exception handling. You should consider using these classes to provide more robust exception handling for your application. The exception classes are as follows:

Error Exception Classes

• InitializationException—Catches error exceptions thrown while the SDK library application constructor attempts to initialize the SDK library code. This class is derived from AdpErrorException.

• UnauthorizedException—Catches error exceptions thrown while the SDK library code attempts to authorize the application. This class is

derived from AdpErrorException.

• AdpRuntimeException—Catches general runtime error exceptions while executing SDK library code. This class is derived from AdpErrorException.

Warning Exception Class

• AdpWarningException—Catches warning exceptions while executing SDK library code.

AdpErrorException and AdpWarningException are both derived from the same base class, AdpException. (AdpErrorException was used in the sample in Getting Started with Applications, but it is recommended that the more granular classes be used in actual applications.)

Note: Most testing is done with the ADP_DEBUG_APPLICATIONID GUID, which is the Authorized Application ID. You can change the GUID to the ADP_EXPIRED_APPLICATIONID to test the application “expired” branch of your error handler.

For exceptions that are not possible to handle in your application, the recommended approach is to re-throw the exception. (The method to re-throw the exception depends on the application language and context.) The integrated crash handler in the SDK library then catches the exception and generates a Crash Report using the context information from the exception. See the Crash Reporting subsection for details on Crash Reporting.

Code Sample

The Java code sample below includes a catch for each of the SDK library exception classes and the original default exception handler. Note that you can change the GUID to the ADP_EXPIRED_APPLICATIONID to test the application “expired” branch of your error handler.

Application app = null;

try {

[FIGURE E]

Intel AppUpSM developer programPart of the Intel® Software Network

7

app = new Application (AdpConstants.ADP_DEBUG_APPLICATIONID);

}

catch (InitializationException e) {

// TODO Add your logic to handle initialization errors

e.printStackTrace();

}

catch (UnauthorizedException e) {

// TODO Add your logic to handle authorization errors

e.printStackTrace();

}

catch (AdpRuntimeException e) {

// TODO Add your logic to handle runtime errors

e.printStackTrace();

}

End-User Error Messages

The SDK contains error message strings that can be retrieved by applications

and displayed to end users. These messages are accessed via their unique Message ID. They do not map directly to the Return/Error Codes.

Instrumentation

The Intel AppUp developer program portal allows you to collect usage statistics for your applications. The Intel AppUp center aggregates this information and passes it to My Dashboard on the Intel AppUp developer program portal. If the application is offline, the information is cached and sent later when the application is online.

Note: The final decision on whether to gather and send this information to the Intel AppUp center lies with the end user. They must explicitly agree to the collection and transmittal of this usage data. If they say no, this data is discarded. Your application must support this explicit end-user opt-in choice. Even if they say yes, no individual user or machine identifying information is collected; all data is aggregated.

The SDK supports the following Instrumentation events to measure

application usage:

• Application Begin Event—Triggers sending a Begin Event message to the Intel AppUp center for the application.

• Application End Event—Triggers sending an End Event message to the Intel AppUp center for the application.

The combination of a beginEvent call followed (eventually) by an endEvent call results in an application usage record being generated. A beginEvent call with no endEvent call results in no application usage record being generated. The following subsections show how to use beginEvent and endEvent for Java.

Code Sample

The Application Constructor call below includes a beginEvent call to trigger a Begin Event message. The Application Constructor call uses a Debug ID. The code immediately after the calls is the Exception handler for both calls.

Application app = null;

try {

app = new Application(AdpConstants.ADP_DEBUG_APPLICATIONID);

app.beginEvent();

}

catch (AdpErrorException e) {

System.out.println(“Exception occured - “ + e.getMessage());

}

The call can also be made with a Production ID, as follows:

Application app = null;

try {

app = new Application(ApplicationId.fromString

(“2CA9A3A1-5428-44B3-8AA6-B6CE19228561”));

app.beginEvent();

}

[FIGURE F]

Intel AppUpSM developer programPart of the Intel® Software Network

8

catch(AdpErrorException e){

System.out.println(“Exception occured - “ + e.getMessage());

}

Insert an endEvent call in the source code where you wish to stop usage measurement, as shown below. The code triggers an End Event message and includes an Exception handler for AdpWarningException and AdpRuntimeException. (Using an endEvent call with no prior beginEvent call results in a warning Exception.)

try {

app.endEvent();

}

Catch(AdpWarningException e) {

System.out.println(“Exception occured - “ + e.getMessage());

}

Catch(AdpRuntimeException e) {

System.out.println(“Exception occured - “ + e.getMessage());

}

Crash Reporting

Even when you follow best practices with respect to error handling, applications sometimes encounter unexpected situations and crash. To facilitate debug in these situations, the Intel AppUpTM SDK library supports Crash Reporting to provide a snapshot of the state of the application when it does crash.

Default crash reports are automatically enabled when the Application Constructor runs; you do not have to explicitly enable this. (Customized Crash Reporting is covered at the end of this subsection.)

When a crash occurs, crash information is first stored locally on disk. Then a process wakes up to create and send the crash report to the Intel AppUp developer program portal. The crash information stored on disk is a subset of the report sent to the Intel AppUp developer program portal. When the process runs, the process adds information to what is stored on disk to create the final report. This process also periodically sweeps the crash reporting area, looking for unsent crash reports.

Note: Since the stability of the system cannot be assumed, there is no

guarantee that a crash report will be generated. To maximize the success of Crash Reporting, the SDK library attempts to write crash information to disk first and limits the amount of information in the report. When implementing custom Crash Reporting, you should also follow this policy by keeping your custom report fields and logic to a minimum.

Note: Crash reports are intended only for application crashes. They are not intended as an error logging vehicle. Abuses will be monitored.

For default Crash Reporting, all information in the report is pre-defined by the SDK library code. If you desire additional or different information than provided in the default crash report, you must implement custom Crash Reporting, which is covered at the end of this subsection. The method to implement custom Crash Reporting automatically disables default Crash Reporting.

Default Crash Report

Default crash reports are viewable via My Dashboard on the Intel AppUp developer program portal. Figure H shows a default crash report from My Dashboard on the portal. This information includes application context information, runtime environment information, SDK identification information, and a core stack dump. The complete report can be viewed by clicking on the Details link for a specific report.

Customizing Crash Reports

Customized Crash Reporting allows you to provide different/additional information than default Crash Reporting. Custom crash reports are set immediately after the SDK Application Constructor call so that crash reports can include data as early in application execution as is reasonable possible. When a customized crash report is set in an application, default crash reporting is automatically disabled.

[FIGURE G]

Intel AppUpSM developer programPart of the Intel® Software Network

9

Customized Crash Reporting requires additional work on the part of the developer, and an understanding of the choices available. The following subsections introduce the SDK crash report classes and provide information to help you make your choices.

AbstractCrashReport

AbstractCrashReport is an abstract class with virtual methods that are designed to populate data existing within the class. Since the system may be at an unstable state, allocation of data on the stack is to be avoided, if possible. These methods will be called by the underlying framework to collect data to be submitted in crash reports. By implementing a subclass of AbstractCrashReport, you can gain control of every field that will be returned during the crash reporting process. However, you are also required to implement every field. (Information on the use of the AbstractCrashReport class is provided the Intel AppUp Software Development Kit API Reference for Java* software document, which is located on the Intel AppUp

developer program portal.

DefaultCrashReport

The DefaultCrashReport class is a reference implementation of the AbstractCrashReport class and is the class that provides default crash reports. This default implementation performs best-effort collection of data that should be appropriate and accurate in most cases. However, you may subclass DefaultCrashReport to customize one or more fields. An example of a custom crash report derived from DefaultCrashReport is provided later in this section.

Customizing Crash Reports Fields

The following table lists the possible fields in a crash report, with the Source

column defining the source (SDK or Developer) of the information for the respective field.

Note: It is your responsibility to ensure that custom Crash Reports do not include any data that violates Intel Privacy rules. See http://appdeveloper.intel.com for details.

The fields with the greatest flexibility for customization are listed below:

• The Category field allows you to create categories to sort your crash reports on the Intel AppUp developer program portal. For example, you may wish to create categories called “MEMORY”, “IO”, “USER ERROR”, etc.

• The Error Data field allows you to create your own stack dumps or long error messages to help you understand why your application crashed.

Note: Some crashes can lead to a client system eventually halting. In these cases, the time to store a crash report on the client system may be limited. To maximize obtaining crash information, you should consider the tradeoffs between the amount of information to include in a custom crash report versus a potentially narrow window of time to store the information on the client system.

Defining and Calling Custom Crash Reports

The following example shows the framework to define and call a custom crash report for Java. The contents of a custom crash report are defined by the developer in MyExceptionHandler. (Implementation of custom Crash Reporting automatically disables default Crash Reporting.)

[FIGURE H]

Intel AppUpSM developer programPart of the Intel® Software Network

10

import java.lang.thread.*;

import com.intel.adp.*;

public class CustomizeCrashReportSample {

/**

* @param args

*/

public static void main(String[] args) {

Application app = null;

try {

app = new Application(AdpConstants.ADP_DEBUG_

APPLICATIONID);

app.setCrashReport(new MyExceptionHandler());

}

catch (AdpErrorException e) {

e.printStackTrace();

System.exit(1);

}

if(app != null) {

throw new Exception(“Something bad happened! But this is

expected.”);

}

System.exit(0);

}

class MyExceptionHandler extends DefaultCrashReport{

@Override

protected void populateCategory() {

this.errorCategory = “My Error Category”;

}

@Override

protected void populateCrashReportFields() {

this.crashReportFields = new AdpCrashReportField[1];

this.crashReportFields[0] = new AdpCrashReportField(“Sub_

Category”,

“Trapped Error”);

}

@Override

protected void populateErrorData() {

// TODO Auto-generated method stub

super.populateErrorData();

}

@Override

protected void populateLineNumber() {

// TODO Auto-generated method stub

super.populateLineNumber();

}

@Override

protected void populateMessage() {

// TODO Auto-generated method stub

this.errorMessage = “User of illegal method”;

}

@Override

protected void populateModuleName() {

// TODO Auto-generated method stub

super.populateModuleName();

}

}

}

class MyExceptionHandler extends DefaultCrashReport{

@Override

protected void populateCategory() {

this.errorCategory = “My Error Category”;

}

@Override

protected void populateCrashReportFields() {

this.crashReportFields = new AdpCrashReportField[1];

this.crashReportFields[0] = new AdpCrashReportField

(“Sub_Category”,

“Trapped Error”);

}

@Override

protected void populateErrorData() {

// TODO Auto-generated method stub

super.populateErrorData();

}

@Override

protected void populateLineNumber() {

// TODO Auto-generated method stub

super.populateLineNumber();

}

@Override

protected void populateMessage() {

// TODO Auto-generated method stub

this.errorMessage = “User of illegal method”;

}

@Override

protected void populateModuleName() {

// TODO Auto-generated method stub

super.populateModuleName();

}

}

Intel AppUpSM developer programPart of the Intel® Software Network

11

Using the Intel AppUp Software Debugger

The SDK includes the Intel Intel AppUp Software Debugger that emulates the Application Services of the Intel AppUp center Consumer Client on your system, without requiring the full client or access to hardware. The Intel AppUpTM Software Debugger allows testing of authorization, error handling, instrumentation, and crash reporting.

With the Intel AppUpTM SDK Plug-in for Eclipse software installed and the Intel AppUpTM SDK code included, you can use the Eclipse debugger and Intel AppUpTM Software Debugger to debug your application. Intel AppUpTM Software Debugger trace information is included in the Intel AppUpTM Software Debugger window.

To start debugging, first start the Intel AppUpTM Software Debugger using one of the following methods:

• Eclipse Start Debugger icon

• F11 key

• Eclipse Start Debugger menu item

Intel AppUpTM Software Debugger output is displayed in a dedicated debugger window. To stop debugging, first stop the Eclipse debugger using one of the following methods:

• Eclipse Stop Debugger icon

• Eclipse Stop Debugger menu item

This allows you to examine the trace information. Then, stop the Intel AppUpTM Software Debugger using one of the following methods:

• Intel AppUpTM Software Debugger Stop icon in Eclipse

• Intel AppUpTM Software Debugger Stop item from the Eclipse menu

The figure below shows the Intel AppUpTM Software Debugger window with debug data displayed.

The Clear button clears the current contents of the Intel AppUpTM Software Debugger window.

The Exit screen closes the Intel AppUpTM Software Debugger window. The close icon in the upper corner of the window also closes the debugger window.

Note: The Intel AppUp center will not run properly if the Intel AppUpTM Software Debugger is running. You must exit the Intel AppUpTM Software Debugger before running the Intel AppUp center.

Developing Components

A component is a reusable module that can be incorporated into applications in the form of libraries, modules, etc. The SDK library allows development of components for submission to the Intel AppUp developer program portal. This section provides information get a component ready for the portal.

Note: An application is licensed to use a component if there is a pre-arranged agreement between the developer of the component and the developer of the application. It is the responsibility of the component developer to enforce the license, i.e., to ensure that the calling application has a license to use your component.

This section provides information on the following topics:

• Component Guidelines

• Component Example

• Application Using Component Example

The information in this section assumes you have already read the information on applications in the previous sections of this document.

[FIGURE I]

Intel AppUpSM developer programPart of the Intel® Software Network

12

Component Guidelines

In general, developing a component is much like developing an application. Components, however, are different in several ways. The following guidelines address the unique aspects of developing components:

• Components are supported by their own class in the SDK library, called Component. The Component class is based on a base Product class. The recommended way of creating components is to extend the SDK library Component class (inheritance).

• You must create the Application class before creating the Component class used in the application.

• Only one instance of each Component may exist within an Application.

• All Components are automatically deleted when the Application class is deleted.

• Component GUIDs are different from Application GUIDs. For components, three GUIDs are available:

ADP_DEBUG_COMPONENTID—Used during development to test the authorized component case.

ADP_EXPIRED_COMPONENTID—Used during development to test the expired component case.

Production Component ID—The actual Production GUID for components that is included prior to submitting a component to the Intel AppUp developer program portal.

• Exception handling for components is the same as for applications.deleted when the Application class is deleted.

• Instrumentation (Begin Events and End Events) is not supported at the component level.

• Crash Reporting is not supported at the component level.

Component Example

The following code shows a component example in Java. SampleComponent is a component that displays a greeting message to the screen, then returns. The

component is created using the superclass Constructor super. A Component Debug ID is used and exceptions are defined. This code appears inside the SDK sample file AdpAdvanceSample (shipped with the SDK), but in reality would be available to application developers in the form of a component/function library or module.

class SampleComponent extends Component{

public SampleComponent() throws

UnauthorizedException,

InitializationException,

AdpRuntimeException {

super(ComponentId.DEBUG_ID);

// TODO Auto-generated constructor stub

}

String greeting(){

return “Greeting from “ + this.getClass().

getName();

}

}

Application Using Component Example

The application’s use of the component is shown in the code example below, which is found in AdpAdvanceSample. AdpAdvanceSample is a sample GUI application shipped with the SDK. It includes a button to invoke SampleComponent as well as buttons to demonstrate the other SDK calls.

public void actionPerformed(ActionEvent

e){

// TODO Auto-generated method stub

try {

SampleComponent comp = new

SampleComponent();

showInInfolist(comp.greeting());

} catch(AdpException e1){

showInInfolist(e1.getMessage());

}

}

[FIGURE J]

Intel AppUpSM developer programPart of the Intel® Software Network

13

Using the Packaging Utility

The SDK for Java includes the Intel AppUpTM Software Packaging Utility that integrates and packages the required jar files and application manifest into a single jar file prior to submitting the file to the Intel AppUpTM Developer Program portal. The jar file produced by the Packaging Utility meets the requirements of the Intel AppUpTM Runnable Jar File Specification. This output jar file contains the following:

• Application jar files for the project

• Intel AppUpTM SDK jar file

• Other required jar files, such as 3rd party jar files, DLLs, etc.

• Application Manifest

For added flexibility, the Packaging Utility allows developers to export package settings to an XML file or to import package settings from an XML file.

The following steps describe how to use the Packaging Utility:

Step 1: Launch the Software Packaging Utility

Click Start->All Programs->Intel

AppUp(TM) Software Development Kit->Java->Intel AppUpTM Packaging Utility for Java* software to launch the utility. You can also double-click on the adp_packager.jar file in the SDK directory. The Packaging Utility launches and displays the Welcome screen shown below.

Buttons on the bottom of the screen allow you to move to the Next screen, to move Back to the previous screen, or to Cancel the screen and close the utility, as appropriate for the context. Click Next to move the Set Application Information screen.

Note: The Import button is discussed at the end of this section under Exporting and Importing Package Settings.

Step 2: Set Application Information

This screen allows you to define basic information for the application manifest, such as publisher name, main jar file, other included files, and the output file.

Note: The name of the Main Jar file can only contain English characters.

Note: Manifest information for this version of the utility can only include English, French, Italian, German, and Spanish characters. Characters from other languages may cause the utility to generate error messages. (Even if the utility generates a jar file that contains unsupported characters, the application may fail validation if submitted to the Intel AppUpSM developer program portal.)

[FIGURE K]

[FIGURE L]

Intel AppUpSM developer programPart of the Intel® Software Network

14

Fill in the publisher information and supply the main application jar filename. Fields with an asterisk are mandatory. Click the upper Browse button and browse to select the main jar file.

Use the Add button to browse to and select the following file:

• appup_sdk_java_1.1.jar

Continue using the Add button to browse to and add any other files to be included in the final jar file. To remove a file from the list, select the file and click the Remove button.

Click the lower Browse button and browse to select the location and filename for the output file. When finished, click Next to move to the Set Runtime Environment screen.

Step 3: Set Runtime Environment

Specify any Program Arguments (if needed) for the application invocation. Arguments must be separated by spaces. Characters such as a comma or a colon are treated as part of the argument they are next to. Returns are permitted.

For System Properties, click the New button to open the Property Definition screen. Then enter the property name and value in the appropriate fields and click OK. (Or Cancel if you don’t want to enter/save the property.) Spaces can be used in the value field to separate different elements of the value.

To remove a property from the list, select the property and click the Remove button. To edit a property in the list, select the property and click the Edit button.

When finished, click Next to move to the Confirm Settings screen.

Step 4: Confirm Settings

The Confirm Settings screen displays a summary of the information from the previous screens. This information defines which files will be included in the final jar file and what information will be included in the jar file manifest.

Click the Back button to go back to previous screens to change any information you want to. If you approve of the configuration, click Next to create the final runnable jar file package.

The utility creates the final output jar file and displays the following screen.

Note: The Export button is discussed at the end of this section under Exporting and Importing Package Settings.

Click Close to close the screen and exit the Packaging Utility.

[FIGURE M]

[FIGURE N]

Intel AppUpSM developer programPart of the Intel® Software Network

15

Exporting and Importing Package Settings

The Package Completion screen in Figure N provides an Export button to save the current package settings to an XML file. You can select the filename and location for the XML file.

The Welcome screen provides an Import button to import package settings from an existing XML file. You can browse to select the desired XML file.

Using the Package Validation Utility

The SDK for Java includes the Intel AppUpTM Software Package Validation Utility that analyzes runnable jar files to help determine if they comply with the Intel AppUpTM Runnable Jar File Specification. The Package Validation Utility should be used prior to submitting the jar file to the Intel AppUpSM Developer Program portal. The utility can help speed the approval process for applications by allowing the developer to catch and correct packaging issues before applications are submitted.

Note: The analysis performed by this utility is only a part of the overall validation performed by Intel for approval of applications. Files that pass this Package Validation Utility may still have approval issues, and ultimately may not be approved by Intel, after submission to the Intel AppUpSM Developer Program portal.

The following steps describe how to use the Package Validation Utility:

Step 1: Launch the Software Package Validation Utility

Click Start->All Programs->Intel AppUpTM Software Development Kit->Java->Intel AppUpTM Software Package Validation Utility for Java* software to launch the utility. You can also double-click on the adp_validation.jar file in the SDK directory. The Package Validation Utility launches and displays the jar package selection screen shown in Figure O.

The Browse… button allows you to select a jar file to validate. The Validate button starts the validation sequence on the selected file. The Cancel button closes the utility.

Click Browse… and browse to the file you wish to validate. When you select the file, the path and filename appears in the file field next to the Browse button.

[FIGURE O]

INTEL APPUPSM DEVELOPER PROGRAM INCENTIVES:

INTEL® ATOMTM DEVELOPER MILLION DOLLAR FUND

Through this fund, we support software developers and companies creating new experiences through applications for Intel® Atom™ processor-based netbooks.

INTEL APPUPSM DEVELOPER CHALLENGE

The contest is designed to encourage breakthrough applications that fundamentally change the user experience on a netbook featuring an Intel Atom processor.

LEGENDS

Want application visibility? The Legends program is a way to share the story behind the applications. Get your app in and submit your story. Become a Legend.

INTEL® BLACK BELT SOFTWARE DEVELOPER

Share your knowledge and earn recognition for your contributions.

Step 2: Start the Validation

Click Validate to start the validation sequence. The utility performs the following steps:

• Checks the format of the jar package

• Extracts the files from the jar package

• Uses the contents of the package manifest to attempt to launch the application

The utility then prompts you to indicate whether or not the application launched successfully, as shown in Figure P.

After checking to see if the application launched successfully, click Yes or No, depending on your observerations.

Intel AppUpSM developer programPart of the Intel® Software Network

16

MORE JAVA* SDK RESOURCES

• Download the AppUpSM Java* SDK

• Java* SDK Technical Overview

• Java* Packaging Guidelines

• API Reference Guide for Java

• Java* Developer Guide

• Release Notes Java* SDK

• Release Notes for Eclipse plug-in (updated for Java)

• Java Forum & Support

LEARN MORE ABOUT DEVELOPER TOOLS AND RESOURCES AT:

• Intel® Software Dispatch – Delivering the latest advances in software technologies, de-veloper tools, and resources and best practices.

• Intel® Software Network

• Intel® Software Development Products

Disclaimers and Legal InformationINFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL’S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIA-BILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.UNLESS OTHERWISE AGREED IN WRITING BY INTEL, THE INTEL PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE INTEL PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR.Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked “reserved” or “undefined.” Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information.The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548-4725, or by visiting Intel’s Web Site.Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor family, not across different processor families. See http://www.intel.com/products/processor_number for details.For beta and pre-release product versions. This document contains information on products in the design phase of development.BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Atom, Centrino Atom Inside, Centrino Inside, Centrino logo, Core Inside, FlashFile, i960, InstantIP, Intel, Intel logo, Intel386, Intel486, IntelDX2, IntelDX4, IntelSX2, Intel Atom, Intel Atom Inside, Intel Core, Intel Inside, Intel Inside logo, Intel. Leap ahead., Intel. Leap ahead. logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel StrataFlash, Intel Viiv, Intel vPro, Intel XScale, Itanium, Itanium Inside, MCS, MMX, Oplus, OverDrive, PDCharm, Pentium, Pentium Inside, skoool, Sound Mark, The Journey Inside, Viiv Inside, vPro Inside, VTune, Xeon, and Xeon Inside are trademarks of Intel Corporation in the U.S. and other countries.* Other names and brands may be claimed as the property of others.Copyright © 2010, Intel Corporation. All rights reserved.Microsoft product screen shot(s) reprinted with permission from Microsoft Corporation.

Step 3: Validation Results

The utility displays the Validation Results screen as shown below. The utility also writes a summary of the analysis to Report.xml.

Click OK to close the screen and exit the Package Validation Utility. Or click Open Report to open the Report.xml file that was just created. (Report.xml contains the results of the most current validation attempt. This file is overwritten with new data each time the Validation Utility is run.)

You may now submit the jar package to the Intel AppUpSM developer program portal.

[FIGURE P]

[FIGURE Q]

Intel AppUpSM developer programPart of the Intel® Software Network