OMERO Application Programming Interface
Table of Contents
All interaction with the OMERO server takes place via several API services available from a ServiceFactory. A good place to start learning about the OmeroApi is the generated javadoc repository:
After that, take a look at some of the integration tests:
API List
The ome.api package in the common component defines the central "verbs" of the Omero system. All external interactions with the system should happen with these verbs, or services. Each OMERO service belongs to a particular service level with each level calling only on services from lower levels.
Service Level 1 (direct DB and hibernate connections)
Service Level 2
Stateful/Binary Services
- RawFileStore
- RawPixelsStore
- RenderingEngine (see RenderingEngine for more)
- ThumbnailStore
- IScale
Discussion
Reads and Writes
IQuery and IUpdate are the basic building blocks for the rest of the (non-binary) API. IQuery is based on QuerySources? and QueryParemeters? which are explained under ((Omero Queries|Queries)). The goal of this design is to make wildly separate definitions of queries (templates, db-stored , Java code, C# code, ...) runnable on the server.
IUpdate takes any graph composed of IObject objects and checks them for dirtiness. All changes to the graph are stored in the database if the user calling IUpdate has the proper permissions, otherwise an exception is thrown.
Dirty checks follow the Three Commandments:
- Any IObject-valued field with unloaded set to true is treated as a place holder (proxy) and is re-loaded from the DB.
- Any collection-valued field with a null value is re-loaded from the DB.
- Any collection-valued field with the FILTERED flag is assumed to be dirty and is loaded from the DB, with the future option of examing the filtered collection for any new and updated values and applying them to the real collection. (Deletions cannot happen this way since it would be unclear if the object was filtered or deleted.)
Administation
The IAdmin interface defines all the actions necessary to administer the security system . It is explained further on the AdminInterface page.
Pojos
Certain operations, like those deailing with data management and viewing, happen more frequently than others (like defining microscopes). Those have been collected in the IPojos interface. IPojos simplify a few very common queries, and there is a related package ("pojos.*") for working with the returned graphs. The Java Client works almost exclusively with the IPojos interface for its non-binary needs.
Examples
// Saving a simple change Dataset d = iQuery.get( Dataset.class,1L ); d.setName( "test" ); iUpdate.saveObject( d ); // Creating a new object Dataset d = new Dataset(); d.setName( "test" ); // not-null fields must be filled in iUpdate.saveObject( d ); // Retrieving a graph Set<Dataset> ds = iQuery.findAllByQuery( "from Dataset d left outer join d.images where d.name = 'test'",null );
Other topics
Stateless versus Stateful Services
A stateless service has no client-noticeable lifecycle and all instances can be treated equally. A new stateful service, on the other hand, will be created for each client-side proxy (see the ServiceFactory.create* methods). Once obtained, a stateful service proxy can only be used by a single user. After task completion, the service should be closed (proxy.close()) to free up server resources.
How to write a service
A tutorial is available on to write a service at wiki/HowToCreateAService. In general, if a properly annotated service is placed in any JAR of the OMERO EAR file (see OmeroBuild for more) then the service will be deployed to the server. In the case of OmeroBlitz, the service must be properly defined under source:trunk/components/blitz/resources/.
Omero Annotations for Validation
The server-side implementation of these interfaces makes use of ((JDK5)) ((Omero Annotations)) and an ((Omero AOP|AOP)) interceptor to validate all method parameters. Calls to pojos.findContainerHierarches are first caught by a method interceptor, which checks for annotations on the parameters and, if available, performs the necessary checks. The interceptor also makes proactive checks. For a range of parameters types (such as Java Collections) it requires that annotations exist and will refuse to proceed if not implemented.
An api call of the form:
pojos.findContainerHierarches(Class,Set,Map)
is implemented as
pojos.findContainerHierarchies(@NotNull Class, @NotNull @Validate(Integer.class) Set, Map)
See also: OmeroQueries | PixelService? | RenderingEngine | ExceptionHandling
