/*
 * Licensed 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.atomos;

import java.nio.file.Path;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;

import org.osgi.annotation.versioning.ProviderType;
import org.osgi.framework.BundleException;
import org.osgi.framework.connect.ConnectFrameworkFactory;
import org.osgi.framework.connect.ModuleConnector;

/**
 * An Atomos Layer may represents a {@link ModuleLayer} that was added to
 * a {@link Atomos} using the {@link AtomosLayer#addLayer(String, LoaderType, Path...)}  addLayer}
 * method or the Atomos Layer could represent the {@link Atomos#getBootLayer() boot layer}.
 * An Atomos Layer will contain one or more {@link AtomosContent Atomos contents} which can
 * then be used to {@link AtomosContent#install(String) install } them as OSGi connected bundles into the
 * {@link ConnectFrameworkFactory#newFramework(Map, ModuleConnector)}  framework}.
 */
@ProviderType
public interface AtomosLayer
{
    /**
     * The loader type used for the class loaders of an Atomos layer.
     */
    @ProviderType
    enum LoaderType
    {
        /**
         * Loader type that will use a unique loader for each connected bundle in the
         * layer and the loader will implement the {@link org.osgi.framework.BundleReference}
         * interface.
         */
        OSGI,
        /**
         * Loader type that will use a single loader for each connected bundle in the
         * layer.
         */
        SINGLE,
        /**
         * Loader type that will use a unique loader for each connected bundle in the
         * layer.
         */
        MANY
    }
    
    /**
     * Adapt this Atomos layer to the specified type. For example,
     * if running in a module layer then the layer can be adapted
     * to a ModuleLayer associated with this Atomos Layer.
     * @param <T> The type to which this Atomos layer is to be adapted.
     * @param type Class object for the type to which this Atomos layer is to be
     *        adapted.
     * @return The object, of the specified type, to which this Atomos layer has been
     *         adapted or {@code empty} if this layer cannot be adapted to the
     *         specified type.
     */
    <T> Optional<T> adapt(Class<T> type);

    /**
     * Adds a layer as a child of this layer and loads modules from the specified
     * module paths
     * 
     * @param name        the name of the new layer
     * @param loaderType  the type of class loader to use
     * @param modulePaths the paths to load modules for the new layer
     * @return a newly created layer
     * @throws UnsupportedOperationException if {@link #isAddLayerSupported()} returns false.
     */
    AtomosLayer addLayer(String name, LoaderType loaderType, Path... modulePaths);

    /**
     * A convenience method that adds the modules found at the specified path
     * to a new child layer of this layer.
     * @param name The name of the layer.
     * @param path The path to the modules.  If {@code null} then the default will try to
     * determine the location on disk of the atomos runtime module and look for a
     * folder with the same name as the specified name of the layer.
     * @throws UnsupportedOperationException if {@link #isAddLayerSupported()} returns false.
     * @return a newly created layer
     */
    AtomosLayer addModules(String name, Path path);

    /**
     * Returns {@code true} if additional layers are supported.
     * @return if modules and additional layers are supported.
     */
    boolean isAddLayerSupported();

    /**
     * The Atomos Layer children of this layer
     * @return The children of this layer
     */
    Set<AtomosLayer> getChildren();

    /**
     * The Atomos parents of this layer
     * @return the parnets of this layer
     */
    List<AtomosLayer> getParents();

    /**
     * The Atomos contents contained in this layer
     * @return the Atomos contents
     */
    Set<AtomosContent> getAtomosContents();

    /**
     * Returns the Atomos content with the given name in this layer, or if not in this
     * layer, the {@linkplain #getParents() parent} layers. Finding content in
     * parent layers is equivalent to invoking {@code findAtomosContent} on each
     * parent, in search order, until the content is found or all parents have
     * been searched. In a <em>tree of layers</em>  then this is equivalent to
     * a depth-first search.
     * @param symbolicName the name of the content to find
     * @return The content with the given name or an empty {@code Optional}
     *         if there isn't a content with this name in this layer or any
     *         parent layer
     */
    Optional<AtomosContent> findAtomosContent(String symbolicName);

    /**
     * The name of the Atomos Layer.  By default the Atomos Layer
     * name is the empty string.  Atomos Layer names are not
     * required to be unique.  All Atomos contents contained in a
     * layer will have {@link AtomosContent#getAtomosLocation() locations}
     * that use the layer name as a prefix.  If the layer
     * name is not the empty string then the location prefix will be
     * the layer name followed by a colon ({@code :}).
     * This allows two different layers to load the same content in
     * different layers.
     * @return the name of the layer
     */
    String getName();

    /**
     * Returns this Atomos Layer's unique identifier. This Atomos Layer is assigned a unique
     * identifier when it was installed in the Atomos runtime.
     * 
     * <p>
     * A Atomos Layer's unique identifier has the following attributes:
     * <ul>
     * <li>Is unique and persistent.</li>
     * <li>Is a {@code long}.</li>
     * <li>Its value is not reused for another layer, even after a layer is
     * uninstalled.</li>
     * <li>Does not change while a layer remains installed.</li>
     * </ul>
     * 
     * @return The unique identifier of this layer.
     */
    long getId();

    /**
     * Returns the loader type used for this Atomos layer.
     * @return the loader type
     */
    LoaderType getLoaderType();

    /**
     * Uninstalls this Atomos Layer along with any {@link #getChildren() children}
     * layers.
     * @throws BundleException If an error happened while uninstalling any connected
     * bundles in the layer
     */
    void uninstall() throws BundleException;
}