Version: 5.3.3-ice35-b63

OmeroBlitz API

omero::api::IAdmin

Overview

[ "ami", "amd" ] 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 omero::model::ExperimenterGroup groups. Methods which return model::Experimenter or model::ExperimenterGroup instances fetch and load all related instances of model::ExperimenterGroup or model::Experimenter, respectively.

Operation Index

canUpdate

Returns true if the currently logged in user can modify the given model::IObject.

getExperimenter

Fetches an model::Experimenter and all related model::ExperimenterGroup.

lookupExperimenter

Looks up an model::Experimenter and all related model::ExperimenterGroup by name.

lookupExperimenters

Looks up all model::Experimenter experimenters present and all related model::ExperimenterGroup groups.

getGroup

Fetches an model::ExperimenterGroup and all contained model::Experimenter users.

lookupGroup

Looks up an model::ExperimenterGroup and all contained model::Experimenter users by name.

lookupGroups

Looks up all model::ExperimenterGroup groups present and all related model::Experimenter experimenters.

containedExperimenters

Fetches all model::Experimenter users contained in this group.

containedGroups

Fetches all model::ExperimenterGroup groups of which the given user is a member.

getDefaultGroup

Retrieves the default model::ExperimenterGroup group for the given user id.

lookupLdapAuthExperimenter

Looks up model::Experimenter experimenters who use LDAP authentication (has set dn on password table).

lookupLdapAuthExperimenters

Looks up all ids of model::Experimenter experimenters who use LDAP authentication (has set dn on password table).

getMemberOfGroupIds

Finds the ids for all groups for which the given model::Experimenter is a member.

getLeaderOfGroupIds

Finds the ids for all groups for which the given model::Experimenter is owner/leader.

updateSelf

Allows a user to update his/her own information.

uploadMyUserPhoto

Uploads a photo for the user which will be displayed on his/her profile.

getMyUserPhotos

Retrieves the model::OriginalFile object attached to this user as specified by uploadMyUserPhoto.

updateExperimenter

Updates an experimenter if admin or owner of group.

updateExperimenterWithPassword

Updates an experimenter if admin or owner of group.

updateGroup

Updates an experimenter group if admin or owner of group.

createUser

Creates and returns a new user.

createSystemUser

Creates and returns a new system user.

createExperimenter

Creates and returns a new user in the given groups.

createExperimenterWithPassword

Creates and returns a new user in the given groups with password.

createGroup

Creates and returns a new group.

addGroups

Adds a user to the given groups.

removeGroups

Removes an experimenter from the given groups.

setDefaultGroup

Sets the default group for a given user.

setGroupOwner

Adds the user to the owner list for this group.

unsetGroupOwner

Removes the user from the owner list for this group.

addGroupOwners

Adds the given users to the owner list for this group.

removeGroupOwners

removes the given users from the owner list for this group.

deleteExperimenter

Removes a user by removing the password information for that user as well as all model::GroupExperimenterMap instances.

deleteGroup

Removes a group by first removing all users in the group, and then deleting the actual model::ExperimenterGroup instance.

changeOwner

Deprecated.

changeGroup

Deprecated.

changePermissions

Deprecated.

moveToCommonSpace

Moves the given objects into the user group to make them visible and linkable from all security contexts.

changePassword

Changes the password for the current user.

changePasswordWithOldPassword

Changes the password for the current user by passing the old password.

changeUserPassword

Changes the password for the a given user.

synchronizeLoginCache

Uses JMX to refresh the login cache if supported.

changeExpiredCredentials

Used after an ExpiredCredentialException instance is thrown.

reportForgottenPassword

Deprecated.

getSecurityRoles

Returns the active sys::Roles in use by the server.

getEventContext

Returns an implementation of sys::EventContext loaded with the security for the current user and thread.

Operations

bool canUpdate(model::IObject obj) throws ServerError

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

model::Experimenter getExperimenter(long id) throws ServerError

Fetches an model::Experimenter and all related model::ExperimenterGroup.

