Package com.orchestranetworks.service

# Interface Procedure

All Known Subinterfaces:
  `ReadOnlyProcedure`

public interface Procedure
This interface must be implemented in order to update data in a dataspace. In EBX®, a procedure is the way to implement a transaction.

For a read-only transaction, `ReadOnlyProcedure` must be implemented instead.

The execution of a procedure happens in a dataspace and has the following features:

- Atomicity
  The updates performed in the dataspace are either all committed or all cancelled (if execution fails), unless a `commit threshold` has been specified.
- Consistency
  Execution fails if there is a "structural" error, for instance if a record to be updated does not exist, or a value to be set is not compatible with the expected type or violates a blocking constraint. As for non-blocking constraints, they do not prevent the data update: the corresponding errors are detected and reported by the data validation layer; this tolerant policy allows tracking and correcting this kind of errors afterwards.
- Isolation
  See Transactions and concurrency.
- Durability
  All the updates performed in the dataspace are persisted.
- Logging
  The execution of a procedure is always logged. Procedure-specific `information` can be added.

See Also:
  - `UserServiceTransaction.add(Procedure)`
  - `ProcedureUtility.execute(Procedure, AdaptationHome)`
  - `ProgrammaticService.execute(Procedure)`
  - `ReadOnlyProcedure`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `execute(ProcedureContext aContext)`
  Defines what this transaction does in the dataspace specified by the container.

- ## Method Details

  - ### execute

    void execute(ProcedureContext aContext) throws Exception
    Defines what this transaction does in the dataspace specified by the container.

    #### Exception handling

    If this method throws an exception, the container properly handles it, by cancelling the current transaction.

    Furthermore, if a `ProcedureContext` method raises an exception, then any preceding modifications made on the repository are first cancelled before the client code gets the exception. This additional feature ensures that the repository and cache remain consistent, even if the client code catches exceptions.

    #### Transaction management and usage constraints.

    The following constraints apply:

    - A procedure can only impact the current dataspace.
    - A procedure cannot call a sub-procedure in the same dataspace in the same thread.
    - A procedure can call a sub-procedure on any other dataspace in the same thread. Limitation: If the main procedure fails after the sub-procedure has committed, the sub-procedure is not cancelled.
    Throws:
      `Exception`
    See Also:
      - `TableTrigger`