/**
 * \namespace Soprano::Server
 *
 * %Soprano provides simple server and client librarys which allow for remote access to %Soprano models. See the
 * Client module for convinience classes to connect to the %Soprano %Server.
 *
 * \sa \ref soprano_server_dbus, \ref soprano_server_protocol, Soprano::Server, Soprano::Client
 */

/**
 * \page soprano_server_dbus Soprano D-Bus Interface
 *
 * \warning When using the %Soprano D-Bus interface from a QT application there is normally no need to use the D-Bus
 * interfaces directly. Soprano::Client::DBusClient and Soprano::Client::DBusModel provide very convenient wrapping
 * classes.
 *
 *
 * %Soprano provides a server implementation with a D-Bus interface. The server can be deployed in two different ways:
 * by running the sopranod server application which registers the org.soprano.Server service or by using
 * the Soprano::Server::ServerCore class and calling Soprano::Server::ServerCore::registerAsDBusObject method.
 *
 * The %Soprano server uses a set of D-Bus interfaces. When registered the server exports the org.soprano.Server interface
 * on the /org/soprano/Server object.
 *
 * \section soprano_server_dbus_server_interface org.soprano.Server
 *
 * \code
 * <interface name="org.soprano.Server">
 *   <method name="createModel">
 *     <arg name="name" type="s" direction="in" />
 *     <arg name="model" type="s" direction="out" />
 *   </method>
 *   <method name="removeModel">
 *     <arg name="name" type="s" direction="in" />
 *   </method>
 *   <method name="allModels">
 *     <arg name="models" type="as" direction="out" />
 *   </method>
 * </interface>
 * \endcode
 *
 * The org.soprano.Server interface provides two main methods to create and remove %Soprano models:
 *
 * <b>org.soprano.Server.createModel</b>
 *
 * The createModel method only takes a single argument: the model's unique name which identifies the model. The
 * method returns the path to the D-Bus object which exports the org.soprano.Model interface.
 *
 * <b>org.soprano.Server.removeModel</b>
 *
 * The removeModel method also just takes the one parameter that is the model's name. It completely removes the model
 * including the data on disk. Use with care.
 *
 *
 * \section soprano_server_dbus_model_interface org.soprano.Model
 *
 * \code
 * <interface name="org.soprano.Model">
 *   <method name="addStatement">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" direction="in" />
 *     <arg name="errorCode" type="i" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="Soprano::Statement" />
 *   </method>
 *   <method name="removeStatement">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" direction="in" />
 *     <arg name="errorCode" type="i" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="Soprano::Statement" />
 *   </method>
 *   <method name="removeAllStatements">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" direction="in" />
 *     <arg name="errorCode" type="i" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="Soprano::Statement" />
 *   </method>
 *   <method name="containsStatement">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" direction="in" />
 *     <arg name="reply" type="b" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="Soprano::Statement" />
 *   </method>
 *   <method name="containsAnyStatement">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" direction="in" />
 *     <arg name="reply" type="b" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="Soprano::Statement" />
 *   </method>
 *   <method name="listStatements">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" direction="in" />
 *     <arg name="iterator" type="s" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="Soprano::Statement" />
 *   </method>
 *   <method name="listContexts">
 *     <arg name="iterator" type="s" direction="out" />
 *   </method>
 *   <method name="statementCount">
 *     <arg name="count" type="i" direction="out" />
 *   </method>
 *   <method name="isEmpty">
 *     <arg name="reply" type="b" direction="out" />
 *   </method>
 *   <method name="executeQuery">
 *     <arg name="query" type="s" direction="in" />
 *     <arg name="queryLang" type="s" direction="in" />
 *     <arg name="iterator" type="s" direction="out" />
 *   </method>
 *   <method name="createBlankNode">
 *     <arg name="node" type="(isss)" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="Soprano::Node" />
 *   </method>
 *   <signal name="statementsAdded" />
 *   <signal name="statementsRemoved" />
 *   <signal name="statementAdded">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="Soprano::Statement" />
 *   </signal>
 *   <signal name="statementRemoved">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.In0" value="Soprano::Statement" />
 *   </signal>
 * </interface>
 * \endcode
 *
 * The org.soprano.Model interface maps the Soprano::Model API to a D-Bus interface. The only difference is that
 * instead of iterators the interface returns D-Bus object paths which provide D-Bus interfaces themselves and that
 * the executeQuery method does take two string parameters: the query itself and the query language.
 *
 * The method listContexts returns the path of a D-Bus object exporting the org.soprano.NodeIterator interface,
 * listStatements returns the path of a D-Bus object exporting the org.soprano.StatementIterator interface, and
 * executeQuery returns the path of a D-Bus object exporting the org.soprano.QueryResultIterator interface.
 *
 * The D-Bus interface to the Soprano::Model obviously needs to encode Soprano::Node instances. A Soprano::Node is encoded as follows:
 * \li The Node type as defined in Soprano::Node::Type: 0 - empty node, 1 - resource node, 2 - literal node, 3 - blank node
 * \li A string representation of the Node (the encoded URI for resource nodes, the identifier for blank nodes, and the
 *     literal value for literal nodes)
 * \li The language code (non-empty only for literal nodes)
 * \li The encoded datatype URI (non-empty only for literal nodes)
 *
 *
 * \section soprano_server_dbus_node_iterator_interface org.soprano.NodeIterator
 *
 * \code
 * <interface name="org.soprano.NodeIterator">
 *   <method name="next">
 *     <arg name="reply" type="b" direction="out" />
 *   </method>
 *   <method name="current">
 *     <arg name="node" type="(isss)" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="Soprano::Node" />
 *   </method>
 *   <method name="close" />
 * </interface>
 * \endcode
 *
 * The node iterator interface maps very closely to the API of Soprano::NodeIterator.
 *
 *
 * \section soprano_server_dbus_statement_iterator_interface org.soprano.StatementIterator
 *
 * \code
 * <interface name="org.soprano.StatementIterator">
 *   <method name="next">
 *     <arg name="reply" type="b" direction="out" />
 *   </method>
 *   <method name="current">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="Soprano::Statement" />
 *   </method>
 *   <method name="close" />
 * </interface>
 * \endcode
 *
 * The statement iterator interface maps very closely to the API of Soprano::StatementIterator.
 *
 *
 * \section soprano_server_dbus_queryresult_iterator_interface org.soprano.QueryResultIterator
 *
 * \code
 * <interface name="org.soprano.QueryResultIterator">
 *   <method name="next">
 *     <arg name="reply" type="b" direction="out" />
 *   </method>
 *   <method name="current">
 *     <arg name="node" type="a{s(isss)}" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="Soprano::BindingSet" />
 *   </method>
 *   <method name="close" />
 *   <method name="currentStatement">
 *     <arg name="statement" type="((isss)(isss)(isss)(isss))" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="Soprano::Statement" />
 *   </method>
 *   <method name="bindingByName">
 *     <arg name="name" type="s" direction="in" />
 *     <arg name="node" type="(isss)" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="Soprano::Node" />
 *   </method>
 *   <method name="bindingByIndex">
 *     <arg name="index" type="i" direction="in" />
 *     <arg name="node" type="(isss)" direction="out" />
 *     <annotation name="com.trolltech.QtDBus.QtTypeName.Out0" value="Soprano::Node" />
 *   </method>
 *   <method name="bindingCount">
 *     <arg name="names" type="i" direction="out" />
 *   </method>
 *   <method name="bindingNames">
 *     <arg name="names" type="as" direction="out" />
 *   </method>
 *   <method name="boolValue">
 *     <arg name="reply" type="b" direction="out" />
 *   </method>
 *   <method name="isGraph">
 *     <arg name="reply" type="b" direction="out" />
 *   </method>
 *   <method name="isBinding">
 *     <arg name="reply" type="b" direction="out" />
 *   </method>
 *   <method name="isBool">
 *     <arg name="reply" type="b" direction="out" />
 *   </method>
 * </interface>
 * \endcode
 *
 * The query result iterator interface maps closely to the Soprano::QueryResultIterator API except that
 * it does not use method overloading (compare bindingByName and bindingByIndex).
 */

