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

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Path;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.function.Consumer;
import java.util.regex.Pattern;
import org.apache.nifi.components.state.Scope;
import org.apache.nifi.components.state.StateMap;
import org.apache.nifi.controller.queue.QueueSize;
import org.apache.nifi.flowfile.FlowFile;
import org.apache.nifi.processor.exception.FlowFileAccessException;
import org.apache.nifi.processor.exception.FlowFileHandlingException;
import org.apache.nifi.processor.exception.MissingFlowFileException;
import org.apache.nifi.processor.exception.ProcessException;
import org.apache.nifi.processor.io.InputStreamCallback;
import org.apache.nifi.processor.io.OutputStreamCallback;
import org.apache.nifi.processor.io.StreamCallback;
import org.apache.nifi.provenance.ProvenanceReporter;
import org.apache.nifi.provenance.ProvenanceEventType;

/**
 * A process session encompasses all the behaviors a processor can perform to
 * obtain, clone, read, modify remove {@link FlowFile}s in an atomic unit.
 * A process session is always tied to a single {@link Processor} at any one time
 * and ensures no FlowFile can ever be accessed by any more than one processor at a given time.
 * The session also ensures that all FlowFiles are always accounted for.
 * The creator of a process session is always required to manage the session.
 * <p>
 * A session is not considered thread safe. The session supports a unit of work that is either committed or rolled back.
 * <p>
 * As noted on specific methods and for specific exceptions
 * automated rollback will occur to ensure consistency of the repository.
 * However, several situations can result in exceptions yet not cause automated rollback.
 * In these cases the consistency of the repository will be retained
 * but callers will be able to indicate whether it should result in rollback or continue on toward a commit.
 * <p>
 * A process session has two types of 'terminal' methods that will result in the session being in a 'fresh' state,
 * containing no knowledge or any FlowFile, as if the session were newly created.
 * After one of these methods is called, the instance may be used again.
 * The terminal methods for a process session are  {@link #commitAsync()} and {@link #rollback()} (and their overloads).
 * <p>
 * Additionally, the {@link #migrate(ProcessSession, Collection)} method transfers all knowledge of the provided FlowFiles
 * to the other process session, as if the FlowFiles never existed in this process session.
 * Note, however, that even if all FlowFiles are migrated via the {@link #migrate(ProcessSession, Collection)} method,
 * the session is not necessarily entirely cleared, as it still may have knowledge of counter adjustments or state changes,
 * e.g. see methods {@link #adjustCounter(String, long, boolean)} or {@link #setState(Map, Scope)}.
 * A commit or rollback will clear these changes as well.
 */
public interface ProcessSession {

    /**
     * Commits the current session ensuring all operations against {@link FlowFile}s within this session are atomically persisted.
     * All FlowFiles operated on within this session must be accounted for by transfer or removal or the commit will fail.
     * <p>
     * As soon as the commit completes the session is again ready to be used.
     * <p>
     * See {@link #commitAsync()}, {@link #commitAsync(Runnable)}, and {@link #commitAsync(Runnable, Consumer)}.
     * The asynchronous session commit methods are preferable to this commit call for most cases
     * as it defers when the actual commit happens to the framework so that it can optimize when the commit call takes place.
     *
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}).
     * @throws FlowFileHandlingException if not all {@link FlowFile}s acted upon within this session are accounted for
     *              such that they have a transfer identified or where marked for removal. Automated rollback occurs.
     * @throws ProcessException if some general fault occurs while persisting the session.
     *              Initiates automatic rollback. The root cause can be obtained via {@link Exception#getCause}.
     */
    void commit();

