Package pl.edu.icm.unity.engine.api

Interface EntityManagement

public interface EntityManagement

Engine API for (closely related) entities and identities management.

Author:

K. Benedyczak

Method Summary

Modifier and Type	Method	Description
Identity	addEntity(IdentityParam toAdd, String credReqIdId, EntityState initialState)	As addEntity(IdentityParam, String, EntityState, List) with the empty list of attributes.
default Identity	addEntity(IdentityParam toAdd, String credReqIdId, EntityState initialState, boolean extractAttributes, List<Attribute> attributes)	Deprecated.
Identity	addEntity(IdentityParam toAdd, String credReqId, EntityState initialState, List<Attribute> attributes)	Adds a new entity with an initial identity.
Identity	addEntity(IdentityParam toAdd, EntityState initialState)	As addEntity(IdentityParam, EntityState, List) with the empty list of attributes and default credential requirements.
default Identity	addEntity(IdentityParam toAdd, EntityState initialState, boolean extractAttributes)	Deprecated.
default Identity	addEntity(IdentityParam toAdd, EntityState initialState, boolean extractAttributes, List<Attribute> attributes)	Deprecated.
Identity	addEntity(IdentityParam toAdd, EntityState initialState, List<Attribute> attributes)	As addEntity(IdentityParam, String, EntityState, List) with the empty list of attributes and default credential requirements.
Identity	addIdentity(IdentityParam toAdd, EntityParam parentEntity)	Adds a new identity under existing entity.
default Identity	addIdentity(IdentityParam toAdd, EntityParam parentEntity, boolean extractAttributes)	Deprecated.
Set<EntityWithContactInfo>	getAllEntitiesWithContactEmails(Set<String> contactEmails)	Returns entities with assigned e-mail - as attribute or identity
Entity	getEntity(EntityParam entity)	Returns information about an entity along with its all identities with authorization in '/'.
Entity	getEntity(EntityParam entity, String target, boolean allowCreate, String group)	Returns information about an entity along with its all identities.
String	getEntityLabel(EntityParam entity)
Entity	getEntityNoContext(EntityParam entity, String group)	Returns information about an entity along with its identities.
Map<String,GroupMembership>	getGroups(EntityParam entity)	Returns a collection with all groups where the entity is a member.
Collection<Group>	getGroupsForPresentation(EntityParam entity)	Returns a collection with all groups where the entity is a member.
Map<Long,List<Identity>>	getIdentitiesForEntities(Set<Long> entityIds)
void	mergeEntities(EntityParam target, EntityParam merged, boolean safeMode)	Merge the 2nd entity with the first one.
void	removeEntity(EntityParam toRemove)
void	removeIdentity(IdentityTaV toRemove)	Deletes identity.
void	resetIdentity(EntityParam entity, String typeIdToReset, String realm, String target)	Reset a possibly targeted value of a dynamic identity.
void	scheduleEntityChange(EntityParam toChange, Date changeTime, EntityScheduledOperation operation)	Schedules an operation to be invoked at a given time on an entity.
void	scheduleRemovalByUser(EntityParam toChange, Date changeTime)	Sets the entity in the EntityState.onlyLoginPermitted and schedules the entity removal at given time unless the user logs in before this time.
void	setEntityStatus(EntityParam toChange, EntityState state)
void	setIdentities(EntityParam entity, Collection<String> updatedTypes, Collection<? extends IdentityParam> newIdentities)	Updates identities of a single entity.
void	updateIdentity(IdentityTaV original, IdentityParam updated)	Updates a given identity.

Method Details

addEntity

Identity addEntity(IdentityParam toAdd,
 String credReqId,
 EntityState initialState,
 List<Attribute> attributes)
            throws EngineException

Adds a new entity with an initial identity.

Parameters:

toAdd - new identity

credReqId - Local CredentialRequirements id

initialState - the initial state of the newly created entity

attributes - initial attributes to be added for the entity. This is especially useful when the root group (to which the entity is automatically added) has some AttributesClasses assigned with mandatory attributes.

Returns:

newly created identity

Throws:

EngineException

addEntity

Identity addEntity(IdentityParam toAdd,
 String credReqIdId,
 EntityState initialState)
            throws EngineException

As addEntity(IdentityParam, String, EntityState, List) with the empty list of attributes.

Throws:

EngineException

addEntity

Identity addEntity(IdentityParam toAdd,
 EntityState initialState,
 List<Attribute> attributes)
            throws EngineException

As addEntity(IdentityParam, String, EntityState, List) with the empty list of attributes and default credential requirements.

Throws:

EngineException

addEntity

Identity addEntity(IdentityParam toAdd,
 EntityState initialState)
            throws EngineException

As addEntity(IdentityParam, EntityState, List) with the empty list of attributes and default credential requirements.

Throws:

EngineException

addIdentity

Identity addIdentity(IdentityParam toAdd,
 EntityParam parentEntity)
              throws EngineException

Adds a new identity under existing entity.

Throws:

EngineException

removeIdentity

void removeIdentity(IdentityTaV toRemove)
             throws EngineException

Deletes identity. It must not be the last identity of the entity. Certain system Identities can not be removed.

Throws:

EngineException

setIdentities

void setIdentities(EntityParam entity,
 Collection<String> updatedTypes,
 Collection<? extends IdentityParam> newIdentities)
            throws EngineException

Updates identities of a single entity. The identities of the types provided with the first argument are replaced with the identities given as the second argument. The set of new identities can contain only identities of types enumerated in the first argument (which can have more types, if some needs to be cleared). Certain system identity types can not be modified using this method, only the resetIdentity(EntityParam, String, String, String) is available for them.

