com.sap.ip.collaboration.room.api

Interface IRoom

public interface IRoom

Public Interface describing a single collaboration room object

The Room API contains functionality concerning one single room object whereas the Rooms API provides methods concerning all rooms (searching, creation, instantiation...).

This interface is part of the Room API. It is public to all customers. It provides methods for reading room properties and basic methods for room manipulation.

This interface is used only for existing collaboration rooms. For room creation please see the description of the Interface IRoomInfo in the Rooms API.

Field Summary

static int	DTN_ITEM_POS_BOTTOM This value can be used as a parameter of method setPosition(String, int) to move a room part to the bottom of the DTN
static int	DTN_ITEM_POS_TOP This value can be used as a parameter of method setPosition(String, int) to move a room part to the top of the DTN

Method Summary

boolean	addRoomParameter(IRoomParameterValue param) Set a parameter to the room.
IRoomPart	createAndAddRoomPart(String roompartName, String roompartTemplate, boolean removeable, IRoleMapping[] roleMappings, IRoomParameterValue[] roompartParameters, IParameterMapping[] parameterMappings) Create a new room part instance from a room part template and attach it to the room
IRoomPart	createRoomPartInstance(String name, String roomPartTemplate, IRoleMapping[] roleMappings, IRoomParameterValue[] parameters, IParameterMapping[] parameterMappings) Deprecated.
boolean	deregisterUserFromCommunity(String userId) Unsubscribe a user from a community.
String	getAdminRoleName() Get the name of the Admin Role of the room.
IRoomRole	getAdminRoomRole() Get an instance of the admin room role
IRoomParameterValue[]	getAllInternalParameters() Get all internal room parameters.
String[]	getAllRoomParameterNames() Get the parameter names of a room
IRoomParameterValue[]	getAllRoomParameters() Get the parameters of a room
String[]	getAllRoomRoleNames() Get the names of all room roles in the room
IRoomRole[]	getAllRoomRoles() Get all room roles of a room
String[]	getAllRoomUserIds() Get the ids of all users of this room.
com.sapportals.wcm.repository.service.archiving.AOStates	getArchivingObjectState() Gets the Archiving Object (AO) state for this room.
IRoomCategory[]	getCategories() Get the categories of a room
Date	getCreationDate() Get the creation date of a room
String	getDescription() Get the description of a room
String[]	getDirectRoomPrincipalSetIds() Get the ids of all principalSets assigned directly to this room.
String[]	getDirectRoomRolePrincipalSetIds(String roomRoleName) Get the ids of all principalSets who are a direct member of a specific room role in this room
String[]	getDirectRoomRoleUserIds(String roomRoleName) Get the ids of all users who are a direct member of a specific room role in this room
String[]	getDirectRoomUserIds() Get the ids of all users assigned directly to this room.
String	getId() Get the id of a room
String	getInitialRoleName() Get the name of the Initial Role of the room.
IRoomRole	getInitialRoomRole() Get an instance of the initial room role
IRoomParameterValue	getInternalParameter(String paramName) Get a specific internal room parameter
Date	getLastModified() Get the date of the last modification of a room
String	getName() Get the name of a room
String	getOwnerId() Get the owner of a room
int	getPosition(String roomPartId) Get the actual position of a Room Part in the DTN.
RoomPrivacyType	getPrivacyType() Get the privacy type of a room.
String	getProperty(String nameSpace, String propName) Get the value of a custom property of the room.
String	getRoomAccessURLExternal() Get an external Access URL for a specific room.
String	getRoomAccessURLInternal() Get the internal representation of an access URL of a room.
IRoomStatusEvent[]	getRoomEvents(long timeStamp, RoomStatusAction[] roomActions, String[] userIds, int maxResultSize) Retrieve room events for this room according to the specified search criteria.
IRoomGroups	getRoomGroups() Get an instance of IRoomGroups which contains the IDs of all User Management Groups and PrincipalSets related to this room.
IRoomInfo	getRoomInfo() Get some information describing a room encapsulated in an independent object.
IRoomParameterValue	getRoomParameter(String paramName) Get the parameter value of a specific parameter for this room
IRoomPart[]	getRoomParts() Get all Room Parts contained in this room
IRoomPrincipals	getRoomPrincipals() Get all users and principalSets who are member of any room role in this room.
IRoomRole	getRoomRole(String roleName) Get a room role instance for a given role name if such a room role exists in the current room
IRoomRole[]	getRoomRolesForMember(String memberId) Get the room roles for a specific user or principalSet in this room (directly and indirectly)
IRoomRole[]	getRoomRolesForUser(String userId) Deprecated. use getRoomRolesForMember(String) instead
String[]	getRoomRoleUserIds(String roomRoleName) Get the ids of all users who are member (directly and indirectly) of a specific room role in this room
String	getRoomStructureRid() Get the RID of the room structure folder in CM.
IRoomUsageUser[]	getRoomUsage(long timeStamp, int listLength) Returns data on the usage of this per user, ordered by the number of visits (most visiting users first).
IRoomUsers	getRoomUsers() Deprecated. use getRoomPrincipals() instead
ITemplate	getTemplate() Get the room template this room is based on
String	getTemplateDescription() Get the template description of a room
String	getTemplateName() Get the template name of a room.
int	getVersion() Get the technical version number of a room object.
boolean	hasPublicAccess() Check if there is a public room role in the room which is mapped to at least one page.
boolean	hasRoomRole(String roomRoleName) Check if a room role with a given role name exists in the room
boolean	isCommunity() Check if the room is a community
boolean	isHidden() Check if the room is hidden
boolean	isListedRoom() Check if the room is a listed room
boolean	isLocked() Check if the room is locked
boolean	isMember(String memberId) Tests whether a specific principal (user or principalSet) has access to this room
boolean	isOIFBased() Check whether this room should use the OIF (object instance floorplan) based navigation pattern.
boolean	isPrivacyTypeChangeAllowed() The room template may define the room privacy type as 'strict' which means that no changes are allowed.
boolean	isRoomPartRemoveable(String roomPartId) Check whether a specific room part can be removed in the room maintenance UI or not
boolean	isUnlistedRoom() Check if the room is a unlisted room
boolean	lock() Lock the current collaboration room
boolean	registerUserInCommunity(String userId) Subscribe a user to a community.
boolean	removeAndDeleteRoomPart(String roomPartInstanceId, boolean overrideRemovalProtection) Remove a room part instance from the room and delete it
boolean	removeRoomPartInstance(String roomPartInstanceId) Deprecated.
void	removeRoomRole(String roleName) Remove a room role from a room.
boolean	requestMembership(String userId) Request membership for a specific user in a room.
boolean	setCategories(IRoomCategory[] newCategories) Set the categories of the room.
boolean	setDescription(String description) Set the description of the room
boolean	setHidden(boolean hiddenFlag) Set the room hide status
boolean	setName(String name) Set the name of the room
boolean	setOwnerId(String newOwnerId) Set the owner of the room
boolean	setOwnerId(String newOwnerId, boolean persist) Deprecated. use setOwnerId(String newOwnerId)
int	setPosition(String roomPartId, int newPosition) Set the position of a Room Part in the DTN.
boolean	setPrivacyType(RoomPrivacyType newPrivacy) Set the privacy type of the room if changing the privacy type is allowed.
boolean	setProperty(String nameSpace, String propName, String propValue) Set a custom property on the room.
boolean	setRoomParameters(IRoomParameterValue[] newParams) Change the values for one or more room parameters.
boolean	setRoomPrincipals(IRoomPrincipals roomPrincipals, boolean sendNotifications) Assign users and principalSets to the room.
boolean	setRoomUsers(IRoomUsers roomUsers, boolean sendNotifications) Deprecated. use setRoomPrincipals(IRoomPrincipals, boolean) instead
boolean	supportsParameterChanges() Check - depending on the room version - if changing the room parameters is supported or not
boolean	supportsRootGroup() Check - depending on the room version - if a root group containing all room role groups is supported
boolean	unlock() Unlock the current room

