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	createRoomPartInstance(String name, String roomPartTemplate, IRoleMapping[] roleMappings, IRoomParameterValue[] parameters, IParameterMapping[] parameterMappings) Create a new room part instance from a room part template and attach it to the room
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.
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	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
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[]	getRoomRolesForUser(String userId) Get the room roles for a specific user in this room
String[]	getRoomRoleUserIds(String roomRoleName) Get the ids of all users who are member 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() Get all users who are member of any room role in this room.
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 userId) Tests whether a specific user has access to this room
boolean	isPrivacyTypeChangeAllowed() The room template may define the room privacy type as 'strict' which means that no changes are allowed.
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	removeRoomPartInstance(String roomPartInstanceId) Remove a room part instance from the 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	setRoomUsers(IRoomUsers roomUsers, boolean sendNotifications) Assign users to the room.
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

public 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

public 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

public String getId()

Get the id of a room

Returns:

String containing the technical id of this room object

getRoomInfo

public 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

public 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

public Date getCreationDate()

Get the creation date of a room

Returns:

Date object containing the creation date of this room object

getLastModified

public 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

public 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

isHidden

public boolean isHidden()

Check if the room is hidden

Returns:

true if the room is hidden, false otherwise

See Also:

setHidden(boolean)

setHidden

public 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

public boolean isLocked()

Check if the room is locked

Returns:

true if the room is locked, false otherwise

See Also:

IRoomSystem#lock(), IRoomSystem#unlock()

lock

public 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

public 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

public String getName()

Get the name of a room

Returns:

String containing the name of this room object

setName

public 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

public String getDescription()

Get the description of a room

Returns:

String containing the description of this room object

setDescription

public 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

public 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

public 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

public 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

public 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

public ITemplate getTemplate()
                      throws TemplateInstantiationException

Get the room template this room is based on

Returns:

the room template instance

Throws:

TemplateInstantiationException

getTemplateName

public 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

public 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

public IRoomCategory[] getCategories()

Get the categories of a room

Returns:

Array containing the categories assigned to this room

setCategories

public 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

public String getOwnerId()

Get the owner of a room

Returns:

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

getPrivacyType

public 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

public 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

public 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()

Returns:

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

setProperty

public 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

public 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

public String[] getAllRoomParameterNames()

Get the parameter names of a room

Returns:

Array containing the names of all parameters of this room object

getAllRoomParameters

public IRoomParameterValue[] getAllRoomParameters()

Get the parameters of a room

Returns:

Array containing all parameters of this room object

getRoomParameter

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public IRoomUsers getRoomUsers()

Get all users who are 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

setRoomUsers

public boolean setRoomUsers(IRoomUsers roomUsers,
                            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:

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

getAllRoomUserIds

public 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.

Returns:

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

getRoomRoleUserIds

public String[] getRoomRoleUserIds(String roomRoleName)

Get the ids of all users who are 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 to a specific room role in this room object

isMember

public boolean isMember(String userId)

Tests whether a specific user has access to this room

Parameters:

userId - the uniqueId of the user to be tested

Returns:

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

getRoomRole

public 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

public IRoomRole getInitialRoomRole()

Get an instance of the initial room role

Returns:

the initial room role

getAdminRoomRole

public IRoomRole getAdminRoomRole()

Get an instance of the admin room role

Returns:

the admin room role

getRoomRolesForUser

public IRoomRole[] getRoomRolesForUser(String userId)

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.

hasRoomRole

public 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

public String[] getAllRoomRoleNames()

Get the names of all room roles in the room

Returns:

Array containing all room role names

getAllRoomRoles

public 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

public 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

public String getAdminRoleName()

Get the name of the Admin Role of the room.

Returns:

the name of the Admin Role of this room

requestMembership

public 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

public boolean isCommunity()

Check if the room is a community

Returns:

true if the room is a community, false otherwise

isListedRoom

public boolean isListedRoom()

Check if the room is a listed room

Returns:

true if the room is a listed room, false otherwise

isUnlistedRoom

public boolean isUnlistedRoom()

Check if the room is a unlisted room

Returns:

true if the room is a unlisted room, false otherwise

registerUserInCommunity

public 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

public 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

public 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

public 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

createRoomPartInstance

public IRoomPart createRoomPartInstance(String name,
                                        String roomPartTemplate,
                                        IRoleMapping[] roleMappings,
                                        IRoomParameterValue[] parameters,
                                        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

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

removeRoomPartInstance

public boolean removeRoomPartInstance(String roomPartInstanceId)

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

public IRoomPart[] getRoomParts()

Get all Room Parts contained in this room

Returns:

Array containing all Room Parts of this room

getPosition

public 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.

Returns:

the DTN position

Throws:

RoomException

setPosition

public 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:

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

public 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

public 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