item.h

/*
    Copyright (c) 2006 Volker Krause <vkrause@kde.org>
                  2007 Till Adam <adam@kde.org>

    This library is free software; you can redistribute it and/or modify it
    under the terms of the GNU Library General Public License as published by
    the Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This library is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
    License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to the
    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301, USA.
*/

#ifndef AKONADI_ITEM_H
#define AKONADI_ITEM_H

#include "akonadi_export.h"

#include <akonadi/entity.h>
#include <akonadi/exception.h>
#include <akonadi/tag.h>
#include <akonadi/collection.h>
#include "itempayloadinternals_p.h"

#include <QtCore/QByteArray>
#include <QtCore/QMetaType>
#include <QtCore/QSet>

#include <boost/static_assert.hpp>
#include <boost/type_traits/is_pointer.hpp>
#include <boost/utility/enable_if.hpp>

#include <typeinfo>
#include <memory>

class KUrl;

template <typename T>
class QVector;

namespace Akonadi {

class ItemPrivate;

class AKONADI_EXPORT Item : public Entity
{
public:
    typedef QList<Item> List;

    typedef QByteArray Flag;

    typedef QSet<QByteArray> Flags;

    static const char *FullPayload;

    Item();

    explicit Item(Id id);

    explicit Item(const QString &mimeType);

    Item(const Item &other);

    ~Item();

    static Item fromUrl(const KUrl &url);

    Flags flags() const;

    QDateTime modificationTime() const;

    void setModificationTime(const QDateTime &datetime);

    bool hasFlag(const QByteArray &name) const;

    void setFlag(const QByteArray &name);

    void clearFlag(const QByteArray &name);

    void setFlags(const Flags &flags);

    void clearFlags();

    void setTags(const Tag::List &list);

    void setTag(const Tag &tag);

    Tag::List tags() const;

    bool hasTag(const Tag &tag) const;

    void clearTag(const Tag &tag);

    void clearTags();

    void setPayloadFromData(const QByteArray &data);

    QByteArray payloadData() const;

    QSet<QByteArray> loadedPayloadParts() const;

    void clearPayload();

    void setRevision(int revision);

    int revision() const;

    Entity::Id storageCollectionId() const;

    void setSize(qint64 size);

    qint64 size() const;

    void setMimeType(const QString &mimeType);

    QString mimeType() const;

    void setGid(const QString &gid);

    QString gid() const;

    void setVirtualReferences(const Collection::List &collections);

    Collection::List virtualReferences() const;

    QVector<int> availablePayloadMetaTypeIds() const;

    template <typename T> void setPayload(const T &p);
    //@cond PRIVATE
    template <typename T> void setPayload(T *p);
    template <typename T> void setPayload(std::auto_ptr<T> p);
    //@endcond

    template <typename T> T payload() const;

    bool hasPayload() const;

    template <typename T> bool hasPayload() const;

    enum UrlType {
        UrlShort = 0,         
        UrlWithMimeType = 1   
    };

    KUrl url(UrlType type = UrlShort) const;

    QSet<QByteArray> availablePayloadParts() const;

    QSet<QByteArray> cachedPayloadParts() const;

    void apply(const Item &other);

    template <typename T> static void addToLegacyMapping(const QString &mimeType);
    void setCachedPayloadParts(const QSet<QByteArray> &cachedParts);

private:
    //@cond PRIVATE
    friend class ItemCreateJob;
    friend class ItemModifyJob;
    friend class ItemModifyJobPrivate;
    friend class ItemSync;
    friend class ProtocolHelper;
    PayloadBase *payloadBase() const;
    void setPayloadBase(PayloadBase *p);
    PayloadBase *payloadBaseV2(int sharedPointerId, int metaTypeId) const;
    //std::auto_ptr<PayloadBase> takePayloadBase( int sharedPointerId, int metaTypeId );
    void setPayloadBaseV2(int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p);
    void addPayloadBaseVariant(int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p) const;
    static void addToLegacyMappingImpl(const QString &mimeType, int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p);

    bool ensureMetaTypeId(int mtid) const;

