org.gstreamer
Class Registry

java.lang.Object
  extended by org.gstreamer.lowlevel.NativeValue
      extended by org.gstreamer.lowlevel.Handle
          extended by org.gstreamer.lowlevel.NativeObject
              extended by org.gstreamer.lowlevel.RefCountedObject
                  extended by org.gstreamer.GObject
                      extended by org.gstreamer.GstObject
                          extended by org.gstreamer.Registry

public class Registry
extends GstObject

Abstract base class for management of Plugin objects.

One registry holds the metadata of a set of plugins. All registries build the RegistryPool.

Design:

The Registry object is a list of plugins and some methods for dealing with them. Plugins are matched 1-1 with a file on disk, and may or may not be loaded at a given time. There may be multiple Registry objects, but the "default registry" is the only object that has any meaning to the core.

The registry.xml file is actually a cache of plugin information. This is unlike versions prior to 0.10, where the registry file was the primary source of plugin information, and was created by the gst-register command.

The primary source, at all times, of plugin information is each plugin file itself. Thus, if an application wants information about a particular plugin, or wants to search for a feature that satisfies given criteria, the primary means of doing so is to load every plugin and look at the resulting information that is gathered in the default registry. Clearly, this is a time consuming process, so we cache information in the registry.xml file.

On startup, plugins are searched for in the plugin search path. This path can be set directly using the GST_PLUGIN_PATH environment variable. The registry file is loaded from ~/.gstreamer-$GST_MAJORMINOR/registry-$ARCH.xml or the file listed in the GST_REGISTRY environment variable. The only reason to change the registry location is for testing.

For each plugin that is found in the plugin search path, there could be 3 possibilities for cached information:

  1. the cache may not contain information about a given file.
  2. the cache may have stale information.
  3. the cache may have current information.

In the first two cases, the plugin is loaded and the cache updated. In addition to these cases, the cache may have entries for plugins that are not relevant to the current process. These are marked as not available to the current process. If the cache is updated for whatever reason, it is marked dirty.

A dirty cache is written out at the end of initialization. Each entry is checked to make sure the information is minimally valid. If not, the entry is simply dropped.

Implementation notes:

The "cache" and "default registry" are different concepts and can represent different sets of plugins. For various reasons, at init time, the cache is stored in the default registry, and plugins not relevant to the current process are marked with the %GST_PLUGIN_FLAG_CACHED bit. These plugins are removed at the end of intitialization.


Nested Class Summary
static interface Registry.PluginFeatureFilter
           
static interface Registry.PluginFilter
           
 
Nested classes/interfaces inherited from class org.gstreamer.GObject
GObject.GCallback
 
Nested classes/interfaces inherited from class org.gstreamer.lowlevel.NativeObject
org.gstreamer.lowlevel.NativeObject.Initializer
 
Field Summary
 
Fields inherited from class org.gstreamer.lowlevel.NativeObject
defaultInit, ownsHandle
 
Constructor Summary
Registry(org.gstreamer.lowlevel.NativeObject.Initializer init)
          Creates a new instance of Registry
 
Method Summary
 boolean addPlugin(Plugin plugin)
          Add the plugin to the registry.
 Plugin findPlugin(java.lang.String name)
          Find a plugin in the registry.
 PluginFeature findPluginFeature(java.lang.String name)
          Find a PluginFeature by name in the registry.
 PluginFeature findPluginFeature(java.lang.String name, org.gstreamer.lowlevel.GType type)
          Find the PluginFeature with the given name and type in the registry.
static Registry getDefault()
          Retrieves the default registry.
 java.util.List<PluginFeature> getPluginFeatureListByPlugin(java.lang.String name)
          Retrieves a list of PluginFeature of the named Plugin.
 java.util.List<PluginFeature> getPluginFeatureListByType(org.gstreamer.lowlevel.GType type)
          Retrieves a list of PluginFeature of the Plugin type.
 java.util.List<Plugin> getPluginList()
          Get a list of all plugins registered in the registry.
 java.util.List<Plugin> getPluginList(Registry.PluginFilter filter, boolean onlyReturnFirstMatch)
          Get a subset of the Plugins in the registry, filtered by filter.
 void removePlugin(Plugin plugin)
          Remove a plugin from the registry.
 boolean scanPath(java.lang.String path)
          Add the given path to the registry.
 
Methods inherited from class org.gstreamer.GstObject
addListenerProxy, getName, initializer, initializer, objectFor, objectFor, ref, removeListenerProxy, setName, steal, toString, unref
 
Methods inherited from class org.gstreamer.GObject
addCallback, connect, connect, connect, disconnect, disconnect, disposeNativeHandle, g_signal_connect, get, invalidate, objectFor, removeCallback, set
 
Methods inherited from class org.gstreamer.lowlevel.NativeObject
classFor, disown, dispose, equals, finalize, getNativeAddress, handle, hashCode, initializer, instanceFor, isDisposed, nativeValue, objectFor, objectFor
 
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Registry

public Registry(org.gstreamer.lowlevel.NativeObject.Initializer init)
Creates a new instance of Registry

Method Detail

getDefault

public static Registry getDefault()
Retrieves the default registry.

Returns:
The default Registry.

findPlugin

public Plugin findPlugin(java.lang.String name)
Find a plugin in the registry.

Parameters:
name - The plugin name to find.
Returns:
The plugin with the given name or null if the plugin was not found.

addPlugin

public boolean addPlugin(Plugin plugin)
Add the plugin to the registry. The plugin-added signal will be emitted.

Parameters:
plugin - the Plugin to add
Returns:
true on success.

removePlugin

public void removePlugin(Plugin plugin)
Remove a plugin from the registry.

Parameters:
plugin - The plugin to remove.

findPluginFeature

public PluginFeature findPluginFeature(java.lang.String name,
                                       org.gstreamer.lowlevel.GType type)
Find the PluginFeature with the given name and type in the registry.

Parameters:
name - The name of the plugin feature to find.
type - The type of the plugin feature to find.
Returns:
The pluginfeature with the given name and type or null if the plugin was not found.

findPluginFeature

public PluginFeature findPluginFeature(java.lang.String name)
Find a PluginFeature by name in the registry.

Parameters:
name - The name of the plugin feature to find.
Returns:
The PluginFeature or null if not found.

getPluginList

public java.util.List<Plugin> getPluginList()
Get a list of all plugins registered in the registry.

Returns:
a List of Plugin

getPluginList

public java.util.List<Plugin> getPluginList(Registry.PluginFilter filter,
                                            boolean onlyReturnFirstMatch)
Get a subset of the Plugins in the registry, filtered by filter.

Parameters:
filter - the filter to use
onlyReturnFirstMatch - If true, only return the first plugin that matches the filter.
Returns:
A List of Plugin objects that match the filter.

getPluginFeatureListByType

public java.util.List<PluginFeature> getPluginFeatureListByType(org.gstreamer.lowlevel.GType type)
Retrieves a list of PluginFeature of the Plugin type.

Parameters:
type - The plugin type.
Returns:
a List of PluginFeature for the plugin type.

getPluginFeatureListByPlugin

public java.util.List<PluginFeature> getPluginFeatureListByPlugin(java.lang.String name)
Retrieves a list of PluginFeature of the named Plugin.

Parameters:
name - The plugin name.
Returns:
a List of PluginFeature for the named plugin.

scanPath

public boolean scanPath(java.lang.String path)
Add the given path to the registry. The syntax of the path is specific to the registry. If the path has already been added, do nothing.

Parameters:
path - The path to add to the registry.
Returns:
true if the registry changed.