client_inc.cc 9.2 KB
Newer Older
1
2
3
4
5
namespace {

const char* const DataSourceClient_doc = "\
The base class of data source clients.\n\
\n\
Jelte Jansen's avatar
Jelte Jansen committed
6
7
8
9
This is the python wrapper for the abstract base class that defines\n\
the common interface for various types of data source clients. A data\n\
source client is a top level access point to a data source, allowing \n\
various operations on the data source such as lookups, traversing or \n\
10
11
12
13
14
15
16
17
18
19
20
21
22
23
updates.\n\
This class serves as both the factory and the main interface to those \n\
classes.\n\
\n\
The constructor takes two arguments; a type (string), and\n\
configuration data for a datasource client of that type. The configuration\n\
data is currently passed as a JSON in string form, and its contents depend\n\
on the type of datasource from the first argument. For instance, a\n\
datasource of type \"sqlite3\" takes the config \n\
{ \"database_file\": \"/var/example.org\" }\n\
We may in the future add support for passing configuration data,\n\
but right now we limit it to a JSON-formatted string\n\
\n\
The client class itself has limited focus and delegates \n\
Jelte Jansen's avatar
Jelte Jansen committed
24
25
the responsibility for these specific operations to other (c++) classes;\n\
in general methods of this class act as factories of these other classes.\n\
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
\n\
- InMemoryClient: A client of a conceptual data source that stores all\n\
  necessary data in memory for faster lookups\n\
- DatabaseClient: A client that uses a real database backend (such as\n\
  an SQL database). It would internally hold a connection to the\n\
  underlying database system.\n\
\n\
It is intentional that while the term these derived classes don't\n\
contain \"DataSource\" unlike their base class. It's also noteworthy\n\
that the naming of the base class is somewhat redundant because the\n\
namespace datasrc would indicate that it's related to a data source.\n\
The redundant naming comes from the observation that namespaces are\n\
often omitted with using directives, in which case \"Client\" would be\n\
too generic. On the other hand, concrete derived classes are generally\n\
not expected to be referenced directly from other modules and\n\
applications, so we'll give them more concise names such as\n\
InMemoryClient. A single DataSourceClient object is expected to handle\n\
only a single RR class even if the underlying data source contains\n\
records for multiple RR classes. Likewise, (when we support views) a\n\
DataSourceClient object is expected to handle only a single view.\n\
\n\
If the application uses multiple threads, each thread will need to\n\
create and use a separate DataSourceClient. This is because some\n\
database backend doesn't allow multiple threads to share the same\n\
connection to the database.\n\
\n\
For a client using an in memory backend, this may result in having a\n\
multiple copies of the same data in memory, increasing the memory\n\
footprint substantially. Depending on how to support multiple CPU\n\
cores for concurrent lookups on the same single data source (which is\n\
not fully fixed yet, and for which multiple threads may be used), this\n\
design may have to be revisited. This class (and therefore its derived\n\
classes) are not copyable. This is because the derived classes would\n\
generally contain attributes that are not easy to copy (such as a\n\
large size of in memory data or a network connection to a database\n\
server). In order to avoid a surprising disruption with a naive copy\n\
it's prohibited explicitly. For the expected usage of the client\n\
classes the restriction should be acceptable.\n\
\n\
Jelte Jansen's avatar
Jelte Jansen committed
65
Todo: This class is still not complete. It will need more factory\n\
66
67
68
69
methods, e.g. for (re)loading a zone.\n\
";

const char* const DataSourceClient_findZone_doc = "\
Jelte Jansen's avatar
Jelte Jansen committed
70
find_zone(name) -> (code, ZoneFinder)\n\
71
72
73
\n\
Returns a ZoneFinder for a zone that best matches the given name.\n\
\n\
Jelte Jansen's avatar
Jelte Jansen committed
74
75
76
code: The result code of the operation (integer).\n\
- DataSourceClient.SUCCESS: A zone that gives an exact match is found\n\
- DataSourceClient.PARTIALMATCH: A zone whose origin is a super domain of name\n\
77
  is found (but there is no exact match)\n\
Jelte Jansen's avatar
Jelte Jansen committed
78
79
80
- DataSourceClient.NOTFOUND: For all other cases.\n\
ZoneFinder: ZoneFinder object for the found zone if one is found;\n\
otherwise None.\n\
81
\n\
Jelte Jansen's avatar
Jelte Jansen committed
82
Any internal error will be raised as an isc.datasrc.Error exception\n\
83
84
85
86
\n\
Parameters:\n\
  name       A domain name for which the search is performed.\n\
\n\
Jelte Jansen's avatar
Jelte Jansen committed
87
88
Return Value(s): A tuple containing a result value and a ZoneFinder object or\n\
None\n\
89
90
91
";

const char* const DataSourceClient_getIterator_doc = "\
Jelte Jansen's avatar
Jelte Jansen committed
92
get_iterator(name, adjust_ttl=True) -> ZoneIterator\n\
93
94
95
96
97
98
\n\
Returns an iterator to the given zone.\n\
\n\
This allows for traversing the whole zone. The returned object can\n\
provide the RRsets one by one.\n\
\n\
Jelte Jansen's avatar
Jelte Jansen committed
99
This throws isc.datasrc.Error when the zone does not exist in the\n\
Jelte Jansen's avatar
Jelte Jansen committed
100
datasource, or when an internal error occurs.\n\
101
\n\
Jelte Jansen's avatar
Jelte Jansen committed
102
The default implementation throws isc.datasrc.NotImplemented. This allows for\n\
103
104
105
106
107
108
109
110
111
easy and fast deployment of minimal custom data sources, where the\n\
user/implementator doesn't have to care about anything else but the\n\
actual queries. Also, in some cases, it isn't possible to traverse the\n\
zone from logic point of view (eg. dynamically generated zone data).\n\
\n\
It is not fixed if a concrete implementation of this method can throw\n\
anything else.\n\
\n\
Parameters:\n\
Jelte Jansen's avatar
Jelte Jansen committed
112
113
  isc.dns.Name The name of zone apex to be traversed. It doesn't do\n\
               nearest match as find_zone.\n\
Jelte Jansen's avatar
Jelte Jansen committed
114
115
116
117
118
  adjust_ttl   If True, the iterator will treat RRs with the same\n\
               name and type but different TTL values to be of the\n\
               same RRset, and will adjust the TTL to the lowest\n\
               value found. If false, it will consider the RR to\n\
               belong to a different RRset.\n\
119
120
121
122
123
\n\
Return Value(s): Pointer to the iterator.\n\
";

const char* const DataSourceClient_getUpdater_doc = "\
JINMEI Tatuya's avatar
JINMEI Tatuya committed
124
get_updater(name, replace, journaling=False) -> ZoneUpdater\n\
125
126
127
128
129
130
\n\
Return an updater to make updates to a specific zone.\n\
\n\
The RR class of the zone is the one that the client is expected to\n\
handle (see the detailed description of this class).\n\
\n\
131
If the specified zone is not found via the client, a None object will\n\
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
be returned; in other words a completely new zone cannot be created\n\
using an updater. It must be created beforehand (even if it's an empty\n\
placeholder) in a way specific to the underlying data source.\n\
\n\
Conceptually, the updater will trigger a separate transaction for\n\
subsequent updates to the zone within the context of the updater (the\n\
actual implementation of the \"transaction\" may vary for the specific\n\
underlying data source). Until commit() is performed on the updater,\n\
the intermediate updates won't affect the results of other methods\n\
(and the result of the object's methods created by other factory\n\
methods). Likewise, if the updater is destructed without performing\n\
commit(), the intermediate updates will be effectively canceled and\n\
will never affect other methods.\n\
\n\
If the underlying data source allows concurrent updates, this method\n\
can be called multiple times while the previously returned updater(s)\n\
are still active. In this case each updater triggers a different\n\
\"transaction\". Normally it would be for different zones for such a\n\
case as handling multiple incoming AXFR streams concurrently, but this\n\
interface does not even prohibit an attempt of getting more than one\n\
updater for the same zone, as long as the underlying data source\n\
allows such an operation (and any conflict resolution is left to the\n\
Jelte Jansen's avatar
Jelte Jansen committed
154
specific implementation).\n\
155
156
157
158
\n\
If replace is true, any existing RRs of the zone will be deleted on\n\
successful completion of updates (after commit() on the updater); if\n\
it's false, the existing RRs will be intact unless explicitly deleted\n\
Jelte Jansen's avatar
Jelte Jansen committed
159
by delete_rrset() on the updater.\n\
160
161
\n\
A data source can be \"read only\" or can prohibit partial updates. In\n\
Jelte Jansen's avatar
Jelte Jansen committed
162
such cases this method will result in an isc.datasrc.NotImplemented exception\n\
163
164
unconditionally or when replace is false).\n\
\n\
JINMEI Tatuya's avatar
JINMEI Tatuya committed
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
If journaling is True, the data source should store a journal of\n\
changes. These can be used later on by, for example, IXFR-out.\n\
However, the parameter is a hint only. It might be unable to store\n\
them and they would be silently discarded. Or it might need to store\n\
them no matter what (for example a git-based data source would store\n\
journal implicitly). When the journaling is True, it requires that the\n\
following update be formatted as IXFR transfer (SOA to be removed,\n\
bunch of RRs to be removed, SOA to be added, bunch of RRs to be added,\n\
and possibly repeated). However, it is not required that the updater\n\
checks that. If it is False, it must not require so and must accept\n\
any order of changes.\n\
\n\
We don't support erasing the whole zone (by replace being True) and\n\
saving a journal at the same time. In such situation, isc.datasrc.Error\n\
is thrown.\n\
\n\
181
Exceptions:\n\
Jelte Jansen's avatar
Jelte Jansen committed
182
183
  isc.datasrc. NotImplemented The underlying data source does not support\n\
               updates.\n\
Jelte Jansen's avatar
Jelte Jansen committed
184
  isc.datasrc.Error Internal error in the underlying data source.\n\
185
186
187
188
\n\
Parameters:\n\
  name       The zone name to be updated\n\
  replace    Whether to delete existing RRs before making updates\n\
JINMEI Tatuya's avatar
JINMEI Tatuya committed
189
  journaling The zone updater should store a journal of the changes.\n\
190
191
192
\n\
";
} // unnamed namespace