    template <typename T>
    typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic, void>::type
    setPayloadImpl(const T &p, const int * /*disambiguate*/ = 0);
    template <typename T>
    typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic, void>::type
    setPayloadImpl(const T &p);

    template <typename T>
    typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic, T>::type
    payloadImpl(const int * /*disambiguate*/ = 0) const;
    template <typename T>
    typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic, T>::type
    payloadImpl() const;

    template <typename T>
    typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic, bool>::type
    hasPayloadImpl(const int * /*disambiguate*/ = 0) const;
    template <typename T>
    typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic, bool>::type
    hasPayloadImpl() const;

    template <typename T>
    typename boost::enable_if<Internal::is_shared_pointer<T>, bool>::type
    tryToClone(T *ret, const int * /*disambiguate*/ = 0) const;
    template <typename T>
    typename boost::disable_if<Internal::is_shared_pointer<T>, bool>::type
    tryToClone(T *) const;

    void setStorageCollectionId(Entity::Id collectionId);

#if 0

    QString payloadExceptionText(int spid, int mtid) const;

    inline void throwPayloadException(int spid, int mtid) const {
        throw PayloadException(payloadExceptionText(spid, mtid));
    }
#else
    void throwPayloadException(int spid, int mtid) const;
#endif
    //@endcond

