org.apache.nifi.processor

Interface ProcessSession

public interface ProcessSession

A process session encompasses all the behaviors a processor can perform to obtain, clone, read, modify remove FlowFiles in an atomic unit. A process session is always tied to a single 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 ProcessSession is always required to manage the session.

A session is not considered thread safe. The session supports a unit of work that is either committed or rolled back

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.

A process session has two 'terminal' methods that will result in the process session being in a 'fresh', 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 the commit() and rollback(). Additionally, the migrate(ProcessSession, Collection) method results in this containing no knowledge of any of the FlowFiles that are provided, as if the FlowFiles never existed in this ProcessSession. After each commit or rollback, the session can be used again. Note, however, that even if all FlowFiles are migrated via the migrate(ProcessSession, Collection) method, this Process Session is not entirely cleared, as it still has knowledge of Counters that were adjusted via the adjustCounter(String, long, boolean) method. A commit or rollback will clear these counters, as well.

Method Summary

Modifier and Type	Method and Description
void	adjustCounter(String name, long delta, boolean immediate) Adjusts counter data for the given counter name and takes care of registering the counter if not already present.
FlowFile	append(FlowFile source, OutputStreamCallback writer) Executes the given callback against the content corresponding to the given FlowFile, such that any data written to the OutputStream of the content will be appended to the end of FlowFile.
void	clearState(Scope scope) Clears all keys and values from the component's state when the session is committed
FlowFile	clone(FlowFile example) Creates a new FlowFile that is a clone of the given FlowFile as of the time this is called, both in content and attributes.
FlowFile	clone(FlowFile parent, long offset, long size) Creates a new FlowFile whose parent is the given FlowFile.
void	commit() Commits the current session ensuring all operations against FlowFiles within this session are atomically persisted.
void	commitAsync() Commits the current session ensuring all operations against FlowFiles within this session are atomically persisted.
default void	commitAsync(Runnable onSuccess) Commits the current session ensuring all operations against FlowFiles within this session are atomically persisted.
void	commitAsync(Runnable onSuccess, Consumer<Throwable> onFailure) Commits the current session ensuring all operations against FlowFiles within this session are atomically persisted.
FlowFile	create() Creates a new FlowFile in the repository with no content and without any linkage to a parent FlowFile.
FlowFile	create(Collection<FlowFile> parents) Creates a new FlowFile in the repository with no content but with a parent linkage to the FlowFiles specified by the parents Collection.
FlowFile	create(FlowFile parent) Creates a new FlowFile in the repository with no content but with a parent linkage to parent.
void	exportTo(FlowFile flowFile, OutputStream destination) Writes the content of the given FlowFile to the given destination stream
void	exportTo(FlowFile flowFile, Path destination, boolean append) Writes the content of the given FlowFile to the given destination path.
FlowFile	get()
List<FlowFile>	get(FlowFileFilter filter) Returns all FlowFiles from all of the incoming queues for which the given FlowFileFilter indicates should be accepted.
List<FlowFile>	get(int maxResults) Returns up to maxResults FlowFiles from the work queue.
ProvenanceReporter	getProvenanceReporter() Returns a ProvenanceReporter that is tied to this ProcessSession.
QueueSize	getQueueSize()
StateMap	getState(Scope scope) Returns the current state for the component.
FlowFile	importFrom(InputStream source, FlowFile destination) Writes to the given FlowFile all content from the given content path.
FlowFile	importFrom(Path source, boolean keepSourceFile, FlowFile destination) Writes to the given FlowFile all content from the given content path.
FlowFile	merge(Collection<FlowFile> sources, FlowFile destination) Combines the content of all given source FlowFiles into a single given destination FlowFile.
FlowFile	merge(Collection<FlowFile> sources, FlowFile destination, byte[] header, byte[] footer, byte[] demarcator) Combines the content of all given source FlowFiles into a single given destination FlowFile.
void	migrate(ProcessSession newOwner) Migrates all FlowFiles to the given new owner as described in migrate(ProcessSession, Collection)
void	migrate(ProcessSession newOwner, Collection<FlowFile> flowFiles) Migrates ownership of the given FlowFiles from this to the given newOwner.
FlowFile	penalize(FlowFile flowFile) Sets a penalty for the given FlowFile which will make it unavailable to be operated on any further during the penalty period.
FlowFile	putAllAttributes(FlowFile flowFile, Map<String,String> attributes) Updates the given FlowFiles attributes with the given key/value pairs.
FlowFile	putAttribute(FlowFile flowFile, String key, String value) Updates the given FlowFiles attributes with the given key/value pair.
InputStream	read(FlowFile flowFile) Provides an InputStream that can be used to read the contents of the given FlowFile.
void	read(FlowFile source, boolean allowSessionStreamManagement, InputStreamCallback reader) Executes the given callback against the contents corresponding to the given FlowFile.
void	read(FlowFile source, InputStreamCallback reader) Executes the given callback against the contents corresponding to the given FlowFile.
void	remove(Collection<FlowFile> flowFiles) Ends the managed persistence for the given FlowFiles.
void	remove(FlowFile flowFile) Ends the managed persistence for the given FlowFile.
FlowFile	removeAllAttributes(FlowFile flowFile, Pattern keyPattern) Remove all attributes from the given FlowFile that have keys which match the given pattern.
FlowFile	removeAllAttributes(FlowFile flowFile, Set<String> keys) Removes the attributes with the given keys from the given FlowFile.
FlowFile	removeAttribute(FlowFile flowFile, String key) Removes the given FlowFile attribute with the given key.
boolean	replaceState(StateMap oldValue, Map<String,String> newValue, Scope scope) Updates the value of the component's state to the new value if and only if the value currently is the same as the given oldValue.
void	rollback() Reverts any changes made during this session.
void	rollback(boolean penalize) Reverts any changes made during this session.
void	setState(Map<String,String> state, Scope scope) Updates the value of the component's state, setting it to given value.
void	transfer(Collection<FlowFile> flowFiles) Transfers the given FlowFiles back to the work queues from which the FlowFiles were pulled.
void	transfer(Collection<FlowFile> flowFiles, Relationship relationship) Transfers the given FlowFile to the appropriate destination processor work queue(s) based on the given relationship.
void	transfer(FlowFile flowFile) Transfers the given FlowFile back to the work queue from which it was pulled.
void	transfer(FlowFile flowFile, Relationship relationship) Transfers the given FlowFile to the appropriate destination processor work queue(s) based on the given relationship.
OutputStream	write(FlowFile source) Provides an OutputStream that can be used to write to the contents of the given FlowFile.
FlowFile	write(FlowFile source, OutputStreamCallback writer) Executes the given callback against the content corresponding to the given FlowFile.
FlowFile	write(FlowFile source, StreamCallback writer) Executes the given callback against the content corresponding to the given flow file.

