JavaRosa is a Java library for rendering forms that are compliant with ODK XForms spec. It is at the heart of many of the ODK tools. ODK JavaRosa is a fork of JavaRosa 1.0 that has been modified to NOT run on J2ME devices. The key differences are:
- Regularly updated to ensure spec compliance
- KoBo additional instance defn. and filter paths
- remember all bind attributes and any additional attributes on
<group>, etc. statements
- numerous enhancements and contributions from SurveyCTO and others.
- J2ME sub-projects removed
ODK JavaRosa is part of Open Data Kit (ODK), a free and open-source set of tools which help organizations author, field, and manage mobile data collection solutions. Learn more about the Open Data Kit project and its history here and read about example ODK deployments here.
- ODK website: https://opendatakit.org
- ODK forum: https://forum.opendatakit.org
- ODK developer Slack chat: http://slack.opendatakit.org
- ODK developer Slack archive: http://opendatakit.slackarchive.io
- ODK developer wiki: https://github.com/opendatakit/opendatakit/wiki
Setting up your development environment
Fork the javarosa project (why and how to fork)
Clone your fork of the project locally. At the command line:
git clone https://github.com/YOUR-GITHUB-USERNAME/javarosa
We recommend using IntelliJ IDEA for development. On the welcome screen, click
Import Project, navigate to your javarosa folder, and select the
build.gradle file. Use the defaults through the wizard. Once the project is imported, IntelliJ may ask you to update your remote Maven repositories. Follow the instructions to do so.
Building the project
To build the project, go to the
View menu, then
Tool Windows > Gradle.
build will be in
odk-javarosa > Tasks > build > build. Double-click
build to package the application. This Gradle task will now be the default action in your
To package a jar, use the
jar Gradle task.
Any and all contributions to the project are welcome. ODK JavaRosa is used across the world primarily by organizations with a social purpose so you can have real impact!
If you're ready to contribute code, see the contribution guide.
Per-commit debug builds can be found on CircleCI. Login with your GitHub account, click the build you'd like, then find the JAR in the Artifacts tab under $CIRCLE_ARTIFACTS.
Publishing the jar to OSSRH and Maven Central
Project maintainers have the private keys to upload signed jars to Sonatype's OSS Repository Hosting (OSSRH) service which is then synced to Maven's Central Repository. This process is outlined here.
While Gradle is the default build tool for all ODK tools (including this one), Maven is used for for publishing the jar because OSSRH's Gradle support is unreliable (e.g., snapshots don't always update). This means version and dependency changes must be made in both
Deviations from OSSRH's documentation are that maintainers use
gpg2 v2.1 and greater (not
gpg), the latest versions of the Maven plugins in
pom.xml, and a
secrets.xml file that include the GPG home directory, key name, and pass phrase. All that is needed in the GPG home directory is
<!-- secrets.xml --> <settings> <servers> <server> <id>ossrh</id> <username>opendatakit</username> <password>very-secure-password</password> </server> </servers> <profiles> <profile> <id>ossrh</id> <activation> <activeByDefault>true</activeByDefault> </activation> <properties> <gpg.executable>/path/to/gpg2</gpg.executable> <gpg.homedir>/path/to/javarosa/gpg/folder</gpg.homedir> <gpg.keyname>1234ABCD</gpg.keyname> <gpg.passphrase>very-secure-passphrase</gpg.passphrase> </properties> </profile> </profiles> </settings>
Official releases are typically done by @yanokwa who uses Oracle Java v1.8.x running on macOS Sierra.
To generate official signed releases, you'll need the GPG folder, GPG passwords, a configured
- Update the version in
pom.xmland merge the changes to master.
x.x.x-SNAPSHOTfor snapshots releases and
x.x.xfor production releases.
- In the repo folder, run
mvn -s secrets.xml clean deployto publish.
Don't forget to update the
build.gradle files in any downstream tools (e.g., ODK Collect, ODK Briefcase) to the newest version!