FileDocCategorySizeDatePackage
RTPManager.javaAPI DocJMF 2.1.1e26201Mon May 12 12:20:40 BST 2003javax.media.rtp

RTPManager

public abstract class RTPManager extends Object implements Controls
The interface implemented by the RTPManager. This is the starting point for creating, maintaining and closing an RTP session.

1. Unicast Session
The following code fragment illustrates how to create a unicast session: 

import java.net.*;
import javax.media.rtp.*;

// create the RTP Manager
RTPManager rtpManager = RTPManager.newInstance();

// create the local endpoint for the local interface on
// any local port
SessionAddress localAddress = new SessionAddress();

// initialize the RTPManager
rtpManager.initialize( localAddress);

// add the ReceiveStreamListener if you need to receive data
// and do other application specific stuff
// ...

// specify the remote endpoint of this unicast session
// the address string and port numbers in the following lines
// need to be replaced with your values.
InetAddress ipAddress = InetAddress.getByName( "168.1.2.3");

SessionAddress remoteAddress = new SessionAddress( ipAddress, 3000);

// open the connection
rtpManager.addTarget( remoteAddress);

// create a send stream for the output data source of a processor
// and start it
DataSource dataOutput = createDataSource();

SendStream sendStream = rtpSession.createSendStream( dataOutput, 1);
sendStream.start();

// send data and do other application specific stuff,
// ...

// close the connection if no longer needed.
rtpManager.removeTarget( remoteAddress, "client disconnected.");

// call dispose at the end of the life-cycle of this RTPManager so
// it is prepared to be garbage-collected.
rtpManager.dispose();
2. Multi-Unicast Session
Creating multi-unicast sessions is similar to the example above. After creating and starting the SendStream new remote endpoints may be added by subsequent addTarget calls: 
addTarget( remoteAddress2);
addTarget( remoteAddress3);
3. Multicast Session
Creating and participating in multicast sessions also works similar to the unicast example. Instead of specifying local and remote endpoints a multicast session address needs to be created and passed into the initialize and addTarget calls. Everything else follows the unicast example. 
//...

// create a multicast address for 224.1.1.0 and ports 3000/3001
IPAddress ipAddress = InetAddress.getByName( "224.1.1.0");

SessionAddress multiAddress = new SessionAddress( ipAddress, 3000);

// initialize the RTPManager
rtpManager.initialize( multiAddress);

// add the target
rtpManager.addTarget( multiAddress);

// ...

Fields Summary
private static boolean
jdkInit
private static Method
forName3ArgsM
private static Method
getSystemClassLoaderM
private static ClassLoader
systemClassLoader
private static Method
getContextClassLoaderM
Constructors Summary
Methods Summary
public abstract voidaddFormat(javax.media.Format format, int payload)
This method is used to add a dynamic payload to format mapping to the RTPManager. The RTPManager maintains all static payload numbers and their correspnding formats as mentioned in the Audio/Video profile document. Using the plugin packethandler interface, a user may plugin his own packetizer or depacketizer to handle RTP streams of a proprietary format using dynamic payload numbers as specified in the AV profile. Before streaming dynamic payloads, a Format object needs to be created for each of the dynamic payload types and associated with a dynamic payload number.

param
format The Format to be associated with this dynamic payload number.
param
payload The RTP payload number
see
Format

