<ANTENNA/>

Antenna

An Ant-to-End Solution For Wireless Java

Version 1.2.1

Setup

Setting up Antenna is rather straightforward. The first thing you want to do is either put the Antenna JAR file into Ant's lib directory or your classpath. Then there's a number of properties you might want to adjust to your needs, either in each build.xml file you use or in a global file that is imported in the specific build.xml files.

<taskdef resource="antenna.properties"/>

If you don't want to put Antenna into your classpath, the following variant also works:

<taskdef resource="antenna.properties" classpath="full name of Antenna jar file"/>

Selecting a WTK and APIs for a project

All Antenna tasks rely on a property "wtk.home" that points to the directory where the Wireless Toolkit has been installed. So, if your WTK resides in "c:\Java_ME_platform_SDK_3.0", you need to add the following line to your build scripts:

<property name="wtk.home" value="c:\Java_ME_platform_SDK_3.0"/>

Depending on which WTK you are using, a different set of base and extension APIs is available for your MIDlets. Antenna automatically detects your WTK version and selects APIs according to the following simple rule: The default BOOTCLASSPATH consists CLDC and MIDP libraries for your CLDC and MIDP version with no extension APIs. If your want to change these settings, you can do so by using the following properties :

Property Default Purpose

wtk.cldc.version 1.0 Specifies the version of CLDC to use.

wtk.midp.version 1.0 Specifies the version of MIDP to use.

wtk.mmapi.enabled false Enables or disables the Multimedia API (MMAPI).

wtk.wma.enabled false Enables or disables the Wireless Messaging API (WMA) 1.0 (JSR-120).

wtk.wma2.enabled false Enables or disables the Wireless Messaging API (WMA) 2.0 (JSR-205).

wtk.j2mews.enabled false Enables or disables the J2ME Web Services API (J2MEWS).

wtk.bluetooth.enabled false Enables or disables the J2ME Bluetooth API (JSR-82).

wtk.java3d.enabled false Enables or disables the J2ME 3D API (JSR-184).

wtk.optionalpda.enabled false Enables or disables the J2ME optional PDA packages (JSR-75).

wtk.locationservices.enabled false Enables or disables the J2ME location services API (JSR-179).

wtk.contenthandler.enabled false Enables or disables the J2ME content handler API (JSR-211).

wtk.satsa.enabled false Enables or disables the J2ME Security and Trust Services API (JSR-177).

wtk.miapi.enabled false Enables or disables the J2ME Mobile Internationalization API (JSR-238).

wtk.ams.enabled false Enables or disables the J2ME Advanced Multimedia Supplements API (JSR-234).

wtk.papi.enabled false Enables or disables the J2ME Payment API (JSR-229).

wtk.s2dvgapi.enabled false Enables or disables the J2ME Scalable 2D Vector Graphics API (JSR-226).

wtk.sipapi.enabled false Enables or disables the J2ME Session Initiation Protocol API (JSR-180).

wtk.all.enabled false Enables all additional libraries (except for CLDC and MIDP) defined for your toolkit.

wtk.midpapi Varies Sets a totally custom BOOTCLASSPATH. Use this property if the set of APIs you need is not covered by the above properties (for example because you are using the system libraries provided another vendor or you have some important additional libraries).

Property	Default	Purpose
wtk.cldc.version	1.0	Specifies the version of CLDC to use.
wtk.midp.version	1.0	Specifies the version of MIDP to use.
wtk.mmapi.enabled	false	Enables or disables the Multimedia API (MMAPI).
wtk.wma.enabled	false	Enables or disables the Wireless Messaging API (WMA) 1.0 (JSR-120).
wtk.wma2.enabled	false	Enables or disables the Wireless Messaging API (WMA) 2.0 (JSR-205).
wtk.j2mews.enabled	false	Enables or disables the J2ME Web Services API (J2MEWS).
wtk.bluetooth.enabled	false	Enables or disables the J2ME Bluetooth API (JSR-82).
wtk.java3d.enabled	false	Enables or disables the J2ME 3D API (JSR-184).
wtk.optionalpda.enabled	false	Enables or disables the J2ME optional PDA packages (JSR-75).
wtk.locationservices.enabled	false	Enables or disables the J2ME location services API (JSR-179).
wtk.contenthandler.enabled	false	Enables or disables the J2ME content handler API (JSR-211).
wtk.satsa.enabled	false	Enables or disables the J2ME Security and Trust Services API (JSR-177).
wtk.miapi.enabled	false	Enables or disables the J2ME Mobile Internationalization API (JSR-238).
wtk.ams.enabled	false	Enables or disables the J2ME Advanced Multimedia Supplements API (JSR-234).
wtk.papi.enabled	false	Enables or disables the J2ME Payment API (JSR-229).
wtk.s2dvgapi.enabled	false	Enables or disables the J2ME Scalable 2D Vector Graphics API (JSR-226).
wtk.sipapi.enabled	false	Enables or disables the J2ME Session Initiation Protocol API (JSR-180).
wtk.all.enabled	false	Enables all additional libraries (except for CLDC and MIDP) defined for your toolkit.
wtk.midpapi	Varies	Sets a totally custom BOOTCLASSPATH. Use this property if the set of APIs you need is not covered by the above properties (for example because you are using the system libraries provided another vendor or you have some important additional libraries).

