Aspect-oriented programming
===========================

Aspect-oriented programming is, among other things, the attempt to
define and centralize cross-cutting concerns. In other words, it is not
much more than the tried-and-true principle of modularization. Having
possibly unseen aspects operating on a given class however, can
complicate an initial examination of the code. Therefore, it is important
to be aware of what portions of the OMERO code base are "advised" and
where to find the advisors (in the case of OMERO solely interceptors).

In Spring_, advisors are declared in the bean definition files (under
:server_sourcedir:`src/main/resources/ome/services`,
:server_source:`services.xml <src/main/resources/ome/services/services.xml>`,
:server_source:`hibernate.xml <src/main/resources/ome/services/hibernate.xml>`,
and others.

In these configuration files, various Spring beans (shared objects) are
defined with names like "proxyHandler", "eventHandler",
"serviceHandler", and "transactionHandler". Each of these is a method
interceptor which is passed execution before the actual logic is
reached. The interceptor can inspect or replace the return value, but
can also stop the method execution from ever taking place.

Unlike with `AspectJ <https://eclipse.org/aspectj/>`_, the AOP
implementation used by OMERO only allows for the advising of interfaces.
Simply creating a new service implementation via "new QueryImpl()" will
not produce an advised object, which in turn will not function
properly, if at all. Instead, advised objects can only be acquired
from the Spring :doc:`context </developers/Server/Context>`.

By and large, only the :doc:`API service methods </developers/Modules/Api>` 
are advised in OMERO.

Why?
----

Often, when implementing or adding code, it becomes clear just how many
requirements are placed by libraries, the application server, and
existing code on any new code. This can include transaction handling,
session handling, security checks, object validation, logging etc. As a
code-base grows, these dependencies slow development and make code
unmanageable. AOP tries to reduce these dependencies by defining each of
these concerns in a single place.

As a quick example, in OMERO transactions and exceptions are handled
through method interceptors. Rather than writing:

::

        void method1(){
            try {

                Transaction tx = new Transaction();
                tx.begin();
                // your code goes here
                tx.commit();
            } catch (TxException e) {
                 tx.rollback();
            } catch (OtherException e) {

            }

        }

you just write:

::

        void method1(){
            // your code goes here
        }

.. seealso::

    :springdoc:`Aspect Oriented Programming <2.0.x/reference/aop.html>`
        Chapter of the Spring documentation    

    `AOP Alliance  <http://aopalliance.sourceforge.net/>`_
        Joint project defining interfaces for various AOP implementations
     
    `AspectJ <https://eclipse.org/aspectj/>`_ 
        The arguable leader in Java/AOP development. Not used in Omero, but a
        good starting point.

    `Aspect-oriented programming <https://en.wikipedia.org/wiki/Aspect-oriented_programming>`_
        Wikipedia page on AOP