Package com.orchestranetworks.d3

# Interface D3Broadcast

public interface D3Broadcast
The broadcast handler contains the information used in the broadcast distributed transaction.

This object is created using one the following methods:

- `D3NodeAsMaster.getHandlerForAsynchronousBroadcast(VersionKey)`
- `D3NodeAsMaster.getHandlerForSynchronousBroadcast(VersionKey)`
- `D3NodeAsMaster.getHandlerForSynchronousBroadcast(VersionKey, long)`.

When created, the broadcast handler can be used in the method `broadcast()`.

This object contains information about the broadcast operation, such as:

- Synchronization mode:
  - if synchronous: after launching the broadcast operation, the method waits for the end of broadcast notification
  - if asynchronous: the method only queues the broadcast operation without waiting for the end of the operation
- Operation time out: if in synchronized mode, this corresponds to the time out of the operation (no effect on the broadcast). If this object is not notified when the time out is reached, the broadcast method throws an `OperationException`.
- `VersionKey` of the delivery dataspace to broadcast.
- Delivery status of the broadcast operation.
- Message of the broadcast operation.
- Stack trace on operation failure.

See Broadcast for more information.

Since:
  5.2.7

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `D3Broadcast.Status`
  Global status of the snapshot broadcast operation.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `broadcast()`
  Broadcasts a snapshot in synchronous or asynchronous mode depending on the way this object has been obtained.
  `List<DeliveryMode>`
  `getDeliveryModes()`
  Returns a list of delivery modes used in this broadcast handler.
  `D3Broadcast.Status`
  `getDeliveryStatus()`
  Deprecated.
  Since 5.4.0
  `D3Broadcast.Status`
  `getDeliveryStatus(DeliveryMode aDeliveryMode)`
  Global delivery status depending on the delivery mode ('Cluster' or 'Federation').
  If the broadcast operation is waiting for its turn:
  returns `'Not initialized'` status regardless of the delivery mode If the delivery mode in the parameter is not relevant:
  throws an `IllegalArgumentException`
  `String`
  `getMessage()`
  Returns the message of the broadcast operation.
  `long`
  `getOperationTimeOut()`
  Returns the operation time-out in milliseconds.
  `String`
  `getStackTrace()`
  Returns the stack trace of the broadcast operation if it failed.
  `VersionKey`
  `getVersionKey()`
  Returns the `VersionKey` of the snapshot to broadcast.
  `boolean`
  `isFullResync()`
  Returns `true` if the operation is full resynchronization concerned.
  `void`
  `setOperationTimeOut(long aOperationTimeOut)`
  Sets the operation time out.

- ## Method Details

  - ### broadcast

    void broadcast() throws OperationException
    Broadcasts a snapshot in synchronous or asynchronous mode depending on the way this object has been obtained.

    It can be created using one of these three methods in the API:

    - `D3NodeAsMaster.getHandlerForAsynchronousBroadcast(VersionKey)`
    - `D3NodeAsMaster.getHandlerForSynchronousBroadcast(VersionKey, long)`
    - `D3NodeAsMaster.getHandlerForSynchronousBroadcast(VersionKey)`
    This snapshot must belong to a delivery dataspace, which is associated with a delivery profile.

    This object is notified upon broadcast termination (after a commit or rollback transaction). It then provides:

    - Status of the transaction
    - Reason for failure if rollback occurs
    - Map of the replica nodes and their statuses
    Throws:
      `OperationException` -
      - if the owner of the current session is not allowed to broadcast
      - if snapshot validation report has its severity higher than the threshold
      - if 'D3 Master configuration' technical dataspace has validation errors
      - if the broadcast process exceeds the operation timeout (for synchronous mode only)

  - ### setOperationTimeOut

    void setOperationTimeOut(long aOperationTimeOut)
    Sets the operation time out. Ignored if the synchronization mode is `asynchronous`.
    Parameters:
      `aOperationTimeOut` - in milliseconds.
    Throws:
      `IllegalArgumentException` - if `aOperationTimeOut` is negative.

  - ### getOperationTimeOut

    long getOperationTimeOut()
    Returns the operation time-out in milliseconds. If the synchronization mode is `asynchronous`, returns `-1`.

  - ### getVersionKey

    VersionKey getVersionKey()
    Returns the `VersionKey` of the snapshot to broadcast.

  - ### getDeliveryModes

    List<DeliveryMode> getDeliveryModes()
    Returns a list of delivery modes used in this broadcast handler.
    Since:
      5.4.0

  - ### getDeliveryStatus

    D3Broadcast.Status getDeliveryStatus(DeliveryMode aDeliveryMode)
    Global delivery status depending on the delivery mode ('Cluster' or 'Federation').
    If the broadcast operation is waiting for its turn:
    - returns `'Not initialized'` status regardless of the delivery mode
    If the delivery mode in the parameter is not relevant:
    - throws an `IllegalArgumentException`
    Since:
      5.4.0

  - ### getDeliveryStatus

    @Deprecated D3Broadcast.Status getDeliveryStatus()
    Deprecated.
    Since 5.4.0
    Returns the global delivery status of the broadcast handler for the default delivery mode (clustered).
    See Also:
      - `getDeliveryStatus(DeliveryMode)`

  - ### isFullResync

    boolean isFullResync()
    Returns `true` if the operation is full resynchronization concerned. Otherwise, returns `false`.
    Since:
      5.5.1

  - ### getMessage

    String getMessage()
    Returns the message of the broadcast operation.

  - ### getStackTrace

    String getStackTrace()
    Returns the stack trace of the broadcast operation if it failed. Otherwise, returns `null`.