Intel AppUp Java Developer Guide

Intel AppUpSM developer programPart of the Intel® Software NetworkPublished also at:http://appdeveloper.intel.com/en-us/article/intel-appup-software-development-kit-developer-guide-java-softwareIntel 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. Intel AppUpSM developer program 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

Intel AppUpSM developer programPart of the Intel® Software Network 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 SoftwareRelated Information libraries, plug-ins, documentation, and Debugger to aid development support.Reference information for the Java • Code examples to aid in the developmentSDK is provided in the Intel AppUpTM • Intel validates submitted applications/ of applications and componentsSoftware Development Kit API components and, when they are ready, • Documentation to show you how toReference for Java software document, publishes them in the Intel AppUp center incorporate the appropriate API calls intowhich is located on the Intel AppUp SM for consumers. your applications/componentsdeveloper program portal. • Consumers purchase (or download) published applications from the Intel Figure C Shows the different elements ofOverview the SDK. AppUpSM center (delivery backend)This section provides an overview of the and run them on their client platforms. SDK Librariesfollowing: 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 FlowIntel AppUp Developer ProgramThe Intel AppUp developer programprovides developers with everythingthey need to create and then selltheir applications/components to endusers of Intel® AtomTM processor-baseddevices (netbooks, smartphones, andpads) through the Intel AppUp center.This allows you to earn money for yourdevelopment efforts. Figure B shows ahigh-level view of how developers, Intel,and consumers interact.The following paragraphs summarize thisinteraction:• Developers prepare their applications/ components for submission to the Intel AppUp developer program portal using existing tools and Intel-provided SDK [FIGURE B] 2

Intel AppUpSM developer programPart of the Intel® Software NetworkDeveloper 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 Integrationreleases, as appropriate for each Developer Process Integration allowslanguage and runtime. you to quickly insert SDK library codeSDK libraries are the only parts of into your existing applications, integratethe SDK that are redistributed with the Intel AppUp Software Debuggerapplications/components. There will be into your debug flow, etc., from withinseparate implementations of the library your IDE. The Intel AppUpTM SDK Plug-for each supported runtime and, in the in 1.1 for Eclipse software providescase of native applications, for each development process integration forsupported operating system. Java.Intel AppUpTM Software Debugger Developer Portal IntegrationThe Intel AppUp Software Debugger is Developer Portal Integration allowsa utility that emulates the Application you to interact with the Intel AppUpServices of the Intel AppUp SM center developer program portal to view yourConsumer Client. The Intel AppUp Dashboard, interact with DeveloperSoftware Debugger allows you to test Resources, etc., from within your IDE.and debug your application/component The Intel AppUp SDK Plug-in 1.1 forwithout requiring the full client stack or Eclipse software provides developmentaccess to hardware. portal integration for Java.Documentation Packaging IntegrationThree types of documentation Packaging Integration allows you toare provided to help you develop integrate and package application/applications/ components for the Intel component jar files, SDK library jar filesAppUp 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

Intel AppUpSM developer programPart of the Intel® Software NetworkValidation IntegrationValidation Integration allows you todetermine whether or not an existingjar file complies with the requirementsof the Intel AppUpTM Runnable Jar FileFormat. The Intel AppUpTM SoftwarePackage Utility analyzes runnable jarfiles to help determine this complianceprior to submission to the Intel AppUpdeveloper program portal.Development FlowThe figure below illustrates the high-level development flow for Intel AppUpdeveloper program applications. Thesteps 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

Intel AppUpSM developer programPart of the Intel® Software Network 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: developer program portal. 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 toget 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-insteps 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 applicationa 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 arefolder.) Advanced Error Handling is not Debug ID is used. During development, the only mandatory work to get a Java 5

