ome.api
Interface IAdmin

All Superinterfaces:
ServiceInterface
All Known Subinterfaces:
LocalAdmin
All Known Implementing Classes:
AdminImpl

public interface IAdmin
extends ServiceInterface

Administration interface providing access to admin-only functionality as well as JMX-based server access and selected user functions. Most methods require membership in privileged groups. Methods which return Experimenter or ExperimenterGroup instances fetch and load all related instances of ExperimenterGroup or Experimenter, respectively.

Since:
OME3.0
Version:
3.0 (Internal version: $Revision: 3282 $ $Date: 2009-01-12 08:49:39 +0000 (Mon, 12 Jan 2009) $)
Author:

Josh Moore      josh.moore@gmx.de

Method Summary
 void addGroups(ome.model.meta.Experimenter user, ome.model.meta.ExperimenterGroup... groups)
          adds a user to the given groups.
 boolean canUpdate(ome.model.IObject obj)
          Returns true if the currently logged in user can modify the given IObject.
 void changeExpiredCredentials(String name, String oldCred, String newCred)
          Used after an ExpiredCredentialsException instance is thrown.
 void changeGroup(ome.model.IObject iObject, String groupName)
          call details.setGroup() on this instance.
 void changeOwner(ome.model.IObject iObject, String omeName)
          call details.setOwner() on this instance.
 void changePassword(String newPassword)
          change the password for the current user
 void changePermissions(ome.model.IObject iObject, ome.model.internal.Permissions perms)
          call defaults.setPermissions() on this instance.
 void changeUserPassword(String omeName, String newPassword)
          change the password for the a given user.
 ome.model.meta.Experimenter[] containedExperimenters(long groupId)
          fetch all users contained in this group.
 ome.model.meta.ExperimenterGroup[] containedGroups(long experimenterId)
          fetch all groups of which the given user is a member.
 long createExperimenter(ome.model.meta.Experimenter experimenter, ome.model.meta.ExperimenterGroup defaultGroup, ome.model.meta.ExperimenterGroup... otherGroups)
          create and return a new user in the given groups.
 long createExperimenterWithPassword(ome.model.meta.Experimenter experimenter, String password, ome.model.meta.ExperimenterGroup defaultGroup, ome.model.meta.ExperimenterGroup... otherGroups)
          create and return a new user in the given groups with password.
 long createGroup(ome.model.meta.ExperimenterGroup group)
          create and return a new group.
 long createSystemUser(ome.model.meta.Experimenter newSystemUser)
          create and return a new system user.
 long createUser(ome.model.meta.Experimenter newUser, String group)
          create and return a new user.
 void deleteExperimenter(ome.model.meta.Experimenter user)
          removes a user by removing the password information for that user as well as all GroupExperimenterMap instances.
 void deleteGroup(ome.model.meta.ExperimenterGroup group)
          removes a group by first removing all users in the group, and then deleting the actual ExperimenterGroup instance.
 ome.model.meta.ExperimenterGroup getDefaultGroup(long experimenterId)
          retrieve the default group for the given user id.
 EventContext getEventContext()
          returns an implementation of EventContext loaded with the security for the current user and thread.
 ome.model.meta.Experimenter getExperimenter(long id)
          fetch an Experimenter and all related groups.
 ome.model.meta.ExperimenterGroup getGroup(long id)
          fetch an ExperimenterGroup and all contained users.
 Roles getSecurityRoles()
          returns the active Roles in use by the server.
 ome.model.meta.Experimenter lookupExperimenter(String omeName)
          look up an Experimenter and all related groups by name.
 List<ome.model.meta.Experimenter> lookupExperimenters()
          Looks up all experimenters present and all related groups.
 ome.model.meta.ExperimenterGroup lookupGroup(String groupName)
          look up an ExperimenterGroup and all contained users by name.
 List<ome.model.meta.ExperimenterGroup> lookupGroups()
          Looks up all groups present and all related experimenters.
 String lookupLdapAuthExperimenter(long id)
          Looks up experimenters who uses LDAP authentication (has set dn on password table).
 List<Map<String,Object>> lookupLdapAuthExperimenters()
          Looks up all id of experimenters who uses LDAP authentication (has set dn on password table).
 void removeGroups(ome.model.meta.Experimenter user, ome.model.meta.ExperimenterGroup... groups)
          removes a user from the given groups.
 void reportForgottenPassword(String name, String email)
          Can be used after repeated AuthenticationException instances are thrown, to request that an email with a temporary password be sent.
 void setDefaultGroup(ome.model.meta.Experimenter user, ome.model.meta.ExperimenterGroup group)
          sets the default group for a given user.
 void setGroupOwner(ome.model.meta.ExperimenterGroup group, ome.model.meta.Experimenter owner)
          sets the owner of a group to be a given user.
 void synchronizeLoginCache()
          uses JMX to refresh the login cache if supported.
 boolean[] unlock(ome.model.IObject... iObjects)
          checks an entity for any in-bound references and if none are present, will remove the Permissions.Flag.LOCKED status.
 void updateExperimenter(ome.model.meta.Experimenter experimenter)
          Updates an experimenter as admin.
 void updateExperimenterWithPassword(ome.model.meta.Experimenter experimenter, String password)
          Updates an experimenter as admin.
 void updateGroup(ome.model.meta.ExperimenterGroup group)
          Updates a group.
 void updateSelf(ome.model.meta.Experimenter experimenter)
          Allows a user to update his/her own information.
 

