/* This file is part of the KDE project
   Copyright (C) 2010 KO GmbH <ben.martin@kogmbh.com>

   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 KO_DOCUMENT_Rdf_H
#define KO_DOCUMENT_Rdf_H

#include "kordf_export.h"
#include "RdfForward.h"
#include "KoSemanticStylesheet.h"
#include "KoRdfSemanticItem.h"
#include "KoRdfSemanticItemViewSite.h"
#include "RdfSemanticTreeWidgetAction.h"
#include "KoRdfSemanticTree.h"
// Calligra
#include <KoDocumentRdfBase.h>
#include <KoXmlReaderForward.h>
#include <KoDataCenterBase.h>
// Soprano
#include <Soprano/Soprano>
// Qt
#include <QObject>
#include <QMap>
#include <QString>
#include <QStringList>
#include <QTextBlockUserData>
#include <QTreeWidgetItem>

class QDomDocument;

class KoStore;
class KoXmlWriter;
class KoDocument;
class KoCanvasBase;
class KoTextEditor;

class KoDocumentRdfPrivate;

class QAction;

/**
 * @short The central access point for the Rdf metadata of an ODF document.
 *
 * @author Ben Martin <ben.martin@kogmbh.com>
 * @see KoDocument
 * @see KoDocumentInfo
 *
 * The KoDocumentRdf object is possibly associated with a KoDocument.
 * There does not need to be a KoDocumentRdf for each KoDocument, but
 * if one exists it is a one-to-one relationship. The KoDocumentRdf
 * is also associated with the KoDocumentResourceManager of a canvas.
 *
 * Once again, the canvas to KoDocumentRdf is either a 1-1 or 1 to
 * zero relationship.
 *
 * ACCESS TO Rdf:
 *
 * You can get at the Rdf information in two main ways: either using
 * Soprano/SPARQL or through KoRdfSemanticItem objects.
 *
 * Subclasses of KoRdfSemanticItem exist for locations (foaf,vcard),
 * events (ical), and locations (two Rdf geolocation formats). To get
 * a list of these objects use the foaf(), calendarEvents(), and
 * locations() methods of this class. Each of these methods optionally
 * takes a Soprano::Model and returns a list of SemanticItems of a
 * particular subclass. If you do not pass an Soprano::Model to the
 * methods the default model() of the KoDocumentRdf is used. By
 * allowing you to pass a model explicitly, you can find contacts that
 * exist in a subset of the full Rdf graph for a document. This is
 * useful if you want to find the contacts in the users current
 * "selection" in the document.
 *
 * For example, to find the foaf entries related to the current KoTextEditor
 *
 * Soprano::Model* model = rdf->findStatements( editor );
 * QList<hKoRdfSemanticItem> foaflist = rdf->semanticItems( "Contact", model );
 *
 * Using the Soprano::Model directly is covered in a latter section of
 * this comment.
 *
 * STORAGE OF Rdf:
 *
 * Broadly there are two ways Rdf metadata is stored in an ODF
 * document.
 *
 * 1) inline in the content.xml file in an Rdfa style, though not
 *    using the full Rdfa spec
 *
 * 2) externally in manifest.rdf or other Rdf/XML files linked to by
 * manifest.rdf
 *
 * The Rdf that is stored using these methods is collected and made
 * available by the KoDocumentRdf class. The inline Rdf using option
 * (1) is stored along with the Calligra C++ objects that are created
 * during document loading. This class also knows how to find the
 * scattered Rdf that option (1) loads. Leaving the Rdf from option
 * (1) scattered in the document allows it to be preserved in the
 * normal course of document editing such as copy and paste, undo and
 * redo operations.
 *
 * The scattered Rdf from option (1) is stored using the
 * KoTextInlineRdf class. You can convert a KoTextInlineRdf to
 * a Soprano::Statement with the toStatement() method of this class.
 *
 * LOW LEVEL Rdf ACCESS:
 *
 * The model() method will give you a Soprano::model with all the Rdf
 * for the document, be them from option (1) or (2) above.
 *
 * The findStatements() methods will give you a Soprano::model
 * containing the statements relevant to a cursor or xml:id in the
 * document. The xml:id is the same identifier that is used in the
 * content.xml file that was loaded.
 *
 * Note that the findStatements() returns a submodel containing only
 * the statements relevant to the xml:id or cursor position you
 * selected. This will be a subset of all the Rdf for the document.
 * The various expand() methods can be used to add more Rdf statements
 * from the document to the submodel returned by findStatements(). For
 * example, the expandStatementsReferencingSubject() method will
 * expand the soprano::model to add Rdf statements which refer to any
 * subject in the Rdf submodel you pass in.
 */
