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 java.lang.String	KM_SERVICE_ID The name of the KM Service - for use in other applications
static java.lang.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.
com.sap.ip.collaboration.room.api.template.IRoomRole	createRoomRole(java.lang.String roleName, java.lang.String roleDescription) Creates a new instance of IRoomRole
IRoomUsers	createRoomUsersObject() Get an empty instance of IRoomUsers.
boolean	deleteRoom(java.lang.String id) Delete the room with the given id
boolean	existsRoom(java.lang.String id) Check if a room with certain room id exists
boolean	existsRoomTemplate(java.lang.String templateName) Check if a room template with a given template name exists
IRoom[]	getAllRoomsForUser(com.sap.security.api.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).
java.lang.String[]	getAvailableRoomTemplateNames() Get a list of available room template names
com.sap.ip.collaboration.room.api.template.ITemplate[]	getAvailableRoomTemplates() Get a list of available room templates
com.sap.netweaver.coll.shared.api.extension.IExtensionPoint[]	getExtensionPoints() Get a list of all available room extension points
java.util.Date	getLastVisit(java.lang.String roomId) Get the Date when the given room was last visited by any user
java.util.Date	getLastVisit(java.lang.String roomId, java.lang.String userId) Get the Date when the given user visited the given room last time
com.sap.ip.collaboration.room.api.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.
com.sap.ip.collaboration.room.api.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.
com.sap.ip.collaboration.room.api.relman.IRelationManager	getRelationManager() Get an instance of the room relation manager
IRoom	getRoom(java.lang.String roomId) Get a room instance from a room ID
java.lang.String	getRoomAccessURLExternal(java.lang.String roomId) Get an external Access URL for a specific room.
java.lang.String	getRoomAccessURLInternal(java.lang.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.
java.lang.String	getRoomDescription(java.lang.String roomId) Get the description of the room with the given room id
com.sap.ip.collaboration.room.api.IRoomStatusEvent[]	getRoomEvents(java.lang.String roomId, long timeStamp, com.sap.ip.collaboration.room.api.RoomStatusAction[] roomActions, java.lang.String[] userIds, int maxResultSize) Retrieve room events according to the specified search criteria.
IRoom	getRoomFromRID(java.lang.String roomRID) Get a room instance from a room RID
java.lang.String	getRoomName(java.lang.String roomId) Get the name of the room with the given room id
com.sap.ip.collaboration.room.api.template.IRoomRole[]	getRoomRolesForUser(java.lang.String roomId, com.sap.security.api.IUser user) Get the room roles for a specific user in a specific room
IRoom[]	getRoomsForUser(com.sap.security.api.IUser user, boolean hiddenFlag) Get only hidden or unhidden rooms a specific user is allowed to enter.
IRoom[]	getRoomsWithPrivacy(com.sap.ip.collaboration.room.api.types.RoomPrivacyType type) Get an Array containing all rooms with a specific privacy (Community, Listed Room, Unlisted Room).
com.sap.ip.collaboration.room.api.template.ITemplate	getRoomTemplate(java.lang.String templateName) Get a room template instance
com.sap.ip.collaboration.room.api.IRoomUsageUser[]	getRoomUsage(java.lang.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(java.lang.String roomId) Check if a room is locked

Field Detail

KM_SERVICE_ID

public static final java.lang.String KM_SERVICE_ID

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

PORTAL_SERVICE_ID

public static final java.lang.String PORTAL_SERVICE_ID

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

Method Detail

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 com.sap.ip.collaboration.room.api.template.IRoomRole createRoomRole(java.lang.String roleName,
                                                                           java.lang.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 java.lang.String[] getAvailableRoomTemplateNames()
                                                 throws com.sap.ip.collaboration.room.api.Exceptions.TemplateInstantiationException

Get a list of available room template names

Returns:

Array of Strings containing all room template names.

Throws:

TemplateInstantiationException -

getAvailableRoomTemplates

public com.sap.ip.collaboration.room.api.template.ITemplate[] getAvailableRoomTemplates()
                                                                                 throws com.sap.ip.collaboration.room.api.Exceptions.TemplateInstantiationException

Get a list of available room templates

Returns:

Array of type ITemplate containing all room templates

Throws:

TemplateInstantiationException -

existsRoomTemplate

public boolean existsRoomTemplate(java.lang.String templateName)
                           throws com.sap.ip.collaboration.room.api.Exceptions.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 com.sap.ip.collaboration.room.api.template.ITemplate getRoomTemplate(java.lang.String templateName)
                                                                     throws com.sap.ip.collaboration.room.api.Exceptions.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(java.lang.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(java.lang.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 boolean deleteRoom(java.lang.String id)

Delete the room with the given id

Parameters:

id - the id of the room to be deleted

Returns:

true if deleting was successful, false if there have been errors during room deletion. In this case it is not guaranteed (but still possible) that all parts of the room have been deleted.

getAllRoomsForUser

public IRoom[] getAllRoomsForUser(com.sap.security.api.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(com.sap.security.api.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(com.sap.ip.collaboration.room.api.types.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 java.lang.String getRoomAccessURLInternal(java.lang.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 java.lang.String getRoomAccessURLExternal(java.lang.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(java.lang.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(java.lang.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 java.util.Date getLastVisit(java.lang.String roomId,
                                   java.lang.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 java.util.Date getLastVisit(java.lang.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 java.lang.String getRoomName(java.lang.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 java.lang.String getRoomDescription(java.lang.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 com.sap.ip.collaboration.room.api.template.IRoomRole[] getRoomRolesForUser(java.lang.String roomId,
                                                                                  com.sap.security.api.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 com.sap.ip.collaboration.room.api.relman.IRelationManager getRelationManager()

Get an instance of the room relation manager

Returns:

instance of the room relation manager

getExtensionPoints

public com.sap.netweaver.coll.shared.api.extension.IExtensionPoint[] getExtensionPoints()

Get a list of all available room extension points

Returns:

Array containing all room extension points

getRoomEvents

public com.sap.ip.collaboration.room.api.IRoomStatusEvent[] getRoomEvents(java.lang.String roomId,
                                                                          long timeStamp,
                                                                          com.sap.ip.collaboration.room.api.RoomStatusAction[] roomActions,
                                                                          java.lang.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 com.sap.ip.collaboration.room.api.IRoomUsageUser[] getRoomUsage(java.lang.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 com.sap.ip.collaboration.room.api.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 com.sap.ip.collaboration.room.api.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