    /**
     * Commits the current session ensuring all operations against {@link FlowFile}s within this session are atomically persisted.
     * All FlowFiles operated on within this session must be accounted for by transfer or removal or the commit will fail.
     * <p>
     * Unlike the {@link #commit()} method, the persistence of data to the repositories
     * is not guaranteed to have occurred by the time that this method returns.
     * Therefore, if any follow-on actions are necessary after the data has been persisted to the repository
     * (for example, acknowledging receipt from a source system, removing a source file, etc.) that logic
     * should be performed only by invoking {@link #commitAsync(Runnable)} or {@link #commitAsync(Runnable, Consumer)}
     * and implementing that action in the provided callback.
     * <p>
     * As a result, the following very common idiom:
     * <pre><code>
     * getDataFromSource();
     * session.commit();
     * acknowledgeReceiptOfData();
     * </code></pre>
     * Cannot be simply changed to:
     * <pre><code>
     * getDataFromSource();
     * session.commitAsync();
     * acknowledgeReceiptOfData();
     * </code></pre>
     * Doing so could result in acknowledging receipt of data from the source system before data has been committed to the repositories.
     * If NiFi were to then be restarted, there is potential for data loss.
     * Rather, the following idiom should take its place to ensure that there is no data loss:
     * <pre><code>
     * getDataFromSource();
     * session.commitAsync( () -> acknowledgeReceiptOfData() );
     * </code></pre>
     * <p>
     * If the session cannot be committed, an error will be logged and the session will be rolled back instead.
     *
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}).
     * @throws FlowFileHandlingException if not all {@link FlowFile}s acted upon within this session are accounted for
     *              such that they have a transfer identified or where marked for removal. Automated rollback occurs.
     */
    void commitAsync();

    /**
     * Commits the current session ensuring all operations against {@link FlowFile}s within this session are atomically persisted.
     * All FlowFiles operated on within this session must be accounted for by transfer or removal or the commit will fail.
     * <p>
     * If the session is successfully committed, the given {@code onSuccess} {@link Runnable} will be called.
     * At the point that the session commit is completed, any calls to {@link #rollback()} / {@link #rollback(boolean)}
     * will not undo that session commit but instead roll back any changes that may have occurred since.
     * <p>
     * If, for any reason, the session could not be committed, an error-level log message will be generated,
     * but the caller will not have a chance to perform any cleanup logic.
     * If such logic is necessary, use {@link #commitAsync(Runnable, Consumer)} instead.
     * <p>
     * Unlike the {@link #commit()} method, the persistence of data to the repositories
     * is not guaranteed to have occurred by the time that this method returns.
     *
     * @param onSuccess {@link Runnable} that will be called if and when the session is successfully committed; may be null
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}).
     * @throws FlowFileHandlingException if not all {@link FlowFile}s acted upon within this session are accounted for
     *              such that they have a transfer identified or where marked for removal. Automated rollback occurs.
     */
    default void commitAsync(Runnable onSuccess) {
        commitAsync(onSuccess, null);
    }

    /**
     * Commits the current session ensuring all operations against FlowFiles within this session are atomically persisted.
     * All FlowFiles operated on within this session must be accounted for by transfer or removal or the commit will fail.
     * <p>
     * If the session is successfully committed, the given {@code onSuccess} {@link Runnable} will be called.
     * At the point that the session commit is completed, any calls to {@link #rollback()} / {@link #rollback(boolean)}
     * will not undo that session commit but instead roll back any changes that may have occurred since.
     * <p>
     * If, for any reason, the session could not be committed, the given {@code onFailure} {@link Consumer} will be called
     * instead of the {@code onSuccess} {@link Runnable}.
     * The Consumer will be provided the Throwable that prevented the session commit from completing.
     * <p>
     * Unlike the {@link #commit()} method, the persistence of data to the repositories
     * is not guaranteed to have occurred by the time that this method returns.
     *
     * @param onSuccess {@link Runnable} that will be called if and when the session is successfully committed; may be null
     * @param onFailure {@link Consumer} that will be called if, for any reason, the session could not be committed; may be null
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}).
     * @throws FlowFileHandlingException if not all {@link FlowFile}s acted upon within this session are accounted for
     *              such that they have a transfer identified or where marked for removal. Automated rollback occurs.
     */
    void commitAsync(Runnable onSuccess, Consumer<Throwable> onFailure);

    /**
     * Reverts any changes made during this session.
     * All {@link FlowFile}s are restored back to their initial session state and back to their original queues.
     * If no changes were made since this session was last committed or rolled back, then this method has no effect.
     * This method can be called any number of times.
     * Calling this method is identical to calling {@link #rollback(boolean)} passing {@code false} as the parameter.
     */
    void rollback();

    /**
     * Reverts any changes made during this session.
     * All {@link FlowFile}s are restored back to their initial session state and back to their original queues,
     * after optionally being penalized.
     * If no changes were made since this session was last committed or rolled back, then this method has no effect.
     * This method can be called any number of times.
     *
     * @param penalize whether the {@link FlowFile}s that are being restored back to their queues should be penalized
     */
    void rollback(boolean penalize);

