Read-Me

Welcome!

This directory contains the PreEmptive Analytics Java API, its documentation, and some samples. We especially appreciate your suggestions to how we can improve the API to meet your needs. Please send your comments or suggestions to support@preemptive.com.

Important Links

• Changes File
• Support and Updates for PreEmptive Solutions products
• Technical support e-mail: support@preemptive.com

PreEmptive Analytics

The APIs in this directory support PreEmptive Analytics which can be used to give application authors and users insight into how their applications are being used.

The PreEmptive Analytics API is just like any other Java library. Choose the JAR for your application and add it to your project:

• lib/pa-java15.jar - For Java desktop or server applications using Java 1.5 and up
• lib/pa-j2me.jar - For Java 2 Platform, Micro Edition (J2ME)
• lib/pa-bb45.jar - For RIM Blackberry v4.5 and up
• lib/pa-android4.jar - For Google Android API Level 4 (Android 1.6) and up

The Javadoc for these APIs are included in this directory.

To use the API you will need two GUIDs:

• A Company ID - This is a GUID that should be used consistently for all your applications. Depending on your scenario, PreEmptive may have created one for you, or you may be able to generate an arbitrary one for yourself.
• An Application ID - This is a GUID of your choosing for a single application.

You want to use the same Application ID for the entire application's lifetime, even when you release new versions: PreEmptive Analytics tracks your application's version via RuntimeIntelligence.setApplicationVersion().

API Usage Pattern

The general usage pattern of the API is:

• Call configuration APIs that define the combination of the company, application, and additional options
• Begin the interaction with an Application Start
• Request the transmission of multiple messages which include:
  • Feature Ticks to mark the occurrence of a tracked event
  • Feature Start and Feature Stop paired messages to record the duration of a tracked event
  • System Profile to report information about the platform
  • Performance Probe to report CPU and memory usage
  • Exception Reports to record error conditions
• End interaction with an Application Stop

Observing Generated Data

To aid in the quick testing of your use of the APIs this directory includes a WAR file that you can deploy locally for testing purposes. The sink.war contains a simple servlet that prints out the headers and the body of HTTP requests. To use this for testing you need to perform the following steps:

1. Deploy the WAR file to a servlet container such as Apache Tomcat on your local machine
2. Use HTTP rather that HTTPS by calling setUseSsl(false)
3. Set the endpoint to point to the machine and port where the WAR file is deployed by calling setServiceEndpoint("host:port/sink/Sink")

Messages that your application generates will be echoed by the servlet rather than being sent to the PA Server. If using Tomcat, you can see them in the localhost log.

Remember to comment out or remove the calls to setUseSsl() and setServiceEndpoint() before releasing your application!

Samples

Provided are some samples which use the PreEmptive Analytics APIs.

• samples/jsp-pa
  An example WAR file using the tag libraries. See the Read-me for details.
• samples/log4j
  Use log4j to generate analytics messages and exception reporting without instrumentation. See here for special instructions.
• samples/pa-api
  A simple example using the Java PA API.