Method Detail

commit

void commit()

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.

As soon as the commit completes the session is again ready to be used

Throws:

IllegalStateException - if detected that this method is being called from within a callback of another method in this session.

FlowFileHandlingException - if not all FlowFiles acted upon within this session are accounted for by user code such that they have a transfer identified or where marked for removal. Automated rollback occurs.

ProcessException - if some general fault occurs while persisting the session. Initiates automatic rollback. The root cause can be obtained via Exception.getCause()

commitAsync

void commitAsync()

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.

Unlike the 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 commitAsync(Runnable) or commitAsync(Runnable, Consumer) and implementing that action in the provided callback.

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 read or write callback (See write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback), read(FlowFile, InputStreamCallback)).

FlowFileHandlingException - if any FlowFile is not appropriately accounted for by transferring it to a Relationship (see transfer(FlowFile, Relationship)) or removed (see remove(FlowFile).

commitAsync

default void commitAsync(Runnable onSuccess)

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.

If the session is successfully committed, the given onSuccess Runnable will be called. At the point that the session commit is completed, the session will have already been committed, so any calls to rollback() / rollback(boolean) will not undo that session commit but instead roll back any changes that may have occurred since.

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 commitAsync(Runnable, Consumer) instead.

Unlike the commit() method, the persistence of data to the repositories is not guaranteed to have occurred by the time that this method returns. As a result, the following very common idiom:

 getDataFromSource();
 session.commit();
 acknowledgeReceiptOfData();
 

Cannot be simply changed to:

 getDataFromSource();
 session.commitAsync();
 acknowledgeReceiptOfData();
 

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:

 getDataFromSource();
 session.commitAsync( () -> acknowledgeReceiptOfData() );
 

Throws:

IllegalStateException - if called from within a callback (See write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback), read(FlowFile, InputStreamCallback)).

