org.deephacks.tools4j.config.RuntimeContext Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of tools4j-config-api-runtime Show documentation
Runtime APIs of Tools4j Config
There is a newer version: 0.15.0
Show newest version
/**
 * 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.deephacks.tools4j.config;

import org.deephacks.tools4j.config.query.ConfigQuery;
import org.deephacks.tools4j.config.query.ConfigQueryBuilder;

import java.util.List;

/**
 * 
 * Central interface for providing configuration to applications.
 * 

 * Applications use this interface for registering {@link Config} classes with this runtime context
 * in order to make them visible and available for provisioning in an administrative context. Configuration
 * instances should not be cached, unless applications have very specific caching needs.
 * 
 *
 * @author Kristoffer Sjogren
 */
public abstract class RuntimeContext {
    private static final String CORE_IMPL = "org.deephacks.tools4j.config.internal.core.runtime.RuntimeCoreContext";

    private static RuntimeContext ctx;

    protected RuntimeContext() {
        // only core should implement this class
        if (!getClass().getName().equals(CORE_IMPL)) {
            throw new IllegalArgumentException("Only RuntimeCoreContext is allowed to"
                    + "implement this interface.");
        }
    }

    /**
     * @return the runtime context.
     */
    public static synchronized RuntimeContext get() {
        if (ctx != null) {
            return ctx;
        }
        try {
            ctx = (RuntimeContext) Class.forName(CORE_IMPL).newInstance();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
        return ctx;
    }

    /**
     * Register a configurable class and make it visible and available for provisioning in
     * an administrative context.
     *
     * 
     * If the same class is registered multiple times, the former class is
     * simply replaced (upgraded).
     * 

     * Be cautious of registering a new version of a class that is not compatible with
     * earlier versions of data of the same class.
     * 
     *
     * @param configurable {@link Config} classes.
     */
    public abstract void register(final Class... configurable);

    /**
     * Register default configurable instances.
     *
     * Each default instance must have a unique id.
     *
     * Schema must registered before any default instances can be registered.
     *
     * @param instances {@link Config} instances.
     */
    public abstract void registerDefault(final Object... instances);

    /**
     * Remove a configurable class. This will make the schema unavailable for provisioning
     * in an administrative context.
     * 
     * Data will never be removed when unregistering a configurable class.
     * 
     *
     * @param configurable {@link Config} classes.
     */
    public abstract void unregister(final Class... configurable);

    /**
     * Read a singleton instance. This requires the configurable to have a
     * static final {@link Id} with a default value assigned.
     *
     * 
     * Trying to read instances that are not singletons will result in an error.
     * 
     *
     * @param configurable {@link Config} class.
     * @return The singleton instance of {@link Config} T class.
     */
    public abstract  T singleton(final Class configurable);

    /**
     * Fetch all instances of the same type. All references and properties
     * will be traversed and fecthed eagerly.
     *
     * @param configurable {@link Config} class.
     * @return all instances of {@link Config} T class.
     */
    public abstract  List all(final Class configurable);

    /**
     * Get a specific instance with respect to its {@link Id}. All references
     * and properties will be traversed and fecthed eagerly.
     *
     * @param id of the instance as specfied by {@link Id}.
     *
     * @param configurable {@link Config} class.
     * @return an instance of {@link Config} T class.
     */
    public abstract  T get(final String id, final Class configurable);

    /**
     * Create a new query used for retrieving configurable instances using
     * flexible composition of Criterion objects.
     *
     * In order to use queries, a cache manager must be available and each field that
     * is queried must be {@link Index} annotated.
     *
     * This feature is currently experimental and must be turned on by setting
     * System Property 'config.query.enabled' to true.
     *
     * @see {@link ConfigQueryBuilder}
     *
     * @param configurable {@link Config} class.
     * @param  Configurable type
     * @return Used for composing a query in conjuction with {@link ConfigQueryBuilder}.
     */
    public abstract  ConfigQuery newQuery(final Class configurable);

}