## MgJoin

MgJoin — Represents a join between two different entities

## Synopsis

    struct      MgJoin;
    enum        MgJoinType;
    guint       mg_join_get_type                (void);
    GObject*    mg_join_new_with_targets        (MgQuery *query,
                                                 MgTarget *target_1,
                                                 MgTarget *target_2);
    GObject*    mg_join_new_with_xml_ids        (MgQuery *query,
                                                 const gchar *target_1_xml_id,
                                                 const gchar *target_2_xml_id);
    GObject*    mg_join_new_copy                (MgJoin *orig,
                                                 GHashTable *replacements);
    void        mg_join_set_join_type           (MgJoin *join,
                                                 MgJoinType type);
    MgJoinType  mg_join_get_join_type           (MgJoin *join);
    MgQuery*    mg_join_get_query               (MgJoin *join);
    MgTarget*   mg_join_get_target_1            (MgJoin *join);
    MgTarget*   mg_join_get_target_2            (MgJoin *join);
    void        mg_join_swap_targets            (MgJoin *join);
    gboolean    mg_join_set_condition           (MgJoin *join,
                                                 MgCondition *cond);
    MgCondition* mg_join_get_condition          (MgJoin *join);
    const gchar* mg_join_render_type            (MgJoin *join);

## Object Hierarchy

      GObject
       +----MgBase
             +----MgJoin

## Implemented Interfaces

MgJoin implements MgXmlStorage and MgReferer.

## Properties

      "prop"                 gpointer             : Read / Write

## Signal Prototypes

    "condition-changed"
                void        user_function      (MgJoin *mgjoin,
                                                gpointer user_data);
    "type-changed"
                void        user_function      (MgJoin *mgjoin,
                                                gpointer user_data);

## Description

This object is a join, within a SELECT query, between two different entities participating in the query; the entoties are themselves represented by MgTarget 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 MgXmlStorage and MgReferer interfaces.

## Details

### struct MgJoin

    struct MgJoin;

### enum MgJoinType

    typedef enum {
            MG_JOIN_TYPE_INNER,
    	MG_JOIN_TYPE_LEFT_OUTER,
    	MG_JOIN_TYPE_RIGHT_OUTER,
    	MG_JOIN_TYPE_FULL_OUTER,
            MG_JOIN_TYPE_CROSS,
            MG_JOIN_TYPE_LAST
    } MgJoinType;

### mg_join_get_type ()

    guint       mg_join_get_type                (void);

Returns : |

### mg_join_new_with_targets ()

    GObject*    mg_join_new_with_targets        (MgQuery *query,
                                                 MgTarget *target_1,
                                                 MgTarget *target_2);

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

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

### mg_join_new_with_xml_ids ()

    GObject*    mg_join_new_with_xml_ids        (MgQuery *query,
                                                 const gchar *target_1_xml_id,
                                                 const gchar *target_2_xml_id);

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

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

### mg_join_new_copy ()

    GObject*    mg_join_new_copy                (MgJoin *orig,
                                                 GHashTable *replacements);

Copy constructor

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

### mg_join_set_join_type ()

    void        mg_join_set_join_type           (MgJoin *join,
                                                 MgJoinType type);

Sets the type of `join`

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

### mg_join_get_join_type ()

    MgJoinType  mg_join_get_join_type           (MgJoin *join);

Get the type of a join

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

### mg_join_get_query ()

    MgQuery*    mg_join_get_query               (MgJoin *join);

Get the MgQuery to which `join` is attached to

`join` : | a MgJoin object
Returns : | the MgQuery

### mg_join_get_target_1 ()

    MgTarget*   mg_join_get_target_1            (MgJoin *join);

Get the 1st MgTarget participating in the join

`join` : | a MgJoin object
Returns : | the MgTarget

### mg_join_get_target_2 ()

    MgTarget*   mg_join_get_target_2            (MgJoin *join);

Get the 2nd MgTarget participating in the join

`join` : | a MgJoin object
Returns : | the MgTarget

### mg_join_swap_targets ()

    void        mg_join_swap_targets            (MgJoin *join);

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

`join` : | a MgJoin object

### mg_join_set_condition ()

    gboolean    mg_join_set_condition           (MgJoin *join,
                                                 MgCondition *cond);

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

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

### mg_join_get_condition ()

    MgCondition* mg_join_get_condition          (MgJoin *join);

Get the join's associated condition

`join` : | a MgJoin object
Returns : | the MgCondition object

### mg_join_render_type ()

    const gchar* mg_join_render_type            (MgJoin *join);

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

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

## Properties

"`prop`" (gpointer : Read / Write) |

## Signals

### The "condition-changed" signal

    void        user_function                  (MgJoin *mgjoin,
                                                gpointer user_data);

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

### The "type-changed" signal

    void        user_function                  (MgJoin *mgjoin,
                                                gpointer user_data);

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