JingleManager (Smack 4.3.3 API)

java.lang.Object
- org.jivesoftware.smackx.jingleold.JingleManager

All Implemented Interfaces:: JingleListener, JingleSessionListener

public class JingleManager
extends Object
implements JingleSessionListener

Jingle is a session establishment protocol defined in (XEP-0166). It defines a framework for negotiating and managing out-of-band ( data that is send and receive through other connection than XMPP connection) data sessions over XMPP. With this protocol you can setup VOIP Calls, Video Streaming, File transfers and whatever out-of-band session based transmission.

To create a Jingle Session you need a Transport method and a Payload type.

A transport method is how it will transmit and receive network packets. Transport MUST have one or more candidates. A transport candidate is an IP Address with a defined port, that other party must send data to.

A supported payload type, is the data encoding format that the jmf will be transmitted. For instance an Audio Payload "GSM".

A Jingle session negotiates a payload type and a pair of transport candidates. Which means that when a Jingle Session is established you will have two defined transport candidates with addresses and a defined Payload type. In other words, you will have two IP address with their respective ports, and a Codec type defined.

The JingleManager is a facade built upon Jabber Jingle (XEP-166) to allow the use of Jingle. This implementation allows the user to simply use this class for setting the Jingle parameters, create and receive Jingle Sessions.

In order to use the Jingle, the user must provide a TransportManager that will handle the resolution of potential IP addresses that can be used to transport the streaming (jmf). This TransportManager can be initialized with several default resolvers, including a fixed solver that can be used when the address and port are know in advance. This API have ready to use Transport Managers, for instance: BasicTransportManager, STUNTransportManager, BridgedTransportManager.

You should also specify a JingleMediaManager if you want that JingleManager assume Media control Using a JingleMediaManager implementation is the easier way to implement a Jingle Application.

Otherwise before creating an outgoing connection, the user must create jingle session listeners that will be called when different events happen. The most important event is sessionEstablished(), that will be called when all the negotiations are finished, providing the payload type for the transmission as well as the remote and local addresses and ports for the communication. See JingleSessionListener for a complete list of events that can be observed.

This is an example of how to use the JingleManager: This example implements a Jingle VOIP Call between two users.

                               To wait for an Incoming Jingle Session:
                               try {
                                           // Connect to an XMPP Server
                                           XMPPConnection x1 = new XMPPTCPConnection("xmpp.com");
                                           x1.connect();
                                           x1.login("juliet", "juliet");
                                           // Create a JingleManager using a BasicResolver
                                           final JingleManager jm1 = new JingleManager(
                                                   x1, new BasicTransportManager());
                                           // Create a JingleMediaManager. In this case using Jingle Audio Media API
                                           JingleMediaManager jingleMediaManager = new AudioMediaManager();
                                           // Set the JingleMediaManager
                                           jm1.setMediaManager(jingleMediaManager);
                                           // Listen for incoming calls
                                           jm1.addJingleSessionRequestListener(new JingleSessionRequestListener() {
                                               public void sessionRequested(JingleSessionRequest request) {
                                                   try {
                                                      // Accept the call
                                                      IncomingJingleSession session = request.accept();
                                                       // Start the call
                                                       session.start();
                                                   } catch (XMPPException e) {
                                                       LOGGER.log(Level.WARNING, "exception", e);
                                                   }
                                               }
                                           });
                                       Thread.sleep(15000);
                                       } catch (Exception e) {
                                           LOGGER.log(Level.WARNING, "exception", e);
                                       }
                               To create an Outgoing Jingle Session:
                                     try {
                                           // Connect to an XMPP Server
                                           XMPPConnection x0 = new XMPPTCPConnection("xmpp.com");
                                           x0.connect();
                                           x0.login("romeo", "romeo");
                                           // Create a JingleManager using a BasicResolver
                                           final JingleManager jm0 = new JingleManager(
                                                   x0, new BasicTransportManager());
                                           // Create a JingleMediaManager. In this case using Jingle Audio Media API
                                           JingleMediaManager jingleMediaManager = new AudioMediaManager(); // Using Jingle Media API
                                           // Set the JingleMediaManager
                                           jm0.setMediaManager(jingleMediaManager);
                                           // Create a new Jingle Call with a full JID
                                           OutgoingJingleSession js0 = jm0.createOutgoingJingleSession("juliet@xmpp.com/Smack");
                                           // Start the call
                                           js0.start();
                                           Thread.sleep(10000);
                                           js0.terminate();
                                           Thread.sleep(3000);
                                       } catch (Exception e) {
                                           LOGGER.log(Level.WARNING, "exception", e);
                                       }

