Projects/Nepomuk/QuickStart: Difference between revisions

    From KDE TechBase
    m (Fix spelling: Nepmuk->Nepomuk)
    (Added links)
    (23 intermediate revisions by 2 users not shown)
    Line 1: Line 1:
    {{Template:I18n/Language Navigation Bar|Development/Tutorials/Metadata/Nepomuk/Quickstart}}
    This page serves as a very simple overview to Nepomuk. It focuses on getting started with Nepomuk and tries not to deal with internal Nepomuk concepts. Please keep in the mind that the processes described here are targeted to the general use case. If you have a more specialized use case in mind, this might not be the best way to use the Nepomuk libraries.


    {{TutorialBrowser|
    =Libraries and Headers=
    series=[[../|Nepomuk]]|
    name=Nepomuk Quickstart|
    pre=[[Getting_Started|Getting started with KDE development]]|
    next=[[../Resources|Handle Resource Metadata with Nepomuk]]|
    }}


    ==Nepomuk Quickstart==
    Most of the non graphic parts of Nepomuk are present in the [https://projects.kde.org/projects/kde/kdelibs/nepomuk-core NepomukCore repository]. It is shipped with KDE 4.9, and should be provided by your distribution. When starting with Nepomuk development, it would be better to stick with your distribution version.


    Reading or setting simple metadata in your application with Nepomuk, can be very easy. However, keep in mind that the process described here may have performance drawbacks when changing a lot of metadata.
    With KDE 4.9, the Nepomuk libraries moved to the Nepomuk2 namespace. The headers also follow a similar convention.
    We will now take a look at a simple way to access a resource's metadata.


    ===Initializing the Resource Manager===
    ==Headers==
    All the Nepomuk headers in are preceded by Nepomuk2. Here are some common Nepomuk includes that are frequently used -


    The ResourceManager is the central KMetaData configuration point. For KDE 4.2 and newer, we must explicitly initialize it in order to connect to the Nepomuk service.
    <syntaxhighlight lang="cpp-qt">
    #include <Nepomuk2/Tag>
    #include <Nepomuk2/Resource>
    #include <Nepomuk2/ResourceManager>
    #include <Nepomuk2/File>
    </syntaxhighlight>


    <syntaxhighlight lang="cpp-qt">
    ==CMake==
    Nepomuk::ResourceManager::instance()->init();
     
    KDE Projects generally use cmake as a build tool. Nepomuk is no different. In order to use Nepomuk you need to add the relevant macros for Nepomuk in your CMakeLists.txt.
     
    <syntaxhighlight lang="cmake">
    find_package(NepomukCore REQUIRED)
    target_link_libraries(myfile ${NEPOMUK_CORE_LIBRARY} )
    </syntaxhighlight>
    </syntaxhighlight>


    This method returns an <i>int</i>. If it succeeds (returns 0), the connection to the Nepomuk service has been established and we can work with it. If it fails (returns negative integer), the Nepomuk service was unreachable and we can't continue working with any Nepomuk related code--this may occur if the user has disabled the Nepomuk service for his current session.
    =Basic Terminology=
     
    At the lowest level Nepomuk is just a database which many applications use to store data. The main difference is that the data is not stored in rows and columns like traditional relational databases. Instead Nepomuk can be viewed as something similar to an object or document store. We store a large number of objects, and each of these objects have (key, value) pairs attached to them.
     
    Each object in our database is called a Resource. Everything in Nepomuk revolves around resources. All the higher level concepts such as files, tags, contacts, music albums, actors, etc. they are all Resources. Each of these resources has a number of (key, value) pairs associated with it. In the Nepomuk world, the keys are called properties or predicates, and have already been defined.


    ===Retrieving Metadata===
    Nepomuk is also based around a concept called the Semantic Web. However, understanding the ideas and details behind the Semantic Web is not necessary.


    Let's get the metadata for a file, assuming the URL or the file is stored in <i>uri</i>.
    =Tags and Ratings=
     
    Every tag in Nepomuk is a Resource. In fact the [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Tag.html Tag class] is also derived from the [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html Resource class].
     
    ==Setting Tags==


    <syntaxhighlight lang="cpp-qt">
    <syntaxhighlight lang="cpp-qt">
    Nepomuk::Resource res( uri );
    Nepomuk2::Tag tag( "Awesome-Tag-Name" );
    QHash<QUrl, Nepomuk::Variant> properties = res.properties();
    Nepomuk2::Resource res( url );
    res.addTag( tag );
    </syntaxhighlight>
    </syntaxhighlight>


    This allows us to obtain all the properties assigned to the file.


    We can now use Nepomuk to get human-readable labels for the properties, and display the properties in a generic way:
    The [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Tag.html <tt>Nepomuk2::Tag</tt>] class will automatically look for for a tag called "Awesome-Tag-Name", it is finds it then [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html#a3c58ca2096f8424e12f31ddd73369597 Tag::exists()] will return true. Otherwise, the tag will be saved the first time the tag is used. In our case, when we add the tag to the Resource via [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html#a649e935b3557d0c5015ab7728f623f66 Resource::addTag()], the tag will be saved.
     
    ==Retrieving Tags==


    <syntaxhighlight lang="cpp-qt">
    <syntaxhighlight lang="cpp-qt">
    for( QHash<QUrl, Nepomuk::Variant>::const_iterator it = properties.constBegin();
    using namespace Nepomuk2;
        it != properties.constEnd(); ++it ) {
      QUrl propertyUri = it.key();
      Nepomuk::Variant value = it.value();


      Nepomuk::Types::Class propertyType( propertyUri );
    Resource res( url );
    QList<Tag> tags = res.tags();
    foreach(const Tag& tag, tags)
        kDebug() << tag.genericLabel();
    </syntaxhighlight>


      someList->appendItem( propertyType.label() + ": " + value.toString() );
    }
    </syntaxhighlight>


    ===Setting Metadata===
    Every resource has a predefined function for retrieving all the Tags any resource is tagged with - [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html#a286c2e37f975e58e38aaa83903040910 Resource::tags()]. The [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Resource.html#ad8d16485bdc9788de60bf5784141bcac Resource::genericLabel()] function tries to find a presentable name for any resource. In the case of tags, it returns the tags name.


    Similarly, assume <i>uri</i> is the URL of a file that we want to set some metadata to. This time we want to set a tag and a comment and will do this using two slightly different methods:
    ==Listing Tags==


    Let's start with the tag and use the easy Nepomukish way:
    The simplest way to list all the tags that are present in Nepomuk is via a static function - [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Tag.html#a03bc6a42a14003aca17e8c3e02f43d17 Tag::allTags()]. You, however, need to be careful using this in a production environment as it executes a blocking query in the background. Depending on the number of tags on the system, it could take some time.


    <syntaxhighlight lang="cpp-qt">
    <syntaxhighlight lang="cpp-qt">
    Nepomuk::Tag tag( "This is my nice tag name" );
    using namespace Nepomuk2;
    Nepomuk::Resource res( uri );
     
    res.addTag( tag );
    QList<Tag> tags = Tag::allTags();
    foreach(const Tag& tag, tags)
        kDebug() << tag.genericLabel();
    </syntaxhighlight>
    </syntaxhighlight>


    Simple! Actually, if the tag already exists, it will be reused.


    Now let's set a comment for the file without the use of the convenience methods in Nepomuk:
    There are also convenience functions to list all the resources that have been assigned a particular tag - [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1Tag.html#a04256e4dda504e5b021afcab0ba4b714 Tag::tagOf]


    <syntaxhighlight lang="cpp-qt">
    <syntaxhighlight lang="cpp-qt">
    Nepomuk::Resource res( uri );
    using namespace Nepomuk2;
    QString comment = getFancyFileComment();
     
    res.setProperty( Soprano::Vocabulary::NAO::description(), comment );
    Tag tag("Awesome-Tag-Name");
    QList<Resoruce> taggedResources = tag.tagOf();
     
    foreach(const Resource& res, taggedResources)
        kDebug() << res.genericLabel();
    </syntaxhighlight>
    </syntaxhighlight>


    That's all. The comment is saved and will now be searchable via Nepomuk.
    ==Ratings==
     
    Every resource in Nepomuk can be given a numeric rating. It is generally done on a scale of 0-10.


    ===Includes and Linking===
    For the example you need the following includes:
    <syntaxhighlight lang="cpp-qt">
    <syntaxhighlight lang="cpp-qt">
    #include <Nepomuk/ResourceManager>
    using namespace Nepomuk2;
    #include <Nepomuk/Variant>
     
    #include <Nepomuk/Types/Class>
    File fileRes( urlOfTheFile );
    #include <Nepomuk/Tag>
    int rating = fileRes.rating();
    #include <Soprano/Vocabulary/NAO>
     
    rating = rating + 1;
    fileRes.setRating( rating );
    </syntaxhighlight>
    </syntaxhighlight>
    In your CMakeLists.txt, you need the find macro for Nepomuk and link to it of course ;)
     
    <syntaxhighlight lang="cmake">
    =Dealing with files=
    find_package(Nepomuk REQUIRED)
     
    target_link_libraries(myfile ${NEPOMUK_LIBRARIES} )
    Every file in Nepomuk is represented as a resource. Since dealing with files is very common, we provide a special [http://api.kde.org/4.x-api/kdelibs-apidocs/nepomuk-core/html/classNepomuk2_1_1File.html File class] which is derived from the Resource class. We also provide convenience functions for checking if a resource is a file.
     
    <syntaxhighlight lang="cpp-qt">
    using namespace Nepomuk2;
     
    File fileRes( urlOfTheFile );
    kDebug() << fileRes.url();
     
    Resource res( urlOfTheFile );
    if( res.isFile() )
        kDebug() << res.toFile().url();
     
    </syntaxhighlight>
    </syntaxhighlight>
    Internally Nepomuk Files are not very different from other Resources.
    = Working Example =
    We understand that using a new framework such as Nepomuk can be quite intimidating at times. Therefore, we though it would be nice to have a working example for you to get started with - [http://quickgit.kde.org/index.php?p=kdeexamples.git&a=tree&h=eddcb1707a9e600db49fafdcb5ed8e8a195bcaba&hb=80a322af2bc5975c01c704173e937ccb8df605e3&f=nepomuk%2Ftest kdeexamples/nepomuk/test]. This example does nothing but it creates an executable called <code>nepomuk-test</code>. It serves as a simple starting point to Nepomuk where all the boiler plate code has been taken care of.

    Revision as of 10:44, 24 August 2012

    This page serves as a very simple overview to Nepomuk. It focuses on getting started with Nepomuk and tries not to deal with internal Nepomuk concepts. Please keep in the mind that the processes described here are targeted to the general use case. If you have a more specialized use case in mind, this might not be the best way to use the Nepomuk libraries.

    Libraries and Headers

    Most of the non graphic parts of Nepomuk are present in the NepomukCore repository. It is shipped with KDE 4.9, and should be provided by your distribution. When starting with Nepomuk development, it would be better to stick with your distribution version.

    With KDE 4.9, the Nepomuk libraries moved to the Nepomuk2 namespace. The headers also follow a similar convention.

    Headers

    All the Nepomuk headers in are preceded by Nepomuk2. Here are some common Nepomuk includes that are frequently used -

    #include <Nepomuk2/Tag>
    #include <Nepomuk2/Resource>
    #include <Nepomuk2/ResourceManager>
    #include <Nepomuk2/File>
    

    CMake

    KDE Projects generally use cmake as a build tool. Nepomuk is no different. In order to use Nepomuk you need to add the relevant macros for Nepomuk in your CMakeLists.txt.

    find_package(NepomukCore REQUIRED)
    target_link_libraries(myfile ${NEPOMUK_CORE_LIBRARY} )
    

    Basic Terminology

    At the lowest level Nepomuk is just a database which many applications use to store data. The main difference is that the data is not stored in rows and columns like traditional relational databases. Instead Nepomuk can be viewed as something similar to an object or document store. We store a large number of objects, and each of these objects have (key, value) pairs attached to them.

    Each object in our database is called a Resource. Everything in Nepomuk revolves around resources. All the higher level concepts such as files, tags, contacts, music albums, actors, etc. they are all Resources. Each of these resources has a number of (key, value) pairs associated with it. In the Nepomuk world, the keys are called properties or predicates, and have already been defined.

    Nepomuk is also based around a concept called the Semantic Web. However, understanding the ideas and details behind the Semantic Web is not necessary.

    Tags and Ratings

    Every tag in Nepomuk is a Resource. In fact the Tag class is also derived from the Resource class.

    Setting Tags

    Nepomuk2::Tag tag( "Awesome-Tag-Name" );
    Nepomuk2::Resource res( url );
    res.addTag( tag );
    


    The Nepomuk2::Tag class will automatically look for for a tag called "Awesome-Tag-Name", it is finds it then Tag::exists() will return true. Otherwise, the tag will be saved the first time the tag is used. In our case, when we add the tag to the Resource via Resource::addTag(), the tag will be saved.

    Retrieving Tags

    using namespace Nepomuk2;
    
    Resource res( url );
    QList<Tag> tags = res.tags();
    foreach(const Tag& tag, tags)
        kDebug() << tag.genericLabel();
    


    Every resource has a predefined function for retrieving all the Tags any resource is tagged with - Resource::tags(). The Resource::genericLabel() function tries to find a presentable name for any resource. In the case of tags, it returns the tags name.

    Listing Tags

    The simplest way to list all the tags that are present in Nepomuk is via a static function - Tag::allTags(). You, however, need to be careful using this in a production environment as it executes a blocking query in the background. Depending on the number of tags on the system, it could take some time.

    using namespace Nepomuk2;
    
    QList<Tag> tags = Tag::allTags();
    foreach(const Tag& tag, tags)
        kDebug() << tag.genericLabel();
    


    There are also convenience functions to list all the resources that have been assigned a particular tag - Tag::tagOf

    using namespace Nepomuk2;
    
    Tag tag("Awesome-Tag-Name");
    QList<Resoruce> taggedResources = tag.tagOf();
    
    foreach(const Resource& res, taggedResources)
        kDebug() << res.genericLabel();
    

    Ratings

    Every resource in Nepomuk can be given a numeric rating. It is generally done on a scale of 0-10.

    using namespace Nepomuk2;
    
    File fileRes( urlOfTheFile );
    int rating = fileRes.rating();
    
    rating = rating + 1;
    fileRes.setRating( rating );
    

    Dealing with files

    Every file in Nepomuk is represented as a resource. Since dealing with files is very common, we provide a special File class which is derived from the Resource class. We also provide convenience functions for checking if a resource is a file.

    using namespace Nepomuk2;
    
    File fileRes( urlOfTheFile );
    kDebug() << fileRes.url();
    
    Resource res( urlOfTheFile );
    if( res.isFile() )
        kDebug() << res.toFile().url();
    


    Internally Nepomuk Files are not very different from other Resources.

    Working Example

    We understand that using a new framework such as Nepomuk can be quite intimidating at times. Therefore, we though it would be nice to have a working example for you to get started with - kdeexamples/nepomuk/test. This example does nothing but it creates an executable called nepomuk-test. It serves as a simple starting point to Nepomuk where all the boiler plate code has been taken care of.