Package 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<Object>
public class XMLParserActivator extends Object implements org.osgi.framework.BundleActivator, org.osgi.framework.ServiceFactory<Object>
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:

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 Details

    • bundleContext

      private volatile org.osgi.framework.BundleContext bundleContext
      Context of this bundle

    • SAXFACTORYNAME

      public static final String SAXFACTORYNAME
      Filename containing the SAX Parser Factory Class name. Also used as the basis for the SERVICE_PID registration property.
      See Also:

    • DOMFACTORYNAME

      public static final String DOMFACTORYNAME
      Filename containing the DOM Parser Factory Class name. Also used as the basis for the SERVICE_PID registration property.
      See Also:

    • PARSERCLASSFILEPATH

      private static final String PARSERCLASSFILEPATH
      Path to the factory class name files
      See Also:

    • SAXCLASSFILE

      public static final String SAXCLASSFILE
      Fully qualified path name of SAX Parser Factory Class Name file
      See Also:

    • DOMCLASSFILE

      public static final String DOMCLASSFILE
      Fully qualified path name of DOM Parser Factory Class Name file
      See Also:

    • SAXFACTORYDESCRIPTION

      private static final String SAXFACTORYDESCRIPTION
      SAX Factory Service Description
      See Also:

    • DOMFACTORYDESCRIPTION

      private static final String DOMFACTORYDESCRIPTION
      DOM Factory Service Description
      See Also:

    • PARSER_VALIDATING

      public static final String PARSER_VALIDATING
      Service property specifying if factory is configured to support validating parsers. The value is of type Boolean.
      See Also:

    • PARSER_NAMESPACEAWARE

      public static final String PARSER_NAMESPACEAWARE
      Service property specifying if factory is configured to support namespace aware parsers. The value is of type Boolean.
      See Also:

    • FACTORYNAMEKEY

      private static final String FACTORYNAMEKEY
      Key for parser factory name property - this must be saved in the parsers properties hashtable so that the parser factory can be instantiated from a ServiceReference
      See Also:

  • Constructor Details

    • XMLParserActivator

      public XMLParserActivator()

  • Method Details

    • start

      public void start(org.osgi.framework.BundleContext context) throws 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:
      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 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:
      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.

    • getParserFactoryClassNames

      private List<String> getParserFactoryClassNames(URL parserUrl) throws IOException
      Given the URL for a file, reads and returns the parser class names. There may be multiple classes specified in this file, one per line. There may also be comment lines in the file, which begin with "#".
      Parameters:
      parserUrl - The URL of the service file containing the parser class names
      Returns:
      A List of strings containing the parser class names.
      Throws:
      IOException - if there is a problem reading the URL input stream

    • registerSAXParsers

      private void registerSAXParsers(List<String> parserFactoryClassNames) throws FactoryConfigurationError
      Register SAX Parser Factory Services with the framework.
      Parameters:
      parserFactoryClassNames - - a List of String objects containing the names of the parser Factory Classes
      Throws:
      FactoryConfigurationError - if thrown from getFactory

    • setDefaultSAXProperties

      private void setDefaultSAXProperties(SAXParserFactory factory, Hashtable<String,Object> props, int index)

      Set the SAX Parser Service Properties. By default, the following properties are set:

      • SERVICE_DESCRIPTION
      • SERVICE_PID
      • PARSER_VALIDATING- instantiates a parser and queries it to find out whether it is validating or not
      • PARSER_NAMESPACEAWARE- instantiates a parser and queries it to find out whether it is namespace aware or not
        Parameters:
        factory - The SAXParserFactory object
        props - Hashtable of service properties.

      • setSAXProperties

        public void setSAXProperties(SAXParserFactory factory, Hashtable<String,Object> 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

      • registerDOMParsers

        private void registerDOMParsers(List<String> parserFactoryClassNames) throws FactoryConfigurationError
        Register DOM Parser Factory Services with the framework.
        Parameters:
        parserFactoryClassNames - - a List of String objects containing the names of the parser Factory Classes
        Throws:
        FactoryConfigurationError - if thrown from getFactory

      • setDefaultDOMProperties

        private void setDefaultDOMProperties(DocumentBuilderFactory factory, Hashtable<String,Object> props, int index)
        Set the DOM parser service properties. By default, the following properties are set:
        • SERVICE_DESCRIPTION
        • SERVICE_PID
        • PARSER_VALIDATING
        • PARSER_NAMESPACEAWARE
          Parameters:
          factory - The DocumentBuilderFactory object
          props - Hashtable of service properties.

        • setDOMProperties

          public void setDOMProperties(DocumentBuilderFactory factory, Hashtable<String,Object> 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.

        • getFactory

          private Object getFactory(String parserFactoryClassName) throws FactoryConfigurationError
          Given a parser factory class name, instantiate that class.
          Parameters:
          parserFactoryClassName - A String object containing the name of the parser factory class
          Returns:
          a parserFactoryClass Object
          Throws:
          FactoryConfigurationError

        • getService

          public Object getService(org.osgi.framework.Bundle bundle, org.osgi.framework.ServiceRegistration<Object> 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<Object>
          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<Object> registration, Object service)
          Releases a XML Parser Factory object.
          Specified by:
          ungetService in interface org.osgi.framework.ServiceFactory<Object>
          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.