class KORDF_EXPORT KoDocumentRdf : public KoDocumentRdfBase
{
    Q_OBJECT
public:
    /**
     * For Rdf stored in manifest.rdf or another rdf file referenced
     * by the manifest, this prefix is used as the start of the graph
     * context. The filename.rdf is appended so that the Rdf can be
     * put back into the right file again during save.
     */
    const static QString RDF_PATH_CONTEXT_PREFIX;

    /**
     * The constructor
     * @param parent a pointer to the parent object
     */
    explicit KoDocumentRdf(QObject *parent = 0);

    /** The destructor */
    ~KoDocumentRdf();

    /**
     * Load from an OASIS document
     * @param store the store with the metaInformation
     * @return true if success
     */
    bool loadOasis(KoStore *store);

    /**
     * Save to an OASIS document
     * @param store a pointer to a KoStore to save in
     * @param manifestWriter the document writer
     * @return true if success
     */
    bool saveOasis(KoStore *store, KoXmlWriter *manifestWriter);

    /**
     * Used by KoRdfSemanticItem when creating new semantic items so that the
     * KoDocumentRdf class can find them.
     */
    void rememberNewInlineRdfObject(KoTextInlineRdf *inlineRdf);

    /**
     * Find all the KoTextInlineRdf objects that exist in the
     * document and update the statements in the Soprano::(model) to
     * reflect the current state of the inline Rdf.
     */
    void updateInlineRdfStatements(const QTextDocument *qdoc);

    /**
     * During a save(), various Rdf objects in the document will
     * create new xmlid values which are used in the saved document.
     * As part of the save state a QMap from the old xmlid to the new
     * xmlid is built up. This method is then used to update the Rdf
     * triples to use the new xmlid values before that Rdf itself is
     * saved. This way the Rdf -> xmlid references will remain valid
     * in the saved ODF file.
     *
     * Since the Rdf is updated to use the new xmlid values, this method
     * also updates the C++ objects to use the new xmlid values so that
     * the instance of the document in memory is correctly linked.
     *
     * This way, Calligra is free to change the xml:id during save() and
     * the Rdf is still linked correctly.
     */
    void updateXmlIdReferences(const QMap<QString, QString> &m);

    /**
     * Get the namespace to URI prefix mapping object.
     */
    KoRdfPrefixMapping* prefixMapping() const;

    /**
     * Get the Soprano::Model that contains all the Rdf
     * You do not own the model, do not delete it.
     */
    virtual QSharedPointer<Soprano::Model> model() const;

    /**
     * Convert an inlineRdf object into a Soprano::Statement
     */
    Soprano::Statement toStatement(KoTextInlineRdf *inlineRdf) const;

    /**
     * Look for the semitem with the given xmlid and return the
     * start and end position for that semitem. If there is no semitem
     * with the \p xmlId then 0,0 is returned.
     */
    QPair<int, int> findExtent(const QString &xmlId) const;

    /**
     * Look for the semitem that is at or surrounding the cursor given. Note that if there
     * are nested semitems, the extend for the most nested semitem is returned.
     * for example, in the below scenario the return value will be QPair< start-b, end-b >.
     *
     * <start-a> ... <start-b> ... cursor ... <end-b> ... <end-a>
     */
    QPair<int, int> findExtent(KoTextEditor *handler) const;

    /**
     * find the xmlid of the semitem that is at or surrounding the cursor given. As with
     * findExtent() this will be only the most nested semitem.
     * @see findExtent()
     */
    QString findXmlId(KoTextEditor *cursor) const;


    /**
     * Find all of the statements which are
     * in context for a given cursor position.
     *
     * Rdf is also added to the returned model from external manifest.rdf
     * and other files which attach to the xml:id
     *
     * The depth parameter allows triple expansion, ie,
     *        depth=1   adds only triples which reference ?s ?p xml:id
     *        depth=2   adds references to statements in depth=1,
     *                  ie, ?s1 ?p2 ?s2 and ?s2 ?p xml:id
     * Because of the complexity, depth should be <=2 or you should use
     * a custom query.
     *
     * FIXME: The logical thing here would be to chain up.
     *   given a cursor in a table:cell, the Rdf for the containing
     *   text:p and text:meta elements should be returned too.
     *
     * Note that the returned model is owned by the caller, you must delete it.
     */
    QSharedPointer<Soprano::Model> findStatements(const QString &xmlid, int depth = 1);
    QSharedPointer<Soprano::Model> findStatements(KoTextEditor *handler, int depth = 1);

