OMERO admin interface
=====================

The one central interface for administering the OMERO security system is
IAdmin. Though several of the methods are restricted to system users
(root and other administrators), many are also for general use. The
``RolesAllowed`` annotations on the
:server_source:`LocalAdmin <src/main/java/ome/api/local/LocalAdmin.java>`
class define who can use which methods.

Actions available through IAdmin and IUpdate
--------------------------------------------

A couple of the methods in the IAdmin interface are also available
implicitly through IUpdate, the main interface for updating the database. This
duplication is mainly useful for large scale changes, such as changing
the permissions to an entire object graph.

-  changePermissions
-  changeGroup

The following shows how these methods can be equivalently used:

::

        // setup
       ServiceFactory sf = new ServiceFactory();
       IAdmin iAdmin = sf.getAdminService();
       IUpdate iUpdate = sf.getUpdateService();
       Image myImg = … ; //
     
       // using IAdmin -- let's change the group of myImg
       // and then make it group private.
       iAdmin.changeGroup(myImg, new ExperimenterGroup( 3L, false ));
       iAdmin.changePermissions( myImg, new Permissions( Permissions.GROUP_PRIVATE ));

       // and do the same using Details and IUpdate
       myImg.getDetails().setPermissions( new Permissions( Permissions.GROUP_PRIVATE )); 
       myImg.getDetails().setGroup( new ExperimenterGroup( 3L, false ));
       iUpdate.saveObject( myImg );

The benefit of the second method is the batching of changes into a
single call. The benefit of the first is at most explicitness. Note,
however, that changing any of the values of Details which are not also
changeable through IAdmin will result in a ``SecurityViolation``.

Actions only available through IAdmin
-------------------------------------

The rest of the write methods provided by IAdmin are disallowed for
IUpdate and will throw ``SecurityViolations``. This includes adding
users, groups, user/group maps, events, enums, or similar. (Enums here
are a special case, because they are created not through IAdmin but
through ITypes). A system administrator may be able to use IUpdate to
create these "System-Types" but using IAdmin is safer, cleaner, and
guaranteed to work in the future.

The password methods and ``synchronizeLoginCache`` are also special cases in
that they have no equivalent in any other API.

Similarities between IAdmin and IQuery
--------------------------------------

All of the read methods provided by IAdmin are also available from
IQuery, that is, the IAdmin (currently) provide no special context or
security privileges. However, having all of the methods in one interface
reduces code duplication, which is especially useful when you want the
entire user/group graph as provided by
getExperimenter/getGroup/lookupExperimenter/lookupGroup.

.. seealso:: 
    |OmeroApi|
