ServiceEnvironment.java

Go to the documentation of this file.

/* Copyright 2010, Object Management Group, Inc.
 * Copyright 2010, PrismTech, Inc.
 * Copyright 2010, Real-Time Innovations, Inc.
 * All rights reserved.
 *
 * Licensed 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.omg.dds.core;

import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.TimeUnit;

import org.omg.dds.core.policy.PolicyFactory;
import org.omg.dds.core.status.Status;
import org.omg.dds.domain.DomainParticipantFactory;
import org.omg.dds.type.TypeSupport;
import org.omg.dds.type.builtin.KeyedBytes;
import org.omg.dds.type.builtin.KeyedString;
import org.omg.dds.type.dynamic.DynamicDataFactory;
import org.omg.dds.type.dynamic.DynamicTypeFactory;


public abstract class ServiceEnvironment implements DDSObject {
    // -----------------------------------------------------------------------
    // Public Fields
    // -----------------------------------------------------------------------

    public static final String IMPLEMENTATION_CLASS_NAME_PROPERTY =
        "org.omg.dds.serviceClassName";



    // -----------------------------------------------------------------------
    // Private Fields
    // -----------------------------------------------------------------------

    private static final String ERROR_STRING =
        "Unable to load OMG DDS implementation. ";



    // -----------------------------------------------------------------------
    // Object Life Cycle
    // -----------------------------------------------------------------------

    public static ServiceEnvironment createInstance(
            ClassLoader classLoader)
    {
        return createInstance(
                IMPLEMENTATION_CLASS_NAME_PROPERTY,
                null,
                classLoader);
    }


    public static ServiceEnvironment createInstance(
            String implClassNameProperty,
            Map<String, Object> environment,
            ClassLoader classLoader)
    {
        // --- Get implementation class name --- //
        /* System.getProperty checks the implClassNameProperty argument as
         * described in the specification for this method and throws
         * NullPointerException or IllegalArgumentException if necessary.
         */
        String className = System.getProperty(implClassNameProperty);
        if (className == null || className.length() == 0) {
            // no implementation class name specified
            throw new ServiceConfigurationException(
                    ERROR_STRING + "Please set " +
                        implClassNameProperty + " property.");
        }

        try {
            // --- Load implementation class --- //
            if (classLoader == null) {
                classLoader = getDefaultClassLoader();
            }
            assert classLoader != null;
            /* IMPORTANT: Load class with ClassLoader.loadClass, not with
             * Class.forName. The latter provides insufficient control over
             * the class loader used and also caches class references in
             * undesirable ways, both of which can cause problems in
             * container environments such as OSGi.
             */
            Class<?> ctxClass = classLoader.loadClass(className);

            // --- Instantiate new object --- //
            try {
                // First, try a constructor that will accept the environment.
                Constructor<?> ctor = ctxClass.getConstructor(Map.class);
                return (ServiceEnvironment) ctor.newInstance(environment);
            } catch (NoSuchMethodException nsmx) {
                /* No Map constructor found; try a no-argument constructor
                 * instead.
                 *
                 * Get the constructor and call it explicitly rather than
                 * calling Class.newInstance(). The latter propagates all
                 * exceptions, even checked ones, complicating error handling
                 * for us and the user.
                 */
                Constructor<?> ctor = ctxClass.getConstructor(
                        (Class<?>[]) null);
                return (ServiceEnvironment) ctor.newInstance((Object[]) null);
            }

            // --- Initialization problems --- //
        } catch (ExceptionInInitializerError initx) {
            // Presumably thrown by ClassLoader.loadClass, but not documented.
            // Thrown by Constructor.newInstance.
            throw new ServiceInitializationException(
                    ERROR_STRING + "Error during static initialization.",
                    initx.getCause());
        } catch (InvocationTargetException itx) {
            // Thrown by Constructor.newInstance
            throw new ServiceInitializationException(
                    ERROR_STRING + "Error during object initialization.",
                    itx.getCause());

            // --- Configuration problems --- //
        } catch (ClassNotFoundException cnfx) {
            // Thrown by ClassLoader.loadClass.
            throw new ServiceConfigurationException(
                    ERROR_STRING + className + " was not found.",
                    cnfx);
        } catch (LinkageError linkx) {
            // Presumably thrown by ClassLoader.loadClass, but not documented.
            throw new ServiceConfigurationException(
                    ERROR_STRING + className + " could not be loaded.",
                    linkx);
        } catch (NoSuchMethodException nsmx) {
            // Thrown by Class.getConstructor: no no-argument constructor
            throw new ServiceConfigurationException(
                    ERROR_STRING + className +
                        " has no appropriate constructor.",
                    nsmx);
        } catch (IllegalAccessException iax) {
            // Thrown by Constructor.newInstance
            throw new ServiceConfigurationException(
                    ERROR_STRING + className +
                        " has no appropriate constructor.",
                    iax);
        } catch (InstantiationException ix) {
            // Thrown by Constructor.newInstance
            throw new ServiceConfigurationException(
                    ERROR_STRING + className + " could not be instantiated.",
                    ix);
        } catch (SecurityException sx) {
            // Thrown by Class.getConstructor.
            throw new ServiceConfigurationException(
                    ERROR_STRING + "Prevented by security manager.", sx);
        } catch (ClassCastException ccx) {
            // Thrown by type cast
            throw new ServiceConfigurationException(
                    ERROR_STRING + className +
                        " is not a ServiceEnvironment.", ccx);

            // --- Implementation problems --- //
        } catch (IllegalArgumentException argx) {
            /* Thrown by Constructor.newInstance to indicate that formal
             * parameters and provided arguments are not compatible. Since
             * the constructor doesn't take any arguments, and we didn't
             * provide any, we shouldn't be able to get here.
             */
            throw new AssertionError(argx);
        }
        /* If any other RuntimeException or Error gets thrown above, it's
         * either a bug in the implementation of this method or an
         * undocumented behavior of the Java standard library. In either
         * case, there's not much we can do about it, so let the exception
         * propagate up the call stack as-is.
         */
    }

    // -----------------------------------------------------------------------
    // Instance Methods
    // -----------------------------------------------------------------------

    public abstract ServiceProviderInterface getSPI();


    // --- From DDSObject: ---------------------------------------------------

    @Override
    public final ServiceEnvironment getEnvironment() {
        return this;
    }


    // --- Private methods: --------------------------------------------------

    private static ClassLoader getDefaultClassLoader() {
        // --- Get class loader from this class --- //
        ClassLoader classLoader =
                ServiceEnvironment.class.getClassLoader();
        if (classLoader != null) {
            return classLoader;
        }

        // --- Fallback: get system class loader --- //
        /* The class loader is probably the bootstrap class loader, which is
         * not directly accessible. Substitute the system class loader if
         * possible.
         */
        try {
            classLoader = ClassLoader.getSystemClassLoader();
        } catch (SecurityException sx) {
            throw new ServiceConfigurationException(
                    ERROR_STRING + "Prevented by security manager.",
                    sx);
        } catch (IllegalStateException isx) {
            /* The documentation for ClassLoader.getSystemClassLoader()
             * says this is thrown if the system class loader tries to
             * instantiate itself recursively. This situation should not
             * occur unless a custom system class loader is injected
             * which uses DDS.
             */
            throw new ServiceConfigurationException(
                    ERROR_STRING +
                        "Circular system class loader dependencies.",
                    isx);
        } catch (Error err) {
            /* The documentation for ClassLoader.getSystemClassLoader() says
             * this is thrown if the system class loader cannot be
             * reflectively instantiated.
             */
            throw new ServiceConfigurationException(
                    ERROR_STRING +
                        "System class loader could not be initialized.",
                    err.getCause());
        }

        // --- Check for null return result --- //
        /* The documentation for ClassLoader.getSystemClassLoader() says that
         * the method may return null if there is no system class loader.
         * However, it doesn't say why that would be the case.
         *
         * Do this check outside of the try/catch above to make sure that
         * no exceptions thrown below will be handled incorrectly. The
         * exception handling logic above is closely tied to the documented
         * behavior of ClassLoader.getSystemClassLoader().
         */
        if (classLoader == null) {
            throw new ServiceConfigurationException(
                    ERROR_STRING + "No system class loader available.");
        }
        return classLoader;
    }

    // -----------------------------------------------------------------------
    // Service-Provider Interface
    // -----------------------------------------------------------------------

    public static interface ServiceProviderInterface {
        // --- Singleton factories: ------------------------------------------

        public DomainParticipantFactory getParticipantFactory();

        public DynamicTypeFactory getTypeFactory();


        // --- Types: --------------------------------------------------------

        public <TYPE> TypeSupport<TYPE> newTypeSupport(
                Class<TYPE> type, String registeredName);


        // --- Time & Duration: ----------------------------------------------

        public Duration newDuration(long duration, TimeUnit unit);

        public Duration infiniteDuration();

        public Duration zeroDuration();

        public ModifiableTime newTime(long time, TimeUnit units);

        public Time invalidTime();


        // --- Instance handle: ----------------------------------------------

        public InstanceHandle nilHandle();


        // --- Conditions & WaitSet: -----------------------------------------

        public GuardCondition newGuardCondition();

        public WaitSet newWaitSet();

        // --- Status: -------------------------------------------------------

        public Set<Class<? extends Status>> allStatusKinds();

        public Set<Class<? extends Status>> noStatusKinds();

        // --- QoS Provider --------------------------------------------------
        public abstract QosProvider newQosProvider(String uri, String profile);

        // --- PolicyFactory -----------------------------------------------------

        public abstract PolicyFactory getPolicyFactory();

        public abstract DynamicDataFactory getDynamicDataFactory();

        // --- Built-in Types -----------------------------------------------------

        public abstract KeyedString newKeyedString();

        public abstract KeyedBytes newKeyedBytes();
    }
}