Package 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 process session 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 types of 'terminal' methods that will result in the session being in a 'fresh' state, containing no knowledge or any FlowFile, as if the session were newly created. After one of these methods is called, the instance may be used again. The terminal methods for a process session are commitAsync() and rollback() (and their overloads).

Additionally, the migrate(ProcessSession, Collection) method transfers all knowledge of the provided FlowFiles to the other process session, as if the FlowFiles never existed in this process session. Note, however, that even if all FlowFiles are migrated via the migrate(ProcessSession, Collection) method, the session is not necessarily entirely cleared, as it still may have knowledge of counter adjustments or state changes, e.g. see methods adjustCounter(String, long, boolean) or setState(Map, Scope). A commit or rollback will clear these changes as well.

Method Summary

Modifier and Type	Method	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 {code writer} OutputStreamCallback against the content of the given FlowFile, such that any data written to the OutputStream will be appended to the end of FlowFile's content.
void	clearState(Scope scope)	Clears all keys and values from the component's state.
FlowFile	clone(FlowFile example)	Creates a new FlowFile with a parent linkage to the example FlowFile.
FlowFile	clone(FlowFile parent, long offset, long size)	Creates a new FlowFile with a parent linkage to the parent 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 all parents.
FlowFile	create(FlowFile parent)	Creates a new FlowFile in the repository with no content but with a parent linkage to the parent.
void	exportTo(FlowFile flowFile, OutputStream destination)	Writes the content of the given FlowFile to given destination OutputStream.
void	exportTo(FlowFile flowFile, Path destination, boolean append)	Writes the content of the given FlowFile to the file at the given destination Path.
FlowFile	get()	Returns the FlowFile from the work queue that is next highest priority to process.
List<FlowFile>	get(int maxResults)	Returns the next up to maxResults FlowFiles from the work queue that are the highest priority to process.
List<FlowFile>	get(FlowFileFilter filter)	Returns all FlowFiles from all the incoming queues which the given FlowFileFilter accepts.
ProvenanceReporter	getProvenanceReporter()	Returns the ProvenanceReporter that is tied to this ProcessSession.
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.
StateMap	getState(Scope scope)	Returns the current state for the component.
FlowFile	importFrom(InputStream source, FlowFile destination)	Writes to contents of the source InputStream to the given FlowFile's content.
FlowFile	importFrom(Path source, boolean keepSourceFile, FlowFile destination)	Writes to contents of the file a the source Path to the given FlowFile's content.
FlowFile	merge(Collection<FlowFile> sources, FlowFile destination)	Combines the content of all given sources 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 sources FlowFiles into a single given destination FlowFile.
void	migrate(ProcessSession newOwner)	Migrates ownership of all FlowFiles from this session to the given newOwner ProcessSession.
void	migrate(ProcessSession newOwner, Collection<FlowFile> flowFiles)	Migrates ownership of the given flowFiles FlowFiles from this session to the given newOwner ProcessSession.
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 FlowFile's attributes with the given key / value pairs.
FlowFile	putAttribute(FlowFile flowFile, String key, String value)	Updates the given FlowFile's attributes with the given key / value pair.
InputStream	read(FlowFile flowFile)	Provides an InputStream that can be used to read the content of the given FlowFile.
void	read(FlowFile source, InputStreamCallback reader)	Executes the given {code reader} InputStreamCallback against the content of 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)	Removes all attributes from the given FlowFile whose key matches 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 attribute with the given key from the given FlowFile.
boolean	replaceState(StateMap oldValue, Map<String,String> newValue, Scope scope)	Updates the value of the component's state, setting it to given newValue, if and only if the current value 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 FlowFiles 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 the content of the given FlowFile.
FlowFile	write(FlowFile source, OutputStreamCallback writer)	Executes the given {code writer} OutputStreamCallback against the content of the given FlowFile.
FlowFile	write(FlowFile source, StreamCallback writer)	Executes the given {code writer} StreamCallback against the content of the given FlowFile.

Method Details

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.

