1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
<?xml version='1.0' encoding="UTF-8"?>
<part id="tracker-private-store" xmlns:xi="http://www.w3.org/2003/XInclude">
<title>Isolating tracker-store clients</title>
<partintro>
<para>
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.
</para>
<para>
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.
</para>
</partintro>
<chapter id="private-daemons">
<title>Defining a private domain ontology</title>
<para>
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
</para>
<para>
The following example would allow org.example.App to set up a private set
of services to index the filesystem.
</para>
<programlisting>
[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;
</programlisting>
<para>
The client could then instruct Tracker libraries to use
this private set up through the following call:
</para>
<programlisting>
tracker_sparql_connection_set_domain ("org.example.App");
</programlisting>
</chapter>
<chapter id="recommendations">
<title>Additional precautions and recommendations</title>
<para>
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.
</para>
<formalpara>
<title>Use TrackerNotifier to receive notifications</title>
<para>
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.
</para>
</formalpara>
<formalpara>
<title>Use TrackerMinerManager to ensure services are started</title>
<para>
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.
</para>
<para>
Note that this is the recommended behavior anyway even if the
client were not to use private services.
</para>
</formalpara>
</chapter>
</part>
|
