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.

The application is in control of notifying any remote parties with the outcome of executing the requested actions.

Author:

Radu Tom Vlad

Constructor Summary

Constructors

Constructor and Description
RoomManager(RoomHandler roomHandler, KurentoClientProvider kcProvider) Provides an instance of the room manager by setting a room handler and the KurentoClient provider.

Method Summary

Modifier and Type	Method and Description
void	addMediaElement(String participantId, org.kurento.client.MediaElement element) Applies a media element (filter, recorder, mixer, etc.) to media that is currently streaming or that might get streamed sometime in the future.
void	addMediaElement(String participantId, org.kurento.client.MediaElement element, org.kurento.client.MediaType type) Applies a media element (filter, recorder, mixer, etc.) to media that is currently streaming or that might get streamed sometime in the future.
void	close() Closes all resources.
Set<UserParticipant>	closeRoom(String roomName) Closes an existing room by releasing all resources that were allocated for the room.
void	createRoom(KurentoClientSessionInfo kcSessionInfo) Creates a room if it doesn't already exist.
String	generatePublishOffer(String participantId) Represents a client's request to initiate the media connection from the server-side (generate the SDP offer and send it back to the client) and must be followed by processing the SDP answer from the client in order to establish the streaming.
UserParticipant	getParticipantInfo(String participantId) Searches for the participant using her identifier and returns the corresponding UserParticipant POJO.
String	getParticipantName(String participantId) Finds the participant's username.
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.
String	getRoomName(String participantId) Finds the room's name of a given participant.
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.
boolean	isClosed()
boolean	isPublisherStreaming(String participantId) Checks if a participant is currently streaming media.
Set<UserParticipant>	joinRoom(String userName, String roomName, boolean webParticipant, KurentoClientSessionInfo kcSessionInfo, String participantId) Represents a client's request to join a room.
Set<UserParticipant>	leaveRoom(String participantId) Represents a client's notification that she's leaving the room.
void	mutePublishedMedia(MutedMediaType muteType, String participantId) Mutes the streamed media of this publisher in a selective manner.
void	muteSubscribedMedia(String remoteName, MutedMediaType muteType, String participantId) Mutes the incoming media stream from the remote publisher in a selective manner.
void	onIceCandidate(String endpointName, String candidate, int sdpMLineIndex, String sdpMid, String participantId) Request that carries info about an ICE candidate gathered on the client side.
String	publishMedia(String participantId, boolean isOffer, String sdp, boolean doLoopback, org.kurento.client.MediaElement... mediaElements) Same as publishMedia(String, boolean, String, MediaElement, MediaType, boolean, MediaElement...) , using as loopback the published stream and no specific type of loopback connection.
String	publishMedia(String participantId, boolean isOffer, String sdp, org.kurento.client.MediaElement loopbackAlternativeSrc, org.kurento.client.MediaType loopbackConnectionType, boolean doLoopback, org.kurento.client.MediaElement... mediaElements) Represents a client's request to start streaming her local media to anyone inside the room.
String	publishMedia(String participantId, String sdp, boolean doLoopback, org.kurento.client.MediaElement... mediaElements) Same as publishMedia(String, boolean, String, MediaElement, MediaType, boolean, MediaElement...) where the sdp String is an offer generated by the remote peer, the published stream will be used for loopback (if required) and no specific type of loopback connection.
void	removeMediaElement(String participantId, org.kurento.client.MediaElement element) Disconnects and removes media element (filter, recorder, etc.) from a media stream.
String	subscribe(String remoteName, String sdpOffer, String participantId) Represents a client's request to receive media from room participants that published their media.
void	unmutePublishedMedia(String participantId) Reverts the effects of the mute operation.
void	unmuteSubscribedMedia(String remoteName, String participantId) Reverts any previous mute operation.
void	unpublishMedia(String participantId) Represents a client's request to stop publishing her media stream.
void	unsubscribe(String remoteName, String participantId) 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(RoomHandler roomHandler,
                   KurentoClientProvider kcProvider)

Provides an instance of the room manager by setting a room handler and the KurentoClient provider.

Parameters:

roomHandler - the room handler implementation

kcProvider - enables the manager to obtain Kurento Client instances

Method Detail

joinRoom

public Set<UserParticipant> joinRoom(String userName,
                                     String roomName,
                                     boolean webParticipant,
                                     KurentoClientSessionInfo kcSessionInfo,
                                     String participantId)
                              throws RoomException

Represents a client's request to join a room. The room must exist in order to perform the join.
Dev advice: 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