    /**
     * Migrates ownership of the given {@code flowFiles} {@link FlowFile}s from {@code this} session to the given {@code newOwner} {@link ProcessSession}.
     * <p>
     * Note, that for any provided FlowFile, if the FlowFile has any child (e.g., by calling {@link #create(FlowFile)}
     * and passing the FlowFile as the argument), then all children that were created must also be in the Collection of provided FlowFiles.
     * <p>
     * Also note, that if any FlowFile given is not the most up-to-date version of that FlowFile,
     * then the most up-to-date version of the FlowFile will be migrated to the new owner.
     * For example, if a call to {@link #putAttribute(FlowFile, String, String)} is made,
     * passing {@code flowFile1} as the FlowFile, and then {@code flowFile1} is passed to this method,
     * then the newest version (including the newly added attribute) will be migrated,
     * not the outdated version of the FlowFile that {@code flowFile1} points to.
     *
     * @param newOwner the {@link ProcessSession} that is to become the new owner of the given {@link FlowFile}s
     * @param flowFiles the {@link FlowFile}s to migrate
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for any of the affected {@link FlowFile}s
     */
    void migrate(ProcessSession newOwner, Collection<FlowFile> flowFiles);

    /**
     * Migrates ownership of all {@link FlowFile}s from {@code this} session to the given {@code newOwner} {@link ProcessSession}.
     * Calling this method is identical to calling {@link #migrate(ProcessSession, Collection)}
     * passing all FlowFiles owned by this session as the parameter,
     * this encompasses both FlowFiles retrieved from the work queue and newly created or cloned ones.
     *
     * @param newOwner the {@link ProcessSession} that is to become the new owner of all {@link FlowFile}s
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for any of the affected {@link FlowFile}s
     */
    void migrate(ProcessSession newOwner);

    /**
     * Adjusts counter data for the given counter name and takes care of registering the counter if not already present.
     * The adjustment occurs only if and when the process session is committed.
     *
     * @param name the name of the counter
     * @param delta the delta by which to modify the counter (+ or -)
     * @param immediate if true, the counter will be updated immediately, without regard to whether the session is committed or rolled back;
     *            otherwise, the counter will be incremented only if and when the session is committed.
     */
    void adjustCounter(String name, long delta, boolean immediate);

    /**
     * Returns the {@link FlowFile} from the work queue that is next highest priority to process.
     * If no FlowFiles are available, returns {@code null}.
     *
     * @return the {@link FlowFile} from the work queue that is next highest priority to process or {@code null}, if none available
     */
    FlowFile get();

    /**
     * Returns the next up to {@code maxResults} {@link FlowFile}s from the work queue that are the highest priority to process.
     * If no FlowFiles are available, returns an empty list. Will not return {@code null}.
     * <p>
     * If multiple incoming queues are present, the behavior is unspecified in terms of
     * whether all queues or only a single queue will be polled in a single call.
     *
     * @param maxResults the maximum number of {@link FlowFile}s to return
     * @return up to {@code maxResults} {@link FlowFile}s from the work queue
     * @throws IllegalArgumentException if {@code maxResults} is less than 0
     */
    List<FlowFile> get(int maxResults);

    /**
     * Returns all {@link FlowFile}s from all the incoming queues which the given {@link FlowFileFilter} accepts.
     * <p>
     * Calls to this method provide exclusive access to the underlying queues.
     * That is, no other thread will be permitted to pull FlowFiles from or add FlowFiles
     * to this {@link Processor}'s incoming queues until this method call has returned.
     *
     * @param filter a {@link FlowFileFilter} to limit which {@link FlowFile}s are returned
     * @return all {@link FlowFile}s from all the incoming queues which the given {@link FlowFileFilter} {@code filter} accepts.
     */
    List<FlowFile> get(FlowFileFilter filter);

    /**
     * Returns the {@link QueueSize} that represents the number of {@link FlowFile}s and their combined data size
     * for all FlowFiles waiting to be processed by the {@link Processor} that owns {@code this} {@link ProcessSession},
     * regardless of which connection the FlowFiles live on.
     *
     * @return the number of {@link FlowFile}s and their combined data size in the work queue
     */
    QueueSize getQueueSize();

