Explanation of the new API
From KatWiki
| Table of contents |
Engine
Engine represents the starting point for accessing the features of the Kat desktop search environment.
Once instantiated, this class reads the list of available repository plugins and instantiates the default repository (SQLite3Repository) or another repository selected by the user. The user's choice is contained in Kat's configuration file.
Engine holds a list of available repository plugins and a method for accessing the list. It also holds a pointer to the active repository and a method for accessing the pointer.
Example:
#include <iostream>
#include <katengine.h>
Kat::Engine* engine = new Kat::Engine();
Kat::RepositoryPluginList repositoryPluginList =
engine->repositoryPlugins();
Kat::RepositoryPluginListIterator it( repositoryPluginList );
for( ; it.current(); ++it )
{
Kat::RepositoryPlugin* repositoryPlugin = it.current();
cout << repositoryPlugin->m_library << endl;
cout << repositoryPlugin->m_description << endl;
cout << repositoryPlugin->m_name << endl;
cout << repositoryPlugin->m_authors << endl;
cout << repositoryPlugin->m_email << endl;
cout << repositoryPlugin->m_version << endl;
cout << repositoryPlugin->m_frameworkVersion << endl;
}
Kat::Repository* repository = engine->repository();
Repository
Repository is a virtual class that has to be subclassed in order to implement a Kat repository. The current version of the API (0.7.0) only contains one implementation of this class: SQLite3Repository.
This virtual class contains the code needed to read the list of available Space and Object plugins so that subclasses will not have to implement this functionality.
Repository holds a list of available space and object plugins and methods for accessing the lists.
Example:
#include <iostream>
#include <katengine.h>
Kat::Engine* engine = new Kat::Engine();
Kat::Repository* repository = engine->repository();
Kat::SpacePluginList spacePluginList =
repository->spacePlugins();
Kat::SpacePlugin* spacePlugin;
Kat::SpacePluginListIterator it( spacePluginList );
for( ; it.current(); ++it )
{
spacePlugin = it.current();
cout << spacePlugin->m_library << endl;
cout << spacePlugin->m_type << endl;
cout << spacePlugin->m_description << endl;
cout << spacePlugin->m_name << endl;
cout << spacePlugin->m_authors << endl;
cout << spacePlugin->m_email << endl;
cout << spacePlugin->m_version << endl;
cout << spacePlugin->m_frameworkVersion << endl;
// spacePlugin->m_constructor is not printable
}
// get the constructor of the FileSystemSpace
spacePlugin = spacePluginList->find( TYPE_FILESYSTEMSPACE );
// instantiate a FileSystemSpace
if ( spacePlugin->m_constructor )
Kat::Space* space = spacePlugin->m_constructor();
Tag
Tag is a class representing atomic information about an entity. Every information entity in Kat is defined as a dictionary whose keys are represented by tags.
A tag describes a piece of information in terms of name, description, data type and role.
The data type of a tag has to be espressed as a subtype of QVariant. The following list shows the subtypes of QVariant that are managed by the Kat desktop search environment:
- QVariant::ByteArray - a QByteArray
- QVariant::Bool - a bool
- QVariant::Date - a QDate
- QVariant::Time - a QTime
- QVariant::DateTime - a QDateTime
- QVariant::Double - a double
- QVariant::Int - an int
- QVariant::LongLong - a long long
- QVariant::String - a QString
- QVariant::StringList - a QStringList
The role of a tag is a combination of the following values that can be obtained using the OR logic operator:
- NONE none
- GET this tag can be requested from the repository
- SET this tag can be sent to the repository to index
- QUERY a query can be run on this tag
Example:
Tag* tag = new Tag( "name",
"name of the space",
0,
Tag::GET | Tag::SET | Tag::QUERY,
QVariant::String );
Entity
Entity is a virtual class representing the most basic information object managed by the Kat desktop search environment. There are two subclasses of it, Space and Object, which are also virtual classes.
Entity is defined as a dictionary of QVariant objects whose keys are represented by integer values.
The key of each dictionary entry is represented by a tag, while the value of the entry is represented by a pointer to a QVariant object.
Entity also holds the list of the tags it supports. Basic tags are defined for the basic class Entity. Every subclass adds to the list the tags that are needed to describe it.
The basic tags defined in Entity are:
- TAG_ID - the unique identifier of the entity
- TAG_TYPE - the type of the entity
Entity defines a pure virtual method, type(), which has to be implemented in every subclass, and can be called in order to know the type of an entity. Being Space and Object subclasses of Entity, it is possible to have, for example, an EntityList containing objects of both subclasses.
Example:
#include <katfilesystemspace.h>
Kat::Engine* engine = new Kat::Engine();
Kat::Repository* repository = engine->repository();
Kat::SpacePluginList spacePluginList =
repository->spacePlugins();
Kat::SpacePlugin* spacePlugin;
// get the constructor of the FileSystemSpace
spacePlugin = spacePluginList->find( TYPE_FILESYSTEMSPACE );
// instantiate a FileSystemSpace
if ( spacePlugin->m_constructor )
Kat::Entity* entity = (Entity*)spacePlugin->m_constructor();
// get the list of supported tags
Kat::TagList tagList = entity->tags();
cout << tagList.count() << endl;
TagListIterator it( tagList );
for ( ; it.current(); ++it )
cout << it.currentKey() << ": " << it.current()->m_field << endl;
// get the value of an attribute
// ALWAYS check for the existence of the attribute!
if ( entity->find( TAG_ID ) )
long long id = entity->find( TAG_ID )->asLongLong();
if ( entity->find( TAG_TYPE ) )
int type = entity->find( TAG_TYPE)->asInt();
// set the value of an attribute
entity->insert( TAG_ID, new QVariant( 4 ) );
// change the value of an attribute
entity->replace( TAG_ID, new QVariant( 5 ) );
// eliminate an attribute
entity->remove( TAG_ID );
If you are not sure whether an attribute has already beed defined in an entity, use replace() instead of insert(). If the attribute is not present in the entity, it is automatically added.
Space
Space is a subclass of Entity. Space is a virtual class that has to be further subclassed in order to implement a Kat information space. The current implementation of the Kat API (0.7.0) only contains one implementation of this class: FileSystemSpace.
This virtual class holds a list of tags that can be used for describing a basic information space. Every subclass of Space inherits that list and adds to it the specific tags needed to describe the more specialized information space.
The tags defined in Space are:
- TAG_SPACE_NAME - the name of the space
- TAG_SPACE_DESCRIPTION - the description of the space
- TAG_SPACE_CREATIONDATE - the creation date of the space
- TAG_SPACE_LASTUPDATEDATE - the last update date of the space
