net.java.sip.communicator.service.protocol.media

Class AbstractOperationSetTelephonyConferencing<ProtocolProviderServiceT extends ProtocolProviderService,OperationSetBasicTelephonyT extends OperationSetBasicTelephony<ProtocolProviderServiceT>,MediaAwareCallT extends MediaAwareCall<MediaAwareCallPeerT,OperationSetBasicTelephonyT,ProtocolProviderServiceT>,MediaAwareCallPeerT extends MediaAwareCallPeer<MediaAwareCallT,?,ProtocolProviderServiceT>,CalleeAddressT>

java.lang.Object

net.java.sip.communicator.service.protocol.media.AbstractOperationSetTelephonyConferencing<ProtocolProviderServiceT,OperationSetBasicTelephonyT,MediaAwareCallT,MediaAwareCallPeerT,CalleeAddressT>

Type Parameters:

ProtocolProviderServiceT -

OperationSetBasicTelephonyT -

MediaAwareCallT -

MediaAwareCallPeerT -

CalleeAddressT -

All Implemented Interfaces:

java.beans.PropertyChangeListener, java.util.EventListener, CallChangeListener, CallListener, RegistrationStateChangeListener, OperationSet, OperationSetTelephonyConferencing

Direct Known Subclasses:

OperationSetTelephonyConferencingJabberImpl, OperationSetTelephonyConferencingSipImpl

public abstract class AbstractOperationSetTelephonyConferencing<ProtocolProviderServiceT extends ProtocolProviderService,OperationSetBasicTelephonyT extends OperationSetBasicTelephony<ProtocolProviderServiceT>,MediaAwareCallT extends MediaAwareCall<MediaAwareCallPeerT,OperationSetBasicTelephonyT,ProtocolProviderServiceT>,MediaAwareCallPeerT extends MediaAwareCallPeer<MediaAwareCallT,?,ProtocolProviderServiceT>,CalleeAddressT>
extends java.lang.Object
implements OperationSetTelephonyConferencing, RegistrationStateChangeListener, java.beans.PropertyChangeListener, CallListener, CallChangeListener

Represents a default implementation of OperationSetTelephonyConferencing in order to make it easier for implementers to provide complete solutions while focusing on implementation-specific details.

Author:

Lyubomir Marinov, Boris Grozev

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	ELEMENT_DISPLAY_TEXT The name of the conference-info XML element display-text.
protected static java.lang.String	ELEMENT_ENDPOINT The name of the conference-info XML element endpoint.
protected static java.lang.String	ELEMENT_MEDIA The name of the conference-info XML element media.
protected static java.lang.String	ELEMENT_SRC_ID The name of the conference-info XML element src-id.
protected static java.lang.String	ELEMENT_STATUS The name of the conference-info XML element status.
protected static java.lang.String	ELEMENT_TYPE The name of the conference-info XML element type.
protected static java.lang.String	ELEMENT_USER The name of the conference-info XML element user.
protected static java.lang.String	ELEMENT_USERS The name of the conference-info XML element users.
protected ProtocolProviderServiceT	parentProvider The ProtocolProviderService implementation which created this instance and for which telephony conferencing services are being provided by this instance.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractOperationSetTelephonyConferencing(ProtocolProviderServiceT parentProvider) Initializes a new AbstractOperationSetTelephonyConferencing instance which is to provide telephony conferencing services for the specified ProtocolProviderService implementation.

Method Summary