Method Detail

canUpdate

boolean canUpdate(ome.model.IObject obj)
Returns true if the currently logged in user can modify the given IObject. This uses the same logic that would be applied during a Hibernate flush to the database.


getExperimenter

ome.model.meta.Experimenter getExperimenter(long id)
fetch an Experimenter and all related groups.

Parameters:
id - id of the Experimenter
Returns:
an Experimenter. Never null.
Throws:
ome.conditions.ApiUsageException - if id does not exist.

lookupExperimenter

ome.model.meta.Experimenter lookupExperimenter(String omeName)
look up an Experimenter and all related groups by name.

Parameters:
omeName - Name of the Experimenter
Returns:
an Experimenter. Never null.
Throws:
ome.conditions.ApiUsageException - if omeName does not exist.

lookupExperimenters

List<ome.model.meta.Experimenter> lookupExperimenters()
Looks up all experimenters present and all related groups.

Returns:
all Experimenters. Never null.

lookupLdapAuthExperimenters

List<Map<String,Object>> lookupLdapAuthExperimenters()
Looks up all id of experimenters who uses LDAP authentication (has set dn on password table).

Returns:
list of Experimenters. Never null.

lookupLdapAuthExperimenter

String lookupLdapAuthExperimenter(long id)
Looks up experimenters who uses LDAP authentication (has set dn on password table).

Returns:
Experimenter. Never null.

getGroup

ome.model.meta.ExperimenterGroup getGroup(long id)
fetch an ExperimenterGroup and all contained users.

Parameters:
id - id of the ExperimenterGroup
Returns:
an ExperimenterGroup. Never null.
Throws:
ome.conditions.ApiUsageException - if id does not exist.

lookupGroup

ome.model.meta.ExperimenterGroup lookupGroup(String groupName)
look up an ExperimenterGroup and all contained users by name.

Parameters:
groupName - Name of the ExperimenterGroup
Returns:
an ExperimenterGroup. Never null.
Throws:
ome.conditions.ApiUsageException - if groupName does not exist.

lookupGroups

List<ome.model.meta.ExperimenterGroup> lookupGroups()
Looks up all groups present and all related experimenters. The experimenters' groups are also loaded.

Returns:
all Groups. Never null.

containedExperimenters

ome.model.meta.Experimenter[] containedExperimenters(long groupId)
fetch all users contained in this group. The returned users will have all fields filled in and all collections unloaded.

Parameters:
groupId - id of the ExperimenterGroup
Returns:
non-null array of all users in this group.

containedGroups

ome.model.meta.ExperimenterGroup[] containedGroups(long experimenterId)
fetch all groups of which the given user is a member. The returned groups will have all fields filled in and all collections unloaded.

Parameters:
experimenterId - id of the Experimenter. Not null.
Returns:
non-null array of all groups for this user.

getDefaultGroup

ome.model.meta.ExperimenterGroup getDefaultGroup(long experimenterId)
retrieve the default group for the given user id.

