Handler.java

/* 
 * 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.felix.ipojo;

import java.util.Dictionary;

import org.apache.felix.ipojo.architecture.ComponentTypeDescription;
import org.apache.felix.ipojo.architecture.HandlerDescription;
import org.apache.felix.ipojo.metadata.Element;
import org.apache.felix.ipojo.util.Logger;

/**
 * Handler Abstract Class.
 * A handler is a 'piece' of 
 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
 */
public abstract class Handler {

    /**
     * The handler namespace property.
     */
    public static final String HANDLER_NAMESPACE_PROPERTY = "handler.namespace";

    /**
     * The handler name property. 
     */
    public static final String HANDLER_NAME_PROPERTY = "handler.name";

    /**
     * The handler type property. 
     */
    public static final String HANDLER_TYPE_PROPERTY = "handler.type";

    /**
     * The handler priority.
     */
    public static final String HANDLER_LEVEL_PROPERTY = "handler.level";

    /**
     * The current handler validity.
     * This impacts directly the instance state.
     */
    protected boolean m_isValid = true;

    /**
     * The HandlerManager managing the current handler.
     */
    protected HandlerManager m_instance;

    /**
     * Sets the factory attached to this handler object.
     * This method must be override to depend on each component factory type. 
     * @param factory the factory to attach.
     */
    public abstract void setFactory(Factory factory);

    /**
     * Gets the logger to use in the handler.
     * This method must be override to depend on each component factory type logging policy.
     * @return the logger.
     */
    public abstract Logger getLogger();

    /**
     * Log method (warning).
     * Log a warning message to the handler logger.
     * @param message the message to log
     */
    public final void warn(String message) {
        getLogger().log(Logger.WARNING, message);
    }

    /**
     * Log method (error).
     * Log an error message to the handler logger.
     * @param message the message to log
     */
    public final void error(String message) {
        getLogger().log(Logger.ERROR, message);
    }

    /**
     * Log method (info).     
     * Log an info message to the handler logger.
     * @param message the message to log
     */
    public final void info(String message) {
        getLogger().log(Logger.INFO, message);
    }
    
    /**
     * Log method (debug).     
     * Log a debug message to the handler logger.
     * @param message the message to log
     */
    public final void debug(String message) {
        getLogger().log(Logger.DEBUG, message);
    }

    /**
     * Log method (warning).
     * Log a warning message to the handler logger.
     * The message is sent with an attached exception.
     * @param message the message to log
     * @param exception the exception to attach with the message
     */
    public final void warn(String message, Throwable exception) {
        getLogger().log(Logger.WARNING, message, exception);
    }

    /**
     * Log method (error).
     * Log an error message to the handler logger.
     * The message is sent with an attached exception.
     * @param message the message to log
     * @param exception the exception to attach to the message
     */
    public final void error(String message, Throwable exception) {
        getLogger().log(Logger.ERROR, message, exception);
    }

    /**
     * Get a plugged handler of the same container.
     * This method must be call only in the start method (or after). 
     * In the configure method, this method can not return a consistent
     * result as all handlers are not plugged. 
     * @param name : name of the handler to find (class name or qualified handler name (ns:name)). 
     * @return the handler object or null if the handler is not found.
     */
    public abstract Handler getHandler(String name);

    /**
     * Attaches the current handler object to the given component instance.
     * An attached handler becomes a part of the instance container.
     * @param instance the component instance on which the current handler will be attached.
     */
    protected abstract void attach(ComponentInstance instance);

    /**
     * Checks if the current handler is valid.
     * This check tests the handler validity.
     * This method must not be override.
     * @return <code>true</code> if the handler is valid.
     */
    public final boolean isValid() {
        return ((Pojo) this).getComponentInstance().getState() == ComponentInstance.VALID;
    }

    /**
     * Sets the validity of the current handler.
     * @param isValid if <code>true</code> the handler becomes valid, else it becomes invalid.
     */
    public final void setValidity(boolean isValid) {
        if (m_isValid != isValid) {
            m_isValid = isValid;
            HandlerManager instance = getHandlerManager();
            if (isValid) {
                instance.stateChanged(instance, ComponentInstance.VALID);
            } else {
                instance.stateChanged(instance, ComponentInstance.INVALID);
            }
        }
    }

    /**
     * Is the current handler valid.
     * @return <code>true</code> if the handler is valid, <code>false</code> otherwise.
     */
    public final boolean getValidity() {
        return m_isValid;
    }

    /**
     * Gets the component instance of the current handler.
     * @return the component instance.
     */
    public final HandlerManager getHandlerManager() {
        if (m_instance != null) { return m_instance; }
        m_instance = (HandlerManager) ((Pojo) this).getComponentInstance();
        return m_instance;
    }

    /**
     * Initializes the component factory.
     * This method aims to collect component factory properties. 
     * Each handler wanting to contribute needs to override this 
     * method and adds properties to the given component description.
     * By default, this method does nothing.
     * @param typeDesc the component description.
     * @param metadata the component type metadata.
     * @throws ConfigurationException if the metadata are not correct (early detection).
     */
    public void initializeComponentFactory(ComponentTypeDescription typeDesc, Element metadata) throws ConfigurationException {
        // The default implementation does nothing.
    }

    /**
     * Configures the handler.
     * @param metadata the metadata of the component
     * @param configuration the instance configuration
     * @throws ConfigurationException if the metadata are not correct.
     */
    public abstract void configure(Element metadata, Dictionary configuration) throws ConfigurationException;

    /**
     * Stops the handler
     * This method stops the management.
     */
    public abstract void stop();

    /**
     * Starts the handler
     * This method starts the management.
     */
    public abstract void start();

    /**
     * This method is called when the component state changed.
     * By default, this method does nothing.
     * @param state the new instance state {@link ComponentInstance}
     */
    public void stateChanged(int state) {
        // The default implementation does nothing.
    }

    /**
     * Returns the current handler description.
     * The simplest description contains only the name and the validity of the handler.
     * If the handler override this method, it can customize the description. 
     * By default, this method returns the simplest description.
     * @return the description of the handler.
     */
    public HandlerDescription getDescription() {
        return new HandlerDescription(this);
    }

    /**
     * Reconfigures the instance.
     * This method is called, when the instance is under reconfiguration.
     * The reconfiguration does not stops the instance, and so the handler supporting
     * the reconfiguration must override this method and handles this case. 
     * By default, this method does nothing.
     * @param configuration the new instance configuration.
     */
    public void reconfigure(Dictionary configuration) {
        // The default implementation does nothing.
    }
}