net.corda.core.transactions

## Class TransactionBuilder

- net.corda.core.transactions.TransactionBuilder

- Direct Known Subclasses:
    NotaryChange.Builder, General.Builder

      public class TransactionBuilder

  A TransactionBuilder is a transaction class that's mutable (unlike the others which are all immutable). It is intended to be passed around contracts that may edit it by adding new states/commands. Then once the states and commands are right, this class can be used as a holding bucket to gather signatures from multiple parties.

  The builder can be customised for specific transaction types, e.g. where additional processing is needed before adding a state/command.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TransactionBuilder(TransactionType type, Party notary, java.util.List<net.corda.core.contracts.StateRef> inputs, java.util.List<net.corda.core.crypto.SecureHash> attachments, java.util.List<net.corda.core.contracts.TransactionState> outputs, java.util.List<net.corda.core.contracts.Command> commands, java.util.Set<net.corda.core.crypto.CompositeKey> signers, Timestamp timestamp)` A TransactionBuilder is a transaction class that's mutable (unlike the others which are all immutable). It is intended to be passed around contracts that may edit it by adding new states/commands. Then once the states and commands are right, this class can be used as a holding bucket to gather signatures from multiple parties.
    `TransactionBuilder()` A TransactionBuilder is a transaction class that's mutable (unlike the others which are all immutable). It is intended to be passed around contracts that may edit it by adding new states/commands. Then once the states and commands are right, this class can be used as a holding bucket to gather signatures from multiple parties.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAttachment(SecureHash attachmentId)`
    `void` | `addCommand(Command arg)`
    `void` | `addCommand(CommandData data, net.corda.core.crypto.CompositeKey keys)`
    `void` | `addCommand(CommandData data, java.util.List<? extends net.corda.core.crypto.CompositeKey> keys)`
    `void` | `addInputState(StateAndRef<?> stateAndRef)`
    `int` | `addOutputState(TransactionState<?> state)`
    `int` | `addOutputState(ContractState state, Party notary, java.lang.Integer encumbrance)`
    `int` | `addOutputState(ContractState state, Party notary)`
    `int` | `addOutputState(ContractState state)` A default notary must be specified during builder construction to use this method
    `TransactionBuilder` | `addSignatureUnchecked(DigitalSignature.WithKey sig)` Adds the signature directly to the transaction, without checking it for validity.
    `java.util.List<net.corda.core.crypto.SecureHash>` | `attachments()`
    `void` | `checkAndAddSignature(DigitalSignature.WithKey sig)` Checks that the given signature matches one of the commands and that it is a correct signature over the tx, then adds it.
    `void` | `checkSignature(DigitalSignature.WithKey sig)` Checks that the given signature matches one of the commands and that it is a correct signature over the tx.
    `java.util.List<net.corda.core.contracts.Command>` | `commands()`
    `TransactionBuilder` | `copy()` Creates a copy of the builder.
    `java.util.List<net.corda.core.crypto.SecureHash>` | `getAttachments()`
    `java.util.List<net.corda.core.contracts.Command>` | `getCommands()`
    `java.util.ArrayList<net.corda.core.crypto.DigitalSignature.WithKey>` | `getCurrentSigs()` The signatures that have been collected so far - might be incomplete!
    `java.util.List<net.corda.core.contracts.StateRef>` | `getInputs()`
    `Party` | `getNotary()`
    `java.util.List<net.corda.core.contracts.TransactionState>` | `getOutputs()`
    `java.util.Set<net.corda.core.crypto.CompositeKey>` | `getSigners()`
    `Timestamp` | `getTime()`
    `Timestamp` | `getTimestamp()`
    `TransactionType` | `getType()`
    `java.util.List<net.corda.core.contracts.StateRef>` | `inputStates()`
    `java.util.List<net.corda.core.contracts.TransactionState>` | `outputStates()`
    `void` | `setNotary(Party p)`
    `void` | `setTime(java.time.Instant time, java.time.Duration timeTolerance)` Places a TimestampCommand in this transaction, removing any existing command if there is one. The command requires a signature from the Notary service, which acts as a Timestamp Authority. The signature can be obtained using NotaryFlow.
    `void` | `setTime(Timestamp newTimestamp)`
    `void` | `setTimestamp(Timestamp p)`
    `TransactionBuilder` | `signWith(java.security.KeyPair key)`
    `SignedTransaction` | `toSignedTransaction(boolean checkSufficientSignatures)`
    `WireTransaction` | `toWireTransaction()`
    `TransactionBuilder` | `withItems(java.lang.Object items)` A more convenient way to add items to this transaction that calls the add* methods for you based on type