See commitAsync(), commitAsync(Runnable), and commitAsync(Runnable, Consumer). The asynchronous session commit methods are preferable to this commit call for most cases as it defers when the actual commit happens to the framework so that it can optimize when the commit call takes place.

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)).

FlowFileHandlingException - if not all FlowFiles acted upon within this session are accounted for 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 Throwable.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.

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() );
 

If the session cannot be committed, an error will be logged and the session will be rolled back instead.

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)).

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

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

Parameters:

onSuccess - 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 read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)).

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

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

Parameters:

onSuccess - Runnable that will be called if and when the session is successfully committed; may be null

onFailure - 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 read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)).

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

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

Parameters:

penalize - whether 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 FlowFiles from this session to the given newOwner ProcessSession.

Note, that 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

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for any of the affected FlowFiles

migrate

void migrate(ProcessSession newOwner)

Migrates ownership of all FlowFiles from this session to the given newOwner ProcessSession. Calling this method is identical to calling 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.

Parameters:

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

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for any of the affected 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 process session 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 session is committed or rolled back; otherwise, the counter will be incremented only if and when the session is committed.

get

FlowFile get()

Returns the FlowFile from the work queue that is next highest priority to process. If no FlowFiles are available, returns null.

Returns:

the FlowFile from the work queue that is next highest priority to process or null, if none available

get

List<FlowFile> get(int maxResults)

Returns the next up to maxResults FlowFiles from the work queue that are the highest priority to process. 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

Throws:

IllegalArgumentException - if maxResults is less than 0

get

List<FlowFile> get(FlowFileFilter filter)

Returns all FlowFiles from all the incoming queues which the given FlowFileFilter accepts.

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 Processor's incoming queues until this method call has returned.

Parameters:

filter - a FlowFileFilter to limit which FlowFiles are returned

Returns:

all FlowFiles from all the incoming queues which the given FlowFileFilter filter accepts.

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.

Returns:

the number of FlowFiles and their combined data size in the work queue

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 instead create(FlowFile) or create(Collection) be used.

When this method is used, a ProvenanceEventType.CREATE or ProvenanceEventType.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 the parent. The newly created FlowFile will inherit all the parent's attributes, except for the UUID.

This method will automatically generate a ProvenanceEventType.FORK or a ProvenanceEventType.JOIN event, depending on whether other FlowFiles are generated from the same parent before the session is committed.

Parameters:

parent - to base the new FlowFile on, inheriting attributes from

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 all parents. The newly created FlowFile will inherit all the attributes that are in common to all parents, except for the UUID.

This method will automatically generate a ProvenanceEventType.JOIN event.

Parameters:

parents - to base the new FlowFile on, inheriting shared attributes from

Returns:

newly created FlowFile

clone

FlowFile clone(FlowFile example)

Creates a new FlowFile with a parent linkage to the example FlowFile. It is a clone of the given FlowFile as of the time this is called, both in attributes and content.

This method will automatically generate a ProvenanceEventType.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 FlowFile

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the example 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. The session is automatically rolled back.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

clone

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

Creates a new FlowFile with a parent linkage to the 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.

This method will automatically generate a ProvenanceEventType.FORK or a ProvenanceEventType.CLONE event, if the offset is 0 and the size is exactly equal to the size of the example FlowFile.

Parameters:

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

offset - of the parent FlowFile's content to base the cloned FlowFile's content on

size - in bytes of the parent FlowFile's content to clone starting from the offset

Returns:

FlowFile that is a partial clone of the given parent FlowFile whose content has the specified size

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the parent 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 the size of the parent FlowFile's content. Automatic rollback will occur.

MissingFlowFileException - if the given FlowFile content cannot be found. The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

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:

the penalized FlowFile

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the flowFile FlowFile

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

putAttribute

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

Updates the given FlowFile's 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 to add or modify

value - of attribute to add or modify

Returns:

the updated 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 read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the flowFile FlowFile

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

putAllAttributes

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

Updates the given FlowFile's 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 or modify

Returns:

the updated 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 read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the flowFile FlowFile

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

removeAttribute

FlowFile removeAttribute(FlowFile flowFile,
 String key)

Removes the attribute with the given key from the given FlowFile.

The attributes with the keys uuid, path, and filename will not be removed. If the key is one of those, this method will return the same FlowFile without removing any attribute.

Parameters:

flowFile - to update

key - of attribute to remove

Returns:

the updated FlowFile with the matching attribute removed

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the flowFile FlowFile

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

removeAllAttributes

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

Removes the attributes with the given keys from the given FlowFile.

The attributes with the keys uuid, path, and filename will not be removed.

Parameters:

flowFile - to update

keys - of attributes to remove

Returns:

the updated FlowFile with the matching attributes removed

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the flowFile FlowFile

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

removeAllAttributes

FlowFile removeAllAttributes(FlowFile flowFile,
 Pattern keyPattern)

Removes all attributes from the given FlowFile whose key matches the given pattern.

The attributes with the keys uuid, path, and filename will not be removed.

Parameters:

flowFile - to update

keyPattern - pattern to match each FlowFile attribute against; may be null, in which case no attribute is removed

Returns:

the updated FlowFile with the matching attributes removed

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the flowFile FlowFile

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

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 read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the flowFile FlowFile

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

IllegalArgumentException - if the given FlowFile was created by this processor

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

Parameters:

flowFiles - to transfer

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the flowFile FlowFile

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

IllegalArgumentException - if any of the given FlowFiles was created by this processor

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 read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the flowFile FlowFile

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

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

transfer

void transfer(Collection<FlowFile> flowFiles,
 Relationship relationship)

Transfers the given FlowFiles 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 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.

Parameters:

flowFiles - to transfer

relationship - to transfer to

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for any of the flowFiles FlowFiles

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

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. 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 read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the given flowFile FlowFile

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 FlowFiles are deleted and so is the content assuming nothing else references it. The FlowFiles 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 read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for any of the given flowFiles FlowFiles

FlowFileHandlingException - if any of the given FlowFiles 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 {code reader} InputStreamCallback against the content of the given FlowFile.

Parameters:

source - the FlowFile to retrieve the content from

reader - InputStreamCallback that will be called to read the FlowFile content

Throws:

