# Isolating tracker-store clients

Every user of tracker_sparql_connection_get() or tracker_sparql_connection_get_async() relies on an external tracker-store instance to maintain the database, and possibly on additional tracker miners to write the data consumed by the application.

Traditionally there has been only a single instance of tracker-store and miners, shared by all consumers of Tracker data. With Tracker 2.0 it became possible to let clients spawn their own sets of these services.

## Defining a private domain ontology

In order to make Tracker aware of this private setup, a domain ontology rule must be dropped by the application on $(datadir)/tracker/domain-ontologies/, the file name will be usually the DBus name or application ID of the client prepended by ".rule", eg. org.example.App.rule

The following example would allow org.example.App to set up a private set of services to index the filesystem.

    [DomainOntology]
    # All locations accept
    # 1) Paths relative from a variable, the variables
    #    may be: HOME, XDG_CACHE_HOME, XDG_DATA_HOME, XDG_RUNTIME_DIR,
    #    XDG_DESKTOP_DIR, XDG_DOCUMENTS_DIR, XDG_DOWNLOAD_DIR,
    #    XDG_MUSIC_DIR, XDG_PICTURES_DIR, XDG_PUBLICSHARE_DIR,
    #    XDG_VIDEOS_DIR.
    #
    #    eg. $XDG_CACHE_HOME/...
    #
    # 2) URIs
    #
    #    eg. file:///var/...
    #

    # Location for the Tracker database (not optional)
    CacheLocation=$XDG_CACHE_HOME/example-app

    # Location for the data journal, used in data recovery
    # situations (optional)
    JournalLocation=$XDG_DATA_HOME/example-app/journal

    # Name of the ontology to use, must be one located in
    # $(sharedir)/tracker/ontologies
    OntologyName=nepomuk

    # DBus name for the owner (not optional). Tracker will use
    # the domain as the prefix of the DBus name for all the
    # services related to this domain ontology.
    #
    # eg. org.gnome.Photos
    Domain=org.example.App

    # Miners that the domain ontology will require. This is
    # purely a hint (mainly for libtracker-control), and not
    # any sort of white list. Anything else knowing about this
    # domain ontology may still perform updates, miners and
    # non-miners.
    Miners=Miner.Files;Miner.Extract;

The client could then instruct Tracker libraries to use this private set up through the following call:

    tracker_sparql_connection_set_domain ("org.example.App");

It is also possible to pass a full path to the domain rule. If the first character of the domain name is / it will be treated as a full path.

## Additional precautions and recommendations

In order to work flawlessly with the created services, the client must adopt some precautions that were optional in the past, but now have become mandatory.

## Use TrackerNotifier to receive notifications

Listening directly to the GraphUpdated DBus signal will yield the wrong results, since it relies on the DBus name adopted by the default tracker-store service.

## Use TrackerMinerManager to ensure services are started

The miner lifetime has been traditionally unclear, being those usually deemed a system service that would usually be there. When using private services that assumption can't hold true, so the client is responsible for ensuring those services are started.

Note that this is the recommended behavior anyway even if the client were not to use private services.