Mainpage.dox

/**
 * \mainpage Soprano (aka QRDF) - A modular RDF storage framework
 *
 * %Soprano is a <a href="http://www.qtsoftware.com/">Qt</a>-based pluggable framework for <a href="http://www.w3.org/RDF/">RDF</a>
 * storage and parsing. It tries to provide a highly usable interface to several Resource Description Framework (RDF) storage solutions.
 *
 * \section overview Overview
 *
 * %Soprano centers around the Soprano::Model class which represents one storage set. A Soprano::Model is basically a set of
 * RDF quadruples, i.e. Soprano::Statement. The actual storage is done via Soprano::Backend plugins. All
 * query operations return Soprano::Iterator instances. Iterator is an explicitly shared class which is very
 * easy to understand and use.
 *
 * %Soprano makes the distinction between two types of Models: Soprano::StorageModel and Soprano::FilterModel.
 * The former is intended to be the basic Model which actually stores the data while the latter can be
 * stacked on top of a Soprano::StorageModel to perform certain filter operations. These filter operations can range
 * from very basic things such as disallowing any write operation (Soprano::Util::ReadOnlyModel) to more complex
 * things such as full text indexing of all literal statements (Soprano::Index::IndexFilterModel) or exporting
 * the Model via D-Bus (Soprano::Server::DBusExportModel).
 *
 * Apart from storage %Soprano provides a system for RDF parser and serializer plugins. For more details on parsing
 * or serializing RDF data see the Soprano::Parser and Soprano::Serializer classes.
 *
 * %Soprano comes with a built in \link Soprano::Server Server \endlink and \link Soprano::Client Client \endlink implementations allowing remote repositories to be built quickly.
 * Soprano::Client::SparqlModel provides a client to arbitrary <a href="http://www.w3.org/TR/rdf-sparql-protocol/">SPARQL (SPARQL Protocol and RDF Query Language)</a>
 * Http services.
 *
 * \section quickstart Quickstart
 *
 * (Also see the \ref soprano_howto for details on building %Soprano applications)
 *
 * Create an RDF Model:
 *
 * \code
 * Soprano::Model* model = Soprano::createModel();
 * \endcode
 *
 * Fill it with statements:
 *
 * \code
 * model->addStatement( Soprano::Statement( QUrl( "http://mysite.org/data#A"), Soprano::Vocabulary::RDFS::label(), Soprano::LiteralValue( "A test resource" ) ) );
 * \endcode
 *
 * Read the data back:
 *
 * \code
 * Soprano::StatementIterator it = model->listStatements();
 * while( it.next() ) {
 *    displayStatement( *it );
 * }
 * \endcode
 *
 * Query the data:
 *
 * \code
 * Soprano::QueryResultIterator it = model->executeQuery( "select ?r where { ?r ?p ?o . }", Soprano::Query::QueryLanguageSparql );
 * while( it.next() ) {
 *    displayResult( it.binding( "r" ) );
 * }
 * \endcode
 *
 * \section contents Contents
 *
 * The following sections contain further information on the usage of %Soprano.
 *
 * \li \subpage soprano_howto - Learn how to integrate %Soprano into your build system
 * \li \subpage soprano_storage - Learn how to use RDF storage in %Soprano
 * \li \subpage soprano_misc - Learn how to parse and serialize RDF data in %Soprano
 * \li \subpage soprano_error_handling - Learn how %Soprano's error system works
 * \li \subpage soprano_writing_plugins - Learn how to write your own %Soprano plugins
 * \li \ref Soprano::Server - Learn how to create a %Soprano server
 * \li \ref Soprano::Client - Learn how to create a %Soprano client accessing a %Soprano server via DBus or a local socket
 * \li \subpage soprano_devel_tools - Learn about the nice command line tools %Soprano provides
 * \li \ref soprano_backends - Learn about the available storage backends and their features and settings
 */