FlowFileHandlingException - if any FlowFile is not appropriately accounted for by transferring it to a Relationship (see transfer(FlowFile, Relationship)) or removed (see remove(FlowFile).

commitAsync

void commitAsync(Runnable onSuccess,
                 Consumer<Throwable> onFailure)

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.

If the session is successfully committed, the given onSuccess Runnable will be called. At the point that the session commit is completed, the session will have already been committed, so any calls to rollback() / rollback(boolean) will not undo that session commit but instead roll back any chances that may have occurred since.

If, for any reason, the session could not be committed, the given onFailure Consumer will be called instead of the onSuccess Runnable. The Consumer will be provided the Throwable that prevented the session commit from completing.

Unlike the commit() method, the persistence of data to the repositories is not guaranteed to have occurred by the time that this method returns.

Throws:

IllegalStateException - if called from within a callback (See write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback), read(FlowFile, InputStreamCallback)).

FlowFileHandlingException - if any FlowFile is not appropriately accounted for by transferring it to a Relationship (see transfer(FlowFile, Relationship)) or removed (see remove(FlowFile).

rollback

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. 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 rollback(boolean) passing false as the parameter.

rollback

void rollback(boolean penalize)

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.

Parameters:

penalize - whether or not the FlowFiles that are being restored back to their queues should be penalized

migrate

void migrate(ProcessSession newOwner,
             Collection<FlowFile> flowFiles)

Migrates ownership of the given FlowFiles from this to the given newOwner.

When calling this method, all of the following pre-conditions must be met:

• This method cannot be called from within a callback (see write(FlowFile, OutputStreamCallback), write(FlowFile, StreamCallback), read(FlowFile, InputStreamCallback), read(FlowFile, boolean, InputStreamCallback) for any of the given FlowFiles.
• No InputStream can be open for the content of any of the given FlowFiles (see read(FlowFile)).
• No OutputStream can be open for the content of any of the given FlowFiles (see write(FlowFile).
• For any provided FlowFile, if the FlowFile has any child (e.g., by calling create(FlowFile) and passing the FlowFile as the argument), then all children that were created must also be in the Collection of provided FlowFiles.

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 putAttribute(FlowFile, String, String) is made, passing flowFile1 as the FlowFile, and then 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 flowFile1 points to.

Parameters:

newOwner - the ProcessSession that is to become the new owner of the given FlowFiles

flowFiles - the FlowFiles to migrate

migrate

void migrate(ProcessSession newOwner)

Migrates all FlowFiles to the given new owner as described in migrate(ProcessSession, Collection)

Parameters:

newOwner - the ProcessSession that is to become the new owner of all FlowFiles

adjustCounter

void adjustCounter(String name,
                   long delta,
                   boolean immediate)

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.

Parameters:

name - the name of the counter

delta - the delta by which to modify the counter (+ or -)

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.

get

FlowFile get()

Returns:

FlowFile that is next highest priority FlowFile to process. Otherwise returns null.

get

List<FlowFile> get(int maxResults)

Returns up to maxResults 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.

Parameters:

maxResults - the maximum number of FlowFiles to return

Returns:

up to maxResults FlowFiles from the work queue. If no FlowFiles are available, returns an empty list. Will not return null.

Throws:

IllegalArgumentException - if maxResults is less than 0

get

List<FlowFile> get(FlowFileFilter filter)

Returns all FlowFiles from all of the incoming queues for which the given 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.

Parameters:

filter - to limit which flow files are returned

Returns:

all FlowFiles from all of the incoming queues for which the given FlowFileFilter indicates should be accepted.

getQueueSize

QueueSize getQueueSize()

Returns:

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

create

FlowFile create()

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 create(FlowFile) or create(Collection). When this method is used, a Provenance CREATE or RECEIVE Event should be generated. See the getProvenanceReporter() method and ProvenanceReporter class for more information

Returns:

newly created FlowFile

create

FlowFile create(FlowFile parent)

Creates a new FlowFile in the repository with no content but with a parent linkage to parent. 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.

Parameters:

parent - to base the new flowfile on

Returns:

newly created flowfile

create

FlowFile create(Collection<FlowFile> parents)

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.

Parameters:

parents - which the new flowfile should inherit shared attributes from

Returns:

new flowfile

clone

FlowFile clone(FlowFile example)

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.

Parameters:

example - FlowFile to be the source of cloning - given FlowFile must be a part of the given session

Returns:

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

NullPointerException - if the argument null

clone

FlowFile clone(FlowFile parent,
               long offset,
               long size)

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).

Parameters:

parent - to base the new flowfile attributes on

offset - of the parent flowfile to base the child flowfile content on

size - of the new flowfile from the offset

Returns:

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

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.

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.

penalize

FlowFile penalize(FlowFile flowFile)

Sets a penalty for the given FlowFile which will make it unavailable to be operated on any further during the penalty period.

Parameters:

flowFile - to penalize

Returns:

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

NullPointerException - if the argument null

putAttribute

FlowFile putAttribute(FlowFile flowFile,
                      String key,
                      String value)

Updates the given FlowFiles attributes with the given key/value pair. If the key is named uuid, this attribute will be ignored.

Parameters:

flowFile - to update

key - of attribute

value - of attribute

Returns:

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.

NullPointerException - if an argument is null

putAllAttributes

FlowFile putAllAttributes(FlowFile flowFile,
                          Map<String,String> attributes)

Updates the given FlowFiles attributes with the given key/value pairs. If the map contains a key named uuid, this attribute will be ignored.

Parameters:

flowFile - to update

attributes - the attributes to add to the given FlowFile

Returns:

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

NullPointerException - if an argument is null

removeAttribute

FlowFile removeAttribute(FlowFile flowFile,
                         String key)

Removes the given FlowFile attribute with the given key. If the key is named uuid, this method will return the same FlowFile without removing any attribute.

Parameters:

flowFile - to update

key - of attribute

Returns:

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

NullPointerException - if the argument null

removeAllAttributes

FlowFile removeAllAttributes(FlowFile flowFile,
                             Set<String> keys)

Removes the attributes with the given keys from the given FlowFile. If the set of keys contains the value uuid, this key will be ignored

Parameters:

flowFile - to update

keys - of attribute

Returns:

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

NullPointerException - if the argument null

removeAllAttributes

FlowFile removeAllAttributes(FlowFile flowFile,
                             Pattern keyPattern)

Remove all attributes from the given FlowFile that have keys which match the given pattern. If the pattern matches the key uuid, this key will not be removed.

Parameters:

flowFile - to update

keyPattern - may be null; if supplied is matched against each of the FlowFile attribute keys

Returns:

FlowFile containing only attributes which did not meet the key pattern

transfer

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.

Parameters:

flowFile - to transfer

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

NullPointerException - if the argument null

IllegalArgumentException - if given relationship is not a known or registered relationship

transfer

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.

Parameters:

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

IllegalArgumentException - if the FlowFile was created by this processor

NullPointerException - if the argument null

transfer

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.

Parameters:

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)

FlowFileHandlingException - if the given FlowFiles are already transferred or removed or don't belong to this session. Automatic rollback will occur.

IllegalArgumentException - if the FlowFile was created by this processor

NullPointerException - if the argument null

transfer

void transfer(Collection<FlowFile> flowFiles,
              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.

Parameters:

flowFiles - to transfer

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

NullPointerException - if the argument null

IllegalArgumentException - if given relationship is not a known or registered relationship

remove

void remove(FlowFile flowFile)

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.

Parameters:

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

remove

void remove(Collection<FlowFile> flowFiles)

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.

Parameters:

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)

FlowFileHandlingException - if any of the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

read

void read(FlowFile source,
          InputStreamCallback reader)
   throws FlowFileAccessException

Executes the given callback against the contents corresponding to the given FlowFile.

Parameters:

source - flowfile to retrieve content of

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 write(FlowFile, OutputStreamCallback) or write(FlowFile, StreamCallback)) or has an OutputStream open (via a call to 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.

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

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

read

InputStream read(FlowFile flowFile)

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 commit() or 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.

Parameters:

flowFile - the FlowFile to read

Returns:

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 write(FlowFile, OutputStreamCallback) or write(FlowFile, StreamCallback)) or has an OutputStream open (via a call to 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.

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

read

void read(FlowFile source,
          boolean allowSessionStreamManagement,
          InputStreamCallback reader)
   throws FlowFileAccessException

Executes the given callback against the contents corresponding to the given FlowFile. Note: The OutputStream provided to the given OutputStreamCallback will not be accessible once this method has completed its execution.

Parameters:

source - flowfile to retrieve content of

allowSessionStreamManagement - allow session to hold the stream open for performance reasons

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 write(FlowFile, OutputStreamCallback) or write(FlowFile, StreamCallback)) or has an OutputStream open (via a call to 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.

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

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

merge

FlowFile merge(Collection<FlowFile> sources,
               FlowFile destination)

Combines the content of all given source FlowFiles into a single given destination FlowFile.

Parameters:

sources - the flowfiles to merge

destination - the flowfile to use as the merged result

Returns:

updated destination FlowFile (new size, etc...)

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)

