/*
 * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 * 
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 * 
 * This code 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
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 * 
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 * 
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.tools.visualvm.core.properties;

import com.sun.tools.visualvm.core.datasource.DataSource;
import com.sun.tools.visualvm.core.datasupport.Positionable;

/**
 * A provider to provide user-customizable properties for DataSources.
 *
 * @since VisualVM 1.2
 * @author Jiri Sedlacek
 */
public abstract class PropertiesProvider<X extends DataSource> implements Positionable {

    /**
     * Key for the "General" properties category (always first if provided).
     */
    public static final int CATEGORY_GENERAL = Integer.MIN_VALUE;

    private final String propertiesName;
    private final String propertiesDescription;
    private final int propertiesCategory;
    private final int preferredPosition;


    /**
     * Creates new instance of PropertiesProvider with the provided name, optional
     * description, properties category and preferred position of the properties
     * within the category.<br>
     * The propertiesCategory value defines position of the category among other
     * categories. If more providers use the same category their position is
     * defined by the preferredPosition value. The propertiesName value defines
     * name of the category if this is the first provider for the category, otherwise
     * it's used as name for the category section.
     *
     * @param propertiesName name of the provided properties
     * @param propertiesDescription description of the provided properties or null
     * @param propertiesCategory category of the provided properties
     * @param preferredPosition preferred position of the properties panel in UI
     */
    public PropertiesProvider(String propertiesName, String propertiesDescription,
                              int propertiesCategory, int preferredPosition) {
        this.propertiesName = propertiesName;
        this.propertiesDescription = propertiesDescription;
        this.propertiesCategory = propertiesCategory;
        this.preferredPosition = preferredPosition;
    }


    /**
     * Returns name of the provided properties.
     *
     * @return name of the provided properties
     */
    public final String getPropertiesName() { return propertiesName; }

    /**
     * Returns description of the provided properties or null for no description.
     *
     * @return description of the provided properties or null for no description
     */
    public final String getPropertiesDescription() { return propertiesDescription; }

    /**
     * Returns category of the provided properties.
     *
     * @return category of the provided properties
     */
    public final int getPropertiesCategory() { return propertiesCategory; }

    /**
     * Returns preferred position of the properties section.
     *
     * @return preferred position of the properties section
     */
    public final int getPreferredPosition() { return preferredPosition; }


    /**
     * Returns true if this PropertiesProvider provides properties for the given
     * DataSource. Default implementation always returns true. Note that if this
     * method returns true for a given DataSource instance the createPanel(DataSource)
     * method for the same instance cannot return null.
     *
     * @param dataSource DataSource for which to provide the properties (null means creating new DataSource)
     * @return true if this PropertiesProvider provides properties for given DataSource, false otherwise
     */
    public boolean supportsDataSource(X dataSource) { return true; }

    /**
     * Returns a PropertiesPanel instance to create or edit the properties. If
     * the provided DataSource is null it means that the DataSource is being
     * created and the properites will define the initial state. Otherwise the
     * DataSource properties are being edited.
     *
     * Note: if using custom JPanel instances in the PropertiesPanel be sure to use
     * JPanel.setOpaque(false) whenever possible to keep the settings UI consistent.
     * For some Look and Feels the PropertiesPanel container doesn't have a standard
     * JPanel background.
     *
     * @param dataSource DataSource to edit the properties or null
     * @return PropertiesPanel instance to create or edit the properties
     */
    public abstract PropertiesPanel createPanel(X dataSource);


    /**
     * Called when a valid PropertiesPanel has been submitted by the user when
     * creating a new DataSource. At this point the provider has a chance to
     * store the properties for the DataSource. The properties should be stored
     * into the DataSource's storage (use dataSource.getStorage()) to ensure they
     * will be always available for persistent DataSources.
     *
     * @param panel user-submitted PropertiesPanel
     * @param dataSource newly created DataSource
     */
    public abstract void propertiesDefined(PropertiesPanel panel, X dataSource);

    /**
     * Called when a valid PropertiesPanel has been submitted by the user when
     * editing an existing DataSource. At this point the provider has a chance
     * to update the properties for the DataSource. The properties should be stored
     * into the DataSource's storage (use dataSource.getStorage()) to ensure they
     * will be always available for persistent DataSources.
     *
     * @param panel user-submitted PropertiesPanel
     * @param dataSource edited existing DataSource
     */
    public abstract void propertiesChanged(PropertiesPanel panel, X dataSource);

    /**
     * Called when a PropertiesPanel has been cancelled by the user. At this point
     * the provider has a chance to perform eventual cleanup.
     *
     * @param panel user-cancelled PropertiesPanel
     * @param dataSource DataSource for which the panel has been cancelled or null if no DataSource has been created
     */
    public abstract void propertiesCancelled(PropertiesPanel panel, X dataSource);

}