Modifier and Type	Method and Description
protected void	basicTelephonyChanged(OperationSetBasicTelephonyT oldValue, OperationSetBasicTelephonyT newValue) Notifies this OperationSetTelephonyConferencing that its basicTelephony property has changed its value from a specific oldValue to a specific newValue
protected void	callBegun(CallEvent event) Notifies this CallListener that a specific Call has been established.
void	callEnded(CallEvent event) Notifies this CallListener that a specific Call has ended.
void	callPeerAdded(CallPeerEvent event) Notifies this CallChangeListener that a specific CallPeer has been added to a specific Call.
void	callPeerRemoved(CallPeerEvent event) Notifies this CallChangeListener that a specific CallPeer has been remove from a specific Call.
void	callStateChanged(CallChangeEvent event) Notifies this CallChangeListener that a specific Call has changed its state.
Call	createConfCall(java.lang.String[] callees) Creates a conference call with the specified callees as call peers.
Call	createConfCall(java.lang.String[] callees, CallConference conference) Creates a conference Call with the specified callees as CallPeers.
protected abstract MediaAwareCallT	createOutgoingCall() Creates a new outgoing Call into which conference callees are to be invited by this OperationSetTelephonyConferencing.
protected abstract CallPeer	doInviteCalleeToCall(CalleeAddressT calleeAddress, MediaAwareCallT call) Invites a callee with a specific address to join a specific Call for the purposes of telephony conferencing.
OperationSetBasicTelephonyT	getBasicTelephony() Gets the OperationSetBasicTelephony implementation which this instance uses to carry out tasks such as establishing Calls.
protected ConferenceInfoDocument	getConferenceInfoDiff(ConferenceInfoDocument from, ConferenceInfoDocument to)
protected ConferenceInfoDocument	getCurrentConferenceInfo(MediaAwareCallPeer<?,?,?> callPeer) Creates a ConferenceInfoDocument which describes the current state of the conference in which callPeer participates.
protected abstract java.lang.String	getLocalDisplayName() Returns the display name for the local peer, which is to be used when we send Conference Information.
protected abstract java.lang.String	getLocalEntity(CallPeer callPeer) Returns a string to be used for the entity attribute of the user element for the local peer, in a Conference Information document to be sent to callPeer
protected long	getRemoteSourceID(MediaAwareCallPeer<?,?,?> callPeer, org.jitsi.service.neomedia.MediaType mediaType) Gets the remote SSRC to be reported in the conference-info XML for a specific CallPeer's media of a specific MediaType.
void	incomingCallReceived(CallEvent event) Notifies this CallListener that a specific incoming Call has been received.
CallPeer	inviteCalleeToCall(java.lang.String uri, Call call) Invites the callee represented by the specified uri to an already existing call.
protected void	notifyAll(Call call) Notifies all CallPeers associated with the telephony conference in which a specific Call is participating about changes in the telephony conference-related information.
protected abstract void	notifyCallPeers(Call call) Notifies all CallPeers associated with a specific Call about changes in the telephony conference-related information.
void	outgoingCallCreated(CallEvent event) Notifies this CallListener that a specific outgoing Call has been created.
protected abstract CalleeAddressT	parseAddressString(java.lang.String calleeAddressString) Parses a String value which represents a callee address specified by the user into an object which is to actually represent the callee during the invitation to a conference Call.
void	propertyChange(java.beans.PropertyChangeEvent ev) Notifies this PropertyChangeListener that the value of a specific property of the notifier it is registered with has changed.
void	registrationStateChanged(RegistrationStateChangeEvent event) Notifies this RegistrationStateChangeListener that the ProtocolProviderSerivce it is registered with has changed its registration state.
protected int	setConferenceInfoXML(MediaAwareCallPeerT callPeer, java.lang.String conferenceInfoXML) Updates the conference-related properties of a specific CallPeer such as conferenceFocus and conferenceMembers with information received from it as a conference focus in the form of a conference-info XML document.
ConferenceDescription	setupConference(ChatRoom chatRoom) Sets up a conference with no participants, which members of chatRoom can join.
static java.lang.String	stripParametersFromAddress(java.lang.String address) Removes the parameters (specified after a semicolon) from a specific address String if any are present in it.

Methods inherited from class java.lang.Object

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

Field Detail

ELEMENT_DISPLAY_TEXT

protected static final java.lang.String ELEMENT_DISPLAY_TEXT

The name of the conference-info XML element display-text.

See Also:

Constant Field Values

ELEMENT_ENDPOINT

protected static final java.lang.String ELEMENT_ENDPOINT

The name of the conference-info XML element endpoint.

See Also:

Constant Field Values

ELEMENT_MEDIA

protected static final java.lang.String ELEMENT_MEDIA

The name of the conference-info XML element media.

See Also:

Constant Field Values

ELEMENT_SRC_ID

