org.apache.deltaspike.core.spi.config.ConfigSource 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.deltaspike.core.spi.config;

import java.util.Map;

/**
 * Implement this interfaces to provide a ConfigSource.
 * A ConfigSource provides properties from a specific place, like
 * JNDI configuration, a properties file, etc
 * 
 * The custom implementation can be 'registered' using a
 * {@link ConfigSourceProvider} or via the
 * {@link java.util.ServiceLoader} mechanism. In the later case
 * it must get registered via creating a
 * META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSource
 * file and adding the fully qualified class name of your ConfigSource
 * implementation into it. 
 */
public interface ConfigSource
{
    /**
     * The default name for the ordinal field.
     * Any ConfigSource might use it's own though or even return a hardcoded
     * in {@link #getOrdinal()}.
     */
    String DELTASPIKE_ORDINAL = "deltaspike_ordinal";
    
    /**
     * Lookup order:
     *
     * 
     *     System properties (ordinal 400)
     *     Environment properties (ordinal 300)
     *     JNDI values (ordinal 200)
     *     Properties file values (/META-INF/apache-deltaspike.properties) (ordinal 100)
     * 
     * 
     * 
Important Hints for custom implementations:
     * 
     * If a custom implementation should be invoked before the default implementations, use a value > 400
     * 
     * 
     * If a custom implementation should be invoked after the default implementations, use a value < 100
     * 
     * 
     *
     *     IMPORTANT:  Have a look at the abstract base-implementation DeltaSpike is using internally,
     *     if a custom implementation should load the ordinal value from the config-source like the default
     *     implementations provided by DeltaSpike do.
     *
     * 
     * 
     * 
Reordering of the default order of the config-sources:
     * Example: If the properties file/s should be used before the other implementations,
     * you have to configure an ordinal > 400. That means, you have to add e.g. deltaspike_ordinal=401 to
     * /META-INF/apache-deltaspike.properties . Hint: In case of property files every file is handled as independent
     * config-source, but all of them have ordinal 400 by default (and can be reordered in a fine-grained manner.
     *
     * @return the 'importance' aka ordinal of the configured values. The higher, the more important.
     */
    int getOrdinal();

    /**
     * Return properties contained in this config source.
     * @return Properties available in this config source.
     */
    Map getProperties();

    /**
     * @param key for the property
     * @return configured value or null if this ConfigSource doesn't provide any value for the given key.
     */
    String getPropertyValue(String key);

    /**
     * @return the 'name' of the configuration source, e.g. 'property-file mylocation/myproperty.properties'
     */
    String getConfigName();
    
    /**
     * Determines if this config source should be scanned for its list of properties.
     * 
     * Generally, slow ConfigSources should return false here. 
     * 
     * @return true if this ConfigSource should be scanned for its list of properties, 
     * false if it should not be scanned.
     */
    boolean isScannable(); 
}