/*
 * RHQ Management Platform
 * Copyright (C) 2005-2008 Red Hat, Inc.
 * All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License, version 2, as
 * published by the Free Software Foundation, and/or the GNU Lesser
 * General Public License, version 2.1, also as published by the Free
 * Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License and the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * and the GNU Lesser General Public License along with this program;
 * if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
package org.rhq.core.pluginapi.inventory;

import org.rhq.core.domain.resource.Resource;
import org.rhq.core.pluginapi.availability.AvailabilityFacet;
import org.rhq.core.pluginapi.configuration.ConfigurationFacet;
import org.rhq.core.pluginapi.content.ContentFacet;
import org.rhq.core.pluginapi.measurement.MeasurementFacet;
import org.rhq.core.pluginapi.operation.OperationFacet;
import org.rhq.core.pluginapi.support.SupportFacet;

/**
 * The plugin component that wraps a {@link Resource}. This component allows you to work with the actual resource, such
 * as determining its availability and setting its configuration, among other things. Resource components have a
 * lifecycle controlled by the plugin container - see {@link #start(ResourceContext)} and {@link #stop()}.
 *
 * <p>Implementations of this interface can also implement one or more of the different functionality facets which will
 * allow the component to support different features such as measureability, configurability and others. These
 * functionality facets are:</p>
 *
 * <ul>
 *   <li>{@link MeasurementFacet}</li>
 *   <li>{@link ConfigurationFacet}</li>
 *   <li>{@link OperationFacet}</li>
 *   <li>{@link DeleteResourceFacet}</li>
 *   <li>{@link CreateChildResourceFacet}</li>
 *   <li>{@link ContentFacet}</li>
 *   <li>{@link SupportFacet}</li>
 * </ul>
 *
 * All implementations of this interface must also implement the base {@link AvailabilityFacet}.
 *
 * @param <T> the parent resource component type for this component. This means you can nest a hierarchy of resource
 *            components that mimic the resource type hierarchy as defined in a plugin deployment descriptor.
 */
public interface ResourceComponent<T extends ResourceComponent<?>> extends AvailabilityFacet {
    /**
     * Initializes the resource component, possibly connecting to the managed resource itself. The implementation can be
     * custom to the plugin or resource, but the idea is that a resource component can create a single connection to
     * their resource here, and maintain that connection throughout the life of the component (i.e. until the time when
     * {@link #stop()} is called).
     *
     * <p>This method typically examines the plugin configuration from {@link ResourceContext#getPluginConfiguration()}
     * and uses that information to connect to the managed resource. If this method finds that the plugin configuration
     * is invalid which causes the connection to the managed resource to fail, then this method should throw
     * {@link InvalidPluginConfigurationException}. This exception typically should not be thrown if the connection
     * failed for some reason other than an invalid plugin configuration (e.g. in the case the managed resource is
     * simply not running now) because usually those conditions can be tracked as part of the resource's
     * {@link AvailabilityFacet#getAvailability() availability} data.</p>
     *
     * <p>Note that this method does <b>not</b> imply that the actual managed resource should be started; this only
     * starts the plugin's resource component. To start the actual resource, plugins must utilize the
     * {@link OperationFacet} facet to provide an operation to start it.</p>
     *
     * @param  context the context for this resource which includes information about the resource
     *
     * @throws InvalidPluginConfigurationException if the resource component failed to start because it could not
     *                                             connect to the resource due to a bad plugin configuration
     * @throws Exception                           any other exception that causes the component to fail to start
     */
    void start(ResourceContext<T> context) throws InvalidPluginConfigurationException, Exception;

    /**
     * Stops the resource component, which usually indicates the plugin container itself is shutting down. This method
     * is used to allow the component to disconnect from its managed resource and to clean up anything else as
     * appropriate.
     *
     * <p>Note that this does <b>not</b> imply that the actual managed resource should be stopped; this only stops the
     * plugin's resource component. To stop the actual resource, plugins must utilize the {@link OperationFacet} facet
     * to provide an operation to stop it.</p>
     */
    void stop();
}