/*

 * Copyright (c) 2014, 2018, 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 jdk.packager.internal;

import java.util.Collection;

import java.util.Iterator;

import java.util.ServiceLoader;

public interface Bundlers {

    /**

     * This convenience method will call

     * {@link #createBundlersInstance(ClassLoader)}

     * with the classloader that this Bundlers is loaded from.

     *

     * @return an instance of Bundlers loaded and configured from

     *         the current ClassLoader.

     */

    public static Bundlers createBundlersInstance() {

        return createBundlersInstance(Bundlers.class.getClassLoader());

    }

    /**

     * This convenience method will automatically load a Bundlers instance

     * from either META-INF/services or the default

     * {@link BasicBundlers} if none are found in

     * the services meta-inf.

     *

     * After instantiating the bundlers instance it will load the default

     * bundlers via {@link #loadDefaultBundlers()} as well as requesting

     * the services loader to load any other bundelrs via

     * {@link #loadBundlersFromServices(ClassLoader)}.

     *

     * @param servicesClassLoader the classloader to search for

     *                            META-INF/service registered bundlers

     * @return an instance of Bundlers loaded and configured from

     *         the specified ClassLoader

     */

    public static Bundlers createBundlersInstance(

            ClassLoader servicesClassLoader) {

        ServiceLoader<Bundlers> bundlersLoader =

                ServiceLoader.load(Bundlers.class, servicesClassLoader);

        Bundlers bundlers = null;

        Iterator<Bundlers> iter = bundlersLoader.iterator();

        if (iter.hasNext()) {

            bundlers = iter.next();

        }

        if (bundlers == null) {

            bundlers = new BasicBundlers();

        }

        bundlers.loadBundlersFromServices(servicesClassLoader);

        return bundlers;

    }

    /**

     * Returns all of the preconfigured, requested, and manually

     * configured bundlers loaded with this instance.

     *

     * @return  a read-only collection of the requested bundlers

     */

    Collection<Bundler> getBundlers();

    /**

     * Returns all of the preconfigured, requested, and manually

     * configured bundlers loaded with this instance that are of

     * a specific BundleType, such as disk images, installers, or

     * remote installers.

     *

     * @return a read-only collection of the requested bundlers

     */

    Collection<Bundler> getBundlers(String type);

    /**

     * Loads the bundlers common to the JDK.  A typical implementation

     * would load:

     * <UL>

     *     <LI>Windows file image</LI>

     *     <LI>Mac .app</LI>

     *     <LI>Linux file image</LI>

     *     <LI>Windows MSI</LI>

     *     <LI>Windows EXE</LI>

     *     <LI>Mac DMG</LI>

     *     <LI>Mac PKG</LI>

     *     <LI>Linux DEB</LI>

     *     <LI>Linux RPM</LI>

     *

     * </UL>

     *

     * This method is called from the

     * {@link #createBundlersInstance(ClassLoader)}

     * and {@link #createBundlersInstance()} methods.

     * NOTE: Because of the module system this method is now not used.

     */

    void loadDefaultBundlers();

    /**

     * Loads bundlers from the META-INF/services directly.

     *

     * This method is called from the

     * {@link #createBundlersInstance(ClassLoader)}

     * and {@link #createBundlersInstance()} methods.

     */

    void loadBundlersFromServices(ClassLoader cl);

    /**

     * Loads a specific bundler into the set of bundlers.

     * Useful for a manually configured bundler.

     *

     * @param bundler the specific bundler to add

     */

    void loadBundler(Bundler bundler);

}