# Gnome::Gda::XaTransaction Class Reference

Distributed transaction manager. More...

Inheritance diagram for Gnome::Gda::XaTransaction:
[legend]
Collaboration diagram for Gnome::Gda::XaTransaction:
[legend]

List of all members.

## Public Types

typedef std::vector < Glib::RefPtr< const Connection > > | ConnectionVector

## Public Member Functions

virtual | ~XaTransaction ()
GdaXaTransaction* | gobj ()
| Provides access to the underlying C GObject.
const GdaXaTransaction* | gobj () const
| Provides access to the underlying C GObject.
GdaXaTransaction* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
bool | register_connection (const Glib::RefPtr< Connection >& cnc, const Glib::ustring& branch)
| Registers cnc to be used by xa_trans to create a distributed transaction.
void | unregister_connection (const Glib::RefPtr< Connection >& cnc)
| Unregisters cnc to be used by xa_trans to create a distributed transaction.
bool | begin ()
| Begins a distributed transaction (managed by xa_trans).
bool | rollback ()
| Cancels a distributed transaction (managed by xa_trans).
bool | commit (ConnectionVector& cnc_to_recover)
| Commits a distributed transaction (managed by xa_trans).
bool | commit_recovered (ConnectionVector& cnc_to_recover)
| Tries to commit the data prepared but which failed to commit (see commit()).
Glib::PropertyProxy_ReadOnly < Glib::ustring > | property_transaction_id () const
| You rarely need to use properties because there are get_ and set_ methods for almost all of them.
Glib::PropertyProxy_ReadOnly < guint > | property_format_id () const
| You rarely need to use properties because there are get_ and set_ methods for almost all of them.

## Static Public Member Functions

static Glib::RefPtr < XaTransaction > | create (guint32 format_id, const Glib::ustring& transaction_id)

## Protected Member Functions

| XaTransaction (guint32 format_id, const Glib::ustring& transaction_id)

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr < Gnome::Gda::XaTransaction > | wrap (GdaXaTransaction* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

Distributed transaction manager.

## Member Typedef Documentation

typedef std::vector<Glib::RefPtr<const Connection> > Gnome::Gda::XaTransaction::ConnectionVector

## Constructor & Destructor Documentation

virtual Gnome::Gda::XaTransaction::~XaTransaction | ( | ) | `[virtual]`

Gnome::Gda::XaTransaction::XaTransaction | ( | guint32 | format_id,
|  | const Glib::ustring & | transaction_id
| ) |  | `[explicit, protected]`

## Member Function Documentation

bool Gnome::Gda::XaTransaction::begin | ( | ) |

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.

Returns:
  `true` if no error occurred.

bool Gnome::Gda::XaTransaction::commit | ( | ConnectionVector & | cnc_to_recover ) |

Commits a distributed transaction (managed by xa_trans).

The commit is composed of two phases: <itemizedlist> <listitem>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)</listitem> <listitem>a COMMIT phase where the transaction data is actually written to the database</listitem> </itemizedlist>

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:

  cnc_to_recover | A place to store the list of connections for which the commit phase failed, or `0`.

Returns:
  `true` if no error occurred (there may be some connections to recover, though).

bool Gnome::Gda::XaTransaction::commit_recovered | ( | ConnectionVector & | cnc_to_recover ) |

Tries to commit the data prepared but which failed to commit (see commit()).

This method allows one to terminate a distributed transaction which succeeded but for which some connections needed to be recovered.

Parameters:

  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 `0`.

Returns:
  `true` if all the data which was still uncommitted has been committed.

static Glib::RefPtr<XaTransaction> Gnome::Gda::XaTransaction::create | ( | guint32 | format_id,
|  | const Glib::ustring & | transaction_id
| ) |  | `[static]`

GdaXaTransaction* Gnome::Gda::XaTransaction::gobj | ( | ) | `[inline]`

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

const GdaXaTransaction* Gnome::Gda::XaTransaction::gobj | ( | ) | const`[inline]`

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

GdaXaTransaction* Gnome::Gda::XaTransaction::gobj_copy | ( | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Glib::PropertyProxy_ReadOnly<guint> Gnome::Gda::XaTransaction::property_format_id | ( | ) | const

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<Glib::ustring> Gnome::Gda::XaTransaction::property_transaction_id | ( | ) | const

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

bool Gnome::Gda::XaTransaction::register_connection | ( | const Glib::RefPtr< Connection >& | cnc,
|  | const Glib::ustring & | branch
| ) |  |

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

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

Parameters:

  cnc | The connection to add to xa_trans.
  branch | The branch qualifier.

Returns:
  `true` if no error occurred.

bool Gnome::Gda::XaTransaction::rollback | ( | ) |

Cancels a distributed transaction (managed by xa_trans).

Returns:
  `true` if no error occurred.

void Gnome::Gda::XaTransaction::unregister_connection | ( | const Glib::RefPtr< Connection >& | cnc ) |

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

This is the opposite of register_connection().

Parameters:

  cnc | The connection to add to xa_trans.

## Friends And Related Function Documentation

Glib::RefPtr< Gnome::Gda::XaTransaction > wrap | ( | GdaXaTransaction * | object,
|  | bool | take_copy = `false`
| ) |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- libgdamm/xatransaction.h