Developer Guidelines :: GBIF IPT User Manual (original) (raw)

Please don’t check in unused files.

Code in the master branch should always compile and allow the startup of Jetty using Maven!

Guice

IptModule contains wiring, but interfaces are annotated directly with @ImplementedBy(ConfigManagerImpl.class)

Configuration

Inside WEB-INF of a running IPT is a single file datadir.location. It points to the currently used data directory where all configuration and data is stored. If this file is deleted the setup interceptor will ask the user to assign a new (potentially existing) data directory.

The hidden file .gbifreg indicates whether the data directory is linked to the production or test registry. Once set, this cannot be changed from the UI!

AppConfig.java contains all IPT wide configuration, in particular the baseURL (referred to in the UI and documentation as the "Public URL") for the application.

Struts2

BaseAction.java supplies the AppConfig, implements session aware and gives access to current user, implements a simpler TextProvider which is faster than the native Struts 2 one.

SetupAndCancelInterceptor.java checks if the data directory is configured and an admin user exists - otherwise redirects to the respective setup page.

For each package (root, portal, manage, admin) its own interceptor stack exists.

The "input" result name is used to show the form. We can therefore use the standard validation interceptor which uses the input result when data doesn’t validate.

The "success" result name is called when the form submit succeeded. In many cases this should simply be a redirect to another, often the corresponding list, action.

The action implements preparable, request aware and the execute method.

execute: FormAction determines if a POST or GET is used and calls save (POST), delete (POST + delete=true) or nothing (GET).

If any other action values need to be set you can override prepare() - but remember to call super.execute().

prepare: the id parameter of the request object is stored in the action.

POSTAction.java simplifies working with forms. For modifying instance data always use POST, never GET. Most full actions for modifying entities should override the following methods:

prepare(): load existing values based on "id" parameter and request object.
save(): persist data AFTER the parameters interceptor did its job.
delete(): this method is called when a POST with a delete=anything_but_null parameter is received.

If the id given does not exist you can set the notFound property to true in any of the above methods. The action will then return a 404 result name.

To do validation, implement the validate() method of an action (instead of using XML validation definitions). See SetupAction.java as an example. Validation requires an input result name that shows the form when the form was not valid. Using the simple theme we also need to declare where to render the validation feedback: http://struts.apache.org/docs/fielderror.html

CSS

Keep number of CSS classes to a minimum and consider using page specific CSS in <head><style> on that page.

Managers

2 tier architecture only with interfaces + implementation.

Internationalization

Templates, actions and also important service messages should be localized using a single ResourceBundle.

Translated vocabularies can be used to populate select drop downs easily by calling getI18nVocab(…).