## GdaQueryJoin GdaQueryJoin — Represents a join between two different entities |

## Synopsis

                        GdaQueryJoin;
    enum                GdaQueryJoinType;
    GdaQueryJoin*       gda_query_join_new_with_targets     (GdaQuery *query,
                                                             GdaQueryTarget *target_1,
                                                             GdaQueryTarget *target_2);
    GdaQueryJoin*       gda_query_join_new_with_xml_ids     (GdaQuery *query,
                                                             const gchar *target_1_xml_id,
                                                             const gchar *target_2_xml_id);
    GdaQueryJoin*       gda_query_join_new_copy             (GdaQueryJoin *orig,
                                                             GHashTable *replacements);
    void                gda_query_join_set_join_type        (GdaQueryJoin *join,
                                                             GdaQueryJoinType type);
    GdaQueryJoinType    gda_query_join_get_join_type        (GdaQueryJoin *join);
    GdaQuery*           gda_query_join_get_query            (GdaQueryJoin *join);
    GdaQueryTarget*     gda_query_join_get_target_1         (GdaQueryJoin *join);
    GdaQueryTarget*     gda_query_join_get_target_2         (GdaQueryJoin *join);
    void                gda_query_join_swap_targets         (GdaQueryJoin *join);
    gboolean            gda_query_join_set_condition_from_fkcons
                                                            (GdaQueryJoin *join);
    gboolean            gda_query_join_set_condition_from_sql
                                                            (GdaQueryJoin *join,
                                                             const gchar *cond,
                                                             GError **error);
    gboolean            gda_query_join_set_condition        (GdaQueryJoin *join,
                                                             GdaQueryCondition *cond);
    GdaQueryCondition*  gda_query_join_get_condition        (GdaQueryJoin *join);
    const gchar*        gda_query_join_render_type          (GdaQueryJoin *join);

## Object Hierarchy

      GObject
       +----GdaObject
             +----GdaQueryObject
                   +----GdaQueryJoin

## Implemented Interfaces

GdaQueryJoin implements GdaXmlStorage and GdaReferer.

## Properties

      "query"                    GdaQuery*             : Read / Write / Construct Only
      "target1"                  GdaQueryTarget*       : Read / Write
      "target1-id"               gchar*                : Write
      "target2"                  GdaQueryTarget*       : Read / Write
      "target2-id"               gchar*                : Write

## Signals

      "condition-changed"                              : Run First
      "type-changed"                                   : 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 GdaQueryTarget 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 GdaXmlStorage and GdaReferer interfaces.

## Details

### GdaQueryJoin

    typedef struct _GdaQueryJoin GdaQueryJoin;

### Warning

`GdaQueryJoin` is deprecated and should not be used in newly-written code.

### enum GdaQueryJoinType

    typedef enum {
            GDA_QUERY_JOIN_TYPE_INNER,
    	GDA_QUERY_JOIN_TYPE_LEFT_OUTER,
    	GDA_QUERY_JOIN_TYPE_RIGHT_OUTER,
    	GDA_QUERY_JOIN_TYPE_FULL_OUTER,
            GDA_QUERY_JOIN_TYPE_CROSS,
            GDA_QUERY_JOIN_TYPE_LAST
    } GdaQueryJoinType;

### Warning

`GdaQueryJoinType` is deprecated and should not be used in newly-written code.

### gda_query_join_new_with_targets ()

    GdaQueryJoin*       gda_query_join_new_with_targets     (GdaQuery *query,
                                                             GdaQueryTarget *target_1,
                                                             GdaQueryTarget *target_2);

### Warning

`gda_query_join_new_with_targets` is deprecated and should not be used in newly-written code.

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

`query` : | a GdaQuery object in which the join will occur
`target_1` : | the 1st GdaQueryTarget object participating in the join
`target_2` : | the 2nd GdaQueryTarget object participating in the join
Returns : | the new object

### gda_query_join_new_with_xml_ids ()

    GdaQueryJoin*       gda_query_join_new_with_xml_ids     (GdaQuery *query,
                                                             const gchar *target_1_xml_id,
                                                             const gchar *target_2_xml_id);

### Warning

`gda_query_join_new_with_xml_ids` is deprecated and should not be used in newly-written code.

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

`query` : | a GdaQuery object in which the join will occur
`target_1_xml_id` : | the 1st GdaQueryTarget object's XML id participating in the join
`target_2_xml_id` : | the 2nd GdaQueryTarget object's XML id participating in the join
Returns : | the new object

### gda_query_join_new_copy ()

    GdaQueryJoin*       gda_query_join_new_copy             (GdaQueryJoin *orig,
                                                             GHashTable *replacements);

### Warning

`gda_query_join_new_copy` is deprecated and should not be used in newly-written code.

