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