/**
 * \page soprano_storage RDF Storage
 *
 * The central class in Soprano is Soprano::Model which represents an RDF repository.
 * Model provides methods to add, remove, and list statements and to query the repository.
 *
 * The actual work is done by storage plugins (Soprano::Backend).
 *
 * Model instances are mostly created by the plugin implementations through the
 * Soprano::Backend::createModel() methods. In the most simple case one does not need to bother
 * with Soprano::Backend though, as the basic methods are duplicated in the Soprano
 * namespace. Thus, to create a simple memory model using the default %Soprano backend:
 *
 * \code
 * Soprano::Model m = Soprano::createModel();
 * \endcode
 *
 * Finer grained control can be achieved by using the Backend directly:
 *
 * \code
 * Soprano::Backend* backend = Soprano::discoverBackendByName( "redland" );
 * Soprano::Model* model = backend->createModel();
 * \endcode
 *
 * %Soprano makes use of contexts, i.e. named graphs. Thus, statements as represented by
 * Soprano::Statement are actually RDF quadruples.
 *
 * For further details on Soprano::Model usage see the class and method documentation.
 *
 * For details on existing backends see:
 * \li \subpage soprano_backends
 */

/**
 * \page soprano_backends Soprano Backends
 *
 * %Soprano is plugin based and comes with three backend plugins which can be used directly
 * (if they have been built):
 *
 * \li \subpage soprano_backend_redland
 * \li \subpage soprano_backend_sesame2
 * \li \subpage soprano_backend_virtuoso
 */

/**
 * \page soprano_misc RDF Parsing and Serialization
 *
 * Apart from RDF storage %Soprano also supports parsing and serialization of RDF data. Both
 * tasks are handled through plugins which are based on Soprano::Parser and Soprano::Serializer.
 */


/**
 * \page soprano_error_handling Error handling in Soprano
 *
 * %Soprano tries to simulate exceptions through the usage of Soprano::Error::ErrorCache.
 *
 * Most methods in %Soprano classes have a means of reporting if an operation was successful or not. For additional error
 * information they inherit Soprano::Error::ErrorCache which provides the method Soprano::Error::ErrorCache::lastError().
 *
 * Thus, advanced error handling would look as follows:
 *
 * \code
 * Soprano::Model* model = Soprano::createModel();
 * Soprano::Statement invalidStatement;
 * if( model->addStatement( invalidStatement ) != Error::ErrorNone ) {
 *    showErrorMessage( model->lastError().message() );
 * }
 * \endcode
 *
 * For methods that do not return an immediate error status, Soprano::Error::Error evaluates to a boolean. Thus, one can easily
 * check if an error occurred as follows:
 *
 * \code
 * Soprano::StatementIterator it = model->listStatements();
 * while( it.next() ) {
 *    doSomething( *it );
 * }
 * if( it.lastError() ) {
 *    displayError( "Iteration failed: " + it.lastError().message() );
 * }
 * \endcode
 *
 * This has the same effect as checking for Soprano::Error::ErrorNone.
 *
 * This error handling is thread-safe. Thus, two threads can for example call methods of one Model at the same time
 * and still get proper Soprano::Error::Error instances back.
 */