Copy constructor

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

### gda_query_join_set_join_type ()

    void                gda_query_join_set_join_type        (GdaQueryJoin *join,
                                                             GdaQueryJoinType type);

### Warning

`gda_query_join_set_join_type` is deprecated and should not be used in newly-written code.

Sets the type of `join`

`join` : | a GdaQueryJoin object
`type` : | the new type of join

### gda_query_join_get_join_type ()

    GdaQueryJoinType    gda_query_join_get_join_type        (GdaQueryJoin *join);

### Warning

`gda_query_join_get_join_type` is deprecated and should not be used in newly-written code.

Get the type of a join

`join` : | a GdaQueryJoin object
Returns : | the type of `join`

### gda_query_join_get_query ()

    GdaQuery*           gda_query_join_get_query            (GdaQueryJoin *join);

### Warning

`gda_query_join_get_query` is deprecated and should not be used in newly-written code.

Get the GdaQuery to which `join` is attached to

`join` : | a GdaQueryJoin object
Returns : | the GdaQuery

### gda_query_join_get_target_1 ()

    GdaQueryTarget*     gda_query_join_get_target_1         (GdaQueryJoin *join);

### Warning

`gda_query_join_get_target_1` is deprecated and should not be used in newly-written code.

Get the 1st GdaQueryTarget participating in the join

`join` : | a GdaQueryJoin object
Returns : | the GdaQueryTarget

### gda_query_join_get_target_2 ()

    GdaQueryTarget*     gda_query_join_get_target_2         (GdaQueryJoin *join);

### Warning

`gda_query_join_get_target_2` is deprecated and should not be used in newly-written code.

Get the 2nd GdaQueryTarget participating in the join

`join` : | a GdaQueryJoin object
Returns : | the GdaQueryTarget

### gda_query_join_swap_targets ()

    void                gda_query_join_swap_targets         (GdaQueryJoin *join);

### Warning

`gda_query_join_swap_targets` is deprecated and should not be used in newly-written code.

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

`join` : | a GdaQueryJoin object

### gda_query_join_set_condition_from_fkcons ()

    gboolean            gda_query_join_set_condition_from_fkcons
                                                            (GdaQueryJoin *join);

### Warning

`gda_query_join_set_condition_from_fkcons` is deprecated and should not be used in newly-written code.

Creates a GdaQueryCondition for `join` using the foreign key constraints present in the database if the two targets `join` joins are database tables (GdaDictTable 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 GdaQueryJoin object
Returns : | TRUE if suitable foreign keys were found and a join condition has been created

### gda_query_join_set_condition_from_sql ()

    gboolean            gda_query_join_set_condition_from_sql
                                                            (GdaQueryJoin *join,
                                                             const gchar *cond,
                                                             GError **error);

### Warning

`gda_query_join_set_condition_from_sql` is deprecated and should not be used in newly-written code.

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 GdaQueryJoin object
`cond` : | a SQL expression
`error` : | place to store the error, or `NULL`
Returns : | a TRUE on success

### gda_query_join_set_condition ()

    gboolean            gda_query_join_set_condition        (GdaQueryJoin *join,
                                                             GdaQueryCondition *cond);

### Warning

`gda_query_join_set_condition` is deprecated and should not be used in newly-written code.

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

`join` : | a GdaQueryJoin object
`cond` : | a GdaQueryCondition object, or `NULL` to remove the join's condition
Returns : | TRUE if no error occurred

### gda_query_join_get_condition ()

    GdaQueryCondition*  gda_query_join_get_condition        (GdaQueryJoin *join);

### Warning

`gda_query_join_get_condition` is deprecated and should not be used in newly-written code.

Get the join's associated condition

`join` : | a GdaQueryJoin object
Returns : | the GdaQueryCondition object

### gda_query_join_render_type ()

    const gchar*        gda_query_join_render_type          (GdaQueryJoin *join);

### Warning

`gda_query_join_render_type` is deprecated and should not be used in newly-written code.

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

`join` : | a GdaQueryJoin object
Returns : | the type as a const string

## Property Details

### The `"query"` property

      "query"                    GdaQuery*             : Read / Write / Construct Only

### The `"target1"` property

      "target1"                  GdaQueryTarget*       : Read / Write

### The `"target1-id"` property

      "target1-id"               gchar*                : Write

Default value: NULL

### The `"target2"` property

      "target2"                  GdaQueryTarget*       : Read / Write

### The `"target2-id"` property

      "target2-id"               gchar*                : Write

Default value: NULL

## Signal Details

### The `"condition-changed"` signal

    void                user_function                      (GdaQueryJoin *gdaqueryjoin,
                                                            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                      (GdaQueryJoin *gdaqueryjoin,
                                                            gpointer      user_data)         : Run First

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