Intel AppUp Software Development Kit Developer Guide for Java technology
SDK Version: 1.1.1. Copyright © 2011 Intel Corporation. All Rights Reserved. Document Number: 323991-003US.
Contents
Intel AppUpSM Developer Program
Getting Started with Applications
Using the Intel AppUpTM Software Debugger
Application Using Component Example
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 for Java* software. The SDK (Software Development Kit) includes programming libraries, documentation, and sample code to help developers create, test, and submit Java applications and components intended for distribution via the Intel AppUpSM center.
Intended Audience
This document is intended for experienced software developers who are developing applications and components for the Intel AppUpSM center, using a Java SE 1.6 (or later) runtime environment. These can be new applications/components or existing applications/components being ported for the Intel AppUpSM center.
Information about the specific editions and versions of the environments that are supported is provided in the Release Notes for the SDK.
Using this Developers 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 AppUpSM 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, authorizes upgrades to a later version of an application, 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 AppUpSM Developer Program portal.
Using the Package Validation Utility, describes how to use the Intel AppUTM Software Package Validation utility to pre-validate runnable jar file packages prior to submission to the Intel AppUpSM Developer Program portal.
Conventions and Symbols
The following table shows the conventions used in this document.
Conventions and Symbols Used in This Document
|
This type |
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 significant. |
|
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. |
Related Information
Reference information for the .NET 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:
Intel AppUpSM Developer Program
SDK Contents
Application/Component Development Flow
Intel AppUpSM Developer Program
The Intel AppUpSM Developer Program provides developers with everything they need to create and then sell their applications/components to end users of Intel® Atom™ processor-based devices (netbooks, smartphones, and pads) through the Intel AppUpSM center. This allows you to earn money for your development efforts. The figure below 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 AppUpSM 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 AppUpSM 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 AppUpSM Developer Program Dashboard (business backend). 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 AppUpTM 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
The figure below shows the different elements of the SDK.
SDK Libraries
SDK libraries provide you with access to the Intel AppUpSM center Consumer Client for services such as Authorization, Error Handling, Instrumentation (metering), Upgrade Authorization, and Crash Reporting. Functionality will 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 AppUpTM 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 AppUpSM Developer Program: (1) sample code, (2) a Developer Guide (this document), and (3) an 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 AppUpTM 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 AppUpSM Developer Program portal to view your Dashboard, interact with Developer Resources, etc., from within your IDE. The Intel AppUpTM 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 create this single runnable jar file for submission to the Intel AppUpSM Developer Program portal.
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 AppUpSM Developer Program portal.
Development Flow
The figure below illustrates the high-level development flow for Intel AppUpSM Developer Program applications. The steps in this flow are as follows:
Join the Intel AppUpSM Developer Program, by creating an account on the Intel AppUpSM 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 AppUpSM Developer Program portal.)
Insert the minimum SDK code into your existing application/component does, 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 AppUpTM 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, Upgrade Authorization, 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, 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 AppUpTM 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 AppUpSM Developer Program portal.
Package your application/component into a jar file that Intel’s guidelines for runnable Java applications. Getting Started with Application provides more information on this topic. Details on the Intel AppUpTM 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 AppUpTM Software Package Validation Utility are provided in Using the Validtion Utility.
Submit your final installation package to the Intel AppUpSM 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 AppUpSM 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 below. 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 AppUpTM 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 to ensure 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 AppUpTM 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 AppUpTM 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 application running initially. Advanced Error Handling, Instrumentation, Upgrade Authorization, 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 AppUpTM Software Debugger that emulates the Application Services of the Intel AppUpSM 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, upgrade authorization, and crash reporting.
With the Intel AppUpTM 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 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:
Intel AppUpTM Software Debugger Start icon in Eclipse
Intel AppUpTM 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
The 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 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
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 AppUpSM Developer Program portal. Production IDs are obtained from the Intel AppUpSM Developer Program portal, which requires that you enroll in the Intel AppUpSM 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.
com.intel.adp.Application app = new com.intel.adp.Application(new
com.intel.adp.ApplicationId(0x12341234,0x56785678,0x12341234,0x56785678));
Assume you are enrolled in the Intel AppUpSM 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.)
Note: While the Production ID is used, you can no longer use the Intel AppUpTM 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 AppUpTM 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 AppUpTM 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 AppUpSM 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 AppUpTM 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 AppUpSM 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
Upgrade Authorization
Crash Reporting
Using the Intel AppUpTM 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 AppUpSM center Consumer Client can concurrently support applications with different API levels.
API level information for an application is displayed in
the Intel AppUpTM Software Debugger
output, as shown in the figure below. 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 {
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.
End User Error Messages
|
Message ID |
Message Text |
|
String_ADP_AUTHORIZATION_EXPIRED |
The license for this application has expired. |
|
String_ADP_BEGINEVENT_ERROMSG |
The application experienced an error while starting a usage record. |
|
String_ADP_ENDEVENT_ERRORMSG |
The application experienced an error while ending a usage record. |
|
String_ADP_FAILURE |
The application experienced a critical error. |
|
String_ADP_INCOMPATIBLE_VERSION |
The current Intel AppUpSM center software does not support this version of the application. |
|
String_ADP_NO_APP_BEGIN_EVENT |
The application did not complete a start of usage record. |
|
String_ADP_NOT_AUTHORIZED |
The application is not authorized to run under this account on this device. |
|
String_ADP_NOT_AVAILABLE |
The application cannot connect to the Intel AppUpSM center. |
|
String_ADP_NOT_INITIALIZED |
The application did not initialize properly. |
|
String_ADP_TIMEOUT |
The Intel AppUpSM center response timed out. |
|
String_ADP_UPGRADE_ERRORMSG |
The application failed to send the upgrade request to the Intel AppUpSM center. |
Instrumentation
The Intel AppUpSM Developer Program portal allows you to collect usage statistics for your applications. The Intel AppUpSM center aggregates this information and passes it to My Dashboard on the Intel AppUpSM 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 AppUpSM 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 AppUpSM center for the application.
Application End Event – Triggers sending an End Event message to the Intel AppUpSM 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 Samples
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();
}
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());
}
Upgrade Authorization
The Intel AppUpTM SDK library provides an API call to support upgrading to one designated version of an application. Typical usage of this In-Application Upgrade call is to support scenarios such as a user upgrading to a premium version of an application from a free version of the application. When invoked, the In-Application Upgrade call passes the Application ID of the target application to the Intel AppUpSM center software. The Intel AppUpSM center software then offers the upgrade to the end user. If the end user accepts the offer, the Intel AppUpSM center software installs the target version of the application (in addition to the original version). If the end user declines the offer, the existing version of the application continues running.
The In-Application Upgrade call uses a Production Application ID to represent the target application. This Production Application ID does not need to be the actual Production ID during development. But the actual Production Application ID must be included prior to uploading your application to the Intel AppUpSM developer program portal. As a mnemonic device, it may be helpful to use the Production Application ID of the original application as the target application during development.
Note: The target application must be: (1) already validated and in the Intel AppUpSM store, or (2) submitted with the original application for validation.
Code Sample
An example of the In-Application Upgrade call is shown below, outlined in red. A basic exception handler is included. The In-Application Upgrade call uses a Production Application ID to represent the target application. This Production Application ID does not need to be the actual Production ID during development. But the actual Production Application ID must be included prior to uploading your application to the Intel AppUpSM developer portal. As a mnemonic device, it may be helpful to use the Production Application ID of the original application as the target application during development.
try {
app.upgrade(new ApplicationId(0x11111111,0x22222222,0x33333333,0x44444444));
}
catch (AdpErrorException e) {
System.out.println("Exception occured - " + e.getMessage());
}
catch (AdpWarningException 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 AppUpSM Developer Program portal. The crash information stored on disk is a subset of the report sent to the Intel AppUpSM 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 AppUpSM Developer Program
portal. The figure below 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.
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 AppUpTM Software Development Kit API Reference for Java* software document, which is located on the Intel AppUpSM 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.
Customizable Crash Report Fields
The table below 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.
Custom Crash Report Fields and Sources
|
Crash Report Fields |
My Dashboard Column |
Source |
|
Application Name |
No (but included in Details) |
SDK |
|
Application ID |
No (but included in Details) |
SDK |
|
ModuleName |
Module (and in Details) |
Developer |
|
LineNumber |
Line (and in Details) |
Developer |
|
Category |
No (but included in Details) |
Developer |
|
Message |
Messages (and in Details) |
Developer |
|
ErrorData |
No (but included in Details) |
Developer |
|
SDK API Level |
No (but included in Details) |
SDK |
|
Runtime |
Runtime (and in Details) |
SDK |
|
Runtime version |
No (but included in Details) |
SDK |
|
OS |
OS (and in Details) |
SDK |
|
OS version |
No (but included in Details) |
SDK |
|
Timestamp |
Timestamp (and in Details) |
SDK |
|
Up to 20 custom fields |
(reserved for future use) |
Developer |
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 AppUpSM 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.)
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();
}
}
Using the Intel AppUpTM Software Debugger
The SDK includes the Intel Intel AppUpTM Software Debugger that emulates the Application Services of the Intel AppUpSM 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, upgrade authorization, 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:
Intel AppUpTM Software Debugger Start icon in Eclipse
Intel AppUpTM 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
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.
Notes: The Intel AppUpSM 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 AppUpSM 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 AppUpSM Developer Program portal. This section provides information get a component ready for the portal.
Notes: 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.
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 AppUpSM Developer Program portal.
Exception handling for components is the same as for applications.
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());
}
}
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 AppUp(TM) 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.)
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 what 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.
Exporting and Importing Package Settings
The Package Completion screen above 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 AAppUpSM 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 AppUp(TM) Software Development Kit->Java->Intel AppUp(TM) 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 below.
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.
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 below.
After checking to see if the application launched successfully, click Yes or No, depending on your observerations.
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.
|
Document Number |
Revision Number |
Description |
Revision Date |
|
323991 |
001 |
Initial document release to support Java SDK V1.1 |
December 2010 |
|
|
002 |
Updated to support Java SDK V1.1.1: • Added In-Application Upgrade Call information. |
February 2011 |
|
|
003 |
Updated In-Application Upgrade Call information. |
May 2011 |
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 LIABILITY 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 © 2011, Intel Corporation. All rights reserved.
Microsoft product screen shot(s) reprinted with permission from Microsoft Corporation.
