org.gjt.sp.jedit

## Class ServiceManager

- java.lang.Object
- - org.gjt.sp.jedit.ServiceManager

-     public class ServiceManager
      extends java.lang.Object

  A generic way for plugins (and core) to provide various API extensions.

  Services are loaded from files named `services.xml` inside the plugin JAR. A service definition file has the following form:

      <?xml version="1.0"?>
      <!DOCTYPE SERVICES SYSTEM "services.dtd">
      <SERVICES>
          <SERVICE NAME="service name" CLASS="fully qualified class name">
              // BeanShell code evaluated when the sevice is first activated
          </SERVICE>
      </SERVICES>

  The following elements are valid:
  - `SERVICES` is the top-level element and refers to the set of services offered by the plugin.
  - A `SERVICE` contains the factory method for this service singleton. The ServiceManager manages named singletons created from these factory methods. It has two attributes, both required: `NAME` and `CLASS`. The `CLASS` attribute must be the name of a known sevice type; see below.
  - A `SERVICE` element should the BeanShell code that returns a new instance of the named class. Note that this code can return `null`.
  To see all of the services offered by jEdit core, see jEdit's `services.xml` file. Some core services are listed below:
  - `FoldHandler`
  - `FoldPainter`
  - `VFS`
  - `Encoding`
  - `EncodingDetector`
  - `StatusWidgetFactory`
  - `DockingFrameworkProvider`
  - `JEditTrayIcon`
  Plugins may define/provide more, so the only way to see a complete list of service types currently in use is by calling `getServiceTypes()`.
  To use a service from a plugin, add a piece of code somewhere that calls `getServiceNames(String)` and `getService(String,String)`.
  Since:
    jEdit 4.2pre1
  See Also:
    `BeanShell`, `PluginJAR`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ServiceManager.ServiceFoldHandlerProvider` A FoldHandler based on the ServiceManager

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ServiceManager()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <E> E` | `getService(java.lang.Class<E> clazz, java.lang.String name)` Returns an instance of the given service.
    `static java.lang.Object` | `getService(java.lang.String clazz, java.lang.String name)` Returns an instance of the given service.
    `static java.lang.String[]` | `getServiceNames(java.lang.Class clazz)`
    `static java.lang.String[]` | `getServiceNames(java.lang.String clazz)` Returns the names of all registered services with the given class.
    `static java.lang.String[]` | `getServiceTypes()` Returns all known service class types.
    `static void` | `loadServices(PluginJAR plugin, java.net.URL uri, PluginJAR.PluginCacheEntry cache)` Loads a `services.xml` file.
    `static void` | `registerService(java.lang.String clazz, java.lang.String name, java.lang.String code, PluginJAR plugin)` Registers a service.
    `static void` | `unloadServices(PluginJAR plugin)` Removes all services belonging to the specified plugin.
    `static void` | `unregisterService(java.lang.String clazz, java.lang.String name)` Unregisters a service.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ServiceManager

          public ServiceManager()

  - ### Method Detail

    - #### loadServices

          public static void loadServices(PluginJAR plugin,
                          java.net.URL uri,
                          PluginJAR.PluginCacheEntry cache)

      Loads a `services.xml` file.
      Since:
        jEdit 4.2pre1

    - #### unloadServices

          public static void unloadServices(PluginJAR plugin)

      Removes all services belonging to the specified plugin.
      Parameters:
        `plugin` - The plugin
      Since:
        jEdit 4.2pre1

    - #### registerService

          public static void registerService(java.lang.String clazz,
                             java.lang.String name,
                             java.lang.String code,
                             PluginJAR plugin)

      Registers a service. Plugins should provide a `services.xml` file instead of calling this directly.
      Parameters:
        `clazz` - The service class
        `name` - The service name
        `code` - BeanShell code to create an instance of this
        `plugin` - The plugin JAR, or null if this is a built-in service
      Since:
        jEdit 4.2pre1

    - #### unregisterService

          public static void unregisterService(java.lang.String clazz,
                               java.lang.String name)

      Unregisters a service.
      Parameters:
        `clazz` - The service class
        `name` - The service name
      Since:
        jEdit 4.2pre1

    - #### getServiceTypes

          public static java.lang.String[] getServiceTypes()

      Returns all known service class types.
      Since:
        jEdit 4.2pre1

    - #### getServiceNames

          public static java.lang.String[] getServiceNames(java.lang.String clazz)

      Returns the names of all registered services with the given class. For example, calling this with a parameter of "org.gjt.sp.jedit.io.VFS" returns all known virtual file systems.
      Parameters:
        `clazz` - The class name
      Since:
        jEdit 4.2pre1

    - #### getServiceNames

          public static java.lang.String[] getServiceNames(java.lang.Class clazz)

    - #### getService

          public static java.lang.Object getService(java.lang.String clazz,
                                    java.lang.String name)

      Returns an instance of the given service. The first time this is called for a given service, the BeanShell code is evaluated. The result is cached for future invocations, so in effect services are singletons.
      Parameters:
        `clazz` - The service class
        `name` - The service name
      Since:
        jEdit 4.2pre1

    - #### getService

          public static <E> E getService(java.lang.Class<E> clazz,
                         java.lang.String name)

      Returns an instance of the given service. The first time this is called for a given service, the BeanShell code is evaluated. The result is cached for future invocations, so in effect services are singletons.
      Parameters:
        `clazz` - The service class
        `name` - The service name
      Returns:
        the service instance
      Since:
        jEdit 4.4pre1