org.glassfish.cafe.api
Interface Communication

All Known Subinterfaces:

Conference, Conversation, IMConference, IMConversation, MSRPConference, MSRPConversation

public interface Communication

Represents a communication. Conversation, Conference etc are a type of Communication.

Author:

binod

See Also:

CommunicationSession

Nested Class Summary

static class

Communication.State Different Communication States.

Method Summary

<T> void	addAgent(String name, Agent<T> agent) Set an agent instance in the communication.
<P extends Participant> void	addParticipant(Class<P> type, String name) Add a participant to the Communication.
<P extends Participant> void	addParticipant(Class<P> type, String name, javax.media.mscontrol.join.Joinable j) Add a participant that can be added to the communication with a specific Joinable.
void	addParticipant(Participant p) Add a participant to the communication.
void	addParticipant(String name) Add a UserParticipant to the communication.
void	end() End the conversation.
<T> Agent<T>	getAgent(String name) Gets the agent from its name.
Collection<Agent>	getAgents() Retrieve the agent instance pertaining to the communication.
Participant	getInitiator() Retrieves the participant who initiated the communication.
String	getName() Return the name of the communication.
<P extends Participant> P	getParticipant(Class<P> type, String name) Retrieve a Participant from the Communication.
Participant	getParticipant(String name) Retrieve a Participant from the Communication.
Communication.State	getState() Return the current state of communication.
<T> Agent<T>	removeAgent(String name) Method to remove an agent from the communication.
void	removeParticipant(Participant p) Remove a participant from the communication.
void	removeParticipant(String name) Remove any type of participant from the communication.
void	replaceParticipant(Participant from, Participant to) Replace a participant with another Participant.

Method Detail

addParticipant

void addParticipant(String name)

Add a UserParticipant to the communication. Executing this method will initiate a call with that participant. Following is an example code. An IllegalArgumentException will be thrown if a participant of the same name already exists. Communication c = ....; c.addParticipant("alice@example.com");

Parameters:

name - Name of the UserParticipant

addParticipant

void addParticipant(Participant p)

Add a participant to the communication.

Parameters:

p - Add a participant to the communicaton.

addParticipant

<P extends Participant> void addParticipant(Class<P> type,
                                            String name)

Add a participant to the Communication. For example, for adding a Recorder to the communication, the following code could be used. An IllegalArgumentException will be thrown if a participant of the same name already exists. Communication c = ....; c.addParticipant(Recorder.class, "recorder-1");

Type Parameters:

P - Any Participant type that extends a MediaParticipant.

Parameters:

type - Any Class that extends MediaParticipant class.

name - Name of the participant

addParticipant

<P extends Participant> void addParticipant(Class<P> type,
                                            String name,
                                            javax.media.mscontrol.join.Joinable j)

Add a participant that can be added to the communication with a specific Joinable. For example, for adding a Recorder to the communication, the following code could be used. An IllegalArgumentException will be thrown if a participant of the same name already exists. Communication c = ....; MediaGroup mg = ....; //Get/create mediagroup. c.createMediaParticipant(Recorder.class, "recorder-1", mg); The Joinable passed in can be retrieved using getJoinable method. If it is null, then a new JSR 309 Joinable will be created by CAFE.

Type Parameters:

P - Any Participant type that extends a MediaParticipant.

Parameters:

type - Any Class that extends MediaParticipant class.

name - Name of the participant

j - An instance of Joinable object.

removeParticipant

void removeParticipant(String name)

Remove any type of participant from the communication.

Parameters:

name - Name of the Participant

removeParticipant

void removeParticipant(Participant p)

Remove a participant from the communication.

Parameters:

p - Participant object.

getParticipant

Participant getParticipant(String name)

Retrieve a Participant from the Communication.

Parameters:

name - Name of the Participant

Returns:

a Participant object

getParticipant

<P extends Participant> P getParticipant(Class<P> type,
                                         String name)

Retrieve a Participant from the Communication.

Type Parameters:

P - A sub-type of a Participant.

Parameters:

name - Name of the Participant

type - Type of the participant.

Returns:

a Participant object.

replaceParticipant

void replaceParticipant(Participant from,
                        Participant to)

Replace a participant with another Participant. This method provide an optimized alternative to executing removeParticipant(Participant) followed by addparticipant(Participant). For example, if both the Participants contain the same Joinable, CAFE might consider a very simple object replacement, rather than a more intensive Participant replacement that might involve sending re-INVItes to put the Participants on hold.a

Parameters:

from - Participant to be replaced.

to - New Participant that replaces the from

end

void end()

End the conversation.

getState

Communication.State getState()

Return the current state of communication.

Returns:

State of the communication.

getName

String getName()

Return the name of the communication. Name is typically assigned at the time of creation of communication by the application. If application does not provide a name, then the CAFE container would create a name.

Returns:

Name of the communication.

See Also:

Conversation, Conference

getInitiator

Participant getInitiator()

Retrieves the participant who initiated the communication. For example, in case of a conference initiated by a phone, the party who actually executed the createConference will be the initiator, where as if the conference is initiated by a web application, the mixer will be initiator. Similarly, when the Conversation is initiated by a phone, the caller will be the initiator. When a conversation is initiated from the web application, the initiator is specified in the CommunicationSession.createConversation method.

Returns:

Participant

addAgent

<T> void addAgent(String name,
                  Agent<T> agent)

Set an agent instance in the communication.

Type Parameters:

T - Type of Agent.

Parameters:

agent - An instance of Agent.

See Also:

Agent

getAgents

Collection<Agent> getAgents()

Retrieve the agent instance pertaining to the communication. This API returns only agents that are not call back agents.

Returns:

Return the agent instance previously set or return null if the agent is not set.

getAgent

<T> Agent<T> getAgent(String name)

Gets the agent from its name.

Parameters:

name - Name of the Agent

Returns:

agent

removeAgent

<T> Agent<T> removeAgent(String name)

Method to remove an agent from the communication.

Type Parameters:

T - type

Parameters:

name - name of the agent.

Returns:

agent if it exists.