Intel AppUp Java Developer Guide

Intel AppUpSM developer program
Part of the Intel® Software Network

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

Intel AppUp Java* Developer Guide
SM

Contents: • Overview: introduces the Intel AppUpSM
Developer Program, this SDK, and
• About This Document
the general application/component
• Overview
development flow.
• Getting Started with Applications
• Advanced Information • Getting Started: provides the minimum
• Developing Components steps for getting an existing Java SE 1.6
• Using the Packaging Utility (or later) application ready to submit
• Using the Package Validation Utility to the Intel AppUp developer program
• Disclaimers and Legal Information portal.
• Advanced Information: describes how to
About This Document
integrate the additional capabilities of
This document is for developers getting the SDK library to build a more robust
started with the Intel AppUpTM Software application that provides a better
Development Kit (SDK) for Java software experience for users, and/or provides
Download the SE 1.6 (or later) environments. The better usage feedback to developers.
SDK includes programming libraries,
AppUp Java SDK & SDK Plug-in documentation, and sample code to help
• Developing Components: describes
how to develop software components
for Eclipse* Software developers create, test, and submit Java*
designed to be included in applications,
applications and components intended
and how to combine components and
fordistribution via the Intel AppUpSM
applications.
center.
• Using the Packaging Utility: describes
Intended Audience how to use the Intel AppUpTM Software
This document is intended for Packaging Utility to create a single
experienced software developers runnable jar file for submission to the
who are developing applications Intel AppUp developer program portal.
and components for the Intel AppUp • Using the Package Validation Utility:
Provides developers with center, using Java. These can be new describes how to use the Intel AppUpTM
applications/components or existing Software Package Validation utility to
everything they need to create and applications/components being ported pre-validate runnable jar file packages
sell their apps to users of millions of for the Intel AppUp center. prior to submission to the Intel AppUp
developer program portal.
Intel® Atom™ processor-based devices. Using this Developer Guide
This developer guide contains the Conventions and Symbols
following sections: The following table shows the
• About this Document: introduces conventions used in this document.
the contents and conventions of this [FIGURE A]
document.
1


This type style Indicates an element of syntax, reserved word, keyword, dashboard (business back-end). The
filename, computer output, or part of a program example. dashboard also displays payment
The text appears in lowercase unless uppercase is signifi- information.
cant. For more information on how the program
This type style Indicates the exact characters you type as input. Also used works, including details on how payment is
to highlight the elements of a graphical user interface such handled, visit the program portal at
as buttons and menu names or filenames and labels when http://appdeveloper.intel.com.
discussing program examples. SDK Contents
Hyperlink Indicates a hyperlink to internal or external information. Use
The Intel AppUpTM SDK for Java software
CNTL+mouse click to navigate.
includes the following major elements:
Notes, cautions, etc. Note: Indicates an important comment or side topic for the
• Intel AppUpTM Software Libraries for Java
user.
SE 1.6 (or later)
[FIGURE A]
• Tools such as the Intel AppUp Software
Related Information libraries, plug-ins, documentation, and Debugger to aid development
support.
Reference information for the Java • Code examples to aid in the development
SDK is provided in the Intel AppUpTM • Intel validates submitted applications/ of applications and components
Software Development Kit API components and, when they are ready,
• Documentation to show you how to
Reference for Java software document, publishes them in the Intel AppUp center
incorporate the appropriate API calls into
which is located on the Intel AppUp SM for consumers.
your applications/components
developer program portal. • Consumers purchase (or download)
published applications from the Intel Figure C Shows the different elements of
Overview the SDK.
AppUpSM center (delivery backend)
This section provides an overview of the and run them on their client platforms.
SDK Libraries
following: Developers typically purchase (or
download) components to include in the SDK libraries provide you with access to
• About this Document: introduces
applications they develop. the Intel AppUp center Consumer Client
the contents and conventions of this
for services such as Authorization, Error
document. • Information on downloads, usage, and
Handling, Instrumentation (metering),
ratings is provided to developers via
• SDK Contents and Crash Reporting. Functionality will
the Intel AppUp developer program
• 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 [FIGURE B]
2


