com.sap.ip.collaboration.room.api

Interface IRooms

public interface IRooms

Public Interface of the Rooms API

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

This interface is part of the Rooms API. It is public to all customers. It provides basic functionality concerning all rooms, such as room creation and retrieval.

The whole Rooms API (including this Interface) is covered by a KM Service. You can get Access to it using the following code:

 
 import com.sapportals.wcm.service.ServiceFactory;  
 IRooms roomsAPI = (IRooms) ServiceFactory.getInstance().getService(IRooms.KM_SERVICE_ID);
 

The Rooms API (including this Interface) is also covered by a Portal Service. To get Access to the Portal Service you may use the following code:

 import com.sapportals.portal.prt.runtime.PortalRuntime;
 IRooms roomsAPI = (IRooms) PortalRuntime.getRuntimeResources().getService(IRooms.PORTAL_SERVICE_ID);
 

Field Summary

static String	KM_SERVICE_ID The name of the KM Service - for use in other applications
static String	PORTAL_SERVICE_ID The name of the Portal Service - for use in other applications

Method Summary

IRoom	createRoom(IRoomInfo info, boolean sendNotifications) Create a new room To create a new room you first have to call getRoomCreationInfo(), fill the info object with properties and then call the createRoom(IRoomInfo) method.
IRoomRole	createRoomRole(String roleName, String roleDescription) Creates a new instance of IRoomRole
IRoomUsers	createRoomUsersObject() Get an empty instance of IRoomUsers.
boolean	deleteRoom(String id) Deprecated.
void	deleteRoom(String id, boolean sendNotifications) Delete the room with the given id
boolean	existsRoom(String id) Check if a room with certain room id exists
boolean	existsRoomTemplate(String templateName) Check if a room template with a given template name exists
IRoom[]	getAllRoomsForUser(IUser user) Get an Array containing ALL rooms a specific user is allowed to enter (all rooms in which the user is member of any room role).
String[]	getAvailableRoomTemplateNames() Get a list of available room template names
ITemplate[]	getAvailableRoomTemplates() Get a list of available room templates
IExtensionPoint[]	getExtensionPoints() Get a list of all available room extension points
Date	getLastVisit(String roomId) Get the Date when the given room was last visited by any user
Date	getLastVisit(String roomId, String userId) Get the Date when the given user visited the given room last time
IRoomUsage[]	getLeastVisitedRooms(int listLength, long timeStamp) Returns a list of the least visited rooms since the time given by timeStamp, ordered ascendingly by the number of visits.
IRoomUsage[]	getMostVisitedRooms(int listLength, long timeStamp) Returns a list of the most visited rooms since the time given by timeStamp, ordered descendingly by the number of visits.
IRelationManager	getRelationManager() Get an instance of the room relation manager
IResourceContext	getResourceContext(IUser contextUser) Deprecated. Please do not use anymore because of missing default locale Get a ResourceContext the given user as ContextUser
IRoom	getRoom(String roomId) Get a room instance from a room ID
String	getRoomAccessURLExternal(String roomId) Get an external Access URL for a specific room.
String	getRoomAccessURLInternal(String roomId) Get an internal Access URL for a specific room.
IRoomCategoryFactory	getRoomCategoryFactory() Get an instance of the IRoomCategoryFactory.
IRoomInfo	getRoomCreationInfo() Get a new instance of IRoomInfo.
String	getRoomDescription(String roomId) Get the description of the room with the given room id
IRoomStatusEvent[]	getRoomEvents(String roomId, long timeStamp, RoomStatusAction[] roomActions, String[] userIds, int maxResultSize) Retrieve room events according to the specified search criteria.
IRoom	getRoomFromRID(String roomRID) Get a room instance from a room RID
String	getRoomName(String roomId) Get the name of the room with the given room id
IRoomProps	getRoomProps() Get all room backend properties The room backend properties contain all technical information about the room backend system - such as Namespaces, Resource Types, Resource PropertyNames, Repository RIDs ...
IRoomRole[]	getRoomRolesForUser(String roomId, IUser user) Get the room roles for a specific user in a specific room
IRoom[]	getRoomsForUser(IUser user, boolean hiddenFlag) Get only hidden or unhidden rooms a specific user is allowed to enter.
IRoom[]	getRoomsWithPrivacy(RoomPrivacyType type) Get an Array containing all rooms with a specific privacy (Community, Listed Room, Unlisted Room).
ITemplate	getRoomTemplate(String templateName) Get a room template instance
IRoomUsageUser[]	getRoomUsage(String roomId, long timeStamp, int listLength) Returns data on room usage per user, ordered by the number of visits (most visiting users first).
boolean	isRoomLocked(String roomId) Check if a room is locked