webParticipant - if true, the internal media endpoints will use the trickle ICE mechanism when establishing connections with external media peers (WebRtcEndpoint); if false, the media endpoint will be a RtpEndpoint, with no ICE implementation

kcSessionInfo - sessionInfo bean to be used to create the room in case it doesn't exist (if null, the room will not be created)

participantId - identifier of the participant

Returns:

set of existing peers of type UserParticipant, can be empty if first

Throws:

RoomException - on error while joining (like the room is not found or is closing)

leaveRoom

public Set<UserParticipant> leaveRoom(String participantId)
                               throws RoomException

Represents a client's notification that she's leaving the room. Will also close the room if there're no more peers.
Dev advice: Send notifications to the other participants in the room to inform about the one that's just left.

Parameters:

participantId - identifier of the participant

Returns:

set of remaining peers of type UserParticipant, if empty this method has closed the room

Throws:

RoomException - on error leaving the room

publishMedia

public String publishMedia(String participantId,
                           boolean isOffer,
                           String sdp,
                           org.kurento.client.MediaElement loopbackAlternativeSrc,
                           org.kurento.client.MediaType loopbackConnectionType,
                           boolean doLoopback,
                           org.kurento.client.MediaElement... mediaElements)
                    throws RoomException

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 can be 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).
Dev advice: Send notifications to the existing participants in the room to inform about the new stream that has been published. Answer to the peer's request by sending it the SDP response (answer or updated offer) generated by the WebRTC endpoint on the server.

Parameters:

participantId - identifier of the participant

isOffer - if true, the sdp is an offer from remote, otherwise is the answer to the offer generated previously by the server endpoint

sdp - SDP String offer or answer, that's been generated by the client's WebRTC peer

loopbackAlternativeSrc - instead of connecting the endpoint to itself, use this MediaElement as source

loopbackConnectionType - the connection type for the loopback; if null, will stream both audio and video media

doLoopback - loopback flag

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

Returns:

the SDP response generated by the WebRTC endpoint on the server (answer to the client's offer or the updated offer previously generated by the server endpoint)

Throws:

RoomException - on error

publishMedia

public String publishMedia(String participantId,
                           String sdp,
                           boolean doLoopback,
                           org.kurento.client.MediaElement... mediaElements)
                    throws RoomException

Same as publishMedia(String, boolean, String, MediaElement, MediaType, boolean, MediaElement...) where the sdp String is an offer generated by the remote peer, the published stream will be used for loopback (if required) and no specific type of loopback connection.

Throws:

RoomException

See Also:

#publishMedia(String, boolean, String, boolean, MediaElement, MediaElement...)

publishMedia

public String publishMedia(String participantId,
                           boolean isOffer,
                           String sdp,
                           boolean doLoopback,
                           org.kurento.client.MediaElement... mediaElements)
                    throws RoomException

Same as publishMedia(String, boolean, String, MediaElement, MediaType, boolean, MediaElement...) , using as loopback the published stream and no specific type of loopback connection.

Throws:

RoomException

See Also:

#publishMedia(String, boolean, String, boolean, MediaElement, MediaElement...)

generatePublishOffer

public String generatePublishOffer(String participantId)
                            throws RoomException

Represents a client's request to initiate the media connection from the server-side (generate the SDP offer and send it back to the client) and must be followed by processing the SDP answer from the client in order to establish the streaming.

Parameters:

participantId - identifier of the participant

Returns:

the SDP offer generated by the WebRTC endpoint on the server

Throws:

RoomException - on error

See Also:

publishMedia(String, String, boolean, MediaElement...)

unpublishMedia

public void unpublishMedia(String participantId)
                    throws RoomException

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.
Dev advice: Send notifications to the existing participants in the room to inform that streaming from this endpoint has ended.

Parameters:

participantId - identifier of the participant

Throws:

RoomException - on error

subscribe

public String subscribe(String remoteName,
                        String sdpOffer,
                        String participantId)
                 throws RoomException

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.
Dev advice: Answer to the peer's request by sending it the SDP answer generated by the the 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

participantId - identifier of the participant

Returns:

the SDP answer generated by the receiving WebRTC endpoint on the server

Throws:

RoomException - on error

unsubscribe

public void unsubscribe(String remoteName,
                        String participantId)
                 throws RoomException

Represents a client's request to stop receiving media from the remote peer.

Parameters:

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

participantId - identifier of the participant

Throws:

RoomException - on error

onIceCandidate

public void onIceCandidate(String endpointName,
                           String candidate,
                           int sdpMLineIndex,
                           String sdpMid,
                           String participantId)
                    throws RoomException

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.

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

participantId - identifier of the participant

Throws:

RoomException - on error

addMediaElement

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

Applies a media element (filter, recorder, mixer, 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:

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

addMediaElement

public void addMediaElement(String participantId,
                            org.kurento.client.MediaElement element,
                            org.kurento.client.MediaType type)
                     throws RoomException

Applies a media element (filter, recorder, mixer, 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. The media connection can be of any type, that is audio, video, data or any (when the parameter is null).

Parameters:

participantId - identifier of the owner of the stream

element - media element to be added

type - the connection type (null is accepted, has the same result as calling addMediaElement(String, MediaElement))

Throws:

RoomException - 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 RoomException

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:

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

mutePublishedMedia

public void mutePublishedMedia(MutedMediaType muteType,
                               String participantId)
                        throws RoomException

Mutes the streamed media of this publisher in a selective manner.

Parameters:

muteType - which leg should be disconnected (audio, video or both)

participantId - identifier of the participant

Throws:

RoomException - in case the participant doesn't exist, has been closed, is not publishing or on error when performing the mute operation

unmutePublishedMedia

public void unmutePublishedMedia(String participantId)
                          throws RoomException

Reverts the effects of the mute operation.

Parameters:

participantId - identifier of the participant

Throws:

RoomException - in case the participant doesn't exist, has been closed, is not publishing or on error when reverting the mute operation

muteSubscribedMedia

public void muteSubscribedMedia(String remoteName,
                                MutedMediaType muteType,
                                String participantId)
                         throws RoomException

Mutes the incoming media stream from the remote publisher in a selective manner.

Parameters:

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

muteType - which leg should be disconnected (audio, video or both)

participantId - identifier of the participant

Throws:

RoomException - in case the participant doesn't exist, has been closed, is not publishing or on error when performing the mute operation

unmuteSubscribedMedia

public void unmuteSubscribedMedia(String remoteName,
                                  String participantId)
                           throws RoomException

Reverts any previous mute operation.

Parameters:

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

participantId - identifier of the participant

Throws:

RoomException - in case the participant doesn't exist, has been closed or on error when reverting the mute operation

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.
Dev advice: Send notifications to all participants to inform that their room has been forcibly closed.

See Also:

closeRoom(String)

isClosed

public boolean isClosed()

Returns:

true after close() has been called

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 RoomException

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:

RoomException - in case the room doesn't exist

getPublishers

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

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:

RoomException - in case the room doesn't exist

getSubscribers

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

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

Parameters:

roomName - name or identifier of the room

Returns:

set of UserParticipant POJOS representing the existing subscribers

Throws:

RoomException - in case the room doesn't exist

getPeerPublishers

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

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:

RoomException - in case the participant doesn't exist

getPeerSubscribers

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

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:

RoomException - in case the participant doesn't exist

isPublisherStreaming

public boolean isPublisherStreaming(String participantId)
                             throws RoomException

Checks if a participant is currently streaming media.

Parameters:

participantId - identifier of the participant

Returns:

true if the participant is streaming media, false otherwise

Throws:

RoomException - in case the participant doesn't exist or has been closed

createRoom

public void createRoom(KurentoClientSessionInfo kcSessionInfo)
                throws RoomException

Creates a room if it doesn't already exist. The room's name will be indicated by the session info bean.

Parameters:

kcSessionInfo - bean that will be passed to the KurentoClientProvider in order to obtain the KurentoClient that will be used by the room

Throws:

RoomException - in case of error while creating the room

closeRoom

public Set<UserParticipant> closeRoom(String roomName)
                               throws RoomException

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.
Dev advice: 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

Returns:

set of UserParticipant POJOS representing the room's participants

Throws:

RoomException - in case the room doesn't exist or has been already closed

getPipeline

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

Returns the media pipeline used by the participant.

Parameters:

participantId - identifier of the participant

Returns:

the Media Pipeline object

Throws:

RoomException - in case the participant doesn't exist

getRoomName

public String getRoomName(String participantId)
                   throws RoomException

Finds the room's name of a given participant.

Parameters:

participantId - identifier of the participant

Returns:

the name of the room

Throws:

RoomException - in case the participant doesn't exist

getParticipantName

public String getParticipantName(String participantId)
                          throws RoomException

Finds the participant's username.

Parameters:

participantId - identifier of the participant

Returns:

the participant's name

Throws:

RoomException - in case the participant doesn't exist

getParticipantInfo

public UserParticipant getParticipantInfo(String participantId)
                                   throws RoomException

Searches for the participant using her identifier and returns the corresponding UserParticipant POJO.

Parameters:

participantId - identifier of the participant

Returns:

UserParticipant POJO containing the participant's name and identifier

Throws:

RoomException - in case the participant doesn't exist