    AKONADI_DECLARE_PRIVATE(Item)
};

template <typename T>
T Item::payload() const
{
    BOOST_STATIC_ASSERT(!boost::is_pointer<T>::value);

    if (!hasPayload()) {
        throwPayloadException(-1, -1);
    }

    return payloadImpl<T>();
}

template <typename T>
typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic, T>::type
Item::payloadImpl(const int *) const
{
    typedef Internal::PayloadTrait<T> PayloadType;
    BOOST_STATIC_ASSERT((PayloadType::isPolymorphic));

    typedef typename Internal::get_hierarchy_root<T>::type Root_T;
    typedef Internal::PayloadTrait<Root_T> RootType;
    BOOST_STATIC_ASSERT((!RootType::isPolymorphic));   // prevent endless recursion

    return PayloadType::castFrom(payloadImpl<Root_T>());
}

template <typename T>
typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic, T>::type
Item::payloadImpl() const
{
    typedef Internal::PayloadTrait<T> PayloadType;
    BOOST_STATIC_ASSERT((!PayloadType::isPolymorphic));

    const int metaTypeId = PayloadType::elementMetaTypeId();

    // make sure that we have a payload format represented by 'metaTypeId':
    if (!ensureMetaTypeId(metaTypeId)) {
        throwPayloadException(PayloadType::sharedPointerId, metaTypeId);
    }

    // Check whether we have the exact payload
    // (metatype id and shared pointer type match)
    if (const Payload<T> *const p = Internal::payload_cast<T>(payloadBaseV2(PayloadType::sharedPointerId, metaTypeId))) {
        return p->payload;
    }

    T ret;
    if (!tryToClone<T>(&ret)) {
        throwPayloadException(PayloadType::sharedPointerId, metaTypeId);
    }
    return ret;
}

template <typename T>
typename boost::enable_if<Internal::is_shared_pointer<T>, bool>::type
Item::tryToClone(T *ret, const int *) const
{
    typedef Internal::PayloadTrait<T> PayloadType;
    BOOST_STATIC_ASSERT((!PayloadType::isPolymorphic));

    const int metaTypeId = PayloadType::elementMetaTypeId();

    // Check whether we have the same payload in 'the other
    // shared pointer' (### make it recurse, trying to find one, but
    // don't introduce infinite recursion):
    typedef typename Internal::shared_pointer_traits<T>::next_shared_ptr NewT;
    typedef Internal::PayloadTrait<NewT> NewPayloadType;

    if (const Payload<NewT> *const p = Internal::payload_cast<NewT>(payloadBaseV2(NewPayloadType::sharedPointerId, metaTypeId))) {
        // If found, attempt to make a clone (required the payload to provide virtual T * T::clone() const)
        const T nt = PayloadType::clone(p->payload);
        if (!PayloadType::isNull(nt)) {
            // if clone succeeded, add the clone to the Item:
            std::auto_ptr<PayloadBase> npb(new Payload<T>(nt));
            addPayloadBaseVariant(PayloadType::sharedPointerId, metaTypeId, npb);
            // and return it
            if (ret) {
                *ret = nt;
            }
            return true;
        }
    }

    return false;
}

template <typename T>
typename boost::disable_if<Internal::is_shared_pointer<T>, bool>::type
Item::tryToClone(T *) const
{
    typedef Internal::PayloadTrait<T> PayloadType;
    BOOST_STATIC_ASSERT((!PayloadType::isPolymorphic));

    return false;
}

template <typename T>
bool Item::hasPayload() const
{
    BOOST_STATIC_ASSERT(!boost::is_pointer<T>::value);
    return hasPayload() && hasPayloadImpl<T>();
}

template <typename T>
typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic, bool>::type
Item::hasPayloadImpl(const int *) const
{
    typedef Internal::PayloadTrait<T> PayloadType;
    BOOST_STATIC_ASSERT((PayloadType::isPolymorphic));

    typedef typename Internal::get_hierarchy_root<T>::type Root_T;
    typedef Internal::PayloadTrait<Root_T> RootType;
    BOOST_STATIC_ASSERT((!RootType::isPolymorphic));   // prevent endless recursion

    try {
        return hasPayloadImpl<Root_T>()
               && PayloadType::canCastFrom(payload<Root_T>());
    } catch (const Akonadi::PayloadException &) {
        return false;
    }
}

template <typename T>
typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic, bool>::type
Item::hasPayloadImpl() const
{
    typedef Internal::PayloadTrait<T> PayloadType;
    BOOST_STATIC_ASSERT((!PayloadType::isPolymorphic));

    const int metaTypeId = PayloadType::elementMetaTypeId();

    // make sure that we have a payload format represented by 'metaTypeId':
    if (!ensureMetaTypeId(metaTypeId)) {
        return false;
    }

    // Check whether we have the exact payload
    // (metatype id and shared pointer type match)
    if (const Payload<T> *const p = Internal::payload_cast<T>(payloadBaseV2(PayloadType::sharedPointerId, metaTypeId))) {
        return true;
    }

    return tryToClone<T>(0);
}

template <typename T>
void Item::setPayload(const T &p)
{
    BOOST_STATIC_ASSERT((!boost::is_pointer<T>::value));
    setPayloadImpl(p);
}

template <typename T>
typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
Item::setPayloadImpl(const T &p, const int *)
{
    typedef Internal::PayloadTrait<T> PayloadType;
    BOOST_STATIC_ASSERT((PayloadType::isPolymorphic));

    typedef typename Internal::get_hierarchy_root<T>::type Root_T;
    typedef Internal::PayloadTrait<Root_T> RootType;
    BOOST_STATIC_ASSERT((!RootType::isPolymorphic));   // prevent endless recursion

    setPayloadImpl<Root_T>(p);
}

template <typename T>
typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
Item::setPayloadImpl(const T &p)
{
    typedef Internal::PayloadTrait<T> PayloadType;
    std::auto_ptr<PayloadBase> pb(new Payload<T>(p));
    setPayloadBaseV2(PayloadType::sharedPointerId,
                     PayloadType::elementMetaTypeId(),
                     pb);
}

template <typename T>
void Item::setPayload(T *p)
{
    p->You_MUST_NOT_use_a_pointer_as_payload;
}

template <typename T>
void Item::setPayload(std::auto_ptr<T> p)
{
    p.Nice_try_but_a_std_auto_ptr_is_not_allowed_as_payload_either;
}

template <typename T>
void Item::addToLegacyMapping(const QString &mimeType) {
    typedef Internal::PayloadTrait<T> PayloadType;
    BOOST_STATIC_ASSERT((!PayloadType::isPolymorphic));
    std::auto_ptr<PayloadBase> p(new Payload<T>);
    addToLegacyMappingImpl(mimeType, PayloadType::sharedPointerId, PayloadType::elementMetaTypeId(), p);
}

}

Q_DECLARE_METATYPE(Akonadi::Item)
Q_DECLARE_METATYPE(Akonadi::Item::List)

#endif