Field Detail

KM_SERVICE_ID

public static final String KM_SERVICE_ID

The name of the KM Service - for use in other applications

See Also:

Constant Field Values

PORTAL_SERVICE_ID

public static final String PORTAL_SERVICE_ID

The name of the Portal Service - for use in other applications

See Also:

Constant Field Values

Method Detail

getRoomProps

public IRoomProps getRoomProps()

Get all room backend properties

The room backend properties contain all technical information about the room backend system - such as Namespaces, Resource Types, Resource PropertyNames, Repository RIDs ...

Returns:

an instance of IRoomProps

getRoomCreationInfo

public IRoomInfo getRoomCreationInfo()

Get a new instance of IRoomInfo. With such an instance you can define and create a new room.

Returns:

a new IRoomInfo object

See Also:

createRoom(IRoomInfo, boolean), IRoomInfo

createRoomUsersObject

public IRoomUsers createRoomUsersObject()

Get an empty instance of IRoomUsers. You can use such an instance of IRoomUsers to set all user relevant data in a new or in an existing room.

Returns:

an instance of IRoomUsers containing no users and no roles.

createRoomRole

public IRoomRole createRoomRole(String roleName,
                                String roleDescription)

Creates a new instance of IRoomRole

Parameters:

roleName - the name of the new room role

roleDescription - the description of the new room role

Returns:

an instance of IRoomRole

getAvailableRoomTemplateNames

public String[] getAvailableRoomTemplateNames()
                                       throws TemplateInstantiationException

Get a list of available room template names

Returns:

Array of Strings containing all room template names.

Throws:

TemplateInstantiationException

getAvailableRoomTemplates

public ITemplate[] getAvailableRoomTemplates()
                                      throws TemplateInstantiationException

Get a list of available room templates

Returns:

Array of type ITemplate containing all room templates

Throws:

TemplateInstantiationException

existsRoomTemplate

public boolean existsRoomTemplate(String templateName)
                           throws TemplateInstantiationException

Check if a room template with a given template name exists

Parameters:

templateName - the name of the room template

Returns:

true if the template exists, false otherwise

Throws:

TemplateInstantiationException

getRoomTemplate

public ITemplate getRoomTemplate(String templateName)
                          throws TemplateInstantiationException

Get a room template instance

Parameters:

templateName - the name of the room template

Returns:

the instance of the room template

Throws:

TemplateInstantiationException

createRoom

public IRoom createRoom(IRoomInfo info,
                        boolean sendNotifications)
                 throws RoomCreationException

Create a new room

To create a new room you first have to call getRoomCreationInfo(), fill the info object with properties and then call the createRoom(IRoomInfo) method.

Parameters:

info - the room info object describing the room to be created

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

Returns:

The new created room if creation was successful or null if creation was not possible.

Throws:

RoomCreationException - in case of any error. If the exception is thrown the room is not created in the backend system. The exception contains more info about the error cause (chained exception).

getRoom

public IRoom getRoom(String roomId)
              throws RoomInstantiationException

Get a room instance from a room ID

Parameters:

roomId - the id of the room to be instantiated

Returns:

the room with the given id if it exists

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

getRoomFromRID

public IRoom getRoomFromRID(String roomRID)
                     throws RoomInstantiationException

Get a room instance from a room RID

Parameters:

roomRID - the RID of the room to be instantiated

Returns:

the room with the given RID if it exists

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

deleteRoom

public void deleteRoom(String id,
                       boolean sendNotifications)
                throws RoomDeletionException,
                       com.sap.ip.collaboration.core.api.util.exception.IncompleteOperationException

Delete the room with the given id

Parameters:

id - the id of the room to be deleted

sendNotifications - if true, the users are sent notification mails

Throws:

RoomDeletionException - if the room cannot be deleted

com.sap.ip.collaboration.core.api.util.exception.IncompleteOperationException - if the room has been deleted with errors. In this case a cleanup function is activated after the deletion. It is not guaranteed (but possible) that all parts of the room have been deleted.

deleteRoom

public boolean deleteRoom(String id)

Deprecated.

getAllRoomsForUser

public IRoom[] getAllRoomsForUser(IUser user)

Get an Array containing ALL rooms a specific user is allowed to enter (all rooms in which the user is member of any room role).

Returns:

Array containing all rooms for the user

getRoomsForUser

public IRoom[] getRoomsForUser(IUser user,
                               boolean hiddenFlag)

Get only hidden or unhidden rooms a specific user is allowed to enter.

Parameters:

user - the user