Developer Platform
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

[FIGURE C]

increase over time with new library Development Process Integration
releases, as appropriate for each
Developer Process Integration allows
language and runtime.
you to quickly insert SDK library code
SDK libraries are the only parts of into your existing applications, integrate
the SDK that are redistributed with the Intel AppUp Software Debugger
applications/components. There will be into your debug flow, etc., from within
separate implementations of the library your IDE. The Intel AppUpTM SDK Plug-
for each supported runtime and, in the in 1.1 for Eclipse software provides
case of native applications, for each development process integration for
supported operating system. Java.

Intel AppUpTM Software Debugger Developer Portal Integration
The Intel AppUp Software Debugger is Developer Portal Integration allows
a utility that emulates the Application you to interact with the Intel AppUp
Services of the Intel AppUp SM center developer program portal to view your
Consumer Client. The Intel AppUp Dashboard, interact with Developer
Software Debugger allows you to test Resources, etc., from within your IDE.
and debug your application/component The Intel AppUp SDK Plug-in 1.1 for
without requiring the full client stack or Eclipse software provides development
access to hardware. portal integration for Java.

Documentation Packaging Integration
Three types of documentation Packaging Integration allows you to
are provided to help you develop integrate and package application/
applications/ components for the Intel component jar files, SDK library jar files
AppUp developer program: and manifest into a single jar file for
1. Sample code upload to the Intel AppUp developer
program portal. The Intel AppUpTM
2. Developer Guide (this document) Software Packaging Utility creates this
3. Online API Reference for a specific single runnable jar file for submission
language/API. to the Intel AppUp developer program
portal.
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

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. [FIGURE D]
• 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,
4


they can provide you with more insight included in the sample, but you should this Debug ID allows testing with the Intel
into usage of your application/component. consider it for an actual application. The AppUp Software Debugger. This Debug ID
Some languages/runtimes do not support Crash Reporting code in the sample is not is a 128-bit number, expressed as a string
all of the SDK capabilities.. required either, and is not discussed in this using predefined constants. The value
section. of the Debug ID is contained in the SDK
• Perform additional testing with the Intel
library. You can also use the absolute value
AppUp Software Debugger to make Assume that you have a working
(all one’s). You must replace the Debug ID
sure any additional SDK code is working application like the sample, but that it does
with a Production ID after testing. (The
properly. not have Intel AppUpTM SDK code included.
Production ID is discussed in detail later
Assume also that you have already
• Replace the Debug GUID with a in this section.) There is also an Expired
installed the SDK. The following steps
Production GUID. You must obtain the Application Debug ID to allow you to test
describe how to integrate Intel AppUpTM
Production GUID from the Intel AppUp the “expired” branch of your application.
SDK code into the application:
Step 3: Insert SDK Shutdown Code
• Package your application/component Step 1: Add SDK Library to the Build Path
into a jar file that meets Intel’s guidelines Locate the code that shuts down the
You must add the SDK library to Java
for runnable Java applications. Getting application and insert the SDK shutdown
Classpath. In Eclipse, use the Build
Started with Application provides more code. The SDK shutdown code is shown
Path item on the Project menu to add
information on this topic. Details on the in the sample below. The shutdown
appupp_sdk_java_v1.1.jar to the project.
Intel AppUp Software Packaging Utility code performs SDK library shutdown.
(Or right click on the selected Project and
are provided in Using the Packaging (The Intel AppUp SDK Plug-in 1.1 for
use Build Path>Configure Build Path to
Utility. Eclipse* software can insert this code
open the Properties. Select the Libraries
automatically.)
• Pre-Validate as much of the application/ tab and click on Add External jars … to add
component as possible. Pre-validation can the library to the Project). Browse to the public AdpHelloWorldWindow()
help smooth validation by Intel. Getting directory where the SDK is installed.
{
Started with Application provides more
Step 2: Insert SDK Authorization Code
information on this topic. Details on the /// <ADP>
Using Authorized Debug ID
Intel AppUp Software Package Validation
Locate the code that initializes try {
Utility are provided in Using the Validtion
the application and insert the SDK
Utility. com.intel.adp.Application app = new
authorization code. The SDK authorization com.intel.adp.Application
• Submit your final installation package to code is shown in the sample in step 3. The
the Intel AppUp developer program portal authorization code includes the Application (com.intel.adp.AdpConstants.ADP_DEBUG_
for validation by Intel. APPLICATIONID) ;
Constructor call, which performs
initialization and authorization, and catches }
Getting Started with Applications exceptions. The application is derived from
a core Application class. Only one instance catch( AdpErrorException e) {
This section describes the basic steps to
get a Java application ready for the Intel of the Application class may exist in an e.printStackTrace();
AppUp developer program portal. The application. (The Intel AppUp SDK Plug-in
steps are described using the sample 1.1 for Eclipse* software can insert this }
program AdpBasicSample. code automatically.) finally {
Component development is covered in Note: A system is authorized to run an
if (app != null)
Developing Components. application if the application was purchased
by the user on the current system or if the app.dispose();
AdpBasicSample in Java system is one of the five systems allowed
}
The AdpBasicSample sample application is by the licensing system. As the application
a minimal Java application that incorporates developer, you are responsible for ensuring /// </ADP>
Intel AppUpTM SDK authorization code and that the current system has a license to
use your application; the OS or runtime }
code to demonstrate Crash Reporting.
(AdpBasicSample is installed with the does not enforce this automatically. Note: The library reference, authorization,
SDK and is located in the …Java/Samples Note that an Authorized Application and shutdown code described above are
folder.) Advanced Error Handling is not Debug ID is used. During development, the only mandatory work to get a Java
5