See Also:: JingleListener, TransportResolver, JingleSession, JingleSession, JingleMediaManager, , STUNTransportManager, BridgedTransportManager, TransportResolver, BridgedResolver, ICEResolver, STUNResolver and BasicResolver.

Constructor Summary

Constructors
Constructor and Description
`JingleManager(XMPPConnection connection, List<JingleMediaManager> jingleMediaManagers)` Default constructor with a defined XMPPConnection, Transport Resolver and a Media Manager.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addCreationListener(CreatedJingleSessionListener createdJingleSessionListener)` Adds a CreatedJingleSessionListener.
`void`	`addJingleSessionRequestListener(JingleSessionRequestListener jingleSessionRequestListener)` Add a Jingle session request listenerJingle to listen to incoming session requests.
`JingleSession`	`createIncomingJingleSession(JingleSessionRequest request)` When the session request is acceptable, this method should be invoked.
`JingleSession`	`createOutgoingJingleSession(org.jxmpp.jid.EntityFullJid responder)` Creates an Jingle session to start a communication with another user.
`void`	`disconnectAllSessions()` Disconnect all Jingle Sessions.
`List<JingleMediaManager>`	`getMediaManagers()` Get the Media Managers of this Jingle Manager.
`JingleSession`	`getSession(String jid)` Get a session with the informed JID.
`static boolean`	`isServiceEnabled(XMPPConnection connection)` Returns true if the Jingle support is enabled for the given connection.
`static boolean`	`isServiceEnabled(XMPPConnection connection, org.jxmpp.jid.Jid userID)` Returns true if the specified user handles Jingle messages.
`void`	`removeCreationListener(CreatedJingleSessionListener createdJingleSessionListener)` Removes a CreatedJingleSessionListener.
`void`	`removeJingleSessionRequestListener(JingleSessionRequestListener jingleSessionRequestListener)` Removes a Jingle session listenerJingle.
`void`	`sessionClosed(String reason, JingleSession jingleSession)` Notification that the session was closed normally.
`void`	`sessionClosedOnError(XMPPException e, JingleSession jingleSession)` Notification that the session was closed due to an exception.
`void`	`sessionDeclined(String reason, JingleSession jingleSession)` Notification that the session was declined.
`void`	`sessionEstablished(PayloadType pt, TransportCandidate rc, TransportCandidate lc, JingleSession jingleSession)` Notification that the session has been established.
`void`	`sessionMediaReceived(JingleSession jingleSession, String participant)` Notification that the Media has arrived for this session.
`void`	`sessionRedirected(String redirection, JingleSession jingleSession)` Notification that the session was redirected.
`static void`	`setJingleServiceEnabled()` Setup the jingle system to let the remote clients know we support Jingle.
`void`	`setMediaManagers(List<JingleMediaManager> jingleMediaManagers)` Set the Media Managers of this Jingle Manager.
`static void`	`setServiceEnabled(XMPPConnection connection, boolean enabled)` Enables or disables the Jingle support on a given connection.
`void`	`triggerSessionCreated(JingleSession jingleSession)` Trigger CreatedJingleSessionListeners that a session was created.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - JingleManager
```
public JingleManager(XMPPConnection connection,
                     List<JingleMediaManager> jingleMediaManagers)
              throws XMPPException,
                     SmackException