IllegalStateException - if detected that this method is being called from within a write callback (see write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a write stream is open (see write(FlowFile)) for the given source FlowFile. 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. The session is automatically rolled back.

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

Parameters:

flowFile - the FlowFile to retrieve the content from

Returns:

an InputStream that can be used to read the content of the FlowFile

Throws:

IllegalStateException - if detected that this method is being called from within a write callback (see write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a write stream is open (see write(FlowFile)) for the given flowFile FlowFile. 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. The session is automatically rolled back.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content; if an attempt is made to read from the stream after the session is committed or rolled back.

merge

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

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

Parameters:

sources - the FlowFiles whose content to merge

destination - the FlowFile to use as the merged result

Returns:

the updated destination destination FlowFile with changed content

Throws:

IllegalArgumentException - if the given destination is contained within the sources

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for any of the given sources and destination FlowFiles

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

MissingFlowFileException - if any of the given FlowFile's content cannot be found. The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content; the state of the destination FlowFile 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 sources FlowFiles into a single given destination FlowFile.

Parameters:

sources - the FlowFiles whose content to merge

destination - the FlowFile to use as the merged result

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:

the updated destination FlowFile with changed content

Throws:

IllegalArgumentException - if the given destination is contained within the sources

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for any of the given sources and destination FlowFiles

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

MissingFlowFileException - if any of the given FlowFile's content cannot be found. The FlowFile should no longer be referenced, will be internally destroyed. The session is automatically rolled back.

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

write

FlowFile write(FlowFile source,
 OutputStreamCallback writer)
        throws FlowFileAccessException

Executes the given {code writer} OutputStreamCallback against the content of the given FlowFile.

Parameters:

source - the FlowFile to write the content of

writer - InputStreamCallback that will be called to write the FlowFile content

Returns:

the updated source FlowFile with changed content

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the given source 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. The session is automatically rolled back.

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

write

OutputStream write(FlowFile source)

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

This method differs from those that make use of callbacks in that this method returns an OutputStream and expects the caller to properly handle the lifecycle of the OutputStream (i.e., the caller is responsible for ensuring that the OutputStream is closed appropriately). The session may or may not handle closing the stream when the session is commited or rolled back, but the responsibility of doing so belongs to the caller.

Parameters:

source - the FlowFile to write the content of

Returns:

an OutputStream that can be used to write the content of the FlowFile

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the given source 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. The session is automatically rolled back.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content; if an attempt is made to write to the stream after the session is committed or rolled back.

write

FlowFile write(FlowFile source,
 StreamCallback writer)
        throws FlowFileAccessException

Executes the given {code writer} StreamCallback against the content of the given FlowFile.

Parameters:

source - the FlowFile to read and write the content of

writer - StreamCallback that will be called to read and write the FlowFile content

Returns:

the updated source FlowFile with changed content

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the given source 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. The session is automatically rolled back.

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 {code writer} OutputStreamCallback against the content of the given FlowFile, such that any data written to the OutputStream will be appended to the end of FlowFile's content.

Parameters:

source - the FlowFile to extend the content of

writer - OutputStreamCallback that will be called to append the FlowFile's content

Returns:

the updated source FlowFile with changed content

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the given source 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. The session is automatically rolled back.

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

importFrom

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

Writes to contents of the file a the source Path to the given FlowFile's content.

Parameters:

source - the Path to 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 with changed content

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the given source 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. The session is automatically rolled back.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

importFrom

FlowFile importFrom(InputStream source,
 FlowFile destination)

Writes to contents of the source InputStream to the given FlowFile's content.

Parameters:

source - the InputStream from which content will be obtained

destination - the FlowFile whose content will be updated

Returns:

the updated destination FlowFile with changed content

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the given source 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. The session is automatically rolled back.

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 file at the given destination Path.

Parameters:

flowFile - the FlowFile to export the content of

destination - the Path to a file to export the FlowFile's content to

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

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the given flowFile 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. The session is automatically rolled back.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

exportTo

void exportTo(FlowFile flowFile,
 OutputStream destination)

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

Parameters:

flowFile - the FlowFile to export the content of

destination - the OutputStream to export the FlowFile's content to

Throws:

IllegalStateException - if detected that this method is being called from within a read or write callback (see read(FlowFile, InputStreamCallback), write(FlowFile, StreamCallback), write(FlowFile, OutputStreamCallback)) or while a read or write stream is open (see read(FlowFile), write(FlowFile)) for the given flowFile 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. The session is automatically rolled back.

FlowFileAccessException - if some IO problem occurs accessing FlowFile content

getProvenanceReporter

ProvenanceReporter getProvenanceReporter()

Returns the ProvenanceReporter that is tied to this ProcessSession.

Returns:

the ProvenanceReporter that is tied to this ProcessSession

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 update the remote State Provider immediately but rather caches the value until the session is committed. At that point, it will publish the state to the remote State Provider, if the state is the latest according to the remote State Provider.

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, setting it to given newValue, if and only if the current value is the same as the given oldValue.

The oldValue will be compared against the value of the state as it is known to this ProcessSession. If the Process Session does not currently know the state, it will be fetched from the StateProvider.

This method does update the remote State Provider immediately but rather caches the value until the session is committed. At that point, it will publish the state to the remote State Provider, if the state is the latest according to the remote State Provider.

Parameters:

oldValue - the value to compare the state's current value against

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

scope - the Scope to use for fetching the current and storing the new state

Returns:

true if the state was updated to the newValue, false if the state's current 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.

This method does update the remote State Provider immediately but rather caches the value until the session is committed. At that point, it will publish the state to the remote State Provider, if the state is the latest according to the remote State Provider.

Parameters:

scope - the Scope to use for clearing the state

Throws:

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