org.kurento.room

Class RoomManager

java.lang.Object

org.kurento.room.RoomManager

public class RoomManager
extends Object

The Kurento room manager represents an SDK for any developer that wants to implement the Room server-side application. They can build their application on top of the manager’s Java API and implement their desired business logic without having to consider room or media-specific details.

Author:

Radu Tom Vlad

Constructor Summary

Constructors

Constructor and Description
RoomManager(RoomEventHandler roomEventHandler, KurentoClientProvider kcProvider) Provides an instance of the room manager by setting an event handler.
RoomManager(UserNotificationService notificationService, KurentoClientProvider kcProvider) Provides an instance of the room manager by setting an user notification service that will be used by the default event handler to send responses and notifications back to the clients.

Method Summary

Methods

Modifier and Type	Method and Description
void	addMediaElement(String participantId, org.kurento.client.MediaElement element) Applies a media element (filter, recorder, etc.) to media that is currently streaming or that might get streamed sometime in the future.
void	close() Closes all resources.
void	closeRoom(String roomName) Closes an existing room by releasing all resources that were allocated for the room.
boolean	createRoom(String roomName) Creates a room if it doesn’t already exist.
void	evictParticipant(String participantId) Method that tries to remove a participant from her room.
Set<UserParticipant>	getParticipants(String roomName) Returns all the participants inside a room.
Set<UserParticipant>	getPeerPublishers(String participantId) Returns the peer’s publishers (participants from which the peer is receiving media).
Set<UserParticipant>	getPeerSubscribers(String participantId) Returns the peer’s subscribers (participants towards the peer is streaming media).
org.kurento.client.MediaPipeline	getPipeline(String participantId) Returns the media pipeline used by the participant.
Set<UserParticipant>	getPublishers(String roomName) Returns all the publishers (participants streaming their media) inside a room.
Set<String>	getRooms() Returns all currently active (opened) rooms.
Set<UserParticipant>	getSubscribers(String roomName) Returns all the subscribers (participants subscribed to a least one stream of another user) inside a room.
void	joinRoom(String userName, String roomName, ParticipantRequest request) Represents a client’s request to join a room.
void	leaveRoom(ParticipantRequest request) Represents a client’s notification that she’s leaving the room.
void	onIceCandidate(String endpointName, String candidate, int sdpMLineIndex, String sdpMid, ParticipantRequest request) Request that carries info about an ICE candidate gathered on the client side.
void	publishMedia(ParticipantRequest request, String sdpOffer, boolean doLoopback, org.kurento.client.MediaElement... mediaElements) Represents a client’s request to start streaming her local media to anyone inside the room.
void	removeMediaElement(String participantId, org.kurento.client.MediaElement element) Disconnects and removes media element (filter, recorder, etc.) from a media stream.
void	sendMessage(String message, String userName, String roomName, ParticipantRequest request) Used by clients to send written messages to all other participants in the room. Side effects: The room event handler should acknowledge the client’s request by sending an empty message.
void	subscribe(String remoteName, String sdpOffer, ParticipantRequest request) Represents a client’s request to receive media from room participants that published their media.
void	unpublishMedia(ParticipantRequest request) Represents a client’s request to stop publishing her media stream.
void	unsubscribe(String remoteName, ParticipantRequest request) Represents a client’s request to stop receiving media from the remote peer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RoomManager

public RoomManager(UserNotificationService notificationService,
           KurentoClientProvider kcProvider)

Provides an instance of the room manager by setting an user notification service that will be used by the default event handler to send responses and notifications back to the clients.

Parameters:

notificationService - encapsulates the communication layer, used to instantiate DefaultRoomEventHandler

kcProvider - enables the manager to obtain Kurento Client instances

RoomManager

public RoomManager(RoomEventHandler roomEventHandler,
           KurentoClientProvider kcProvider)

Provides an instance of the room manager by setting an event handler.

Parameters:

roomEventHandler - the room event handler implementation

kcProvider - enables the manager to obtain Kurento Client instances

Method Detail

joinRoom

public void joinRoom(String userName,
            String roomName,
            ParticipantRequest request)

Represents a client’s request to join a room. If the room does not exist, it is created.
Side effects: The room event handler should send notifications to the existing participants in the room to inform about the new peer.

Parameters:

userName - name or identifier of the user in the room. Will be used to identify her WebRTC media peer (from the client-side).

