OSGi 8.1.0 · org.osgi.util.xml.XMLParserActivator · APIdia, the JavaDoc alternative

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

Modifier and Type	Field and Description
private volatile BundleContext	bundleContext Context of this bundle
public static final String	DOMCLASSFILE Fully qualified path name of DOM Parser Factory Class Name file
private static final String	DOMFACTORYDESCRIPTION DOM Factory Service Description
public static final String	DOMFACTORYNAME Filename containing the DOM Parser Factory Class name.
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
public static final String	PARSER_NAMESPACEAWARE Service property specifying if factory is configured to support namespace aware parsers.
public static final String	PARSER_VALIDATING Service property specifying if factory is configured to support validating parsers.
private static final String	PARSERCLASSFILEPATH Path to the factory class name files
public static final String	SAXCLASSFILE Fully qualified path name of SAX Parser Factory Class Name file
private static final String	SAXFACTORYDESCRIPTION SAX Factory Service Description
public static final String	SAXFACTORYNAME Filename containing the SAX Parser Factory Class name.

Constructor Summary

Access	Constructor and Description
public	XMLParserActivator()

Method Summary

Modifier and Type	Method and Description
private Object	Returns: a parserFactoryClass Object getFactory(String A `String` object containing the name of the parser factory class parserFactoryClassName) Given a parser factory class name, instantiate that class.
private List<String>	Returns: A List of strings containing the parser class names. getParserFactoryClassNames(URL The URL of the service file containing the parser class names parserUrl) Given the URL for a file, reads and returns the parser class names.
public Object	Returns: A new, configured XML Parser Factory object or null if a configuration error was encountered getService(Bundle The bundle using the service. bundle, ServiceRegistration<Object> The `ServiceRegistration` object for the service. registration) Implements org.osgi.framework.ServiceFactory.getService. Creates a new XML Parser Factory object.
private void	registerDOMParsers(List<String> - a `List` of `String` objects containing the names of the parser Factory Classes parserFactoryClassNames) Register DOM Parser Factory Services with the framework.
private void	registerSAXParsers(List<String> - a `List` of `String` objects containing the names of the parser Factory Classes parserFactoryClassNames) Register SAX Parser Factory Services with the framework.
private void	setDefaultDOMProperties(DocumentBuilderFactory The `DocumentBuilderFactory` object factory, Hashtable<String, Object> `Hashtable` of service properties. props, int index) Set the DOM parser service properties.
private void	setDefaultSAXProperties(SAXParserFactory The `SAXParserFactory` object factory, Hashtable<String, Object> `Hashtable` of service properties. props, int index) Set the SAX Parser Service Properties.
public void	setDOMProperties(DocumentBuilderFactory - the DocumentBuilderFactory object factory, Hashtable<String, Object> - Hashtable of service properties. props) Set the customizable DOM Parser Service Properties.
public void	setSAXProperties(SAXParserFactory - the SAXParserFactory object factory, Hashtable<String, Object> - the properties object for the service properties) Set the customizable SAX Parser Service Properties.
public void	start(BundleContext The execution context of the bundle being started. context) Implements org.osgi.framework.BundleActivator.start. Called when this bundle is started so the Framework can perform the bundle-specific activities necessary to start this bundle.
public void	stop(BundleContext The execution context of the bundle being stopped. context) Implements org.osgi.framework.BundleActivator.stop. This method has nothing to do as all active service registrations will automatically get unregistered when the bundle stops.
public void	ungetService(Bundle The bundle releasing the service. bundle, ServiceRegistration<Object> The `ServiceRegistration` object for the service. registration, Object The XML Parser Factory object returned by a previous call to the `getService` method. service) Implements org.osgi.framework.ServiceFactory.ungetService. Releases a XML Parser Factory object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

bundleContext	back to summary
private volatile BundleContext bundleContext Context of this bundle

DOMCLASSFILE	back to summary
public static final String DOMCLASSFILE Fully qualified path name of DOM Parser Factory Class Name file

DOMFACTORYDESCRIPTION	back to summary
private static final String DOMFACTORYDESCRIPTION DOM Factory Service Description

DOMFACTORYNAME	back to summary
public static final String DOMFACTORYNAME Filename containing the DOM Parser Factory Class name. Also used as the basis for the `SERVICE_PID` registration property.

FACTORYNAMEKEY	back to summary
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

PARSER_NAMESPACEAWARE	back to summary
public static final String PARSER_NAMESPACEAWARE Service property specifying if factory is configured to support namespace aware parsers. The value is of type `Boolean`.

PARSER_VALIDATING	back to summary
public static final String PARSER_VALIDATING Service property specifying if factory is configured to support validating parsers. The value is of type `Boolean`.

PARSERCLASSFILEPATH	back to summary
private static final String PARSERCLASSFILEPATH Path to the factory class name files

SAXCLASSFILE	back to summary
public static final String SAXCLASSFILE Fully qualified path name of SAX Parser Factory Class Name file

SAXFACTORYDESCRIPTION	back to summary
private static final String SAXFACTORYDESCRIPTION SAX Factory Service Description

SAXFACTORYNAME	back to summary
public static final String SAXFACTORYNAME Filename containing the SAX Parser Factory Class name. Also used as the basis for the `SERVICE_PID` registration property.

Constructor Detail

XMLParserActivator	back to summary
public XMLParserActivator()

Method Detail

getFactory back to summary

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

private Object getFactory(String parserFactoryClassName) throws FactoryConfigurationError

