Difference between revisions of "Projects/Nepomuk/QuickStart"

Jump to: navigation, search
(Includes and Linking)
(Re-done most of the page)
Line 13: Line 13:
 
We will now take a look at a simple way to access a resource's metadata.
 
We will now take a look at a simple way to access a resource's metadata.
  
===Initializing the Resource Manager===
+
===Some Basics===
  
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.
+
Nepomuk is centred around a main 'Resource' class. For simple, non-high performance access to Nepomuk, it is recommended that you use the Resource class.
 +
 
 +
Everything in Nepomuk is a Resource. Each Resource has a number of properties associated with it, which are stored as (key, value) pairs. They keys are referred to as properties or predicates, and the values are referred to as the objects.
 +
 
 +
Every file, folder, contact or tag is a Resource.
 +
 
 +
===Dealing with Tags===
 +
 
 +
Every tag in Nepomuk is a Resource. In fact the Tag class is also derived from the Resource class.
 +
 
 +
====Setting Tags====
  
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
Nepomuk::ResourceManager::instance()->init();
+
Nepomuk2::Tag tag( "Awesome-Tag-Name" );
 +
Nepomuk2::Resource res( url );
 +
res.addTag( tag );
 
</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.
 
  
===Retrieving Metadata===
+
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.
  
Let's get the metadata for a file, assuming the URL or the file is stored in <i>uri</i>.
+
====Retrieving Tags====
  
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
Nepomuk::Resource res( uri );
+
using namespace Nepomuk2;
QHash<QUrl, Nepomuk::Variant> properties = res.properties();
+
 
 +
Resource res( url );
 +
QList<Tag> tags = res.tags();
 +
foreach(const Tag& tag, tags)
 +
    kDebug() << tag.genericLabel();
 
</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:
+
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.
  
<syntaxhighlight lang="cpp-qt">
+
====Listing all the Tags====
for( QHash<QUrl, Nepomuk::Variant>::const_iterator it = properties.constBegin();
+
    it != properties.constEnd(); ++it ) {
+
  QUrl propertyUri = it.key();
+
  Nepomuk::Variant value = it.value();
+
  
  Nepomuk::Types::Class propertyType( propertyUri );
+
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.
  
  someList->appendItem( propertyType.label() + ": " + value.toString() );
+
<syntaxhighlight lang="cpp-qt">
}
+
using namespace Nepomuk2;
 +
 
 +
QList<Tag> tags = Tag::allTags();
 +
foreach(const Tag& tag, tags)
 +
    kDebug() << tag.genericLabel();
 
</syntaxhighlight>
 
</syntaxhighlight>
  
===Setting Metadata===
 
  
Similarly, assume <i>url</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:
+
===Dealing with files===
  
Let's start with the tag and use the easy Nepomukish way:
+
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.
  
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
Nepomuk::Tag tag( "This is my nice tag name" );
+
using namespace Nepomuk2;
Nepomuk::Resource res( url );
+
 
res.addTag( tag );
+
File fileRes( urlOfTheFile );
 +
kDebug() << fileRes.url();
 +
 
 +
Resource res( urlOfTheFile );
 +
if( res.isFile() )
 +
    kDebug() << res.toFile().url();
 +
 
 
</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:
+
Internally Nepomuk Files are not very different from other Resources.
 +
 
 +
===Ratings===
 +
 
 +
Every resource in Nepomuk can be given a numeric rating. It is generally done on a scale of 0-10.
  
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
Nepomuk::Resource res( url );
+
using namespace Nepomuk2;
QString comment = getFancyFileComment();
+
 
res.setProperty( Soprano::Vocabulary::NAO::description(), comment );
+
File fileRes( urlOfTheFile );
 +
int rating = fileRes.rating();
 +
 
 +
rating = rating + 1;
 +
fileRes.setRating( rating );
 
</syntaxhighlight>
 
</syntaxhighlight>
  
That's all. The comment is saved and will now be searchable via Nepomuk.
 
  
 
===Includes and Linking===
 
===Includes and Linking===
 
For the example you need the following includes:
 
For the example you need the following includes:
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
#include <Nepomuk2/ResourceManager>
 
#include <Nepomuk2/Variant>
 
#include <Nepomuk2/Types/Class>
 
 
#include <Nepomuk2/Tag>
 
#include <Nepomuk2/Tag>
#include <Soprano/Vocabulary/NAO>
+
#include <Nepomuk2/Resource>
 +
#include <Nepomuk2/File>
 +
#include <KDebug>
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
 
In your CMakeLists.txt, you need the find macro for Nepomuk and link to it of course ;)
 
In your CMakeLists.txt, you need the find macro for Nepomuk and link to it of course ;)
 +
 
<syntaxhighlight lang="cmake">
 
<syntaxhighlight lang="cmake">
 
find_package(NepomukCore REQUIRED)
 
find_package(NepomukCore REQUIRED)
 
target_link_libraries(myfile ${NEPOMUK_CORE_LIBRARY} )
 
target_link_libraries(myfile ${NEPOMUK_CORE_LIBRARY} )
 
</syntaxhighlight>
 
</syntaxhighlight>

Revision as of 17:14, 1 August 2012


Nepomuk Quickstart
Tutorial Series   Nepomuk
Previous   Getting started with KDE development
What's Next   Handle Resource Metadata with Nepomuk
Further Reading   n/a

Contents

Nepomuk Quickstart

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. We will now take a look at a simple way to access a resource's metadata.

Some Basics

Nepomuk is centred around a main 'Resource' class. For simple, non-high performance access to Nepomuk, it is recommended that you use the Resource class.

Everything in Nepomuk is a Resource. Each Resource has a number of properties associated with it, which are stored as (key, value) pairs. They keys are referred to as properties or predicates, and the values are referred to as the objects.

Every file, folder, contact or tag is a Resource.

Dealing with Tags

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 all the 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();


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.

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 );


Includes and Linking

For the example you need the following includes:

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


In your CMakeLists.txt, you need the find macro for Nepomuk and link to it of course ;)

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

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal