/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2011 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2011 Sun Microsystems, Inc.

 */

package org.netbeans.modules.web.jsfapi.spi.components;

import javax.swing.JComponent;

import javax.swing.event.ChangeListener;

/**

 * Provides support for extending a JSF framework with a JSF component library.

 * It allows to modify the web module to make use of the JSF suite in JSF framework. 

 * 

 * @author Martin Fousek <marfous@netbeans.org>

 * 

 * @since 1.7

 */

public interface JsfComponentCustomizer {

    /**

     * Attaches a change listener that is to be notified of changes

     * in the customizer (e.g., the result of the {@link #isValid} method

     * has changed).

     *

     * @param  listener a listener.

     */

    public void addChangeListener(ChangeListener listener);

    /**

     * Removes a change listener.

     *

     * @param  listener a listener.

     */    

    public void removeChangeListener(ChangeListener listener);

    /**

     * Returns a UI component used to allow the user to update this customizer.

     *

     * @return a component. This method might be called more than once and it is 

     * expected to always return the same instance.

     */

    public JComponent getComponent();

    /**

     * Checks if this customizer is valid (e.g., if the configuration set

     * using the UI component returned by {@link #getComponent} is valid).

     * <p>

     *

     * @return {@code true} if the configuration is valid, {@code false} otherwise.

     * @see #getErrorMessage()

     * @see #getWarningMessage()

     */

    public boolean isValid();

    /**

     * Get error message or {@code null} if the {@link #getComponent component} is {@link #isValid() valid}.

     * 

     * @return error message or {@code null} if the {@link #getComponent component} is {@link #isValid() valid}

     * 

     * @see #isValid()

     * @see #getWarningMessage()

     */    

    public String getErrorMessage();

    /**

     * Get warning message that can be not {@code null} even for {@link #isValid() valid} customizer.

     * In other words, it is safe to extend web module even if this method returns a message.

     * 

     * @return warning message or {@code null}

     * 

     * @see #isValid()

     * @see #getErrorMessage()

     */    

    public String getWarningMessage();

    /**

     * Allow to save actual configuration of UI component. 

     * <p>

     * This method is called after closing component by OK button.

     */

    public void saveConfiguration();

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2010 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2010 Sun Microsystems, Inc.

 */

package org.netbeans.modules.web.jsfapi.spi.components;

import java.util.Set;

import org.netbeans.modules.web.api.webmodule.WebModule;

import org.netbeans.modules.web.jsfapi.api.JSFVersion;

import org.openide.filesystems.FileObject;

/**

 * This interface allows providing support for JSF component libraries. It can be used

 * to extend a web module and JSF framework with a JSF suite, to find out whether a web

 * module is already extended by a JSF component library, or to retrieve a JSF suite's

 * specific configuration thru the {@link JsfComponentCustomizer}.

 *

 * <p>Instances of this class are registered in the {@value 

 * org.netbeans.modules.web.jsfapi.spi.components.JsfComponentProvider#COMPONENTS_PATH}

 * in the module layer, see {@link Registration}.</p>

 * 

 * @author Martin Fousek <marfous@netbeans.org>

 */

public interface JsfComponentImplementation {

    /**

     * Returns the name of this JSF component library.

     *

     * @return the name; never {@code null}.

     */    

    public String getName();

    /**

     * Returns the description of this JSF component library.

     *

     * @return the description.

     */

    public String getDescription();

    /**

     * Called to extend the given web module and JSF framework with the JSF 

     * component library corresponding to this implementation.

     *

     * @param  webModule the web module to be extended; never null.

     * @return the set of newly created files in the web module which should be opened.

     */

    public Set<FileObject> extend(WebModule webModule);

    /**

     * Returns for which version is the JSF component library designated. 

     * <p>

     * By creating new project and choosing JSF framework are JSF suites filtered 

     * out according to their {@link JSFVersion}.

     * 

     * @return {@link JSFVersion} suitable for this JSF component library.

     */

    public JSFVersion getJsfVersion();

    /**

     * Finds out if a given web module has already been extended with this JSF component library.

     * <p>

     * <b>This method should be as fast as possible.</b>

     *

     * @param webmodule the web module; never {@code null}.

     * @return {@code true} if the web module has already been extended with this JSF suite, 

     * {@code false} otherwise.

     */

    public boolean isInWebModule(WebModule webModule);

    /**

     * Creates a {@link JsfComponentCustomizer} for this JSF component

     * library.

     * <p>

     * For new project is called with {@code null} parameter. In project customizer is called for 

     * actual {@link WebModule}.

     * 

     * @param webmodule the web module for which should be customizer adapted; null if the 

     * project doesn't exist yet

     * @return a new customizer; can be <code>null</code> if the JSF suite doesn't 

     * support that and no extending panel should be offered.

     */

    public JsfComponentCustomizer createJsfComponentCustomizer(WebModule webModule);

    /**

     * Performs actions needed for removal JSF component library form the web module.

     *

     * @param webModule the web module from which should be JSF component library removed; never null.

     */

    public void remove(WebModule webModule);

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2011 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2011 Sun Microsystems, Inc.

 */

package org.netbeans.modules.web.jsfapi.spi.components;

import java.util.Set;

/**

 * Provides all {@link JsfComponentImplementation}s in given {@link JsfComponentProvider}.

 * JSF Support searches in registered {@link JsfComponentProvider}s for all 

 * {@link JsfComponentImplementation}s to offer them as JSF component libraries.

 * 

 * <p>

 * Every JSF suite module should contain only one {@link JsfComponentProvider} which 

 * can return more {@link JsfComponentImplementation}s.

 * 

 * 

 * @author Martin Fousek <marfous@netbeans.org>

 * 

 * @since 1.7

 */

public interface JsfComponentProvider {

    public static final String COMPONENTS_PATH = "j2ee/jsf/components";    //NOI18N

    /**

     * Get all registered {@link JsfComponentImplementation}s  contained in the module.

     * 

     * @return a set of registered {@link JsfComponentImplementation}s; never null.

     */

    public Set<JsfComponentImplementation> getJsfDescriptors();

}