<ANTENNA/>

Antenna

An Ant-to-End Solution For Wireless Java

Version 0.9.15-beta

(c) 2002-2007 Jörg Pleumann

News | Overview | Download | Setup | JAD | Build | Package | MakePRC | RAPC
Run | Preverify | Obfuscate | SmartLink | Preprocess | Deploy | Sign | History |

News

Antenna 1.0.0. is out This is a bugfix release of 0.9.15, the bump in version number is due to a mistake with the version number of the previous release. The following things have been fixed: Antenna 0.9.15-beta is out! There are several new features and improvements in this release which was contributed by Omry Yadan, who joined the project recently

Overview

Antenna provides a set of Ant tasks suitable for developing wireless Java applications targeted at the Mobile Information Device Profile (MIDP). With Antenna, you can compile, preverify, package, obfuscate, and run your MIDP applications (aka MIDlets), manipulate Java Application Descriptor (JAD) files, as well as convert JAR files to PRC files designed to run on the MIDP for PalmOS implementations from Sun and IBM. Deployment is supported via a deployment task and a corresponding HTTP servlet for Over-the-Air (OTA) provisioning. A small preprocessor allows to generate different variants of a MIDlet from a single source.

Of course you can also do much of that with the J2ME Wireless Toolkit or other Java IDEs, but using an Ant script results in a defined and reproducable build process that is independent of a particular programming environment. See this article for an excellent introduction to Ant as well as reasons for using it.

The Antenna tasks are mostly built around functionality provided by the Wireless Toolkit and thus require this software. If you want to make use of the obfuscation task, you should have one (or both) of the free RetroGuard and ProGuard obfuscators on your harddisk. Naturally, Ant itself is also needed, where version 1.5.0 seems to be the minimum required version as reported by users. Antenna works very well in Ant-supportive IDEs like Eclipse or JEdit.

Here is a list of tasks contained in the package:

Task Purpose
WtkJad A task that is able to create new JAD files from scratch or update existing ones.
WtkBuild An extension to Ant's standard javac task that sets the appropriate bootclasspath allows for preverification.
WtkPackage An extension to Ant's standard jar task that handles the JAD file correctly and is able to include complete libraries into the resulting JAR file. It also allows for preverification and obfuscation of the generated file.
WtkMakePrc A task to convert an existing JAR/JAD into a PalmOS PRC file that can be used with MIDP for Palm OS.
WtkRun A task to run a MIDlet suite contained in a JAR/JAD file in the Wireless Toolkit's emulator.
WtkRapc A task that invokes the BlackBerry rapc compiler, and generates BlackBerry .cod files.
WtkPreverify A standalone task for preverifying a set of classes. This task is normally not needed, since the build and packaging tasks include the same functionality.
WtkObfuscate A standalone task for obfuscating a JAR file. This task is normally not needed, since the packaging task includes the same functionality.
WtkSmartLink A task for removing unnecessary classes from a JAR file.
WtkPreprocess A simple Java preprocessor, similar to the ones known from C and other languages, that allows for conditional compilation and including source files.
WtkDeploy A deployment task that allows to put a MIDlet on a remote Web server for later download.
WtkSign A task for signing midlets

Samples

There are several sample build.xml files in the "samples" subdirectory of the Antenna source distribution. These files show how to build the default demo MIDlets contained in the Wireless Toolkit and some others. Running the samples is a good way to test your setup as well as a good starting point for your own build.xml files. The Antenna project is hosted on SourceForge and distributed under the GNU Lesser General Public License (LGPL). You can download the most recent version here.

Mailing List

There's also a mailing list for discussing Antenna. You can subscribe to the list here,
list archives are available here

Contact

If you find Antenna useful, you might want to send a picture postcard of your hometown or country telling me so. My surface mail address is: Jצrg Pleumann, Amselstrasse 41, D-45472 M�lheim, Germany. E-mails are also fine, but don't underestimate the productivity (and ego) boost that a wall full of postcards next to my desk will cause. :)

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 should also work: 
<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\wtk-1.0.4", you need to add the following line to your build scripts: 

<property name="wtk.home" value="c:\Java\wtk-1.0.4"/>
Depending on the WTK version 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 of CLDC-1.0 and MIDP 1.0 with no extension APIs. If your want to change these settings, you can do so by using the following properties (the "WTK" column specifies WTK version required for this property to be taken into account):

Property Default Purpose WTK
wtk.cldc.version 1.0 Specifies the version of CLDC to use. 2.1+
wtk.midp.version 2.0 for WTK 2.x, 1.0 otherwise. Specifies the version of MIDP to use. 2.0+
wtk.mmapi.enabled false Enables or disables the Multimedia API (MMAPI). 2.0+
wtk.wma.enabled false Enables or disables the Wireless Messaging API (WMA). 2.0+
wtk.wma.version 1.0 Selects the supported version of the Wireless Messaging API (WMA). Currently either 1.0 (JSR-120) or 2.0 (JSR-205) is allowed. 2.3+
wtk.j2mews.enabled false Enables or disables the J2ME Web Services API (J2MEWS). 2.1+
wtk.bluetooth.enabled false Enables or disables the J2ME Bluetooth API (JSR-82). 2.2+
wtk.java3d.enabled false Enables or disables the J2ME 3D API (JSR-184). 2.2+
wtk.optionalpda.enabled false Enables or disables the J2ME optional PDA packages (JSR-75). 2.2+
wtk.locationservices.enabled false Enables or disables the J2ME location services API (JSR-179). 2.3+
wtk.contenthandler.enabled false Enables or disables the J2ME content handler API (JSR-211). 2.3+
wtk.satsa.enabled false Enables or disables the J2ME Security and Trust Services API (JSR-177). 2.3+
wtk.miapi.enabled false Enables or disables the J2ME Mobile Internationalization API (JSR-238). 2.5+
wtk.ams.enabled false Enables or disables the J2ME Advanced Multimedia Supplements API (JSR-234). 2.5+
wtk.papi.enabled false Enables or disables the J2ME Payment API (JSR-229). 2.5+
wtk.s2dvgapi.enabled false Enables or disables the J2ME Scalable 2D Vector Graphics API (JSR-226). 2.5+
wtk.sipapi.enabled false Enables or disables the J2ME Session Initiation Protocol API (JSR-180). 2.5+
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). 1.0+

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.

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:

  1. Install a servlet-capable Web server, preferredly Tomcat.
  2. 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.
  3. 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".
  4. 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.
  5. Test deployment by running the "deploy" sample (modify "build.xml" first).
  6. 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.

SourceForge.net Logo