    /**
     * Creates a new {@link FlowFile} in the repository with no content and without any linkage to a parent FlowFile.
     * <p>
     * This method is appropriate only when data is received or created from an external system.
     * Otherwise, this method should be avoided and instead {@link #create(FlowFile)} or {@link #create(Collection)} be used.
     * <p>
     * When this method is used, a {@link ProvenanceEventType#CREATE} or {@link ProvenanceEventType#RECEIVE} event should be generated.
     * See the {@link #getProvenanceReporter()} method and {@link ProvenanceReporter} class for more information.
     *
     * @return newly created FlowFile
     */
    FlowFile create();

    /**
     * Creates a new {@link FlowFile} in the repository with no content but with a parent linkage to the {@code parent}.
     * The newly created FlowFile will inherit all the parent's attributes, except for the UUID.
     * <p>
     * This method will automatically generate a {@link ProvenanceEventType#FORK} or a {@link ProvenanceEventType#JOIN} event,
     * depending on whether other FlowFiles are generated from the same parent before the session is committed.
     *
     * @param parent to base the new {@link FlowFile} on, inheriting attributes from
     * @return newly created {@link FlowFile}
     */
    FlowFile create(FlowFile parent);

    /**
     * Creates a new {@link FlowFile} in the repository with no content but with a parent linkage to all {@code parents}.
     * The newly created FlowFile will inherit all the attributes that are in common to all parents, except for the UUID.
     * <p>
     * This method will automatically generate a {@link ProvenanceEventType#JOIN} event.
     *
     * @param parents to base the new {@link FlowFile} on, inheriting shared attributes from
     * @return newly created {@link FlowFile}
     */
    FlowFile create(Collection<FlowFile> parents);

    /**
     * Creates a new {@link FlowFile} with a parent linkage to the {@code example} FlowFile.
     * It is a clone of the given FlowFile as of the time this is called, both in attributes and content.
     * <p>
     * This method will automatically generate a {@link ProvenanceEventType#CLONE} event.
     *
     * @param example {@link FlowFile} to be the source of cloning - given FlowFile must be a part of the given session
     * @return {@link FlowFile} that is a clone of the given {@code example} FlowFile
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code example} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content
     */
    FlowFile clone(FlowFile example);

    /**
     * Creates a new {@link FlowFile} with a parent linkage to the {@code parent} FlowFile.
     * It is a clone of the given FlowFile as of the time this is called, both in attributes and a subset of the content.
     * The content of the new FlowFile will be a subset of the byte sequence of the given FlowFile,
     * starting at the specified offset and with the length specified.
     * <p>
     * This method will automatically generate a {@link ProvenanceEventType#FORK} or a {@link ProvenanceEventType#CLONE} event,
     * if the offset is 0 and the size is exactly equal to the size of the example FlowFile.
     *
     * @param parent {@link FlowFile} to be the source of cloning - given FlowFile must be a part of the given session
     * @param offset of the parent {@link FlowFile}'s content to base the cloned FlowFile's content on
     * @param size in bytes of the parent {@link FlowFile}'s content to clone starting from the {@code offset}
     * @return {@link FlowFile} that is a partial clone of the given {@code parent} FlowFile whose content has the specified {@code size}
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code parent} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Or if the specified {@code offset} + {@code size} exceeds the size of the {@code parent} FlowFile's content.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content
     */
    FlowFile clone(FlowFile parent, long offset, long size);

    /**
     * Sets a penalty for the given {@link FlowFile},
     * which will make it unavailable to be operated on any further during the penalty period.
     *
     * @param flowFile to penalize
     * @return the penalized {@link FlowFile}
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     */
    FlowFile penalize(FlowFile flowFile);

    /**
     * Updates the given {@link FlowFile}'s attributes with the given {@code key} / {@code value} pair.
     * <p>
     * If the {@code key} is named {@code uuid}, this attribute will be ignored.
     *
     * @param flowFile to update
     * @param key of attribute to add or modify
     * @param value of attribute to add or modify
     * @return the updated {@link FlowFile} with the attribute added or modified
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     */
    FlowFile putAttribute(FlowFile flowFile, String key, String value);

