This section is not about developing applications with Orbeon Forms, but about developing Orbeon Forms itself. It is for those who want to modify the code of Orbeon Forms. This documentation provided here is very much work in progress. If you would like to contribute to the Orbeon Forms development and don't find all the information you are looking for here, please feel free to join the ops-users mailing list and ask your question on the list.

At any time you can download a nightly build, which is a build of the latest Orbeon Forms source code.

Unlike released versions of Orbeon Forms, nightly builds are not tested before they are made available. The only guarantee is that nightly builds pass the Orbeon Forms unit tests. A build that does not pass all the unit tests is not uploaded to the nightly build directory. The Orbeon Forms developers are doing their best not to cause any regression in nightly builds, so in most cases you can use nightly builds for development. If you notice any regression is a nightly build, please report it on ops-users.

The name "nightly builds" seems to imply that they are created only once a day. In fact, nightly builds are created at all time during the day, whenever a modification occurs on the code repository. So there might in fact be several nightly builds in a day of development is active during that day, or no new build if nothing was checked in the repository that day.

First note that if your main reason for getting the source is to have a build of Orbeon Forms with the latest code, we recommend that you instead download a nightly build (see above).

The source code of Orbeon Forms is available on the CVS repository hosted by ObjectWeb. To checkout the source code on your local machine, follow the instructions provided on the project CVS page under the Anonymous CVS Access.

We build Orbeon Forms with Ant. The Ant configuration file (build.xml) is located at the root of the source directory. You can start Ant from the command line. If you are using an IDE like Eclipse or IntelliJ, you can also use the builtin Ant support provided by your IDE. The Orbeon Forms build.xml defines a number of targets, but only a few are used frequently:

• orbeon-war: Build Orbeon Forms and creates an exploded war file in the directory build/ops-war. To test your modifications to the Orbeon Forms code, you will typically run a Tomcat with a context pointing to that directory. That context, defined in Tomcat's server.xml will typically look like:

  <Context crossContext="true" debug="0" docBase="path to your source/build/ops-war" path="/ops" reloadable="false"/>

• orbeon-dist-war: This will build a "distribution" war file, which is equivalent to the war file created by our automated build system and uploaded to the "unstable builds" directory. The produced file will be located in build/distrib/ops.war

During development, you can choose to compile Java files with your IDE instead of compiling them with Ant. You might want to do this because the compiler that comes in your IDE is faster than javac, or reports better errors. Often the main reason is to be able to leverage HotSwap in the JVM. HotSwap works by starting the VM in debug mode and connecting to the VM with your IDE. As your application is running, you can then modify the Java code, and recompile it with your IDE. After the IDE has successfully compiled any modified Java file, it will send the new code to the JVM, which will replace the old code with the new code.

HotSwap still has limitations: it is not a silver bullet and there will be cases where you will need to redeploy the web application or restart the application server. But you will spare yourself a redeployment or restart in most of the cases where your modification to the Java code does not significantly change the structure of the Java class. If you are using IntelliJ, you can find more information about HotSwap on their site.

To compile files from your IDE:

• Ant setup:
  • Set the skip.compilation Ant property (you just need to have this property set some value; the value of the property does not matter).
  • If you have compiled code before without this property, run first the clean Ant task.
  • With the skip.compilation property set, run the orbeon-war Ant task.
• IDE setup:
  • Set your IDE to generate class files in build/ops-war/WEB-INF/classes.
  • Point your IDE to the jar files in the lib directory, as the Orbeon Forms code has dependencies on those libraries.
  • Setup your IDE to compile the files in src/java. Exclude all the classes in the following packages:
    • org.orbeon.oxf.processor.bpel
    Also exclude the following classes:
    • org.orbeon.oxf.resources.CacheImport
    • org.orbeon.oxf.resources.CacheResourceManagerFactory
    • org.orbeon.oxf.resources.CacheResourceManagerImpl
    • org.orbeon.oxf.resources.XMLDBImport
• Once this setup is done:
  • Compile all the sources a first time before you start the application server.
  • Start the application server in debug mode.
  • Connect to the application server with your IDE.
  • Now comes the interesting part: modify Java code whenever you want, compile it, and your IDE will send the new code to the JVM which will on the fly use this new code instead of the old one.