Building the J2ME Demo Project for JavaRosa
Setting up the J2ME Demo for JavaRosa is easy, but requires many steps and a programmer's expertise. Please read over this entire page first, before starting the install process. Once you start, follow the instructions carefully and use the versions we list and the install locations we suggest.
Some steps may be complicated by specific issues. Please review the details of a step before performing it to see if there are more specific instructions which are relevant to you
Before getting started, please keep the following in mind
- Ant, not eclipse, is the build tool for JavaRosa. If eclipse shows errors, but the build.xml file works without issue, the build is fine. If eclipse is configured correctly it should not show problems, but plugins and changes make this occasionally difficult.
- Eclipse doesn't update folders automatically when they are changed from outside Eclipse. If the tutorial mentions a file that you do not see in your Package Explorer, click on the project and refresh by pressing F5.
- Keeping up with minor version changes is difficult, so labels and menu structures may have changed slightly. If the directions seem clear, continue with the tutorial, but please come back and update it for future users.
- Please make sure to download the exact version of anything which mentions a version until you've had success with the basic instructions.
- Make sure that you download 32-bit versions of both Eclipse and Java. Certain features of the emulator will not work with 64-bit Java and 64-bit Eclipse will not work with 32-bit Java. Installing a 32-bit JDK may require uninstalling previous versions.
Installing the Development Environment
- Install TortoiseHg.
- Install JDK 6.0 Update NN.
- Install Sun Java Wireless Toolkit for CLDC v2.5.2_01.
- Install to the non-default location of C:\WTK2.5.2.
- Install J2MEPolish-v2.1.0-- Later or earlier J2MEPolish versions will not work.
- If using Windows Vista or Windows 7, additional instructions should be followed here
- Install J2MEPolish to C:\Program Files\J2ME-Polish
- If you already have a different version of Polish installed additional instructions should be followed here
- Set the WTK directory during the install process to C:\WTK2.5.2.
- Install Eclipse IDE for Java Developers.
- Install to C:\Eclipse.
- Install EclipseME v1.7.9 plugin.
- Use Eclipse update location http://www.eclipseme.org/updates.
- If you are using Eclipse Galileo, you will most probably get stuck on the 'Review Licenses' screen, with the 'Finish' button disabled even though you have accepted the terms. To resolve, 'Install New Software..." -> Add Ganymede as a location: http://download.eclipse.org/releases/ganymede/.
- Use Eclipse update location http://www.eclipseme.org/updates.
Configuring the Development Environment
- Start up Eclipse and Create a new Workspace
- Click on File -> Switch Workspace -> Other.
- Specify a new folder for your JavaRosa workspace.
- Click on Window -> Preferences.
- Expand the Java ME node, go to Device Management -> Manual Install....
- Specify C:\WTK2.5.2 as your search directory, select Refresh and upon completion, select Finish.
- Double click each device listing and edit the group to read Sun Java(TM) Wireless Toolkit 2.5.2 for CLDC.
- Select DefaultColorPhone (or another phone of choice) as your default.
- Expand the Java node, and expand Build Path -> Classpath Variables.
- Define a new classpath variable by clicking New....
- Name the variable J2ME_POLISH_HOME and set its value to the installation directory of J2MEPolish (usually C:\Program Files\J2ME-Polish)
- Select Installed JREs from the Java node you just expanded.
- Click Add... -> Standard VM, and select the folder where the JDK resides (usually C:\Program Files\Java\jdk1.6.0_nn).
- Enter -Xmx128M into the Default VM Arguments field.
- Now select Finish. Enable the JDK as default by checking the checkbox.
- Restart Eclipse.
Downloading the Source Code
- Using the Windows Explorer, locate the folder you used for the JavaRosa workspace.
It should contain a folder called .metadata
- Right click in that folder, and select TortoiseHG... -> Clone a Repository
- Enter the Source Path http://bitbucket.org/javarosa/javarosa. Ensure that the Destination Path is the workspace folder.
- Click Clone to clone the repository. This will download the JavaRosa source code.
- Note that your javarosa repository folder (the folder that contains .hg/) must be inside your eclipse workspace folder (the folder that contains .metadata/); if they are the same folder, you will have problems
- Return to Eclipse, and go to the menu File -> Import -> General -> Existing Projects into Workspace
- Select the javarosa folder you created and select all projects. Deselect any projects that you aren't interested in and don't need the code for your application. This will likely include everything in util/ (org.javarosa.rmstest, schema-generator, and validator-*) Make sure to deselect the "Copy files into workspace" option. If you aren't sure what to deselect, simply click Finish.
- Download the most recent libraries that JavaRosa depends upon from javarosa-dependencies-rNNNN.zip.
- Right click on the file, and select Extract.
- Change the path so you extract and merge into your javarosa folder.
- This step should go through the javarosa folder and insert jars into multiple places
- In Eclipse, select all projects, right click, and Refresh and wait for the refresh.
- Open up the javarosa-libs project, make sure it contains a number of jar files like regexp-me.jar. If not, something went wrong. Try to extract the libraries again.
Configuring the Source Code
- Your workspace should almost be free of errors. You will probably see the error Project 'j2me-javarosa' is missing required library: 'tools/j2merosa-libraries.jar'. Under the j2me-javarosa project.
- Inside of the j2me-javarosa project, open the build.properties file.
- Find the line containing polish.home=... and make sure it points to your J2ME-Polish installation directory
- Now double click build.xml in the j2me-javarosa project. This is the ant file responsible for building JavaRosa.
- On the right hand side of the screen you will see a pane labeled Outline.
- Right click on JavaRosa at the top of the outline and select Run As -> External Tools Configuration.
- Go to the JRE tab, and choose Separate JRE. The JDK you added earlier in the tutorial should be selected.
- Click Apply, then Close
- Now Right click on the target labeled BuildClean and select Run As -> Ant Build
- The build should finish, and the j2me-javarosa folder should now contain a jar called j2merosa-libraries.jar
- Your projects should now have no errors. If you see errors, go to Project -> Clean... -> OK.
- If you see a WTP Metadata error, right click on the concerned folder and choose Validate.
Running the Demo
- Again, under the j2me-javarosa project, double click on the build.xml file to go to the ant build script.
- Right click on the BuildCleanRunEmulator target in the Outline. Go to Run As... -> Ant Build.
- The build script will run and launch the WTK Emulator. If it does not, ask for help on the mailing list or ask to be added to the skype chat, so we can provide feedback.
Beyond the Demo
Looking through the demo source code will give you most of the information needed to build a J2MERosa application. As you become a more advanced user, you may also want to check out other javarosa projects.
To start adding new features to javarosa, rather than just building custom deployments based on the existing featureset, you'll have to start editing core code. This is the code that went into the 'j2merosa-libraries' jar used before.