The following two database parameters affect Sagas:

• max_saga_duration: This database parameter defines the maximum time in seconds that a Saga is considered to be active and is not marked incomplete. max_saga_duration is the system default for Saga duration, You can override this value using the begin() API. A Saga is marked incomplete if any of its participants are unable to finalize the Saga within the Saga duration. An incomplete Saga can be finalized using the dbms_saga.rollback_saga() interface.

• saga_hist_retention: This database parameter defines the maximum time in days for retaining information for completed Sagas. The default value for saga_hist_retention is 30 days.

Preparatory Steps

This example sets up and configures a broker, two participants, namely TravelAgency and Airline, and their respective coordinator. Following these preparatory and provisioning steps, a Saga topology with two participants is created.

Steps 1 through 7 are executed on brokerPDB, 8 through 11 at TravelAgency, and 12 through 15 at AirlinePDB.

1. Provision or designate a pluggable database (PDB) called brokerPDB to host the broker.
2. At brokerPDB, create a mailbox user that owns the broker and its JMS topic. For example: MB.
3. Grant the role SAGA_ADM_ROLE to user MB.
4. Create a proxy user AirlineatMB (Role: SAGA_CONNECT_ROLE).
5. Create a proxy user TravelAgencyatMB (Role: SAGA_CONNECT_ROLE).
6. Create dblink LinkToAirline to Airline PDB using MBatAirline schema.
7. Create dblink LinkToTravelAgency to Travel PDB using MBatTravel schema.
8. Provision or designate a PDB called TravelAgency to host Travel Reservation service.
9. At the TravelAgency PDB, create a user TA.
10. Create a proxy user MBatTravelAgency (Role: SAGA_CONNECT_ROLE).
11. Create dblink LinktoBroker to brokerPDB using TravelAgencyatMB schema.
12. Provision or designate a PDB called AirlinePDB to host the Airline.
13. At AirlinePDB, create user Airline.
14. Create proxy user MBatAirline (Role SAGA_CONNECT_ROLE).
15. Create dblink LinktoBroker to brokerPDB using AirlineatMB schema.

DBA views and entries associated with the dictionary entries in this example can be found in the DBA_SAGA_PARTICIPANTS view. For more information about the DBA_SAGA_PARTICIPANTS view and the following DBA views, see the Database Reference Guide.

• DBA_SAGAS

• DBA_HIST_SAGAS

• DBA_INCOMPLETE_SAGAS

• DBA_SAGA_DETAILS

• DBA_PARTICIPANT_SET

• DBA_SAGA_FINALIZATION

• DBA_SAGA_PENDING

• DBA_SAGA_ERRORS

Provisioning Steps

BrokerPDB:

--Add a broker
dbms_saga_adm.add_broker(name=>'TravelBroker',  schema=>'MB');

TravelAgencyPDB:

--Add the Saga coordinator(local to the initiator)
 dbms_saga_adm.add_coordinator(
 coordinator_name => 'TACoordinator',
 dblink_to_broker => 'LinktoBroker',
 mailbox_schema => 'MB',
 broker_name => 'TravelBroker',
 dblink_to_coordinator => 'LinkToTravelAgency'
);

--Add the local Saga participant TravelAgency and its coordinator as below
 dbms_saga_adm.add_participant(
 participant_name=> 'TravelAgency',
 coordinator_name=> 'TACoordinator',
 dblink_to_broker=> 'LinktoBroker',
 mailbox_schema=> 'MB',
 broker_name=> 'TravelBroker',
 dblink_to_participant=> 'LinktoTravelAgency',
 callback_package => 'dbms_ta_cbk'
);

AirlinePDB:

--Add the local Saga participant Airline as below
 dbms_saga_adm.add_participant(
 participant_name=> 'Airline', 
 dblink_to_broker=> 'LinktoBroker',
 mailbox_schema=> 'MB',
 broker_name=> 'TravelBroker',
 dblink_to_participant=> 'LinktoAirline'
 callback_package => 'dbms_airline_cbk'
);

--Add a table with reservable column which maintains flight information
Create table flights(id NUMBER primary key,
 seats NUMBER reservable constraint flights_const check (seats > 0));

The following is a PL/SQL sample program depicting a Saga initiator (TravelAgency) and a Saga participant (Airline).

Saga Client Library

<dependency>
  <groupId>com.oracle.database.saga</groupId>
  <artifactId>saga-core</artifactId>
  <version>${SAGA_VERSION}</version>
</dependency>

JAX-RS Filter

<dependency>
  <groupId>com.oracle.database.saga</groupId>
  <artifactId>saga-filter</artifactId>
  <version>${SAGA_VERSION}</version>
