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

import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.apache.sling.event.jobs.Job;
import org.osgi.annotation.versioning.ProviderType;

import java.io.IOException;
import java.util.Map;

/**
 * Plumber is an osgi service aiming to make pipes available to the sling system, in order to
 */
@ProviderType
public interface Plumber {

    /**
     * Instantiate a pipe from the given resource and returns it
     *
     * @param resource configuration resource
     *
     * @return pipe instantiated from the resource, null otherwise
     */
    Pipe getPipe(Resource resource);


    /**
     * Instantiate a pipe from the given resource and returns it
     *
     * @param resource      configuration resource
     * @param upperBindings already set binding we want to initiate our pipe with
     *
     * @return pipe instantiated from the resource, null otherwise
     */
    Pipe getPipe(Resource resource, PipeBindings upperBindings);


    /**
     * executes in a background thread
     *
     * @param resolver resolver used for registering the execution (id will be checked against the configuration)
     * @param path     path of the pipe to execute
     * @param bindings additional bindings to use when executing
     *
     * @return Job if registered, null otherwise
     */
    Job executeAsync(ResourceResolver resolver, String path, Map<String, Object> bindings);

    /**
     * executes in a background thread
     *
     * @param path     path of the pipe to execute
     * @param bindings additional bindings to use when executing
     *
     * @return Job if registered, null otherwise
     */
    Job executeAsync(String path, Map<String, Object> bindings);

    /**
     * Executes a pipe at a certain path
     *
     * @param resolver resource resolver with which pipe will be executed
     * @param path     path of a valid pipe configuration
     * @param bindings bindings to add to the execution of the pipe, can be null
     * @param writer   output of the pipe
     * @param save     in case that pipe writes anything, wether the plumber should save changes or not
     *
     * @return instance of <code>ExecutionResult</code>
     */
    ExecutionResult execute(ResourceResolver resolver, String path, Map<String, Object> bindings, OutputWriter writer, boolean save);

    /**
     * Executes a given pipe
     *
     * @param resolver resource resolver with which pipe will be executed
     * @param pipe     pipe to execute
     * @param bindings bindings to add to the execution of the pipe, can be null
     * @param writer   output of the pipe
     * @param save     in case that pipe writes anything, wether the plumber should save changes or not
     *
     * @return instance of <code>ExecutionResult</code>
     */
    ExecutionResult execute(ResourceResolver resolver, Pipe pipe, Map<String, Object> bindings, OutputWriter writer, boolean save);

    /**
     * Registers
     *
     * @param type      resource type of the pipe to register
     * @param pipeClass class of the pipe to register
     */
    void registerPipe(String type, Class<? extends BasePipe> pipeClass);


    /**
     * returns wether or not a pipe type is registered
     *
     * @param type resource type tested
     *
     * @return true if the type is registered, false if not
     */
    boolean isTypeRegistered(String type);

    /**
     * status of the pipe
     *
     * @param pipeResource resource corresponding to the pipe
     *
     * @return status of the pipe, can be blank, 'started' or 'finished'
     */
    String getStatus(Resource pipeResource);

    /**
     * Provides a builder helping quickly build and execute a pipe
     *
     * @param resolver resource resolver that will be used for building the pipe
     *
     * @return instance of PipeBuilder
     */
    PipeBuilder newPipe(ResourceResolver resolver);

    /**
     * returns true if the pipe is considered to be running
     *
     * @param pipeResource resource corresponding to the pipe
     *
     * @return true if still running
     */
    boolean isRunning(Resource pipeResource);

    /**
     * Extract pipe bindings from the request
     * @param request from where to extract bindings
     * @param writeAllowed should we consider this execution is about to modify content
     * @return map of bindings
     * @throws IOException in case something turns wrong with an input stream
     */
    Map<String, Object> getBindingsFromRequest(SlingHttpServletRequest request, boolean writeAllowed) throws IOException;

    /**
     * @return service user that has been configured for executing pipes;
     */
    Map<String, Object> getServiceUser();
}