IllegalArgumentException - if the given destination is contained within the sources

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content. The state of the destination will be as it was prior to this call.

merge

FlowFile merge(Collection<FlowFile> sources,
               FlowFile destination,
               byte[] header,
               byte[] footer,
               byte[] demarcator)

Combines the content of all given source FlowFiles into a single given destination FlowFile.

Parameters:

sources - to merge together

destination - to merge to

header - bytes that will be added to the beginning of the merged output. May be null or empty.

footer - bytes that will be added to the end of the merged output. May be null or empty.

demarcator - bytes that will be placed in between each object merged together. May be null or empty.

Returns:

updated destination FlowFile (new size, etc...)

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)

IllegalArgumentException - if the given destination is contained within the sources

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content. The state of the destination will be as it was prior to this call.

write

FlowFile write(FlowFile source,
               OutputStreamCallback writer)
        throws FlowFileAccessException

Executes the given callback against the content corresponding to the given FlowFile. Note: The OutputStream provided to the given OutputStreamCallback will not be accessible once this method has completed its execution.

Parameters:

source - to write to

writer - used to write new content

Returns:

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), or if there is an open InputStream or OutputStream for the FlowFile's content (see read(FlowFile) and write(FlowFile)).

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content; if an attempt is made to access the OutputStream provided to the given OutputStreamCallaback after this method completed its execution