</dependency>

JAX-RS Filter Configuration

The JAX-RS filter has the following parameters that can be configured using a property file (sagafilter.properties, application.properties, or both):

Participants Configuration

Each of the participants has the following parameters that can be configured using a property file (osaga.app.properties, application.properties, or both):

The following example illustrates the use of a subset of the important Saga annotations through a simple Travel Agency Saga application. The Travel Agency emulates a real travel agency that performs Airline reservations for its end users. The Travel Agency is a JAX-RS application (Initiator) that uses one participant: Airline. Airline is implemented as a standard Java application (not JAX-RS).

The Travel Agency and Airline leverage appropriate Saga annotations for performing their tasks. In this example, TravelAgency is the Saga initiator that initiates a Saga to purchase airline tickets for its end users. Airline is the Saga participant. The example is a simple illustration where only one reservation is made by a participant towards a Saga. In practice, a Saga may span multiple participants.

Other microservices, such as Hotel and CarRental would have a structure similar to the Airline microservice.

The Travel Agency could be modified in the following ways to accommodate another participant. Consider adding a Car Rental service:

• In TravelAgencyController’s booking method, another sendRequest() is required to send the payload to the “Car” participant.

  Saga.sendRequest ("Car", bookingPayload.getCar().toString());

• A new annotated method is required to handle responses from the Car service.

  @Response(sender = "Car”)

• Additional logic in the @Response methods is necessary to account for the state of the reservation after messages are received from participants.

  @Response(sender = "Car") 
  public void responseFromCar(SagaMessageContext info) {
    if (!info.getPayload().equals("success")) {
      /* On error, rollback right away */
      Saga.rollbackSaga ();
    } else {
      /* Store the car's response */
      cache.putCarResponse(info.getSagaId(), info.getPayload());
  
      /* Check to see if Airline has responded 
         If a response is found, commit */
      if (cache.containsAirlineResponse(info.getSagaId())) {
        Saga.commitSaga ();
      } 
    }
  }
  

The method to handle Airline’s response would be similar, except that it would replace cache.containsAirlineResponse(info.getSagaId()) with cache.containsCarResponse(info.getSagaId()) and cache.putAirlineResponse() with cache.putCarResponse().

The following asynchronous flow diagram shows the process flow of a Saga application illustrated in the previous code examples. The numbers in the flow diagram correspond to the numbers shown in the code snippet.

Figure 28-1 Asynchronous Flow

Saga Property File

The following shows the Saga property file used by the example program.

# JAX-RS filter properties 
osaga.filter.database.tnsAlias=ta
osaga.filter.database.walletPath=/Path/to/wallet
osaga.filter.database.tnsPath=/Path/to/tns
osaga.filter.initiator.publisherCount=2
osaga.filter.initiator.name=TravelAgency
osaga.travelagency.tnsAlias=ta

# Property values for the Initiator Travelagency
osaga.travelagency.walletPath=/Path/to/wallet
osaga.travelagency.tnsPath=/Path/to/tns
osaga.travelagency.numListeners=2
osaga.travelagency.numPublishers=2

# Properties pertaining to the Airline participant
osaga.airline.tnsAlias=airline1
osaga.airline.walletPath=/Path/to/wallet
osaga.airline.tnsPath=/Path/to/tns
osaga.airline.numListeners=2
osaga.airline.numPublishers=2

request Function

Syntax: function request(saga_id IN RAW, saga_sender IN VARCHAR2, payload IN JSON DEFAULT NULL) return JSON;

Description: The request function is invoked when receiving a Saga message with opcode REQUEST. The application is expected to implement this method. A JSON payload is returned that is sent back to the initiator as a response.

response Procedure

Syntax: procedure response(saga_id IN RAW, saga_sender IN VARCHAR2, payload IN JSON DEFAULT NULL)

Description: The response procedure is invoked when receiving a Saga message with opcode RESPONSE. The application is expected to implement this method.

before_commit Procedure

Syntax: procedure before_commit(saga_id IN RAW, saga_sender IN VARCHAR2, payload IN JSON DEFAULT NULL)

Description: The before_commit procedure is invoked before executing the Saga commit on the current participant when receiving a Saga message with opcode COMMIT for the same transaction. The before_commit() procedure is called before the lock-free reservation commits. The application is expected to implement this method and the applications that use lock-free reservations can choose whether to implement the before_commit() or after_commit() procedure.

after_commit Procedure

Syntax: procedure after_commit(saga_id IN RAW, saga_sender IN VARCHAR2, payload IN JSON DEFAULT NULL)

Description: The after_commit procedure is invoked after executing the Saga commit on the current participant when receiving a Saga message with opcode COMMIT for the same transaction. The after_commit procedure is called after the lock-free reservation commits. The application is expected to implement this method and the applications that use lock-free reservations can choose whether to implement the before_commit() or after_commit() procedure.

before_rollback Procedure

Syntax: procedure before_rollback(saga_id IN RAW, saga_sender IN VARCHAR2, payload IN JSON DEFAULT NULL)

Description: The before_rollback procedure is invoked before executing the Saga rollback on the current participant when receiving a Saga message with opcode ROLLBACK for the same transaction. The before_rollback procedure is called before the lock-free reservation rollbacks. The application is expected to implement this procedure and the applications that use lock-free reservations can choose whether to implement the before_rollback or after_rollback procedure.

after_rollback Procedure

Syntax: procedure after_rollback(saga_id IN RAW, saga_sender IN VARCHAR2, payload IN JSON DEFAULT NULL)

Description: The after_rollback procedure is invoked after executing the Saga rollback on the current participant when receiving a Saga message with opcode ROLLBACK for the same transaction. The after_rollback procedure is called after the lock-free reservation rollbacks. The application is expected to implement this procedure and the applications that use lock-free reservations can choose whether to implement the before_rollback or after_rollback procedure.

forget Procedure

Syntax: procedure forget(saga_id IN RAW, saga_sender IN VARCHAR2, payload IN JSON DEFAULT NULL)

Description: The Saga coordinator invokes the forget procedure to ask a participant to mark the Saga as forgotten. A Saga marked as forgotten cannot be finalized and requires administrative intervention. The forget procedure is triggered upon receiving a negative acknowledgment from the coordinator. A coordinator can respond with a negative acknowledgment to join requests. For example, if a Saga is set with a timeout and a participant join request is received after the timeout, a negative acknowledgment is sent to the participant. Another example of a negative acknowledgment is when a negative acknowledgment is sent on a join request made after a Saga has already been finalized by its initiator.

is_join Procedure

Syntax: procedure is_join (saga_id IN saga_id_t, saga_sender IN VARCHAR2);

Description: The Saga participants invoke the is_join procedure to disassociate themselves from the ongoing Sagas. The procedure gives the participant a choice to move ahead in this Saga or send a REJECT back to the initiator.

reject Procedure

Syntax: procedure reject (saga_id IN saga_id_t, saga_sender IN VARCHAR2);

Description: An initiator invokes the reject procedure and receives a notification if a participant rejected the invitation to join the Saga. A participant can return FALSE in their is_join method, which sends a REJECT message to the initiator.

after_saga Procedure

Syntax: procedure after_saga(saga_id in RAW, status in varchar2)

Description: For PL/SQL-based initiators, the after_saga procedure is invoked if defined in the callback package. For PL/SQL-based participants, the after_saga method is invoked if defined in the callback package and when event 10855 is set at level 512.

The argument status has the stringified values for enum(org.eclipse.microprofile.lra.annotation.LRAStatus).

Lock-free reservation enables automatic compensation (rollback) of changes to reservable columns. The reservation journal table records an entry for every update to a reservable column in the database. These entries provide the information needed for compensating changes to the reservable columns. The reservation journal entries associated with Saga-related changes to the reservable columns are retained until the Saga is finalized.

The Saga framework uses the saga_finalization$ dictionary table to track the set of reservable tables and their corresponding journals affected by a Saga. The creation of the reservation journal entry happens during the SQL update. For example, here is a sequence of updates and the respective saga_finalization$ entries:

Update hotel_rooms set rooms = rooms – 2 where date=to_date(‘20201010’);
Update hotel_rooms set rooms = rooms - 1 where date=to_date(‘20201011’);
Update dinner_tables set available_tables= available_tables - 3 where date=to_date(‘20201010’);

The Saga framework performs compensating actions during a Saga rollback. Reservation journal entries provide the data that is required to take compensatory actions for Saga transactions. The Saga framework sequentially processes the saga_finalization$ table for a Saga branch and executes the compensatory actions using the reservation journal. Saga_finalization$ entries are marked "compensated" upon successful Saga compensation. Saga_finalization$ entries are marked "committed" upon successful Saga commit. After a saga_finalization$ entry is marked as "compensated" or "committed", no further actions are possible.

After a Saga is finalized (successful commit or compensation), the reservation journal entries corresponding to all reservation journals associated with the Saga are deleted. The saga_finalization$ entries for the given Saga are also deleted.