Adds javadocs.

src/net/java/sip/communicator/impl/neomedia/AudioMediaStreamImpl.java

@@ -17,12 +17,20 @@
 import net.java.sip.communicator.util.*;
 
 /**
+ * Extends <tt>MediaStreamImpl</tt> in order to provide an implementation of
+ * <tt>AudioMediaStream</tt>.
+ *
  * @author Lubomir Marinov
  */
 public class AudioMediaStreamImpl
     extends MediaStreamImpl
     implements AudioMediaStream
 {
+
+    /**
+     * The <tt>Logger</tt> used by the <tt>AudioMediaStreamImpl</tt> 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 <tt>AudioMediaStreamImpl</tt> instance which will use
+     * the specified <tt>MediaDevice</tt> for both capture and playback of audio
+     * exchanged via the specified <tt>StreamConnector</tt>.
+     *
+     * @param connector the <tt>StreamConnector</tt> the new instance is to use
+     * for sending and receiving audio
+     * @param device the <tt>MediaDevice</tt> the new instance is to use for
+     * both capture and playback of audio exchanged via the specified
+     * <tt>StreamConnector</tt>
+     */
     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

src/net/java/sip/communicator/impl/neomedia/MediaServiceImpl.java

@@ -36,9 +36,17 @@ public class MediaServiceImpl
     private static final List<MediaDevice> EMPTY_DEVICES
         = Collections.emptyList();
 
+    /**
+     * The <tt>CaptureDevice</tt> 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 <tt>CaptureDevice</tt> user choices such as the default audio
+     * and video capture devices.
+     *
+     * @return the <tt>CaptureDevice</tt> user choices such as the default audio
+     * and video capture devices.
+     */
     DeviceConfiguration getDeviceConfiguration()
     {
         return deviceConfiguration;
@@ -130,11 +145,22 @@ public List<MediaDevice> 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 <tt>MediaService</tt> implementation and thus makes it
+     * operational.
+     */
     void start()
     {
         deviceConfiguration.initialize();
@@ -142,6 +168,10 @@ void start()
         encodingConfiguration.registerCustomPackages();
     }
 
+    /**
+     * Stops this <tt>MediaService</tt> implementation and thus signals that its
+     * utilization should cease.
+     */
     void stop()
     {
     }

src/net/java/sip/communicator/impl/neomedia/MediaStreamImpl.java

@@ -32,6 +32,11 @@ public class MediaStreamImpl
                SendStreamListener,
                SessionListener
 {
+
+    /**
+     * The <tt>Logger</tt> used by the <tt>MediaStreamImpl</tt> 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 <tt>RTPManager</tt> which utilizes {@link #rtpConnector} and sends
+     * and receives RTP and RTCP traffic on behalf of this <tt>MediaStream</tt>.
+     */
     private RTPManager rtpManager;
 
+    /**
+     * The <tt>MediaDirection</tt> 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 <tt>SendStream</tt> 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 <tt>RTPManager</tt> instance which sends and receives RTP and
+     * RTCP traffic on behalf of this <tt>MediaStream</tt>.
+     *
+     * @return the <tt>RTPManager</tt> instance which sends and receives RTP and
+     * RTCP traffic on behalf of this <tt>MediaStream</tt>
+     */
     private RTPManager getRTPManager()
     {
         if (rtpManager == null)
@@ -292,6 +318,14 @@ private RTPManager getRTPManager()
         return rtpManager;
     }
 
+    /**
+     * Registers any custom JMF <tt>Format</tt>s with a specific
+     * <tt>RTPManager</tt>. Extenders should override in order to register their
+     * own customizations.
+     *
+     * @param rtpManager the <tt>RTPManager</tt> to register any custom JMF
+     * <tt>Format</tt>s 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 <tt>MediaDirection</tt> 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<SendStream> 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 <tt>MediaDirection</tt> 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<SendStream> sendStreams = rtpManager.getSendStreams();
 
             if (sendStreams != null)

src/net/java/sip/communicator/impl/neomedia/VideoMediaStreamImpl.java

@@ -22,12 +22,20 @@
 import net.java.sip.communicator.util.*;
 
 /**
+ * Extends <tt>MediaStreamImpl</tt> in order to provide an implementation of
+ * <tt>VideoMediaStream</tt>.
+ *
  * @author Lubomir Marinov
  */
 public class VideoMediaStreamImpl
     extends MediaStreamImpl
     implements VideoMediaStream
 {
+
+    /**
+     * The <tt>Logger</tt> used by the <tt>VideoMediaStreamImpl</tt> 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 <tt>VideoMediaStreamImpl</tt> instance which will use
+     * the specified <tt>MediaDevice</tt> for both capture and playback of video
+     * exchanged via the specified <tt>StreamConnector</tt>.
+     *
+     * @param connector the <tt>StreamConnector</tt> the new instance is to use
+     * for sending and receiving video
+     * @param device the <tt>MediaDevice</tt> the new instance is to use for
+     * both capture and playback of video exchanged via the specified
+     * <tt>StreamConnector</tt>
+     */
     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

src/net/java/sip/communicator/impl/neomedia/device/CaptureMediaDevice.java

@@ -31,6 +31,11 @@
 public class CaptureMediaDevice
     implements MediaDevice
 {
+
+    /**
+     * The <tt>Logger</tt> used by <tt>CaptureMediaDevice</tt> 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 <tt>Format</tt> instance in a specific list of
+     * <tt>Format</tt>s which matches a specific <tt>Format</tt>. The
+     * implementation considers a pair of <tt>Format</tt>s matching if they have
+     * the same encoding.
+     *
+     * @param formats the array of <tt>Format</tt>s to be searched for a match
+     * to the specified <tt>format</tt>
+     * @param format the <tt>Format</tt> to search for a match in the specified
+     * <tt>formats</tt>
+     * @return the first element of <tt>formats</tt> which matches
+     * <tt>format</tt> 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 <tt>DataSource</tt> of this instance which provides the
+     * captured (RTP) data to be sent by <tt>MediaStream</tt> to
+     * <tt>MediaStreamTarget</tt>.
+     *
+     * @return the output <tt>DataSource</tt> of this instance which provides
+     * the captured (RTP) data to be sent by <tt>MediaStream</tt> to
+     * <tt>MediaStreamTarget</tt>
+     */
     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<? extends Format> mediaFormatImpl
+            = (MediaFormatImpl<? extends Format>) 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 <tt>MediaDirection</tt> 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 <tt>MediaDirection</tt> 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)

src/net/java/sip/communicator/service/neomedia/DefaultStreamConnector.java

@@ -22,6 +22,11 @@
 public class DefaultStreamConnector
     implements StreamConnector
 {
+
+    /**
+     * The <tt>Logger</tt> used by the <tt>DefaultStreamConnector</tt> 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 <tt>DefaultStreamConnector</tt> 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 <tt>DefaultStreamConnector</tt> instances are to
+     * attempt to bind to.
+     */
     private static int minPort = -1;
 
+    /**
+     * Creates a new <tt>DatagramSocket</tt> instance which is bound to the
+     * specified local <tt>InetAddress</tt> and its port is within the range
+     * defined by the <tt>ConfigurationService</tt> 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 <tt>InetAddress</tt> the new
+     * <tt>DatagramSocket</tt> is to bind to
+     * @return a new <tt>DatagramSocket</tt> instance bound to the specified
+     * local <tt>InetAddress</tt>
+     */
     private static synchronized DatagramSocket createDatagramSocket(
             InetAddress bindAddr)
     {
@@ -94,6 +120,10 @@ private static synchronized DatagramSocket createDatagramSocket(
         return null;
     }
 
+    /**
+     * The local <tt>InetAddress</tt> this <tt>StreamConnector</tt> 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 <tt>InetAddress</tt> the new instance is to
+     * attempt to bind to
      */
     public DefaultStreamConnector(InetAddress bindAddr)
     {

src/net/java/sip/communicator/service/neomedia/MediaStream.java

@@ -19,6 +19,7 @@
  * the <tt>openMediaStream()</tt> method of the <tt>MediaService</tt>.
  *
  * @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 <tt>MediaStream</tt> 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 <tt>MediaStreamTarget</tt> describing the data
+     * (e.g. RTP) and the control data (e.g. RTCP) locations to which this
+     * <tt>MediaStream</tt> is to send and from which it is to receive
+     */
     public void setTarget(MediaStreamTarget target);
 }