    /**
     * Updates the given {@link FlowFile}'s attributes with the given {@code key} / {@code value} pairs.
     * <p>
     * If the map contains a key named {@code uuid}, this attribute will be ignored.
     *
     * @param flowFile to update
     * @param attributes the attributes to add or modify
     * @return the updated {@link FlowFile} with the attributes added or modified
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     */
    FlowFile putAllAttributes(FlowFile flowFile, Map<String, String> attributes);

    /**
     * Removes the attribute with the given {@code key} from the given {@link FlowFile}.
     * <p>
     * The attributes with the keys {@code uuid}, {@code path}, and {@code filename} will not be removed.
     * If the {@code key} is one of those, this method will return the same FlowFile without removing any attribute.
     *
     * @param flowFile to update
     * @param key of attribute to remove
     * @return the updated {@link FlowFile} with the matching attribute removed
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     */
    FlowFile removeAttribute(FlowFile flowFile, String key);

    /**
     * Removes the attributes with the given {@code keys} from the given {@link FlowFile}.
     * <p>
     * The attributes with the keys {@code uuid}, {@code path}, and {@code filename} will not be removed.
     *
     * @param flowFile to update
     * @param keys of attributes to remove
     * @return the updated {@link FlowFile} with the matching attributes removed
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     */
    FlowFile removeAllAttributes(FlowFile flowFile, Set<String> keys);

    /**
     * Removes all attributes from the given {@link FlowFile} whose key matches the given pattern.
     * <p>
     * The attributes with the keys {@code uuid}, {@code path}, and {@code filename} will not be removed.
     *
     * @param flowFile to update
     * @param keyPattern pattern to match each {@link FlowFile} attribute against; may be null, in which case no attribute is removed
     * @return the updated {@link FlowFile} with the matching attributes removed
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     */
    FlowFile removeAllAttributes(FlowFile flowFile, Pattern keyPattern);

    /**
     * Transfers the given {@link FlowFile} back to the work queue from which it was pulled.
     * <p>
     * The processor will not be able to operate on the given FlowFile until this session is committed.
     * Any modifications that have been made to the FlowFile will be maintained.
     * FlowFiles that are created by the processor cannot be transferred back to themselves via this method.
     *
     * @param flowFile to transfer
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws IllegalArgumentException if the given {@link FlowFile} was created by this processor
     */
    void transfer(FlowFile flowFile);

    /**
     * Transfers the given {@link FlowFile}s back to the work queues from which the FlowFiles were pulled.
     * <p>
     * The processor will not be able to operate on the given FlowFiles until this session is committed.
     * Any modifications that have been made to the FlowFiles will be maintained.
     * FlowFiles that are created by the processor cannot be transferred back to themselves via this method.
     *
     * @param flowFiles to transfer
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if any of the given {@link FlowFile}s is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws IllegalArgumentException if any of the given {@link FlowFile}s was created by this processor
     */
    void transfer(Collection<FlowFile> flowFiles);

    /**
     * Transfers the given {@link FlowFile} to the appropriate destination processor work queue(s) based on the given {@code relationship}.
     * <p>
     * If the relationship leads to more than one destination the state of the FlowFile is replicated
     * such that each destination receives an exact copy of the FlowFile though each will have its own unique identity.
     * The destination processors will not be able to operate on the given FlowFile until this session is committed or
     * until the ownership of the session is migrated to another processor.
     * If ownership of the session is passed to a destination processor then that destination processor will have immediate visibility
     * of the transferred FlowFiles within the session.
     *
     * @param flowFile to transfer
     * @param relationship to transfer to
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws IllegalArgumentException if given relationship is not a known or registered relationship
     */
    void transfer(FlowFile flowFile, Relationship relationship);

    /**
     * Transfers the given {@link FlowFile}s to the appropriate destination processor work queue(s) based on the given {@code relationship}.
     * <p>
     * If the relationship leads to more than one destination the state of each FlowFile is replicated
     * such that each destination receives an exact copy of the FlowFile though each will have its own unique identity.
     * The destination processors will not be able to operate on the given FlowFiles until this session is committed or
     * until the ownership of the session is migrated to another processor.
     * If ownership of the session is passed to a destination processor then that destination processor will have immediate visibility
     * of the transferred FlowFiles within the session.
     *
     * @param flowFiles to transfer
     * @param relationship to transfer to
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for any of the {@code flowFiles} {@link FlowFile}s
     * @throws FlowFileHandlingException if any of the given {@link FlowFile}s is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws IllegalArgumentException if given relationship is not a known or registered relationship
     */
    void transfer(Collection<FlowFile> flowFiles, Relationship relationship);