Field Detail

DTN_ITEM_POS_TOP

static final int DTN_ITEM_POS_TOP

This value can be used as a parameter of method setPosition(String, int) to move a room part to the top of the DTN

See Also:

Constant Field Values

DTN_ITEM_POS_BOTTOM

static final int DTN_ITEM_POS_BOTTOM

This value can be used as a parameter of method setPosition(String, int) to move a room part to the bottom of the DTN

See Also:

Constant Field Values

Method Detail

getId

String getId()

Get the id of a room

Returns:

String containing the technical id of this room object

getRoomInfo

IRoomInfo getRoomInfo()

Get some information describing a room encapsulated in an independent object. This IRoomInfo object can be used to query the properties of a room. The IRoomInfo object contains all information about the room itselbt, but not the portal related stuff (workset, pages, ...) and also not the content (folders, documents, ...).

Also you can use this info object to copy rooms: Since room creation is based on the same Interface IRoomInfo just get this info object for any existing room, change the properties you want to change and then create a new collaboration room based on this info object using the method IRooms. createRoom(IRoomInfo, boolean).

Returns:

parts of the room information

See Also:

IRoomInfo

getRoomGroups

IRoomGroups getRoomGroups()

Get an instance of IRoomGroups which contains the IDs of all User Management Groups and PrincipalSets related to this room.