Parameters:
experimenterId - of the Experimenter. Not null.
Returns:
non-null ExperimenterGroup. If no default group is found, an exception will be thrown.

updateSelf

void updateSelf(ome.model.meta.Experimenter experimenter)
Allows a user to update his/her own information. This is limited to the fields on Experimenter, all other fields (groups, etc.) are ignored. The experimenter argument need not have the proper id nor the proper omeName (which is immutable). To change the users default group (which is the only other customizable option), use setDefaultGroup(Experimenter, ExperimenterGroup)

Parameters:
experimenter - A data transfer object. Only the fields: firstName, middleName, lastName, email, and institution are checked. Not null.
See Also:
setDefaultGroup(Experimenter, ExperimenterGroup)

updateExperimenter

void updateExperimenter(ome.model.meta.Experimenter experimenter)
Updates an experimenter as admin. All aspects of the passed object are taken into account including omeName, groups, and default group.

Parameters:
experimenter - the Experimenter to update.

updateExperimenterWithPassword

void updateExperimenterWithPassword(ome.model.meta.Experimenter experimenter,
                                    String password)
Updates an experimenter as admin. All aspects of the passed object are taken into account including omeName, groups, and default group.

Parameters:
experimenter - the Experimenter to update.
password - Not-null. Must pass validation in the security sub-system.

updateGroup

void updateGroup(ome.model.meta.ExperimenterGroup group)
Updates a group. All aspects of the passed object are taken into account including group name and the included users.

Parameters:
group - the ExperimenterGroup to update.

createUser

long createUser(ome.model.meta.Experimenter newUser,
                String group)
create and return a new user. This user will be created with the default group specified.

Parameters:
newUser - a new Experimenter instance
Returns:
id of the newly created Experimenter

createSystemUser

long createSystemUser(ome.model.meta.Experimenter newSystemUser)
create and return a new system user. This user will be created with the "System" (administration) group as default and will also be in the "user" group.

Parameters:
newUser - a new Experimenter instance
Returns:
id of the newly created Experimenter

createExperimenter

long createExperimenter(ome.model.meta.Experimenter experimenter,
                        ome.model.meta.ExperimenterGroup defaultGroup,
                        ome.model.meta.ExperimenterGroup... otherGroups)
create and return a new user in the given groups.

Parameters:
experimenter - A new Experimenter instance. Not null.
defaultGroup - Instance of ExperimenterGroup. Not null.
otherGroups - Array of ExperimenterGroup instances. Can be null.
Returns:
id of the newly created Experimenter Not null.

createExperimenterWithPassword

long createExperimenterWithPassword(ome.model.meta.Experimenter experimenter,
                                    String password,
                                    ome.model.meta.ExperimenterGroup defaultGroup,
                                    ome.model.meta.ExperimenterGroup... otherGroups)
create and return a new user in the given groups with password.

Parameters:
experimenter - A new Experimenter instance. Not null.
password - Not-null. Must pass validation in the security sub-system.
defaultGroup - Instance of ExperimenterGroup. Not null.
otherGroups - Array of ExperimenterGroup instances. Can be null.
Returns:
id of the newly created Experimenter Not null.
Throws:
ome.conditions.SecurityViolation - if the new password is too weak.

createGroup

long createGroup(ome.model.meta.ExperimenterGroup group)
create and return a new group.

Parameters:
newGroup - a new ExperimenterGroup instance. Not null.
Returns:
id of the newly created ExperimenterGroup

addGroups

void addGroups(ome.model.meta.Experimenter user,
               ome.model.meta.ExperimenterGroup... groups)
adds a user to the given groups.

Parameters:
user - A currently managed entity. Not null.
groups - Groups to which the user will be added. Not null.

removeGroups

void removeGroups(ome.model.meta.Experimenter user,
                  ome.model.meta.ExperimenterGroup... groups)
removes a user from the given groups.

Parameters:
user - A currently managed entity. Not null.
groups - Groups from which the user will be removed. Not null.

setDefaultGroup

void setDefaultGroup(ome.model.meta.Experimenter user,
                     ome.model.meta.ExperimenterGroup group)
sets the default group for a given user.