roomName - name or identifier of the room

request - instance of ParticipantRequest POJO containing the participant’s id and a request id (optional identifier of the request at the communications level, included when responding back to the client)

leaveRoom

public void leaveRoom(ParticipantRequest request)

Represents a client’s notification that she’s leaving the room.
Side effects: The room event handler should acknowledge the client’s request by sending an empty message. Should also send notifications to the other participants in the room to inform about the one that has just left.

Parameters:

request - instance of ParticipantRequest POJO

publishMedia

public void publishMedia(ParticipantRequest request,
                String sdpOffer,
                boolean doLoopback,
                org.kurento.client.MediaElement... mediaElements)

Represents a client’s request to start streaming her local media to anyone inside the room. The media elements should have been created using the same pipeline as the publisher's. The streaming media endpoint situated on the server is automatically connected to itself thus realizing what is known as a loopback connection. The loopback is performed after applying all additional media elements specified as parameters (in the same order as they appear in the params list).
Side effects: The room event handler should send notifications to the existing participants in the room to inform about the new stream that has been published. Should also answer to the client’s endpoint by sending it the SDP answer generated by the WebRTC endpoint on the server.

Parameters:

request - instance of ParticipantRequest POJO

sdpOffer - SDP offer String generated by the client’s WebRTC peer

doLoopback - loopback flag

mediaElements - variable array of media elements (filters, recorders, etc.) that are connected between the source WebRTC endpoint and the subscriber endpoints

unpublishMedia

public void unpublishMedia(ParticipantRequest request)

Represents a client’s request to stop publishing her media stream. All media elements on the server-side connected to this peer will be disconnected and released. The peer is left ready for publishing her media in the future.
Side effects: The room event handler should send notifications to the existing participants in the room to inform that streaming from this endpoint has ended. Should also acknowledge the client’s request by sending an empty message.

Parameters:

request - instance of ParticipantRequest POJO

subscribe

public void subscribe(String remoteName,
             String sdpOffer,
             ParticipantRequest request)

Represents a client’s request to receive media from room participants that published their media. Will have the same result when a publisher requests its own media stream.
Side effects: The room event handler should answer to the client’s endpoint by sending it the SDP answer generated by the its receiving WebRTC endpoint on the server.

Parameters:

remoteName - identification of the remote stream which is effectively the peer’s name (participant)

sdpOffer - SDP offer String generated by the client’s WebRTC peer

request - instance of ParticipantRequest POJO

unsubscribe

public void unsubscribe(String remoteName,
               ParticipantRequest request)

Represents a client’s request to stop receiving media from the remote peer.
Side effects: The room event handler should acknowledge the client’s request by sending an empty message.

Parameters:

remoteName - identification of the remote stream which is effectively the peer’s name (participant)

request - instance of ParticipantRequest POJO

sendMessage

public void sendMessage(String message,
               String userName,
               String roomName,
               ParticipantRequest request)

Used by clients to send written messages to all other participants in the room.
Side effects: The room event handler should acknowledge the client’s request by sending an empty message. Should also send notifications to the all participants in the room with the message and its sender.

Parameters:

message - message contents

userName - name or identifier of the user in the room

roomName - room’s name

request - instance of ParticipantRequest POJO

onIceCandidate

public void onIceCandidate(String endpointName,
                  String candidate,
                  int sdpMLineIndex,
                  String sdpMid,
                  ParticipantRequest request)

Request that carries info about an ICE candidate gathered on the client side. This information is required to implement the trickle ICE mechanism. Should be triggered or called whenever an icecandidate event is created by a RTCPeerConnection.
Side effects: The room event handler should acknowledge the client’s request by sending an empty message.

Parameters:

endpointName - the name of the peer whose ICE candidate was gathered

candidate - the candidate attribute information

sdpMLineIndex - the index (starting at zero) of the m-line in the SDP this candidate is associated with

sdpMid - media stream identification, "audio" or "video", for the m-line this candidate is associated with

request - instance of ParticipantRequest POJO

close

@PreDestroy
public void close()

Closes all resources. This method has been annotated with the @PreDestroy directive (javax.annotation package) so that it will be automatically called when the RoomManager instance is container-managed.
Side effects: The room event handler should send notifications to all participants to inform that their room has been forcibly closed.

See Also:

closeRoom(String)

