Developing with OMERO

Server-side

Quick how-to

• Add to common/src/ome/api interface "I[API]" Run "ant install" for common
• Add to server/src/ome/logic class "[API]Impl"
• Code. (This may include writing queries, tasks, etc. )
• Update spring configuration in: server/resources/ome/services/services.xml
• Write test by extending AbstractManagedContextTest

Client-side

If you are satisfied with working with the generated domain model objects directly, working with the server is nearly trivial. You simply need to supply connection paramters, either in a spring.properties on your classpath or through system variables. After that, all calls on any ServiceFactory? object will return a functioning proxy.

If, however, the possible instability of this worries you, it is straight forward to design an adapter around the existing model and API. To implement an adapter, you will need to define your own domain model objects (thin-wrappers) and provide an implementation of the unit-of-work interfaces for your service.

Using Eclipse

There are currently .project and .classpath files stored in subversion in each component directory (e.g. common's .classpath and common's .project). These require require a successful build to have taken place:

   java omero prepare-eclipse

This is for two reasons. One, the Eclipse projects are not configured to perform the code-generation needed. This creates the directory:

    COMPONENT/target/generated/src

which will be missing from any Eclipse project you open before building the source.

Also, Ivy is used to copy all the jar dependencies from OMERO_HOME/lib/repository to COMPONENT/target/libs, which is then used in the Eclipse .classpath files.

Unit-Testing

The unit testing framework is fairly simple. Only methods which contain logic written within the OMERO are tested. This means that framework functionality like remoting is not tested. Neither is Hibernate functionality; this is a part of integration testing. (see below)

Therefore, most of the code which is unit tested lies in the logic packages of the server component. This is done using jMock.

You can run the unit tests for any component from its directory by entering:

 java omero -f components/<component>/build.xml test

The same can be done for all components using from the top-level directory with the command:

 java omero build-all

Integration-Testing

Integration testing is a bit more complex because of the reliance on a database (which is not easily mockable), all Hibernate related classes are tested in integration mode.

To run integration tests, use java omero integration like the java omero test command above.

Running integration tests places several restrictions on the environment:

• There must be a running OMERO database.
• It must contain some projects, datasets, images, image annotations, dataset annotations, classifications, categories, and category groups.
• An application server should be running.

These tests could break for a number of reasons. Patience is needed.

Writing your own tests

For more information on writing tests in general see http://testng.org. For a test to be an "integration" test, place it in the "integration" testng-group. If a test is temporarily broken, add it to the "broken" or "ignore" group.

Place your test in the test directory of the proper component. (Previous restrictions about package names like "utests" or "itests" are no longer relevant.)

For each test that is run, a report is produced in COMPONENT_NAME/target/reports. Here, you can find all exceptions or failures. View with "mozilla target/reports/index.html".

If you want to see which tests are failing run with:

 java omero strict-test

( "ant strict-test" might work as well.)

The tests should continue running with JUnit3 as well (you can try this with the "junittest" target, though for that you may have to use "java omero":

 java omero -f components/rendering/build.xml junittest

Debugging a running OMERO instance

Once you have the Omero-EJB component and the Client-EJB component working in Eclipse and the Omero-APP deployed to JBoss, you can debug the server remotely by doing the following.

1. Install the JBoss-IDE (there is an Eclipse update site available.
2. Copy the JBoss run script bin/run.sh to bin/debug.sh and add two lines:

   # Execute the JVM
      "$JAVA" $JAVA_OPTS \
         -Xdebug \ <----------------------------------------------------------------Add this
         -Xrunjdwp:server=y,transport=dt_socket,address=4142,suspend=n \ <---and this
         -Djava.endorsed.dirs="$JBOSS_ENDORSED_DIRS" \
         -classpath "$JBOSS_CLASSPATH" \
         org.jboss.Main "$@"
      STATUS=$?
      # if it doesn't work, you may want to take a look at this:
      #    http://developer.java.sun.com/developer/bugParade/bugs/4465334.html
   done
   

3. Create a new debug configuration of type JBoss remote.
4. Set the port value to match the value you added to debug.sh (here 4142)
5. Click on Debug and you'll see your running threads. You can now place break points as you see fit.
6. Create a run configuration for your code:
7. Run your code and you'll see your JBoss threads get suspended. Once JBoss threads are suspended you can step through them just like local debugging:
8. Here you can see the client process and the server debug session running side by side.

Note: If you take too much time examining your threads, your calls may throw timeout exceptions.

---

See also: OmeroInstall, OmeroContributing, OmeroCommunity