Projects/Nepomuk/Resources: Difference between revisions

    From KDE TechBase
    No edit summary
    (Adding some clarification to when an item is stored)
    (6 intermediate revisions by 3 users not shown)
    Line 1: Line 1:
    The Nepomuk Resource class provides a convenient wrapper over the Nepomuk data. It does so by keeping a cache of the relevant data and using the Resource Watcher to keep it up to date.
    <languages />
    <translate>
    == Introduction == <!--T:1-->


    = Saving Resources =
    <!--T:2-->
    Resources are a real-time view of the data in the virtuoso database. They are automatically saved after each change, and all other resources across the different applications are updated.
    The ''Nepomuk Resource'' class provides a convenient wrapper over the '''Nepomuk''' data. It does so by keeping a cache of the relevant data and using the ''Resource Watcher'' to keep it up to date.


    === Saving New Resources ===
    == Saving Resources == <!--T:3-->
     
    <!--T:4-->
    Resources are a real-time view of the data in the '''virtuoso''' database. They are automatically saved after each change, and all other resources across the different applications are updated.
     
    === Saving New Resources === <!--T:5-->
     
    <!--T:6-->
    A new resource will automatically be saved the first time it is used.
    A new resource will automatically be saved the first time it is used.


    <!--T:7-->
    <syntaxhighlight lang="cpp-qt">
    <syntaxhighlight lang="cpp-qt">
         Nepomuk2::Resource res;
         Nepomuk2::Resource res;
    Line 12: Line 22:
         res.uri(); // Will be blank
         res.uri(); // Will be blank


         res.setRating( 5 ); // Will be created and saved
         <!--T:8-->
    res.setRating( 5 ); // Will be created and saved
         res.exists(); // Will return true
         res.exists(); // Will return true
         res.uri(); // Will return its unique identifier
         res.uri(); // Will return its unique identifier
    </syntaxhighlight>
    </syntaxhighlight>


    = Managing Properties =
    The following examples show the behavior of storing resources in different cases. It uses the  HistoryItem ontology used in KGet as an example of a typed resource.
     
    <syntaxhighlight lang="cpp-qt">
      /**
      * This resource won't be saved to the database because
      * there is no property assigned to it
      */
      Nepomuk2::Resource notSaved("file:///tmp/notsaved.txt");
     
      /**
      * This resource will be saved to the database because we
      * set a property to it
      */
      Nepomuk2::Resource saved("file:///tmp/saved.txt");
     
      saved.addProperty(Nepomuk2::Vocabulary::NIE::comment(), Nepomuk2::Variant("This will be saved"));
     
      /**
      * This is saved to a resource with the Nepomuk2::HistoryItem type
      * because we set a property of it
      */
      Nepomuk2::HistoryItem typedResource("file:///tmp/typedResource.txt");
     
      typedResource.setSize(50);
    </syntaxhighlight>
     
    == Managing Properties == <!--T:9-->


    = Nepomuk Resource Generator =
    <!--T:10-->
    When using the [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html <tt>Resource</tt>] class, one can easily access certain properties such as ratings and tags via convenience functions. However, if one wishes to access more properties then that is performed via the [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html#a9a59f482f21c6150bc9cb39dd47a7d77 <tt>property</tt>], [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html#a8ffb9cb55cb641e022479e80b9fc0dcf <tt>setProperty</tt>] and [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html#a7dcb083459a2e967a4ddfbf5f6fbcf9e <tt>addProperty</tt>] functions.


    While it is fairly convenient to use the <code>setProperty</code> and <code>getProperty</code> methods. It requires you to explicitly define the property which you need modify. This can get quite cumbersome and destroys readability of the code.
    <!--T:11-->
    It's important to know which properties are available in each resource. The simplest way would be to check they keys in [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html#ac26aeaa49c264ce6e3778e028aa4dc85 <tt>properties</tt>].


    === Accessing the Vocabularies === <!--T:12-->
    <!--T:13-->
    In order to modify any of the properties in '''Nepomuk''', one must access the ontologies. The recommended way of doing that is by using the pre-generated ontologies headers which are shipped with '''Soprano''' and '''NepomukCore'''.
    <!--T:14-->
    <syntaxhighlight lang="cpp-qt">
    #include <Soprano/Vocabulary/RDF>
    #include <Soprano/Vocabulary/RDFS>
    #include <Soprano/Vocabulary/NRL>
    #include <Soprano/Vocabulary/NAO>
    <!--T:15-->
    #include <Nepomuk2/Vocabulary/NIE>
    #include <Nepomuk2/Vocabulary/NFO>
    #include <Nepomuk2/Vocabulary/NMM>
    #include <Nepomuk2/Vocabulary/NCO>
    #include <Nepomuk2/Vocabulary/PIMO>
    #include <Nepomuk2/Vocabulary/NCAL>
    <!--T:16-->
    using namespace Neppomuk2::Vocabulary;
    using namespace Soprano::Vocabulary;
    </syntaxhighlight>
    === Setting Properties === <!--T:17-->
    <!--T:18-->
    When setting a property of a resource. It is imperative that the domain, range and cardinality of the property be correct. Otherwise the <tt>setProperty</tt> call will silently fail and output an error as a debug message. In future releases we will provide other ways to get notified of the errors.
    <!--T:19-->
    Example -
    <syntaxhighlight lang="cpp-qt">
        Nepomuk2::Resource res;
        res.addType( NCO::Contact() );
        <!--T:20-->
    res.setProperty( NFO::fileName(), "Fire" ); // Will silently fail
        res.property( NFO::fileName() ).toString(); // Will be empty
        <!--T:21-->
    res.addProperty( NCO::fullname(), QLatin1String("Tom Marvolo Riddle") ); // Will work
        res.addProperty( NCO::fullname(), QLatin1String("Lord Voldemort") ); // Will fail - nco:fullname has a max cardinality of 1
        <!--T:22-->
    QString origName = res.property( NCO::fullname() ).toString(); // will return "Tom Marvolo Riddle"
        res.setProperty( NCO::fullname(), QLatin1String("Lord Voldemort") ); // will work this time - we're using setProperty
        <!--T:23-->
    QString newName = res.property( NCO::fullname() ).toString(); // Will return You-know-who
    </syntaxhighlight>
    == Nepomuk Resource Generator == <!--T:24-->
    <!--T:25-->
    While it is fairly convenient to use the <tt>setProperty</tt> and <tt>getProperty</tt> methods. It requires you to explicitly define the property which you need modify. This can get quite cumbersome and destroys readability of the code.
    <!--T:26-->
    In order to improve this situation we have provided a resource generator, which generates custom <code>Resource</code> classes from the ontologies. It relies on a CMake macro to accomplish that.
    In order to improve this situation we have provided a resource generator, which generates custom <code>Resource</code> classes from the ontologies. It relies on a CMake macro to accomplish that.


    ===Usage in CMake===
    ===Usage in CMake=== <!--T:27-->


    The resource generator is best used through the CMake macro provided by Nepomuk. The syntax is fairly simple and similar to the macro for adding ui files to a list of sources:
    <!--T:28-->
    The resource generator is best used through the CMake macro provided by '''Nepomuk'''. The syntax is fairly simple and similar to the macro for adding ui files to a list of sources:


    <!--T:29-->
    <syntaxhighlight lang="text">
    <syntaxhighlight lang="text">
    NEPOMUK2_ADD_ONTOLOGY_CLASSES(<sources-var>
    NEPOMUK2_ADD_ONTOLOGY_CLASSES(<sources-var>
    Line 38: Line 137:




    <!--T:30-->
    The optional CLASSES parameter allows to specify the classes to be generated (RDF class names) in case one does not want all classes in the ontologies to be generated. If omitted all classes in the ontology files will be generated.
    The optional CLASSES parameter allows to specify the classes to be generated (RDF class names) in case one does not want all classes in the ontologies to be generated. If omitted all classes in the ontology files will be generated.


    <!--T:31-->
    The optional VISIBILITY parameter can only be used in non-fast mode and allows to set the gcc visibility to make the generated classes usable in a publically exported API. The <visibility-name> is used to create the name of the export macro and the export include file. Thus, when using "VISIBILITY foobar" include
    The optional VISIBILITY parameter can only be used in non-fast mode and allows to set the gcc visibility to make the generated classes usable in a publically exported API. The <visibility-name> is used to create the name of the export macro and the export include file. Thus, when using "VISIBILITY foobar" include
    file "foobar_export.h" needs to define FOOBAR_EXPORT.
    file "foobar_export.h" needs to define FOOBAR_EXPORT.


    ==== Example ====
    ==== Example ==== <!--T:32-->
     
    <!--T:33-->
    <syntaxhighlight lang="cmake">
    <syntaxhighlight lang="cmake">
    include(Nepomuk2AddOntologyClasses)
    include(Nepomuk2AddOntologyClasses)


    <!--T:34-->
    nepomuk2_add_ontology_classes (SRCS
    nepomuk2_add_ontology_classes (SRCS
         ONTOLOGIES
         ONTOLOGIES
    Line 56: Line 160:




    <!--T:35-->
    This will generate a C++ class for each type defined in the mentioned ontologies.  
    This will generate a C++ class for each type defined in the mentioned ontologies.  
    <syntaxhighlight lang="cpp-qt">
    <syntaxhighlight lang="cpp-qt">
    #include "personcontact.h"
    #include "personcontact.h"


    <!--T:36-->
    Nepomuk2::PersonContact spiderman;
    Nepomuk2::PersonContact spiderman;
    spiderman.setFullName( QLatin1String("Peter Parker") );
    spiderman.setFullName( QLatin1String("Peter Parker") );
    QString name = spiderman.fullname();
    QString name = spiderman.fullname();
    </syntaxhighlight>
    </syntaxhighlight>
    <!--T:37-->
    [[Category:Documentation]]
    [[Category:Development]]
    [[Category:Tutorials]]
    </translate>

    Revision as of 22:25, 16 July 2013

    Introduction

    The Nepomuk Resource class provides a convenient wrapper over the Nepomuk data. It does so by keeping a cache of the relevant data and using the Resource Watcher to keep it up to date.

    Saving Resources

    Resources are a real-time view of the data in the virtuoso database. They are automatically saved after each change, and all other resources across the different applications are updated.

    Saving New Resources

    A new resource will automatically be saved the first time it is used.

        Nepomuk2::Resource res;
        res.exists(); // Will return false
        res.uri(); // Will be blank
    
        res.setRating( 5 ); // Will be created and saved
        res.exists(); // Will return true
        res.uri(); // Will return its unique identifier
    

    The following examples show the behavior of storing resources in different cases. It uses the HistoryItem ontology used in KGet as an example of a typed resource.

      /**
       * This resource won't be saved to the database because
       * there is no property assigned to it
       */
      Nepomuk2::Resource notSaved("file:///tmp/notsaved.txt");
      
      /**
       * This resource will be saved to the database because we
       * set a property to it
       */
      Nepomuk2::Resource saved("file:///tmp/saved.txt");
      
      saved.addProperty(Nepomuk2::Vocabulary::NIE::comment(), Nepomuk2::Variant("This will be saved"));
      
      /**
       * This is saved to a resource with the Nepomuk2::HistoryItem type
       * because we set a property of it
       */
      Nepomuk2::HistoryItem typedResource("file:///tmp/typedResource.txt");
    
      typedResource.setSize(50);
    

    Managing Properties

    When using the Resource class, one can easily access certain properties such as ratings and tags via convenience functions. However, if one wishes to access more properties then that is performed via the property, setProperty and addProperty functions.

    It's important to know which properties are available in each resource. The simplest way would be to check they keys in properties.

    Accessing the Vocabularies

    In order to modify any of the properties in Nepomuk, one must access the ontologies. The recommended way of doing that is by using the pre-generated ontologies headers which are shipped with Soprano and NepomukCore.

    #include <Soprano/Vocabulary/RDF>
    #include <Soprano/Vocabulary/RDFS>
    #include <Soprano/Vocabulary/NRL>
    #include <Soprano/Vocabulary/NAO>
    
    #include <Nepomuk2/Vocabulary/NIE>
    #include <Nepomuk2/Vocabulary/NFO>
    #include <Nepomuk2/Vocabulary/NMM>
    #include <Nepomuk2/Vocabulary/NCO>
    #include <Nepomuk2/Vocabulary/PIMO>
    #include <Nepomuk2/Vocabulary/NCAL>
    
    using namespace Neppomuk2::Vocabulary;
    using namespace Soprano::Vocabulary;
    

    Setting Properties

    When setting a property of a resource. It is imperative that the domain, range and cardinality of the property be correct. Otherwise the setProperty call will silently fail and output an error as a debug message. In future releases we will provide other ways to get notified of the errors.

    Example -

        Nepomuk2::Resource res;
        res.addType( NCO::Contact() );
    
        res.setProperty( NFO::fileName(), "Fire" ); // Will silently fail
        res.property( NFO::fileName() ).toString(); // Will be empty
    
        res.addProperty( NCO::fullname(), QLatin1String("Tom Marvolo Riddle") ); // Will work
        res.addProperty( NCO::fullname(), QLatin1String("Lord Voldemort") ); // Will fail - nco:fullname has a max cardinality of 1
    
        QString origName = res.property( NCO::fullname() ).toString(); // will return "Tom Marvolo Riddle"
        res.setProperty( NCO::fullname(), QLatin1String("Lord Voldemort") ); // will work this time - we're using setProperty
    
        QString newName = res.property( NCO::fullname() ).toString(); // Will return You-know-who
    

    Nepomuk Resource Generator

    While it is fairly convenient to use the setProperty and getProperty methods. It requires you to explicitly define the property which you need modify. This can get quite cumbersome and destroys readability of the code.

    In order to improve this situation we have provided a resource generator, which generates custom Resource classes from the ontologies. It relies on a CMake macro to accomplish that.

    Usage in CMake

    The resource generator is best used through the CMake macro provided by Nepomuk. The syntax is fairly simple and similar to the macro for adding ui files to a list of sources:

    NEPOMUK2_ADD_ONTOLOGY_CLASSES(<sources-var>
             [ONTOLOGIES] <onto-file1> [<onto-file2> ...]
             [CLASSES <classname1> [<classname2> ...]]
             [VISIBILITY <visibility-name>]
           )
    


    The optional CLASSES parameter allows to specify the classes to be generated (RDF class names) in case one does not want all classes in the ontologies to be generated. If omitted all classes in the ontology files will be generated.

    The optional VISIBILITY parameter can only be used in non-fast mode and allows to set the gcc visibility to make the generated classes usable in a publically exported API. The <visibility-name> is used to create the name of the export macro and the export include file. Thus, when using "VISIBILITY foobar" include file "foobar_export.h" needs to define FOOBAR_EXPORT.

    Example

    include(Nepomuk2AddOntologyClasses)
    
    nepomuk2_add_ontology_classes (SRCS
        ONTOLOGIES
        ${SHAREDDESKTOPONTOLOGIES_ROOT_DIR}/nie/nie.trig
        ${SHAREDDESKTOPONTOLOGIES_ROOT_DIR}/nie/nco.trig
        ${SHAREDDESKTOPONTOLOGIES_ROOT_DIR}/pimo/pimo.trig
    )
    


    This will generate a C++ class for each type defined in the mentioned ontologies.

    #include "personcontact.h"
    
    Nepomuk2::PersonContact spiderman;
    spiderman.setFullName( QLatin1String("Peter Parker") );
    QString name = spiderman.fullname();