diff --git a/src/net/java/sip/communicator/impl/neomedia/AudioMediaStreamImpl.java b/src/net/java/sip/communicator/impl/neomedia/AudioMediaStreamImpl.java index 5f2f526c4..b3af4eda9 100644 --- a/src/net/java/sip/communicator/impl/neomedia/AudioMediaStreamImpl.java +++ b/src/net/java/sip/communicator/impl/neomedia/AudioMediaStreamImpl.java @@ -17,12 +17,20 @@ import net.java.sip.communicator.util.*; /** + * Extends MediaStreamImpl in order to provide an implementation of + * AudioMediaStream. + * * @author Lubomir Marinov */ public class AudioMediaStreamImpl extends MediaStreamImpl implements AudioMediaStream { + + /** + * The Logger used by the AudioMediaStreamImpl class and + * its instances for logging output. + */ private static final Logger logger = Logger.getLogger(AudioMediaStreamImpl.class); @@ -68,6 +76,17 @@ public class AudioMediaStreamImpl */ private static boolean formatsRegisteredOnce = false; + /** + * Initializes a new AudioMediaStreamImpl instance which will use + * the specified MediaDevice for both capture and playback of audio + * exchanged via the specified StreamConnector. + * + * @param connector the StreamConnector the new instance is to use + * for sending and receiving audio + * @param device the MediaDevice the new instance is to use for + * both capture and playback of audio exchanged via the specified + * StreamConnector + */ public AudioMediaStreamImpl(StreamConnector connector, MediaDevice device) { super(connector, device); @@ -89,6 +108,11 @@ public void addSoundLevelListener(SoundLevelListener listener) // TODO Auto-generated method stub } + /* + * Overrides MediaStreamImpl#registerCustomCodecFormats(RTPManager) in order + * to register CUSTOM_CODEC_FORMATS. + */ + @Override protected void registerCustomCodecFormats(RTPManager rtpManager) { // if we have already registered custom formats and we are running JMF diff --git a/src/net/java/sip/communicator/impl/neomedia/MediaServiceImpl.java b/src/net/java/sip/communicator/impl/neomedia/MediaServiceImpl.java index e8ea63541..2e4816e8c 100644 --- a/src/net/java/sip/communicator/impl/neomedia/MediaServiceImpl.java +++ b/src/net/java/sip/communicator/impl/neomedia/MediaServiceImpl.java @@ -36,9 +36,17 @@ public class MediaServiceImpl private static final List EMPTY_DEVICES = Collections.emptyList(); + /** + * The CaptureDevice user choices such as the default audio and + * video capture devices. + */ private final DeviceConfiguration deviceConfiguration = new DeviceConfiguration(); + /** + * The format-related user choices such as the enabled and disabled codecs + * and the order of their preference. + */ private final EncodingConfiguration encodingConfiguration = new EncodingConfiguration(); @@ -88,6 +96,13 @@ public MediaDevice getDefaultDevice(MediaType mediaType) : new CaptureMediaDevice(captureDeviceInfo, mediaType); } + /** + * Gets the CaptureDevice user choices such as the default audio + * and video capture devices. + * + * @return the CaptureDevice user choices such as the default audio + * and video capture devices. + */ DeviceConfiguration getDeviceConfiguration() { return deviceConfiguration; @@ -130,11 +145,22 @@ public List getDevices(MediaType mediaType) return captureDevices; } + /** + * Gets the format-related user choices such as the enabled and disabled + * codecs and the order of their preference. + * + * @return the format-related user choices such as the enabled and disabled + * codecs and the order of their preference + */ EncodingConfiguration getEncodingConfiguration() { return encodingConfiguration; } + /** + * Starts this MediaService implementation and thus makes it + * operational. + */ void start() { deviceConfiguration.initialize(); @@ -142,6 +168,10 @@ void start() encodingConfiguration.registerCustomPackages(); } + /** + * Stops this MediaService implementation and thus signals that its + * utilization should cease. + */ void stop() { } diff --git a/src/net/java/sip/communicator/impl/neomedia/MediaStreamImpl.java b/src/net/java/sip/communicator/impl/neomedia/MediaStreamImpl.java index e3e0cf267..a3f4c751f 100644 --- a/src/net/java/sip/communicator/impl/neomedia/MediaStreamImpl.java +++ b/src/net/java/sip/communicator/impl/neomedia/MediaStreamImpl.java @@ -32,6 +32,11 @@ public class MediaStreamImpl SendStreamListener, SessionListener { + + /** + * The Logger used by the MediaStreamImpl class and its + * instances for logging output. + */ private static final Logger logger = Logger.getLogger(MediaStreamImpl.class); @@ -53,8 +58,18 @@ public class MediaStreamImpl */ private final RTPConnectorImpl rtpConnector; + /** + * The RTPManager which utilizes {@link #rtpConnector} and sends + * and receives RTP and RTCP traffic on behalf of this MediaStream. + */ private RTPManager rtpManager; + /** + * The MediaDirection in which this instance is started. For + * example, {@link MediaDirection#SENDRECV} if this instances is both + * sending and receiving data (e.g. RTP and RTCP) or + * {@link MediaDirection#SENDONLY} if this instance is only sending data. + */ private MediaDirection startedDirection; /** @@ -115,6 +130,10 @@ public void controllerUpdate(ControllerEvent event) } } + /** + * Creates new SendStream instances for the streams of + * {@link #device} through {@link #rtpManager}. + */ private void createSendStreams() { RTPManager rtpManager = getRTPManager(); @@ -237,6 +256,13 @@ public String getRemoteSourceID() return null; } + /** + * Gets the RTPManager instance which sends and receives RTP and + * RTCP traffic on behalf of this MediaStream. + * + * @return the RTPManager instance which sends and receives RTP and + * RTCP traffic on behalf of this MediaStream + */ private RTPManager getRTPManager() { if (rtpManager == null) @@ -292,6 +318,14 @@ private RTPManager getRTPManager() return rtpManager; } + /** + * Registers any custom JMF Formats with a specific + * RTPManager. Extenders should override in order to register their + * own customizations. + * + * @param rtpManager the RTPManager to register any custom JMF + * Formats with + */ protected void registerCustomCodecFormats(RTPManager rtpManager) { } @@ -347,6 +381,16 @@ public void start() start(MediaDirection.SENDRECV); } + /** + * Starts the processing of media in this instance in a specific direction. + * + * @param direction a MediaDirection value which represents the + * direction of the processing of media to be started. For example, + * {@link MediaDirection#SENDRECV} to start both capture and playback of + * media in this instance or {@link MediaDirection#SENDONLY} to only start + * the capture of media in this instance + */ + @SuppressWarnings("unchecked") public void start(MediaDirection direction) { if (direction == null) @@ -358,7 +402,6 @@ public void start(MediaDirection direction) && !MediaDirection.SENDONLY.equals(startedDirection))) { RTPManager rtpManager = getRTPManager(); - @SuppressWarnings("unchecked") Iterable sendStreams = rtpManager.getSendStreams(); if (sendStreams != null) @@ -446,6 +489,16 @@ public void stop() stop(MediaDirection.SENDRECV); } + /** + * Stops the processing of media in this instance in a specific direction. + * + * @param direction a MediaDirection value which represents the + * direction of the processing of media to be stopped. For example, + * {@link MediaDirection#SENDRECV} to stop both capture and playback of + * media in this instance or {@link MediaDirection#SENDONLY} to only stop + * the capture of media in this instance + */ + @SuppressWarnings("unchecked") public void stop(MediaDirection direction) { if (direction == null) @@ -459,7 +512,6 @@ public void stop(MediaDirection direction) && (MediaDirection.SENDRECV.equals(startedDirection) || MediaDirection.SENDONLY.equals(startedDirection))) { - @SuppressWarnings("unchecked") Iterable sendStreams = rtpManager.getSendStreams(); if (sendStreams != null) diff --git a/src/net/java/sip/communicator/impl/neomedia/VideoMediaStreamImpl.java b/src/net/java/sip/communicator/impl/neomedia/VideoMediaStreamImpl.java index bacb6242d..d15dda95f 100644 --- a/src/net/java/sip/communicator/impl/neomedia/VideoMediaStreamImpl.java +++ b/src/net/java/sip/communicator/impl/neomedia/VideoMediaStreamImpl.java @@ -22,12 +22,20 @@ import net.java.sip.communicator.util.*; /** + * Extends MediaStreamImpl in order to provide an implementation of + * VideoMediaStream. + * * @author Lubomir Marinov */ public class VideoMediaStreamImpl extends MediaStreamImpl implements VideoMediaStream { + + /** + * The Logger used by the VideoMediaStreamImpl class and + * its instances for logging output. + */ private static final Logger logger = Logger.getLogger(VideoMediaStreamImpl.class); @@ -46,8 +54,8 @@ public static Dimension selectVideoSize( if(videoDS == null) return null; - FormatControl formatControl = - (FormatControl) videoDS.getControl(FormatControl.class.getName()); + FormatControl formatControl + =(FormatControl) videoDS.getControl(FormatControl.class.getName()); if (formatControl == null) return null; @@ -123,6 +131,17 @@ public int compare(FormatInfo info0, FormatInfo info1) return ((VideoFormat) selectedFormat).getSize(); } + /** + * Initializes a new VideoMediaStreamImpl instance which will use + * the specified MediaDevice for both capture and playback of video + * exchanged via the specified StreamConnector. + * + * @param connector the StreamConnector the new instance is to use + * for sending and receiving video + * @param device the MediaDevice the new instance is to use for + * both capture and playback of video exchanged via the specified + * StreamConnector + */ public VideoMediaStreamImpl(StreamConnector connector, MediaDevice device) { super(connector, device); @@ -145,6 +164,11 @@ public Component getVisualComponent() return null; } + /* + * Overrides MediaStreamImpl#registerCustomCodecFormats(RTPManager) in order + * to register Constants#H264_RTP. + */ + @Override protected void registerCustomCodecFormats(RTPManager rtpManager) { // if we have already registered custom formats and we are running JMF diff --git a/src/net/java/sip/communicator/impl/neomedia/device/CaptureMediaDevice.java b/src/net/java/sip/communicator/impl/neomedia/device/CaptureMediaDevice.java index f9fb3ff9c..0b6c46803 100644 --- a/src/net/java/sip/communicator/impl/neomedia/device/CaptureMediaDevice.java +++ b/src/net/java/sip/communicator/impl/neomedia/device/CaptureMediaDevice.java @@ -31,6 +31,11 @@ public class CaptureMediaDevice implements MediaDevice { + + /** + * The Logger used by CaptureMediaDevice and its instances + * for logging output. + */ private static final Logger logger = Logger.getLogger(CaptureMediaDevice.class); @@ -171,6 +176,10 @@ else if (sourceFormat.matches(new Format(VideoFormat.H263_RTP))) return (VideoFormat) result.intersects(sourceFormat); } + /** + * Releases the resources allocated by this instance in the course of its + * execution and prepares it to be garbage collected. + */ public void close() { if (captureDevice != null) @@ -210,6 +219,19 @@ public void close() } } + /** + * Finds the first Format instance in a specific list of + * Formats which matches a specific Format. The + * implementation considers a pair of Formats matching if they have + * the same encoding. + * + * @param formats the array of Formats to be searched for a match + * to the specified format + * @param format the Format to search for a match in the specified + * formats + * @return the first element of formats which matches + * format i.e. is of the same encoding + */ private Format findFirstMatchingFormat(Format[] formats, Format format) { for (Format match : formats) @@ -323,6 +345,15 @@ private DataSource getConnectedCaptureDevice() return captureDevice; } + /** + * Gets the output DataSource of this instance which provides the + * captured (RTP) data to be sent by MediaStream to + * MediaStreamTarget. + * + * @return the output DataSource of this instance which provides + * the captured (RTP) data to be sent by MediaStream to + * MediaStreamTarget + */ public DataSource getDataSource() { Processor processor = getProcessor(); @@ -487,7 +518,8 @@ public void setFormat(MediaFormat format) * We need javax.media.Format and we know how to convert MediaFormat to * it only for MediaFormatImpl so assert early. */ - MediaFormatImpl mediaFormatImpl = (MediaFormatImpl) format; + MediaFormatImpl mediaFormatImpl + = (MediaFormatImpl) format; Processor processor = getProcessor(); @@ -555,6 +587,15 @@ public void setFormat(MediaFormat format) } } + /** + * Starts the processing of media in this instance in a specific direction. + * + * @param direction a MediaDirection value which represents the + * direction of the processing of media to be started. For example, + * {@link MediaDirection#SENDRECV} to start both capture and playback of + * media in this instance or {@link MediaDirection#SENDONLY} to only start + * the capture of media in this instance + */ public void start(MediaDirection direction) { if (direction == null) @@ -571,6 +612,15 @@ public void start(MediaDirection direction) } } + /** + * Stops the processing of media in this instance in a specific direction. + * + * @param direction a MediaDirection value which represents the + * direction of the processing of media to be stopped. For example, + * {@link MediaDirection#SENDRECV} to stop both capture and playback of + * media in this instance or {@link MediaDirection#SENDONLY} to only stop + * the capture of media in this instance + */ public void stop(MediaDirection direction) { if (direction == null) diff --git a/src/net/java/sip/communicator/service/neomedia/DefaultStreamConnector.java b/src/net/java/sip/communicator/service/neomedia/DefaultStreamConnector.java index 2bf788a48..3a21e33e5 100644 --- a/src/net/java/sip/communicator/service/neomedia/DefaultStreamConnector.java +++ b/src/net/java/sip/communicator/service/neomedia/DefaultStreamConnector.java @@ -22,6 +22,11 @@ public class DefaultStreamConnector implements StreamConnector { + + /** + * The Logger used by the DefaultStreamConnector class and + * its instances for logging output. + */ private static final Logger logger = Logger.getLogger(DefaultStreamConnector.class); @@ -47,6 +52,10 @@ public class DefaultStreamConnector public static final String MAX_PORT_NUMBER_PROPERTY_NAME = "net.java.sip.communicator.service.media.MAX_PORT_NUMBER"; + /** + * The maxium port number DefaultStreamConnector instances are to + * attempt to bind to. + */ private static int maxPort = -1; /** @@ -56,8 +65,25 @@ public class DefaultStreamConnector public static final String MIN_PORT_NUMBER_PROPERTY_NAME = "net.java.sip.communicator.service.media.MIN_PORT_NUMBER"; + /** + * The minimum port number DefaultStreamConnector instances are to + * attempt to bind to. + */ private static int minPort = -1; + /** + * Creates a new DatagramSocket instance which is bound to the + * specified local InetAddress and its port is within the range + * defined by the ConfigurationService properties + * {@link #MIN_PORT_NUMBER_PROPERTY_NAME} and + * {@link #MAX_PORT_NUMBER_PROPERTY_NAME}. Attempts at most + * {@link #BIND_RETRIES_PROPERTY_NAME} times to bind. + * + * @param bindAddr the local InetAddress the new + * DatagramSocket is to bind to + * @return a new DatagramSocket instance bound to the specified + * local InetAddress + */ private static synchronized DatagramSocket createDatagramSocket( InetAddress bindAddr) { @@ -94,6 +120,10 @@ private static synchronized DatagramSocket createDatagramSocket( return null; } + /** + * The local InetAddress this StreamConnector attempts to + * bind to on demand. + */ private final InetAddress bindAddr; /** @@ -131,7 +161,8 @@ public DefaultStreamConnector() * {@link #MAX_PORT_NUMBER_PROPERTY_NAME} at most * {@link #BIND_RETRIES_PROPERTY_NAME} times. * - * @param bindAddr + * @param bindAddr the local InetAddress the new instance is to + * attempt to bind to */ public DefaultStreamConnector(InetAddress bindAddr) { diff --git a/src/net/java/sip/communicator/service/neomedia/MediaStream.java b/src/net/java/sip/communicator/service/neomedia/MediaStream.java index 3fead0b5a..17dbedaab 100644 --- a/src/net/java/sip/communicator/service/neomedia/MediaStream.java +++ b/src/net/java/sip/communicator/service/neomedia/MediaStream.java @@ -19,6 +19,7 @@ * the openMediaStream() method of the MediaService. * * @author Emil Ivov + * @author Lubomir Marinov */ public interface MediaStream { @@ -148,5 +149,13 @@ public interface MediaStream */ public void removePropertyChangeListener(PropertyChangeListener listener); + /** + * Sets the target of this MediaStream to which it is to send and + * from which it is to receive data (e.g. RTP) and control data (e.g. RTCP). + * + * @param target the MediaStreamTarget describing the data + * (e.g. RTP) and the control data (e.g. RTCP) locations to which this + * MediaStream is to send and from which it is to receive + */ public void setTarget(MediaStreamTarget target); }