public abstract voidaddReceiveStreamListener(javax.media.rtp.ReceiveStreamListener listener)
Adds a ReceiveStreamListener. This listener listens to all the
events that notify state transitions for a particular
ReceiveStream.
public abstract voidaddRemoteListener(javax.media.rtp.RemoteListener listener)
Adds a RemoteListener to the session. This listener listens
to all remote RTP events. Currently, these include
ReceiverReportEvent, ReceiveSenderReportEvent and
RemoteCollisionEvent. This interface would be usefuly for an RTCP
monitor that does not wish to receive any particular stream
transitionEvents but just wants to monitor the session quality
and statistics.
public abstract voidaddSendStreamListener(javax.media.rtp.SendStreamListener listener)
Adds a SendStreamListener. This listener listens to all the
events that notify state transitions for a particular
SendStream.
public abstract voidaddSessionListener(javax.media.rtp.SessionListener listener)
Adds a SessionListener. A SessionListener will receive
events that pertain to the Session as a whole. Currently,
these include the NewParticipantEvent and
LocalCollisionEvent. Events are notified in the
update(SessionEvent) method which must be implemented by all
SessionListeners.
classname
SessionListener
public abstract voidaddTarget(javax.media.rtp.SessionAddress remoteAddress)
This method opens the session, causing RTCP reports to be
generated and callbacks to be made through the
SessionListener interface. This method must be called after
session initialization and prior to the creation of any streams
on a session.
param
remoteAddress The RTP session address of a remote end
point for this session. i.e. the IP address/port of a remote
host
exception
InvalidSessionAddressException This exception is
thrown if the remote control and data addresses given in
parameter localAddress are not valid session addresses.

classname
SessionAddress
static java.util.VectorbuildClassList(java.util.Vector prefixList, java.lang.String name)
Build a list of complete class names.



For each element of the prefix-list
the following element is added to the list:

<prefix>.<name>


These are added to the list in the same order as the prefixes appear
in the prefix-list.

param
prefixList The list of prefixes to prepend to the class name.
param
name The name of the class to build the list for.
return
A vector of class name strings.
        
        // New list which has the name as the first element ...
        Vector classList = new Vector();

        // Try and instance one directly from the classpath
        // if it's there.
        // $jdr: This has been objected to as confusing,
        // the argument for it's inclusion is that it
        // gives the user (via the classpath) a way
        // of modifying the search list at run time
        // for all applications.
        classList.addElement(name);

        // ... for each prefix append the name and put it
        // in the class list ...
        Enumeration prefix = prefixList.elements();
        while( prefix.hasMoreElements()) {
            String prefixName = (String)prefix.nextElement();
            classList.addElement(prefixName + "." + name);
        }

        // ... done
        return classList;
    
private static booleancheckIfJDK12()
        if (jdkInit)
            return (forName3ArgsM != null);
        jdkInit = true;
        try {
            forName3ArgsM = Class.class.getMethod("forName",
                                                  new Class[] {
                String.class, boolean.class, ClassLoader.class
                    });
            
            getSystemClassLoaderM = ClassLoader.class.getMethod("getSystemClassLoader", null);

            // TODO: may need to invoke RuntimePermission("getClassLoader") privilege
            systemClassLoader = (ClassLoader) getSystemClassLoaderM.invoke(ClassLoader.class, null);

            getContextClassLoaderM = Thread.class.getMethod("getContextClassLoader", null);

            return true;
        } catch (Throwable t) {
            forName3ArgsM = null;
            return false;
        }
    
public abstract javax.media.rtp.SendStreamcreateSendStream(javax.media.protocol.DataSource dataSource, int streamIndex)
This method is used to create a sending stream within the RTP
session. For each time the call is made, a new sending stream
will be created. This stream will use the SDES items as entered
in the initialize() call for all its RTCP messages. Each stream
is sent out with a new SSRC (Synchronisation SouRCe
identifier), but from the same participant i.e. local
participant. 
param
dataSource This is the PushOutputDataSource or
PullOutputDataSource which is the output data source of the
Processor. This data source may contain more than one
stream. The stream which is used in creating this RTP
stream is specified in the next parameter of stream.
param
streamIndex The index of the sourcestream from which
data is sent out on this RTP stream. An index of 1 would indicate the first
sourcestream of this data source should be used to create the RTP
stream. If the index is set to zero, it would indicate a RTP
mixer operation is desired. i.e. all the streams of this
data source must be mixed into one single stream from one single
SSRC. 


Note: The RTP payload that is used to send this stream is found
from the format set on the SourceStream of the data source
supplied. 

If the sourcestream has no format set or has a
format for which a packetizer plugin cannot be found in the session
manager's database, an UnsupportedFormatException will be thrown
by the RTPManager. 


