UT_ORMManyToManyField.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_ORMManyToManyField.h
 *
 * COMMENTS:
 *
 *  The UT_ORMManyToManyField is a powerful field that lets models define
 *  a M2M relationship between each other. The ORM system will generate the
 *  corresponding through table for the relationship. Note that objects are
 *  loaded on an as needed bases so theres no performance cost to defining
 *  these objects on models.
 *
 *  See UT_SQLORM for more information on the ORM system.
 *
 *  Example:
 *
 *      The below example highlights how easy it is to work with M2M
 *      relationships through the ORM system as all the complex work is
 *      auto generated and the developer can focus on the actual task at
 *      hand.
 *
 *  class User : public UT_ORMModel<User>
 *  {
 *  public:
 *      class Meta : public UT_ORMModelMeta
 *      {
 *          void doBuild() override
 *          {
 *              // Since the m2m isnt an actual column on the db the field
 *              // name isnt as important. It mainly lets you search via field
 *              // name. Using UT_ORMManyToManyField makes that not necessary
 *              // as it does that for you.
 *              //
 *              // The "user" is the related name. This is the name that is used
 *              // when User meta info is added to Group meta info. This allows
 *              // for searches like Group.filter({`user__in`}) to return all
 *              // groups with users in the provided list.
 *              addField("m2m_group", &User::myGroups, "user");
 *          }
 *      };
 *
 *      UT_ORMManyToManyField<User, Group> myGroups;
 *  };
 *
 *  int main()
 *  {
 *      UT_Array<Group> groups = user.all(ec);
 *      for (auto&& group : groups)
 *      {
 *          // ....
 *      }
 *  }
 */

#ifndef __UT_ORMMANYTOMANYFIELD_H__
#define __UT_ORMMANYTOMANYFIELD_H__

#include "UT_API.h"

#include "UT_Array.h"
#include "UT_Function.h"
#include "UT_ORMField.h"
#include "UT_ORMMigrationBuilder.h"
#include "UT_ORMModelMeta.h"
#include "UT_ORMOperation.h"
#include "UT_SQLORM.h"
#include "UT_UniquePtr.h"
#include "UT_ORMError.h"

class UT_API UT_ORMManyToManyManager
{
public:
    UT_ORMManyToManyManager() = default;
    UT_ORMManyToManyManager(const UT_ORMFieldColumn* field);

    explicit inline operator bool() const { return isValid(); }

    inline bool isValid() const
    {
        return myThrough != nullptr;
    }

    template <typename LObjT, typename RObjT>
    void add(LObjT& obj, const RObjT& new_list_obj, UT_ErrorCode& ec)
    {
        UT_Array<RObjT> objs;
        objs.emplace_back(new_list_obj);
        add(obj, objs, ec);
    }

    template <typename LObjT, typename RObjT>
    void add(LObjT& obj, const UT_Array<RObjT>& new_list_obj, UT_ErrorCode& ec)
    {
        if (isValid())
        {
            const UT_ORMFieldColumn* source_obj_field
                    = myThrough->findForeignRelatedField(mySourceFieldName);
            const UT_ORMFieldColumn* target_obj_field
                    = myThrough->findForeignRelatedField(myTargetFieldName);
            if (source_obj_field != nullptr && target_obj_field != nullptr)
            {
                const UT_ORMModelMeta& meta = obj.meta();
                if (UT_AutoSqlTransaction tran(
                            meta.db(), [ec]() { return !ec; },
                            /*savepoint=*/false);
                    tran)
                {
                    for (auto&& new_item : new_list_obj)
                    {
                        UT_ORMQuerySet qset(*myThrough);
                        UT_ORMQuerySetResult result = qset.create(
                                {UT::orm::FilterArg(
                                         mySourceFieldName, source_obj_field,
                                         &obj),
                                 UT::orm::FilterArg(
                                         myTargetFieldName, target_obj_field,
                                         &new_item)});
                        ec = result.getError();

                        if (ec)
                            break;
                    }
                }
                else
                {
                    ec = tran.entryFailure();
                }
            }
        }
        else
        {
            ec = UTmakeErrorCode(UT::SqlOrmError::UT_ORM_INVALID_M2M_MANAGER);
        }
    }

    template <typename LObjT, typename RObjT>
    void remove(LObjT& obj, const RObjT& obj_to_remove, UT_ErrorCode& ec)
    {
        if (isValid())
        {
            const UT_ORMFieldColumn* target_obj_field
                    = myThrough->findForeignRelatedField(myTargetFieldName);

            if (target_obj_field != nullptr)
            {
                using r_pk_obj_t = typename RObjT::Meta::primary_key_t;
                r_pk_obj_t value;
                target_obj_field->adapter()->getValue(obj_to_remove, value, ec);
                if (ec)
                {
                    return;
                }

                UT_Array<r_pk_obj_t> values;
                values.emplace_back(value);
                removeIds(obj, values, ec);
            }
        }
        else
        {
            ec = UTmakeErrorCode(UT::SqlOrmError::UT_ORM_INVALID_M2M_MANAGER);
        }
    }