evictParticipant

public void evictParticipant(String participantId)
                      throws AdminException

Method that tries to remove a participant from her room.
Side effects: The room event handler should notify the remaining participants. If none are left and the room gets closed, the RoomEventHandler.onRoomClosed(String, Set) method will be called.

Parameters:

participantId - identifier of the participant

Throws:

AdminException - in case that no participant exists with the given id or it was impossible to perform the operation

getRooms

public Set<String> getRooms()

Returns all currently active (opened) rooms.

Returns:

set of the rooms’ identifiers (names)

getParticipants

public Set<UserParticipant> getParticipants(String roomName)
                                     throws AdminException

Returns all the participants inside a room.

Parameters:

roomName - name or identifier of the room

Returns:

set of UserParticipant POJOS (an instance contains the participant’s identifier and her user name)

Throws:

AdminException - in case the room doesn’t exist

getPublishers

public Set<UserParticipant> getPublishers(String roomName)
                                   throws AdminException

Returns all the publishers (participants streaming their media) inside a room.

Parameters:

roomName - name or identifier of the room

Returns:

set of UserParticipant POJOS representing the existing publishers

Throws:

AdminException - in case the room doesn’t exist

getSubscribers

public Set<UserParticipant> getSubscribers(String roomName)
                                    throws AdminException

Returns all the subscribers (participants subscribed to a least one stream of another user) inside a room. A publisher is automatically subscribed to its own stream (loopback) and will not be included in the returned values unless it requests explicitly a connection to its own or another user’s stream.

Parameters:

roomName - name or identifier of the room

Returns:

set of UserParticipant POJOS representing the existing subscribers

Throws:

AdminException - in case the room doesn’t exist

getPeerPublishers

public Set<UserParticipant> getPeerPublishers(String participantId)
                                       throws AdminException

Returns the peer’s publishers (participants from which the peer is receiving media). The own stream doesn’t count.

Parameters:

participantId - identifier of the participant

Returns:

set of UserParticipant POJOS representing the publishers this participant is currently subscribed to

Throws:

AdminException - in case the participant doesn’t exist

getPeerSubscribers

public Set<UserParticipant> getPeerSubscribers(String participantId)
                                        throws AdminException

Returns the peer’s subscribers (participants towards the peer is streaming media). The own stream doesn’t count.

Parameters:

participantId - identifier of the participant

Returns:

set of UserParticipant POJOS representing the participants subscribed to this peer

Throws:

AdminException - in case the participant doesn’t exist

createRoom

public boolean createRoom(String roomName)
                   throws AdminException

Creates a room if it doesn’t already exist.

Parameters:

roomName - name or identifier of the room

Returns:

true if the room has been created, false if it already exists with same name.

Throws:

AdminException - in case there was a problem obtaining the required instance of the Kurento Client

getPipeline

public org.kurento.client.MediaPipeline getPipeline(String participantId)
                                             throws AdminException

Returns the media pipeline used by the participant.

Parameters:

participantId - identifier of the participant

Returns:

the Media Pipeline object

Throws:

AdminException - in case the participant doesn’t exist

closeRoom

public void closeRoom(String roomName)
               throws AdminException

Closes an existing room by releasing all resources that were allocated for the room. Once closed, the room can be reopened (will be empty and it will use another Media Pipeline). Existing participants will be evicted.
Side effects: The room event handler should send notifications to the existing participants in the room to inform that the room was forcibly closed.

Parameters:

roomName - name or identifier of the room

Throws:

AdminException - in case the room doesn’t exist or has been already closed

addMediaElement

public void addMediaElement(String participantId,
                   org.kurento.client.MediaElement element)
                     throws AdminException

Applies a media element (filter, recorder, etc.) to media that is currently streaming or that might get streamed sometime in the future. The element should have been created using the same pipeline as the publisher's.

Parameters:

participantId - identifier of the owner of the stream

element - media element to be added

Throws:

AdminException - in case the participant doesn’t exist, has been closed or on error when applying the filter

removeMediaElement

public void removeMediaElement(String participantId,
                      org.kurento.client.MediaElement element)
                        throws AdminException

Disconnects and removes media element (filter, recorder, etc.) from a media stream.

Parameters:

participantId - identifier of the participant

element - media element to be removed

Throws:

AdminException - in case the participant doesn’t exist, has been closed or on error when removing the filter