/**
 * \page soprano_server_protocol Soprano Server Protocol
 *
 * \warning The protocol described on this page is used internally by the Soprano TCP and local socket server and client.
 * Normally there is no need to deal with it except if you want to write a client or server in another
 * programming language.
 *
 * The server protocol is quite simple and is based on a set of commands and binary serializations for
 * data types. It has been optimized for speed and nothing else so it always tries to comunicate as
 * little data as possible.
 *
 * \section soprano_server_protocol_commands Commands
 *
 * Commands are identified by unsigned 16bit integer values (native bit order). Issuing a command
 * is done by sending the command number followed by the command parameters.
 *
 * The following table lists the available commands.
 *
 * <table>
 * <tr><th>Command</th><th>Code</th><th>Parameters</th><th>Return values</th><th>Description</th></tr>
 * <tr><td>Create model</td><td>0x1</td><td>name (string), settings (List of #Soprano::BackendSetting)</td><td>model ID (unsigned 32bit int)</td><td>Retrieve the ID for a model (if the model does not yet exist, it is craeted.</td></tr>
 * <tr><td>FIXME...</td></tr>
 * </table>
 *
 * \section soprano_server_protocol_types Types
 *
 * The default implementation of the protocol uses QDataStream. Thus, all basic types are encoded as QDataStream does it.
 *
 * \subsection soprano_server_protocol_types_node Soprano::Node
 *
 * A %Soprano node starts with the node type encoded as unsigned 8bit. For the possible values see Soprano::Node::Type.
 * If it is a literal node (Soprano::Node::LiteralNode) after the type follow the literal value (Soprano::LiteralValue)
 * and the language (string). If it is a resource (Soprano::Node::ResourceNode) or blank node (Soprano::Node::BlankNode)
 * after the type follows the URI of the node (URI). If it is an empty node, nothing follows the type.
 *
 * \subsection soprano_server_protocol_types_statement Soprano::Statement
 *
 * A %Soprano statement is encoded simply by encoding the subject, predicate, object, and context node in that order.
 *
 * \subsection soprano_server_protocol_types_literalvalue Soprano::LiteralValue
 *
 * A %Soprano literal value is encoded as a QVariant: The type of the data (unsigned 32bit) followed
 * by a null flag (8bit) and the data of the specified type.
 *
 * \subsection soprano_server_protocol_types_bindingset Soprano::BindingSet
 *
 * FIXME...
 */