- - ### Constructor Detail

    - #### TransactionBuilder

          public TransactionBuilder(TransactionType type,
                                    Party notary,
                                    java.util.List<net.corda.core.contracts.StateRef> inputs,
                                    java.util.List<net.corda.core.crypto.SecureHash> attachments,
                                    java.util.List<net.corda.core.contracts.TransactionState> outputs,
                                    java.util.List<net.corda.core.contracts.Command> commands,
                                    java.util.Set<net.corda.core.crypto.CompositeKey> signers,
                                    Timestamp timestamp)

      A TransactionBuilder is a transaction class that's mutable (unlike the others which are all immutable). It is intended to be passed around contracts that may edit it by adding new states/commands. Then once the states and commands are right, this class can be used as a holding bucket to gather signatures from multiple parties.

      The builder can be customised for specific transaction types, e.g. where additional processing is needed before adding a state/command.

      Parameters:
        `notary` - Notary used for the transaction. If null, this indicates the transaction DOES NOT have a notary. When this is set to a non-null value, an output state can be added by just passing in a `interface ContractState` – a `class TransactionState` with this notary specified will be generated automatically.
        `signers` - The set of public keys the transaction needs signatures for. The logic for building the signers set can be customised for every `class TransactionType`. E.g. in the general case it contains the command and notary public keys, but for the `class TransactionType.NotaryChange` transactions it is the set of all input ContractState.participants.

    - #### TransactionBuilder

          public TransactionBuilder()

      A TransactionBuilder is a transaction class that's mutable (unlike the others which are all immutable). It is intended to be passed around contracts that may edit it by adding new states/commands. Then once the states and commands are right, this class can be used as a holding bucket to gather signatures from multiple parties.

      The builder can be customised for specific transaction types, e.g. where additional processing is needed before adding a state/command.

  - ### Method Detail

    - #### getTime

          public Timestamp getTime()

    - #### copy

          public TransactionBuilder copy()

      Creates a copy of the builder.

    - #### setTime

          public void setTime(java.time.Instant time,
                              java.time.Duration timeTolerance)

      Places a TimestampCommand in this transaction, removing any existing command if there is one. The command requires a signature from the Notary service, which acts as a Timestamp Authority. The signature can be obtained using NotaryFlow.

      The window of time in which the final timestamp may lie is defined as time +/- timeTolerance. If you want a non-symmetrical time window you must add the command via `TransactionBuilder.addCommand` yourself. The tolerance should be chosen such that your code can finish building the transaction and sending it to the TSA within that window of time, taking into account factors such as network latency. Transactions being built by a group of collaborating parties may therefore require a higher time tolerance than a transaction being built by a single node.

      See Also:
        TimestampCommand, NotaryFlow, `TransactionBuilder.addCommand`

    - #### setTime

          public void setTime(Timestamp newTimestamp)

    - #### withItems

          public TransactionBuilder withItems(java.lang.Object items)

      A more convenient way to add items to this transaction that calls the add* methods for you based on type

    - #### getCurrentSigs

          public java.util.ArrayList<net.corda.core.crypto.DigitalSignature.WithKey> getCurrentSigs()

      The signatures that have been collected so far - might be incomplete!

    - #### signWith

          public TransactionBuilder signWith(java.security.KeyPair key)

    - #### checkAndAddSignature

          public void checkAndAddSignature(DigitalSignature.WithKey sig)

      Checks that the given signature matches one of the commands and that it is a correct signature over the tx, then adds it.

      Throws:
        - if the signature didn't match the transaction contents.
        - if the signature key doesn't appear in any command.

    - #### checkSignature

          public void checkSignature(DigitalSignature.WithKey sig)

      Checks that the given signature matches one of the commands and that it is a correct signature over the tx.

      Throws:
        - if the signature didn't match the transaction contents.
        - if the signature key doesn't appear in any command.

    - #### addSignatureUnchecked

          public TransactionBuilder addSignatureUnchecked(DigitalSignature.WithKey sig)

      Adds the signature directly to the transaction, without checking it for validity.

    - #### toWireTransaction

          public WireTransaction toWireTransaction()

    - #### toSignedTransaction

          public SignedTransaction toSignedTransaction(boolean checkSufficientSignatures)

    - #### addInputState

          public void addInputState(StateAndRef<?> stateAndRef)

    - #### addAttachment

          public void addAttachment(SecureHash attachmentId)

    - #### addOutputState

          public int addOutputState(TransactionState<?> state)

    - #### addOutputState

          public int addOutputState(ContractState state,
                                    Party notary,
                                    java.lang.Integer encumbrance)

    - #### addOutputState

          public int addOutputState(ContractState state,
                                    Party notary)

    - #### addOutputState

          public int addOutputState(ContractState state)

      A default notary must be specified during builder construction to use this method

    - #### addCommand

          public void addCommand(Command arg)

    - #### addCommand

          public void addCommand(CommandData data,
                                 net.corda.core.crypto.CompositeKey keys)

    - #### addCommand

          public void addCommand(CommandData data,
                                 java.util.List<? extends net.corda.core.crypto.CompositeKey> keys)

    - #### inputStates

          public java.util.List<net.corda.core.contracts.StateRef> inputStates()

    - #### outputStates

          public java.util.List<net.corda.core.contracts.TransactionState> outputStates()

    - #### commands

          public java.util.List<net.corda.core.contracts.Command> commands()

    - #### attachments

          public java.util.List<net.corda.core.crypto.SecureHash> attachments()

    - #### getType

          public TransactionType getType()

    - #### getNotary

          public Party getNotary()

    - #### setNotary

          public void setNotary(Party p)

    - #### getInputs

          public java.util.List<net.corda.core.contracts.StateRef> getInputs()

    - #### getAttachments

          public java.util.List<net.corda.core.crypto.SecureHash> getAttachments()

    - #### getOutputs

          public java.util.List<net.corda.core.contracts.TransactionState> getOutputs()

    - #### getCommands

          public java.util.List<net.corda.core.contracts.Command> getCommands()

    - #### getSigners

          public java.util.Set<net.corda.core.crypto.CompositeKey> getSigners()

    - #### getTimestamp

          public Timestamp getTimestamp()

    - #### setTimestamp

          public void setTimestamp(Timestamp p)