Please note that the properties for selecting a CLDC and MIDP version also set the default values for the "config" and "profile" properties used in the WtkJad and WtkPackage tasks. So, if you set the versions properly at the beginning of your build.xml file, you normally don't have to deal with these values again.

Supported toolkits

Antenna version 1.2.0 has been tested with the following toolkits:

SUN Java ME SDK 3.0
Sun WTK 2.5.2
MOTODEV SDK for Java ME v2
Nokia S60 3rd edition FP1
Nokia S60 3rd edition FP2
Nokia N97 SDK
SPRINT WTK 332
Samsung_SDK_11 (autodetected as WTK 2.5.2)
SonyEricsson WTK 2.5.2
Nokia S40 5th Edition SDK Feature Pack 1
LG SDK 1.3 for Java ME

For backward compatibility also support for older Toolkit's are included: Sun Wireless Toolkit 1.0, 2.0, 2.1, 2.2, 2.3, iDEN SDK 3.0, 4.0 and i730 SDK.

Adding a new Toolkit

You can add a new toolkit to antenna just by editing a text file and adding another. Do like this: First you add the new toolkit to the file autodetext.txt (in the res directory). It should look something like this: #sony ericsson sonyericwtk2;lib/semc_ext_jp8.jar;lib/cldcapi11.jar Lines starting with # are comments. The lines defining toolkits should start with the toolkit property filename and then contain a list of files that are unique to this toolkit. File names should be relative to wtk.home. Then you add a properties file, in this case sonyericwtk2.properties. It looks something like this:

               name="Sony Ericsson WTK2"
               include=wtk25
               nokiaui=lib/nokiaext.jar
               semc=lib/semc_ext_jp8.jar
               vodafone=lib/vscl21.jar

The properties you could use are:

name: a descriptive name for the toolkit. Use this always.
preverifyversion: 1 means WTK 1 style, support only CLDC 1.0, 2 means WTK 2 style, include Target parameter in preverify command, 3 means WTK 3 style, only add parameter cldc1.0 if cldc 1.0 is used
emulator: exe or jar file for emulator
cldc10,cldc11: libraries for cldc versions
midp10,midp20,midp21: libraries for midp versions
include: include another toolkit definition. Useful if the toolkit is an add-on to another toolkit, like WTK 2.5 or Java ME SDK 3.0

All other properties will be taken for add-on libraries that will be added to classpath if wtk.[propertiy].enabled is true, or if wtk.all.enabled is true.

Toolkit support for optional libraries