hiddenFlag - the desired status of the rooms: true for hidden rooms, false for unhidden rooms

Returns:

Array containing all rooms matching the criteria

getRoomsWithPrivacy

public IRoom[] getRoomsWithPrivacy(RoomPrivacyType type)

Get an Array containing all rooms with a specific privacy (Community, Listed Room, Unlisted Room).

Parameters:

type - the wanted RoomPrivacyType

Returns:

Array containing all rooms with the given privacy

getRoomAccessURLInternal

public String getRoomAccessURLInternal(String roomId)
                                throws RoomInstantiationException

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

Attention: The internal Access URL cannot be used in an email or anywhere else outside the portal. The link will not work in such an environment. In this case you have to use getRoomAccessURLExternal(String)

Parameters:

roomId - the id of the room

Returns:

the internal Access URL of the room

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

getRoomAccessURLExternal

public String getRoomAccessURLExternal(String roomId)
                                throws RoomInstantiationException

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.

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

Parameters:

roomId - the id of the room

Returns:

the external Access URL of the room

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

existsRoom

public boolean existsRoom(String id)

Check if a room with certain room id exists

Parameters:

id - the id of the room

Returns:

true if the room exists, false otherwise

isRoomLocked

public boolean isRoomLocked(String roomId)
                     throws RoomInstantiationException

Check if a room is locked

Parameters:

roomId - the id of the room

Returns:

true if the room exists and is locked, false otherwise

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

getLastVisit

public Date getLastVisit(String roomId,
                         String userId)
                  throws RoomInstantiationException

Get the Date when the given user visited the given room last time

Parameters:

roomId - the id of the room

userId - the uniqueID of the user

Returns:

the date of the last visit of this user in this room

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

getLastVisit

public Date getLastVisit(String roomId)
                  throws RoomInstantiationException

Get the Date when the given room was last visited by any user

Parameters:

roomId - the id of the room

Returns:

the date when the given room was last visited

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

getRoomName

public String getRoomName(String roomId)
                   throws RoomInstantiationException

Get the name of the room with the given room id

Parameters:

roomId - the id of the room to get the name for

Returns:

the name of the room

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

getRoomDescription

public String getRoomDescription(String roomId)
                          throws RoomInstantiationException

Get the description of the room with the given room id

Parameters:

roomId - the id of the room to get the description for

Returns:

the description of the room

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

getRoomCategoryFactory

public IRoomCategoryFactory getRoomCategoryFactory()

Get an instance of the IRoomCategoryFactory.
Using this Factory you can create and instantiate IRoomCategory objects.

Returns:

the Factory instance

getRoomRolesForUser

public IRoomRole[] getRoomRolesForUser(String roomId,
                                       IUser user)
                                throws RoomInstantiationException

Get the room roles for a specific user in a specific room

Parameters:

roomId - the id of the room

user - the user

Returns:

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

Throws:

RoomInstantiationException - in case of an error in the backend system. The RoomInstantiationException is a chained exception and contains the causing error(s).

getRelationManager

public IRelationManager getRelationManager()

Get an instance of the room relation manager

Returns:

instance of the room relation manager

getExtensionPoints

public IExtensionPoint[] getExtensionPoints()

Get a list of all available room extension points

Returns:

Array containing all room extension points

getRoomEvents

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

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

Parameters:

roomId - id of the room

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(String roomId,
                                     long timeStamp,
                                     int listLength)

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

Parameters:

roomId - the room id

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

getMostVisitedRooms

public IRoomUsage[] getMostVisitedRooms(int listLength,
                                        long timeStamp)

Returns a list of the most visited rooms since the time given by timeStamp, ordered descendingly by the number of visits.

Parameters:

listLength - length of the list of rooms

timeStamp - time since when to start counting visits

Returns:

IRoomUsage[] usage data per room

getLeastVisitedRooms

public IRoomUsage[] getLeastVisitedRooms(int listLength,
                                         long timeStamp)

Returns a list of the least visited rooms since the time given by timeStamp, ordered ascendingly by the number of visits.

Parameters:

listLength - length of the list of rooms

timeStamp - time since when to start counting visits

Returns:

IRoomUsage[] usage data per room

getResourceContext

public IResourceContext getResourceContext(IUser contextUser)
                                    throws com.sapportals.portal.security.usermanagement.UserManagementException

Deprecated. Please do not use anymore because of missing default locale Get a ResourceContext the given user as ContextUser

Parameters:

contextUser - the EP6 user object

Returns:

Context with the contextuser converted to old IUser interface

Throws:

com.sapportals.portal.security.usermanagement.UserManagementException - is thrown if the user can't be converted from old to new IUser interface