javax.media.rtp
Interface RTPManager


public interface RTPManager
extends javax.media.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 = Manager.createRTPManager();
 
 // create the local endpoint for the local interface on
 // any local port
 IPAddress 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.openConnection( remoteAddress);
 
 // create a send stream for the output data source of a processor
 // and start it
 DataSource dataOutput = createDataSource();

 SendStream sendStream = rtpManager.createSendStream( dataOutput, 1);
 sendStream.start();
 
 // send data and do other application specific stuff,
 // ...
 
 // close the connection if no longer needed.
 rtpManager.closeConnection( 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 openConnection calls:
   openConnection( remoteAddress2);
   openConnection( 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 openConnection 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);
 
 // open the connection
 rtpManager.openConnection( multiAddress);
 
 // ...


Method Summary
 void addFormat(javax.media.Format format, int payload)
          This method is used to add a dynamic payload to format mapping to the RTPManager.
 void addReceiveStreamListener(javax.media.rtp.ReceiveStreamListener listener)
          Adds a ReceiveStreamListener.
 void addRemoteListener(javax.media.rtp.RemoteListener listener)
          Adds a RemoteListener to the session.
 void addSendStreamListener(javax.media.rtp.SendStreamListener listener)
          Adds a SendStreamListener.
 void addSessionListener(javax.media.rtp.SessionListener listener)
          Adds a SessionListener.
 void closeConnection(javax.media.rtp.SessionAddress remoteAddress, java.lang.String reason)
          Closes all open streams associated with the endpoint defined by remoteAddress.
 void closeConnections(java.lang.String reason)
          Closes the open streams associated with all remote endpoints that have been added previously by subsequent open() calls.
 javax.media.rtp.SendStream createSendStream(javax.media.protocol.DataSource dataSource, int streamIndex)
          This method is used to create a sending stream within the RTP session.
 void dispose()
          Releases all objects allocated in the course of the session and prepares the RTPManager to be garbage-collected.
 java.util.Vector getActiveParticipants()
          Returns a vector of all the active (data sending) participants.
 java.util.Vector getAllParticipants()
          Returns all the participants of this session.
 javax.media.rtp.GlobalReceptionStats getGlobalReceptionStats()
          This method will provide access to overall data and control messsage reception statistics for this session.
 javax.media.rtp.GlobalTransmissionStats getGlobalTransmissionStats()
          This method will provide access to overall data and control messsage transmission statistics for this session.
 javax.media.rtp.LocalParticipant getLocalParticipant()
          Retrieves the local participant.
 java.util.Vector getPassiveParticipants()
          Returns all the passive participants.
 java.util.Vector getReceiveStreams()
          Returns the ReceiveStreams created by the RTPManager.
 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.
 java.util.Vector getSendStreams()
          Returns the SendStreams created by the RTPManager.
 void initialize(javax.media.rtp.SessionAddress localAddress)
          Initializes the session.
 void initialize(javax.media.rtp.SessionAddress[] localAddresses, javax.media.rtp.rtcp.SourceDescription[] sourceDescription, double rtcpBandwidthFraction, double rtcpSenderBandwidthFraction, javax.media.rtp.EncryptionInfo encryptionInfo)
          Initializes the session.
 void openConnection(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.
 void removeReceiveStreamListener(javax.media.rtp.ReceiveStreamListener listener)
          Removes a ReceiveStreamListener.
 void removeRemoteListener(javax.media.rtp.RemoteListener listener)
          Removes a RemoteListener.
 void removeSendStreamListener(javax.media.rtp.SendStreamListener listener)
          Removes a SendStreamListener.
 void removeSessionListener(javax.media.rtp.SessionListener listener)
          Removes a SessionListener.
 
Methods inherited from interface javax.media.Controls
getControl, getControls
 

Method Detail

addFormat

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

addReceiveStreamListener

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

addRemoteListener

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

addSendStreamListener

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

addSessionListener

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

closeConnection

public void closeConnection(javax.media.rtp.SessionAddress remoteAddress,
                            java.lang.String reason)
                     throws javax.media.rtp.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.


closeConnections

public void closeConnections(java.lang.String reason)
Closes the open streams associated with all remote endpoints that have been added previously by subsequent open() 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 javax.media.rtp.SendStream createSendStream(javax.media.protocol.DataSource dataSource,
                                                   int streamIndex)
                                            throws javax.media.format.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:
javax.media.format.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 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 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 java.util.Vector getAllParticipants()
Returns all the participants of this session.

getGlobalReceptionStats

public javax.media.rtp.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 javax.media.rtp.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 javax.media.rtp.LocalParticipant getLocalParticipant()
Retrieves the local participant.

getPassiveParticipants

public 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 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 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 java.util.Vector getSendStreams()
Returns the SendStreams created by the RTPManager. SendStreams returned are a snapshot of the current state in the RTPSesionManager and the SendStreamListener interface may be used to get notified of additional streams.

initialize

public void initialize(javax.media.rtp.SessionAddress localAddress)
                throws javax.media.rtp.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 openConnection() call.


initialize

public void initialize(javax.media.rtp.SessionAddress[] localAddresses,
                       javax.media.rtp.rtcp.SourceDescription[] sourceDescription,
                       double rtcpBandwidthFraction,
                       double rtcpSenderBandwidthFraction,
                       javax.media.rtp.EncryptionInfo encryptionInfo)
                throws javax.media.rtp.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:
javax.media.rtp.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 -  

openConnection

public void openConnection(javax.media.rtp.SessionAddress remoteAddress)
                    throws javax.media.rtp.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:
javax.media.rtp.InvalidSessionAddressException - This exception is thrown if the remote control and data addresses given in parameter localAddress are not valid session addresses.


removeReceiveStreamListener

public void removeReceiveStreamListener(javax.media.rtp.ReceiveStreamListener listener)
Removes a ReceiveStreamListener.

removeRemoteListener

public void removeRemoteListener(javax.media.rtp.RemoteListener listener)
Removes a RemoteListener.

removeSendStreamListener

public void removeSendStreamListener(javax.media.rtp.SendStreamListener listener)
Removes a SendStreamListener.

removeSessionListener

public void removeSessionListener(javax.media.rtp.SessionListener listener)
Removes a SessionListener.


JMF 2.0 Proposed API Changes (12-Sep-00): click here to send API Feedback
Copyright 2000 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. Sun, Sun Microsystems and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.