hp.opencall.media.ccapi
Class ConferenceSession

java.lang.Object
  hp.opencall.media.platform.Capability
      hp.opencall.media.platform.ResourceCapability
          hp.opencall.media.service.Session
              hp.opencall.media.ccapi.ConferenceSession

All Implemented Interfaces:

ConferenceIF

public class ConferenceSession

extends hp.opencall.media.service.Session

implements ConferenceIF

ConferenceSession is the center class of the conference API.

ConferenceSession models a conference session within the Media Platform and acts as the enclosing object for all the resources that are involved in the conference( ConfCP, AsyncMediaGroup...)

If the user doesn't need to deal with this conference resources, he can use the default ConferenceSession's implementation. In any cases the Platform creates this session on the occurence of the registration of the first user.

The Platform starts up the conference session as follows
1. It initializes a new ConferenceSession .
2. It invokes its newConferenceSession method if the user has extended default ConferenceSession class

The newConferenceSession method is thus the entry point for the extended conferenceSession service.

Session Termination

A session is terminated by invoking the release() method. All the associated resources (such as AsyncMediaGroup) are released, and all associated confCP are unregistered from the conference.

Moreover It releases itself as soon as it hasn't anymore ConfCP registered or Conferencing.

Access
A handler on this session is given in CCSession with method register through a ConferenceIF interface. This handler is a proxy on ConferenceSession built with interface ConferenceIF. It enables to call ConferenceIF methods from CCSession User Thread (in addition to Conference User Thread)

Thread Management

The Platform schedules a thread, referred to as a Conference User Thread, to invoke the Call Control API callback methods. For example, newConferenceSession is invoked on a Conference User Thread.
In order to ensure appropriate synchronization in the platform, conference API methods (including AsyncMediaGroup methods) can only be called from the Conference User Thread that last called back to the ConferenceSession user code. It is required to implicitely or explicitely create new threads for the application's own purposes, referred to as Application Threads, care should be taken to not invoke those API methods from these threads.

The same proxy mechanism as the one implemented for CCSession enables to create a proxy on ConferenceSession with users interfaces (implemented by the oclet extending ConferenceSession) on which can be called methods from external threads. This proxy instance is given through an Object and a cast in the interface is needed to call a method on it.

This ConferenceSession is called back by the framework on each ConfCP state change. It is also called back on ConferenceSession state changes. Note that the RELEASED conferenceSessionStateChange is useful to manage conference id.

Field Summary

static hp.opencall.media.platform.AccessControlManager	acm
static int	ACTIVE The session is ACTIVE as soon as one ConfCP is Conferencing
static int	IDLE not yet initialized
static int	OPENED The session is OPENED as soon as one ConfCP is Registered
static int	RELEASED The session is RELEASED as soon a a release() method is called or if no more ConfCP is Registered
static String[]	sName Table indexed by state value to return state name

Fields inherited from class hp.opencall.media.service.Session

_defaultStreamsLogMask, myTerminal

Method Summary

void	confCPStateChange(ConfCP aCP, int aNewCPState) Indicates state changes of conferencing call parties (ConfCP) linked to the conference .
void	conferenceSessionStateUpdate(int aNewState) Indicates a ConferenceSession state change.
ConfCP[]	getConfCP() Gets a table of the ConfCP objects associated to this ConferenceSession.
ConferenceSpec	getConferenceSpec() Returns the ConferenceSpec of the ConferenceSession.
int	getConferencingConfCPNb() Gives the number of ConfCP joined to the conference.
Object	getProxy(Class aClass) Creates a proxy instance on which developers methods implemented by the ConferenceSession oclet can be called from external threads.
Object	getProxy(Class[] aInterTab) Creates a proxy instance on which developers methods implemented by the ConferenceSession oclet can be called from external threads.
int	getRegisteredConfCPNb() Gives the number of ConfCP registered to the conference.
int	getState() Returns the state of the ConferenceSession
Color	getStateColor()
void	joinAll() Notifies every CP registered to the conference that a joinAll() has been triggered by calling method onjoinAll(CP aCP, ConferenceIF aConfIF) of ConferenceListeners.
AsyncMediaGroup	loopConf(ConfigSpec aSpec) Creates an AsyncMediaGroup and connects it to the Conference.
static void	main(String[] arguments)
void	newConferenceSession() Called by the platform at extended conference session startup.
void	release() Terminates the conference session.
String	toString()
void	unjoinAll() Notifies every CP joined to the conference that a unjoinAll() has been triggered by calling method onunjoinAll(CP aCP, ConferenceIF aConfIF) of ConferenceListeners.
void	unloopConf(AsyncMediaGroup asycMG) This method disconnects and releases the given AsyncMediaGroup from the conference Pre-conditions: 1.