Parameters:

entity - all identities must belong to this entity

updatedTypes - set of all types that shall be modified

newIdentities - a new, complete set of identities for the given types

Throws:

EngineException

updateIdentity

void updateIdentity(IdentityTaV original,
 IdentityParam updated)
             throws EngineException

Updates a given identity. Useful to change details of an identity like confirmation status. Note that updated identity must have the same comparable representation as the original one, i.e. must have the same type and value parts which are part of comparable representation must be unchanged. Operation only available with full permissions.

Throws:

EngineException

resetIdentity

void resetIdentity(EntityParam entity,
 String typeIdToReset,
 String realm,
 String target)
            throws EngineException

Reset a possibly targeted value of a dynamic identity. For the identities which are fixed this method throws an exception.

Parameters:

entity - subject

typeIdToReset - which id type should be reset, must be dynamic

realm - if null then all realms should be cleared

target - if null then all targets should be cleared

Throws:

EngineException

removeEntity

void removeEntity(EntityParam toRemove)
           throws EngineException

Throws:

EngineException

setEntityStatus

void setEntityStatus(EntityParam toChange,
 EntityState state)
              throws EngineException

Throws:

EngineException

scheduleEntityChange

void scheduleEntityChange(EntityParam toChange,
 Date changeTime,
 EntityScheduledOperation operation)
                   throws EngineException

Schedules an operation to be invoked at a given time on an entity. Requires regular identityModify capability (not assigned for self access).

Throws:

EngineException

scheduleRemovalByUser

void scheduleRemovalByUser(EntityParam toChange,
 Date changeTime)
                    throws EngineException

Sets the entity in the EntityState.onlyLoginPermitted and schedules the entity removal at given time unless the user logs in before this time. Requires only the attributeModify capability (allowed for selfAccess).

Throws:

EngineException

getIdentitiesForEntities

Map<Long,List<Identity>> getIdentitiesForEntities(Set<Long> entityIds)

getEntity

Entity getEntity(EntityParam entity)
          throws EngineException

Returns information about an entity along with its all identities with authorization in '/'.

Throws:

EngineException

getEntity

Entity getEntity(EntityParam entity,
 String target,
 boolean allowCreate,
 String group)
          throws EngineException

Returns information about an entity along with its all identities. This version supports dynamic identities as it allows for specifying a receiver of the information and whether it is allowed to establish a new identifier.

Parameters:

entity - who to resolve

target - for whom the information is targeted

allowCreate - whether dynamic identities can be created

group - group wrt which authorization should be performed.

Returns:

Throws:

EngineException

getEntityNoContext

Entity getEntityNoContext(EntityParam entity,
 String group)
                   throws EngineException

Returns information about an entity along with its identities. This version requires higher privileges and returns all identities, also those targeted for anybody in any realm.

Throws:

EngineException

getAllEntitiesWithContactEmails

Set<EntityWithContactInfo> getAllEntitiesWithContactEmails(Set<String> contactEmails)
                                                    throws EngineException

Returns entities with assigned e-mail - as attribute or identity

Parameters:

contactEmails - email assigned to the entity

Throws:

EngineException

getGroups

Map<String,GroupMembership> getGroups(EntityParam entity)
                               throws EngineException

Returns a collection with all groups where the entity is a member. For convenience returned as map indexed with group paths.

Parameters:

entity -

Returns:

Throws:

EngineException

getGroupsForPresentation

Collection<Group> getGroupsForPresentation(EntityParam entity)
                                    throws EngineException

Returns a collection with all groups where the entity is a member. This method returns resolved groups with description and displayed name, however without information on attribute statements and other data which might be secret.

Throws:

EngineException

mergeEntities

void mergeEntities(EntityParam target,
 EntityParam merged,
 boolean safeMode)
            throws EngineException

Merge the 2nd entity with the first one. Only non conflicting information is moved. In particular the information of the merged entity is processed as follows:

1. static identities are added to the base entity
2. dynamic identities are added to the base entity only if it has no identities of a particular identity type and the identity is removable
3. credential requirement and attribute classes are ignored
4. credentials are added, however only if the target identity has no credential defined of the same type
5. group memberships are copied
6. attributes are copied, however only if the target has no attribute of the same type in the same group. Also attributes not allowed by the target's attribute policy are ignored

If the safe mode is activated then the operation will throw exception (without making any changes) if any of attributes, credentials or dynamic removable identity was not copied due to conflicts.

Throws:

EngineException

getEntityLabel

String getEntityLabel(EntityParam entity)
               throws EngineException

Returns:

displayed name of the entity or null if undefined

Throws:

EngineException

addEntity

@Deprecated
default Identity addEntity(IdentityParam toAdd,
 String credReqIdId,
 EntityState initialState,
 boolean extractAttributes,
 List<Attribute> attributes)
                    throws EngineException

Deprecated.

Throws:

EngineException

addEntity

@Deprecated
default Identity addEntity(IdentityParam toAdd,
 EntityState initialState,
 boolean extractAttributes,
 List<Attribute> attributes)
                    throws EngineException

Deprecated.

Throws:

EngineException

addEntity

@Deprecated
default Identity addEntity(IdentityParam toAdd,
 EntityState initialState,
 boolean extractAttributes)
                    throws EngineException

Deprecated.

Throws:

EngineException

addIdentity

@Deprecated
default Identity addIdentity(IdentityParam toAdd,
 EntityParam parentEntity,
 boolean extractAttributes)
                      throws EngineException

Deprecated.

Throws:

EngineException