GnomeDbJoin

GnomeDbJoin — Represents a join between two different entities

Synopsis




            GnomeDbJoin;
enum        GnomeDbJoinType;
GType       gnome_db_join_get_type          (void);
GObject*    gnome_db_join_new_with_targets  (GnomeDbQuery *query,
                                             GnomeDbTarget *target_1,
                                             GnomeDbTarget *target_2);
GObject*    gnome_db_join_new_with_xml_ids  (GnomeDbQuery *query,
                                             const gchar *target_1_xml_id,
                                             const gchar *target_2_xml_id);
GObject*    gnome_db_join_new_copy          (GnomeDbJoin *orig,
                                             GHashTable *replacements);
void        gnome_db_join_set_join_type     (GnomeDbJoin *join,
                                             GnomeDbJoinType type);
GnomeDbJoinType gnome_db_join_get_join_type (GnomeDbJoin *join);
GnomeDbQuery* gnome_db_join_get_query       (GnomeDbJoin *join);
GnomeDbTarget* gnome_db_join_get_target_1   (GnomeDbJoin *join);
GnomeDbTarget* gnome_db_join_get_target_2   (GnomeDbJoin *join);
void        gnome_db_join_swap_targets      (GnomeDbJoin *join);
gboolean    gnome_db_join_set_condition     (GnomeDbJoin *join,
                                             GnomeDbCondition *cond);
GnomeDbCondition* gnome_db_join_get_condition
                                            (GnomeDbJoin *join);
gboolean    gnome_db_join_set_condition_from_fkcons
                                            (GnomeDbJoin *join);
gboolean    gnome_db_join_set_condition_from_sql
                                            (GnomeDbJoin *join,
                                             const gchar *cond,
                                             GError **error);
const gchar* gnome_db_join_render_type      (GnomeDbJoin *join);

Object Hierarchy


  GObject
   +----GnomeDbBase
         +----GnomeDbJoin

Implemented Interfaces

GnomeDbJoin implements GnomeDbXmlStorage and GnomeDbReferer.

Properties


  "prop"                 gpointer              : Read / Write

Signals


"condition-changed"
            void        user_function      (GnomeDbJoin *dbjoin,
                                            gpointer     user_data)      : Run first
"type-changed"
            void        user_function      (GnomeDbJoin *dbjoin,
                                            gpointer     user_data)      : Run first

Description

This object is a join, within a SELECT query, between two different entities participating in the query; the entoties are themselves represented by GnomeDbTarget objects. It is important to specify joinning conditions as joins and not simply as WHERE conditions because the joins carry more information than a simple condition and because some features of Libmergeant rely on the joins analysis.

It implements the GnomeDbXmlStorage and GnomeDbReferer interfaces.

Details

GnomeDbJoin

typedef struct _GnomeDbJoin GnomeDbJoin;


enum GnomeDbJoinType

typedef enum {
        GNOME_DB_JOIN_TYPE_INNER,
	GNOME_DB_JOIN_TYPE_LEFT_OUTER,
	GNOME_DB_JOIN_TYPE_RIGHT_OUTER,
	GNOME_DB_JOIN_TYPE_FULL_OUTER,
        GNOME_DB_JOIN_TYPE_CROSS,
        GNOME_DB_JOIN_TYPE_LAST
} GnomeDbJoinType;


gnome_db_join_get_type ()

GType       gnome_db_join_get_type          (void);

Returns :

gnome_db_join_new_with_targets ()

GObject*    gnome_db_join_new_with_targets  (GnomeDbQuery *query,
                                             GnomeDbTarget *target_1,
                                             GnomeDbTarget *target_2);

Creates a new GnomeDbJoin object. Note: the GnomeDbTarget ranks (1st and 2nd) does not matter, but is necessary since the join may not be symetrical (LEFT or RIGHT join). Also, the GnomeDbJoin object may decide to swap the two if necessary.

query : a GnomeDbQuery object in which the join will occur
target_1 : the 1st GnomeDbTarget object participating in the join
target_2 : the 2nd GnomeDbTarget object participating in the join
Returns : the new object

gnome_db_join_new_with_xml_ids ()

GObject*    gnome_db_join_new_with_xml_ids  (GnomeDbQuery *query,
                                             const gchar *target_1_xml_id,
                                             const gchar *target_2_xml_id);

Creates a new GnomeDbJoin object. Note: the GnomeDbTarget ranks (1st and 2nd) does not matter, but is necessary since the join may not be symetrical (LEFT or RIGHT join). Also, the GnomeDbJoin object may decide to swap the two if necessary.