    /**
     * Ends the managed persistence for the given {@link FlowFile}.
     * <p>
     * The persistent attributes for the FlowFile are deleted and so is the content assuming nothing else references it.
     * This FlowFile will no longer be available for further operation.
     *
     * @param flowFile to remove
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the given {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     */
    void remove(FlowFile flowFile);

    /**
     * Ends the managed persistence for the given {@link FlowFile}s.
     * <p>
     * The persistent attributes for the FlowFiles are deleted and so is the content assuming nothing else references it.
     * The FlowFiles will no longer be available for further operation.
     *
     * @param flowFiles to remove
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for any of the given {@code flowFiles} {@link FlowFile}s
     * @throws FlowFileHandlingException if any of the given {@link FlowFile}s is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     */
    void remove(Collection<FlowFile> flowFiles);

    /**
     * Executes the given {code reader} {@link InputStreamCallback} against the content of the given {@link FlowFile}.
     *
     * @param source the {@link FlowFile} to retrieve the content from
     * @param reader {@link InputStreamCallback} that will be called to read the {@link FlowFile} content
     * @throws IllegalStateException if detected that this method is being called from within a write callback
     *              (see {@link #write(FlowFile, StreamCallback)}, {@link #write(FlowFile, OutputStreamCallback)})
     *              or while a write stream is open (see {@link #write(FlowFile)}) for the given {@code source} {@link FlowFile}.
     *              Said another way, it is not permissible to call this method while writing to the same FlowFile.
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content;
     *              if an attempt is made to access the {@link InputStream} provided to the given {@link InputStreamCallback}
     *              after this method completed its execution
     */
    void read(FlowFile source, InputStreamCallback reader) throws FlowFileAccessException;

    /**
     * Provides an {@link InputStream} that can be used to read the content of the given {@link FlowFile}.
     * <p>
     * This method differs from those that make use of callbacks in that this method returns an InputStream and expects the caller
     * to properly handle the lifecycle of the InputStream (i.e., the caller is responsible for ensuring that the InputStream is closed appropriately).
     * The session may or may not handle closing the stream when the session is commited or rolled back,
     * but the responsibility of doing so belongs to the caller.
     *
     * @param flowFile the {@link FlowFile} to retrieve the content from
     * @return an {@link InputStream} that can be used to read the content of the {@link FlowFile}
     * @throws IllegalStateException if detected that this method is being called from within a write callback
     *              (see {@link #write(FlowFile, StreamCallback)}, {@link #write(FlowFile, OutputStreamCallback)})
     *              or while a write stream is open (see {@link #write(FlowFile)}) for the given {@code flowFile} {@link FlowFile}.
     *              Said another way, it is not permissible to call this method while writing to the same FlowFile.
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content;
     *              if an attempt is made to read from the stream after the session is committed or rolled back.
     */
    InputStream read(FlowFile flowFile);

    /**
     * Combines the content of all given {@code sources} {@link FlowFile}s into a single given destination FlowFile.
     *
     * @param sources the {@link FlowFile}s whose content to merge
     * @param destination the {@link FlowFile} to use as the merged result
     * @return the updated {@code destination} destination {@link FlowFile} with changed content
     * @throws IllegalArgumentException if the given destination is contained within the sources
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for any of the given {@code sources} and {@code destination} {@link FlowFile}s
     * @throws FlowFileHandlingException if any of the given {@link FlowFile}s is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if any of the given {@link FlowFile}'s content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content;
     *              the state of the {@code destination} {@link FlowFile} will be as it was prior to this call.
     */
    FlowFile merge(Collection<FlowFile> sources, FlowFile destination);

    /**
     * Combines the content of all given {@code sources} {@link FlowFile}s into a single given destination FlowFile.
     *
     * @param sources the {@link FlowFile}s whose content to merge
     * @param destination the {@link FlowFile} to use as the merged result
     * @param header bytes that will be added to the beginning of the merged output; may be null or empty
     * @param footer bytes that will be added to the end of the merged output; may be null or empty
     * @param demarcator bytes that will be placed in between each object merged together; may be null or empty
     * @return the updated {@code destination} {@link FlowFile} with changed content
     * @throws IllegalArgumentException if the given destination is contained within the sources
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for any of the given {@code sources} and {@code destination} {@link FlowFile}s
     * @throws FlowFileHandlingException if any of the given {@link FlowFile}s is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if any of the given {@link FlowFile}'s content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content;
     *              the state of the {@code destination} {@link FlowFile} will be as it was prior to this call.
     */
    FlowFile merge(Collection<FlowFile> sources, FlowFile destination, byte[] header, byte[] footer, byte[] demarcator);