Methods inherited from class hp.opencall.media.service.Session

bindSessionToTerminal, checkObjectInterfaces, getName, getSessionAC, getTerminalAddress, printOut, sessionId, setDefaultStreamsLogMask

Methods inherited from class hp.opencall.media.platform.ResourceCapability

checkCapability, revoke

Methods inherited from class hp.opencall.media.platform.Capability

addRevocationListener, removeRevocationListener

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

acm

public static final hp.opencall.media.platform.AccessControlManager acm

IDLE

public static final int IDLE

not yet initialized

See Also:

Constant Field Values

OPENED

public static final int OPENED

The session is OPENED as soon as one ConfCP is Registered

See Also:

Constant Field Values

ACTIVE

public static final int ACTIVE

The session is ACTIVE as soon as one ConfCP is Conferencing

See Also:

Constant Field Values

RELEASED

public static final int RELEASED

The session is RELEASED as soon a a release() method is called or if no more ConfCP is Registered

See Also:

Constant Field Values

sName

public static final String[] sName

Table indexed by state value to return state name

Method Detail

main

public static void main(String[] arguments)

toString

public String toString()

getStateColor

public Color getStateColor()

getConfCP

public ConfCP[] getConfCP()
                   throws AccessControlException

Gets a table of the ConfCP objects associated to this ConferenceSession.

Throws:

BadThreadException - if the method is not called on the proper User Thread.

AccessControlException

Since:

OCMP 2.2

joinAll

public void joinAll()
             throws AccessControlException

Description copied from interface: ConferenceIF

Notifies every CP registered to the conference that a joinAll() has been triggered by calling method onjoinAll(CP aCP, ConferenceIF aConfIF) of ConferenceListeners.

Pre-conditions:
1. This method must be called from a Conference User Thread or on the proxy given back by method register of CCSession.
2. This notification will occure only if the CP is registered to conference with a ConferenceListener not null.(The associated ConfCP is Registered).

Post-conditions:
1. Method onjoinAll(CP aCP, ConferenceIF aConfIF) of registered CP is called in a CCSession User Thread

Specified by:

joinAll in interface ConferenceIF

Throws:

AccessControlException

unjoinAll

public void unjoinAll()
               throws AccessControlException

Description copied from interface: ConferenceIF

Notifies every CP joined to the conference that a unjoinAll() has been triggered by calling method onunjoinAll(CP aCP, ConferenceIF aConfIF) of ConferenceListeners.

Pre-conditions:
1. This method must be called from a Conference User Thread or on the proxy given back by method register of CCSession.
2. This notification will occure only if the CP is registered to conference with a ConferenceListener not null and if its has been joined to the conference (The associated ConfCP is Conferencing).

Post-conditions:
1. Method onunjoinAll(CP aCP, ConferenceIF aConfIF) of joined CP is called in a CCSession User Thread

Specified by:

unjoinAll in interface ConferenceIF

Throws:

AccessControlException

release

public void release()

Description copied from interface: ConferenceIF

Terminates the conference session.

Pre-conditions:
No condition on the thread from which this method is called

The session and all its associated resources are released Every AsyncMediaGroups are released, CP registered or joined to the conference are unjoined and unregistered from the conference.(ConfCP become Invalid) CP registered with a ConferenceListener are notified that a release has been triggered by call back method onrelease(CP aCP, ConferenceIF aConfIF) on a CCSession User Thread. CP state doesn't change

Post-conditions:
The session becomes RELEASED. Method conferenceSessionStateChange(Released) is called back at the end of the resources clear. Any further reference to this conference session object will throw ResourceReleasedException.

Specified by:

release in interface ConferenceIF

getState

public int getState()
             throws AccessControlException

Description copied from interface: ConferenceIF

Returns the state of the ConferenceSession

Specified by:

getState in interface ConferenceIF

Throws:

AccessControlException

getConferenceSpec

public ConferenceSpec getConferenceSpec()

Description copied from interface: ConferenceIF

Returns the ConferenceSpec of the ConferenceSession.

Specified by:

getConferenceSpec in interface ConferenceIF

getProxy

public Object getProxy(Class aClass)
                throws CCBadParamsException

Description copied from interface: ConferenceIF

Creates a proxy instance on which developers methods implemented by the ConferenceSession oclet can be called from external threads.

The proxy must be created with an interface implemented by the extended ConferenceSession. It gives back a Object. A cast in the interface class is needed to call one of its method.