```
    Default constructor with a defined XMPPConnection, Transport Resolver and a Media Manager. If a fully implemented JingleMediaSession is entered, JingleManager manage Jingle signalling and jmf
    
    Parameters:
    
    connection - XMPP XMPPConnection to be used
    
    jingleMediaManagers - an implemented JingleMediaManager to be used.
    
    Throws:
    
    SmackException
    
    XMPPException
- Method Detail
  - setJingleServiceEnabled
```
public static void setJingleServiceEnabled()
```
    Setup the jingle system to let the remote clients know we support Jingle. (This used to be a static part of construction. The problem is a remote client might attempt a Jingle connection to us after we've created an XMPPConnection, but before we've setup an instance of a JingleManager. We will appear to not support Jingle. With the new method you just call it once and all new connections will report Jingle support.)
  - setServiceEnabled
```
public static void setServiceEnabled(XMPPConnection connection,
                                     boolean enabled)
```
    Enables or disables the Jingle support on a given connection.
    Before starting any Jingle jmf session, check that the user can handle it. Enable the Jingle support to indicate that this client handles Jingle messages.
    
    Parameters:
    
    connection - the connection where the service will be enabled or disabled
    
    enabled - indicates if the service will be enabled or disabled
  - isServiceEnabled
```
public static boolean isServiceEnabled(XMPPConnection connection)
```
    Returns true if the Jingle support is enabled for the given connection.
    
    Parameters:
    
    connection - the connection to look for Jingle support
    
    Returns:
    
    a boolean indicating if the Jingle support is enabled for the given connection
  - isServiceEnabled
```
public static boolean isServiceEnabled(XMPPConnection connection,
                                       org.jxmpp.jid.Jid userID)
                                throws XMPPException,
                                       SmackException,
                                       InterruptedException
```
    Returns true if the specified user handles Jingle messages.
    
    Parameters:
    
    connection - the connection to use to perform the service discovery
    
    userID - the user to check. A fully qualified xmpp ID, e.g. jdoe@example.com
    
    Returns:
    
    a boolean indicating whether the specified user handles Jingle messages
    
    Throws:
    
    SmackException - if there was no response from the server.
    
    XMPPException
    
    InterruptedException
  - getMediaManagers
```
public List<JingleMediaManager> getMediaManagers()
```
    Get the Media Managers of this Jingle Manager.
    
    Returns:
    
    the list of JingleMediaManagers
  - setMediaManagers
```
public void setMediaManagers(List<JingleMediaManager> jingleMediaManagers)
```
    Set the Media Managers of this Jingle Manager.
    
    Parameters:
    
    jingleMediaManagers - JingleMediaManager to be used for open, close, start and stop jmf streamings
  - addJingleSessionRequestListener
```
public void addJingleSessionRequestListener(JingleSessionRequestListener jingleSessionRequestListener)
```
    Add a Jingle session request listenerJingle to listen to incoming session requests.
    
    Parameters:
    
    jingleSessionRequestListener - an implemented JingleSessionRequestListener
    
    See Also:
    
    removeJingleSessionRequestListener(JingleSessionRequestListener), JingleListener
  - removeJingleSessionRequestListener
```
public void removeJingleSessionRequestListener(JingleSessionRequestListener jingleSessionRequestListener)
```
    Removes a Jingle session listenerJingle.
    
    Parameters:
    
    jingleSessionRequestListener - The jingle session jingleSessionRequestListener to be removed
    
    See Also:
    
    addJingleSessionRequestListener(JingleSessionRequestListener), JingleListener
  - addCreationListener
```
public void addCreationListener(CreatedJingleSessionListener createdJingleSessionListener)
```
    Adds a CreatedJingleSessionListener. This listener will be called when a session is created by the JingleManager instance.
    
    Parameters:
    
    createdJingleSessionListener -
  - removeCreationListener
```
public void removeCreationListener(CreatedJingleSessionListener createdJingleSessionListener)
```
    Removes a CreatedJingleSessionListener. This listener will be called when a session is created by the JingleManager instance.
    
    Parameters:
    
    createdJingleSessionListener -
  - triggerSessionCreated
```
public void triggerSessionCreated(JingleSession jingleSession)
```
    Trigger CreatedJingleSessionListeners that a session was created.
    
    Parameters:
    
    jingleSession -
  - sessionEstablished
```
public void sessionEstablished(PayloadType pt,
                               TransportCandidate rc,
                               TransportCandidate lc,
                               JingleSession jingleSession)
