OpenScape
V3.2, Revision 044 20100322

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

All Known Subinterfaces:
ComConnectionInternal, QueueConnection, QueueConnectionInternal, VoiceBasedConnectionInternal, VoiceConnection, VoiceConnectionInternal
All Known Implementing Classes:
AbstractComConnection, AbstractQueueConnection, AbstractVoiceBasedConnection, AbstractVoiceConnection, QueueConnectionImpl, QueueConnectionImpl, VoiceConnectionImpl, VoiceConnectionImpl

public interface ComConnection

Generic representation of a connection whithin a communication.

A ComConnection represents one connection of a certain participant within one communication (represented by a Communication object). A communication has typically multiple connections representing all parties which are involved in this communication.
Communications with more than two active connections are named conferences.

Information on the participant itself can be retrieved by the method getComEndpoint(). See description of ComEndpoint for details thereof.

There is an extended class for each media type supported (e.g. VoiceConnection for the media type voice). Only these extended classes are instantiated to objects but never this class.
The media type of a connection is always the same as the media type of the communication where this connection belongs to.

Security Note:
By providing a user token for invokation of methods in this class or classes derived a security check is in place to prevent operations on other connections than the own one (i.e. isMyConnection() is true). An exception is thrown if this security requirement is violated.
Using a long lived service security statement doesn't implicate this restriction.
Methods which provide only information of this connection but do not cause any action on the communication system maybe invoked without restriction in any case.


Method Summary
 ComConnection deflect(ComEndpoint deflectToAddr)
          Forwards connection to a new destination.
 ComConnection deflect(java.lang.String targetUri)
          Forwards connection to a new destination.
 void drop()
          Terminate connection.
 ComEndpoint getComEndpoint()
          Get participant of communication represented by this connection.
 Communication getCommunication()
          Get the Communication this connection is part of.
 InitiationCause getInitiationCause()
          Determine the cause of the creation of this connection.
 java.lang.String getObjectId()
          Get a string that can be used to identify this connection object.
 ConnectionState getState()
          Get state of connection.
 TerminationCause getTerminationCause()
          Determine the cause of the termination of this connection.
 boolean isMyConnection()
          Determine whether this is the own connection.
 

Method Detail

deflect

ComConnection deflect(ComEndpoint deflectToAddr)
Forwards connection to a new destination.

A connection which is in state ALERTING is forwarded to a new destination. The connection will be terminated and control over the communication is lost for the invoking user or device view. The caller will afterwards alert the new destination.
See also transfer(ComEndpoint) to forward a connection in state CONNECTED.

Any ComEndpoint object obtained from Basic Communication maybe used as destination. 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:
deflectToAddr - endpoint of new destination.
Returns:
newly created ComConnection object.
Throws:
ComException - on immediate detected problems.

deflect

ComConnection deflect(java.lang.String targetUri)
Forwards connection to a new destination.

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

Parameters:
targetUri - URI of new destination.
Returns:
newly created ComConnection object.
Throws:
ComException - on immediate detected problems.

drop

void drop()
Terminate connection.

Terminating a connection results in a termination of the whole communication in the following cases:

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

Throws:
ComException - on immediate detected problems.

getComEndpoint

ComEndpoint getComEndpoint()
Get participant of communication represented by this connection.

The participant represented by this connection can be retrieved. See ComEndpoint for a description of the various address formats a participant can be described by.

Returns:
the ComEndpoint for this connection.

getState

ConnectionState getState()
Get state of connection.

Each connection is always in a certain state describing the progress of this connection in a communication. See ConnectionState for a description of the states and their meaning.

Returns:
the ConnectionState for this connection.

getCommunication

Communication getCommunication()
Get the Communication this connection is part of.

Retrieves the Communication object which represent the communication this connection is participating. This allows e.g. to find the other participants of this communication or get further information on the communication.

Returns:
the Communication the connection is participating.

isMyConnection

boolean isMyConnection()
Determine whether this is the own connection.

In each communication there is one connection representing the own participation in this communication. This method allows to determine whether this ComConnection object is the own one or not.
This attribute is specific for user or device view. I.e. a connection representing one certain user (or device) has this attribute set in the view of this user (or device) but not in the views of the other participants of the communication.

Returns:
true if this is the user's connection, otherwise false.

getInitiationCause

InitiationCause getInitiationCause()
Determine the cause of the creation of this connection.

Each connection is created by invoking a certain request. This might be a normal call from one user to another user, a consultation or a lot of other requests. The InitiationCause object allows to determine this and further information.

This information object is valid during the whole lifecycle of the ComConnection object.

Returns:
information about the creation of this connection.

getTerminationCause

TerminationCause getTerminationCause()
Determine the cause of the termination of this connection.

This information object is valid only during termination of the ComConnection object (i.e. while receiving the onTerminated(ComConnection, ComEndpoint) event). It provides information on the cause of the termination.

Returns:
information about the termination of this connection.

getObjectId

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

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

OpenScape
V3.2, Revision 044 20100322

Copyright (c) 2014 Unify, Germany
All rights reserved.

This software is the confidential and proprietary information of Unify, Germany