Parameters

id

id of the Experimenter

Return Value

an Experimenter. Never null.

Exceptions

ApiUsageException

if id does not exist.

model::Experimenter lookupExperimenter(string name) throws ServerError

Looks up an model::Experimenter and all related model::ExperimenterGroup by name.

Parameters

name

Name of the Experimenter

Return Value

an Experimenter. Never null.

Exceptions

ApiUsageException

if omeName does not exist.

ExperimenterList lookupExperimenters() throws ServerError

Looks up all model::Experimenter experimenters present and all related model::ExperimenterGroup groups.

Return Value

all Experimenters. Never null.

model::ExperimenterGroup getGroup(long id) throws ServerError

Fetches an model::ExperimenterGroup and all contained model::Experimenter users.

Parameters

id

id of the ExperimenterGroup

Return Value

an ExperimenterGroup. Never null.

Exceptions

ApiUsageException

if id does not exist.

model::ExperimenterGroup lookupGroup(string name) throws ServerError

Looks up an model::ExperimenterGroup and all contained model::Experimenter users by name.

Parameters

name

Name of the ExperimenterGroup

Return Value

an ExperimenterGroup. Never null.

Exceptions

ApiUsageException

if groupName does not exist.

ExperimenterGroupList lookupGroups() throws ServerError

Looks up all model::ExperimenterGroup groups present and all related model::Experimenter experimenters. The experimenter's groups are also loaded.

Return Value

all Groups. Never null.

ExperimenterList containedExperimenters(long groupId) throws ServerError

Fetches all model::Experimenter users contained in this group. The returned users will have all fields filled in and all collections unloaded.

Parameters

groupId

id of the ExperimenterGroup

Return Value

non-null array of all model::Experimenter users in this group.

ExperimenterGroupList containedGroups(long experimenterId) throws ServerError

Fetches all model::ExperimenterGroup 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.

Return Value

non-null array of all model::ExperimenterGroup groups for this user.

model::ExperimenterGroup getDefaultGroup(long experimenterId) throws ServerError

Retrieves the default model::ExperimenterGroup group for the given user id.

Parameters

experimenterId

of the Experimenter. Not null.

Return Value

non-null model::ExperimenterGroup. If no default group is found, an exception will be thrown.

string lookupLdapAuthExperimenter(long id) throws ServerError

Looks up model::Experimenter experimenters who use LDAP authentication (has set dn on password table).

Return Value

Experimenter. Never null.

RList lookupLdapAuthExperimenters() throws ServerError

Looks up all ids of model::Experimenter experimenters who use LDAP authentication (has set dn on password table).

Return Value

list of experimenters. Never null.

LongList getMemberOfGroupIds(model::Experimenter exp) throws ServerError

Finds the ids for all groups for which the given model::Experimenter is a member.

Parameters

exp

Non-null, managed (i.e. with id)

See Also

model::Details::getOwner

LongList getLeaderOfGroupIds(model::Experimenter exp) throws ServerError

Finds the ids for all groups for which the given model::Experimenter is owner/leader.

Parameters

exp

Non-null, managed (i.e. with id)

See Also

model::Details::getOwner

void updateSelf(model::Experimenter experimenter) throws ServerError

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

Parameters

experimenter

A data transfer object. Only the fields: firstName, middleName, lastName, email, and institution are checked. Not null.

See Also

setDefaultGroup

long uploadMyUserPhoto(string filename, string format, ::Ice::ByteSeq data) throws ServerError

Uploads a photo for the user which will be displayed on his/her profile. This photo will be saved as an model::OriginalFile object with the given format, and attached to the user's model::Experimenter object via an model::FileAnnotation with the namespace: openmicroscopy.org/omero/experimenter/photo (NSEXPERIMENTERPHOTO). If such an model::OriginalFile instance already exists, it will be overwritten. If more than one photo is present, the oldest version will be modified (i.e. the highest updateEvent id). Note: as outlined in ticket 1794 this photo will be placed in the user group and therefore will be visible to everyone on the system.