protected static final java.lang.String ELEMENT_SRC_ID

The name of the conference-info XML element src-id.

See Also:

Constant Field Values

ELEMENT_STATUS

protected static final java.lang.String ELEMENT_STATUS

The name of the conference-info XML element status.

See Also:

Constant Field Values

ELEMENT_TYPE

protected static final java.lang.String ELEMENT_TYPE

The name of the conference-info XML element type.

See Also:

Constant Field Values

ELEMENT_USER

protected static final java.lang.String ELEMENT_USER

The name of the conference-info XML element user.

See Also:

Constant Field Values

ELEMENT_USERS

protected static final java.lang.String ELEMENT_USERS

The name of the conference-info XML element users.

See Also:

Constant Field Values

parentProvider

protected final ProtocolProviderServiceT extends ProtocolProviderService parentProvider

The ProtocolProviderService implementation which created this instance and for which telephony conferencing services are being provided by this instance.

Constructor Detail

AbstractOperationSetTelephonyConferencing

protected AbstractOperationSetTelephonyConferencing(ProtocolProviderServiceT parentProvider)

Initializes a new AbstractOperationSetTelephonyConferencing instance which is to provide telephony conferencing services for the specified ProtocolProviderService implementation.

Parameters:

parentProvider - the ProtocolProviderService implementation which has requested the creation of the new instance and for which the new instance is to provide telephony conferencing services

Method Detail

basicTelephonyChanged

protected void basicTelephonyChanged(OperationSetBasicTelephonyT oldValue,
                                     OperationSetBasicTelephonyT newValue)

Notifies this OperationSetTelephonyConferencing that its basicTelephony property has changed its value from a specific oldValue to a specific newValue

Parameters:

oldValue - the old value of the basicTelephony property

newValue - the new value of the basicTelephony property

callBegun

protected void callBegun(CallEvent event)

Notifies this CallListener that a specific Call has been established.

Parameters:

event - a CallEvent which specified the newly-established Call

callEnded

public void callEnded(CallEvent event)

Notifies this CallListener that a specific Call has ended.

Specified by:

callEnded in interface CallListener

Parameters:

event - a CallEvent which specified the Call which has just ended

callPeerAdded

public void callPeerAdded(CallPeerEvent event)

Notifies this CallChangeListener that a specific CallPeer has been added to a specific Call.

Specified by:

callPeerAdded in interface CallChangeListener

Parameters:

event - a CallPeerEvent which specifies the CallPeer which has been added to a Call

callPeerRemoved

public void callPeerRemoved(CallPeerEvent event)

Notifies this CallChangeListener that a specific CallPeer has been remove from a specific Call.

Specified by:

callPeerRemoved in interface CallChangeListener

Parameters:

event - a CallPeerEvent which specifies the CallPeer which has been removed from a Call

callStateChanged

public void callStateChanged(CallChangeEvent event)

Notifies this CallChangeListener that a specific Call has changed its state. Does nothing.

Specified by:

callStateChanged in interface CallChangeListener

Parameters:

event - a CallChangeEvent which specifies the Call which has changed its state, the very state which has been changed and the values of the state before and after the change

createConfCall

public Call createConfCall(java.lang.String[] callees)
                    throws OperationFailedException

Creates a conference call with the specified callees as call peers.

Specified by:

createConfCall in interface OperationSetTelephonyConferencing

Parameters:

callees - the list of addresses that we should call

Returns:

the newly created conference call containing all CallPeers

Throws:

OperationFailedException - if establishing the conference call fails

See Also:

OperationSetTelephonyConferencing.createConfCall(String[])

createConfCall

public Call createConfCall(java.lang.String[] callees,
                           CallConference conference)
                    throws OperationFailedException

Creates a conference Call with the specified callees as CallPeers.

Specified by:

createConfCall in interface OperationSetTelephonyConferencing

Parameters:

callees - the list of addresses that we should call

conference - the CallConference which represents the state of the telephony conference into which the specified callees are to be invited

Returns:

the newly-created conference call containing all CallPeers

Throws:

OperationFailedException - if establishing the conference Call fails

createOutgoingCall

