GdaXaTransaction

GdaXaTransaction — Distributed transaction manager

Stability Level

Stable, unless otherwise indicated

Types and Values

Description

The GdaXaTransaction object acts as a distributed transaction manager: to make sure local transactions on several connections (to possibly different databases and database types) either all succeed or all fail. For more information, see the X/Open CAE document Distributed Transaction Processing: The XA Specification. This document is published by The Open Group and available at

http://www.opengroup.org/public/pubs/catalog/c193.htm.

The two phases commit protocol is implemented during the execution of a distributed transaction: modifications made on any connection are first prepared (which means that they are store in the database), and if that phase succeeded for all the involved connections, then the commit phase is executed (where all the data previously stored during the prepare phase are actually committed). That second phase may actually fail, but the distributed transaction will still be considered as successfull as the data stored during the prepare phase can be committed afterwards.

A distributed transaction involves the following steps:

  1. Create a GdaXaTransaction object

  2. Register the connections which will be part of the distributed transaction with that object using gda_xa_transaction_register_connection()

  3. Beging the distributed transaction using gda_xa_transaction_begin()

  4. Work individually on each connection as normally (make modifications)

  5. Commit the distributed transaction using gda_xa_transaction_commit()

  6. Discard the GdaXaTransaction object using g_object_unref()

Functions

gda_xa_transaction_new ()

GdaXaTransaction *
gda_xa_transaction_new (guint32 format,
                        const gchar *global_transaction_id);

Creates a new GdaXaTransaction object, which will control the process of performing a distributed transaction across several connections.

Parameters

format

a format ID

 

global_transaction_id

the global transaction ID

 

Returns

the newly created object.

[transfer full]


gda_xa_transaction_register_connection ()

gboolean
gda_xa_transaction_register_connection
                               (GdaXaTransaction *xa_trans,
                                GdaConnection *cnc,
                                const gchar *branch,
                                GError **error);

Registers cnc to be used by xa_trans to create a distributed transaction.

Note: any GdaConnection object can only be registered with at most one GdaXaTransaction object; also some connections may not be registered at all with a GdaXaTransaction object because the database provider being used does not support it.

Parameters

xa_trans

a GdaXaTransaction object

 

cnc

the connection to add to xa_trans

 

branch

the branch qualifier

 

error

a place to store errors, or NULL.

[allow-none]

Returns

TRUE if no error occurred


gda_xa_transaction_unregister_connection ()

void
gda_xa_transaction_unregister_connection
                               (GdaXaTransaction *xa_trans,
                                GdaConnection *cnc);

Unregisters cnc to be used by xa_trans to create a distributed transaction. This is the opposite of gda_xa_transaction_register_connection().

Parameters

xa_trans

a GdaXaTransaction object

 

cnc

the connection to add to xa_trans

 

gda_xa_transaction_begin ()

gboolean
gda_xa_transaction_begin (GdaXaTransaction *xa_trans,
                          GError **error);

Begins a distributed transaction (managed by xa_trans ). Please note that this phase may fail for some connections if a (normal) transaction is already started (this depends on the database provider being used), so it's better to avoid starting any (normal) transaction on any of the connections registered with xa_trans .

Parameters

xa_trans

a GdaXaTransaction object

 

error

a place to store errors, or NULL.

[allow-none]

Returns

TRUE if no error occurred


gda_xa_transaction_commit ()

gboolean
gda_xa_transaction_commit (GdaXaTransaction *xa_trans,
                           GSList **cnc_to_recover,
                           GError **error);

Commits a distributed transaction (managed by xa_trans ). The commit is composed of two phases:

  • a PREPARE phase where all the connections are required to store their transaction data to a permanent place (to be able to complete the commit should a problem occur afterwards)

  • a COMMIT phase where the transaction data is actually written to the database

If the PREPARE phase fails for any of the connection registered with xa_trans , then the distributed commit fails and FALSE is returned. During the COMMIT phase, some commit may actually fail but the transaction can still be completed because the PREPARE phase succeeded (through the recover method).

Parameters

xa_trans

a GdaXaTransaction object

 

cnc_to_recover

a place to store the list of connections for which the commit phase failed, or NULL.

[allow-none][element-type Gda.Connection][out callee-allocates]

error

a place to store errors, or NULL

 

Returns

TRUE if no error occurred (there may be some connections to recover, though)


gda_xa_transaction_rollback ()

gboolean
gda_xa_transaction_rollback (GdaXaTransaction *xa_trans,
                             GError **error);

Cancels a distributed transaction (managed by xa_trans ).

Parameters

xa_trans

a GdaXaTransaction object

 

error

a place to store errors, or NULL.

[allow-none]

Returns

TRUE if no error occurred


gda_xa_transaction_commit_recovered ()

gboolean
gda_xa_transaction_commit_recovered (GdaXaTransaction *xa_trans,
                                     GSList **cnc_to_recover,
                                     GError **error);

Tries to commit the data prepared but which failed to commit (see gda_xa_transaction_commit()). This method allows one to terminate a distributed transaction which succeeded but for which some connections needed to be recovered.

Parameters

xa_trans

a GdaXaTransaction object

 

cnc_to_recover

a place to store the list of connections for which the there were data to recover and which failed to be actually committed, or NULL.

[allow-none][element-type Gda.Connection][out callee-allocates]

error

a place to store errors, or NULL.

[allow-none]

Returns

TRUE if all the data which was still uncommitted has been committed


gda_xa_transaction_id_to_string ()

gchar *
gda_xa_transaction_id_to_string (const GdaXaTransactionId *xid);

Creates a string representation of xid , in the format <gtrid>,<bqual>,<formatID> the <gtrid> and <bqual> strings contain alphanumeric characters, and non alphanumeric characters are converted to "ab" where ab is the hexadecimal representation of the character.

Parameters

xid

a GdaXaTransactionId pointer

 

Returns

a new string representation of xid .

[transfer full]


gda_xa_transaction_string_to_id ()

GdaXaTransactionId *
gda_xa_transaction_string_to_id (const gchar *str);

Creates a new GdaXaTransactionId structure from its string representation, it's the opposite of gda_xa_transaction_id_to_string().

Parameters

str

a string representation of a GdaXaTransactionId, in the "gtrid,bqual,formatID" format

 

Returns

a new GdaXaTransactionId structure, or NULL in str has a wrong format

Free-function: g_free

Types and Values

struct GdaXaTransaction

struct GdaXaTransaction {
	GObject                  object;
	GdaXaTransactionPrivate *priv;
};

enum GdaXaTransactionError

Members

GDA_XA_TRANSACTION_ALREADY_REGISTERED_ERROR

   

GDA_XA_TRANSACTION_DTP_NOT_SUPPORTED_ERROR

   

GDA_XA_TRANSACTION_CONNECTION_BRANCH_LENGTH_ERROR

   

struct GdaXaTransactionId

struct GdaXaTransactionId {
	guint32  format;
	gushort  gtrid_length;
	gushort  bqual_length;
	char     data [128];
};

Members

guint32 format;

any number

 

gushort gtrid_length;

number between 1 and 64

 

gushort bqual_length;

number between 1 and 64

 

char data[128];