/**
 * \page soprano_writing_plugins Writing Soprano Plugins
 *
 * %Soprano has five kinds of plugins: Soprano::Backend, Soprano::Parser, Soprano::Serializer,
 * Soprano::Query::Parser, and Soprano::Query::Serializer.
 *
 * Creating a new plugin for %Soprano is pretty easy. Imagine, for example, we want to write a new Backend plugin.
 * We simply create a class that inherits from QObject and the Soprano::Backend interface and
 * use the Q_INTERFACES macro to tell Qt's meta-object system about the new plugin. We then
 * export the plugin via the Q_EXPORT_PLUGIN2 macro in the source file.
 *
 * An example would look as follows:
 *
 * \code
 * class MyBackend : public QObject, public Soprano::Backend
 * {
 *    Q_OBJECT
 *    Q_INTERFACES(Soprano::Backend)
 *
 * public:
 *    StorageModel* createModel( const QStringList& options = QStringList() ) const;
 *    bool deleteModelData( const BackendSettings& settings ) const;
 *    BackendFeatures supportedFeatures() const;
 * };
 * \endcode
 *
 * In the implementation file, export the plugin so that it can be picked up by the
 * plugin loading framework:
 *
 * \code
 * Q_EXPORT_PLUGIN2(soprano_mybackend, MyBackend)
 * \endcode
 *
 * The plugin then needs to be linked as a library and installed into the lib/soprano
 * target folder.
 *
 * Finally we need to create a desktop file describing the plugin. The minimal desktop file
 * looks as follows (for details see \subpage soprano_plugin_desktop_file):
 *
 * \code
 * [Desktop Entry]
 * Encoding=UTF-8
 * X-Soprano-Library=libsoprano_mybackend
 * X-Soprano-Version=2.2
 * Type=Service
 * ServiceTypes=Soprano/Backend
 * Name=MyBackend
 * Comment=My very cool and fast Soprano backend
 * \endcode
 *
 * The desktop file should be installed into share/soprano/plugins so the Soprano::PluginManager
 * will find it.
 *
 * All plugin interfaces inherit from Soprano::Error::ErrorCache for error handling and
 * subclasses should use Soprano::Error::ErrorCache::clearError()
 * and Soprano::Error::ErrorCache::setError() to report the status.
 */

/**
 * \page soprano_plugin_desktop_file Soprano Plugin Desktop Files
 *
 * Generic Desktop entries:
 * \code
 * [Desktop Entry]
 * Encoding=UTF-8
 * \endcode
 *
 * The name of the lib to load. This is the filename of the library without the extension.
 * \code
 * X-Soprano-Library=
 * \endcode
 *
 * Optional information about the plugin:
 *
 * \code
 * X-Soprano-Plugin-Author=
 * X-Soprano-Plugin-EMail=
 * X-Soprano-Plugin-Website=
 * X-Soprano-Plugin-License=
 * X-Soprano-Plugin-Version=
 * \endcode
 *
 * The soprano version this plugin has been written for.
 * The major version is the one that is important.
 * \code
 * X-Soprano-Version=
 * \endcode
 *
 * The type always needs to be set to "Service". ServiceTypes can be one of the following:
 * \li Soprano/Backend
 * \li Soprano/Parser
 * \li Soprano/Serializer
 * \li Soprano/QueryParser
 * \li Soprano/QuerySerializer
 *
 * \code
 * ServiceTypes=
 * Type=Service
 * \endcode
 *
 * The name of the plugin (human readable):
 * \code
 * Name=
 * \endcode
 *
 * An optional comment to further describe the plugin:
 * \code
 * Comment=
 * \endcode
 */

/**
 * \namespace Soprano::Vocabulary
 *
 * The vocabulary namespace contains static const QUrl objects for the most frequently
 * used ontology resources such as RDF or RDFS.
 *
 * Each member of this namespace is a namespace again which contains the resources for
 * one particular ontology. Linking to these namespaces is no overhead since the QUrl
 * objects are not created before the first usage. Thus, if an application for example
 * never uses any resource from the RDF namespace no memory will be allocated for its
 * members.
 */

/**
 * \page soprano_devel_tools Soprano Development Tools
 *
 * %Soprano provides two small tools that can make the life of a developer easier.
 *
 * \section sopranocmd sopranocmd
 *
 * sopranocmd is a simple command line client to access %Soprano repositories or the \ref Soprano::Server.
 * sopranocmd's usage is rather simple. It provides a comprehensive help message which can be accessed via:
 *
 * \code
 * sopranocmd --help
 * \endcode
 *
 *
 * \section onto2vocabularyclass onto2vocabularyclass
 *
 * onto2vocabularyclass is a small tool which creates C++ namespaces for ontologies such as Soprano::Vocabulary::RDF
 * or Soprano::Vocabulary::NRL. Usage is as follows:
 *
 * \code
 * onto2vocabularyclass --name <name> --encoding <encoding> [--namespace <ns>] [--export-module <module>|--no-visibility-export] <ontologyfile>
 * \endcode
 *
 * The value of \p --name is use as the name of the generated namespace (the RDF in Soprano::Vocabulary::RDF).
 *
 * The optional value of \p --namespace is used as the surrounding namespace (the Soprano::Vocabulary in Soprano::Vocabulary::RDF).
 * If none is specified the global namespace is used.
 *
 * The value of \p --encoding specifies the encoding of the ontologyfile used for parsing.
 *
 * For historical reasons by default the %Soprano visibility macro SOPRANO_EXPORT is used. This can be
 * changed by specifying the visibility export module through \p --export-module or disabling visibility
 * all together with \p --no-visibility-export. The latter is useful if the namespace is not part of a public
 * API. When using the \p --export-module parameter the value is used to generate the macro (&lt;module&gt;_EXPORT)
 * and to generate the include file (&lt;module&gt;_export.h) which has to exist and define the macro.
 *
 * See \ref cmake_magic for simple integration of onto2vocabularyclass in the build system.
 */

/**
 * \page soprano_howto Soprano Howto
 *
 * \section includes Soprano includes
 *
 * Using %Soprano in your own project is pretty straight forward. %Soprano provides includes for all classes and enumerations.
 * Using a %Soprano class like Statement is as simple as including
 *
 * \code
 * #include <Soprano/Statement>
 * \endcode
 *
 * For an easy start one can simply include the %Soprano header which pulls in all classes. The following code shows a
 * simple example of a %Soprano application which creates a new Model, adds a Statement, and lists it.
 *
 * \code
 * #include <Soprano/Soprano>
 * #include <QDebug>
 *
 * int main( int argc, char** argv )
 * {
 *     Soprano::Model* model = Soprano::createModel();
 *     model->addStatement( QUrl( "http://mysite.org/data#A"),
 *                          Soprano::Vocabulary::RDFS::label(),
 *                          Soprano::LiteralValue( "A test resource" ) );
 *     Soprano::StatementIterator it = model->listStatements();
 *     while( it.next() )
 *         qDebug() << *it;
 * }
 * \endcode
 *
 *
 * \section build_systems Soprano in the Build System
 *
 * Integrating %Soprano into your own build system is rather simple. %Soprano provides a set of libraries and one include path.
 * The libraries are:
 * \li libsoprano - The core library providing storage, parsing, and all utility classes
 * \li libsopranoindex - The full text index based on CLucene (Soprano::Index)
 * \li libsopranoserver - The server library which provides a simple implementation of an RDF database server (Soprano::Server)
 * \li libsopranoclient - The counterpart to the server library (Soprano::Client)
 *
 * A PkgConfig description is provided for the core library and can be used as described in the following.
 *
 *
 * \subsection qmake Using qmake with Soprano
 *
 * %Soprano provides pkg-config integration which allows to build the above example using qmake. The following pro file
 * looks for %Soprano includes and libs via pkg-config and builds the application sopranotest.
 *
 * \code
 * TEMPLATE = app
 * SOURCES += main.cpp
 * TARGET = sopranotest
 * CONFIG += qt link_pkgconfig
 * PKGCONFIG += soprano
 * \endcode
 *
 *
 * \subsection cmake Using CMake with Soprano
 *
 * Using cmake is simple. Find required packages \em Qt4 and \em PkgConfig, look for %Soprano via PkgConfig and link to both
 * %Soprano and QtCore:
 *
 * \code
 * find_package(PkgConfig REQUIRED)
 * find_package(Qt4 REQUIRED)
 * pkg_search_module(Soprano REQUIRED soprano)
 * include_directories(${Soprano_INCLUDE_DIRS} ${QT_INCLUDE_DIR})
 * add_executable(sopranotest main.cpp)
 * target_link_libraries(sopranotest ${Soprano_LIBRARIES} ${QT_QTCORE_LIBRARY})
 * \endcode
 *
 * \warning PkgConfig is not available on Windows. For platform independent development use a typical cmake module like
 * KDE's <a href="http://websvn.kde.org:80/%2Acheckout%2A/trunk/KDE/kdelibs/cmake/modules/FindSoprano.cmake">FindSoprano.cmake</a>.
 *
 * \subsubsection cmake_magic Some CMake Magic
 *
 * %Soprano provides the simple \ref onto2vocabularyclass tool which can generate convenience namespaces such as Soprano::Vocabulary::RDF
 * from ontology files. With CMake it is very simple to generate these namespaces on-the-fly instead of packaging the generated files by
 * using the SopranoAddOntology macro provided by %Soprano:
 *
 * \code
 * soprano_add_ontology(SOURCES
 *                      ONTOLOGY_FILE
 *                      ONTOLOGY_NAME
 *                      NAMESPACE
 *                      ENCODING
 *                      [VISIBLITY VISIBILITY_NAME])
 * \endcode
 *
 * Imagine one's code contains an ontology description in rdf+xml format named Foo (Foo Object Ontology) and you want to make its classes and
 * properties accessible in the <em>MyStuff::Foo</em> namespace. One simply includes the cmake macro provided by Soprano:
 *
 * \code
 * include(SopranoAddOntology)
 * \endcode
 *
 * And then uses it to add the generated files to the sources:
 *
 * \code
 * soprano_add_ontology(foo_SOURCES ${CMAKE_CURRENT_BINARY_DIR}/foo.rdfs "FOO" "Vocabulary" "rdfxml")
 * \endcode
 *
 * This will add a command to generate files foo.h and foo.cpp at build time and add the latter to the sources foo_SOURCES. The generated
 * namespace will be named Vocabulary::FOO. It is optionally possible to make the namespace public API and export it by adding the VISIBILITY
 * keyword:
 *
 * \code
 * soprano_add_ontology(foo_SOURCES ${CMAKE_CURRENT_BINARY_DIR}/foo.rdfs "FOO" "Vocabulary" "rdfxml" VISIBILITY "foo")
 * \endcode
 */