VERY IMPORTANT NOTE
A typical use case would be

 ConferenceIF myConferenceIF = myCCsession.register( myCallParty, myConferenceSpec, .... );
 SpecificConferenceIF mySpecificConferenceIF = (SpecificConferenceIF) myConferenceIF.getProxy(...);
 mySpecificConferenceIF.someSpecificMethod(....);// as someSpecificMethod() runs asynchronously in another thread, unpredictable result may occur !
 myAsyncMediaGroup.join( myConferenceIF );
 

The preferred method to avoid race conditions is to call

 class MyConferenceSpec extend ConferenceSpec { .... }
 MyConferenceSpec myConferenceSpec = new MyConferenceSpec(.... parameters ....) {
     public .... getOneOfMyParameters() { .... }
 }
 someSpecificMethod(.... myConferenceSpec.getOneOfMyParameters() ....);
 

form the conference session thread, having a custom class inherit ConferenceSpec to transmit parameters.

Pre-conditions:
1. The oclet must implement the interfaces given in parameter
Post-conditions:

Specified by:

getProxy in interface ConferenceIF

Throws:

CCBadParamsException - if the interface is not implemented by the oclet

getProxy

public Object getProxy(Class[] aInterTab)
                throws CCBadParamsException

Description copied from interface: ConferenceIF

Creates a proxy instance on which developers methods implemented by the ConferenceSession oclet can be called from external threads.

The proxy must be created with a list of user interfaces implemented by the extended ConferenceSession. It gives back a Object. A cast in the interface class is needed to call an interface method.

See IMPORTANT NOTE in ConferenceIF.getProxy(Class).

Pre-conditions:
1. The oclet must implement the interfaces given in parameter
Post-conditions:

Specified by:

getProxy in interface ConferenceIF

Throws:

CCBadParamsException - if the interfaces are not implemented by the oclet

getRegisteredConfCPNb

public int getRegisteredConfCPNb()
                          throws AccessControlException

Description copied from interface: ConferenceIF

Gives the number of ConfCP registered to the conference.

Specified by:

getRegisteredConfCPNb in interface ConferenceIF

Throws:

AccessControlException

getConferencingConfCPNb

public int getConferencingConfCPNb()
                            throws AccessControlException

Description copied from interface: ConferenceIF

Gives the number of ConfCP joined to the conference. (ConfCP Conferencing)

Specified by:

getConferencingConfCPNb in interface ConferenceIF

Throws:

AccessControlException

loopConf

public AsyncMediaGroup loopConf(ConfigSpec aSpec)
                         throws AccessControlException,
                                BadConfigSpecException

Creates an AsyncMediaGroup and connects it to the Conference. This media group can thus be used either to play a message to every CONFERENCING CallParties, or record the conference in a file.

Pre-conditions:
1. Enough MediaProcessing resources must be available so that a MediaGroup can be allocated.

Throws:

BadThreadException - if the method is not called on the proper User Thread

ResourceNotAvailableException - if no more MediaGroup resources are available.

AccessControlException

BadConfigSpecException

Since:

OCMP 2.2

unloopConf

public void unloopConf(AsyncMediaGroup asycMG)
                throws AccessControlException

This method disconnects and releases the given AsyncMediaGroup from the conference

Pre-conditions:
1. The AsyncMediaGroup must have been created.

Throws:

BadThreadException - if the method is not called on the proper User Thread.

AccessControlException

Since:

OCMP 2.2

newConferenceSession

public void newConferenceSession()

Called by the platform at extended conference session startup.

This method is called by the platform the first time method register(...) is called for a conference. It is called in a conference User Thread

Since:

OCMP 2.2

confCPStateChange

public void confCPStateChange(ConfCP aCP,
                              int aNewCPState)

Indicates state changes of conferencing call parties (ConfCP) linked to the conference . This method is a notification method and mustn't be considered as a management method on ConfCP.

Called by the framework to inform on a ConfCP state change.

Parameters:

aCP - the conference call party subject to the change.

aNewCPState - the new Call Party state. It can be REGISTERED, CONFERENCING, INVALID

Since:

OCMP 2.2

conferenceSessionStateUpdate

public void conferenceSessionStateUpdate(int aNewState)

Indicates a ConferenceSession state change.

Called by the framework to inform of a ConferenceSession state change. The RELEASED state reception is useful to manage conference ids. This call back enables conference management. It ensures every conferencing resources are released (every ConfCP invalid ...)

Parameters:

aNewState - The new session state. It can be Idle, Opened, Active or Released.

Since:

OCMP 2.2