    template <typename LObjT, typename RObjValueT>
    void removeIds(
            LObjT& obj,
            const UT_Array<RObjValueT>& values,
            UT_ErrorCode& ec)
    {
        if (isValid())
        {
            const UT_ORMFieldColumn* source_obj_field
                    = myThrough->findForeignRelatedField(mySourceFieldName);

            UT_StringHolder remove_in_str;
            remove_in_str.format("{}__in", myTargetFieldName);

            UT_ORMQuerySet qset(*myThrough);
            qset.filter({UT::orm::FilterArg(
                                 mySourceFieldName, source_obj_field, &obj),
                         UT::orm::FilterArg(remove_in_str, values)})
                    .remove();
        }
        else
        {
            ec = UTmakeErrorCode(UT::SqlOrmError::UT_ORM_INVALID_M2M_MANAGER);
        }
    }

    template <typename LObjT, typename RObjT>
    void set(
            LObjT& obj,
            const UT_Array<RObjT>& new_items,
            bool do_clear,
            UT_ErrorCode& ec)
    {
        if (isValid())
        {
            const UT_ORMModelMeta& meta = obj.meta();
            if (UT_AutoSqlTransaction tran(
                        meta.db(), [&ec]() { return !ec; },
                        /*savepoint=*/false);
                tran)
            {
                if (do_clear)
                {
                    clear(obj, ec);
                    if (ec)
                        return;
                    add(obj, new_items, ec);
                }
                else
                {
                    const UT_ORMFieldColumn* source_obj_field
                            = myThrough->findForeignRelatedField(
                                    mySourceFieldName);
                    const UT_ORMFieldColumn* target_obj_field
                            = myThrough->findForeignRelatedField(
                                    myTargetFieldName);
                    if (source_obj_field != nullptr && target_obj_field)
                    {
                        using r_pk_field_t =
                                typename RObjT::Meta::primary_key_t;
                        UT_ORMQuerySet old_qset(*myThrough);
                        UT_ORMQuerySetResult result
                                = old_qset
                                          .filter({UT::orm::FilterArg(
                                                  mySourceFieldName,
                                                  source_obj_field, &obj)})
                                          .values({myTargetFieldName})
                                          .get();

                        UT_Array<r_pk_field_t> old_ids;
                        if (result.getError())
                        {
                            ec = result.getError();
                            return;
                        }

                        for (auto&& value : result)
                        {
                            r_pk_field_t fk_v
                                    = value.stmt().get<r_pk_field_t>(0);
                            old_ids.emplace_back(fk_v);
                        }

                        UT_Array<RObjT> add_items;
                        for (auto&& new_item : new_items)
                        {
                            r_pk_field_t fk_v;
                            target_obj_field->adapter()->getValue(
                                    new_item, fk_v, ec);
                            if (ec)
                            {
                                return;
                            }

                            bool found = false;
                            for (exint i = old_ids.size(); i-- > 0;)
                            {
                                if (old_ids[i] == fk_v)
                                {
                                    found = true;
                                    old_ids.removeIndex(i);
                                    break;
                                }
                            }

                            if (!found)
                            {
                                add_items.emplace_back(new_item);
                            }
                        }

                        removeIds(obj, old_ids, ec);
                        add(obj, add_items, ec);
                    }
                }
            }
            else
            {
                ec = tran.entryFailure();
            }
        }
        else
        {
            ec = UTmakeErrorCode(UT::SqlOrmError::UT_ORM_INVALID_M2M_MANAGER);
        }
    }

    template <typename LObjT>
    void clear(LObjT& obj, UT_ErrorCode& ec)
    {
        if (isValid())
        {
            const UT_ORMFieldColumn* source_obj_field
                    = myThrough->findForeignRelatedField(mySourceFieldName);
            if (source_obj_field != nullptr)
            {
                UT_ORMQuerySet qset(*myThrough);
                UT_ORMQuerySetResult result
                        = qset.filter({UT::orm::FilterArg(
                                              mySourceFieldName,
                                              source_obj_field, &obj)})
                                  .remove();

                ec = result.getError();
            }
        }
        else
        {
            ec = UTmakeErrorCode(UT::SqlOrmError::UT_ORM_INVALID_M2M_MANAGER);
        }
    }

    template <typename LObjT, typename RObjT>
    UT_Array<RObjT> all(LObjT& obj, UT_ErrorCode& ec, const UT_ORMModelMeta& rmeta) const
    {
        UT_ORMQuerySet qset = all<LObjT, RObjT>(obj, rmeta);
        UT_ORMQuerySetResult result = qset.get();
        ec = result.getError();

        UT_Array<RObjT> items;
        if (ec)
            return items;

        for (auto&& value : result)
        {
            RObjT obj;
            if (value.load(obj, ec))
                items.emplace_back(obj);
            else
                return items;
        }
        return items;
    }

