Package com.orchestranetworks.userservice

# Interface UserServiceTransaction

public interface UserServiceTransaction
This interface offers the possibility to mix in a single transaction and in any specified order:

- Record creations,
- Record or dataset updates,
- Custom procedure executions.

Since:
  5.8.0
See Also:
  - `UserServiceTransactionManager.createTransaction()`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `UserServiceTransaction.DeletedObjectOutcome`
  Enumeration for specifying the outcome of a transaction when the underlying data, of the object being updated, was deleted by another thread.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(Procedure aProcedure)`
  Adds a procedure.
  `void`
  `add(ObjectKey anObjectKey)`
  Adds an object to be created or updated.
  `void`
  `add(ObjectKey anObjectKey, UserServiceTransaction.DeletedObjectOutcome aDeletedObjectOutcome)`
  Adds an object to be created or updated.
  `ProcedureResult`
  `execute()`
  In the same transaction, updates and creates objects and executes procedures in the same order as they were previously added.
  `ProcedureResult`
  `execute(boolean addErrorMessageIfException)`
  In the same transaction, updates and creates objects and executes procedures in the same order as they were previously added.
  `ProcedureResult`
  `execute(AdaptationHome aDataSpace)`
  In the same transaction, on a given dataspace, updates and creates objects and executes procedures in the same order as they were previously added.
  `ProcedureResult`
  `execute(AdaptationHome aDataSpace, boolean addErrorMessageIfException)`
  In the same transaction, on a given dataspace, updates and creates objects and executes procedures in the same order as they were previously added.

- ## Method Details

  - ### add

    void add(ObjectKey anObjectKey)
    Adds an object to be created or updated. The object must have been previously registered.
    Parameters:
      `anObjectKey` - the object key. The object must be a record or a dataset.
    Throws:
      `UserServiceException` - if:
      - The object does not exist,
      - The object is not a record or a dataset.
    See Also:
      - `UserServiceObjectContextBuilder.registerRecordOrDataSet(ObjectKey, Adaptation)`
      - `UserServiceObjectContextBuilder.registerNewRecord(ObjectKey, AdaptationTable)`

  - ### add

    void add(ObjectKey anObjectKey, UserServiceTransaction.DeletedObjectOutcome aDeletedObjectOutcome)
    Adds an object to be created or updated. The object must have been previously registered.
    Parameters:
      `anObjectKey` - the object key. The object must be a record or a dataset.
      `aDeletedObjectOutcome` - specifies the outcome when transaction is executed if the underlying data was deleted by another thread. This parameter is ignored if object is a record being created.
    Throws:
      `UserServiceException` - if:
      - The object does not exist,
      - The object is not a record or a dataset.
    Since:
      5.8.1
    See Also:
      - `UserServiceObjectContextBuilder.registerRecordOrDataSet(ObjectKey, Adaptation)`
      - `UserServiceObjectContextBuilder.registerNewRecord(ObjectKey, AdaptationTable)`

  - ### add

    void add(Procedure aProcedure)
    Adds a procedure.
    Parameters:
      `aProcedure` - the procedure.

  - ### execute

    ProcedureResult execute()
    In the same transaction, updates and creates objects and executes procedures in the same order as they were previously added. The user interface will automatically report error messages.

    Calling this method is similar to calling execute(true).

    Returns:
      the result of the execution.
    Throws:
      `UserServiceException` - if objects are not all from the same dataspace.

  - ### execute

    ProcedureResult execute(boolean addErrorMessageIfException)
    In the same transaction, updates and creates objects and executes procedures in the same order as they were previously added.

    The dataspace that will be used to execute the transaction is the one common to all added objects, or, if only procedures were added, the one from the current entity selection.

    Parameters:
      `addErrorMessageIfException` - specifies whether the user interface automatically reports an error message whenever the execution has encountered an error.
    Returns:
      the result of the execution.
    Throws:
      `UserServiceException` - if all objects are not from the same dataspace.
    See Also:
      - `DataspaceEntitySelection.getDataspace()`

  - ### execute

    ProcedureResult execute(AdaptationHome aDataSpace)
    In the same transaction, on a given dataspace, updates and creates objects and executes procedures in the same order as they were previously added. The user interface will automatically report error messages.

    Calling this method is similar to calling execute(aDataSpace, true).

    Parameters:
      `aDataSpace` - the dataspace used when executing the transaction.
    Returns:
      the result of the execution.
    Throws:
      `UserServiceException` - if an object is not from the dataspace `aDataSpace`.

  - ### execute

    ProcedureResult execute(AdaptationHome aDataSpace, boolean addErrorMessageIfException)
    In the same transaction, on a given dataspace, updates and creates objects and executes procedures in the same order as they were previously added.
    Parameters:
      `aDataSpace` - the dataspace used when executing the transaction.
      `addErrorMessageIfException` - specifies if the user interface automatically reports an error message whenever the execution has encountered an error.
    Returns:
      the result of the execution.
    Throws:
      `UserServiceException` - if an object is not from the dataspace `aDataSpace`.