Returns:

IRoomGroups instance

getCreationDate

Date getCreationDate()

Get the creation date of a room

Returns:

Date object containing the creation date of this room object

getLastModified

Date getLastModified()

Get the date of the last modification of a room

Returns:

Date object representing the date when the room was last modified

getVersion

int getVersion()

Get the technical version number of a room object. Room instances which have been created with different versions of the Room API have different version numbers. This is necessary because not all room versions support all features. Calling a method which is not supported on the actual version of a room object results in a RoomVersionException.

A list of all possible versions is available at class RoomVersion

Returns:

the version number of the room

isOIFBased

boolean isOIFBased()

Check whether this room should use the OIF (object instance floorplan) based navigation pattern. This setting depends on the room template the room is based on and can be changed only there.

Returns:

true if OIF should be used, false otherwise

isHidden

boolean isHidden()

Check if the room is hidden

Returns:

true if the room is hidden, false otherwise

See Also:

setHidden(boolean)

setHidden

boolean setHidden(boolean hiddenFlag)

Set the room hide status

Parameters:

hiddenFlag - true means the room will be hidden, false means the room will be unhidden

Returns:

true if the operation was successful, false otherwise

isLocked

boolean isLocked()

Check if the room is locked

Returns:

true if the room is locked, false otherwise

See Also:

IRoomSystem#lock(), IRoomSystem#unlock()

lock

boolean lock()

Lock the current collaboration room

Returns:

true if the room was unlocked and locking of the room was successful, false otherwise

See Also:

unlock(), isLocked()

unlock

boolean unlock()

Unlock the current room

Returns:

true if the room was locked and unlocking of the room was successful, false otherwise

See Also:

lock(), isLocked()

getName

String getName()

Get the name of a room

Returns:

String containing the name of this room object

setName

boolean setName(String name)

Set the name of the room

Parameters:

name - the new name of the room

Returns:

true if successful, false otherwise (i.e. persistency problems)

getDescription

String getDescription()

Get the description of a room

Returns:

String containing the description of this room object

setDescription

boolean setDescription(String description)

Set the description of the room

Parameters:

description - the new description of the room

Returns:

true if successful, false otherwise (i.e. persistency problems)

getRoomAccessURLInternal

String getRoomAccessURLInternal()

Get the internal representation of an access URL of a room. This URL can be used to jump directly into the room when displayed in the portal environment.

Attention: The returned URL is only useful in the portal environment. This means, it cannot be used as a link in an eMail for example.

Returns:

String containing the access URL of the room

getRoomAccessURLExternal

String getRoomAccessURLExternal()

Get an external Access URL for a specific room. The Access URL can be used to display links in a portal environment as well as in external environments such as emails. Clicking on such a link results in entering the room.

Note: External Room links generated by this method only work correctly if the server is configured properly. The correct HTTP Protocol, Servername and Port of the machine need to be configured under Collaboration Administration -> Configure Room Backend.

For links in the portal environment getRoomAccessURLInternal() should be used because this is not dependent on the configuration.

Returns:

String containing the access URL of the room

getRoomStructureRid

String getRoomStructureRid()

Get the RID of the room structure folder in CM. This folder is the root for all CM content in the room. It contains links to all private store folders of the room as well as a link to the public area which again contains links to the public store folders assigned to the room.

Returns:

the RID of the room structure folder in CM

hasPublicAccess

boolean hasPublicAccess()

Check if there is a public room role in the room which is mapped to at least one page. In all other cases only members of the room have access to (the public area of) the room.

Returns:

true if there is a public room role and this role is mapped to at least one room page, false otherwise

getTemplate

ITemplate getTemplate()
                      throws TemplateInstantiationException

Get the room template this room is based on

Returns:

the room template instance

Throws:

TemplateInstantiationException

getTemplateName

String getTemplateName()

Get the template name of a room.

Returns:

String containing the name of the template which was used when this room was created.

getTemplateDescription

String getTemplateDescription()

Get the template description of a room

Returns:

String containing the description of the template which was used to create this room.

getCategories

IRoomCategory[] getCategories()

Get the categories of a room

Returns:

Array containing the categories assigned to this room

setCategories

boolean setCategories(IRoomCategory[] newCategories)

Set the categories of the room.

You can create new instances of IRoomCategory using the IRoomCategoryFactory which you will get using the method IRooms.getRoomCategoryFactory().

Parameters:

newCategories - Array containing the new Categories of the room

Returns:

true if successful, false otherwise (i.e. persistency problems)

getOwnerId

String getOwnerId()

Get the owner of a room

Returns:

String containing the unique id of the owner of this room object

getPrivacyType

RoomPrivacyType getPrivacyType()

Get the privacy type of a room.
Possible privacy types are currently:

• public (Community, free access),
• listed (Listed room, invitation upon request),
• unlisted (Not listed room, access only with invitation)

Returns:

the privacy type of this room object

isPrivacyTypeChangeAllowed

boolean isPrivacyTypeChangeAllowed()

The room template may define the room privacy type as 'strict' which means that no changes are allowed. To check whether changing the privacy type is allowed or not, call this method. To change the privacy type, call setPrivacyType()

Returns:

true if changing the privacy type is allowed, false otherwise

setPrivacyType

boolean setPrivacyType(RoomPrivacyType newPrivacy)

Set the privacy type of the room if changing the privacy type is allowed. The room template may define the room privacy type as 'strict' which means that no changes are allowed. To check whether changing the privacy type is allowed or not call isPrivacyTypeChangeAllowed()

Parameters:

newPrivacyType - the new privacy type of the room

Returns:

true if successful, false otherwise (i.e. persistency problems)

setProperty

boolean setProperty(String nameSpace,
                    String propName,
                    String propValue)

Set a custom property on the room. Custom properties are set and read only by external applications. They are not provided as input parameters to the iViews of the room. For this purpose you have to use room parameters.

Custom properties are only maintained by the application which created the property itself. Each application should use its own namespace (prefix) for its own properties to make sure that there are no name clashes with other applications.

Parameters:

nameSpace - the NameSpace of the application (max. 450 characters)

propName - the name of the custom property (max. 450 characters)

propValue - the value of the custom property

Returns:

true if setting the new parameter was successful, false otherwise

getProperty

String getProperty(String nameSpace,
                   String propName)

Get the value of a custom property of the room. Custom properties are set and read only by external applications. They are not provided as input parameters to the iViews of the room. For this purpose you have to use room parameters.

Custom properties are only maintained by the application which created the property itself. Each application should use its own namespace (prefix) for its own properties to make sure that there are no name clashes with other applications.

Parameters:

nameSpace - the NameSpace of the application

propName - the name of the custom property

Returns:

the value stored in the custom property

getAllRoomParameterNames

String[] getAllRoomParameterNames()

Get the parameter names of a room

Returns:

Array containing the names of all parameters of this room object

getAllRoomParameters

IRoomParameterValue[] getAllRoomParameters()

Get the parameters of a room

Returns:

Array containing all parameters of this room object

getRoomParameter

IRoomParameterValue getRoomParameter(String paramName)

Get the parameter value of a specific parameter for this room

Parameters:

paramName - the name of the parameter to query

Returns:

an instance of IRoomParameterValue for the given parameter name of this room object

addRoomParameter

boolean addRoomParameter(IRoomParameterValue param)

Set a parameter to the room. If a parameter with the same parameter name already exists in the room the value of the existing parameter is changed to the new value.

Parameters:

param - the new parameter of the room

Returns:

true if successful, false otherwise (i.e. persistency problems)

setRoomParameters

boolean setRoomParameters(IRoomParameterValue[] newParams)
                          throws RoomVersionException

Change the values for one or more room parameters. The new values are also mapped to the corresponding iView parameters. The mapping rules are taken from the room template snapshot.

This functionality is only supported by room instances with version >= RoomVersion.VERSION_60_SP2FP. For earlier versions a RoomVersionException is thrown.

To check whether this feature is available or not for the current version call supportsParameterChanges()

Parameters:

newParams - a list of parameters to be changed

Returns:

true if successful, false otherwise

Throws:

RoomVersionException

getAllInternalParameters

IRoomParameterValue[] getAllInternalParameters()

Get all internal room parameters. Internal room parameters are defined by the system for each new room. They provide values like the room id, the room name or the structure RID of a specific room.

These parameters can also be mapped to iView parameters in the room template wizard.

Returns:

Array containing all internal parameters of this room including their values.

See Also:

getInternalParameter(String)

getInternalParameter

IRoomParameterValue getInternalParameter(String paramName)

Get a specific internal room parameter

Parameters:

paramName - the name of the internal room parameter

Returns:

the internal parameter including its value

See Also:

getAllInternalParameters()

setOwnerId

boolean setOwnerId(String newOwnerId)

Set the owner of the room

Parameters:

newOwnerId - the uniqueID of the new owner for the room

Returns:

true if successful, false otherwise (i.e. persistency problems)

setOwnerId

boolean setOwnerId(String newOwnerId,
                   boolean persist)

Deprecated. use setOwnerId(String newOwnerId)

Set the owner of the room

Parameters:

newOwnerId - the uniqueID of the new owner for the room

persist - if false, the new value will not be persisted in the backend

Returns:

true if successful, false otherwise (i.e. persistency problems)

getRoomUsers

IRoomUsers getRoomUsers()

Deprecated. use getRoomPrincipals() instead

Don't use this method anymore because it only contains the users assigened directly to any room role in the room. It does not contain the principalSets and neither the users contained in these principalSets.

Get all users who are direct member of any room role in this room.

You can also use the returned object to modify the users (invite new users, change roles of existing users or remove users) and then put the modified object back into the room using the method setRoomUsers(IRoomUsers, boolean). This will commit the changes and the room will reflect these changes on the user level.

Returns:

IRoomUsers object which holds all users of the room

See Also:

setRoomUsers(IRoomUsers, boolean), IRoomUsers

getRoomPrincipals

IRoomPrincipals getRoomPrincipals()

Get all users and principalSets who are member of any room role in this room.

You can also use the returned object to modify the users/principalSets (invite new users/principalSets, change roles of existing users/principalSets or remove users/principalSets) and then put the modified object back into the room using the method setRoomPrincipals(IRoomPrincipals, boolean). This will commit the changes and the room will reflect these changes on the user/principalSet level.

Returns:

IRoomPrincipals object which holds all users and principalSets of the room

See Also:

setRoomPrincipals(IRoomPrincipals, boolean), IRoomPrincipals

setRoomUsers

boolean setRoomUsers(IRoomUsers roomUsers,
                     boolean sendNotifications)

Deprecated. use setRoomPrincipals(IRoomPrincipals, boolean) instead

Don't use this method anymore. The new method signature to be used is boolean setRoomPrincipals(IRoomPrincipals roomPrincipals, boolean sendNotifications)

Assign users to the room.

You can create a new instance of IRoomUsers using the API method IRoomsSystem.createRoomUsersObject() or you can get an instance of IRoomUsers from any existing room using the method getRoomUsers(). Such an instance can be used to modify the users (invite new users, change roles of existing users or remove users) and then put the modified object back into the room using the method setRoomUsers(IRoomUsers, boolean). This will commit the changes and the room will reflect these changes on the user level.

Note: Users who have not been member before the method call will get an invitation email. Users who lose their membership as an effect of the call will also be notified via email.

Parameters:

newRoomUsers - the object containing the new user-role combinations

sendNotifications - if true invitation emails will be sent to all room members

Returns:

true if successful, false otherwise (i.e. persistency problems)

See Also:

getRoomUsers(), IRoomsSystem#createRoomUsersObject(), IRoomUsers

setRoomPrincipals

boolean setRoomPrincipals(IRoomPrincipals roomPrincipals,
                          boolean sendNotifications)

Assign users and principalSets to the room.

You can create a new instance of IRoomPrincipals using the API method IRooms.createRoomPrincipalsObject() or you can get an instance of IRoomPrincipals from any existing room using the method getRoomPrincipals(). Such an instance can be used to modify the users/principalSets (invite new users/principalSets, change roles of existing users/principalSets or remove users/principalSets) and then put the modified object back into the room using the method setRoomPrincipals(IRoomPrincipals, boolean). This will commit the changes and the room will reflect these changes on the user/principalSet level.

Note: Users who have not been member before the method call will get an invitation email. Users who lose their membership as an effect of the call will also be notified via email. PrincipalSet members never get email notifications.

Parameters:

roomPrincipals - the object containing the new user-role/principalSet-role combinations

sendNotifications - if true invitation emails will be sent to all direct room members

Returns:

true if successful, false otherwise (i.e. persistency problems)

See Also:

getRoomPrincipals(), IRooms.createRoomPrincipalsObject(), IRoomPrincipals

getAllRoomUserIds

String[] getAllRoomUserIds()

Get the ids of all users of this room. This is not the list of users who are currently online in the room. The returned Array contains all users who have access to this room. This includes users who are assigened directly to the room as well as indirectly via principalSet membership.

Returns:

Array containing the unique ids of all users who are assigned to any room role in this room (directly and indirectly).

getDirectRoomUserIds

String[] getDirectRoomUserIds()

Get the ids of all users assigned directly to this room. Users who are member of a principalSet assigned to the room are not returned by this method.

Returns:

Array containing the unique ids of all users who are assigned directly to any room role in this room.

getDirectRoomPrincipalSetIds

String[] getDirectRoomPrincipalSetIds()

Get the ids of all principalSets assigned directly to this room.

Returns:

Array containing the unique ids of all principalSets which are assigned directly to any room role in this room.

getRoomRoleUserIds

String[] getRoomRoleUserIds(String roomRoleName)

Get the ids of all users who are member (directly and indirectly) of a specific room role in this room

Parameters:

roomRoleName - the name of the room role

Returns:

Array containing the unique ids of all users who are assigned to a specific room role in this room object

getDirectRoomRoleUserIds

String[] getDirectRoomRoleUserIds(String roomRoleName)

Get the ids of all users who are a direct member of a specific room role in this room

Parameters:

roomRoleName - the name of the room role

Returns:

Array containing the unique ids of all users who are assigned directly to a specific room role in this room object

getDirectRoomRolePrincipalSetIds

String[] getDirectRoomRolePrincipalSetIds(String roomRoleName)

Get the ids of all principalSets who are a direct member of a specific room role in this room

Parameters:

roomRoleName - the name of the room role

Returns:

Array containing the unique ids of all principalSets that are assigned directly to a specific room role in this room object

isMember

boolean isMember(String memberId)

Tests whether a specific principal (user or principalSet) has access to this room

Parameters:

memberId - the uniqueId of the principal to be tested

Returns:

boolean true if the given principal is member of any room role, false otherwise

getRoomRole

IRoomRole getRoomRole(String roleName)
                      throws NoSuchRoomRoleException

Get a room role instance for a given role name if such a room role exists in the current room

Parameters:

roleName -

Returns:

the room role instance

Throws:

NoSuchRoomRoleException

getInitialRoomRole

IRoomRole getInitialRoomRole()

Get an instance of the initial room role

Returns:

the initial room role

getAdminRoomRole

IRoomRole getAdminRoomRole()

Get an instance of the admin room role

Returns:

the admin room role

getRoomRolesForUser

IRoomRole[] getRoomRolesForUser(String userId)

Deprecated. use getRoomRolesForMember(String) instead

Get the room roles for a specific user in this room

Parameters:

userId - the uniqueId of the user

