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

      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:

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

    • 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 invalid input: '&' 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.