application running initially. Advanced Step 5: Get and Swap in a Production ID Step 6: Create an Installation Package
Error Handling, Instrumentation, and
Once your application is working, you Create a single JAR file that includes
Crash Reporting are not discussed here,
must replace the Authorized Application the Intel AppUpTM SDK library jar file,
but you should consider them for actual
Debug ID with an Authorized Production application jar file(s), and an application
applications. Those topics are all covered
Application ID before you can submit the manifest file. The Intel AppUp Software
in Advanced Information.
application to the Intel AppUp developer Packaging Utility can help create these
Step 4: Test Application with Intel program portal. Production IDs are Java runnable jar packages. See Using the
AppUpTM Software Debugger obtained from the Intel AppUp developer Packaging Utility, for information on using
Program portal, which requires that this utility. For general information on
The SDK includes the Intel AppUp you enroll in the Intel AppUp developer packaging requirements, refer to http://
Software Debugger that emulates the Program. The Production ID is a 128-bit appdeveloper.intel.com/en-us/article/
Application Services of the Intel AppUp number organized as four integers in hex packaging-requirements.
center Consumer Client on your system, format. The following example shows
without requiring the full client or access Step 7: Pre-Validate the Installation
part of the authorization code with a
to hardware. The Intel AppUp Software Package
Production ID included.
Debugger allows testing of authorization, Intel validates application packages
error handling, instrumentation, and crash Assume you are enrolled in the Intel
submitted to the Intel AppUp developer
reporting. AppUp developer program and have
program portal prior to publishing them
logged into the program portal. Start
With the Intel AppUp SDK Plug-in 1.1 on the Intel AppUpSM center. You should
the application submission process
for Eclipse 3.5.2 installed and the Intel become familiar with the validation
and provide information that uniquely
AppUpTM SDK code included, you can process so you can pre-validate as many
identifies your application. After entering
use the Eclipse debugger and Intel of the items as possible yourself prior
that information, click on the Get a GUID
AppUpTM Software Debugger to debug to submission. This helps to smooth the
button on the portal. The site displays a
your application. Intel AppUp Software approval process for your application. The
GUID, which is a Production ID. You can
Debugger trace information is included Intel AppUp Software Package Validation
copy and paste this Production ID into
in the Intel AppUp Software Debugger Utility can help validate Java runnable
your application, replacing the Debug ID.
window. jar packages. See Using the Validation
(You can also request that the portal email
Utility, for information on using this utility.
To start debugging, first start the Intel a Production ID to you.)
For more information on the validation
AppUp Software Debugger using one of com.intel.adp.Application app = new com. process, refer to http://appdeveloper.
the following methods: intel.adp.Application(new intel.com/en-us/article/troubleshooting-
• Intel AppUp Software Debugger Start validation-failures.
icon in Eclipse com.intel.adp.ApplicationId(0x12
341234,0x56785678,0x12341234, Step 8: Submit the Application
• Intel AppUp Software Debugger Start 0x56785678));
item from the Eclipse menu Submit your application package by
Note: While the Production ID is used, following the steps on the Intel AppUp
Then start the Eclipse debugger using one
you can no longer use the Intel AppUp Developer Program portal. You can then
of the following methods:
Software Debugger for normal testing and monitor status of the application via the My
• Eclipse Start Debugger icon debugging. (The Application Constructor Dashboard page on the portal. Alternately,
• F11 key call will always return an ADP_NOT_ with the Intel AppUpTM SDK Plug-in for
AUTHORIZED error.) You can always Eclipse* software installed, you can use the
• Eclipse Start Debugger menu item
return to using the Debug ID to perform Dashboard feature to monitor status.
This allows you to examine trace broader testing and debugging using the
information. Then, stop the Intel AppUp Intel AppUp Software Debugger. Advanced Information
Software Debugger using one of the This section provides advanced information
following methods: You can obtain a Production ID as early in
your development cycle as you wish. Since on the following topics:
• Intel AppUp Software Debugger Stop
submitting the name for an application • API Levels
icon in Eclipse
is required to receive a Production ID,
• Advanced Error Handling
• Intel AppUp Software Debugger Stop getting a Production ID early increases
item from the Eclipse menu your chances that your desired application • Instrumentation
name will still be available.
6


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
[FIGURE E] change the GUID to the ADP_EXPIRED_
APPLICATIONID to test the application
• Crash Reporting Exception Handling
“expired” branch of your error handler.
• Using the Intel AppUp Software Exception handling in the
For exceptions that are not possible
Debugger AdpBasicSample program can be
to handle in your application, the
expanded to provide more robust
API Levels recommended approach is to re-throw
handling of error and warning
the exception. (The method to re-throw
The Intel AppUpTM SDK library provides a exceptions.
the exception depends on the application
mechanism to determine compatibility of The Java SDK library includes includes language and context.) The integrated
the API level of applications versus the three pre-defined exception classes for crash handler in the SDK library then
API level of client systems. errors and one pre-defined exception catches the exception and generates
Applications with API levels higher than class for warnings to provide greater a Crash Report using the context
that supported by the client system granularity in exception handling. You information from the exception. See the
are not permitted to be downloaded should consider using these classes to Crash Reporting subsection for details on
to the client. If the API level on a client provide more robust exception handling Crash Reporting.
system is rolled back to a lower API for your application. The exception
level, applications with higher API levels classes are as follows: Code Sample
already installed on the client system The Java code sample below includes
Error Exception Classes
are not permitted to run. An Intel AppUp a catch for each of the SDK library
• InitializationException—Catches
center Consumer Client can concurrently exception classes and the original
error exceptions thrown while the
support applications with different API default exception handler. Note that
SDK library application constructor
levels. you can change the GUID to the ADP_
attempts to initialize the SDK library
EXPIRED_APPLICATIONID to test the
API level information for an application code. This class is derived from
application “expired” branch of your
is displayed in the Intel AppUp Software AdpErrorException.
error handler.
Debugger output, as shown in the
• UnauthorizedException—Catches
Figure F. This information can be useful Application app = null;
error exceptions thrown while
when debugging potential issues.
the SDK library code attempts to try {
authorize the application. This class is
7


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
[FIGURE F]
code immediately after the calls is the
app = new Application (AdpConstants. and displayed to end users. These Exception handler for both calls.
ADP_DEBUG_APPLICATIONID); messages are accessed via their unique Application app = null;
} Message ID. They do not map directly to
the Return/Error Codes. try {
catch (InitializationException e) {
app = new Application(AdpConstants.
Instrumentation
// TODO Add your logic to handle ADP_DEBUG_APPLICATIONID);
initialization errors The Intel AppUp developer program portal
app.beginEvent();
allows you to collect usage statistics
e.printStackTrace(); for your applications. The Intel AppUp }
} center aggregates this information and
catch (AdpErrorException e) {
passes it to My Dashboard on the Intel
catch (UnauthorizedException e) { AppUp developer program portal. If the System.out.println(“Exception
// TODO Add your logic to handle application is offline, the information occured - “ + e.getMessage());
authorization errors is cached and sent later when the
}
application is online.
e.printStackTrace(); The call can also be made with a
Note: The final decision on whether to
} Production ID, as follows:
gather and send this information to the
Intel AppUp center lies with the end Application app = null;
catch (AdpRuntimeException e) {
user. They must explicitly agree to the
try {
// TODO Add your logic to handle collection and transmittal of this usage
runtime errors data. If they say no, this data is discarded. app = new Application(ApplicationId.
e.printStackTrace(); Your application must support this explicit fromString
end-user opt-in choice. Even if they
} (“2CA9A3A1-5428-44B3-8AA6-
say yes, no individual user or machine
B6CE19228561”));
identifying information is collected; all
End-User Error Messages
data is aggregated. app.beginEvent();
The SDK contains error message strings
that can be retrieved by applications The SDK supports the following }
Instrumentation events to measure
8


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
[FIGURE G] additional or different information than
provided in the default crash report, you
catch(AdpErrorException e){ Crash Reporting must implement custom Crash Reporting,
System.out.println(“Exception Even when you follow best practices which is covered at the end of this
occured - “ + e.getMessage()); with respect to error handling, subsection. The method to implement
applications sometimes encounter custom Crash Reporting automatically
} disables default Crash Reporting.
unexpected situations and crash. To
Insert an endEvent call in the source facilitate debug in these situations,
Default Crash Report
code where you wish to stop usage the Intel AppUpTM SDK library supports
measurement, as shown below. The Crash Reporting to provide a snapshot of Default crash reports are viewable
code triggers an End Event message the state of the application when it does via My Dashboard on the Intel AppUp
and includes an Exception handler crash. developer program portal. Figure H
for AdpWarningException and shows a default crash report from
Default crash reports are automatically
AdpRuntimeException. (Using an My Dashboard on the portal. This
enabled when the Application
endEvent call with no prior beginEvent information includes application context
Constructor runs; you do not have to
call results in a warning Exception.) information, runtime environment
explicitly enable this. (Customized Crash
information, SDK identification
try {
Reporting is covered at the end of this
information, and a core stack dump.
subsection.)
The complete report can be viewed by
app.endEvent();
When a crash occurs, crash information clicking on the Details link for a specific
} is first stored locally on disk. Then a report.
process wakes up to create and send
Catch(AdpWarningException e) { Customizing Crash Reports
the crash report to the Intel AppUp
System.out.println(“Exception developer program portal. The crash Customized Crash Reporting allows
occured - “ + e.getMessage()); information stored on disk is a subset you to provide different/additional
of the report sent to the Intel AppUp information than default Crash
}
developer program portal. When Reporting. Custom crash reports are set
Catch(AdpRuntimeException e) { the process runs, the process adds immediately after the SDK Application
information to what is stored on disk to Constructor call so that crash reports
System.out.println(“Exception
create the final report. This process also can include data as early in application
occured - “ + e.getMessage());
periodically sweeps the crash reporting execution as is reasonable possible.
} area, looking for unsent crash reports. When a customized crash report is set in
Note: Since the stability of the system an application, default crash reporting is
cannot be assumed, there is no automatically disabled.
9


Customized Crash Reporting requires column defining the source (SDK or Note: Some crashes can lead to a client
additional work on the part of the Developer) of the information for the system eventually halting. In these
developer, and an understanding of respective field. cases, the time to store a crash report
the choices available. The following on the client system may be limited. To
Note: It is your responsibility to ensure
subsections introduce the SDK crash maximize obtaining crash information,
that custom Crash Reports do not
report classes and provide information you should consider the tradeoffs
include any data that violates Intel
to help you make your choices. between the amount of information to
Privacy rules. See http://appdeveloper.
intel.com for details. include in a custom crash report versus
AbstractCrashReport a potentially narrow window of time
AbstractCrashReport is an abstract The fields with the greatest flexibility to store the information on the client
class with virtual methods that are for customization are listed below: system.
designed to populate data existing • The Category field allows you to
within the class. Since the system may Defining and Calling Custom Crash
create categories to sort your crash
be at an unstable state, allocation of Reports
reports on the Intel AppUp developer
data on the stack is to be avoided, program portal. For example, you The following example shows the
if possible. These methods will be may wish to create categories called framework to define and call a custom
called by the underlying framework to “MEMORY”, “IO”, “USER ERROR”, etc. crash report for Java. The contents of
collect data to be submitted in crash a custom crash report are defined by
• The Error Data field allows you to
reports. By implementing a subclass the developer in MyExceptionHandler.
create your own stack dumps or long
of AbstractCrashReport, you can (Implementation of custom Crash
error messages to help you understand
gain control of every field that will be Reporting automatically disables default
why your application crashed.
returned during the crash reporting 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

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 [FIGURE H]

10


import java.lang.thread.*; @Override
import com.intel.adp.*; protected void populateMessage() {
// TODO Auto-generated method stub
public class CustomizeCrashReportSample {
this.errorMessage = “User of illegal method”;
/** }
* @param args
@Override
*/
protected void populateModuleName() {
public static void main(String[] args) {
Application app = null;
super.populateModuleName();
try { }
app = new Application(AdpConstants.ADP_DEBUG_
}
APPLICATIONID);
app.setCrashReport(new MyExceptionHandler()); }
}
class MyExceptionHandler extends DefaultCrashReport{
catch (AdpErrorException e) {
e.printStackTrace(); @Override
System.exit(1); protected void populateCategory() {
} this.errorCategory = “My Error Category”;
}
if(app != null) {
throw new Exception(“Something bad happened! But this is @Override
expected.”); protected void populateCrashReportFields() {
} this.crashReportFields = new AdpCrashReportField[1];
this.crashReportFields[0] = new AdpCrashReportField
System.exit(0);
(“Sub_Category”,
}
“Trapped Error”);
}
class MyExceptionHandler extends DefaultCrashReport{
@Override
@Override
protected void populateErrorData() {
protected void populateCategory() {
this.errorCategory = “My Error Category”;
super.populateErrorData();
}
}
@Override
@Override
protected void populateCrashReportFields() {
protected void populateLineNumber() {
this.crashReportFields = new AdpCrashReportField[1];
this.crashReportFields[0] = new AdpCrashReportField(“Sub_
super.populateLineNumber();
Category”,
}
“Trapped Error”);
} @Override
protected void populateMessage() {
@Override
protected void populateErrorData() {
this.errorMessage = “User of illegal method”;
}
super.populateErrorData();
} @Override
protected void populateModuleName() {
@Override
protected void populateLineNumber() {
super.populateModuleName();
}
super.populateLineNumber();
} }

11


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
[FIGURE I]
the component and the developer of
Using the Intel AppUp Software • F11 key the application. It is the responsibility
Debugger of the component developer to enforce
• Eclipse Start Debugger menu item the license, i.e., to ensure that the calling
The SDK includes the Intel Intel AppUp Intel AppUpTM Software Debugger output application has a license to use your
Software Debugger that emulates the is displayed in a dedicated debugger component.
Application Services of the Intel AppUp window. To stop debugging, first stop
center Consumer Client on your system, This section provides information on the
the Eclipse debugger using one of the following topics:
without requiring the full client or access following methods:
to hardware. The Intel AppUpTM Software • Component Guidelines
Debugger allows testing of authorization, • Eclipse Stop Debugger icon
• Component Example
error handling, instrumentation, and crash • Eclipse Stop Debugger menu item
reporting. • Application Using Component Example
This allows you to examine the trace
With the Intel AppUpTM SDK Plug-in information. Then, stop the Intel AppUpTM The information in this section assumes
for Eclipse software installed and the Software Debugger using one of the you have already read the information on
Intel AppUpTM SDK code included, you following methods: applications in the previous sections of
can use the Eclipse debugger and Intel this document.
• Intel AppUpTM Software Debugger Stop
AppUpTM Software Debugger to debug
icon in Eclipse
your application. Intel AppUpTM Software
Debugger trace information is included • Intel AppUpTM Software Debugger Stop
in the Intel AppUpTM Software Debugger item from the Eclipse menu
window. The figure below shows the Intel AppUpTM
To start debugging, first start the Intel Software Debugger window with debug
AppUpTM Software Debugger using one of data displayed.
the following methods: The Clear button clears the current
• Eclipse Start Debugger icon contents of the Intel AppUpTM Software
Debugger window.

12


Component Guidelines component is created using the superclass Application Using Component Example
Constructor super. A Component Debug
In general, developing a component is much The application’s use of the component
ID is used and exceptions are defined. This
like developing an application. Components, is shown in the code example below,
code appears inside the SDK sample file
however, are different in several ways. The which is found in AdpAdvanceSample.
AdpAdvanceSample (shipped with the
following guidelines address the unique AdpAdvanceSample is a sample GUI
SDK), but in reality would be available to
aspects of developing components: application shipped with the SDK. It includes
application developers in the form of a
a button to invoke SampleComponent as
• Components are supported by their own component/function library or module.
well as buttons to demonstrate the other
class in the SDK library, called Component.
SDK calls.
The Component class is based on a base class SampleComponent extends Component{
Product class. The recommended way of public void actionPerformed(ActionEvent
creating components is to extend the SDK public SampleComponent() throws
e){
library Component class (inheritance). UnauthorizedException,

• You must create the Application class // TODO Auto-generated method stub
InitializationException,
before creating the Component class AdpRuntimeException {
try {
used in the application.
super(ComponentId.DEBUG_ID);
• Only one instance of each Component SampleComponent comp = new
may exist within an Application. SampleComponent();
// TODO Auto-generated constructor stub
• All Components are automatically deleted showInInfolist(comp.greeting());
}
when the Application class is deleted.
} catch(AdpException e1){
• Component GUIDs are different from String greeting(){
Application GUIDs. For components, three showInInfolist(e1.getMessage());
return “Greeting from “ + this.getClass().
GUIDs are available:
getName();
}
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 [FIGURE J]

13


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
[FIGURE K] version of the utility can only include
English, French, Italian, German, and
Using the Packaging Utility AppUp(TM) Software Development Spanish characters. Characters from
Kit->Java->Intel AppUpTM Packaging other languages may cause the utility to
The SDK for Java includes the Intel
Utility for Java* software to launch the generate error messages. (Even if the
AppUpTM Software Packaging Utility that
utility. You can also double-click on the utility generates a jar file that contains
integrates and packages the required jar
adp_packager.jar file in the SDK directory. unsupported characters, the application
files and application manifest into a single
The Packaging Utility launches and displays may fail validation if submitted to the Intel
jar file prior to submitting the file to the
the Welcome screen shown below. AppUpSM developer program portal.)
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
[FIGURE L]
14


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.
[FIGURE M] The utility creates the final output jar file
and displays the following screen.
Fill in the publisher information and supply For System Properties, click the New
the main application jar filename. Fields button to open the Property Definition Note: The Export button is discussed at
with an asterisk are mandatory. Click the screen. Then enter the property name and the end of this section under Exporting
upper Browse button and browse to value in the appropriate fields and click and Importing Package Settings.
select the main jar file. OK. (Or Cancel if you don’t want to enter/ Click Close to close the screen and exit
save the property.) Spaces can be used the Packaging Utility.
Use the Add button to browse to and
in the value field to separate different
select the following file:
elements of the value.
• 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.

[FIGURE N]
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
INTEL APPUPSM DEVELOPER
existing XML file. You can browse to select the desired XML file.
PROGRAM INCENTIVES:
Using the Package Validation Utility
INTEL® ATOMTM DEVELOPER
The SDK for Java includes the Intel AppUp Software Package Validation Utility that
TM MILLION DOLLAR FUND
analyzes runnable jar files to help determine if they comply with the Intel AppUpTM Through this fund, we support
Runnable Jar File Specification. The Package Validation Utility should be used prior to software developers and
submitting the jar file to the Intel AppUpSM Developer Program portal. The utility can help companies creating new
speed the approval process for applications by allowing the developer to catch and correct experiences through applications
packaging issues before applications are submitted. for Intel® Atom™
processor-based netbooks.
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 INTEL APPUPSM
submission to the Intel AppUpSM Developer Program portal. DEVELOPER CHALLENGE
The contest is designed to
The following steps describe how to use the Package Validation Utility: encourage breakthrough
Step 1: Launch the Software Package Validation Utility applications that fundamentally
change the user experience on a
Click Start->All Programs->Intel AppUpTM Software Development Kit->Java->Intel netbook featuring an Intel Atom
AppUpTM Software Package Validation Utility for Java* software to launch the utility. processor.
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. LEGENDS
The Browse… button allows you to select a jar file to validate. The Validate button Want application visibility? The
starts the validation sequence on the selected file. The Cancel button closes the utility. Legends program is a way to share
Click Browse… and browse to the file you wish to validate. When you select the file, the the story behind the applications.
path and filename appears in the file field next to the Browse button. 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.

[FIGURE O]

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.

16


MORE JAVA* SDK RESOURCES

• Download the AppUpSM Java*
[FIGURE P] SDK

• Java* SDK Technical
Step 3: Validation Results
Overview
The utility displays the Validation Results screen as shown below. The utility also writes
• Java* Packaging Guidelines
a summary of the analysis to Report.xml.
• API Reference Guide for Java
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 • Java* Developer Guide
the most current validation attempt. This file is overwritten with new data each time • Release Notes Java* SDK
the Validation Utility is run.)
• Release Notes for Eclipse
You may now submit the jar package to the Intel AppUpSM developer program portal. 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
[FIGURE Q]
and best practices.
• Intel® Software Network
• Intel® Software
Development Products
Disclaimers and Legal Information
INFORMATION 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.

Intel AppUp Java Developer Guide

Recommended

Recommended

More Related Content

What's hot

What's hot (18)

Viewers also liked

Viewers also liked (6)

Similar to Intel AppUp Java Developer Guide

Similar to Intel AppUp Java Developer Guide (20)

More from ReadWrite

More from ReadWrite (20)

Intel AppUp Java Developer Guide