javax.media.rtp
Class RTPManager

java.lang.Object
  |
  +--javax.media.rtp.RTPManager

public abstract class RTPManager
extends java.lang.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);
 
 // ...


Constructor Summary
RTPManager()
           
 
Method Summary
abstract  void addFormat(Format format, int payload)
          This method is used to add a dynamic payload to format mapping to the RTPManager.
abstract  void addReceiveStreamListener(ReceiveStreamListener listener)
          Adds a ReceiveStreamListener.
abstract  void addRemoteListener(RemoteListener listener)
          Adds a RemoteListener to the session.
abstract  void addSendStreamListener(SendStreamListener listener)
          Adds a SendStreamListener.
abstract  void addSessionListener(SessionListener listener)
          Adds a SessionListener.
abstract  void addTarget(SessionAddress remoteAddress)
          This method opens the session, causing RTCP reports to be generated and callbacks to be made through the SessionListener interface.
abstract  SendStream createSendStream(DataSource dataSource, int streamIndex)
          This method is used to create a sending stream within the RTP session.
abstract  void dispose()
          Releases all objects allocated in the course of the session and prepares the RTPManager to be garbage-collected.
abstract  java.util.Vector getActiveParticipants()
          Returns a vector of all the active (data sending) participants.
abstract  java.util.Vector getAllParticipants()
          Returns all the participants of this session.
abstract  GlobalReceptionStats getGlobalReceptionStats()
          This method will provide access to overall data and control messsage reception statistics for this session.
abstract  GlobalTransmissionStats getGlobalTransmissionStats()
          This method will provide access to overall data and control messsage transmission statistics for this session.
abstract  LocalParticipant getLocalParticipant()
          Retrieves the local participant.
abstract  java.util.Vector getPassiveParticipants()
          Returns all the passive participants.
abstract  java.util.Vector getReceiveStreams()
          Returns the ReceiveStreams created by the RTPManager.
abstract  java.util.Vector getRemoteParticipants()
          Returns a Vector of all the remote participants in the session.This vector is simply a snapshot of the current state in the RTPManager.
static java.util.Vector getRTPManagerList()
          Build a list of RTPManager implementation classes.
abstract  java.util.Vector getSendStreams()
          Returns the SendStreams created by the RTPManager.
abstract  void initialize(RTPConnector connector)
          Initializes the session.
abstract  void initialize(SessionAddress localAddress)
          Initializes the session.
abstract  void initialize(SessionAddress[] localAddresses, SourceDescription[] sourceDescription, double rtcpBandwidthFraction, double rtcpSenderBandwidthFraction, EncryptionInfo encryptionInfo)
          Initializes the session.
static RTPManager newInstance()
          Create an RTPManager object for the underlying implementation class.
abstract  void removeReceiveStreamListener(ReceiveStreamListener listener)
          Removes a ReceiveStreamListener.
abstract  void removeRemoteListener(RemoteListener listener)
          Removes a RemoteListener.
abstract  void removeSendStreamListener(SendStreamListener listener)
          Removes a SendStreamListener.
abstract  void removeSessionListener(SessionListener listener)
          Removes a SessionListener.
abstract  void removeTarget(SessionAddress remoteAddress, java.lang.String reason)
          Closes all open streams associated with the endpoint defined by remoteAddress.
abstract  void removeTargets(java.lang.String reason)
          Closes the open streams associated with all remote endpoints that have been added previously by subsequent addTarget() calls.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RTPManager

public RTPManager()
Method Detail

addFormat

public abstract void addFormat(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.
Parameters:
format - The Format to be associated with this dynamic payload number.
payload - The RTP payload number
See Also:
Format

addReceiveStreamListener

public abstract void addReceiveStreamListener(ReceiveStreamListener listener)
Adds a ReceiveStreamListener. This listener listens to all the events that notify state transitions for a particular ReceiveStream.

addRemoteListener

public abstract void addRemoteListener(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.

addSendStreamListener

public abstract void addSendStreamListener(SendStreamListener listener)
Adds a SendStreamListener. This listener listens to all the events that notify state transitions for a particular SendStream.

addSessionListener

public abstract void addSessionListener(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.

removeTarget

public abstract void removeTarget(SessionAddress remoteAddress,
                                  java.lang.String reason)
                           throws InvalidSessionAddressException
Closes all open streams associated with the endpoint defined by remoteAddress.

Parameters:
remoteAddress - The RTP session address of a remote end point for this session. i.e. the IP address/port of a remote host
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.


removeTargets

public abstract void removeTargets(java.lang.String reason)
Closes the open streams associated with all remote endpoints that have been added previously by subsequent addTarget() calls.

Parameters:
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.


createSendStream

public abstract SendStream createSendStream(DataSource dataSource,
                                            int streamIndex)
                                     throws UnsupportedFormatException,
                                            java.io.IOException
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.
Parameters:
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.
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.
Returns:
The SendStream created by the RTPManager.
Throws:
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.
java.io.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

dispose

public abstract void dispose()
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.

getActiveParticipants

public abstract java.util.Vector getActiveParticipants()
Returns a vector of all the active (data sending) participants. These participants may be remote and/or the local participant.

getAllParticipants

public abstract java.util.Vector getAllParticipants()
Returns all the participants of this session.

getGlobalReceptionStats

public abstract GlobalReceptionStats getGlobalReceptionStats()
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.
Returns:
The GlobalReceptionStats for this session

getGlobalTransmissionStats

public abstract GlobalTransmissionStats getGlobalTransmissionStats()
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.
Returns:
The GlobalTransmissionStats for this session

getLocalParticipant

public abstract LocalParticipant getLocalParticipant()
Retrieves the local participant.

getPassiveParticipants

public abstract java.util.Vector getPassiveParticipants()
Returns all the passive participants. These participants will include the local participant and some remote participants that do not send any data.

getReceiveStreams

public abstract java.util.Vector getReceiveStreams()
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.

getRemoteParticipants

public abstract java.util.Vector getRemoteParticipants()
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.


getSendStreams

public abstract java.util.Vector getSendStreams()
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.

initialize

public abstract void initialize(SessionAddress localAddress)
                         throws InvalidSessionAddressException,
                                java.io.IOException
Initializes the session. Once this method has been called, the session is "initialized" and this method cannot be called again.

Parameters:
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.


initialize

public abstract void initialize(SessionAddress[] localAddresses,
                                SourceDescription[] sourceDescription,
                                double rtcpBandwidthFraction,
                                double rtcpSenderBandwidthFraction,
                                EncryptionInfo encryptionInfo)
                         throws InvalidSessionAddressException,
                                java.io.IOException
Initializes the session. Once this method has been called, the session is "initialized" and this method cannot be called again.

Parameters:
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.

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.
rtcpBandwidthFraction - The fraction of the session bandwidth that the RTPManager must use when sending out RTCP reports.
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.

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.

Throws:
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.
java.io.IOException -  

initialize

public abstract void initialize(RTPConnector connector)
Initializes the session. Once this method has been called, the session is "initialized" and this method cannot be called again.

Parameters:
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.

addTarget

public abstract void addTarget(SessionAddress remoteAddress)
                        throws InvalidSessionAddressException,
                               java.io.IOException
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.
Parameters:
remoteAddress - The RTP session address of a remote end point for this session. i.e. the IP address/port of a remote host
Throws:
InvalidSessionAddressException - This exception is thrown if the remote control and data addresses given in parameter localAddress are not valid session addresses.


removeReceiveStreamListener

public abstract void removeReceiveStreamListener(ReceiveStreamListener listener)
Removes a ReceiveStreamListener.

removeRemoteListener

public abstract void removeRemoteListener(RemoteListener listener)
Removes a RemoteListener.

removeSendStreamListener

public abstract void removeSendStreamListener(SendStreamListener listener)
Removes a SendStreamListener.

removeSessionListener

public abstract void removeSessionListener(SessionListener listener)
Removes a SessionListener.

newInstance

public static RTPManager newInstance()
Create an RTPManager object for the underlying implementation class.

getRTPManagerList

public static java.util.Vector getRTPManagerList()
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.


Submit a bug or feature
Copyright 1999-2001 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. See the Specification License for more details.
Sun, Sun Microsystems, and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.