← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/api_java/db_associate.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdb/docs/api_java/db_associate.html
1
 
<!--$Id$-->
2
 
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
 
<!--All rights reserved.-->
4
 
<!--See the file LICENSE for redistribution information.-->
5
 
<html>
6
 
<head>
7
 
<title>Berkeley DB: Db.associate</title>
8
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
10
 
</head>
11
 
<body bgcolor=white>
12
 
<a name="2"><!--meow--></a>
13
 
<table width="100%"><tr valign=top>
14
 
<td>
15
 
<h1>Db.associate</h1>
16
 
</td>
17
 
<td align=right>
18
 
<a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
19
 
</td></tr></table>
20
 
<hr size=1 noshade>
21
 
<tt>
22
 
<h3><pre>
23
 
import com.sleepycat.db.*;
24
 
<p>
25
 
public interface DbSecondaryKeyCreate
26
 
{
27
 
    public int secondary_key_create(DbTxn txnid,
28
 
      Db secondary, Dbt key, Dbt data, Dbt result)
29
 
        throws DbException;
30
 
}
31
 
public class Db
32
 
{
33
 
    ...
34
 
    public void associate(Db secondary,
35
 
      DbSecondaryKeyCreate secondary_key_create, int flags)
36
 
        throws DbException;
37
 
    ...
38
 
}
39
 
</pre></h3>
40
 
<h1>Description</h1>
41
 
<p>The Db.associate function is used to declare one database a
42
 
secondary index for a primary database.  After a secondary database has
43
 
been "associated" with a primary database, all updates to the primary
44
 
will be automatically reflected in the secondary and all reads from the
45
 
secondary will return corresponding data from the primary.  Note that
46
 
as primary keys must be unique for secondary indices to work, the
47
 
primary database must be configured without support for duplicate data
48
 
items.  See <a href="../ref/am/second.html">Secondary indices</a> for
49
 
more information.
50
 
<p>The associate method called should be a method off a database handle for
51
 
the primary database that is to be indexed.
52
 
The <b>secondary</b> argument should be an open database handle of
53
 
either a newly created and empty database that is to be used to store
54
 
a secondary index, or of a database that was previously associated with
55
 
the same primary and contains a secondary index.  Note that it is not
56
 
safe to associate as a secondary database a handle that is in use by
57
 
another thread of control or has open cursors.  If the handle was opened
58
 
with the <a href="../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag it is safe to use it in multiple threads
59
 
of control after the Db.associate method has returned.  Note also
60
 
that either secondary keys must be unique or the secondary database must
61
 
be configured with support for duplicate data items.
62
 
<p>If the operation is to be transaction-protected (other than by specifying
63
 
the Db.DB_AUTO_COMMIT flag), the <b>txnid</b> parameter is a
64
 
transaction handle returned from <a href="../api_java/txn_begin.html">DbEnv.txn_begin</a>; otherwise, null.
65
 
<p>The <b>callback</b> argument should refer to a callback function that
66
 
creates a secondary key from a given primary key and data pair.  When
67
 
called, the first argument will be the secondary <a href="../api_java/db_class.html">Db</a> handle; the
68
 
second and third arguments will be <a href="../api_java/dbt_class.html">Dbt</a>s containing a primary
69
 
key and datum respectively;  and the fourth argument will be a zeroed
70
 
DBT in which the callback function should fill in <b>data</b> and
71
 
<b>size</b> fields that describe the secondary key.
72
 
<a name="3"><!--meow--></a>
73
 
<a name="4"><!--meow--></a>
74
 
<p>If any key/data pair in the primary yields a null secondary key and
75
 
should be left out of the secondary index, the callback function may
76
 
optionally return Db.DB_DONOTINDEX.  Otherwise, the callback
77
 
function should return 0 in case of success or any other integer error
78
 
code in case of failure; the error code will be returned from the Berkeley DB
79
 
interface call that initiated the callback.  Note that if the callback
80
 
function returns Db.DB_DONOTINDEX for any key/data pairs in the
81
 
primary database, the secondary index will not contain any reference to
82
 
those key/data pairs, and such operations as cursor iterations and range
83
 
queries will reflect only the corresponding subset of the database.  If
84
 
this is not desirable, the application should ensure that the callback
85
 
function is well-defined for all possible values and never returns
86
 
Db.DB_DONOTINDEX.
87
 
<p>The callback argument may be NULL if and only if both the primary and
88
 
secondary database handles were opened with the <a href="../api_java/db_open.html#DB_RDONLY">Db.DB_RDONLY</a> flag.
89
 
<p>The <b>flags</b> value must be set to 0 or
90
 
the following value:
91
 
<p><dl compact>
92
 
<p><dt><a name="Db.DB_CREATE">Db.DB_CREATE</a><dd>If the secondary database is empty, walk through the primary and create
93
 
an index to it in the empty secondary.  This operation is potentially
94
 
very expensive.
95
 
<p>If the secondary database has been opened in an environment configured
96
 
with transactions, each put necessary for its creation will be done in
97
 
the context of a transaction created for the purpose.
98
 
<p>Care should be taken not to use a newly-populated secondary database in
99
 
another thread of control until the Db.associate call has
100
 
returned successfully in the first thread.
101
 
<p>If transactions are not being used, care should be taken not to modify
102
 
a primary database being used to populate a secondary database, in
103
 
another thread of control, until the Db.associate call has
104
 
returned successfully in the first thread.  If transactions are being
105
 
used, Berkeley DB will perform appropriate locking and the application need
106
 
not do any special operation ordering.
107
 
</dl>
108
 
<p>In addition, the following flag may be set by
109
 
bitwise inclusively <b>OR</b>'ing it into the <b>flags</b> parameter:
110
 
<p><dl compact>
111
 
<p><dt><a name="Db.DB_AUTO_COMMIT">Db.DB_AUTO_COMMIT</a><dd>Enclose the Db.associate call within a transaction.  If the call succeeds,
112
 
changes made by the operation will be recoverable.  If the call fails,
113
 
the operation will have made no changes.
114
 
</dl>
115
 
<p>The Db.associate method throws an exception that encapsulates a non-zero error value on
116
 
failure.
117
 
<h1>Errors</h1>
118
 
<p>The Db.associate method may fail and throw an exception encapsulating a non-zero error for the following conditions:
119
 
<p><dl compact>
120
 
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
121
 
<p>The secondary database handle has already been associated with this or
122
 
another database handle.
123
 
<p>The secondary database handle is not open.
124
 
<p>The primary database has been configured to allow duplicates.
125
 
</dl>
126
 
<p>The Db.associate method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods.
127
 
If a catastrophic error has occurred, the Db.associate method may fail and
128
 
throw a <a href="../api_java/runrec_class.html">DbRunRecoveryException</a>,
129
 
in which case all subsequent Berkeley DB calls will fail in the same way.
130
 
<h1>Class</h1>
131
 
<a href="../api_java/db_class.html">Db</a>
132
 
<h1>See Also</h1>
133
 
<a href="../api_java/db_list.html">Databases and Related Methods</a>
134
 
</tt>
135
 
<table width="100%"><tr><td><br></td><td align=right>
136
 
<a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
137
 
</td></tr></table>
138
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
139
 
</body>
140
 
</html>