protected abstract MediaAwareCallT createOutgoingCall()
                                               throws OperationFailedException

Creates a new outgoing Call into which conference callees are to be invited by this OperationSetTelephonyConferencing.

Returns:

a new outgoing Call into which conference callees are to be invited by this OperationSetTelephonyConferencing

Throws:

OperationFailedException - if anything goes wrong

doInviteCalleeToCall

protected abstract CallPeer doInviteCalleeToCall(CalleeAddressT calleeAddress,
                                                 MediaAwareCallT call)
                                          throws OperationFailedException

Invites a callee with a specific address to join a specific Call for the purposes of telephony conferencing.

Parameters:

calleeAddress - the address of the callee to be invited to the specified existing Call

call - the existing Call to invite the callee with the specified address to

Returns:

a new CallPeer instance which describes the signaling and the media streaming of the newly-invited callee within the specified Call

Throws:

OperationFailedException - if inviting the specified callee to the specified Call fails

getBasicTelephony

public OperationSetBasicTelephonyT getBasicTelephony()

Gets the OperationSetBasicTelephony implementation which this instance uses to carry out tasks such as establishing Calls.

Returns:

the OperationSetBasicTelephony implementation which this instance uses to carry out tasks such as establishing Calls

getRemoteSourceID

protected long getRemoteSourceID(MediaAwareCallPeer<?,?,?> callPeer,
                                 org.jitsi.service.neomedia.MediaType mediaType)

Gets the remote SSRC to be reported in the conference-info XML for a specific CallPeer's media of a specific MediaType.

Parameters:

callPeer - the CallPeer whose remote SSRC for the media of the specified mediaType is to be returned

mediaType - the MediaType of the specified callPeer's media whose remote SSRC is to be returned

Returns:

the remote SSRC to be reported in the conference-info XML for the specified callPeer's media of the specified mediaType

incomingCallReceived

public void incomingCallReceived(CallEvent event)

Notifies this CallListener that a specific incoming Call has been received.

Specified by:

incomingCallReceived in interface CallListener

Parameters:

event - a CallEvent which specifies the newly-received incoming Call

inviteCalleeToCall

public CallPeer inviteCalleeToCall(java.lang.String uri,
                                   Call call)
                            throws OperationFailedException

Invites the callee represented by the specified uri to an already existing call. The difference between this method and createConfCall is that inviteCalleeToCall allows a user to transform an existing 1 to 1 call into a conference call, or add new peers to an already established conference.

Specified by:

inviteCalleeToCall in interface OperationSetTelephonyConferencing

Parameters:

uri - the callee to invite to an existing conf call.

call - the call that we should invite the callee to.

Returns:

the CallPeer object corresponding to the callee represented by the specified uri.

Throws:

OperationFailedException - if inviting the specified callee to the specified call fails

notifyAll

protected void notifyAll(Call call)

Notifies all CallPeers associated with the telephony conference in which a specific Call is participating about changes in the telephony conference-related information.

Parameters:

call - the Call which specifies the telephony conference the associated CallPeers of which are to be notified about changes in the telephony conference-related information

notifyCallPeers

protected abstract void notifyCallPeers(Call call)

Notifies all CallPeers associated with a specific Call about changes in the telephony conference-related information. In contrast, Object.notifyAll() notifies all CallPeers associated with the telephony conference in which a specific Call is participating.

Parameters:

call - the Call whose CallPeers are to be notified about changes in the telephony conference-related information

outgoingCallCreated

public void outgoingCallCreated(CallEvent event)

Notifies this CallListener that a specific outgoing Call has been created.

Specified by:

outgoingCallCreated in interface CallListener

Parameters:

event - a CallEvent which specifies the newly-created outgoing Call

parseAddressString

protected abstract CalleeAddressT parseAddressString(java.lang.String calleeAddressString)
                                              throws OperationFailedException

Parses a String value which represents a callee address specified by the user into an object which is to actually represent the callee during the invitation to a conference Call.

Parameters:

calleeAddressString - a String value which represents a callee address to be parsed into an object which is to actually represent the callee during the invitation to a conference Call

Returns:

