Into

Modules

Documentation

classPiiResourceDatabase

#include <PiiResourceDatabase.h>

A database that stores statements about resources.

Description

PiiResourceDatabase is based upon the idea of making statements about resources in the form of subject-predicate-object expressions, just like in RDF (http://www.w3.org/RDF/). These expressions are known as triples in RDF terminology, and the term is adopted here as well. The subject denotes the resource, and the predicate denotes traits or aspects of the resource and expresses a relationship between the subject and the object. For example, one way to represent the notion "This class was created at Intopii" in RDF is as a triple: a subject denoting "PiiResourceDatabase", a predicate denoting "creator", and an object denoting "Intopii". The shorthand form for such a triplet could be something like (PiiResourceDatabase,creator,"Intopii").

Unlike W3C's RDF, PiiResourceDatabase does not require that resources and predicates are identified by URIs. Any string containing no white spaces will work as long as it is unique in the context of the database. In particular, class names are excellent resource identifiers for already being unique due to symbol naming restrictions. For predicates, namespaces may be used if needed. An example of a statement with a namespace could be (PiiResourceDatabase,my:opinion,"Confusing"), which states that "In my opinion, PiiResourceDatabase is confusing." The "my:" namespace avoids polluting the global namespace with my custom predicates.

Instances of PiiResourceStatement are used to store the triples in PiiResourceDatabase. The object of each triple may be either a reference to another resource or a string literal. In the examples above, double quotes were used to illustrate that the object was a literal. But a triplet can describe a relationship between two resources, for example that "PiiResourceDatabase uses PiiResourceStatement": (PiiResourceDatabase,uses,PiiResourceStatement).

Statements in PiiResourceDatabase are also resources, and they have automatically assigned ids. Therefore, it is possible to reify statements in RDF style. In RDF terminology, reification means staments about statements. Resource ids of the form "#123" (a hash followed by an integer) are reserved for statements.

Constructors and destructor

PiiResourceDatabase
( )
~PiiResourceDatabase
( )

Public member functions

int
addStatement
( )

Add a statement to the database.

int
addStatement
(
  • const char * subject
  • const char * predicate
  • const char * object
  • PiiResourceStatement::Type type = PiiResourceStatement::LiteralType
)

Add a statement to the database.

int
addStatement
( )
int
addStatement
( )

Add a statement to the database.

QList< int >
addStatements
( )

A statements to the database.

void
dump
( )

Dump all statements in the database to debug output.

template<class Filter>
int
findFirst
(
  • Filter filter
)

Returns the id of the first statement matching filter.

void
removeStatement
(
  • int id
)

Remove the statement with the given id.

void
removeStatements
(
  • const QList< int > & ids
)

Remove all statements whose id is in the given list.

template<class Selector, class Filter>
QList< typename Selector::ValueType >
select
(
  • Selector selector
  • Filter filter
)

Returns a list of subjects, predicates, or objects whose containing statement matches filter.

template<class Filter>
QList< PiiResourceStatement >
select
(
  • Filter filter
)

Returns a list of statements matching the given filter.

int
statementCount
( )

Returns the number of stored statements.

QList< PiiResourceStatement >
statements
( )

Returns all stored statements as a list.

Function details

  • PiiResourceDatabase

    ()

  • ~PiiResourceDatabase

    ()

  • int addStatement

    ( )

    Add a statement to the database.

    Returns the id of the statement.

  • int addStatement

    (
    • const char * subject
    • const char * predicate
    • const char * object
    • PiiResourceStatement::Type type = PiiResourceStatement::LiteralType
    )

    Add a statement to the database.

    Returns the id of the statement. 

     PiiResourceDatabase db;
 db.addStatement("PiiResourceDatabase", "creator", "Intopii", PiiResourceStatement::LiteralType);

  • int addStatement

    ( )

    This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

  • int addStatement

    ( )

    Add a statement to the database.

    This function takes a statement id as the subject, and can be used in reifying statements. 

     // I think statement #123 is vague
 db.addStatement(123, "my:evaluation", "bullshit");
    Returns

    the id of the new statement

  • QList< int > addStatements

    ( )

    A statements to the database.

    This function adds the given statements to the database, starting from the first one. If the subject of a statement is "#", the statement is treated as a reification of the previous statement (a statement about statement). The subject ("#") will be replaced with the resource id of the previous statement. Note that all successive reifications refer to the same (non-reified) statement. 

     PiiResourceDatabase db;
 // In my opinion, PiiResourceDatabase is flexible
 // The truth value of the previous statement is true.
 db.addStatements(QList<PiiResourceStatement>() <<
                  PiiResourceStatement("PiiResourceDatabase", "my:opinion", "flexible") <<
                  PiiResourceStatement("#", "my:truth value", "true"));

  • void dump

    ()

    Dump all statements in the database to debug output.

  • template<class Filter>

    int findFirst

    (
    • Filter filter
    )

    Returns the id of the first statement matching filter.

    If no statement matches, -1 will be returned.

  • void removeStatement

    (
    • int id
    )

    Remove the statement with the given id.

  • void removeStatements

    (
    • const QList< int > & ids
    )

    Remove all statements whose id is in the given list.

  • template<class Selector, class Filter>

    QList< typename Selector::ValueType > select

    (
    • Selector selector
    • Filter filter
    )

    Returns a list of subjects, predicates, or objects whose containing statement matches filter.

    A selector is a function object that picks one field of a statement. The type of the returned list depends on the return value of the selector. Supported selectors are:

    • subject - the subject of a statement, QString

    • predicate - the predicate of a statement, QString

    • object - the object of a statement, QString

    • attribute("name") - named attribute of a statement, QString. The attribute selector is equal to a logical AND filter that first matches the predicate to name and then compares the object.

    • statementId - the id of a statement, int.

    • resourceType - the type of the object, PiiResourceStatement::Type. 

     QList<QString> lstResult;
 // Find all child resources of PiiImagePlugin
 lstResult = db->select(Pii::subject, Pii::attribute("pii:parent") == "PiiImagePlugin");
 // Find all cool resources
 lstResult = db->select(Pii::subject, Pii::attribute("my:evaluation") == "cool");
 // Find all cool operations
 lstResult = db->select(Pii::subject, Pii::attribute("my:evaluation") == "cool") &&
             db->select(Pii::subject, Pii::attribute("pii:class") == "PiiOperation");
 // Get the names of all attributes attached to MyOperation
 lstResult = db->select(Pii::predicate, Pii::subject == "MyOperation");
 // Find cool superclasses
 lstResult = db->select(Pii::object, Pii::predicate == "pii:class") &&
             db->select(Pii::subject, Pii::attribute("my:evaluation") == "cool");
 // List all operations not in MyPlugin.
 // Note that this query will only consider operations that have
 // the pii:class attribute; the attribute() selector discards all
 // statements that do not have the specified attribute name as
 // the predicate.
 lstResult = db->select(Pii::subject, Pii::attribute("pii:parent") != "MyPlugin") &&
             db->select(Pii::subject, Pii::attribute("pii:class") == "PiiOperation");

    Filters support all comparison operators and the logical AND and OR operators. In addition, there are two fuctions to convert the QString output of a selector to a number:

    • resourceStringTo<T>() - converts a string argument to a numeric type denoted by T. Returns 0 if the string cannot be converted. If the conversion fails, any subsequent comparison will fail. That is, resourceStringTo<int>("abc") == 0 will be false even though the function will return 0.

    • resourceidToInt() - converts a resource id of the form #123 to an integer. If the input string is not an id of a statement, -1 will be returned, and any subsequent comparison will return false. 

     using namespace Pii;
 // Find the names of relations between MyClass and YourClass
 db->select(predicate, subject == "MyClass" && object == "YourClass");
 // Find all resources whose my:score is more than 5 or whose
 // your:score is at least 0.5.
 db->select(subject,
            resourceStringTo<int>(attribute("my:score")) > 5 ||
            resourceStringTo<double>(attribute("your:score")) >= 0.5);
 // Find the objects of all statements whose object is a literal,
 // but neither "Foo" nor "Bar" if the predicate is "my:name".
 db->select(subject,
            !(attribute("my:name") == "Foo" ||
              attribute("my:name") == "Bar") &&
              resourceType == PiiResourceStatement::LiteralType);
 // Find the ids of reified statements as integers.
 QList<int> = db->select(resourceIdToInt(subject),
                         resourceIdToInt(subject) != -1);
 // Find the ids of the reification statements.
 QList<int> = db->select(statementId,
                         resourceIdToInt(subject) != -1);
  • template<class Filter>

    QList< PiiResourceStatement > select

    (
    • Filter filter
    )

    Returns a list of statements matching the given filter. 

     QList<PiiResourceStatement> lstResult;
 // Fetch all statements that specify a parent-child relationship
 lstResult = db->select(Pii::predicate == "pii:parent");
 // Fetch all statements about MyOperation
 lstResult = db->select(Pii::subject == "MyOperation");
 // Fetch all literal statements about MyOperation
 lstResult = db->select(Pii::subject == "MyOperation");
 // Fetch all statements in which MyOperation is either the subject or the object
 lstResult = db->select(Pii::subject == "MyOperation" || Pii::object == "MyOperation);
 // Get all statements that specify child resources of MyPlugin
 lstResult = db->select(Pii::predicate == "pii:parent" && Pii::object == "MyPlugin");
 // Same, but shorter
 lstResult = db->select(Pii::attribute("pii:parent") == "MyPlugin");

    In the examples, Pii::subject, Pii::predicate etc. are global instances of selector structures Pii::Subject, Pii::Predicate etc. One can equally well use Pii::Subject(), Pii::Predicate() etc. in their place.

  • int statementCount

    ()

    Returns the number of stored statements.

  • QList< PiiResourceStatement > statements

    ()

    Returns all stored statements as a list.

Notes (0)

Add a note

Not a single note added yet. Be the first, add yours.