Note on PullDataSources supplied to the RTPManager:
In most cases, it is expected that the data source supplied to the
RTPManager for stream creation would be a
PushDataSource. In cases that the data source is a PullDataSource,
it MUST have a format set on its SourceStreams. This is the only
way for RTPManger to determine the RTP payload to use in
the header of the stream as well as the bitrate to pulldata from
this data source. 
return
The SendStream created by the RTPManager.
exception
UnsupportedFormatException
(javax.media.format.UnsupportedFormatException ). This
exception is thrown if the format is not set on the sourcestream
or a RTP payload cannot be located for the format set on the
sourcestream.
exception
IOException
Thrown for two possible reasons which will be specified in the
message part of the exception
1) If the session was initiated with zero rtcpBandwidthFraction which
implied that this participant could not send out any RTP/RTCP
data or control messages. i.e. it could not also create any send
streams and was just a passive listener for this session.
2) If there was any problem opening the sending sockets
classname
SendStream
public abstract voiddispose()
Releases all objects allocated in the course of the session and prepares
the RTPManager to be garbage-collected. This method should be called at
the end of any RTP session.
public abstract java.util.VectorgetActiveParticipants()
Returns a vector of all the active (data sending)
participants. These participants may be remote and/or the local participant.
public abstract java.util.VectorgetAllParticipants()
Returns all the participants of this session.
static java.lang.ClassgetClassForName(java.lang.String className)
        /**
         *  Note: if we don't want this functionality
         *  just replace it with Class.forName(className)
         */

        try {
            return Class.forName(className);
        } catch (Exception e) {
            if (!checkIfJDK12()) {
                throw new ClassNotFoundException(e.getMessage());
            }
        } catch (Error e) {
            if (!checkIfJDK12()) {
                throw e;
            }
        }

        /**
         *  In jdk1.2 application, when you have jmf.jar in the ext directory and
         *  you want to access a class that is not in jmf.jar but is in the CLASSPATH,
         *  you have to load it using the the system class loader.
         */
        try {
            return (Class) forName3ArgsM.invoke(Class.class, new Object[] {
                className, new Boolean(true), systemClassLoader});
        } catch (Throwable e) {
        }

        /**
         *  In jdk1.2 applet, when you have jmf.jar in the ext directory and
         *  you want to access a class that is not in jmf.jar but applet codebase,
         *  you have to load it using the the context class loader.
         */
        try {
            // TODO: may need to invoke RuntimePermission("getClassLoader") privilege
            ClassLoader contextClassLoader =
                (ClassLoader) getContextClassLoaderM.invoke(Thread.currentThread(), null);
            return (Class) forName3ArgsM.invoke(Class.class, new Object[] {
                className, new Boolean(true), contextClassLoader});
        } catch (Exception e) {
            throw new ClassNotFoundException(e.getMessage());
        } catch (Error e) {
            throw e;
        }
    
public abstract javax.media.rtp.GlobalReceptionStatsgetGlobalReceptionStats()
This method will provide access to overall data and control
messsage reception statistics for this session. Statistics on
data from individual sources is available from the
getSourceReceptionStats() method of the ReceiveStream interface.
return
The GlobalReceptionStats for this session
classname
ReceiveStream
public abstract javax.media.rtp.GlobalTransmissionStatsgetGlobalTransmissionStats()
This method will provide access to overall data and control
messsage transmission statistics for this session. Statistics on
data from individual sources is available from the
getSourceTransmissionStats() method of the SendStream interface.
return
The GlobalTransmissionStats for this session
classname
SendStream
public abstract javax.media.rtp.LocalParticipantgetLocalParticipant()
Retrieves the local participant.
public abstract java.util.VectorgetPassiveParticipants()
Returns all the passive participants. These participants will
include the local participant and some remote participants that
do not send any data.
static java.util.VectorgetProtocolPrefixList()
        return (Vector) javax.media.PackageManager.getProtocolPrefixList().clone();
    