// DOXYGEN_VERSION=2.3
// DOXYGEN_NAME=Soprano
// DOXYGEN_COPYRIGHT=2007-2009 <a href='mailto:trueg@kde.org'>Sebastian Trueg</a>
// DOXYGEN_ENABLE=YES
// DOXYGEN_SET_RECURSIVE = NO
// DOXYGEN_SET_HTML_DYNAMIC_SECTIONS  = YES
// DOXYGEN_SET_FILE_PATTERNS = *.h
// DOXYGEN_SET_INPUT = @topdir@/soprano/Mainpage.dox
// DOXYGEN_SET_INPUT += @topdir@/soprano/soprano/
// DOXYGEN_SET_INPUT += @topdir@/soprano/soprano/util/
// DOXYGEN_SET_INPUT += @topdir@/soprano/soprano/vocabulary/
// DOXYGEN_SET_INPUT += @topdir@/soprano/soprano/inference/
// DOXYGEN_SET_INPUT += @topdir@/soprano/index/indexfiltermodel.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/index/cluceneindex.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/index/indexqueryhit.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/servercore.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/dbus/tcpclient.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/dbus/localsocketclient.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/dbus/dbusclient.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/dbus/dbusmodel.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/dbus/dbusstatementiterator.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/dbus/dbusnodeiterator.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/dbus/dbusqueryresultiterator.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/dbus/dbusexportmodel.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/dbus/dbusexportiterator.h
// DOXYGEN_SET_INPUT += @topdir@/soprano/server/SopranoServer.dox
// DOXYGEN_SET_EXCLUDE = @topdir@/soprano/soprano/datetime.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/desktopfile.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/inifile.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/sopranopluginfile.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/pluginstub.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/util/mutexiteratorbase.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/util/mutexnodeiteratorbackend.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/util/mutexstatementiteratorbackend.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/util/mutexqueryresultiteratorbackend.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/util/asyncmodel_p.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/util/asynccommand.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/util/asynciteratorbackend.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/util/asyncqueryresultiteratorbackend.h
// DOXYGEN_SET_EXCLUDE += @topdir@/soprano/soprano/util/extreadwritelock.h