Returns:

Array of type IRoomRole containing all room roles the given user is member of in this room.

getRoomRolesForMember

IRoomRole[] getRoomRolesForMember(String memberId)

Get the room roles for a specific user or principalSet in this room (directly and indirectly)

Parameters:

memberId - the uniqueId of the principal (user or principalSet)

Returns:

Array of type IRoomRole containing all room roles the given principal is member of in this room (directly and indirectly)

hasRoomRole

boolean hasRoomRole(String roomRoleName)

Check if a room role with a given role name exists in the room

Parameters:

roomRoleName - the name of the room role

Returns:

true if the role exists, false if not

getAllRoomRoleNames

String[] getAllRoomRoleNames()

Get the names of all room roles in the room

Returns:

Array containing all room role names

getAllRoomRoles

IRoomRole[] getAllRoomRoles()

Get all room roles of a room

Returns:

Array of type IRoomRole containing all room role objects of this room.

See Also:

IRoomRole

getInitialRoleName

String getInitialRoleName()

Get the name of the Initial Role of the room. The initial role is used for new members of a community (self registration).

Returns:

the name of the Initial Role of this room

getAdminRoleName

String getAdminRoleName()

Get the name of the Admin Role of the room.

Returns:

the name of the Admin Role of this room

requestMembership

boolean requestMembership(String userId)

Request membership for a specific user in a room. In the current implementation of this method an email is sent from the specified user to the owner of the room. The owner can then invite the new user using the room maintenance UI.

Parameters:

userId - the uniqueID of the user

Returns:

true if successful, false otherwise

isCommunity

boolean isCommunity()

Check if the room is a community

Returns:

true if the room is a community, false otherwise

isListedRoom

boolean isListedRoom()

Check if the room is a listed room

Returns:

true if the room is a listed room, false otherwise

isUnlistedRoom

boolean isUnlistedRoom()

Check if the room is a unlisted room

Returns:

true if the room is a unlisted room, false otherwise

registerUserInCommunity

boolean registerUserInCommunity(String userId)

Subscribe a user to a community. The given user will be assigned to the default room role in the community.

Parameters:

userId - the uniqueId of the user to be added.

Returns:

true if the room is a community and the given user could be added successfully to the default room role, false otherwise

deregisterUserFromCommunity

boolean deregisterUserFromCommunity(String userId)

Unsubscribe a user from a community. The given user will be removed from all room roles in the community.

Parameters:

userId - the uniqueId of the user to be removed

Returns:

true if the room is a community and removing the user from all room roles was successful, false otherwise

supportsRootGroup

boolean supportsRootGroup()

Check - depending on the room version - if a root group containing all room role groups is supported

Returns:

true if this room has a root group, false otherwise

supportsParameterChanges

boolean supportsParameterChanges()

Check - depending on the room version - if changing the room parameters is supported or not

Returns:

true if this room supports parameter updates, false otherwise

isRoomPartRemoveable

boolean isRoomPartRemoveable(String roomPartId)

Check whether a specific room part can be removed in the room maintenance UI or not

Parameters:

roomPartId -

Returns:

true if the room part is removeable in the UI, false otherwise

createAndAddRoomPart

IRoomPart createAndAddRoomPart(String roompartName,
                               String roompartTemplate,
                               boolean removeable,
                               IRoleMapping[] roleMappings,
                               IRoomParameterValue[] roompartParameters,
                               IParameterMapping[] parameterMappings)
                               throws RoomPartCreationException

Create a new room part instance from a room part template and attach it to the room

Parameters:

name - the name for the new instance

roomPartTemplate - the name of the room part template

removeable - true if the room part should be removeable in the room maintenance UI, false otherwise

roleMappings - the mappings from room part roles to room roles

parameters - the external parameters from the roomPartTemplate with values

parameterMappings - the parameters from the roomPartTemplate which are mapped to room parameters

Returns:

a new instance of IRoomPart

Throws:

RoomPartCreationException

createRoomPartInstance

IRoomPart createRoomPartInstance(String name,
                                 String roomPartTemplate,
                                 IRoleMapping[] roleMappings,
                                 IRoomParameterValue[] parameters,
                                 IParameterMapping[] parameterMappings)
                                 throws RoomPartCreationException