JSR API Support	Antenna property	Sun WTK 2.5	Java ME SDK 3.0	MOTODEV Studio for Java ME	Nokia S60 3rd Edition SDK	Nokia N97 SDK	Nokia S40 5^thed	Sony Ericsson SDK 2.5	Sprint WTK 3.3.2	LG SDK 1.3 for Java ME
CLDC version		1.0,1.1	1.0,1.1	1.1	1.1	1.1	1.0, 1.1	1.0, 1.1	1.0, 1.1	1.0, 1.1
MIDP version		1.0,2.0,2.1	1.0,2.0,2.1	2.1(2.0)	2.0,2.1	2.0,2.1	1.0,2.0,2.1	1.0,2.0,2.1	1.0,2.0,2.1	1.0,2.0,2.1
JSR 75 PDA	optionalpda	x	x	x	x	x	x	x	x	x
JSR 82 Bluetooth	Bluetooth	x	x	x	x	x	x	x	x	x
JSR 135 Mobile Media 1.2	mmapi	x	x	x	x	x	x	x	x	x
JSR 172 Web Services	j2mews	x	x	x	x	x	x	x	x	x
JSR 177 Security and Trust Services	satsa	x	x	x	x	x	x	x	x	x
JSR 179 Location	locationservices	x	x	x	x	x		x	x	x
JSR 180 SIP	sipapi	x	x	x	x			x	x	x
JSR 184 Mobile 3D Graphics	java3d	x	x	x	x	x	x	x	x	x
JSR 120 WMA 1.0	wma	x	x	x	x	x	x	x	x	x
JSR 205 Wireless Messaging 2.0	wma2	x	x	x	x	x	x	x	x	x
JSR 209 AGUI	agui		x
JSR 211 Content Handler	contenthandler	x	x	x			x	x	x	x
JSR 226 Scalable 2D Vector Graphics	s2dvgapi	x	x	x	x	x	x	x	x	x
JSR 229 Payment	papi	x	x					x	x	x
JSR 234 Advanced Multimedia Supplements	ams	x	x	x	x	x	x	x	x	x
JSR 238 Mobile Internationalization	miapi	x	x	x				x	x	x
JSR 239 Java Binding for OpenGL ES	opengl	x	x	x				x		x
JSR 256 Mobile Sensor	mobilesensor		x			x				x
JSR 257 Contactless Communication	rfid									x
JSR 280 XML	xml		x
JSR 300 DRM	drm									x
G24 MOTO2MOTO	G24			x
Motorola APIs	motorola			x
Nokia UI API	nokiaui					x	x	x
eSWT API	eswt					x
IAP Info	iapinfo					x

Using the Websphere Micro Environment Toolkit for PalmOS

Starting from version 0.9.11, Antenna also supports the PRC converter from the IBM Websphere Micro Environment Toolkit for PalmOS (WME). This converter is needed to generate PRC files for IBM J9 VM that runs on the new Tungsten devices. To use it, specify the WME's home directory as follows:

<property name="wtk.wme.home" value="your path goes here"/>

The current release of the WME already supports CLDC 1.1 and MIDP 2.0 plus some extension APIs. The MIDP for PalmOS from Sun, in contrast, seems to be pretty much dead. Please note that the name of this property has changed with Antenna 0.9.12 for reasons of consistency.

Using Over-the-Air provisioning

In addition to the various Ant tasks, the project also provides a simple servlet for OTA provisioning of MIDlet suites. This servlet is included in the same ZIP file as the tasks. It allows to upload MIDlet suites via the WtkDeploy task. Once uploaded, a MIDlet suite can be downloaded by WWW and WAP clients. Lists of available suites can be retrieved in HTML and WML. The format of these lists can be modified using a template mechanism.

The following steps are necessary to run the OTA servlet:

Install a servlet-capable Web server, preferredly Tomcat.
Add a new Web application, for example by creating a directory "antenna" under "<tomcat>/webapps". Create a directory "WEB-INF" and a subdirectory "WEB-INF/lib" there.
Copy the "web.xml" file from the "etc" directory of the Antenna source distribution (or from CVS) to "WEB-INF" and adjust it to your personal needs. Copy the "antenna-bin.jar" binary distribution file to "WEB-INF/lib".
You should have a working configuration now. Test it by starting Tomcat and accessing the servlet using a Web browser or the Wireless Toolkit's OTA provisioning mechanism. If the servlet URL is "http://localhost/antenna", the HTML and WML pages are available as "http://localhost/antenna/index.html" and "http://localhost/antenna/index.wml", respectively. When only the directory is specified, the servlet tries to determine the correct version from the HTTP request headers.
Test deployment by running the "deploy" sample (modify "build.xml" first).
To create your own layout for the pages, copy the two files from the "res" directory of the Antenna source distribution (or from CVS) to "WEB-INF" and modify them. There's documentation inside the "index.html" file that tells you how to do this.

If you are running the OTA servlet with modified templates, it would be nice if you added a small hyperlink saying "Powered by Antenna" (pointing to the project's homepage) to the bottom of the page. Same if you modify the servlet itself.

A running version of the servlet should be available on my home machine.