    /**
     * Executes the given {code writer} {@link OutputStreamCallback} against the content of the given {@link FlowFile}.
     *
     * @param source the {@link FlowFile} to write the content of
     * @param writer {@link InputStreamCallback} that will be called to write the {@link FlowFile} content
     * @return the updated {@code source} {@link FlowFile} with changed content
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the given {@code source} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content;
     *              if an attempt is made to access the {@link OutputStream} provided to the given {@link OutputStreamCallback}
     *              after this method completed its execution
     */
    FlowFile write(FlowFile source, OutputStreamCallback writer) throws FlowFileAccessException;

    /**
     * Provides an {@link OutputStream} that can be used to write the content of the given {@link FlowFile}.
     * <p>
     * This method differs from those that make use of callbacks in that this method returns an OutputStream and expects the caller
     * to properly handle the lifecycle of the OutputStream (i.e., the caller is responsible for ensuring that the OutputStream is closed appropriately).
     * The session may or may not handle closing the stream when the session is commited or rolled back,
     * but the responsibility of doing so belongs to the caller.
     *
     * @param source the {@link FlowFile} to write the content of
     * @return an {@link OutputStream} that can be used to write the content of the {@link FlowFile}
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the given {@code source} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content;
     *              if an attempt is made to write to the stream after the session is committed or rolled back.
     */
    OutputStream write(FlowFile source);

    /**
     * Executes the given {code writer} {@link StreamCallback} against the content of the given {@link FlowFile}.
     *
     * @param source the {@link FlowFile} to read and write the content of
     * @param writer {@link StreamCallback} that will be called to read and write the {@link FlowFile} content
     * @return the updated {@code source} {@link FlowFile} with changed content
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the given {@code source} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content;
     *              if an attempt is made to access the {@link InputStream} or {@link OutputStream}
     *              provided to the given {@link StreamCallback} after this method completed its execution
     */
    FlowFile write(FlowFile source, StreamCallback writer) throws FlowFileAccessException;

    /**
     * Executes the given {code writer} {@link OutputStreamCallback} against the content of the given {@link FlowFile},
     * such that any data written to the OutputStream will be appended to the end of FlowFile's content.
     *
     * @param source the {@link FlowFile} to extend the content of
     * @param writer {@link OutputStreamCallback} that will be called to append the {@link FlowFile}'s content
     * @return the updated {@code source} {@link FlowFile} with changed content
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the given {@code source} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content;
     *              if an attempt is made to access the {@link OutputStream} provided to the given {@link OutputStreamCallback}
     *              after this method completed its execution
     */
    FlowFile append(FlowFile source, OutputStreamCallback writer) throws FlowFileAccessException;

    /**
     * Writes to contents of the file a the {@code source} {@link Path} to the given {@link FlowFile}'s content.
     *
     * @param source the {@link Path} to the file from which content will be obtained
     * @param keepSourceFile if true the content is simply copied;
     *              if false the original content might be used in a destructive way for efficiency,
     *              such that the repository will have the data but the original data will be gone.
     *              If false the source object will be removed or gone once imported.
     *              It will not be restored if the session is rolled back so this must be used with caution.
     *              In some cases it can result in tremendous efficiency gains but is also dangerous.
     * @param destination the {@link FlowFile} whose content will be updated
     * @return the updated {@code destination} {@link FlowFile} with changed content
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the given {@code source} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content
     */
    FlowFile importFrom(Path source, boolean keepSourceFile, FlowFile destination);

    /**
     * Writes to contents of the {@code source} {@link InputStream} to the given {@link FlowFile}'s content.
     *
     * @param source the {@link InputStream} from which content will be obtained
     * @param destination the {@link FlowFile} whose content will be updated
     * @return the updated {@code destination} {@link FlowFile} with changed content
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the given {@code source} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content
     */
    FlowFile importFrom(InputStream source, FlowFile destination);