/**
 * \namespace Soprano::Client
 *
 * The Client module provides classes to connect to remote RDF sources, most important the %Soprano Server which
 * can be connected via DBus, a local socket, or TCP (see below).
 * Apart from the %Soprano %Server, arbitrary SPARQL Http services can be connected via SparqlModel.
 *
 * \section soprano_server_client_details Overview of the Soprano Server clients
 *
 * The %Soprano Server clients have the following restrictions:
 *
 * <b>TCP %Client:</b> (TcpClient)
 * \li No signals are emitted (Model::statementsAdded() and Model::statementsRemoved())
 * \li No permission handling, i.e. each process running on the machine can access a running %Soprano server,
 *     indifferent of the user id of the server process.
 * <!--\li Queries are always transmitted as strings and thus, might be serialized on the client side and parsed
 *     again on the server side when using Model::executeQuery( const Query& ) const.-->
 *
 * <b>Local Socket %Client:</b> (LocalSocketClient)
 * \li No signals are emitted (Model::statementsAdded() and Model::statementsRemoved())
 * <!--\li Queries are always transmitted as strings and thus, might be serialized on the client side and parsed
 *     again on the server side when using Model::executeQuery( const Query& ) const.-->
 *
 * <b>DBus %Client:</b> (DBusClient)
 * \li No restrictions
 * <!--\li Queries are always transmitted as strings and thus, might be serialized on the client side and parsed
 *     again on the server side when using Model::executeQuery( const Query& ) const.-->
 *
 * While the local socket comunication is the fastest due to its missing signal handling it can be sub-optimal at times.
 * The best solution at the moment is the DBus client. Although being the slowest (slightly slower than
 * the local Socket client) it is reliable and feature-complete (signals are transmitted). However, it is also possible
 * to combine both: use the local socket communication for fast commands and create a D-Bus connection only for the
 * signals.
 *
 * \sa \ref Soprano::Server, \ref soprano_server_dbus
 */
