001    package org.apache.ojb.broker.util.configuration;
002    
003    /* Copyright 2002-2005 The Apache Software Foundation
004     *
005     * Licensed under the Apache License, Version 2.0 (the "License");
006     * you may not use this file except in compliance with the License.
007     * You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    
018    import org.apache.ojb.broker.util.logging.Logger;
019    
020    /**
021     * The <code>Configurator</code> interface defines methods for looking up 
022     * Configurations and for configuring <code>Configurable</code> instances.
023     * 
024     * call sequence:
025     * 1. The application obtains a <code>Configurator</code> instance (typically from a
026     * Factory).
027     * 
028     * 2. The application uses the Configurator to configure <code>Configurable</code> 
029     * instances. 
030     * The Configurator must lookup the proper <code>Configuration</code> and invoke
031     * the <code>configure</code> method on the <code>Configurable</code> instance.
032     *
033     * <pre>
034     *      // 1. obtain Configurator
035     *      Configurator configurator = OjbConfigurator.getInstance();
036     * 
037     *      // 2. ask Configurator to configure the Configurable instance
038     *      Configurable obj = ...
039     *      configurator.configure(obj);
040     * </pre>
041     *
042     * @author Thomas Mahler
043     * @version $Id: Configurator.java,v 1.1 2007-08-24 22:17:30 ewestfal Exp $
044     */
045    public interface Configurator
046    {
047    
048            /**
049             * this method allows to set a logger that tracks configuration events.
050             * @param loggerInstance the logger to set
051             */
052        public void setLogger(Logger loggerInstance);
053    
054        /**
055         * configures the <code>Configurable</code> instance target.
056         * @param target the <code>Configurable</code> instance.
057         * @throws ConfigurationException
058         */
059        public void configure(Configurable target) throws ConfigurationException;
060    
061        /**
062         * looks up the proper <code>Configuration</code> for 
063         * the <code>Configurable</code> instance target.
064         * @param target the <code>Configurable</code> instance.
065         * @return the resulting<code>Configuration</code>.
066         * @throws  ConfigurationException
067         */
068        public Configuration getConfigurationFor(Configurable target) throws ConfigurationException;
069    }