Version: 5.4.10-ice35-b105

OmeroBlitz API
Home Previous Up Next Index

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.
getCurrentAdminPrivileges
Gets the light administrator privileges for the current user.
getAdminPrivileges
Gets the light administrator privileges for the given user.
getAdminsWithPrivileges
Gets the administrators who have all the given privileges.
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.
createRestrictedSystemUser
Creates and returns a new system user.
createRestrictedSystemUserWithPassword
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.
setAdminPrivileges
Sets the set of light administrator privileges for the given user.
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

AdminPrivilegeList getCurrentAdminPrivileges() throws ServerError

Gets the light administrator privileges for the current user.

Return Value

the current user's light administrator privileges

AdminPrivilegeList getAdminPrivileges(model::Experimenter user) throws ServerError

Gets the light administrator privileges for the given user.

Parameters

user
the user whose privileges are being queried

Return Value

the user's light administrator privileges

ExperimenterList getAdminsWithPrivileges(AdminPrivilegeList privileges) throws ServerError

Gets the administrators who have all the given privileges. Consistent with the results from "getAdminPrivileges".

Parameters

privileges
the required privileges

Return Value

the light administrators who have those privileges

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 createRestrictedSystemUser(model::Experimenter experimenter, AdminPrivilegeList privileges) 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. Their light administrator privileges will be set as given.

Parameters

experimenter
a new model::Experimenter instance
privileges
the privileges to set for the user

Return Value

id of the newly created model::Experimenter

long createRestrictedSystemUserWithPassword(model::Experimenter experimenter, AdminPrivilegeList privileges, RString password) 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. Their light administrator privileges and password will be set as given.

Parameters

experimenter
a new model::Experimenter instance
privileges
the privileges to set for the user
password
Not-null. Must pass validation in the security sub-system.

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.

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

changeOwner() is deprecated. use omero::cmd::Chown2() instead.

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

changeGroup() is deprecated. use omero::cmd::Chgrp2() instead.

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

changePermissions() is deprecated. use omero::cmd::Chmod2() instead.

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 setAdminPrivileges(model::Experimenter user, AdminPrivilegeList privileges) throws ServerError

Sets the set of light administrator privileges for the given user.

Parameters

user
the user whose privileges are to be set
privileges
the privileges to set for the user

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.

See also ticket 911 and ticket 3201

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

reportForgottenPassword() is deprecated. use omero::cmd::ResetPasswordRequest() instead.

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


Home Previous Up Next Index