001/*
002 *  Copyright 2018 Anyware Services
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.ametys.plugins.extraction.execution.pipeline;
017
018import java.io.OutputStream;
019import java.util.List;
020import java.util.Map;
021
022import org.ametys.plugins.extraction.execution.ExtractionExecutor;
023import org.ametys.plugins.extraction.execution.PathResolver;
024import org.ametys.runtime.i18n.I18nizableText;
025
026/**
027 * A descriptor which can provide a {@link Pipeline} with {@link #newPipeline(OutputStream) newPipeline} method.
028 */
029public interface PipelineDescriptor
030{
031    /**
032     * Gets the label
033     * @return the label
034     */
035    I18nizableText getLabel();
036    
037    /**
038     * Gets the {@link ExtractionMatcher extraction matcher} to check if the pipeline is able to handle a given extraction
039     * @return the {@link ExtractionMatcher extraction matcher} of the pipeline
040     */
041    ExtractionMatcher getExtractionMatcher();
042    
043    /**
044     * Gets the XSLT file names to chain
045     * @return the XSLT file names to chain
046     */
047    List<String> getStylesheets();
048    
049    /**
050     * Gets the {@link PipelineSerializerModel serializer model}
051     * @return the {@link PipelineSerializerModel serializer model}
052     */
053    PipelineSerializerModel getSerializerModel();
054    
055    /**
056     * Gets the result subfolder (or file). 
057     * <br>Can contain variables (see {@link PathResolver}), resolved against the extraction results.
058     * <br>If it returns
059     * <ul>
060     * <li>a file path without variable, then all extraction results will be in this file;</li>
061     * <li>a file path with variables, then extraction results will be dispatched in the resolved file paths;</li>
062     * <li>
063     * a folder path without variable, then all extraction results will be in one file under this folder 
064     * (the file name will be the one provided in <code>defaultResultFileName</code> parameter 
065     * of {@link ExtractionExecutor#execute(String, String, String, java.util.Map, PipelineDescriptor) ExtractionExecutor#execute method});
066     * </li>
067     * <li>
068     * a folder path with variables, then each first level content extraction result will be dispatched in one file under the resolved folders
069     * (the file name will be the <b>title</b> of the content, and the extension is the return of {@link #getDefaultExtension()});
070     * </li>
071     * </ul>
072     * @return the result subfolder (or file)
073     */
074    String getResultSubfolder();
075    
076    /**
077     * Gets the default extension of the file result(s)
078     * <br>The default extension is used when {@link #getResultSubfolder()} is a folder and not a file.
079     * @return the default extension of the file result(s)
080     */
081    String getDefaultExtension();
082    
083    /**
084     * Provides a new {@link Pipeline}
085     * @param out the output stream to write on
086     * @return the built {@link Pipeline}
087     */
088    Pipeline newPipeline(OutputStream out);
089    
090    /**
091     * Get the output parameters to add some specific features in each serializer.
092     * @return The output parameters
093     */
094    Map<String, String> getOutputParameters();
095}