Intel AppUpSM developer programPart of the Intel® Software Networkapplication running initially. Advanced Step 5: Get and Swap in a Production ID Step 6: Create an Installation PackageError Handling, Instrumentation, and Once your application is working, you Create a single JAR file that includesCrash 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 applicationapplications. Those topics are all covered Application ID before you can submit the manifest file. The Intel AppUp Softwarein Advanced Information. application to the Intel AppUp developer Packaging Utility can help create theseStep 4: Test Application with Intel program portal. Production IDs are Java runnable jar packages. See Using theAppUpTM Software Debugger obtained from the Intel AppUp developer Packaging Utility, for information on using Program portal, which requires that this utility. For general information onThe 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 showswithout requiring the full client or access Step 7: Pre-Validate the Installation part of the authorization code with ato hardware. The Intel AppUp Software Package Production ID included.Debugger allows testing of authorization, Intel validates application packageserror handling, instrumentation, and crash Assume you are enrolled in the Intel submitted to the Intel AppUp developerreporting. AppUp developer program and have program portal prior to publishing them logged into the program portal. StartWith the Intel AppUp SDK Plug-in 1.1 on the Intel AppUpSM center. You should the application submission processfor Eclipse 3.5.2 installed and the Intel become familiar with the validation and provide information that uniquelyAppUpTM SDK code included, you can process so you can pre-validate as many identifies your application. After enteringuse the Eclipse debugger and Intel of the items as possible yourself prior that information, click on the Get a GUIDAppUpTM Software Debugger to debug to submission. This helps to smooth the button on the portal. The site displays ayour application. Intel AppUp Software approval process for your application. The GUID, which is a Production ID. You canDebugger trace information is included Intel AppUp Software Package Validation copy and paste this Production ID intoin 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 validationAppUp 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 AppUpThen start the Eclipse debugger using one you can no longer use the Intel AppUp Developer Program portal. You can thenof 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 theinformation. Then, stop the Intel AppUp Intel AppUp Software Debugger. Advanced InformationSoftware Debugger using one of the This section provides advanced informationfollowing 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