Deprecated.

Create a new room part instance from a room part template and attach it to the room

Parameters:

name - the name for the new instance

roomPartTemplate - the name of the room part template

roleMappings - the mappings from room part roles to room roles

parameters - the external parameters from the roomPartTemplate with values

parameterMappings - the parameters from the roomPartTemplate which are mapped to room parameters

Returns:

a new instance of IRoomPart

Throws:

RoomPartCreationException

removeAndDeleteRoomPart

boolean removeAndDeleteRoomPart(String roomPartInstanceId,
                                boolean overrideRemovalProtection)

Remove a room part instance from the room and delete it

Parameters:

roomPartInstanceId - the instance id of the room part to be deleted

overrideRemovalProtection - true if the room part should be removed also if it is marked as not removeable

Returns:

true if deletion has been successful, false otherwise

removeRoomPartInstance

boolean removeRoomPartInstance(String roomPartInstanceId)

Deprecated.

Remove a room part instance from the room

Parameters:

roomPartInstanceId - the instance id of the room part to be removed

Returns:

true if removal has been successful, false otherwise

getRoomParts

IRoomPart[] getRoomParts()

Get all Room Parts contained in this room

Returns:

Array containing all Room Parts of this room

removeRoomRole

void removeRoomRole(String roleName)
                    throws NoSuchRoomRoleException,
                           RoomException

Remove a room role from a room. A room role that contains users that are not assigned to another room role cannot be removed. A room role that comes from the room template cannot be removed. A room role that is mapped to a room part cannot be removed.

Parameters:

roleName - the name of the room role

Throws:

NoSuchRoomRoleException - if the room does not have a room role with the provided name

RoomException - if the room role cannot be removed

getPosition

int getPosition(String roomPartId)
                throws RoomException

Get the actual position of a Room Part in the DTN. The position of the first element in the DTN is 0.

Parameters:

child - the id of the Room Part

Returns:

the DTN position

Throws:

RoomException

setPosition

int setPosition(String roomPartId,
                int newPosition)
                throws RoomException

Set the position of a Room Part in the DTN. To set a room part to the first position in the DTN, DTN_ITEM_POS_TOP should be passed as parameter newPosition. To set a room part to the last position in the DTN, DTN_ITEM_POS_BOTTOM should be passed as parameter newPosition. If a Room Part is set to position 50 using this method and there are only 3 elements in the DTN then 2 (counting starts at 0) is returned and subsequent calls to getPosition(String) will also return 2.

Parameters:

child - the id of the Room Part

newPosition - the new position

Returns:

the new position (after the change). If the method is called with parameter newPosition=50 and there are only 3 elements in the DTN then 2 (counting starts at 0) is returned

Throws:

RoomException

getRoomEvents

IRoomStatusEvent[] getRoomEvents(long timeStamp,
                                 RoomStatusAction[] roomActions,
                                 String[] userIds,
                                 int maxResultSize)

Retrieve room events for this room according to the specified search criteria. The array is ordered by timestamp starting with the most recent events.

Parameters:

timeStamp - look for events since this time specify null to get all StatusActions

roomActions - return only events with the specified RoomStatusAction values, specify null to get all RoomStatusActions

userIds - return only events caused by the specified users, specify null to retrieve events by any user

maxResultSize - cut the size of the result to this number, use 0 for default of 100

Returns:

IRoomStatusEvent[] array of events with the specified criteria

getRoomUsage

IRoomUsageUser[] getRoomUsage(long timeStamp,
                              int listLength)

Returns data on the usage of this per user, ordered by the number of visits (most visiting users first).

Parameters:

timeStamp - time since when to count

listLength - cut the size of the returned array to this value (in case the room has more users)

Returns:

IRoomUsageUser[] usage data per user

getArchivingObjectState

com.sapportals.wcm.repository.service.archiving.AOStates getArchivingObjectState()

Gets the Archiving Object (AO) state for this room. If there is no AO created for this room, null is returned.

Returns:

the state

Access Rights

This class can be accessed from:

SC	DC	Public Part	ACH
[sap.com] KMC-COLL	[sap.com] tc/kmc/coll/room	api	EP-KM-CRS