public static java.util.VectorgetRTPManagerList()
Build a list of RTPManager implementation classes.
The implemenation class must be named 'RTPSessionMgr' and is
required to extend from javax.media.rtp.RTPManager.


The first name in the list will always be:

media.rtp.RTPSessionMgr





Each additional name looks like:

com.<company>.media.rtp.RTPSessionMgr


for every <company> in the
company-list.

        // The first element is the name of the protocol handler ...
        String sourceName =
            "media.rtp.RTPSessionMgr";

        return buildClassList(getProtocolPrefixList(), sourceName);
    
public abstract java.util.VectorgetReceiveStreams()
Returns the ReceiveStreams created by the
RTPManager. These are streams formed when the RTPManager
detects a new source of RTP data.
ReceiveStreams returned are a snapshot of the current state in the
RTPManager and the ReceiveStreamListener interface may be used
to get notified of additional streams.
public abstract java.util.VectorgetRemoteParticipants()
Returns a Vector of all the remote participants in the
session.This vector is simply a snapshot of the current state in
the RTPManager. The SessionListener interface can be
used to get notified of additional participants for the
Session. 
public abstract java.util.VectorgetSendStreams()
Returns the SendStreams created by the
RTPManager.
SendStreams returned are a snapshot of the current state in the
RTPSesion and the SendStreamListener interface may be used
to get notified of additional streams.
public abstract voidinitialize(javax.media.rtp.SessionAddress localAddress)
Initializes the session. Once this method has been called, the
session is "initialized" and this method cannot be called again. 
param
localAddress Encapsulates the *local* control and data
addresses to be used for the session. If either InetAddress
contained in this parameter is null, a default local address
will be chosen. The ports do not necessarily need to be specified
(i.e. they may be the ANY_PORT constant); the RTPManager will pick
appropriate ports in that case. 

If the session joins a multicast group, the localAddress will be ignored.
The multicast address will be taken from the addTarget() call.
public abstract voidinitialize(javax.media.rtp.SessionAddress[] localAddresses, javax.media.rtp.rtcp.SourceDescription[] sourceDescription, double rtcpBandwidthFraction, double rtcpSenderBandwidthFraction, javax.media.rtp.EncryptionInfo encryptionInfo)
Initializes the session. Once this method has been called, the
session is "initialized" and this method cannot be called again. 
param
localAddresses An array of local session adresses.
In most cases the address will contain a single session address,
but for multi-homed systems (systems with more than one IP interface)
there may be several local adresses specified in this parameter. 
param
sourceDescription An array of SourceDescription
objects containing information to send in RTCP SDES packets
for the local participant. This information can be changed by
calling setSourceDescription() on the local Participant
object.
param
rtcpBandwidthFraction The fraction of the session bandwidth
that the RTPManager must use when sending out RTCP reports.
param
rtcpSenderBandwidthFraction The fraction of the
rtcpBandwidthFraction that the RTPManager must use to send out RTCP Sender
reports from the local participant. The remaining fraction of the
rtcp_bw is used for sending out RTCP Receiver reports. 
param
encryptionInfo the encryption information to be used in
this session.

Note : The rtcpBandwidthFraction is set to zero for a
non-participating observer of this session. In this case
the application will receive both RTP and RTCP messages, but will
not send out any RTCP feedback reports.
This is equivalent to setting the outgoing RTP/RTCP
bandwidth of this application to zero, implying that this
application may NOT send out any data or control streams and can
thus not make a call to createSendStream(). If it does, it will
receive an exception. Further, this application is NOT considered
a Participant since it does not send out any RTCP
information. Consequently, this client will NOT appear in the
list of Participants for this session.


