OpenScape
V3.2, Revision 044 20100322

com.siemens.symphonia.bcom.bcommon.external
Interface Communication

All Known Subinterfaces:
CommunicationInternal, VoiceCommunication, VoiceCommunicationInternal
All Known Implementing Classes:
AbstractCommunication, AbstractVoiceCommunication, VoiceCommunicationImpl, VoiceCommunicationImpl

public interface Communication

Generic representation of a communication.

A Communication represents one communication for one media type. The specific features of the actual media is represented by an extended object (e.g. VoiceCommunication for the media type voice).
Therefore a Communication cannot be instantiated but only the extended object for a specific media type. For voice communication the method createVoiceCommunication() can be used.

The communication may be a two-party communication or a conference with multiple parties.


Method Summary
 void clearPreferredDevice()
          Cancel overwrite of preferred device.
 ComConnection conference(Communication absorbedCommunication)
          Joins parties of a consultation communication together.
 ComConnection connect(ComEndpoint calledParty)
          Add new party to communication.
 ComConnection connect(java.lang.String targetUri)
          Add new party to communication.
 ComConnection consult(ComConnection consultingConnection, ComEndpoint consultedEndpoint)
          Make a consultation communication.
 ComConnection consult(ComConnection consultingConnection, java.lang.String targetUri)
          Make a consultation communication.
 int getActiveConnectionNumber()
          Number of active ComConnections.
 java.io.Serializable getAttachedData(java.lang.String key)
          Retrieves attached data.
 java.util.Iterator getComConnections()
          Provides all connections of this communication.
 ComSession getComSession()
          Get the ComSession this Communication belongs to.
 int getConnectionNumber()
          Number of all ComConnections.
 java.lang.String[] getKeysOfAttachedData()
          Get all keys used for attached data.
 ComConnection getMyConnection()
          Get the own connection.
 java.lang.String getObjectId()
          Get a string that can be used to identify this communication object.
 void removeAttachedData(java.lang.String key)
          Removes attached data.
 void setAttachedData(java.lang.String key, java.io.Serializable value)
          Stores attached data.
 void setPreferredDevice(ComEndpoint preferredDevice)
          Overwrite preferred device setting.
 void setPreferredDevice(java.lang.String targetUri)
          Overwrite preferred device setting.
 

Method Detail

getComSession

ComSession getComSession()
Get the ComSession this Communication belongs to.

A ComSession can be used to group Communications together. The ComSession this Communications belongs to is retrieved by this method.

Returns:
ComSession this Communication belongs to.

getComConnections

java.util.Iterator getComConnections()
Provides all connections of this communication.

For each participant of the communication there is a ComConnection object describing the state and allowing further operations. All ComConnections of the communication are retrieved independent from their state.

Returns:
Iterator to list of ComConnection objects.

getConnectionNumber

int getConnectionNumber()
Number of all ComConnections.

Determine the total number of all ComConnection objects currently associated with this communication independent of their state.

Returns:
the number of associated connections.

getActiveConnectionNumber

int getActiveConnectionNumber()
Number of active ComConnections.

Determine the total number of all ComConnection objects currently associated with this communication and their state is not TERMINATED.

Returns:
the number of associated connections that are not terminated.

getMyConnection

ComConnection getMyConnection()
Get the own connection.

Relating to a user's view there is in any communication one (and only one) ComConnection which represents the own connection.
An ordinary user is only allowed to carry methods out on this connection. The other connections are only for information purpose. Ie. a user can see who are the other participants of the communication and what they are doing but don't control them.

Returns:
the user's own connection.

connect

ComConnection connect(ComEndpoint calledParty)
Add new party to communication.

Create new ComConnection object(s) for this Communication. From the graph model this means just adding further ComConnection nodes. Applied it takes the following effects:

Any ComEndpoint object obtained from Basic Communication maybe used as target for the communication. This holds also for ComEndpoint objects received by events or walking through the graph.

Note:
This method invokes a synchronous service request which implicates:

Parameters:
calledParty - endpoint new connection should be established to.
Returns:
newly created ComConnection object.
Throws:
ComException - on immediate detected problems.

connect

ComConnection connect(java.lang.String targetUri)
Add new party to communication.

Has the same semantics as connect(ComEndpoint) but allows to specify the communication target as URI. The following URI formats are supported:

Parameters:
targetUri - URI new connection should be established to.
Returns:
newly created ComConnection object.
Throws:
ComException - on immediate detected problems.

consult

ComConnection consult(ComConnection consultingConnection,
                      ComEndpoint consultedEndpoint)
Make a consultation communication.

Places an existing communication on hold and creates a communication to another party. The following pre-conditions must hold:

After establishing the consultation communication it is possible to toggle between the two communications by means of the method alternate() or join all parties together using the method conference().