```
    Description copied from interface: JingleSessionListener
    
    Notification that the session has been established. Arguments specify the payload type and transport to use.
    
    Specified by:
    
    sessionEstablished in interface JingleSessionListener
    
    Parameters:
    
    pt - the Payload tyep to use
    
    rc - the remote candidate to use for connecting to the remote service.
    
    lc - the local candidate where we must listen for connections
    
    jingleSession - Session that called the method
  - sessionDeclined
```
public void sessionDeclined(String reason,
                            JingleSession jingleSession)
```
    Description copied from interface: JingleSessionListener
    
    Notification that the session was declined.
    
    Specified by:
    
    sessionDeclined in interface JingleSessionListener
    
    Parameters:
    
    reason - the reason (if any).
    
    jingleSession - Session that called the method
  - sessionRedirected
```
public void sessionRedirected(String redirection,
                              JingleSession jingleSession)
```
    Description copied from interface: JingleSessionListener
    
    Notification that the session was redirected.
    
    Specified by:
    
    sessionRedirected in interface JingleSessionListener
    
    jingleSession - session that called the method
  - sessionClosed
```
public void sessionClosed(String reason,
                          JingleSession jingleSession)
```
    Description copied from interface: JingleSessionListener
    
    Notification that the session was closed normally.
    
    Specified by:
    
    sessionClosed in interface JingleSessionListener
    
    Parameters:
    
    reason - the reason (if any).
    
    jingleSession - Session that called the method
  - sessionClosedOnError
```
public void sessionClosedOnError(XMPPException e,
                                 JingleSession jingleSession)
```
    Description copied from interface: JingleSessionListener
    
    Notification that the session was closed due to an exception.
    
    Specified by:
    
    sessionClosedOnError in interface JingleSessionListener
    
    Parameters:
    
    e - the exception.
    
    jingleSession - session that called the method
  - sessionMediaReceived
```
public void sessionMediaReceived(JingleSession jingleSession,
                                 String participant)
```
    Description copied from interface: JingleSessionListener
    
    Notification that the Media has arrived for this session.
    
    Specified by:
    
    sessionMediaReceived in interface JingleSessionListener
    
    Parameters:
    
    jingleSession - session that called the method
    
    participant - description of the participant
  - disconnectAllSessions
```
public void disconnectAllSessions()
```
    Disconnect all Jingle Sessions.
  - createOutgoingJingleSession
```
public JingleSession createOutgoingJingleSession(org.jxmpp.jid.EntityFullJid responder)
                                          throws XMPPException
```
    Creates an Jingle session to start a communication with another user.
    
    Parameters:
    
    responder - the fully qualified jabber ID with resource of the other user.
    
    Returns:
    
    The session on which the negotiation can be run.
    
    Throws:
    
    XMPPException
  - createIncomingJingleSession
```
public JingleSession createIncomingJingleSession(JingleSessionRequest request)
                                          throws XMPPException
```
    When the session request is acceptable, this method should be invoked. It will create an JingleSession which allows the negotiation to procede.
    
    Parameters:
    
    request - the remote request that is being accepted.
    
    Returns:
    
    the session which manages the rest of the negotiation.
    
    Throws:
    
    XMPPException
  - getSession
```
public JingleSession getSession(String jid)
```
    Get a session with the informed JID. If no session is found, return null.
    
    Parameters:
    
    jid -
    
    Returns:
    
    the JingleSession

Class JingleManager

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

JingleManager

Method Detail

setJingleServiceEnabled

setServiceEnabled

isServiceEnabled

isServiceEnabled

getMediaManagers

setMediaManagers

addJingleSessionRequestListener

removeJingleSessionRequestListener

addCreationListener

removeCreationListener

triggerSessionCreated

sessionEstablished

sessionDeclined

sessionRedirected

sessionClosed

sessionClosedOnError

sessionMediaReceived

disconnectAllSessions

createOutgoingJingleSession

createIncomingJingleSession

getSession