write

OutputStream write(FlowFile source)

Provides an OutputStream that can be used to write to the contents of the given FlowFile.

Parameters:

source - to write to

Returns:

an OutputStream that can be used to write to the contents of the 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), or if there is an open InputStream or OutputStream for the FlowFile's content (see read(FlowFile)).

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content; if an attempt is made to access the OutputStream provided to the given OutputStreamCallaback after this method completed its execution

write

FlowFile write(FlowFile source,
               StreamCallback writer)
        throws FlowFileAccessException

Executes the given callback against the content corresponding to the given flow file. Note: The InputStream & OutputStream provided to the given StreamCallback will not be accessible once this method has completed its execution.

Parameters:

source - to read from and write to

writer - used to read the old content and write new content

Returns:

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), or if there is an open InputStream or OutputStream for the FlowFile's content (see read(FlowFile) and write(FlowFile)).

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content; if an attempt is made to access the InputStream or OutputStream provided to the given StreamCallback after this method completed its execution

append

FlowFile append(FlowFile source,
                OutputStreamCallback writer)
         throws FlowFileAccessException

Executes the given callback against the content corresponding to the given FlowFile, such that any data written to the OutputStream of the content will be appended to the end of FlowFile. Note: The OutputStream provided to the given OutputStreamCallback will not be accessible once this method has completed its execution.