query : a GnomeDbQuery object in which the join will occur
target_1_xml_id : the 1st GnomeDbTarget object's XML id participating in the join
target_2_xml_id : the 2nd GnomeDbTarget object's XML id participating in the join
Returns : the new object

gnome_db_join_new_copy ()

GObject*    gnome_db_join_new_copy          (GnomeDbJoin *orig,
                                             GHashTable *replacements);

Copy constructor

orig : a GnomeDbJoin to make a copy of
replacements : a hash table to store replacements, or NULL
Returns : a the new copy of orig

gnome_db_join_set_join_type ()

void        gnome_db_join_set_join_type     (GnomeDbJoin *join,
                                             GnomeDbJoinType type);

Sets the type of join

join : a GnomeDbJoin object
type : the new type of join

gnome_db_join_get_join_type ()

GnomeDbJoinType gnome_db_join_get_join_type (GnomeDbJoin *join);

Get the type of a join

join : a GnomeDbJoin object
Returns : the type of join

gnome_db_join_get_query ()

GnomeDbQuery* gnome_db_join_get_query       (GnomeDbJoin *join);

Get the GnomeDbQuery to which join is attached to

join : a GnomeDbJoin object
Returns : the GnomeDbQuery

gnome_db_join_get_target_1 ()

GnomeDbTarget* gnome_db_join_get_target_1   (GnomeDbJoin *join);

Get the 1st GnomeDbTarget participating in the join

join : a GnomeDbJoin object
Returns : the GnomeDbTarget

gnome_db_join_get_target_2 ()

GnomeDbTarget* gnome_db_join_get_target_2   (GnomeDbJoin *join);

Get the 2nd GnomeDbTarget participating in the join

join : a GnomeDbJoin object
Returns : the GnomeDbTarget

gnome_db_join_swap_targets ()

void        gnome_db_join_swap_targets      (GnomeDbJoin *join);

Changes the relative roles of the two GnomeDbTarget objects. It does not change the join condition itself, and is usefull only for the internals of the GnomeDbQuery object

join : a GnomeDbJoin object

gnome_db_join_set_condition ()

gboolean    gnome_db_join_set_condition     (GnomeDbJoin *join,
                                             GnomeDbCondition *cond);

Sets cond to be join's condition. This is possible only if cond uses query fields which are either of type GnomeDbQfField and reference one of the two targets which join uses, or any other query field type.

join : a GnomeDbJoin object
cond : a GnomeDbCondition object, or NULL to remove the join's condition
Returns : TRUE if no error occurred

gnome_db_join_get_condition ()

GnomeDbCondition* gnome_db_join_get_condition
                                            (GnomeDbJoin *join);

Get the join's associated condition

join : a GnomeDbJoin object
Returns : the GnomeDbCondition object

gnome_db_join_set_condition_from_fkcons ()

gboolean    gnome_db_join_set_condition_from_fkcons
                                            (GnomeDbJoin *join);

Creates a GnomeDbCondition for join using the foreign key constraints present in the database if the two targets join joins are database tables (GnomeDbTable objects).

If there is more than one FK constraint between the database tables, then no join is created, and the call returns FALSE.

join : a GnomeDbJoin object
Returns : TRUE if suitable foreign keys were found and a join condition has been created

gnome_db_join_set_condition_from_sql ()

gboolean    gnome_db_join_set_condition_from_sql
                                            (GnomeDbJoin *join,
                                             const gchar *cond,
                                             GError **error);

Parses cond and if it represents a valid SQL expression to be join's condition, then set it to be join's condition.

join : a GnomeDbJoin object
cond : a SQL expression
error : place to store the error, or NULL
Returns : a TRUE on success

gnome_db_join_render_type ()

const gchar* gnome_db_join_render_type      (GnomeDbJoin *join);

Get the SQL version of the join type ("INNER JOIN", "LEFT JOIN", etc)

join : a GnomeDbJoin object
Returns : the type as a const string

Property Details

The "prop" property

  "prop"                 gpointer              : Read / Write

Signal Details

The "condition-changed" signal

void        user_function                  (GnomeDbJoin *dbjoin,
                                            gpointer     user_data)      : Run first

dbjoin : the object which received the signal.
user_data : user data set when the signal handler was connected.

The "type-changed" signal

void        user_function                  (GnomeDbJoin *dbjoin,
                                            gpointer     user_data)      : Run first

dbjoin : the object which received the signal.
user_data : user data set when the signal handler was connected.