an object which is to actually represent the specified calleeAddressString during the invitation to a conference Call

Throws:

OperationFailedException - if parsing the specified calleeAddressString fails

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent ev)

Notifies this PropertyChangeListener that the value of a specific property of the notifier it is registered with has changed.

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

Parameters:

ev - a PropertyChangeEvent which describes the source of the event, the name of the property which has changed its value and the old and new values of the property

See Also:

PropertyChangeListener.propertyChange(PropertyChangeEvent)

registrationStateChanged

public void registrationStateChanged(RegistrationStateChangeEvent event)

Notifies this RegistrationStateChangeListener that the ProtocolProviderSerivce it is registered with has changed its registration state.

Specified by:

registrationStateChanged in interface RegistrationStateChangeListener

Parameters:

event - a RegistrationStateChangeEvent which specifies the old and the new value of the registration state of the ProtocolProviderService this RegistrationStateChangeListener listens to

setConferenceInfoXML

protected int setConferenceInfoXML(MediaAwareCallPeerT callPeer,
                                   java.lang.String conferenceInfoXML)
                            throws org.jitsi.util.xml.XMLException

Updates the conference-related properties of a specific CallPeer such as conferenceFocus and conferenceMembers with information received from it as a conference focus in the form of a conference-info XML document.

Parameters:

callPeer - the CallPeer which is a conference focus and has sent the specified conference-info XML document

conferenceInfoXML - the conference-info XML document sent by callPeer in order to update the conference-related information of the local peer represented by the associated Call

Returns:

the value of the version attribute of the conference-info XML element of the specified conferenceInfoXML if it was successfully parsed and represented in the specified callPeer

Throws:

org.jitsi.util.xml.XMLException - If conferenceInfoXML couldn't be parsed as a ConferenceInfoDocument

stripParametersFromAddress

public static java.lang.String stripParametersFromAddress(java.lang.String address)

Removes the parameters (specified after a semicolon) from a specific address String if any are present in it.

Parameters:

address - the String value representing an address from which any parameters are to be removed

Returns:

a String representing the specified address without any parameters

getCurrentConferenceInfo

protected ConferenceInfoDocument getCurrentConferenceInfo(MediaAwareCallPeer<?,?,?> callPeer)

Creates a ConferenceInfoDocument which describes the current state of the conference in which callPeer participates. The created document contains a "full" description (as opposed to a partial description, see RFC4575).

Returns:

a ConferenceInfoDocument which describes the current state of the conference in which this CallPeer participates.

getLocalEntity

protected abstract java.lang.String getLocalEntity(CallPeer callPeer)

Returns a string to be used for the entity attribute of the user element for the local peer, in a Conference Information document to be sent to callPeer

Parameters:

callPeer - The CallPeer for which we are creating a Conference Information document.

Returns:

a string to be used for the entity attribute of the user element for the local peer, in a Conference Information document to be sent to callPeer

getLocalDisplayName

protected abstract java.lang.String getLocalDisplayName()

Returns the display name for the local peer, which is to be used when we send Conference Information.

Returns:

the display name for the local peer, which is to be used when we send Conference Information.

getConferenceInfoDiff

protected ConferenceInfoDocument getConferenceInfoDiff(ConferenceInfoDocument from,
                                                       ConferenceInfoDocument to)
                                                throws java.lang.IllegalArgumentException

Parameters:

from - A document with state full from which to generate a "diff".

to - A document with state full to which to generate a "diff"

Returns:

a ConferenceInfoDocument, such that when it is applied to from using the procedure defined in section 4.6 of RFC4575, the result is to. May return null if from and to are not found to be different (that is, in case no document needs to be sent)

Throws:

java.lang.IllegalArgumentException

setupConference

public ConferenceDescription setupConference(ChatRoom chatRoom)

Sets up a conference with no participants, which members of chatRoom can join. Returns a ConferenceDescription that describes how the call can be joined. Unimplemented by default, returns null.

Specified by:

setupConference in interface OperationSetTelephonyConferencing

Parameters:

chatRoom - the ChatRoom for which to set up a conference.

Returns:

a ConferenceDescription corresponding to the created conference.