Intel AppUpSM developer programPart of the Intel® Software Network 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 robustAPI Levels recommended approach is to re-throw handling of error and warning the exception. (The method to re-throwThe Intel AppUpTM SDK library provides a exceptions. the exception depends on the applicationmechanism to determine compatibility of The Java SDK library includes includes language and context.) The integratedthe API level of applications versus the three pre-defined exception classes for crash handler in the SDK library thenAPI level of client systems. errors and one pre-defined exception catches the exception and generatesApplications with API levels higher than class for warnings to provide greater a Crash Report using the contextthat supported by the client system granularity in exception handling. You information from the exception. See theare not permitted to be downloaded should consider using these classes to Crash Reporting subsection for details onto 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 exceptionlevel, applications with higher API levels classes are as follows: Code Samplealready installed on the client system The Java code sample below includes Error Exception Classesare not permitted to run. An Intel AppUp a catch for each of the SDK library • InitializationException—Catchescenter Consumer Client can concurrently exception classes and the original error exceptions thrown while thesupport applications with different API default exception handler. Note that SDK library application constructorlevels. you can change the GUID to the ADP_ attempts to initialize the SDK library EXPIRED_APPLICATIONID to test theAPI level information for an application code. This class is derived from application “expired” branch of youris displayed in the Intel AppUp Software AdpErrorException. error handler.Debugger output, as shown in the • UnauthorizedException—CatchesFigure F. This information can be useful Application app = null; error exceptions thrown whilewhen debugging potential issues. the SDK library code attempts to try { authorize the application. This class is 7

Intel AppUpSM developer programPart of the Intel® Software Network 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

Intel AppUpSM developer programPart of the Intel® Software Network 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

Intel AppUpSM developer programPart of the Intel® Software NetworkCustomized Crash Reporting requires column defining the source (SDK or Note: Some crashes can lead to a clientadditional work on the part of the Developer) of the information for the system eventually halting. In thesedeveloper, and an understanding of respective field. cases, the time to store a crash reportthe choices available. The following on the client system may be limited. To Note: It is your responsibility to ensuresubsections introduce the SDK crash maximize obtaining crash information, that custom Crash Reports do notreport classes and provide information you should consider the tradeoffs include any data that violates Intelto 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 versusAbstractCrashReport a potentially narrow window of timeAbstractCrashReport is an abstract The fields with the greatest flexibility to store the information on the clientclass with virtual methods that are for customization are listed below: system.designed to populate data existing • The Category field allows you towithin the class. Since the system may Defining and Calling Custom Crash create categories to sort your crashbe at an unstable state, allocation of Reports reports on the Intel AppUp developerdata on the stack is to be avoided, program portal. For example, you The following example shows theif possible. These methods will be may wish to create categories called framework to define and call a customcalled by the underlying framework to “MEMORY”, “IO”, “USER ERROR”, etc. crash report for Java. The contents ofcollect data to be submitted in crash a custom crash report are defined by • The Error Data field allows you toreports. By implementing a subclass the developer in MyExceptionHandler. create your own stack dumps or longof AbstractCrashReport, you can (Implementation of custom Crash error messages to help you understandgain 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 requiredto implement every field. (Informationon the use of the AbstractCrashReportclass is provided the Intel AppUpSoftware Development Kit APIReference for Java* software document,which is located on the Intel AppUpdeveloper program portal.DefaultCrashReportThe DefaultCrashReport class isa reference implementation of theAbstractCrashReport class and is theclass that provides default crash reports.This default implementation performsbest-effort collection of data thatshould be appropriate and accurate inmost cases. However, you may subclassDefaultCrashReport to customizeone or more fields. An example of acustom crash report derived fromDefaultCrashReport is provided later inthis section.Customizing Crash Reports FieldsThe following table lists the possiblefields in a crash report, with the Source [FIGURE H] 10

Intel AppUpSM developer programPart of the Intel® Software Network 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) { // TODO Auto-generated method stub 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() { // TODO Auto-generated method stub this.errorCategory = “My Error Category”; super.populateErrorData(); } } @Override @Override protected void populateCrashReportFields() { protected void populateLineNumber() { this.crashReportFields = new AdpCrashReportField[1]; // TODO Auto-generated method stub this.crashReportFields[0] = new AdpCrashReportField(“Sub_ super.populateLineNumber(); Category”, } “Trapped Error”); } @Override protected void populateMessage() { @Override // TODO Auto-generated method stub protected void populateErrorData() { this.errorMessage = “User of illegal method”; // TODO Auto-generated method stub } super.populateErrorData(); } @Override protected void populateModuleName() { @Override // TODO Auto-generated method stub protected void populateLineNumber() { super.populateModuleName(); // TODO Auto-generated method stub } super.populateLineNumber(); } } 11

Intel AppUpSM developer programPart of the Intel® Software Network 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 ofUsing the Intel AppUp Software • F11 key the application. It is the responsibilityDebugger of the component developer to enforce • Eclipse Start Debugger menu item the license, i.e., to ensure that the callingThe SDK includes the Intel Intel AppUp Intel AppUpTM Software Debugger output application has a license to use yourSoftware Debugger that emulates the is displayed in a dedicated debugger component.Application Services of the Intel AppUp window. To stop debugging, first stopcenter 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 GuidelinesDebugger allows testing of authorization, • Eclipse Stop Debugger icon • Component Exampleerror handling, instrumentation, and crash • Eclipse Stop Debugger menu itemreporting. • Application Using Component Example This allows you to examine the traceWith the Intel AppUpTM SDK Plug-in information. Then, stop the Intel AppUpTM The information in this section assumesfor Eclipse software installed and the Software Debugger using one of the you have already read the information onIntel AppUpTM SDK code included, you following methods: applications in the previous sections ofcan use the Eclipse debugger and Intel this document. • Intel AppUpTM Software Debugger StopAppUpTM Software Debugger to debug icon in Eclipseyour application. Intel AppUpTM SoftwareDebugger trace information is included • Intel AppUpTM Software Debugger Stopin the Intel AppUpTM Software Debugger item from the Eclipse menuwindow. The figure below shows the Intel AppUpTMTo start debugging, first start the Intel Software Debugger window with debugAppUpTM 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

Intel AppUpSM developer programPart of the Intel® Software NetworkComponent Guidelines component is created using the superclass Application Using Component Example Constructor super. A Component DebugIn general, developing a component is much The application’s use of the component ID is used and exceptions are defined. Thislike developing an application. Components, is shown in the code example below, code appears inside the SDK sample filehowever, are different in several ways. The which is found in AdpAdvanceSample. AdpAdvanceSample (shipped with thefollowing guidelines address the unique AdpAdvanceSample is a sample GUI SDK), but in reality would be available toaspects 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 ExampleThe following code shows a componentexample in Java. SampleComponent isa component that displays a greetingmessage to the screen, then returns. The [FIGURE J] 13

Intel AppUpSM developer programPart of the Intel® Software Network 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, andUsing the Packaging Utility AppUp(TM) Software Development Spanish characters. Characters from Kit->Java->Intel AppUpTM Packaging other languages may cause the utility toThe SDK for Java includes the Intel Utility for Java* software to launch the generate error messages. (Even if theAppUpTM Software Packaging Utility that utility. You can also double-click on the utility generates a jar file that containsintegrates and packages the required jar adp_packager.jar file in the SDK directory. unsupported characters, the applicationfiles and application manifest into a single The Packaging Utility launches and displays may fail validation if submitted to the Inteljar 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 PackagingUtility meets the requirements of the IntelAppUpTM 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 ManifestFor added flexibility, the Packaging Utilityallows developers to export packagesettings to an XML file or to import packagesettings from an XML file.The following steps describe how to usethe Packaging Utility:Step 1: Launch the Software PackagingUtilityClick Start->All Programs->Intel [FIGURE L] 14

Intel AppUpSM developer programPart of the Intel® Software Network 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 Newthe main application jar filename. Fields button to open the Property Definition Note: The Export button is discussed atwith an asterisk are mandatory. Click the screen. Then enter the property name and the end of this section under Exportingupper 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 differentselect the following file: elements of the value.• appup_sdk_java_1.1.jarContinue using the Add button to browseto and add any other files to be included inthe final jar file. To remove a file from thelist, select the file and click the Removebutton.Click the lower Browse button andbrowse to select the location and filenamefor the output file. When finished,click Next to move to the Set RuntimeEnvironment screen.Step 3: Set Runtime EnvironmentSpecify any Program Arguments (ifneeded) for the application invocation.Arguments must be separated by spaces.Characters such as a comma or a colon aretreated as part of the argument they arenext to. Returns are permitted. [FIGURE N] 15

Intel AppUpSM developer programPart of the Intel® Software NetworkExporting and Importing Package SettingsThe Package Completion screen in Figure N provides an Export button to save the currentpackage 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 DEVELOPERexisting XML file. You can browse to select the desired XML file. PROGRAM INCENTIVES:Using the Package Validation Utility INTEL® ATOMTM DEVELOPERThe SDK for Java includes the Intel AppUp Software Package Validation Utility that TM MILLION DOLLAR FUNDanalyzes runnable jar files to help determine if they comply with the Intel AppUpTM Through this fund, we supportRunnable Jar File Specification. The Package Validation Utility should be used prior to software developers andsubmitting the jar file to the Intel AppUpSM Developer Program portal. The utility can help companies creating newspeed the approval process for applications by allowing the developer to catch and correct experiences through applicationspackaging 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 validationperformed by Intel for approval of applications. Files that pass this Package ValidationUtility may still have approval issues, and ultimately may not be approved by Intel, after INTEL APPUPSMsubmission to the Intel AppUpSM Developer Program portal. DEVELOPER CHALLENGE The contest is designed toThe following steps describe how to use the Package Validation Utility: encourage breakthroughStep 1: Launch the Software Package Validation Utility applications that fundamentally change the user experience on aClick Start->All Programs->Intel AppUpTM Software Development Kit->Java->Intel netbook featuring an Intel AtomAppUpTM 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 PackageValidation Utility launches and displays the jar package selection screen shown in Figure O. LEGENDSThe Browse… button allows you to select a jar file to validate. The Validate button Want application visibility? Thestarts the validation sequence on the selected file. The Cancel button closes the utility. Legends program is a way to shareClick 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 ValidationClick 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 applicationThe utility then prompts you to indicate whether or not the application launchedsuccessfully, as shown in Figure P.After checking to see if the application launched successfully, click Yes or No, dependingon your observerations. 16

Intel AppUpSM developer programPart of the Intel® Software Network MORE JAVA* SDK RESOURCES • Download the AppUpSM Java*[FIGURE P] SDK • Java* SDK TechnicalStep 3: Validation Results OverviewThe utility displays the Validation Results screen as shown below. The utility also writes • Java* Packaging Guidelinesa summary of the analysis to Report.xml. • API Reference Guide for JavaClick OK to close the screen and exit the Package Validation Utility. Or click Open Reportto open the Report.xml file that was just created. (Report.xml contains the results of • Java* Developer Guidethe most current validation attempt. This file is overwritten with new data each time • Release Notes Java* SDKthe Validation Utility is run.) • Release Notes for EclipseYou 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, developer tools, and resources[FIGURE Q] and best practices. • Intel® Software Network • Intel® Software Development ProductsDisclaimers and Legal InformationINFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS. NO LICENSE, EXPRESS ORIMPLIED, 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 USEOF 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 FORANY APPLICATION IN WHICH THE FAILURE OF THE INTEL PRODUCT COULD CREATE A SITUATION WHERE PERSONALINJURY OR DEATH MAY OCCUR.Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on theabsence or characteristics of any features or instructions marked “reserved” or “undefined.” Intel reserves these for future definitionand shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The informationhere 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 todeviate 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 bycalling 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, IntelSingleDriver, 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, andXeon 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.

http://www.readwriteweb.com	137
http://static.slidesharecdn.com	1
http://www.netvibes.com	1
http://notepad.com	1
http://www.expertulpc.com	1

Intel AppUp Java Developer Guide

by ReadWriteWeb on Jan 20, 2011

Accessibility

Upload Details

Usage Rights

5 Embeds 141

Statistics

Intel AppUp Java Developer Guide Document Transcript