Given a parser factory class name, instantiate that class.

Parameters

parserFactoryClassName:String: A String object containing the name of the parser factory class

Returns:Object

a parserFactoryClass Object

getParserFactoryClassNames	back to summary
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:URL The URL of the service file containing the parser class names Returns:List<String> A List of strings containing the parser class names. Exceptions IOException: if there is a problem reading the URL input stream

getParserFactoryClassNames

back to summary

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:URL: The URL of the service file containing the parser class names

Returns:List<String>

A List of strings containing the parser class names.

Exceptions

IOException:: if there is a problem reading the URL input stream

getService back to summary

getService	back to summary
public Object getService(Bundle bundle, ServiceRegistration<Object> registration) Implements org.osgi.framework.ServiceFactory.getService. 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. Parameters bundle:Bundle The bundle using the service. registration:ServiceRegistration<Object> The `ServiceRegistration` object for the service. Returns:Object A new, configured XML Parser Factory object or null if a configuration error was encountered Annotations @Override

public Object getService(Bundle bundle, ServiceRegistration<Object> registration)

Implements org.osgi.framework.ServiceFactory.getService.

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.

Parameters

bundle:Bundle: The bundle using the service.
registration:ServiceRegistration<Object>: The ServiceRegistration object for the service.

Returns:Object

A new, configured XML Parser Factory object or null if a configuration error was encountered

Annotations

@Override

registerDOMParsers back to summary

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

private void registerDOMParsers(List<String> parserFactoryClassNames) throws FactoryConfigurationError

Parameters

parserFactoryClassNames:List<String>: - a List of String objects containing the names of the parser Factory Classes

Exceptions

FactoryConfigurationError:: if thrown from getFactory

registerSAXParsers back to summary

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

private void registerSAXParsers(List<String> parserFactoryClassNames) throws FactoryConfigurationError

Parameters

parserFactoryClassNames:List<String>: - a List of String objects containing the names of the parser Factory Classes

Exceptions

FactoryConfigurationError:: if thrown from getFactory

setDefaultDOMProperties back to summary

setDefaultDOMProperties	back to summary
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:DocumentBuilderFactory The `DocumentBuilderFactory` object props:Hashtable<String, Object> `Hashtable` of service properties.

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:DocumentBuilderFactory: The DocumentBuilderFactory object
props:Hashtable<String, Object>: Hashtable of service properties.

setDefaultSAXProperties back to summary

setDefaultSAXProperties	back to summary
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:SAXParserFactory The `SAXParserFactory` object props:Hashtable<String, Object> `Hashtable` of service properties.

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:SAXParserFactory: The SAXParserFactory object
props:Hashtable<String, Object>: Hashtable of service properties.

setDOMProperties	back to summary
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:DocumentBuilderFactory - the DocumentBuilderFactory object props:Hashtable<String, Object> - Hashtable of service properties.

setDOMProperties

back to summary

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:DocumentBuilderFactory: - the DocumentBuilderFactory object
props:Hashtable<String, Object>: - Hashtable of service properties.

setSAXProperties	back to summary
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:SAXParserFactory - the SAXParserFactory object properties:Hashtable<String, Object> - the properties object for the service

setSAXProperties

back to summary

public void setSAXProperties(SAXParserFactory factory, Hashtable<String, Object> properties)

Set the customizable SAX Parser Service Properties.

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:SAXParserFactory: - the SAXParserFactory object
properties:Hashtable<String, Object>: - the properties object for the service

start	back to summary
public void start(BundleContext context) throws Exception Implements org.osgi.framework.BundleActivator.start. 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. Parameters context:BundleContext The execution context of the bundle being started. Annotations @Override Exceptions 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.

start

back to summary

public void start(BundleContext context) throws Exception

Implements org.osgi.framework.BundleActivator.start.

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.

Parameters

context:BundleContext: The execution context of the bundle being started.

Annotations

@Override

Exceptions

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	back to summary
public void stop(BundleContext context) throws Exception Implements org.osgi.framework.BundleActivator.stop. This method has nothing to do as all active service registrations will automatically get unregistered when the bundle stops. Parameters context:BundleContext The execution context of the bundle being stopped. Annotations @Override Exceptions 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.

stop

back to summary

public void stop(BundleContext context) throws Exception

Implements org.osgi.framework.BundleActivator.stop.

This method has nothing to do as all active service registrations will automatically get unregistered when the bundle stops.

Parameters

context:BundleContext: The execution context of the bundle being stopped.

Annotations

@Override

Exceptions

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.

ungetService back to summary

ungetService	back to summary
public void ungetService(Bundle bundle, ServiceRegistration<Object> registration, Object service) Implements org.osgi.framework.ServiceFactory.ungetService. Releases a XML Parser Factory object. Parameters bundle:Bundle The bundle releasing the service. registration:ServiceRegistration<Object> The `ServiceRegistration` object for the service. service:Object The XML Parser Factory object returned by a previous call to the `getService` method. Annotations @Override

public void ungetService(Bundle bundle, ServiceRegistration<Object> registration, Object service)

Implements org.osgi.framework.ServiceFactory.ungetService.

Releases a XML Parser Factory object.

Parameters

bundle:Bundle: The bundle releasing the service.
registration:ServiceRegistration<Object>: The ServiceRegistration object for the service.
service:Object: The XML Parser Factory object returned by a previous call to the getService method.

Annotations

@Override

public Class XMLParserActivator

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail