Directories and packages in jMoby

This document explains the structure of the jMoby CVS directory - which may help developers to decide where to put their new code. And it also summarizes contents of Java packages - so the developers can easier add their own packages (and doing so they are encouraged to update this document).

jMoby directories

The following directories names in the CVS space are worth to mention:

src

Source code should be (almost only) put in one of the following places (Ant will automatically compiles all sources stored here, except the code in the sub-directories named notyet):

src/main: This is the main place to put your source code. Put here all packages unless the other places (see below) seem more appropriate.
src/Clients: This is the place for standalone clients. I would recommend to put here only clients that do not use any package name - otherwise put them in src/main/org/biomoby/client.
src/samples: This is the place for code that is not compiled automatically by Ant (so it does not break anything), and its purpose is to give examples, tutorial or other didactic material. You can compile anything put here using Ant' target samples-compile.
There is also a directory src/samples-resources where you can put various files (property files, testing data etc.) that should be found by the sample code. All these files will be packed together with the samples code when Ant's target samples-jar is called.

src/config

Files here serve for configuration and for running things. They are supposed to be copied (by Ant) to some other place (usually to the build directory), perhaps with some modifications (so here can be actually templates of the real things), and to be used/run from there.

src/support

Files in this directory are used as templates when creating various binary distributions. They are not intended to be used per se. If you put new files here make sure that Ant (build.xml file) knows what to do with them.

src/webapps

Here are files and templates that are used when the servlets war files are being created.

docs

A place for the public documentation. The contents of this sub-directory - once committed - is visible from the main BioMoby page http://www.biomoby.org/moby-live/Java/docs/. The Ant (target docs) also puts here (in the docs/API sub-directory) the generated (javadoc) API documentation.

doc-dev

A place for casual documentation. This is meant for developers notes - it is visible for the CVS users but it is not visible from the main BioMoby page.

data

A place for data files used by various tutorials or examples.

xmls

A place for additional fragments used by Ant's build.xml.

jMoby packages

One of the Ben's Twelve Commandments suggests to "think carefully about package names". This chapter aims to help with such decisions.

Base (high-level) package names

There are several high-level package names - and everybody is welcome to make more specialized packages within (below) these packages. Of course, you are also free to create your packages outside of these pre-defined packages - but if you do so try first to establish an argument why you do so (one obvious argument would be, for example, that you wish to keep your institution name in the package name - which is possible, see another Ben's Commandment about it).

org.biomoby.client: It contains components used to develop Moby clients. The Moby clients can be both clients of the Moby registry and clients of the Moby services.
org.biomoby.registry: It contains components helping with Moby registry. These components are supposed to be used by those who are running a registry. At the moment, there is not many components here, because most of the registry implementation is in Perl. Note that if you write code that uses registry by calling its API methods you should put it into the org.biomoby.client package because in fact you are a client of the registry. Here should go components that use direct access to the registry databases (like a direct JDBC access), or here we may have Java-implementation of the whole registry someday.
org.biomoby.service: It contains general components that can be used by those writing code for Moby services. This is not meant to be used for the service-specific code - such as a business logic to get to a plant database at MIPS (for that I assume the developer will have his/her own package name which is not committed to the jMoby CVS) - but for general components that can be re-used by any/many service providers for their services.
org.biomoby.shared: It contains components that are used by classes from more than one package above. The bottom-line (or a bottom-rule) is: If one wants to run clients, it must be sufficent for him to pack all classes from org.biomoby.client and from org.biomoby.shared only. If one wants to create a registry oriented component, it is enough for him to pack org.biomoby.registry and org.biomoby.shared. And similarly for service providers which would pack org.biomoby.service and org.biomoby.shared.
Additionally the org.biomoby.shared package is a good place for putting there Java interfaces - assuming that they are expected to be used more generally. For example, here is Central.java - an interface defining an access to a Moby registry.

Other package names

Please feel free (or better: feel obliged) to add here basic descriptions of your own packages. You may also consider to add a package.html file directly into your package directory (to the same sub-directory where your sources are) - such files will be picked up by Ant and included directly in the generated API.

Martin Senger

Last modified: Thu Feb 14 15:10:15 2008