Parameters

filename

Not null. String name which will be used.

format

Not null. Format.value string. 'image/jpeg' and 'image/png' are common values.

data

Not null. Data from the image. This will be written to disk.

Return Value

the id of the overwritten or newly created user photo OriginalFile object.

OriginalFileList getMyUserPhotos() throws ServerError

Retrieves the model::OriginalFile object attached to this user as specified by uploadMyUserPhoto. The return value is order by the most recently modified file first.

Return Value

file objects. Possibly empty.

void updateExperimenter(model::Experimenter experimenter) throws ServerError

Updates an experimenter if admin or owner of group. Only string fields on the object are taken into account. The root and guest experimenters may not be renamed. Before a SecurityViolation would be thrown, however, this method will pass to updateSelf if the current user matches the given experimenter.

Parameters

experimenter

the Experimenter to update.

void updateExperimenterWithPassword(model::Experimenter experimenter, RString password) throws ServerError

Updates an experimenter if admin or owner of group. Only string fields on the object are taken into account. The root and guest experimenters may not be renamed.

Parameters

experimenter

the Experimenter to update.

password

Not-null. Must pass validation in the security sub-system.

void updateGroup(model::ExperimenterGroup group) throws ServerError

Updates an experimenter group if admin or owner of group. Only string fields on the object are taken into account. The root, system and guest groups may not be renamed, nor may the user's current group.

Parameters

group

the ExperimenterGroup to update.

long createUser(model::Experimenter experimenter, string group) throws ServerError

Creates and returns a new user. This user will be created with the default group specified.

Parameters

experimenter

a new model::Experimenter instance

group

group name of the default group for this user

Return Value

id of the newly created model::Experimenter

long createSystemUser(model::Experimenter experimenter) throws ServerError

Creates and returns 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

experimenter

a new model::Experimenter instance

Return Value

id of the newly created model::Experimenter

long createExperimenter(model::Experimenter user, model::ExperimenterGroup defaultGroup, ExperimenterGroupList groups) throws ServerError

Creates and returns a new user in the given groups.

Parameters

user

A new model::Experimenter instance. Not null.

defaultGroup

Instance of model::ExperimenterGroup. Not null.

groups

Array of model::ExperimenterGroup instances. Can be null.

Return Value

id of the newly created model::Experimenter Not null.

long createExperimenterWithPassword(model::Experimenter user, RString password, model::ExperimenterGroup defaultGroup, ExperimenterGroupList groups) throws ServerError

Creates and returns a new user in the given groups with password.

Parameters

user

A new model::Experimenter instance. Not null.

password

Not-null. Must pass validation in the security sub-system.

defaultGroup

Instance of model::ExperimenterGroup. Not null.

groups

Array of model::ExperimenterGroup instances. Can be null.

Return Value

id of the newly created model::Experimenter Not null.

Exceptions

SecurityViolation

if the new password is too weak.

long createGroup(model::ExperimenterGroup group) throws ServerError

Creates and returns a new group. The model::Details::setPermissions method should be called on the instance which is passed. The given model::Permissions will become the default for all objects created while logged into this group, possibly modified by the user's umask settings. If no permissions is set, the default will be omero::model::Permissions::USER_PRIVATE, i.e. a group in which no user can see the other group member's data. See also ticket 1434

Parameters

group

a new model::ExperimenterGroup instance. Not null.

Return Value

id of the newly created ExperimenterGroup

void addGroups(model::Experimenter user, ExperimenterGroupList groups) throws ServerError

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.

void removeGroups(model::Experimenter user, ExperimenterGroupList groups) throws ServerError

Removes an experimenter from the given groups.

• The root experimenter is required to be in both the user and system groups.
• An experimenter may not remove themself from the user or system group.
• An experimenter may not be a member of only the user group, some other group is also required as the default group.
• An experimenter must remain a member of some group.

Parameters

user

A currently managed entity. Not null.

groups