    /**
     * Writes the content of the given {@link FlowFile} to the file at the given {@code destination} {@link Path}.
     *
     * @param flowFile the {@link FlowFile} to export the content of
     * @param destination the {@link Path} to a file to export the {@link FlowFile}'s content to
     * @param append if true will append to the current content of the file at the given path;
     *              if false will replace any current content
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the given {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content
     */
    void exportTo(FlowFile flowFile, Path destination, boolean append);

    /**
     * Writes the content of the given {@link FlowFile} to given {@code destination} {@link OutputStream}.
     *
     * @param flowFile the {@link FlowFile} to export the content of
     * @param destination the {@link OutputStream} to export the {@link FlowFile}'s content to
     * @throws IllegalStateException if detected that this method is being called from within a read or write callback
     *              (see {@link #read(FlowFile, InputStreamCallback)}, {@link #write(FlowFile, StreamCallback)},
     *              {@link #write(FlowFile, OutputStreamCallback)}) or while a read or write stream is open
     *              (see {@link #read(FlowFile)}, {@link #write(FlowFile)}) for the given {@code flowFile} {@link FlowFile}
     * @throws FlowFileHandlingException if the given {@link FlowFile} is already transferred or removed or doesn't belong to this session.
     *              Automatic rollback will occur.
     * @throws MissingFlowFileException if the given {@link FlowFile} content cannot be found.
     *              The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.
     * @throws FlowFileAccessException if some IO problem occurs accessing {@link FlowFile} content
     */
    void exportTo(FlowFile flowFile, OutputStream destination);

    /**
     * Returns the {@link ProvenanceReporter} that is tied to {@code this} {@link ProcessSession}.
     *
     * @return the {@link ProvenanceReporter} that is tied to {@code this} {@link ProcessSession}
     */
    ProvenanceReporter getProvenanceReporter();

    /**
     * Updates the value of the component's state, setting it to given value.
     * <p>
     * This method does update the remote State Provider immediately but rather caches the value until the session is committed.
     * At that point, it will publish the state to the remote State Provider, if the state is the latest according to the remote State Provider.
     *
     * @param state the value to change the state to
     * @param scope the {@link Scope} to use when storing the state
     * @throws IOException if unable to communicate with the underlying storage mechanism
     */
    void setState(Map<String, String> state, Scope scope) throws IOException;

    /**
     * Returns the current state for the component.
     * <p>
     * This return value will never be {@code null}.
     * If the state has not yet been set, the StateMap's version will be -1, and the map of values will be empty.
     *
     * @param scope the {@link Scope} to use when fetching the state
     * @return the current state for the component
     * @throws IOException if unable to communicate with the underlying storage mechanism
     */
    StateMap getState(Scope scope) throws IOException;

    /**
     * Updates the value of the component's state, setting it to given {@code newValue},
     * if and only if the current value is the same as the given {@code oldValue}.
     * <p>
     * The oldValue will be compared against the value of the state as it is known to {@code this} {@link ProcessSession}.
     * If the Process Session does not currently know the state, it will be fetched from the StateProvider.
     * <p>
     * This method does update the remote State Provider immediately but rather caches the value until the session is committed.
     * At that point, it will publish the state to the remote State Provider, if the state is the latest according to the remote State Provider.
     *
     * @param oldValue the value to compare the state's current value against
     * @param newValue the new value to use if and only if the state's current value is the same as the given {@code oldValue}
     * @param scope the {@link Scope} to use for fetching the current and storing the new state
     * @return {@code true} if the state was updated to the {@code newValue},
     *              {@code false} if the state's current value was not equal to {@code oldValue}
     * @throws IOException if unable to communicate with the underlying storage mechanism
     */
    boolean replaceState(StateMap oldValue, Map<String, String> newValue, Scope scope) throws IOException;

    /**
     * Clears all keys and values from the component's state.
     * <p>
     * This method does update the remote State Provider immediately but rather caches the value until the session is committed.
     * At that point, it will publish the state to the remote State Provider, if the state is the latest according to the remote State Provider.
     *
     * @param scope the {@link Scope} to use for clearing the state
     * @throws IOException if unable to communicate with the underlying storage mechanism.
     */
    void clearState(Scope scope) throws IOException;
}
