XMLParserActivator
Date: 2016-06-25

org.osgi.util.xml

## Class XMLParserActivator

- java.lang.Object
- - org.osgi.util.xml.XMLParserActivator

- All Implemented Interfaces:
    org.osgi.framework.BundleActivator, org.osgi.framework.ServiceFactory

      public class XMLParserActivator
      extends java.lang.Object
      implements org.osgi.framework.BundleActivator, org.osgi.framework.ServiceFactory

  A BundleActivator class that allows any JAXP compliant XML Parser to register itself as an OSGi parser service. Multiple JAXP compliant parsers can concurrently register by using this BundleActivator class. Bundles who wish to use an XML parser can then use the framework's service registry to locate available XML Parsers with the desired characteristics such as validating and namespace-aware.

  The services that this bundle activator enables a bundle to provide are:

  - `javax.xml.parsers.SAXParserFactory`(`SAXFACTORYNAME`)
  - `javax.xml.parsers.DocumentBuilderFactory`( `DOMFACTORYNAME` )

  The algorithm to find the implementations of the abstract parsers is derived from the JAR file specifications, specifically the Services API.

  An XMLParserActivator assumes that it can find the class file names of the factory classes in the following files:

  - `/META-INF/services/javax.xml.parsers.SAXParserFactory` is a file contained in a jar available to the runtime which contains the implementation class name(s) of the SAXParserFactory.
  - `/META-INF/services/javax.xml.parsers.DocumentBuilderFactory` is a file contained in a jar available to the runtime which contains the implementation class name(s) of the `DocumentBuilderFactory`

  If either of the files does not exist, `XMLParserActivator` assumes that the parser does not support that parser type.

  `XMLParserActivator` attempts to instantiate both the `SAXParserFactory` and the `DocumentBuilderFactory`. It registers each factory with the framework along with service properties:

  - `PARSER_VALIDATING`- indicates if this factory supports validating parsers. It's value is a `Boolean`.
  - `PARSER_NAMESPACEAWARE`- indicates if this factory supports namespace aware parsers It's value is a `Boolean`.

  Individual parser implementations may have additional features, properties, or attributes which could be used to select a parser with a filter. These can be added by extending this class and overriding the `setSAXProperties` and `setDOMProperties` methods.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DOMCLASSFILE` Fully qualified path name of DOM Parser Factory Class Name file
    `static java.lang.String` | `DOMFACTORYNAME` Filename containing the DOM Parser Factory Class name.
    `static java.lang.String` | `PARSER_NAMESPACEAWARE` Service property specifying if factory is configured to support namespace aware parsers.
    `static java.lang.String` | `PARSER_VALIDATING` Service property specifying if factory is configured to support validating parsers.
    `static java.lang.String` | `SAXCLASSFILE` Fully qualified path name of SAX Parser Factory Class Name file
    `static java.lang.String` | `SAXFACTORYNAME` Filename containing the SAX Parser Factory Class name.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XMLParserActivator()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `getService(org.osgi.framework.Bundle bundle, org.osgi.framework.ServiceRegistration registration)` Creates a new XML Parser Factory object.
    `void` | `setDOMProperties(javax.xml.parsers.DocumentBuilderFactory factory, java.util.Hashtable props)` Set the customizable DOM Parser Service Properties.
    `void` | `setSAXProperties(javax.xml.parsers.SAXParserFactory factory, java.util.Hashtable properties)` Set the customizable SAX Parser Service Properties.
    `void` | `start(org.osgi.framework.BundleContext context)` Called when this bundle is started so the Framework can perform the bundle-specific activities necessary to start this bundle.
    `void` | `stop(org.osgi.framework.BundleContext context)` This method has nothing to do as all active service registrations will automatically get unregistered when the bundle stops.
    `void` | `ungetService(org.osgi.framework.Bundle bundle, org.osgi.framework.ServiceRegistration registration, java.lang.Object service)` Releases a XML Parser Factory object.

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

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

- - ### Field Detail

    - #### SAXFACTORYNAME

          public static final java.lang.String SAXFACTORYNAME

      Filename containing the SAX Parser Factory Class name. Also used as the basis for the `SERVICE_PID` registration property.
      See Also:
        Constant Field Values

    - #### DOMFACTORYNAME

          public static final java.lang.String DOMFACTORYNAME

      Filename containing the DOM Parser Factory Class name. Also used as the basis for the `SERVICE_PID` registration property.
      See Also:
        Constant Field Values

    - #### SAXCLASSFILE

          public static final java.lang.String SAXCLASSFILE

      Fully qualified path name of SAX Parser Factory Class Name file
      See Also:
        Constant Field Values

    - #### DOMCLASSFILE

          public static final java.lang.String DOMCLASSFILE

      Fully qualified path name of DOM Parser Factory Class Name file
      See Also:
        Constant Field Values

    - #### PARSER_VALIDATING

          public static final java.lang.String PARSER_VALIDATING

      Service property specifying if factory is configured to support validating parsers. The value is of type `Boolean`.
      See Also:
        Constant Field Values

    - #### PARSER_NAMESPACEAWARE

          public static final java.lang.String PARSER_NAMESPACEAWARE

      Service property specifying if factory is configured to support namespace aware parsers. The value is of type `Boolean`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XMLParserActivator

          public XMLParserActivator()

  - ### Method Detail

    - #### start

          public void start(org.osgi.framework.BundleContext context)
                     throws java.lang.Exception

      Called when this bundle is started so the Framework can perform the bundle-specific activities necessary to start this bundle. This method can be used to register services or to allocate any resources that this bundle needs.

      This method must complete and return to its caller in a timely manner.

      This method attempts to register a SAX and DOM parser with the Framework's service registry.

      Specified by:
        `start` in interface `org.osgi.framework.BundleActivator`
      Parameters:
        `context` - The execution context of the bundle being started.
      Throws:
        `java.lang.Exception` - If this method throws an exception, this bundle is marked as stopped and the Framework will remove this bundle's listeners, unregister all services registered by this bundle, and release all services used by this bundle.

    - #### stop

          public void stop(org.osgi.framework.BundleContext context)
                    throws java.lang.Exception

      This method has nothing to do as all active service registrations will automatically get unregistered when the bundle stops.
      Specified by:
        `stop` in interface `org.osgi.framework.BundleActivator`
      Parameters:
        `context` - The execution context of the bundle being stopped.
      Throws:
        `java.lang.Exception` - If this method throws an exception, the bundle is still marked as stopped, and the Framework will remove the bundle's listeners, unregister all services registered by the bundle, and release all services used by the bundle.

    - #### setSAXProperties

          public void setSAXProperties(javax.xml.parsers.SAXParserFactory factory,
                              java.util.Hashtable properties)

      Set the customizable SAX Parser Service Properties.

      This method attempts to instantiate a validating parser and a namespace aware parser to determine if the parser can support those features. The appropriate properties are then set in the specified properties object.

      This method can be overridden to add additional SAX2 features and properties. If you want to be able to filter searches of the OSGi service registry, this method must put a key, value pair into the properties object for each feature or property. For example, properties.put("http://www.acme.com/features/foo", Boolean.TRUE);

      Parameters:
        `factory` - - the SAXParserFactory object
        `properties` - - the properties object for the service

    - #### setDOMProperties

          public void setDOMProperties(javax.xml.parsers.DocumentBuilderFactory factory,
                              java.util.Hashtable props)

      Set the customizable DOM Parser Service Properties.

      This method attempts to instantiate a validating parser and a namespace aware parser to determine if the parser can support those features. The appropriate properties are then set in the specified props object.

      This method can be overridden to add additional DOM2 features and properties. If you want to be able to filter searches of the OSGi service registry, this method must put a key, value pair into the properties object for each feature or property. For example, properties.put("http://www.acme.com/features/foo", Boolean.TRUE);

      Parameters:
        `factory` - - the DocumentBuilderFactory object
        `props` - - Hashtable of service properties.

    - #### getService

          public java.lang.Object getService(org.osgi.framework.Bundle bundle,
                                    org.osgi.framework.ServiceRegistration registration)

      Creates a new XML Parser Factory object.

      A unique XML Parser Factory object is returned for each call to this method.

      The returned XML Parser Factory object will be configured for validating and namespace aware support as specified in the service properties of the specified ServiceRegistration object. This method can be overridden to configure additional features in the returned XML Parser Factory object.

      Specified by:
        `getService` in interface `org.osgi.framework.ServiceFactory`
      Parameters:
        `bundle` - The bundle using the service.
        `registration` - The `ServiceRegistration` object for the service.
      Returns:
        A new, configured XML Parser Factory object or null if a configuration error was encountered

    - #### ungetService

          public void ungetService(org.osgi.framework.Bundle bundle,
                          org.osgi.framework.ServiceRegistration registration,
                          java.lang.Object service)

      Releases a XML Parser Factory object.
      Specified by:
        `ungetService` in interface `org.osgi.framework.ServiceFactory`
      Parameters:
        `bundle` - The bundle releasing the service.
        `registration` - The `ServiceRegistration` object for the service.
        `service` - The XML Parser Factory object returned by a previous call to the `getService` method.