    /**
     * Add all the Rdf that is associated with the given xml:id
     */
    void addStatements(QSharedPointer<Soprano::Model> model, const QString &xmlid);

    /**
     * Find an inline Rdf object from the xml:id which
     * it has in the content.xml file
     */
    KoTextInlineRdf* findInlineRdfByID(const QString &xmlid) const;

    /**
     * Obtain a list of semantic objects of the given class, if any, for the Rdf
     * in the default model() or the one you optionally pass in.
     */
    QList< hKoRdfBasicSemanticItem > semanticItems(const QString &className, QSharedPointer< Soprano::Model > m = QSharedPointer<Soprano::Model>(0));

    /**
     * Create a SemanticItem subclass using its name from
     * classNames(). Useful for menus and other places that want to
     * allow the user to create new SemanticItem Objects.
     */
    hKoRdfBasicSemanticItem createSemanticItem(const QString &semanticClass, QObject *parent = 0) const;

    /**
     * This is used for triples that do not specify their xhtml:about
     * ie, the subject URI.
     */
    QString rdfInternalMetadataWithoutSubjectURI() const;

    /**
     * Soprano::Node that can be used as the model context for
     * statements which should be stored in the manifest.rdf file.
     */
    Soprano::Node manifestRdfNode() const;

    /**
     * Soprano::Node that can be used as the model context for
     * statements which were stored in the context.xml file.
     */
    Soprano::Node inlineRdfContext() const;

    /**
     * If model contains ?s ?p ?o
     * look for and add
     * ?s2 ?p2 ?s
     */
    void expandStatementsReferencingSubject(QSharedPointer<Soprano::Model> model) const;

    /**
     * If model contains ?s ?p ?o
     * look for and add
     * ?o ?p2 ?o2
     */
    void expandStatementsSubjectPointsTo(QSharedPointer<Soprano::Model> model) const;

    /**
     * Add n ?p ?o from m_model to model
     */
    void expandStatementsSubjectPointsTo(QSharedPointer<Soprano::Model> model, const Soprano::Node &n) const;

    /**
     * Rdf allows for linked lists to be serialized as a graph. This method will
     * ensure that all data from m_model for any lists that are started in 'model'
     * is copied into 'model'.
     *
     * Lists have the format
     * prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
     * ?id    rdf:first  ?value
     * ?id    rdf:rest   ?next1
     * ?next1 rdf:first  ?value2
     * ?next1 rdf:rest   ?nextN
     * ?nextN rdf:first  ?valueN
     * ?nextN rdf:rest   rdf:nil
     */
    void expandStatementsToIncludeRdfLists(QSharedPointer<Soprano::Model> model) const;

    /**
     * If model contains ?s ?p ?o
     * look for and add
     * ?s ?p3 ?o3
     */
    void expandStatementsToIncludeOtherPredicates(QSharedPointer<Soprano::Model> model) const;

    /**
     * One round of all expandStatements methods
     */
    void expandStatements(QSharedPointer<Soprano::Model> model) const;

    /**
     * FIXME? What does this do?
     */
    QAction * createInsertSemanticObjectReferenceAction(KoCanvasBase *host);

    /**
     * FIXME? What does this do?
     */
    QList<QAction *> createInsertSemanticObjectNewActions(KoCanvasBase *host);

    /**
     * Collect together the semantic item, stylehseet, xmlid of the
     * site to apply it at and the extent in the document (start,end)
     * of the semantic item. Used when applying stylesheets in bulk so
     * that all the sites can be collected and the QMap<int,reflowItem> map
     * will sort them in the order of start to end document position.
     *
     * @see insertReflow()
     * @see applyReflow()
     */
    struct reflowItem
    {
        hKoRdfSemanticItem m_si;
        hKoSemanticStylesheet m_ss;
        QString m_xmlid;
        QPair<int, int> m_extent;

        reflowItem(hKoRdfSemanticItem si, const QString &xmlid, hKoSemanticStylesheet ss, const QPair<int, int> &extent);
    };

