exceptionfactory commented on code in PR #8620:
URL: https://github.com/apache/nifi/pull/8620#discussion_r1558294655
##########
nifi-api/src/main/java/org/apache/nifi/processor/ProcessSession.java:
##########
@@ -173,846 +120,783 @@ public interface ProcessSession {
* 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 called from within a callback (See
{@link #write(FlowFile, StreamCallback)}, {@link #write(FlowFile,
OutputStreamCallback)},
- * {@link #read(FlowFile, InputStreamCallback)}).
+ * @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() {
Review Comment:
This appears to be a new method.
##########
nifi-api/src/main/java/org/apache/nifi/processor/ProcessSession.java:
##########
@@ -173,846 +120,783 @@ public interface ProcessSession {
* 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 called from within a callback (See
{@link #write(FlowFile, StreamCallback)}, {@link #write(FlowFile,
OutputStreamCallback)},
- * {@link #read(FlowFile, InputStreamCallback)}).
+ * @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() {
+ commitAsync(null, null);
+ }
+
+ /**
+ * 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.
*
- * @throws FlowFileHandlingException if any FlowFile is not appropriately
accounted for by transferring it to a Relationship (see {@link
#transfer(FlowFile, Relationship)})
- * or removed (see {@link #remove(FlowFile)}.
+ * @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>
- * 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>
- *
- * <p>
- * If the session is successfully committed, the given
<code>onSuccess</code> {@link Runnable} will be called.
- * At the point that the session commit is completed, the session will
have already been committed, so any calls
- * to {@link #rollback()} / {@link #rollback(boolean)} will not undo that
session commit but instead roll back any chances
- * that may have occurred since.
- * </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</code> {@link Consumer} will be called
- * instead of the <code>onSuccess</code> {@link Runnable}. The Consumer
will be provided the Throwable that prevented the session
- * commit from completing.
- * </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.
- * </p>
- *
- * @throws IllegalStateException if called from within a callback (See
{@link #write(FlowFile, StreamCallback)}, {@link #write(FlowFile,
OutputStreamCallback)},
- * {@link #read(FlowFile, InputStreamCallback)}).
- *
- * @throws FlowFileHandlingException if any FlowFile is not appropriately
accounted for by transferring it to a Relationship (see {@link
#transfer(FlowFile, Relationship)})
- * or removed (see {@link #remove(FlowFile)}.
+ * 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 FlowFiles are restored
- * back to their initial session state and back to their original queues.
If
- * this session is already committed or rolled back then no changes will
- * occur. This method can be called any number of times. Calling this
method
- * is identical to calling {@link #rollback(boolean)} passing
- * <code>false</code> as the parameter.
+ * 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 FlowFiles are restored
- * back to their initial session state and back to their original queues,
- * after optionally being penalized. If this session is already committed
or
- * rolled back then no changes will occur. This method can be called any
- * number of times.
+ * 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 or not the FlowFiles that are being restored
back
- * to their queues should be penalized
+ * @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>
- * Migrates ownership of the given FlowFiles from {@code this} to the
given {@code newOwner}.
- * </p>
- *
- * <p>
- * When calling this method, all of the following pre-conditions must be
met:
- * </p>
- *
- * <ul>
- * <li>This method cannot be called from within a callback
- * (see {@link #write(FlowFile, OutputStreamCallback)}, {@link
#write(FlowFile, StreamCallback)},
- * {@link #read(FlowFile, InputStreamCallback)}, {@link #read(FlowFile,
boolean, InputStreamCallback)} for any of
- * the given FlowFiles.</li>
- * <li>No InputStream can be open for the content of any of the given
FlowFiles (see {@link #read(FlowFile)}).</li>
- * <li>No OutputStream can be open for the content of any of the given
FlowFiles (see {@link #write(FlowFile)}.</li>
- * <li>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.</li>
- * </ul>
- *
+ * 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</code> as the FlowFile, and then
<code>flowFile1</code> 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</code> points to.
- * </p>
- *
- * @param newOwner the ProcessSession that is to become the new owner of
the given FlowFiles
- * @param flowFiles the FlowFiles to migrate
+ * 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 all FlowFiles to the given new owner as described in {@link
#migrate(ProcessSession, Collection)}
- * @param newOwner the ProcessSession that is to become the new owner of
all 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 ProcessSession is committed.
+ * 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 ProcessSession is commit or
rolled back;
- * otherwise, the counter will be incremented only if and when
the
- * ProcessSession is committed.
+ * @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);
/**
- * @return FlowFile that is next highest priority FlowFile to process.
- * Otherwise returns null.
+ * 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 up to <code>maxResults</code> FlowFiles from the work queue. If
- * no FlowFiles are available, returns an empty list. Will not return null.
- * 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.
+ * 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 FlowFiles to return
- * @return up to <code>maxResults</code> FlowFiles from the work queue. If
- * no FlowFiles are available, returns an empty list. Will not return null.
- * @throws IllegalArgumentException if <code>maxResults</code> is less than
- * 0
+ * @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>
- * Returns all FlowFiles from all of the incoming queues for which the
given
- * {@link FlowFileFilter} indicates should be accepted. Calls to this
method
- * provide exclusive access to the underlying queues. I.e., no other thread
- * will be permitted to pull FlowFiles from this Processor's queues or add
- * FlowFiles to this Processor's incoming queues until this method call has
- * returned.
- * </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 to limit which flow files are returned
- * @return all FlowFiles from all of the incoming queues for which the
given
- * {@link FlowFileFilter} indicates should be accepted.
+ * @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);
/**
- * @return the QueueSize that represents the number of FlowFiles and their
- * combined data size for all FlowFiles waiting to be processed by the
- * Processor that owns this ProcessSession, regardless of which Connection
- * the FlowFiles live on
+ * 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 FlowFile in the repository with no content and without any
- * linkage to a parent FlowFile. This method is appropriate only when data
- * is received or created from an external system. Otherwise, this method
- * should be avoided and should instead use {@link #create(FlowFile)} or
- * {@see #create(Collection)}.
- *
- * When this method is used, a Provenance CREATE or RECEIVE Event should be
- * generated. See the {@link #getProvenanceReporter()} method and
- * {@link ProvenanceReporter} class for more information
+ * 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 FlowFile in the repository with no content but with a
- * parent linkage to <code>parent</code>. The newly created FlowFile will
- * inherit all of the parent's attributes except for the UUID. This method
- * will automatically generate a Provenance FORK event or a Provenance JOIN
- * event, depending on whether or not other FlowFiles are generated from
the
- * same parent before the ProcessSession is committed.
+ * 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 flowfile on
- * @return newly created flowfile
+ * @param parent to base the new {@link FlowFile} on, inheriting
attributes from
+ * @return newly created {@link FlowFile}
*/
FlowFile create(FlowFile parent);
/**
- * Creates a new FlowFile in the repository with no content but with a
- * parent linkage to the FlowFiles specified by the parents Collection. The
- * newly created FlowFile will inherit all of the attributes that are in
- * common to all parents (except for the UUID, which will be in common if
- * only a single parent exists). This method will automatically generate a
- * Provenance JOIN event.
+ * 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 which the new flowfile should inherit shared attributes
from
- * @return new flowfile
+ * @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 FlowFile that is a clone of the given FlowFile as of the
- * time this is called, both in content and attributes. This method
- * automatically emits a Provenance CLONE Event.
- *
- * @param example FlowFile to be the source of cloning - given FlowFile
must
- * be a part of the given session
- * @return FlowFile that is a clone of the given example
- * @throws IllegalStateException if detected that this method is being
- * called from within a callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
- * @throws MissingFlowFileException if the given FlowFile content cannot be
- * found. The FlowFile should no longer be reference, will be internally
- * destroyed, and the session is automatically rolled back and what is left
- * of the FlowFile is destroyed.
- * @throws FlowFileAccessException if some IO problem occurs accessing
- * FlowFile content
- * @throws NullPointerException if the argument null
+ * 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 FlowFile whose parent is the given FlowFile. 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.
- * The new FlowFile will contain all of the attributes of the original.
This
- * method automatically emits a Provenance FORK Event (or a Provenance
CLONE
- * Event, if the offset is 0 and the size is exactly equal to the size of
- * the example FlowFile).
- *
- * @param parent to base the new flowfile attributes on
- * @param offset of the parent flowfile to base the child flowfile content
on
- * @param size of the new flowfile from the offset
- * @return a FlowFile with the specified size whose parent is first
argument
- * to this function
- *
- * @throws IllegalStateException if detected that this method is being
- * called from within a callback of another method in this session and for
- * the given FlowFile
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session, or if the
- * specified offset + size exceeds that of the size of the parent FlowFile.
- * Automatic rollback will occur.
- * @throws MissingFlowFileException if the given FlowFile content cannot be
- * found. The FlowFile should no longer be reference, will be internally
- * destroyed, and the session is automatically rolled back and what is left
- * of the FlowFile is destroyed.
+ * 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 FlowFile which will make it unavailable to
- * be operated on any further during the penalty period.
+ * 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 FlowFile the new FlowFile reference to use
- * @throws IllegalStateException if detected that this method is being
- * called from within a callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
- * @throws NullPointerException if the argument null
+ * @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 FlowFiles attributes with the given key/value pair. If
- * the key is named {@code uuid}, this attribute will be ignored.
+ * 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
- * @param value of attribute
- * @return FlowFile the updated FlowFile
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
- * @throws NullPointerException if an argument is null
+ * @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 FlowFiles attributes with the given key/value pairs.
If
- * the map contains a key named {@code uuid}, this attribute will be
- * ignored.
+ * 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 to the given FlowFile
- * @return FlowFile the updated FlowFile
- * @throws IllegalStateException if detected that this method is being
- * called from within a callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
- * @throws NullPointerException if an argument is null
+ * @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 given FlowFile attribute with the given key. If the key is
- * named {@code uuid}, this method will return the same FlowFile without
- * removing any attribute.
+ * Removes the attribute with the given {@code key} from the given {@link
FlowFile}.
+ * <p>
+ * If the {@code key} is named {@code uuid}, this method will return the
same FlowFile without removing any attribute.
*
* @param flowFile to update
- * @param key of attribute
- * @return FlowFile the updated FlowFile
- * @throws IllegalStateException if detected that this method is being
- * called from within a callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
- * @throws NullPointerException if the argument null
+ * @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 keys from the given FlowFile. If
- * the set of keys contains the value {@code uuid}, this key will be
ignored
+ * Removes the attributes with the given {@code keys} from the given
{@link FlowFile}.
+ * <p>
+ * If the set of keys contains the value {@code uuid}, this key will be
ignored.
*
* @param flowFile to update
- * @param keys of attribute
- * @return FlowFile the updated FlowFile
- * @throws IllegalStateException if detected that this method is being
- * called from within a callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
- * @throws NullPointerException if the argument null
+ * @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);
/**
- * Remove all attributes from the given FlowFile that have keys which match
- * the given pattern. If the pattern matches the key {@code uuid}, this key
- * will not be removed.
+ * Removes all attributes from the given {@link FlowFile} whose key
matches the given pattern.
+ * <p>
+ * If the pattern matches the key {@code uuid}, this key will not be
removed.
*
* @param flowFile to update
- * @param keyPattern may be null; if supplied is matched against each of
the
- * FlowFile attribute keys
- * @return FlowFile containing only attributes which did not meet the key
- * pattern
+ * @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 FlowFile to the appropriate destination processor
- * work queue(s) based on the given relationship. 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.
+ * 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
- * @param relationship to transfer to
- * @throws IllegalStateException if detected that this method is being
- * called from within a callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
- * @throws NullPointerException if the argument null
- * @throws IllegalArgumentException if given relationship is not a known or
- * registered relationship
+ * @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, Relationship relationship);
+ void transfer(FlowFile flowFile);
/**
- * Transfers the given FlowFile back to the work queue from which it was
- * pulled. 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.
+ * 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 flowFile to transfer
- * @throws IllegalStateException if detected that this method is being
- * called from within a callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
- * @throws IllegalArgumentException if the FlowFile was created by this
- * processor
- * @throws NullPointerException if the argument null
+ * @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(FlowFile flowFile);
+ void transfer(Collection<FlowFile> flowFiles);
/**
- * Transfers the given FlowFiles back to the work queues from which the
- * FlowFiles were pulled. 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.
+ * 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 flowFiles to transfer
- * @throws IllegalStateException if detected that this method is being
- * called from within a callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFiles are already
- * transferred or removed or don't belong to this session. Automatic
- * rollback will occur.
- * @throws IllegalArgumentException if the FlowFile was created by this
- * processor
- * @throws NullPointerException if the argument null
+ * @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(Collection<FlowFile> flowFiles);
+ void transfer(FlowFile flowFile, Relationship relationship);
/**
- * Transfers the given FlowFile to the appropriate destination processor
- * work queue(s) based on the given relationship. 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.
+ * 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 callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
- * @throws NullPointerException if the argument null
- * @throws IllegalArgumentException if given relationship is not a known or
- * registered relationship
+ * @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 FlowFile. The persistent
- * attributes for the FlowFile are deleted and so is the content assuming
- * nothing else references it and this FlowFile will no longer be available
- * for further operation.
+ * 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 callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
+ * @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 FlowFiles. The persistent
- * attributes for the FlowFile are deleted and so is the content assuming
- * nothing else references it and this FlowFile will no longer be available
- * for further operation.
+ * 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 callback of another method in this session and for
- * the given FlowFile(s)
- * @throws FlowFileHandlingException if any of the given FlowFile is
already
- * transferred or removed or doesn't belong to this session. Automatic
- * rollback will occur.
+ * @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 callback against the contents corresponding to the
- * given FlowFile.
- *
- * @param source flowfile to retrieve content of
- * @param reader that will be called to read the flowfile content
- * @throws IllegalStateException if detected that this method is being
- * called from within a write callback of another method
(i.e., from within the callback
- * that is passed to {@link #write(FlowFile,
OutputStreamCallback)} or {@link #write(FlowFile, StreamCallback)})
- * or has an OutputStream open (via a call to {@link
#write(FlowFile)}) in this session and for
- * the given FlowFile(s). Said another way, it is not
permissible to call this method while writing to
- * the same FlowFile.
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session.
Automatic
- * rollback will occur.
- * @throws MissingFlowFileException if the given FlowFile content cannot be
- * found. The FlowFile should no longer be referenced, will be
internally
- * destroyed, and the session is automatically rolled back and
what is left
- * of the FlowFile is destroyed.
- * @throws FlowFileAccessException if some IO problem occurs accessing
- * FlowFile content; if an attempt is made to access the
InputStream
- * provided to the given InputStreamCallback after this method
completed its
- * execution
+ * 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 InputStream that can be used to read the contents of the
given FlowFile.
- * 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 Process Session may or may not handle closing the stream when
{@link #commit()} or {@link #rollback()}
- * is called, but the responsibility of doing so belongs to the caller.
The InputStream will throw
- * an IOException if an attempt is made to read from the stream after the
session is committed or
- * rolled back.
- *
- * @param flowFile the FlowFile to read
- * @return an InputStream that can be used to read the contents of the
FlowFile
- * @throws IllegalStateException if detected that this method is being
- * called from within a write callback of another method
(i.e., from within the callback
- * that is passed to {@link #write(FlowFile,
OutputStreamCallback)} or {@link #write(FlowFile, StreamCallback)})
- * or has an OutputStream open (via a call to {@link
#write(FlowFile)}) in this session and for
- * the given FlowFile(s). Said another way, it is not
permissible to call this method while writing to
- * the same FlowFile.
- * @throws FlowFileHandlingException if the given FlowFile is already
- * transferred or removed or doesn't belong to this session.
Automatic
- * rollback will occur.
- * @throws MissingFlowFileException if the given FlowFile content cannot be
- * found. The FlowFile should no longer be referenced, will be
internally
- * destroyed, and the session is automatically rolled back and
what is left
- * of the FlowFile is destroyed.
+ * 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.
+ */
+ default FlowFile merge(Collection<FlowFile> sources, FlowFile destination)
{
Review Comment:
This appears to be a new method.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
