Extending OMERO.server
======================
.. topic:: Overview
Despite all the effort put into building OMERO, it will never
satisfy the requirements of every group. Where we have seen it
useful to do so, we have created extension points which can be used
by third-party developers to extend, improve, and adapt OMERO. We
outline most of these options below as well as some of their
trade-offs. We are also always interested to hear other possible
extension points. Please contact the :mailinglist:`ome-devel mailing list `
with any such suggestions.
Existing extension points
-------------------------
To get a feeling for what type of extension points are available, you
might want to take a look at the following pages. Many of them will
point you back to this page for packaging and deploying your new code.
- :doc:`/developers/Search/FileParsers` - write Java file parsers to
further extend search
- :doc:`/developers/Server/LoginAttemptListener` - write a
Java handler for failed login attempts
- :doc:`/developers/cli/index` - write drop in Python extensions
for the command-line
- :doc:`/developers/scripts/index` - write python scripts to
process data server-side
- :doc:`/developers/Server/Ldap` - write a Java authentication
plugin
- :doc:`/developers/Server/PasswordProvider` - write a Java
password backend
- :doc:`/developers/Modules/Search/Bridges` - write Java Lucene parsers
to extend search
- :doc:`/sysadmins/mail` - server email sender (added in OMERO 5.1, no
developer documentation as yet)
- :property:`omero.policy.bean` - policy configuration point e.g. for setting
download restriction policy on users (added in OMERO 5.1, no developer
documentation as yet)
Extending the Model
-------------------
The OME Data Model and its OMERO representation, the |OmeroModel|,
intentionally draw lines between what metadata can be supported and what
cannot. Though we are always examining new fields for inclusion, it is not
possible to represent everyone's model within OME.
Structured annotations
^^^^^^^^^^^^^^^^^^^^^^
The primary extension point for including external data are the
:doc:`/developers/Model/StructuredAnnotations` (SAs). SAs
are designed as email-like attachments which can be associated with
various core metadata types. In general, they should link to information
outside of the OME model, i.e. information which OMERO clients and
servers do not understand. URLs can point to external data
sources, or XML in a non-OME namespace can be attached.
The primary drawbacks are that the attachments are opaque and cannot be
used in a fine-grain manner.
Code generation
^^^^^^^^^^^^^^^
Since it is prohibitive to model full objects with the SAs, one alternative is
to add types directly to the :doc:`generated code `. By
adding a file named ``*.ome.xml`` to
:sourcedir:`components/model/resources/mappings` and running a full-build, it
is possible to have new objects generated in all
:doc:`/developers/server-blitz` languages. Supported fields include:
- boolean
- string
- long
- double
- timestamp
- links to any other ``ome.model.*`` object, including enumerations
For example:
::
Collections of primitive values like
```` are not supported. Please see
the existing mapping files for more examples of what can be done.
The primary drawback of code-generating your own types is isolation and
maintenance. Firstly, your installation becomes isolated from the rest
of the OME ecosystem. New types are not understood by other servers and
clients, and cannot be exported or shared. Secondly, you will need to
maintain your own server **and** client builds of the system, since the
provided binary builds would not have your new types.
Measurement results
^^^^^^^^^^^^^^^^^^^
For storing large quantities of only partially structured data, such as
tabular/CSV data with no pre-defined columns, neither the SAs nor the
code-generation extensions are ideal. SAs cannot easily be aggregated,
and code-generation would generate too many types. This is particularly
clear in the storage and management of HCS analysis results.
To solve this problem, we provide the :ref:`OMERO.tables ` API
for storing tabular data indexed via Roi, Well, or Image id.
Services
--------
Traditionally, services were added via Java interfaces in the
:sourcedir:`components/common/src/ome/api`
package. The creation of such "core" services is described under
:doc:`/developers/Server/HowToCreateAService`. However,
with the introduction of :doc:`/developers/server-blitz`, it is also
possible to write blitz-only services which are defined by a slice
definition under :sourcedir:`components/blitz/resources/omero`.
A core service is required when server internal code should also make
use of the interface. Since this is very rarely the case for third-party
developers wanting to extend OMERO, only the creation of blitz services
will be discussed here.
Add a slice definition
^^^^^^^^^^^^^^^^^^^^^^
The easiest possible service definition in slice is:
::
module example {
interface NewService {
void doSomething();
};
};
This should be added to any existing or a new ``*.ice`` file under the
``blitz/resources/omero`` directory. After the next ant build, stubs
will be created for all the :doc:`/developers/server-blitz` languages,
i.e. |OmeroJava|, |OmeroPy|, and |OmeroCpp|.
.. note::
Once you have gotten your code working, it is most re-usable
if you can put it all in a single directory under tools/. These
components also have their ``resources/*.ice`` files turned into code,
and they can produce their own artifacts which you can distribute
without modifying the main code base.
Warning: exceptions
^^^^^^^^^^^^^^^^^^^
You will need to think carefully about what exceptions to handle. Ice
(especially |OmeroCpp|) does not handle exceptions
well that are not strictly defined. In general, if you would like to add
your own exception type, feel free to do so, but either 1) subclass
``omero::ServerError`` or 2) add to the appropriate ``throws`` clauses.
And regardless, if you are accessing any internal OMERO API, add
``omero::ServerError`` to your ``throws`` clause.
See :doc:`/developers/Modules/ExceptionHandling` for more
information.
Java implementation using _Disp
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To implement your service, create a class subclassing
"example.\_NewServiceDisp" class which was code-generated. In this
example, the class would be named "NewServiceI" by convention. If this
service needs to make use of any of the internal API, it should do so
via dependency injection. For example, to use IQuery add either:
::
void setLocalQuery(LocalQuery query) {
this.query = query;
}
or
::
NewServiceI(LocalQuery query) {
this.query = query;
}
The next step "Java Configuration" will take care of how those objects
get injected.
Java implementation using _Tie
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Rather than subclassing the ``_Disp`` object, it is also possible to
implement the ``_Tie`` interface for your new service. This allows
wrapping and testing your implementation more easily at the cost of a
little indirection. You can see how such an object is configured in
:source:`blitz-servantDefinitions `.
Java configuration
^^^^^^^^^^^^^^^^^^
Configuration in the Java servers takes place via Spring_. One or more files
matching a pattern like ``ome/services/blitz-*.xml`` should be added to your
application.
::
This is a simple bean definition in Spring. The description is not necessary.
The three patterns which are available are:
- ``ome/services/blitz-*.xml`` - highest-level objects which have
access to all the other defined objects.
- ``ome/services/services-*.xml`` - internal server objects which do
not have access to ``blitz-*.xml`` objects.
- ``ome/services/db-*.xml`` - base connection and security objects.
These will be included in background java process like the index and
pixeldata handlers.
.. note::
:doc:`/developers/Server/PasswordProvider` and similar should
be included at this level.
See :sourcedir:`components/blitz/resources/ome/services`
and :sourcedir:`components/server/resources/ome/services`
for all the available objects.
.. _JavaDeployment:
Java deployment
^^^^^^^^^^^^^^^
Finally, these resources should all be added to
``OMERO_DIST/lib/server/extensions.jar``:
- the code generated classes
- your ``NewServiceI.class`` file and any related classes
- your ``ome/service/blitz-*.xml`` file (or other XML)
Non-service beans
^^^^^^^^^^^^^^^^^
In addition to writing your own services, the instructions above can be
used to package any Spring-bean into the OMERO server. For example:
::
//
// MyLoginAttemptListener.java
//
import ome.services.messages.LoginAttemptMessage;
import org.springframework.context.ApplicationListener;
/**
* Trivial listener for login attempts.
*/
public class MyLoginAttemptListener implements
ApplicationListener {
public void onApplicationEvent(LoginAttemptMessage lam) {
if (lam.success != null && !lam.success) {
// Do something
}
}
}
::
This listener will be added to the Spring runtime and listen for all LoginAttemptMessages.
Putting ``MyLoginAttemptListener.class`` and
``ome/services/blitz-myLoginListener.xml`` into
``lib/server/extensions.jar`` is enough to activate your code:
::
~/example $ ls -1
MyLoginListener.class
MyLoginListener.java
lib
...
~/example $ jar cvf lib/server/extensions.jar MyLoginListener.class ome/services/blitz-myLoginListener.xml
added manifest
adding: MyLoginListener.class(in = 0) (out= 0)(stored 0%)
adding: ome/services/blitz-myLoginListener.xml(in = 0) (out= 0)(stored 0%)
Servers
-------
With the |OmeroGrid| infrastructure, it is possible to have your own
processes managed by the OMERO infrastructure. For example, at some
sites, `NGINX `_ is started to
host |OmeroWeb|. Better integration is possible however, if your server
also uses the Ice_ remoting framework.
One way or the other, to have your server started, monitored, and
eventually shutdown by |OmeroGrid|, you will need
to add it to the "application descriptor" for your site. When using:
::
bin/omero admin start
the application descriptor used is :file:`etc/grid/default.xml`.
The ```` element contains various ````\ s. Each node
is a single daemon process that can start and stop other processes.
Inside the nodes, you can either directly add a ```` element, or
in order to reuse your description, you can use a ````
which must refer to a ````.
To clarify with an example, if you have a simple
application which should watch for newly created Images and send you an
email: ``mail_on_import.py``, you could add this in either of the following
ways:
Server element
^^^^^^^^^^^^^^
::
${PYTHONPATH}
Server-template and server-instance elements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
${PYTHONPATH}
.. seealso::
:ome-devel:`[ome-devel] model description driven code generation <2009-July/001332.html>`