    /**
     * Because applying a stylesheet to a semantic item could change
     * the length of the text showing the item in the document, it is
     * best to apply these stylesheets to semitems starting from the
     * end of the document. This is because any change in the length
     * of a semitem has no effect on all the other semitems that are
     * before it in the document. After we have applied all the
     * changes, the kwdoc will update the positions of all the
     * kotextmeta etc objects and they will once again be correct.
     * Doing things explicitly backwards is a huge efficiency gain
     * because no layout is needed on the document during our updates
     * because each update does not invalidate the positions of any
     * objects before the update in the document text.
     *
     * Call insertReflow() for all the items you want to apply a
     * stylesheet on and then applyReflow() with the built up
     * collection 'col' argument to will actually apply the
     * stylesheets starting from the semitem lowest in the document
     * and working backwards.
     *
     * @see applyReflow()
     */
    void insertReflow(QMap<int, reflowItem> &col, hKoRdfSemanticItem obj, hKoSemanticStylesheet ss);
    void insertReflow(QMap<int, reflowItem> &col, hKoRdfSemanticItem obj, const QString &sheetType, const QString &stylesheetName);
    void insertReflow(QMap<int, reflowItem> &col, hKoRdfSemanticItem obj);
    /**
     * @short Apply the stylesheets built up with insertReflow().
     *
     * @see insertReflow()
     */
    void applyReflow(const QMap<int, reflowItem> &col);

    //FIXME: this method also seems to be STATIC and why it has such second default param??
    /**
     * For debugging, output the model and a header string for identification
     */
    void dumpModel(const QString &msg, QSharedPointer<Soprano::Model> m = QSharedPointer<Soprano::Model>(0)) const;

Q_SIGNALS:
    /**
     * Emitted when a new semanticItem is created so that dockers can
     * update themselves accordingly. It is expected that when
     * semanticObjectViewSiteUpdated is emitted the view will take care
     * of reflowing the semantic item using it's stylesheet.
     */
    void semanticObjectAdded(hKoRdfBasicSemanticItem item) const;
    void semanticObjectUpdated(hKoRdfBasicSemanticItem item) const;
    void semanticObjectViewSiteUpdated(hKoRdfBasicSemanticItem item, const QString &xmlid) const;

public:
    void emitSemanticObjectAdded(hKoRdfBasicSemanticItem item) const;
    void emitSemanticObjectUpdated(hKoRdfBasicSemanticItem item);
    void emitSemanticObjectViewSiteUpdated(hKoRdfBasicSemanticItem item, const QString &xmlid);
    void emitSemanticObjectAddedConst(hKoRdfBasicSemanticItem const item) const;

    /**
     * You should use the KoRdfSemanticItem::userStylesheets() method instead of this one.
     * This is mainly an internal method to allow user stylesheets to be managed per document.
     */
    QList<hKoSemanticStylesheet> userStyleSheetList(const QString& className) const;
    void setUserStyleSheetList(const QString& className,const QList<hKoSemanticStylesheet>& l);


private:

    /**
     * @see expandStatementsToIncludeRdfLists()
     */
    void expandStatementsToIncludeRdfListsRecurse(QSharedPointer<Soprano::Model> model,
            QList<Soprano::Statement> &addList,
            const Soprano::Node &n) const;


    /**
     * Soprano can give undesirable behaviour when loading two files
     * into the same model. When parsing the second Rdf file, the sane
     * genid1 numbers can be reused, leading to semantic errors on
     * bnodes. This method updates all the bnodes in 'm' to be new
     * ones created using m_model->createBlankNode(). bnode identity
     * is preserved for the model m. ie. genid2 and another genid2 in
     * m will be replaced with the same m_model->createBlankNode()
     * value. After calling this method, you can add all the
     * statements to 'm' and be assured that no bnodes in 'm' are
     * going to accidentially be the same as a bnode in m_model.
     */
    void freshenBNodes(QSharedPointer<Soprano::Model> m);

    /**
     * Used by loadOasis() to load Rdf from a particular external
     * Rdf/XML file.
     */
    bool loadRdf(KoStore *store, const Soprano::Parser *parser, const QString &fileName);

    /**
     * Used by saveOasis() to save Rdf to a the Rdf file nominated
     * with context. Note that this method can not be used to save to
     * content.xml, those Rdf statements must be saved as the
     * content.xml file is generated.
     */
    bool saveRdf(KoStore *store, KoXmlWriter *manifestWriter, const Soprano::Node &context) const;


    /**
     * idrefList queries soprano after loading and creates a list of all rdfid's that
     * where found in the manifest.rdf document. This list is used to make sure we do not
     * create more inline rdf objects than necessary
     * @return a list of xml-id's
     */
    QStringList idrefList() const;

private:

    /**
     * Test whether a model is present that supports:
     * - context / graphs
     *  - querying on graphs
     *  - storage in memory.
     */
    bool backendIsSane();

    /// reimplemented
    virtual bool completeLoading(KoStore *store);

    /// reimplemented
    virtual bool completeSaving(KoStore *store, KoXmlWriter *manifestWriter, KoShapeSavingContext *context);

    KoDocumentRdfPrivate * const d;
};

#endif