Parameters:
user - A currently managed Experimenter. Not null.
group - The group which should be set as default group for this user. Not null.

setGroupOwner

void setGroupOwner(ome.model.meta.ExperimenterGroup group,
                   ome.model.meta.Experimenter owner)
sets the owner of a group to be a given user.

Parameters:
group - A currently managed ExperimenterGroup. Not null.
owner - A currently managed Experimenter. Not null.

deleteExperimenter

void deleteExperimenter(ome.model.meta.Experimenter user)
removes a user by removing the password information for that user as well as all GroupExperimenterMap instances.

Parameters:
user - Experimenter to be deleted. Not null.

deleteGroup

void deleteGroup(ome.model.meta.ExperimenterGroup group)
removes a group by first removing all users in the group, and then deleting the actual ExperimenterGroup instance.

Parameters:
group - ExperimenterGroup to be deleted. Not null.

changeOwner

void changeOwner(ome.model.IObject iObject,
                 String omeName)
call details.setOwner() on this instance. It is valid for the instance to be unloaded (or constructed with an unloading-constructor.)

Parameters:
iObject - An entity or an unloaded reference to an entity. Not null.
omeName - The user name who should gain ownership of this entity. Not null.

changeGroup

void changeGroup(ome.model.IObject iObject,
                 String groupName)
call details.setGroup() on this instance. It is valid for the instance to be unloaded (or constructed with an unloading-constructor.)

Parameters:
iObject - An entity or an unloaded reference to an entity. Not null.
groupName - The group name who should gain ownership of this entity. Not null.

changePermissions

void changePermissions(ome.model.IObject iObject,
                       ome.model.internal.Permissions perms)
call defaults.setPermissions() on this instance. It is valid for the instance to be unloaded (or constructed with an unloading-constructor.)

Parameters:
iObject - An entity or an unloaded reference to an entity. Not null.
perms - The permissions value for this entity. Not null.

unlock

boolean[] unlock(ome.model.IObject... iObjects)
checks an entity for any in-bound references and if none are present, will remove the Permissions.Flag.LOCKED status. This method is backend- intensive and should not be used in a tight loop. Returns an array with length equal to the number of instances passed in. A true value means that the object is now unlocked.

Parameters:
iObjects - a variable array argument of objects to be unlocked
Returns:
an array of equal length to iObjects where a true value asserts that the instance is now unlocked in the database.

reportForgottenPassword

void reportForgottenPassword(String name,
                             String email)
                             throws ome.conditions.AuthenticationException
Can be used after repeated AuthenticationException instances are thrown, to request that an email with a temporary password be sent. The given email must match the email for the user listed under the name argument. Does not require a session to be active.

Parameters:
name -
email -
Throws:
ome.conditions.AuthenticationException - when name and email do not match

changeExpiredCredentials

void changeExpiredCredentials(String name,
                              String oldCred,
                              String newCred)
                              throws ome.conditions.AuthenticationException
Used after an ExpiredCredentialsException instance is thrown. Does not require

Throws:
ome.conditions.AuthenticationException

changePassword

void changePassword(String newPassword)
change the password for the current user

Parameters:
newPassword - Not-null. Must pass validation in the security sub-system.
Throws:
ome.conditions.SecurityViolation - if the new password is too weak.

changeUserPassword

void changeUserPassword(String omeName,
                        String newPassword)
change the password for the a given user.

Parameters:
newPassword - Not-null. Might must pass validation in the security sub-system.
Throws:
ome.conditions.SecurityViolation - if the new password is too weak.

synchronizeLoginCache

void synchronizeLoginCache()
uses JMX to refresh the login cache if supported. Some backends may not provide refreshing. This may be called internally during some other administrative tasks. The exact implementation of this depends on the application server and the authentication/authorization backend.


getSecurityRoles

Roles getSecurityRoles()
returns the active Roles in use by the server.

Returns:
Non-null, immutable Roles instance.

getEventContext

EventContext getEventContext()
returns an implementation of EventContext loaded with the security for the current user and thread. If called remotely, not all values of EventContext will be sensible.

Returns:
Non-null, immutable EventContext instance


OmeroJava Api

Version: Beta-4.1.1-r5927-b91

Copyright © 2009 The University of Dundee. All Rights Reserved.