Init called a second time or thereafter will return
without doing anything, since the session had already been
initialized. If parameters to init() are different from
before, the user must note that the new parameters will ignored
as a result of no action being performed. 
exception
InvalidSessionAddressException This exception is
thrown if the local control and data addresses given in
parameter localAddress do not belong to one of the localhost
interfaces.
exception
IOException
classname
SessionAddress
classname
SourceDescription
public abstract voidinitialize(javax.media.rtp.RTPConnector connector)
Initializes the session. Once this method has been called, the
session is "initialized" and this method cannot be called again. 
param
connector An implementation of the RTPConnector interface that
allows the developer to connect the RTPManager to any type of transport.
By default, RTP is streamed over UDP. If an RTPConnector is present, the
RTPManager will use the connector's send and receive methods to send or
receive data.
Please note: the methods addTarget, removeTarget and removeTargets cannot
be used in conjunction with an RTPConnector since these tasks will be handled
directly by the connector object.
classname
RTPConnector
public static javax.media.rtp.RTPManagernewInstance()
Create an RTPManager object for the underlying
implementation class.
 

                                                                                                                         
      
     
               

                           
      
      

                                                           
      
      

                           
      
     

                                                
      
     

                                                                                               
      
        
                 

                                                                              
      
     

                                                                                                                                                                                                                                                                                                                                                                                                                                                                  
      
     
                       
     

                                      
       

                            
      
    

                
      
    

                                                  
      
    

                                                  
      
    

             
      
    

                               
      
    

                                                           
      
    

                                                
      
    

                                            
      
    

                                                                                                                
      
      
                  

                                                                                                                                                                                                                                                                                                                                                                                 
      
      
  	         
                 
                 
                 
          

                                                                                                            
    
      
      

                                                                                                 
      
       
          

               
      
      

               
      
      

               
      
     

               
      
     

                  
        
        RTPManager rtpManager= null;

        Enumeration SessionList =
            getRTPManagerList().elements();

        while( SessionList.hasMoreElements()) {
            String protoClassName = (String)SessionList.nextElement();

            try {	    
                Class protoClass = getClassForName(protoClassName);
                
                rtpManager = (RTPManager)protoClass.newInstance();
            } catch (ClassNotFoundException e) {
                // System.out.println( "class def not found.");
            } catch (InstantiationException e) {
                String err = "Error instantiating class: " + protoClassName + " : " + e;
                Log.error(e);				
            } catch (IllegalAccessException e) {
                System.out.println( "illegal access.");
            } catch (Exception e) {		
                String err = "Error instantiating class: " + protoClassName + " : " + e;
                Log.error(e);		
            } catch (Error e) {
                String err = "Error instantiating class: " + protoClassName + " : " + e;
                Log.error(e);		
            }

            if( rtpManager != null) {
                break;
            }
        }

        return rtpManager;
    
public abstract voidremoveReceiveStreamListener(javax.media.rtp.ReceiveStreamListener listener)
Removes a ReceiveStreamListener.
classname
ReceiveStreamListener
public abstract voidremoveRemoteListener(javax.media.rtp.RemoteListener listener)
Removes a RemoteListener.
classname
RTPRemoteListener
public abstract voidremoveSendStreamListener(javax.media.rtp.SendStreamListener listener)
Removes a SendStreamListener.
classname
SendStreamListener
public abstract voidremoveSessionListener(javax.media.rtp.SessionListener listener)
Removes a SessionListener.
classname
SessionListener
public abstract voidremoveTarget(javax.media.rtp.SessionAddress remoteAddress, java.lang.String reason)
Closes all open streams associated with the endpoint defined
by remoteAddress.

param
remoteAddress The RTP session address of a remote end
point for this session. i.e. the IP address/port of a remote
host
param
reason A string that RTCP will send out to other
participants as the reason the local participant has quit the
session.This RTCP packet will go out with the default SSRC of the
session. If supplied as null, a default reason will be supplied
by the RTPManager.

public abstract voidremoveTargets(java.lang.String reason)
Closes the open streams associated with all remote endpoints
that have been added previously by subsequent addTarget() calls. 
param
reason A string that RTCP will send out to other
participants as the reason the local participant has quit the
session.This RTCP packet will go out with the default SSRC of the
session. If supplied as null, a default reason will be supplied
by the RTPManager.