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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
|
<?xml version="1.0" ?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>docs/manager.rd</title>
</head>
<body>
<h2><a name="label-0" id="label-0">BDB::XML::Manager</a></h2><!-- RDLabel: "BDB::XML::Manager" -->
<p>Provides a high-level object used to manage various aspects of Berkeley
DB XML usage. You use XML::Manager to perform activities such as container
management (including creation and open), preparing XML::Query queries,
executing one-off queries, creating transaction objects,
creating update and query context objects</p>
<p>A XML::Manager object can be created with BDB::Env#manager</p>
<p>BDB::Transaction respond to the same method than BDB::XML::Manager</p>
<h3><a name="label-1" id="label-1">Class Methods</a></h3><!-- RDLabel: "Class Methods" -->
<dl>
<dt><a name="label-2" id="label-2"><code>new(<var>flags</var> = <var>0</var>)</code></a></dt><!-- RDLabel: "new" -->
<dd>
create a new Manager object that uses a private internal
database environment
<dl>
<dt><a name="label-3" id="label-3"><var>flags</var></a></dt><!-- RDLabel: "flags" -->
<dd>
flags can have the value
<dl>
<dt><a name="label-4" id="label-4">BDB::XML::ALLOW_EXTERNAL_ACCESS</a></dt><!-- RDLabel: "BDB::XML::ALLOW_EXTERNAL_ACCESS" -->
<dd>
to allow queries to access external data sources
</dd>
<dt><a name="label-5" id="label-5">BDB::XML::ALLOW_AUTO_OPEN</a></dt><!-- RDLabel: "BDB::XML::ALLOW_AUTO_OPEN" -->
<dd>
to allow queries that reference unopened containers will
automatically open those containers
</dd>
</dl>
</dd>
</dl></dd>
</dl>
<h3><a name="label-6" id="label-6">Methods</a></h3><!-- RDLabel: "Methods" -->
<dl>
<dt><a name="label-7" id="label-7"><code>create_container(<var>name</var>, <var>flags</var> = <var>0</var>, <var>type</var> = <var>XML</var>::<var>Container</var>::<var>NodeContainer</var>, <var>mode</var> = <var>0</var>)</code></a></dt><!-- RDLabel: "create_container" -->
<dd>
Creates and opens a container. If the container already exists at
the time this method is called, an exception is thrown.
<dl>
<dt><a name="label-8" id="label-8"><var>name</var></a></dt><!-- RDLabel: "name" -->
<dd>
container's name
</dd>
<dt><a name="label-9" id="label-9"><var>flags</var></a></dt><!-- RDLabel: "flags" -->
<dd>
the flags to use for this container creation.
</dd>
<dt><a name="label-10" id="label-10"><var>type</var></a></dt><!-- RDLabel: "type" -->
<dd>
the type of container to create.
</dd>
<dt><a name="label-11" id="label-11"><var>mode</var></a></dt><!-- RDLabel: "mode" -->
<dd>
mode for creation (see chmod(2))
</dd>
</dl></dd>
<dt><a name="label-12" id="label-12"><code>create_document</code></a></dt><!-- RDLabel: "create_document" -->
<dd>
create a XML::Document object</dd>
<dt><a name="label-13" id="label-13"><code>create_modify</code></a></dt><!-- RDLabel: "create_modify" -->
<dd>
create a XML::Modify object</dd>
<dt><a name="label-14" id="label-14"><code>create_query_context(<var>rt</var> = <var>XML</var>::<var>Context</var>::<var>LiveValues</var>, <var>et</var> = <var>XML</var>::<var>Context</var>::<var>Eager</var>)</code></a></dt><!-- RDLabel: "create_query_context" -->
<dd>
create a XML::Context object
<dl>
<dt><a name="label-15" id="label-15"><var>rt</var></a></dt><!-- RDLabel: "rt" -->
<dd>
specifies whether to return live (XML::Context::LiveValues)
or dead values (XML::Context::DeadValues)
</dd>
<dt><a name="label-16" id="label-16"><var>et</var></a></dt><!-- RDLabel: "et" -->
<dd>
specifies if the resultants values are derived and
stored in-memory before query evaluation is completed
(XML::Context::Eager) or if they are calculated as you ask for them
(XML::Query::Lazy)
</dd>
</dl></dd>
<dt><a name="label-17" id="label-17"><code>create_results</code></a></dt><!-- RDLabel: "create_results" -->
<dd>
create a XML::Results object</dd>
<dt><a name="label-18" id="label-18"><code>begin(<var>flags</var> = <var>0</var>)</code></a></dt><!-- RDLabel: "begin" -->
<dd>
create a new transaction
<ul>
<li><var>flags</var></li>
</ul></dd>
<dt><a name="label-19" id="label-19"><code>create_update_context</code></a></dt><!-- RDLabel: "create_update_context" -->
<dd>
create a XML::Update object</dd>
<dt><a name="label-20" id="label-20"><code>dump_container(<var>name</var>, <var>path</var>)</code></a></dt><!-- RDLabel: "dump_container" -->
<dt><a name="label-21" id="label-21"><code>dump_container(<var>name</var>, <var>io</var>, <var>to_close</var> = <var>false</var>)</code></a></dt><!-- RDLabel: "dump_container" -->
<dd>
Dumps the contents of the specified container.
<dl>
<dt><a name="label-22" id="label-22"><var>name</var></a></dt><!-- RDLabel: "name" -->
<dd>
name of the container
</dd>
<dt><a name="label-23" id="label-23"><var>path</var></a></dt><!-- RDLabel: "path" -->
<dd>
the pathname of the file where the contents will be dumped
</dd>
<dt><a name="label-24" id="label-24"><var>io</var></a></dt><!-- RDLabel: "io" -->
<dd>
object which respond to #write
</dd>
<dt><a name="label-25" id="label-25"><var>to_close</var></a></dt><!-- RDLabel: "to_close" -->
<dd>
if an IO object was given, specify if this object
must be closed at the end.
</dd>
</dl></dd>
<dt><a name="label-26" id="label-26"><code>env</code></a></dt><!-- RDLabel: "env" -->
<dd>
Returns the underlying environnement</dd>
<dt><a name="label-27" id="label-27"><code>home</code></a></dt><!-- RDLabel: "home" -->
<dd>
Returns the home directory for the underlying database environment</dd>
<dt><a name="label-28" id="label-28"><code>load_container(<var>name</var>, <var>path</var>, <var>update</var> = <var>nil</var>)</code></a></dt><!-- RDLabel: "load_container" -->
<dt><a name="label-29" id="label-29"><code>load_container(<var>name</var>, <var>io</var>, <var>to_close</var> = <var>false</var>, <var>update</var> = <var>nil</var>)</code></a></dt><!-- RDLabel: "load_container" -->
<dd>
Loads data from the specified path (or io) into the container.
<dl>
<dt><a name="label-30" id="label-30"><var>name</var></a></dt><!-- RDLabel: "name" -->
<dd>
name of the container to load.
</dd>
<dt><a name="label-31" id="label-31"><var>path</var></a></dt><!-- RDLabel: "path" -->
<dd>
the pathname of the file which contains the data.
</dd>
<dt><a name="label-32" id="label-32"><var>io</var></a></dt><!-- RDLabel: "io" -->
<dd>
an object which respond to #read
</dd>
<dt><a name="label-33" id="label-33"><var>update</var></a></dt><!-- RDLabel: "update" -->
<dd>
an optional update context
</dd>
</dl></dd>
<dt><a name="label-34" id="label-34"><code>open_container(<var>name</var>, <var>flags</var> = <var>0</var>)</code></a></dt><!-- RDLabel: "open_container" -->
<dd>
Opens a container and return an XML::Container object
<dl>
<dt><a name="label-35" id="label-35"><var>name</var></a></dt><!-- RDLabel: "name" -->
<dd>
the container's name
</dd>
<dt><a name="label-36" id="label-36"><var>flags</var></a></dt><!-- RDLabel: "flags" -->
<dd>
the flags to use for this container open. Specify
BDB::CREATE to create and open a new container.
</dd>
</dl></dd>
<dt><a name="label-37" id="label-37"><code>prepare(<var>query</var>, <var>context</var> = <var>nil</var>)</code></a></dt><!-- RDLabel: "prepare" -->
<dd>
<p>Compile a Query expression and return a new XML::Query object.</p>
<p>You can then use XML::Query#execute</p>
<dl>
<dt><a name="label-38" id="label-38"><var>query</var></a></dt><!-- RDLabel: "query" -->
<dd>
the query to compile
</dd>
<dt><a name="label-39" id="label-39"><var>context</var></a></dt><!-- RDLabel: "context" -->
<dd>
an optional query context
</dd>
</dl></dd>
<dt><a name="label-40" id="label-40"><code>query(<var>query</var>, <var>context</var> = <var>nil</var>) [{<var>res</var>| ... }</code></a></dt><!-- RDLabel: "query" -->
<dd>
<p>Execute a query. If a block is given it will call Xml::Results#each for
the results, or it will return an Xml::Results object</p>
<p>This is equivalent to call XML::Manager#prepare and then
XML::Query#execute</p>
<dl>
<dt><a name="label-41" id="label-41"><var>query</var></a></dt><!-- RDLabel: "query" -->
<dd>
the query to compile
</dd>
<dt><a name="label-42" id="label-42"><var>context</var></a></dt><!-- RDLabel: "context" -->
<dd>
an optional query context
</dd>
</dl></dd>
<dt><a name="label-43" id="label-43"><code>resolver = <var>object</var></code></a></dt><!-- RDLabel: "resolver = object" -->
<dd>
<p>Register a resolver</p>
<p>A resolver is an object which can respond to #resolve_collection,
#resolve_document, #resolve_entity, #resolve_schema, #resolve_module
or #resolve_module_location</p>
<p>These methods (if implemented) must return <var>nil</var> if they can't resolve</p>
<p>def resolve_collection(txn_or_manager, uri)</p>
<pre>Xml::Results.new</pre>
<p>end</p>
<p>def resolve_document(txn_or_manager, uri)</p>
<pre>Xml::Value.new</pre>
<p>end</p>
<p>def resolve_entity(txn_or_manager, system_id, public_id)</p>
<pre>'an object which respond to #read'</pre>
<p>end</p>
<p>def resolve_schema(txn_or_manager, schema_location, namespace)</p>
<pre>'an object which respond to #read'</pre>
<p>end</p>
<p>def resolve_module(txn_or_manager, module_location, namespace)</p>
<pre>'an object which respond to #read'</pre>
<p>end</p>
<p>def resolve_module_location(txn_or_manager, namespace)</p>
<pre>Xml::Results.new</pre>
<p>end</p></dd>
<dt><a name="label-44" id="label-44"><code>remove_container(<var>name</var>)</code></a></dt><!-- RDLabel: "remove_container" -->
<dd>
Remove a container
<dl>
<dt><a name="label-45" id="label-45"><var>name</var></a></dt><!-- RDLabel: "name" -->
<dd>
the name of the container to be removed. The container
must be closed
</dd>
</dl></dd>
<dt><a name="label-46" id="label-46"><code>rename_container(<var>old_name</var>, <var>new_name</var>)</code></a></dt><!-- RDLabel: "rename_container" -->
<dd>
Rename a container
<dl>
<dt><a name="label-47" id="label-47"><var>old_name</var></a></dt><!-- RDLabel: "old_name" -->
<dd>
the name of the container to be renamed.
The container must be closed and must have been opened at least once
</dd>
<dt><a name="label-48" id="label-48"><var>new_name</var></a></dt><!-- RDLabel: "new_name" -->
<dd>
its new name
</dd>
</dl></dd>
<dt><a name="label-49" id="label-49"><code>container_flags</code></a></dt><!-- RDLabel: "container_flags" -->
<dd>
Return the default container flags</dd>
<dt><a name="label-50" id="label-50"><code>container_flags = <var>flags</var></code></a></dt><!-- RDLabel: "container_flags = flags" -->
<dd>
Set the default container flags for new XML::Container</dd>
<dt><a name="label-51" id="label-51"><code>container_type</code></a></dt><!-- RDLabel: "container_type" -->
<dd>
Return the default container type</dd>
<dt><a name="label-52" id="label-52"><code>container_type = <var>type</var></code></a></dt><!-- RDLabel: "container_type = type" -->
<dd>
Set the default container type for new XML::Container</dd>
<dt><a name="label-53" id="label-53"><code>container_version(<var>file</var>)</code></a></dt><!-- RDLabel: "container_version" -->
<dd>
Examines the named <var>file</var>, and if it is a container, returns a non-zero
database format version. If the <var>file</var> does not exist, or is not a container,
zero is returned.</dd>
<dt><a name="label-54" id="label-54"><code>create_index_lookup(<var>container</var>, <var>uri</var>, <var>name</var>, <var>index</var>, <var>value</var> = <var>nil</var>, <var>op</var> = <var>XML</var>::<var>IndexLookup</var>::<var>EQ</var>)</code></a></dt><!-- RDLabel: "create_index_lookup" -->
<dd>
Instantiates an new XML::IndexLookup object for performing index lookup
operations. Only a single index may be specified, and substring indexes
are not supported.
<dl>
<dt><a name="label-55" id="label-55"><var>container</var></a></dt><!-- RDLabel: "container" -->
<dd>
The target container for the lookup operation
</dd>
<dt><a name="label-56" id="label-56"><var>uri</var></a></dt><!-- RDLabel: "uri" -->
<dd>
The namespace of the node to be used. The default namespace is selected
by passing an empty string for the namespace.
</dd>
<dt><a name="label-57" id="label-57"><var>name</var></a></dt><!-- RDLabel: "name" -->
<dd>
The name of the element or attribute node to be used.
</dd>
<dt><a name="label-58" id="label-58"><var>index</var></a></dt><!-- RDLabel: "index" -->
<dd>
A comma-separated list of strings that represent the indexing strategy.
</dd>
<dt><a name="label-59" id="label-59"><var>value</var></a></dt><!-- RDLabel: "value" -->
<dd>
The value to be used as the single value for an equality or inequality
lookup, or as the lower bound of a range lookup.
</dd>
<dt><a name="label-60" id="label-60"><var>op</var></a></dt><!-- RDLabel: "op" -->
<dd>
Selects the operation to be performed. Must be one of:
XML::IndexLookup::NONE, XML::IndexLookup::EQ, XML::IndexLookup::GT,
XML::IndexLookup::GTE, XML::IndexLookup::LT, XML::IndexLookup::LTE .
</dd>
</dl></dd>
<dt><a name="label-61" id="label-61"><code>pagesize</code></a></dt><!-- RDLabel: "pagesize" -->
<dd>
Return the current page size value</dd>
<dt><a name="label-62" id="label-62"><code>pagesize = <var>size</var></code></a></dt><!-- RDLabel: "pagesize = size" -->
<dd>
Set the current page size value</dd>
<dt><a name="label-63" id="label-63"><code>reindex_container(<var>name</var>, <var>context</var> = <var>nil</var>, <var>flags</var> = <var>0</var>)</code></a></dt><!-- RDLabel: "reindex_container" -->
<dd>
<p>Reindex an entire container. The container should be backed up prior to using
this method, as it destroys existing indexes before reindexing. If the operation
fails, and your container is not backed up, you may lose information.</p>
<p>Use this call to change the type of indexing used for a container between
document-level indexes and node-level indexes. This method can take a very
long time to execute, depending on the size of the container, and should
not be used casually.</p>
<dl>
<dt><a name="label-64" id="label-64"><var>name</var></a></dt><!-- RDLabel: "name" -->
<dd>
The path to the container to be reindexed.
</dd>
<dt><a name="label-65" id="label-65"><var>context</var></a></dt><!-- RDLabel: "context" -->
<dd>
The update context to use for the reindex operation.
</dd>
<dt><a name="label-66" id="label-66"><var>flags</var></a></dt><!-- RDLabel: "flags" -->
<dd>
Use XML::INDEX_NODES in order to index the container at
the node level; otherwise, it will be indexed at the document level.
</dd>
</dl></dd>
<dt><a name="label-67" id="label-67"><code>sequence_increment = <var>increment</var></code></a></dt><!-- RDLabel: "sequence_increment = increment" -->
<dd>
Sets the integer <var>increment</var> to be used when pre-allocating document ids
for new documents created by XML::Container::put</dd>
<dt><a name="label-68" id="label-68"><code>sequence_increment</code></a></dt><!-- RDLabel: "sequence_increment" -->
<dd>
Retrieve the integer increment.</dd>
<dt><a name="label-69" id="label-69"><code>update_container(<var>name</var>, <var>context</var> = <var>nil</var>)</code></a></dt><!-- RDLabel: "update_container" -->
<dd>
Upgrades the container from a previous version of Berkeley DB XML
<dl>
<dt><a name="label-70" id="label-70"><var>name</var></a></dt><!-- RDLabel: "name" -->
<dd>
name of the container to be upgraded
</dd>
<dt><a name="label-71" id="label-71"><var>context</var></a></dt><!-- RDLabel: "context" -->
<dd>
an optional update context
</dd>
</dl></dd>
<dt><a name="label-72" id="label-72"><code>verify_container(<var>name</var>, <var>flags</var> = <var>0</var>)</code></a></dt><!-- RDLabel: "verify_container" -->
<dt><a name="label-73" id="label-73"><code>verify_container(<var>name</var>, <var>path</var>, <var>flags</var> = <var>BDB</var>::<var>SALVAGE</var>)</code></a></dt><!-- RDLabel: "verify_container" -->
<dt><a name="label-74" id="label-74"><code>verify_container(<var>name</var>, <var>io</var>, <var>to_close</var> = <var>false</var>, <var>flags</var> = <var>BDB</var>::<var>SALVAGE</var>)</code></a></dt><!-- RDLabel: "verify_container" -->
<dd>
Checks that the container data files are not corrupt, and optionally
writes the salvaged container data to the specified pathname.
<dl>
<dt><a name="label-75" id="label-75"><var>name</var></a></dt><!-- RDLabel: "name" -->
<dd>
name of the container
</dd>
<dt><a name="label-76" id="label-76"><var>path</var></a></dt><!-- RDLabel: "path" -->
<dd>
name of the file where the container will be
dumped if BDB::SALVAGE is set.
</dd>
<dt><a name="label-77" id="label-77"><var>io</var></a></dt><!-- RDLabel: "io" -->
<dd>
an object which respond to #write if BDB::SALVAGE is set
</dd>
<dt><a name="label-78" id="label-78"><var>to_close</var></a></dt><!-- RDLabel: "to_close" -->
<dd>
if true the io will be closed at end.
</dd>
<dt><a name="label-79" id="label-79"><var>flags</var></a></dt><!-- RDLabel: "flags" -->
<dd>
can have the value BDB::SALVAGE, BDB::AGGRESSIVE
</dd>
</dl></dd>
<dt><a name="label-80" id="label-80"><code>flags</code></a></dt><!-- RDLabel: "flags" -->
<dd>
Get the flags used to open the manager.</dd>
<dt><a name="label-81" id="label-81"><code>implicit_timezone</code></a></dt><!-- RDLabel: "implicit_timezone" -->
<dd>
Get the implicit timezone used for queries</dd>
<dt><a name="label-82" id="label-82"><code>implicit_timezone=(<var>tz</var>)</code></a></dt><!-- RDLabel: "implicit_timezone=" -->
<dd>
Set the implicit timezone used for queries</dd>
<dt><a name="label-83" id="label-83"><code>compact_container(<var>name</var>, <var>context</var> = <var>Xml</var>::<var>Context</var>.<var>new</var>)</code></a></dt><!-- RDLabel: "compact_container" -->
<dd>
Compact the databases comprising the container.</dd>
<dt><a name="label-84" id="label-84"><code>truncate_container(<var>name</var>, <var>context</var> = <var>XML</var>::<var>Context</var>.<var>new</var>)</code></a></dt><!-- RDLabel: "truncate_container" -->
<dd>
Truncate the container.</dd>
</dl>
</body>
</html>
|