Parameters:

source - the flowfile for which content should be appended

writer - used to write new bytes to the flowfile content

Returns:

the updated flowfile reference for the new content

Throws:

FlowFileAccessException - if an attempt is made to access the OutputStream provided to the given OutputStreamCallaback after this method completed its execution

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), or if there is an open InputStream or OutputStream for the FlowFile's content (see read(FlowFile) and write(FlowFile)).

importFrom

FlowFile importFrom(Path source,
                    boolean keepSourceFile,
                    FlowFile destination)

Writes to the given FlowFile all content from the given content path.

Parameters:

source - the file from which content will be obtained

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.

destination - the FlowFile whose content will be updated

Returns:

the updated destination FlowFile (new size)

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

importFrom

FlowFile importFrom(InputStream source,
                    FlowFile destination)

Writes to the given FlowFile all content from the given content path.

Parameters:

source - the file from which content will be obtained

destination - the FlowFile whose content will be updated

Returns:

the updated destination FlowFile (new size)

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

exportTo

void exportTo(FlowFile flowFile,
              Path destination,
              boolean append)

Writes the content of the given FlowFile to the given destination path.

Parameters:

flowFile - to export the content of

destination - to export the content to

append - if true will append to the current content at the given path; if false will replace any current content

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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

exportTo

void exportTo(FlowFile flowFile,
              OutputStream destination)

Writes the content of the given FlowFile to the given destination stream

Parameters:

flowFile - to export the content of

destination - to export the content 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)

FlowFileHandlingException - if the given FlowFile is already transferred or removed or doesn't belong to this session. Automatic rollback will occur.

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.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

getProvenanceReporter

ProvenanceReporter getProvenanceReporter()

Returns a ProvenanceReporter that is tied to this ProcessSession.

Returns:

the provenance reporter

setState

void setState(Map<String,String> state,
              Scope scope)
       throws IOException

Updates the value of the component's state, setting it to given value. This method does not push the new value to the remote State Provider but rather caches the value until commit() is called. 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.

Parameters:

state - the value to change the state to

scope - the scope to use when storing the state

Throws:

IOException - if unable to communicate with the underlying storage mechanism

getState

StateMap getState(Scope scope)
           throws IOException

Returns the current state for the component. This return value will never be null. If the state has not yet been set, the StateMap's version will be -1, and the map of values will be empty.

Parameters:

scope - the scope to use when fetching the state

Returns:

the current state for the component

Throws:

IOException - if unable to communicate with the underlying storage mechanism

replaceState

boolean replaceState(StateMap oldValue,
                     Map<String,String> newValue,
                     Scope scope)
              throws IOException

Updates the value of the component's state to the new value if and only if the value currently is the same as the given oldValue. The oldValue will be compared against the value of the state as it is known to the Process Session. If the Process Session does not currently know the state, it will be fetched from the StateProvider. The value will not be provided to any remote state provider until commit() is called. At that point, if the value that has been set by this method is the most up-to-date value, according to the state provider, then the remote state provider will be updated to match the given newValue.

Parameters:

oldValue - the old value to compare against

newValue - the new value to use if and only if the state's value is the same as the given oldValue

scope - the scope to use for storing the new state

Returns:

true if the state was updated to the new value, false if the state's value was not equal to oldValue

Throws:

IOException - if unable to communicate with the underlying storage mechanism

clearState

void clearState(Scope scope)
         throws IOException

Clears all keys and values from the component's state when the session is committed

Parameters:

scope - the scope whose values should be cleared

Throws:

IOException - if unable to communicate with the underlying storage mechanism.