1 /* 2 * Copyright (C) 2008 - 2011 Vivien Malerba <malerba@gnome-db.org> 3 * Copyright (C) 2011 Murray Cumming <murrayc@murrayc.com> 4 * 5 * This library is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Lesser General Public 7 * License as published by the Free Software Foundation; either 8 * version 2 of the License, or (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public 16 * License along with this library; if not, write to the 17 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 18 * Boston, MA 02110-1301, USA. 19 */ 20 21 #ifndef __GDA_XA_TRANSACTION_H__ 22 #define __GDA_XA_TRANSACTION_H__ 23 24 #include <glib-object.h> 25 #include <libgda/gda-enums.h> 26 #include <libgda/gda-decl.h> 27 28 G_BEGIN_DECLS 29 30 #define GDA_TYPE_XA_TRANSACTION (gda_xa_transaction_get_type()) 31 #define GDA_XA_TRANSACTION(obj) (G_TYPE_CHECK_INSTANCE_CAST (obj, GDA_TYPE_XA_TRANSACTION, GdaXaTransaction)) 32 #define GDA_XA_TRANSACTION_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST (klass, GDA_TYPE_XA_TRANSACTION, GdaXaTransactionClass)) 33 #define GDA_IS_XA_TRANSACTION(obj) (G_TYPE_CHECK_INSTANCE_TYPE(obj, GDA_TYPE_XA_TRANSACTION)) 34 #define GDA_IS_XA_TRANSACTION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), GDA_TYPE_XA_TRANSACTION)) 35 36 typedef struct _GdaXaTransaction GdaXaTransaction; 37 typedef struct _GdaXaTransactionClass GdaXaTransactionClass; 38 typedef struct _GdaXaTransactionPrivate GdaXaTransactionPrivate; 39 typedef struct _GdaXaTransactionId GdaXaTransactionId; 40 41 /* error reporting */ 42 extern GQuark gda_xa_transaction_error_quark (void); 43 #define GDA_XA_TRANSACTION_ERROR gda_xa_transaction_error_quark () 44 45 typedef enum 46 { 47 GDA_XA_TRANSACTION_ALREADY_REGISTERED_ERROR, 48 GDA_XA_TRANSACTION_DTP_NOT_SUPPORTED_ERROR, 49 GDA_XA_TRANSACTION_CONNECTION_BRANCH_LENGTH_ERROR 50 } GdaXaTransactionError; 51 52 struct _GdaXaTransaction { 53 GObject object; 54 GdaXaTransactionPrivate *priv; 55 }; 56 57 struct _GdaXaTransactionClass { 58 GObjectClass parent_class; 59 60 /*< private >*/ 61 /* Padding for future expansion */ 62 void (*_gda_reserved1) (void); 63 void (*_gda_reserved2) (void); 64 void (*_gda_reserved3) (void); 65 void (*_gda_reserved4) (void); 66 }; 67 68 69 /** 70 * GdaXaTransactionId: 71 * @format: any number 72 * @gtrid_length: number between 1 and 64 73 * @bqual_length: number between 1 and 64 74 * @data: 75 */ 76 struct _GdaXaTransactionId { 77 guint32 format; 78 gushort gtrid_length; 79 gushort bqual_length; 80 char data [128]; 81 }; 82 83 /** 84 * SECTION:gda-xa-transaction 85 * @short_description: Distributed transaction manager 86 * @title: GdaXaTransaction 87 * @stability: Stable 88 * @see_also: 89 * 90 * The #GdaXaTransaction object acts as a distributed transaction manager: to make sure local transactions on several 91 * connections (to possibly different databases and database types) either all succeed or all fail. For more information, 92 * see the X/Open CAE document Distributed Transaction Processing: The XA Specification. 93 * This document is published by The Open Group and available at 94 * <ulink url="http://www.opengroup.org/public/pubs/catalog/c193.htm">http://www.opengroup.org/public/pubs/catalog/c193.htm</ulink>. 95 * 96 * The two phases commit protocol is implemented during the execution of a distributed transaction: modifications 97 * made on any connection are first <emphasis>prepared</emphasis> (which means that they are store in the database), and 98 * if that phase succeeded for all the involved connections, then the <emphasis>commit</emphasis> phase is executed 99 * (where all the data previously stored during the <emphasis>prepare</emphasis> phase are actually committed). 100 * That second phase may actually fail, but the distributed transaction will still be considered as successfull 101 * as the data stored during the <emphasis>prepare</emphasis> phase can be committed afterwards. 102 * 103 * A distributed transaction involves the following steps: 104 * <orderedlist> 105 * <listitem><para>Create a #GdaXaTransaction object</para></listitem> 106 * <listitem><para>Register the connections which will be part of the distributed transaction with that object 107 * using gda_xa_transaction_register_connection()</para></listitem> 108 * <listitem><para>Beging the distributed transaction using gda_xa_transaction_begin()</para></listitem> 109 * <listitem><para>Work individually on each connection as normally (make modifications)</para></listitem> 110 * <listitem><para>Commit the distributed transaction using gda_xa_transaction_commit()</para></listitem> 111 * <listitem><para>Discard the #GdaXaTransaction object using g_object_unref()</para></listitem> 112 * </orderedlist> 113 */ 114 115 GType gda_xa_transaction_get_type (void) G_GNUC_CONST; 116 GdaXaTransaction *gda_xa_transaction_new (guint32 format, const gchar *global_transaction_id); 117 118 gboolean gda_xa_transaction_register_connection (GdaXaTransaction *xa_trans, GdaConnection *cnc, 119 const gchar *branch, GError **error); 120 void gda_xa_transaction_unregister_connection (GdaXaTransaction *xa_trans, GdaConnection *cnc); 121 122 gboolean gda_xa_transaction_begin (GdaXaTransaction *xa_trans, GError **error); 123 gboolean gda_xa_transaction_commit (GdaXaTransaction *xa_trans, GSList **cnc_to_recover, GError **error); 124 gboolean gda_xa_transaction_rollback (GdaXaTransaction *xa_trans, GError **error); 125 126 gboolean gda_xa_transaction_commit_recovered (GdaXaTransaction *xa_trans, GSList **cnc_to_recover, 127 GError **error); 128 129 /* utility functions */ 130 gchar *gda_xa_transaction_id_to_string (const GdaXaTransactionId *xid); 131 GdaXaTransactionId *gda_xa_transaction_string_to_id (const gchar *str); 132 133 G_END_DECLS 134 135 #endif 136