Remark:
The methods connect(ComEndpoint) or connect(String) can achieve the same consultation communication. But these methode fail if it is not possible to establish a consultation communication whereas connect() establishes are second (independent) communication or creates a conference.
Generally you create a new Communication by means of createVoiceCommunication() and invoke this method on the new Communication. As parameter consultingConnection your own already established connection from another communication has to be provided.

Note:
This method invokes a synchronous service request which implicates:

Parameters:
consultingConnection - the already existing connection of the user.
consultedEndpoint - endpoint new connection should be established to.
Returns:
the new created consultation connection.
Throws:
ComException - on immediate detected problems.

consult

ComConnection consult(ComConnection consultingConnection,
                      java.lang.String targetUri)
Make a consultation communication.

Has the same semantics as consult(ComConnection, ComEndpoint) but allows to specify the communication target as URI. The following URI formats are supported:

Parameters:
consultingConnection - the already existing connection of the user.
targetUri - URI new connection should be established to.
Returns:
the new created consultation connection.
Throws:
ComException - on immediate detected problems.

conference

ComConnection conference(Communication absorbedCommunication)
Joins parties of a consultation communication together.

All parties of a consultation communication are joined together in one combined conference.

This Communication object persists and hosts the emerging conference from the consultation communication. The other Communication object (as passed by the parameter absorbedCommunication) gets terminated after the ComConnection of the communication partner has been moved to this Communication.
It is also possible to join a consultation communication to an already existing conference. Repeating this multiple times results in a conference with more then three participants.

Note:
This method invokes a synchronous service request which implicates:

Parameters:
absorbedCommunication - the consultation communication which is added to this one
Returns:
the active ComConnection of this user.
Throws:
ComException - on immediate detected problems.

getAttachedData

java.io.Serializable getAttachedData(java.lang.String key)
Retrieves attached data.

Gets the attached data object stored previous by setAttachedData().

Note:
This method invokes a synchronous service request which implicates:

Parameters:
key - which was used to store the data object.
Returns:
the attached data object or null if there are no attached data with the given key.

setAttachedData

void setAttachedData(java.lang.String key,
                     java.io.Serializable value)
Stores attached data.

Allows to store an application specific data object with this Communication. The identification of the data object is done by a key selected by the application.

There is no check for uniqueness of the given key. If the key is already used the old data object is overwritten by the new one.

The size of the data object to be stored is checked against a limit and also the sum of all data objects stored with this Communication is checked. It is not allowed to store more data than this limits. Huge objects should be stored in the database and only the database reference should be attached.
The current limit for both checks is 10KByte.

Note:
This method invokes a synchronous service request which implicates:

Parameters:
key - which is to be used for storing the data object.
value - object to be stored as attached data.

removeAttachedData

void removeAttachedData(java.lang.String key)
Removes attached data.

Searches for the attached data specified by the given key and removes both the data object and the key.
It is silently ignored if the given key doesn't exist.

Note:
This method invokes a synchronous service request which implicates:

Parameters:
key - of the data object to be removed.

getKeysOfAttachedData

java.lang.String[] getKeysOfAttachedData()
Get all keys used for attached data.

Retrieves all keys for which data are attached on this Communication.

Note:
This method invokes a synchronous service request which implicates:

Returns:
Array with all keys of the attached data; length of the array maybe 0 if there are not attached data.

setPreferredDevice

void setPreferredDevice(ComEndpoint preferredDevice)
Overwrite preferred device setting.

Defines a preferred device which holds only for this Communication. I.e. the methods connect(ComEndpoint) and connect(String) as well as deflectONS() and transferONS() invoked on a VoiceConnection object which is part of this communication will use this preferred device instead of the database setting.

This setting is not persistent. When the Communication is terminated also the overwrite expires.

Note:
This method invokes a synchronous service request which implicates:

Parameters:
preferredDevice - target to overwrite database setting.

setPreferredDevice

void setPreferredDevice(java.lang.String targetUri)
Overwrite preferred device setting.

Has the same semantics as setPreferredDevice(ComEndpoint) but allows to specify the preferred device as URI. The following URI formats are supported:

Parameters:
targetUri - URI the preferred device should be set to.

clearPreferredDevice

void clearPreferredDevice()
Cancel overwrite of preferred device.

Cancels a possibly overwrite of the preferred device as set by setPreferredDevice(ComEndpoint) or setPreferredDevice(String). I.e. the database setting will be used again.

If no overwrite is set the method does nothing.

Note:
This method invokes a synchronous service request which implicates:


getObjectId

java.lang.String getObjectId()
Get a string that can be used to identify this communication object.

Returns:
a string that can be used to identify this communication object

OpenScape
V3.2, Revision 044 20100322

Copyright (c) 2007 Siemens Enterprise Communications, Germany
All rights reserved.

This software is the confidential and proprietary information of Siemens Enterprise Communications, Germany