001/*
002 * (C) Copyright 2015 Nuxeo SA (http://nuxeo.com/) and others.
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 *
016 * Contributors:
017 *     Thierry Delprat <tdelprat@nuxeo.com>
018 *     Antoine Taillefer <ataillefer@nuxeo.com>
019 */
020
021package org.nuxeo.ecm.automation.server.jaxrs.batch;
022
023import java.io.IOException;
024import java.io.InputStream;
025import java.util.List;
026import java.util.Map;
027import java.util.Set;
028
029import org.nuxeo.ecm.core.api.Blob;
030import org.nuxeo.ecm.core.api.CoreSession;
031import org.nuxeo.ecm.core.transientstore.api.TransientStore;
032
033/**
034 * Service interface to collect inputs (Blobs) for an operation or operation chain.
035 *
036 * @since 5.4.2
037 */
038public interface BatchManager {
039
040    /**
041     * Returns the {@link TransientStore} backing the batches.
042     *
043     * @since 7.4
044     */
045    TransientStore getTransientStore();
046
047    /**
048     * Adds an inputStream as a blob to a batch. Will create a new {@link Batch} if needed.
049     * <p>
050     * Streams are persisted as temporary files.
051     *
052     * @deprecated since 10.1, use {@link #addBlob(String, String, Blob, String, String)} instead
053     */
054    @Deprecated
055    void addStream(String batchId, String index, InputStream is, String name, String mime) throws IOException;
056
057    /**
058     * Adds a blob to a batch. Will create a new {@link Batch} if needed.
059     *
060     * @since 10.1
061     */
062    void addBlob(String batchId, String index, Blob blob, String name, String mime) throws IOException;
063
064    /**
065     * Adds an inputStream as a chunk to a batch. Will create a new {@link Batch} if needed.
066     * <p>
067     * Streams are persisted as temporary files.
068     *
069     * @since 7.4
070     * @deprecated since 10.1, use {@link #addBlob(String, String, Blob, int, int, String, String, long)} instead
071     */
072    @Deprecated
073    void addStream(String batchId, String index, InputStream is, int chunkCount, int chunkIndex, String name,
074            String mime, long fileSize) throws IOException;
075
076    /**
077     * Adds a blob as a chunk to a batch. Will create a new {@link Batch} if needed.
078     *
079     * @since 10.1
080     */
081    void addBlob(String batchId, String index, Blob blob, int chunkCount, int chunkIndex, String name, String mime,
082            long fileSize) throws IOException;
083
084    /**
085     * Returns true if there is a batch for the given {@code batchId}, false otherwise.
086     *
087     * @since 5.7.2
088     */
089    boolean hasBatch(String batchId);
090
091    /**
092     * Gets Blobs associated to a given batch. Returns null if batch does not exist.
093     */
094    List<Blob> getBlobs(String batchId);
095
096    /**
097     * Gets Blobs associated to a given batch. Returns null if batch does not exist. Waits for upload in progress if
098     * needed.
099     *
100     * @since 5.7
101     */
102    List<Blob> getBlobs(String batchId, int timeoutS);
103
104    Blob getBlob(String batchId, String fileIndex);
105
106    Blob getBlob(String batchId, String fileIndex, int timeoutS);
107
108    /**
109     * @since 7.4
110     */
111    List<BatchFileEntry> getFileEntries(String batchId);
112
113    /**
114     * @since 7.4
115     */
116    BatchFileEntry getFileEntry(String batchId, String fileIndex);
117
118    /**
119     * Cleans up the temporary storage associated to the batch.
120     */
121    void clean(String batchId);
122
123    /**
124     * Initializes a batch by with an automatically generated id.
125     *
126     * @return the batch id
127     * @since 7.4
128     */
129    String initBatch();
130
131    /**
132     * Initializes a batch with a given batchId and Context Name. If batchId is not provided, it will be automatically
133     * generated.
134     *
135     * @return the batchId
136     * @deprecated since 7.10, use {@link BatchManager#initBatch()} instead.
137     */
138    @Deprecated
139    String initBatch(String batchId, String contextName);
140
141    /**
142     * Initiates a new batch with the given handler.
143     *
144     * @param handlerName the batch handler name
145     * @return the newly created batch
146     * @throws IllegalArgumentException it the batch handler does not exist
147     * @since 10.1
148     */
149    Batch initBatch(String handlerName);
150
151    /**
152     * Executes the chain or operation on the {@code Blobs} from the given {@code batchId}.
153     * <p>
154     * This method does not clean the temporary storage associated to the {@code batchId}.
155     *
156     * @since 5.7
157     */
158    Object execute(String batchId, String chainOrOperationId, CoreSession session, Map<String, Object> contextParams,
159            Map<String, Object> operationParams);
160
161    /**
162     * Executes the chain or operation on the {@code Blob} from the given {@code batchId} and {@code fileIndex}.
163     * <p>
164     * This method does not clean the temporary storage associated to the {@code batchId}.
165     *
166     * @since 5.7.2
167     */
168    Object execute(String batchId, String fileIndex, String chainOrOperationId, CoreSession session,
169            Map<String, Object> contextParams, Map<String, Object> operationParams);
170
171    /**
172     * Executes the chain or operation on the {@code Blobs} from the given {@code batchId}.
173     * <p>
174     * This method cleans the temporary storage associated to the {@code batchId} after the execution.
175     *
176     * @since 5.7
177     */
178    Object executeAndClean(String batchId, String chainOrOperationId, CoreSession session,
179            Map<String, Object> contextParams, Map<String, Object> operationParams);
180
181    /**
182     * Removes a file from a batch.
183     *
184     * @since 8.4
185     */
186    boolean removeFileEntry(String batchId, String filedIdx);
187
188    /**
189     * Fetches information about a batch.
190     *
191     * @param batchId the batch id
192     * @return the batch, or {@code null} if it doesn't exist
193     * @since 10.1
194     */
195    Batch getBatch(String batchId);
196
197    /**
198     * Returns the supported batch handler names.
199     *
200     * @return the supported batch handler names
201     * @since 10.1
202     */
203    Set<String> getSupportedHandlers();
204
205    /**
206     * Gets a batch handler.
207     *
208     * @param handlerName the batch handler name
209     * @return the batch handler, or {@code null} if it doesn't exist
210     * @since 10.1
211     */
212    BatchHandler getHandler(String handlerName);
213
214}