    template <typename LObjT, typename RObjT>
    UT_ORMQuerySet all(LObjT& obj, const UT_ORMModelMeta& rmeta) const
    {
        UT_ORMQuerySet qset(rmeta);
        if (isValid())
        {
            const UT_ORMFieldColumn* source_obj_field
                    = myThrough->findForeignRelatedField(mySourceFieldName);

            if (source_obj_field != nullptr)
            {
                UT_StringHolder filter_name;
                filter_name.format(
                        "{}__{}", myQueryFieldName, source_obj_field->name());
                UT_ORMQuerySet qset(rmeta);
                return qset.filter({UT::orm::FilterArg(
                        filter_name, source_obj_field, &obj)});
            }
            else
            {
                qset.error(UTmakeErrorCode(UT::SqlOrmError::UT_ORM_OPERATION_FAILED));
            }
        }
        else
        {
            qset.error(
                UTmakeErrorCode(UT::SqlOrmError::UT_ORM_INVALID_M2M_MANAGER));
        }
        return qset;
    }

    static UT_ORMManyToManyManager lookupM2MManager(
            const UT_ORMModelMeta& meta,
            const UT_ORMModelMeta& other_meta,
            const UT_StringHolder& field_name);

private:
    UT_SharedPtr<UT_ORMModelMeta> myThrough;
    UT_StringHolder myQueryFieldName;
    UT_StringHolder mySourceFieldName;
    UT_StringHolder myTargetFieldName;
};

template <typename Owner, typename OtherModel>
class UT_ORMManyToManyField
{
public:
    UT_ORMManyToManyField(
            Owner& owner,
            const UT_StringHolder& field_name = UT_StringHolder::theEmptyString,
            const UT_ORMModelMeta& rmeta = OtherModel::metaInfo())
        : myOwner(owner), myFieldName(field_name), myRightMeta(rmeta)
    {
    }

    void add(const OtherModel& rmodel, UT_ErrorCode& ec);
    UT_Array<OtherModel> all(UT_ErrorCode& ec) const;
    UT_ORMQuerySet all() const;
    void remove(const OtherModel& model, UT_ErrorCode& ec);
    void clear(UT_ErrorCode& ec);
    void addBulk(const UT_Array<OtherModel>& rmodels, UT_ErrorCode& ec);
    void set(
            const UT_Array<OtherModel>& rmodels,
            UT_ErrorCode& ec,
            bool do_clear = false);

    void setOwner(Owner& owner) { myOwner = owner; }

private:
    UT_ORMManyToManyManager& manager()
    {
        // Make sure we lazy load the manager. Theres no need to find the
        // manager if its never actually used.
        if (!myHasLookedForManager)
        {
            myHasLookedForManager = true;
            myManyManager = UT_ORMManyToManyManager::lookupM2MManager(
                    myOwner.get().meta(), myRightMeta, myFieldName);
        }
        return myManyManager;
    }
    const UT_ORMManyToManyManager& manager() const
    {
        return SYSconst_cast(this)->manager();
    }

    bool myHasLookedForManager = false;
    UT_ORMManyToManyManager myManyManager;
    UT_StringHolder myFieldName;
    std::reference_wrapper<Owner> myOwner;
    const UT_ORMModelMeta& myRightMeta;
};

template <typename Owner, typename Model>
void
UT_ORMManyToManyField<Owner, Model>::add(const Model& rmodel, UT_ErrorCode& ec)
{
    return manager().template add<Owner, Model>(myOwner, rmodel, ec);
}

template <typename Owner, typename Model>
void
UT_ORMManyToManyField<Owner, Model>::addBulk(
        const UT_Array<Model>& rmodels,
        UT_ErrorCode& ec)
{
    return manager().template add<Owner, Model>(myOwner, rmodels, ec);
}

template <typename Owner, typename Model>
UT_Array<Model>
UT_ORMManyToManyField<Owner, Model>::all(UT_ErrorCode& ec) const
{
    return manager().template all<Owner, Model>(myOwner, ec, myRightMeta);
}

template <typename Owner, typename Model>
UT_ORMQuerySet
UT_ORMManyToManyField<Owner, Model>::all() const
{
    return manager().template all<Owner, Model>(myOwner, myRightMeta);
}

template <typename Owner, typename Model>
void
UT_ORMManyToManyField<Owner, Model>::remove(
        const Model& model,
        UT_ErrorCode& ec)
{
    return manager().template remove<Owner, Model>(myOwner, model, ec);
}

template <typename Owner, typename Model>
void
UT_ORMManyToManyField<Owner, Model>::clear(UT_ErrorCode& ec)
{
    return manager().template clear<Owner>(myOwner, ec);
}

template <typename Owner, typename OtherModel>
void
UT_ORMManyToManyField<Owner, OtherModel>::set(
        const UT_Array<OtherModel>& items,
        UT_ErrorCode& ec,
        bool do_clear)
{
    return manager().template set<Owner, OtherModel>(
            myOwner, items, do_clear, ec);
}

#endif // __UT_ORMMANYTOMANYFIELD_H__