From b32b303d3990899fee0168056027f392508070c2 Mon Sep 17 00:00:00 2001
From: Lyubomir Marinov <lyubomir.marinov@jitsi.org>
Date: Thu, 22 Nov 2012 21:39:18 +0000
Subject: [PATCH] - Commits work in progress on adding javadocs. Reported by
Yana Stamcheva. - Fixes spelling mistakes. - Fixes warnings.
---
.../coreaudio/CoreAudioVolumeControl.java | 1 -
.../impl/neomedia/device/AudioSystem.java | 121 ++++++++++++------
.../impl/neomedia/device/CaptureDevices.java | 4 +-
.../impl/neomedia/device/DeviceSystem.java | 110 ++++++++++++++++
.../jitsi/impl/neomedia/device/Devices.java | 28 ++--
.../device/ExtendedCaptureDeviceInfo.java | 2 +-
.../impl/neomedia/device/NotifyDevices.java | 1 +
7 files changed, 210 insertions(+), 57 deletions(-)
diff --git a/src/org/jitsi/impl/neomedia/coreaudio/CoreAudioVolumeControl.java b/src/org/jitsi/impl/neomedia/coreaudio/CoreAudioVolumeControl.java
index 60eb5da6..b0b4f136 100644
--- a/src/org/jitsi/impl/neomedia/coreaudio/CoreAudioVolumeControl.java
+++ b/src/org/jitsi/impl/neomedia/coreaudio/CoreAudioVolumeControl.java
@@ -8,7 +8,6 @@
import org.jitsi.impl.neomedia.*;
import org.jitsi.impl.neomedia.device.*;
-import org.jitsi.service.neomedia.*;
import org.jitsi.util.*;
/**
diff --git a/src/org/jitsi/impl/neomedia/device/AudioSystem.java b/src/org/jitsi/impl/neomedia/device/AudioSystem.java
index 7fc9a761..f495ac0a 100644
--- a/src/org/jitsi/impl/neomedia/device/AudioSystem.java
+++ b/src/org/jitsi/impl/neomedia/device/AudioSystem.java
@@ -10,13 +10,43 @@
import org.jitsi.service.neomedia.*;
+/**
+ * Represents a <tt>DeviceSystem</tt> which provides support for the devices to
+ * capture and play back audio (media). Examples include implementations which
+ * integrate the native PortAudio, PulseAudio libraries.
+ *
+ * @author Lyubomir Marinov
+ */
public abstract class AudioSystem
extends DeviceSystem
{
+ /**
+ * The constant/flag (to be) returned by {@link #getFeatures()} in order to
+ * indicate that the respective <tt>AudioSystem</tt> supports toggling its
+ * denoise functionality between on and off. The UI will look for the
+ * presence of the flag in order to determine whether a check box is to be
+ * shown to the user to enable toggling the denoise functionality.
+ */
public static final int FEATURE_DENOISE = 2;
+ /**
+ * The constant/flag (to be) returned by {@link #getFeatures()} in order to
+ * indicate that the respective <tt>AudioSystem</tt> supports toggling its
+ * echo cancellation functionality between on and off. The UI will look for
+ * the presence of the flag in order to determine whether a check box is to
+ * be shown to the user to enable toggling the echo cancellation
+ * functionality.
+ */
public static final int FEATURE_ECHO_CANCELLATION = 4;
+ /**
+ * The constant/flag (to be) returned by {@link #getFeatures()} in order to
+ * indicate that the respective <tt>AudioSystem</tt> differentiates between
+ * playback and notification audio devices. The UI, for example, will look
+ * for the presence of the flag in order to determine whether separate combo
+ * boxes are to be shown to the user to allow the configuration of the
+ * preferred playback and notification audio devices.
+ */
public static final int FEATURE_NOTIFY_AND_PLAYBACK_DEVICES = 8;
public static final String LOCATOR_PROTOCOL_AUDIORECORD = "audiorecord";
@@ -86,7 +116,9 @@ public static AudioSystem[] getAudioSystems()
public static final int PLAYBACK_INDEX = 2;
/**
- * The list of the devices: capture, notify or playback.
+ * The list of devices detected by this <tt>AudioSystem</tt> indexed by
+ * their category which is among {@link #CAPTURE_INDEX},
+ * {@link #NOTIFY_INDEX} and {@link #PLAYBACK_INDEX}.
*/
private Devices[] devices;
@@ -103,45 +135,43 @@ protected AudioSystem(String locatorProtocol, int features)
}
/**
- * Gets the list of a kind of devices: cpature, notify or playback.
+ * Gets the list of a kind of devices: capture, notify or playback.
*
- * @param index The index of the specific devices: cpature, notify or
+ * @param index The index of the specific devices: capture, notify or
* playback.
*
- * @return The list of a kind of devices: cpature, notify or playback.
+ * @return The list of a kind of devices: capture, notify or playback.
*/
public List<ExtendedCaptureDeviceInfo> getDevices(int index)
{
- return this.devices[index].getDevices();
+ return devices[index].getDevices();
}
/**
- * Gets the selected device for a specific kind: cpature, notify or
+ * Gets the selected device for a specific kind: capture, notify or
* playback.
*
- * @param index The index of the specific devices: cpature, notify or
+ * @param index The index of the specific devices: capture, notify or
* playback.
- *
- * @return The selected device for a specific kind: cpature, notify or
+ * @return The selected device for a specific kind: capture, notify or
* playback.
*/
public ExtendedCaptureDeviceInfo getDevice(int index)
{
- return this.devices[index].getDevice(
- getLocatorProtocol(),
- getDevices(index));
+ return
+ devices[index].getDevice(getLocatorProtocol(), getDevices(index));
}
/**
- * Sets the list of a kind of devices: cpature, notify or playback.
+ * Sets the list of a kind of devices: capture, notify or playback.
*
- * @param activeCaptureDevices The list of a kind of devices: cpature,
+ * @param activeCaptureDevices The list of a kind of devices: capture,
* notify or playback.
*/
protected void setCaptureDevices(
List<ExtendedCaptureDeviceInfo> activeCaptureDevices)
{
- this.devices[CAPTURE_INDEX].setActiveDevices(activeCaptureDevices);
+ devices[CAPTURE_INDEX].setActiveDevices(activeCaptureDevices);
}
/**
@@ -158,7 +188,7 @@ public void setDevice(
ExtendedCaptureDeviceInfo device,
boolean save)
{
- this.devices[index].setDevice(
+ devices[index].setDevice(
getLocatorProtocol(),
device,
save,
@@ -173,26 +203,40 @@ public void setDevice(
protected void setPlaybackDevices(
List<ExtendedCaptureDeviceInfo> activePlaybackDevices)
{
- this.devices[PLAYBACK_INDEX].setActiveDevices(activePlaybackDevices);
+ devices[PLAYBACK_INDEX].setActiveDevices(activePlaybackDevices);
// The active notify device list is a copy of the playback one.
- this.devices[NOTIFY_INDEX].setActiveDevices(activePlaybackDevices);
+ devices[NOTIFY_INDEX].setActiveDevices(activePlaybackDevices);
}
/**
- * Pre-initializes this audio system before setting the different devices.
+ * {@inheritDoc}
+ *
+ * Removes any capture, playback and notification devices previously
+ * detected by this <tt>AudioSystem</tt> and prepares it for the execution
+ * of its {@link DeviceSystem#doInitialize()} implementation (which detects
+ * all devices to be provided by this instance).
*/
+ @Override
protected void preInitialize()
{
super.preInitialize();
- if(this.devices == null)
+
+ if (devices == null)
{
- this.devices = new Devices[3];
- this.devices[0] = new CaptureDevices(this);
- this.devices[1] = new NotifyDevices(this);
- this.devices[2] = new PlaybackDevices(this);
+ devices = new Devices[3];
+ devices[CAPTURE_INDEX] = new CaptureDevices(this);
+ devices[NOTIFY_INDEX] = new NotifyDevices(this);
+ devices[PLAYBACK_INDEX] = new PlaybackDevices(this);
}
}
+ /**
+ * {@inheritDoc}
+ *
+ * Because <tt>AudioSystem</tt> may support playback and notification audio
+ * devices apart from capture audio devices, fires more specific
+ * <tt>PropertyChangeEvent</tt>s than <tt>DeviceSystem</tt>
+ */
@Override
protected void postInitialize()
{
@@ -204,7 +248,7 @@ protected void postInitialize()
{
try
{
- this.postInitializeSpecificDevices(CAPTURE_INDEX);
+ postInitializeSpecificDevices(CAPTURE_INDEX);
}
finally
{
@@ -212,11 +256,11 @@ protected void postInitialize()
{
try
{
- this.postInitializeSpecificDevices(NOTIFY_INDEX);
+ postInitializeSpecificDevices(NOTIFY_INDEX);
}
finally
{
- this.postInitializeSpecificDevices(PLAYBACK_INDEX);
+ postInitializeSpecificDevices(PLAYBACK_INDEX);
}
}
}
@@ -224,31 +268,30 @@ protected void postInitialize()
}
/**
- * Sets the device lists after the different audio systems (portaudio,
- * pulseaudio, etc) have finished to detects the evices.
+ * Sets the device lists after the different audio systems (PortAudio,
+ * PulseAudio, etc) have finished to detects the devices.
*
* @param index The index corresponding to a specific device kind:
* capture/notify/playback.
*/
protected void postInitializeSpecificDevices(int index)
{
- // Gets all current active devies.
- List<ExtendedCaptureDeviceInfo> activeDevices = this.getDevices(index);
+ // Gets all current active devices.
+ List<ExtendedCaptureDeviceInfo> activeDevices = getDevices(index);
// Gets the default device.
+ Devices devices = this.devices[index];
ExtendedCaptureDeviceInfo selectedActiveDevice
- = this.devices[index].getDevice(
- getLocatorProtocol(),
- activeDevices);
+ = devices.getDevice(getLocatorProtocol(), activeDevices);
// Sets the default device as selected (this function will only fire a
// property change if the device has changed from previous
// configuration).
// This "set" part is important because only the fire property event
// provides a way to get hot plugged devices working during a call.
- this.devices[index].setDevice(
- getLocatorProtocol(),
- selectedActiveDevice,
- false,
- activeDevices);
+ devices.setDevice(
+ getLocatorProtocol(),
+ selectedActiveDevice,
+ false,
+ activeDevices);
}
/**
diff --git a/src/org/jitsi/impl/neomedia/device/CaptureDevices.java b/src/org/jitsi/impl/neomedia/device/CaptureDevices.java
index 3638784c..422b1add 100644
--- a/src/org/jitsi/impl/neomedia/device/CaptureDevices.java
+++ b/src/org/jitsi/impl/neomedia/device/CaptureDevices.java
@@ -15,7 +15,7 @@
import org.jitsi.impl.neomedia.*;
/**
- * Manages the list of active (currently pluged-in) capture devices and manages
+ * Manages the list of active (currently plugged-in) capture devices and manages
* user preferences between all known devices (previously and actually
* plugged-in).
*
@@ -35,7 +35,7 @@ public class CaptureDevices
private List<ExtendedCaptureDeviceInfo> activeCaptureDevices = null;
/**
- * Initializes the capture device list managment.
+ * Initializes the capture device list management.
*
* @param audioSystem The audio system managing this capture device list.
*/
diff --git a/src/org/jitsi/impl/neomedia/device/DeviceSystem.java b/src/org/jitsi/impl/neomedia/device/DeviceSystem.java
index d3224c6d..79caa0a8 100644
--- a/src/org/jitsi/impl/neomedia/device/DeviceSystem.java
+++ b/src/org/jitsi/impl/neomedia/device/DeviceSystem.java
@@ -19,11 +19,33 @@
import org.jitsi.util.*;
import org.jitsi.util.event.*;
+/**
+ * Represents the base of a supported device system/backend such as DirectShow,
+ * PortAudio, PulseAudio, QuickTime, video4linux2. A <tt>DeviceSystem</tt> is
+ * initialized at a certain time (usually, during the initialization of the
+ * <tt>MediaService</tt> implementation which is going to use it) and it
+ * registers with FMJ the <tt>CaptureDevice</tt>s it will provide. In addition
+ * to providing the devices for the purposes of capture, a <tt>DeviceSystem</tt>
+ * also provides the devices on which playback is to be performed i.e. it acts
+ * as a <tt>Renderer</tt> factory via its {@link #createRenderer(boolean)}
+ * method.
+ *
+ * @author Lyubomir Marinov
+ */
public abstract class DeviceSystem
extends PropertyChangeNotifier
{
+ /**
+ * The <tt>Logger</tt> used by the <tt>DeviceSystem</tt> class and its
+ * instances for logging output.
+ */
private static final Logger logger = Logger.getLogger(DeviceSystem.class);
+ /**
+ * The constant/flag (to be) returned by {@link #getFeatures()} in order to
+ * indicate that the respective <tt>DeviceSystem</tt> supports invoking its
+ * {@link #initialize()} more than once.
+ */
public static final int FEATURE_REINITIALIZE = 1;
public static final String LOCATOR_PROTOCOL_CIVIL = "civil";
@@ -40,6 +62,9 @@ public abstract class DeviceSystem
public static final String PROP_DEVICES = "devices";
+ /**
+ * The list of <tt>DeviceSystem</tt>s which have been initialized.
+ */
private static List<DeviceSystem> deviceSystems
= new LinkedList<DeviceSystem>();
@@ -80,6 +105,17 @@ public static DeviceSystem[] getDeviceSystems(MediaType mediaType)
return ret.toArray(new DeviceSystem[ret.size()]);
}
+ /**
+ * Initializes the <tt>DeviceSystem</tt> instances which are to represent
+ * the supported device systems/backends such as DirectShow, PortAudio,
+ * PulseAudio, QuickTime, video4linux2. The method may be invoked multiple
+ * times. If a <tt>DeviceSystem</tt> has been initialized by a previous
+ * invocation of the method, its {@link #initialize()} method will be called
+ * again as part of the subsequent invocation only if the
+ * <tt>DeviceSystem</tt> in question returns a set of flags from its
+ * {@link #getFeatures()} method which contains the constant/flag
+ * {@link #FEATURE_REINITIALIZE}.
+ */
public static void initializeDeviceSystems()
{
ConfigurationService cfg = LibJitsi.getConfigurationService();
@@ -117,8 +153,22 @@ public static void initializeDeviceSystems()
}
}
+ /**
+ * Initializes the <tt>DeviceSystem</tt> instances which are to represent
+ * the supported device systems/backends which are to capable of capturing
+ * and playing back media of a specific type such as audio or video.
+ *
+ * @param mediaType the <tt>MediaType</tt> of the <tt>DeviceSystem</tt>s to
+ * be initialized
+ */
public static void initializeDeviceSystems(MediaType mediaType)
{
+ /*
+ * The list of supported DeviceSystem implementations if hard-coded. The
+ * order of the classes is significant and represents a decreasing
+ * preference with respect to which DeviceSystem is to be picked up as
+ * the default one (for the specified mediaType, of course).
+ */
String[] classNames;
switch (mediaType)
@@ -152,6 +202,19 @@ public static void initializeDeviceSystems(MediaType mediaType)
initializeDeviceSystems(classNames);
}
+ /**
+ * Initializes the <tt>DeviceSystem</tt> instances specified by the names of
+ * the classes which implement them. If a <tt>DeviceSystem</tt> instance has
+ * already been initialized for a specific class name, no new instance of
+ * the class in question will be initialized and rather the
+ * {@link #initialize()} method of the existing <tt>DeviceSystem</tt>
+ * instance will be invoked if the <tt>DeviceSystem</tt> instance returns a
+ * set of flags from its {@link #getFeatures()} which contains
+ * {@link #FEATURE_REINITIALIZE}.
+ *
+ * @param classNames the names of the classes which extend the
+ * <tt>DeviceSystem</tt> class and instances of which are to be initialized
+ */
private static void initializeDeviceSystems(String[] classNames)
{
synchronized (deviceSystems)
@@ -197,9 +260,11 @@ private static void initializeDeviceSystems(String[] classNames)
if (t instanceof ThreadDeath)
throw (ThreadDeath) t;
else if (logger.isDebugEnabled())
+ {
logger.debug(
"Failed to initialize " + className,
t);
+ }
}
if (o instanceof DeviceSystem)
{
@@ -225,19 +290,39 @@ else if (logger.isDebugEnabled())
if (t instanceof ThreadDeath)
throw (ThreadDeath) t;
else if (logger.isDebugEnabled())
+ {
logger.debug(
"Failed to reinitialize " + className,
t);
+ }
}
}
}
}
}
+ /**
+ * The set of flags indicating which optional features are supported by this
+ * <tt>DeviceSystem</tt>. For example, the presence of the flag
+ * {@link #FEATURE_REINITIALIZE} indicates that this instance is able to
+ * deal with multiple consecutive invocations of its {@link #initialize()}
+ * method.
+ */
private final int features;
+ /**
+ * The protocol of the <tt>MediaLocator</tt> of the
+ * <tt>CaptureDeviceInfo</tt>s (to be) registered (with FMJ) by this
+ * <tt>DeviceSystem</tt>. The protocol is a unique identifier of a
+ * <tt>DeviceSystem</tt>.
+ */
private final String locatorProtocol;
+ /**
+ * The <tt>MediaType</tt> of this <tt>DeviceSystem</tt> i.e. the type of the
+ * media that this instance supports for capture and playback such as audio
+ * or video.
+ */
private final MediaType mediaType;
protected DeviceSystem(MediaType mediaType, String locatorProtocol)
@@ -279,11 +364,13 @@ public Renderer createRenderer(boolean playback)
if (t instanceof ThreadDeath)
throw (ThreadDeath) t;
else
+ {
logger.warn(
"Failed to initialize a new "
+ className
+ " instance",
t);
+ }
}
}
return null;
@@ -326,11 +413,26 @@ protected final void initialize()
}
}
+ /**
+ * Invoked as part of the execution of {@link #initialize()} after the
+ * execution of {@link #doInitialize()} regardless of whether the latter
+ * completed successfully. The implementation of <tt>DeviceSystem</tt> fires
+ * a new <tt>PropertyChangeEvent</tt> to notify that the value of the
+ * property {@link #PROP_DEVICES} of this instance may have changed i.e.
+ * that the list of devices detected by this instance may have changed.
+ */
protected void postInitialize()
{
firePropertyChange(PROP_DEVICES, null, null);
}
+ /**
+ * Invoked as part of the execution of {@link #initialize()} before the
+ * execution of {@link #doInitialize()}. The implementation of
+ * <tt>DeviceSystem</tt> removes from FMJ's <tt>CaptureDeviceManager</tt>
+ * the <tt>CaptureDeviceInfo</tt>s whose <tt>MediaLocator</tt> has the same
+ * protocol as {@link #getLocatorProtocol()} of this instance.
+ */
protected void preInitialize()
{
Format format;
@@ -379,15 +481,23 @@ protected void preInitialize()
* historical reasons.
*/
if (logger.isDebugEnabled())
+ {
logger.debug(
"Failed to commit CaptureDeviceManager",
ioe);
+ }
}
}
}
}
}
+ /**
+ * Returns a human-readable representation of this <tt>DeviceSystem</tt>.
+ *
+ * @return a <tt>String</tt> which represents this <tt>DeviceSystem</tt> in
+ * a human-readable form
+ */
@Override
public String toString()
{
diff --git a/src/org/jitsi/impl/neomedia/device/Devices.java b/src/org/jitsi/impl/neomedia/device/Devices.java
index d1723fd8..f63cae7e 100644
--- a/src/org/jitsi/impl/neomedia/device/Devices.java
+++ b/src/org/jitsi/impl/neomedia/device/Devices.java
@@ -21,23 +21,23 @@
public abstract class Devices
{
/**
- * The selected active device.
+ * The audio system managing this device list.
*/
- private ExtendedCaptureDeviceInfo device = null;
+ private final AudioSystem audioSystem;
/**
- * The list of device ID/names saved by the congifuration service and
- * previously saved given user preference order.
+ * The selected active device.
*/
- private List<String> devicePreferences = new ArrayList<String>();
+ private ExtendedCaptureDeviceInfo device = null;
/**
- * The audio system managing this device list.
+ * The list of device ID/names saved by the configuration service and
+ * previously saved given user preference order.
*/
- private AudioSystem audioSystem;
+ private final List<String> devicePreferences = new ArrayList<String>();
/**
- * Initializes the device list managment.
+ * Initializes the device list management.
*
* @param audioSystem The audio system managing this device list.
*/
@@ -84,7 +84,7 @@ public ExtendedCaptureDeviceInfo getDevice(
}
}
- // Search if an active device match one of the previsouly configured
+ // Search if an active device match one of the previously configured
// in the preferences.
synchronized(devicePreferences)
{
@@ -151,7 +151,7 @@ private void loadDevicePreferences(String locator, String property)
if (deviceIdentifiersString != null)
{
devicePreferences.clear();
- // We must parce the string in order to load the device
+ // We must parse the string in order to load the device
// list.
String[] deviceIdentifiers = deviceIdentifiersString
.substring(2, deviceIdentifiersString.length() - 2)
@@ -317,7 +317,7 @@ private void addToDevicePreferences(
}
}
// If there is no active devices or the device is not selected, then
- // set the new device to the end of the device peference list.
+ // set the new device to the end of the device preference list.
devicePreferences.add(newDeviceIdentifier);
}
}
@@ -355,7 +355,7 @@ private void renameOldFashionedIdentifier(
// If there is one old fashioned identifier.
if(nameIndex != -1)
{
- // If the correspondant new fashioned identifier
+ // If the corresponding new fashioned identifier
// does not exists, then renames the old one into
// the new one.
if(idIndex == -1)
@@ -363,7 +363,7 @@ private void renameOldFashionedIdentifier(
devicePreferences.set(nameIndex,
activeDevices.get(i).getIdentifier());
}
- // Else removes the dupplicate.
+ // Else removes the duplicate.
else
{
devicePreferences.remove(nameIndex);
@@ -377,7 +377,7 @@ private void renameOldFashionedIdentifier(
}
/**
- * Saves the device preferences and wrtite it to the configuration file.
+ * Saves the device preferences and write it to the configuration file.
*
* @param locator The string representation of the locator.
* @param property the name of the <tt>ConfigurationService</tt> property
diff --git a/src/org/jitsi/impl/neomedia/device/ExtendedCaptureDeviceInfo.java b/src/org/jitsi/impl/neomedia/device/ExtendedCaptureDeviceInfo.java
index 6d7201e3..abad3638 100644
--- a/src/org/jitsi/impl/neomedia/device/ExtendedCaptureDeviceInfo.java
+++ b/src/org/jitsi/impl/neomedia/device/ExtendedCaptureDeviceInfo.java
@@ -10,7 +10,7 @@
/**
* Adds some important information (i.e. device type, UID.) to FMJ
- * CaptureDeviceInfo.
+ * <tt>CaptureDeviceInfo</tt>.
*
* @author Vincent Lucas
*/
diff --git a/src/org/jitsi/impl/neomedia/device/NotifyDevices.java b/src/org/jitsi/impl/neomedia/device/NotifyDevices.java
index 9fed477f..92e98059 100644
--- a/src/org/jitsi/impl/neomedia/device/NotifyDevices.java
+++ b/src/org/jitsi/impl/neomedia/device/NotifyDevices.java
@@ -36,6 +36,7 @@ public NotifyDevices(AudioSystem audioSystem)
*
* @return The property of the capture devices.
*/
+ @Override
protected String getPropDevice()
{
return PROP_DEVICE;
--
GitLab