Package org.apache.axiom.om

# Class OMAbstractFactory

java.lang.Object
org.apache.axiom.om.OMAbstractFactory

public class OMAbstractFactory extends Object
Provides instances for object model and meta factories.

The `getMetaFactory()` method returns the `OMMetaFactory` instance for the default Axiom implementation. The `getMetaFactory(String)` method locates a `OMMetaFactory` instance for an Axiom implementation with a given feature. The following features are predefined by the Axiom API:

`FEATURE_DEFAULT`
  Identifies the default Axiom implementation. An implementation with that feature is expected to provide a full implementation of the Axiom API.
`FEATURE_DOM`
  Used by Axiom implementations that implement DOM in addition to the Axiom API.

Implementations may define other custom features.

Axiom discovers implementations by looking for `META-INF/axiom.xml` resources. They specify the `OMMetaFactory` implementation as well as the set of features that each implementation supports. If multiple implementations with the same feature are found, then Axiom will select the one with the highest priority. The priority for a given feature is also declared in `META-INF/axiom.xml`. This algorithm is used both in non OSGi and OSGi environments.

In a non OSGi environment, the default Axiom implementation can be overridden using the system property specified by `META_FACTORY_NAME_PROPERTY`.

The `getOMFactory()`, `getSOAP11Factory()` and `getSOAP12Factory()` methods return default instances for plain XML, SOAP 1.1 and SOAP 1.2 object model factories. They are convenience methods calling `getMetaFactory()` and then delegating to the returned `OMMetaFactory`.

Note that while `getMetaFactory()` always returns the same instance, the other methods may return new instances on every invocation, depending on the `OMMetaFactory` implementation.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `FEATURE_DEFAULT`
  Feature for Axiom implementations that can be used as default implementations.
  `static final String`
  `FEATURE_DOM`
  Feature for Axiom implementations that implement DOM in addition to the Axiom API.
  `static final String`
  `META_FACTORY_NAME_PROPERTY`
  The name of the system property that allows to override the default Axiom implementation.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static OMMetaFactory`
  `getMetaFactory()`
  Get the meta factory instance for the default Axiom implementation.
  `static OMMetaFactory`
  `getMetaFactory(String feature)`
  Get the meta factory instance for the Axiom implementation with a given feature.
  `static OMFactory`
  `getOMFactory()`
  Get the default OM factory instance.
  `static SOAPFactory`
  `getSOAP11Factory()`
  Get the default SOAP 1.1 OM factory instance.
  `static SOAPFactory`
  `getSOAP12Factory()`
  Get the default SOAP 1.2 OM factory instance.
  `static void`
  `setMetaFactoryLocator(OMMetaFactoryLocator locator)`
  Explicitly set a meta factory locator.

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

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

- ## Field Details

  - ### META_FACTORY_NAME_PROPERTY

    public static final String META_FACTORY_NAME_PROPERTY
    The name of the system property that allows to override the default Axiom implementation. The value must be the fully qualified name of a class implementing `OMMetaFactory` and that is visible to the class loader from which the `axiom-api` library is loaded. An instance of this class will be returned by `getMetaFactory()`.

    Note that this system property is not supported in an OSGi environment.

    See Also:
      - Constant Field Values

  - ### FEATURE_DEFAULT

    public static final String FEATURE_DEFAULT
    Feature for Axiom implementations that can be used as default implementations.
    See Also:
      - Constant Field Values

  - ### FEATURE_DOM

    public static final String FEATURE_DOM
    Feature for Axiom implementations that implement DOM in addition to the Axiom API. The `OMMetaFactory` for such an Axiom implementation must implement `DOMMetaFactory`. See the documentation of `DOMMetaFactory` for more information about the requirements and constraints that apply to Axiom implementations that support this feature.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### setMetaFactoryLocator

    public static void setMetaFactoryLocator(OMMetaFactoryLocator locator)
    Explicitly set a meta factory locator. The new locator will be used by all subsequent calls to `getMetaFactory()` and `getMetaFactory(String)` to locate the appropriate meta factory. Note that the meta factory locator is an application wide setting. More precisely, the configured locator will be used by all classes loaded from the class loader where Axiom is deployed and all its child class loaders. Therefore this method should be used with care and only be invoked during the initialization of the application.

    When Axiom is deployed as a bundle in an OSGi environment, this method will be used to inject the meta factory instances from the deployed implementation bundles.

    Parameters:
      `locator` - the new meta factory locator, or `null` to revert to the default meta factory locator

  - ### getMetaFactory

    public static OMMetaFactory getMetaFactory()
    Get the meta factory instance for the default Axiom implementation. This method is equivalent to `getMetaFactory(String)` with `FEATURE_DEFAULT` as parameter.
    Returns:
      the meta factory instance for the default Axiom implementation
    Throws:
      `OMException` - if no Axiom implementation with `FEATURE_DEFAULT` could be located

  - ### getMetaFactory

    public static OMMetaFactory getMetaFactory(String feature)
    Get the meta factory instance for the Axiom implementation with a given feature. If multiple Axiom implementations declare the same feature, then the method will return the meta factory for the implementation that declares the highest priority for that feature in its `META-INF/axiom.xml` descriptor.
    Parameters:
      `feature` - the requested feature
    Returns:
      the meta factory instance for the Axiom implementation with the given feature.
    Throws:
      `OMException` - if no Axiom implementation with the requested feature could be located

  - ### getOMFactory

    public static OMFactory getOMFactory()
    Get the default OM factory instance. This method has the same effect as calling `OMMetaFactory.getOMFactory()` on the `OMMetaFactory` instance returned by `getMetaFactory()`.
    Returns:
      the default OM factory instance
    Throws:
      `OMException` - if the factory's implementation class can't be found or if the class can't be instantiated

  - ### getSOAP11Factory

    public static SOAPFactory getSOAP11Factory()
    Get the default SOAP 1.1 OM factory instance. This method has the same effect as calling `OMMetaFactory.getSOAP11Factory()` on the `OMMetaFactory` instance returned by `getMetaFactory()`.
    Returns:
      the default SOAP 1.1 OM factory instance
    Throws:
      `OMException` - if the factory's implementation class can't be found or if the class can't be instantiated

  - ### getSOAP12Factory

    public static SOAPFactory getSOAP12Factory()
    Get the default SOAP 1.2 OM factory instance. This method has the same effect as calling `OMMetaFactory.getSOAP12Factory()` on the `OMMetaFactory` instance returned by `getMetaFactory()`.
    Returns:
      the default SOAP 1.2 OM factory instance
    Throws:
      `OMException` - if the factory's implementation class can't be found or if the class can't be instantiated