org.apache.axiom.om.OMAbstractFactory Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.axiom.om;
import org.apache.axiom.om.dom.DOMMetaFactory;
import org.apache.axiom.soap.SOAPFactory;
/**
* Provides instances for object model and meta factories.
*
* The {@link #getMetaFactory()} method returns the {@link OMMetaFactory} instance for the default
* Axiom implementation. The {@link #getMetaFactory(String)} method locates a {@link OMMetaFactory}
* instance for an Axiom implementation with a given feature. The following features are predefined
* by the Axiom API:
*
* - {@link #FEATURE_DEFAULT}
*
- Identifies the default Axiom implementation. An implementation with that feature is expected
* to provide a full implementation of the Axiom API.
*
- {@link #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 {@code META-INF/axiom.xml} resources. They
* specify the {@link 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 {@code 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 {@link #META_FACTORY_NAME_PROPERTY}.
*
* The {@link #getOMFactory()}, {@link #getSOAP11Factory()} and {@link #getSOAP12Factory()}
* methods return default instances for plain XML, SOAP 1.1 and SOAP 1.2 object model factories.
* They are convenience methods calling {@link #getMetaFactory()} and then delegating to the
* returned {@link OMMetaFactory}.
*
* Note that while {@link #getMetaFactory()} always returns the same instance, the other methods
* may return new instances on every invocation, depending on the {@link OMMetaFactory}
* implementation.
*/
public class OMAbstractFactory {
/**
* 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 {@link OMMetaFactory} and that
* is visible to the class loader from which the {@code axiom-api} library is loaded. An
* instance of this class will be returned by {@link #getMetaFactory()}.
*
* Note that this system property is not supported in an OSGi environment.
*/
public static final String META_FACTORY_NAME_PROPERTY = "org.apache.axiom.om.OMMetaFactory";
/**
* Feature for Axiom implementations that can be used as default implementations.
*/
public static final String FEATURE_DEFAULT = "default";
/**
* Feature for Axiom implementations that implement DOM in addition to the Axiom API. The
* {@link OMMetaFactory} for such an Axiom implementation must implement {@link DOMMetaFactory}.
* See the documentation of {@link DOMMetaFactory} for more information about the requirements
* and constraints that apply to Axiom implementations that support this feature.
*/
public static final String FEATURE_DOM = "dom";
private static final String DEFAULT_LOCATOR_CLASS_NAME =
"org.apache.axiom.locator.DefaultOMMetaFactoryLocator";
/**
* The default {@link OMMetaFactoryLocator} that will be used if no locator has been set
* explicitly.
*/
private static final OMMetaFactoryLocator defaultMetaFactoryLocator;
/**
* The {@link OMMetaFactoryLocator} set through
* {@link #setMetaFactoryLocator(OMMetaFactoryLocator)}. If this is null, then
* {@link #defaultMetaFactoryLocator} will be used.
*/
private static volatile OMMetaFactoryLocator metaFactoryLocator;
static {
// We could actually instantiate the default locator directly, but doing it using
// reflection avoids introducing a circular dependency between the org.apache.axiom.om
// and org.apache.axiom.locator packages.
try {
defaultMetaFactoryLocator = (OMMetaFactoryLocator)Class.forName(DEFAULT_LOCATOR_CLASS_NAME).newInstance();
} catch (InstantiationException ex) {
throw new InstantiationError(ex.getMessage());
} catch (IllegalAccessException ex) {
throw new IllegalAccessError(ex.getMessage());
} catch (ClassNotFoundException ex) {
throw new NoClassDefFoundError(ex.getMessage());
}
}
private OMAbstractFactory() {}
/**
* Explicitly set a meta factory locator. The new locator will be used by all subsequent calls
* to {@link #getMetaFactory()} and {@link #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.
*
* @param locator
* the new meta factory locator, or null to revert to the default meta
* factory locator
*/
public static void setMetaFactoryLocator(OMMetaFactoryLocator locator) {
metaFactoryLocator = locator;
}
/**
* Get the meta factory instance for the default Axiom implementation. This method is equivalent
* to {@link #getMetaFactory(String)} with {@link #FEATURE_DEFAULT} as parameter.
*
* @return the meta factory instance for the default Axiom implementation
* @throws OMException
* if no Axiom implementation with {@link #FEATURE_DEFAULT} could be located
*/
public static OMMetaFactory getMetaFactory() {
return getMetaFactory(FEATURE_DEFAULT);
}
/**
* 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
* {@code META-INF/axiom.xml} descriptor.
*
* @param feature
* the requested feature
* @return 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
*/
public static OMMetaFactory getMetaFactory(String feature) {
OMMetaFactoryLocator locator = metaFactoryLocator;
if (locator == null) {
locator = defaultMetaFactoryLocator;
}
OMMetaFactory metaFactory = locator.getOMMetaFactory(feature);
if (metaFactory == null) {
String jarHint;
if (feature.equals(FEATURE_DEFAULT)) {
jarHint = "axiom-impl.jar";
} else if (feature.equals(FEATURE_DOM)) {
jarHint = "axiom-dom.jar";
} else {
jarHint = null;
}
StringBuilder buffer = new StringBuilder();
buffer.append("No meta factory found for feature '").append(feature).append("'");
if (jarHint != null) {
buffer.append("; this usually means that ").append(jarHint)
.append(" is not in the classpath or that the META-INF/axiom.xml resource can't be read");
}
throw new OMException(buffer.toString());
} else {
return metaFactory;
}
}
/**
* Get the default OM factory instance. This method has the same effect as calling
* {@link OMMetaFactory#getOMFactory()} on the {@link OMMetaFactory} instance returned by
* {@link #getMetaFactory()}.
*
* @return 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
*/
public static OMFactory getOMFactory() {
return getMetaFactory().getOMFactory();
}
/**
* Get the default SOAP 1.1 OM factory instance. This method has the same effect as calling
* {@link OMMetaFactory#getSOAP11Factory()} on the {@link OMMetaFactory} instance returned by
* {@link #getMetaFactory()}.
*
* @return 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
*/
public static SOAPFactory getSOAP11Factory() {
return getMetaFactory().getSOAP11Factory();
}
/**
* Get the default SOAP 1.2 OM factory instance. This method has the same effect as calling
* {@link OMMetaFactory#getSOAP12Factory()} on the {@link OMMetaFactory} instance returned by
* {@link #getMetaFactory()}.
*
* @return 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
*/
public static SOAPFactory getSOAP12Factory() {
return getMetaFactory().getSOAP12Factory();
}
}