/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.sling.scripting.api.bundle;

import java.io.InputStream;
import java.util.Set;

import javax.script.ScriptException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import org.osgi.annotation.versioning.ConsumerType;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleContext;

/**
 * <p>
 * A {@code BundledRenderUnit} represents a pre-packaged script or precompiled script (Java class) that will be executed in order to
 * render a {@link org.apache.sling.api.SlingHttpServletRequest}.
 * </p>
 * <p>
 * The {@code BundledRenderUnit} provider module is responsible for defining how a unit is executed. However, when executing the unit in the
 * context of a {@link javax.script.ScriptEngine}, the provider module should add the current executing unit into the {@link
 * javax.script.ScriptEngine}'s {@link javax.script.ScriptContext} using the {@link #VARIABLE} key.
 * </p>
 */
@ConsumerType
public interface BundledRenderUnit {

    /**
     * The variable available in the {@link javax.script.Bindings} associated to a {@link org.apache.sling.api.SlingHttpServletRequest} if
     * that request is served by a {@code BundledRenderUnit}.
     */
    String VARIABLE = BundledRenderUnit.class.getName();

    /**
     * In case this {@code BundledRenderUnit} wraps a precompiled script, this method will return an instance of that object.
     *
     * @return a precompiled unit, if {@code this} unit wraps a precompiled script; {@code null} otherwise
     */
    @Nullable
    default Object getUnit() {
        return null;
    }

    /**
     * Returns the name of {@code this BundledRenderUnit}. This can be the name of the wrapped script or precompiled script.
     *
     * @return the name {@code this BundledRenderUnit}
     */
    @NotNull String getName();

    /**
     * Returns the {@link Bundle} the publishing bundle of this unit (not to be confused with the provider module, which is the module that
     * instantiates a {@link BundledRenderUnit}). This method can be useful for getting an instance of the bundle's classloader, when
     * needed to load dependencies at run-time. To do so the following code example can help:
     *
     * <pre>
     * Bundle bundle = bundledRenderUnit.getBundle();
     * Classloader bundleClassloader = bundle.adapt(BundleWiring.class).getClassLoader();
     * </pre>
     */
    @NotNull Bundle getBundle();

    /**
     * Returns the {@link BundleContext} to use for this unit. This method can be useful for getting an instance of the publishing bundle's
     * context, when needed to load dependencies at run-time.
     *
     * @return the bundle context of the bundle publishing this unit
     */
    @NotNull BundleContext getBundleContext();

    /**
     * Returns the {@code Set} of {@link TypeProvider}s which are related to this unit.
     *
     * @return the set of providers; if the unit doesn't have any inheritance chains, then the set will contain only one {@link
     * TypeProvider}
     */
    @NotNull Set<TypeProvider> getTypeProviders();

    /**
     * Retrieves an OSGi runtime dependency of the wrapped script identified by the passed {@code className} parameter.
     *
     * @param className the fully qualified class name
     * @param <T>       the expected service type
     * @return an instance of the {@link T} or {@code null}
     */
    @Nullable <T> T getService(@NotNull String className);

    /**
     * Retrieves multiple instances of an OSGi runtime dependency of the wrapped script identified by the passed {@code className}
     * parameter, filtered according to the passed {@code filter}.
     *
     * @param className the fully qualified class name
     * @param filter    a filter expression or {@code null} if all the instances should be returned; for more details about the {@code
     *                  filter}'s syntax check {@link org.osgi.framework.BundleContext#getServiceReferences(String, String)}
     * @param <T>       the expected service type
     * @return an instance of the {@link T} or {@code null}
     */
    @Nullable <T> T[] getServices(@NotNull String className, @Nullable String filter);

    /**
     * Returns the path of this executable in the resource type hierarchy. The path can be relative to the search paths or absolute.
     *
     * @return the path of this executable in the resource type hierarchy
     */
    @NotNull
    String getPath();

    /**
     * This method will execute / evaluate the wrapped script or precompiled script with the given request.
     *
     * @throws ScriptException if the execution leads to an error
     */
    void eval(@NotNull HttpServletRequest request, @NotNull HttpServletResponse response) throws ScriptException;

    /**
     * This method will return an input stream if {@code this} unit is backed by a script that can be interpreted.
     *
     * @return an {@link InputStream} providing the source code of the backing script; if {@code this} unit is backed by a precompiled
     * script (essentially a Java class), then this method will return {@code null}
     */
    @Nullable
    default InputStream getInputStream() {
        return null;
    }
}