Groups from which the user will be removed. Not null.

void setDefaultGroup(model::Experimenter user, model::ExperimenterGroup group) throws ServerError

Sets the default group for a given user.

Parameters

user

A currently managed model::Experimenter. Not null.

group

The group which should be set as default group for this user. Not null.

void setGroupOwner(model::ExperimenterGroup group, model::Experimenter owner) throws ServerError

Adds the user to the owner list for this group. Since Beta 4.2 multiple users can be the owner of a group.

Parameters

group

A currently managed model::ExperimenterGroup. Not null.

owner

A currently managed model::Experimenter. Not null.

void unsetGroupOwner(model::ExperimenterGroup group, model::Experimenter owner) throws ServerError

Removes the user from the owner list for this group. Since Beta 4.2 multiple users can be the owner of a group.

Parameters

group

A currently managed model::ExperimenterGroup. Not null.

owner

A currently managed model::Experimenter. Not null.

void addGroupOwners(model::ExperimenterGroup group, ExperimenterList owners) throws ServerError

Adds the given users to the owner list for this group.

Parameters

group

A currently managed model::ExperimenterGroup. Not null.

owners

A set of currently managed model::Experimenters. Not null.

void removeGroupOwners(model::ExperimenterGroup group, ExperimenterList owners) throws ServerError

removes the given users from the owner list for this group.

Parameters

group

A currently managed model::ExperimenterGroup. Not

owners

A set of currently managed model::Experimenters. Not null.

void deleteExperimenter(model::Experimenter user) throws ServerError

Removes a user by removing the password information for that user as well as all model::GroupExperimenterMap instances.

Parameters

user

Experimenter to be deleted. Not null.

void deleteGroup(model::ExperimenterGroup group) throws ServerError

Removes a group by first removing all users in the group, and then deleting the actual model::ExperimenterGroup instance.

Parameters

group

model::ExperimenterGroup to be deleted. Not null.

void changeOwner(model::IObject obj, string omeName) throws ServerError

This operation is deprecated.

void changeGroup(model::IObject obj, string omeName) throws ServerError

This operation is deprecated.

void changePermissions(model::IObject obj, model::Permissions perms) throws ServerError

This operation is deprecated.

void moveToCommonSpace(IObjectList objects) throws ServerError

Moves the given objects into the user group to make them visible and linkable from all security contexts. See also ticket 1794

Parameters

void changePassword(RString newPassword) throws ServerError

Changes the password for the current user.

Warning:This method requires the user to be authenticated with a password and not with a one-time session id. To avoid this problem, use changePasswordWithOldPassword.

Parameters

newPassword

Possibly null to allow logging in with no password.

Exceptions

SecurityViolation

if the user is not authenticated with a password.

void changePasswordWithOldPassword(RString oldPassword, RString newPassword) throws ServerError

Changes the password for the current user by passing the old password.

Parameters

oldPassword

Not-null. Must pass validation in the security sub-system.

newPassword

Possibly null to allow logging in with no password.

Exceptions

SecurityViolation

if the oldPassword is incorrect.

void changeUserPassword(string omeName, RString newPassword) throws ServerError

Changes the password for the a given user.

Parameters

newPassword

Not-null. Might must pass validation in the security sub-system.

Exceptions

SecurityViolation

if the new password is too weak.

void synchronizeLoginCache() throws ServerError

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.

void changeExpiredCredentials(string name, string oldCred, string newCred) throws ServerError

Used after an ExpiredCredentialException instance is thrown.

void reportForgottenPassword(string name, string email) throws ServerError

This operation is deprecated.

sys::Roles getSecurityRoles() throws ServerError

Returns the active sys::Roles in use by the server.

Return Value

Non-null, immutable sys::Roles instance.

sys::EventContext getEventContext() throws ServerError

Returns an implementation of sys::EventContext loaded with the security for the current user and thread. If called remotely, not all values of sys::EventContext will be sensible.

Return Value

Non-null, immutable sys::EventContext instance