Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
“This License” refers to version 3 of the GNU General Public License.
“Copyright” also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
“The Program” refers to any copyrightable work licensed under this
License. Each licensee is addressed as “you”. “Licensees” and
“recipients” may be individuals or organizations.
To “modify” a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a “modified version” of the
earlier work or a work “based on” the earlier work.
A “covered work” means either the unmodified Program or a work based
on the Program.
To “propagate” a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To “convey” a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays “Appropriate Legal Notices”
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The “source code” for a work means the preferred form of the work
for making modifications to it. “Object code” means any non-source
form of a work.
A “Standard Interface” means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The “System Libraries” of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
“Major Component”, in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The “Corresponding Source” for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
“keep intact all notices”.
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
“aggregate” if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A “User Product” is either (1) a “consumer product”, which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, “normally used” refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
“Installation Information” for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
“Additional permissions” are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered “further
restrictions” within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An “entity transaction” is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A “contributor” is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's “contributor version”.
A contributor's “essential patent claims” are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, “control” includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a “patent license” is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To “grant” such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. “Knowingly relying” means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is “discriminatory” if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License “or any later version” applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the “copyright” line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
<program> Copyright (C) <year> <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an “about box”.
You should also get your employer (if you work as a programmer) or school,
if any, to sign a “copyright disclaimer” for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
<http://www.gnu.org/licenses/>.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
<http://www.gnu.org/philosophy/why-not-lgpl.html>.
db4o-8.0.184.15484+dfsg/doc/ 0000755 0001750 0001750 00000000000 11520622620 015410 5 ustar directhex directhex db4o-8.0.184.15484+dfsg/doc/tutorial/ 0000755 0001750 0001750 00000000000 11621751575 017271 5 ustar directhex directhex db4o-8.0.184.15484+dfsg/doc/tutorial/bin/ 0000755 0001750 0001750 00000000000 11621751011 020022 5 ustar directhex directhex db4o-8.0.184.15484+dfsg/doc/tutorial/bin/Db4objects.Db4o.CS.xml 0000644 0001750 0001750 00000133433 11520622074 023635 0 ustar directhex directhex
Db4objects.Db4o.CSConfiguration interface for db4o networking clients.Configuration interface for db4o networking clients.7.5
A configuration provider that provides access to the
networking configuration methods.
A configuration provider that provides access to the
networking configuration methods.
7.5Access to the networking configuration methods.Access to the networking configuration methods.
adds ConfigurationItems to be applied when
a networking
Db4objects.Db4o.CS.Internal.ClientObjectContainer
is opened.
the
IClientConfigurationItem7.12
Sets the number of IDs to be pre-allocated in the database for new
objects created on the client.
Sets the number of IDs to be pre-allocated in the database for new
objects created on the client.
The number of IDs to be prefetchedSets the number of objects to be prefetched for an ObjectSet.Sets the number of objects to be prefetched for an ObjectSet.The number of objects to be prefetchedreturns the MessageSender for this Configuration context.
returns the MessageSender for this Configuration context.
This setting should be used on the client side.
MessageSenderSets the depth to which prefetched objects will be activated.Sets the depth to which prefetched objects will be activated.Sets the slot cache size to the given value.Sets the slot cache size to the given value.
configures the time a client waits for a message response
from the server.
configures the time a client waits for a message response
from the server.
Default value: 600000ms (10 minutes)
It is recommended to use the same values for
TimeoutClientSocket(int)
and
#timeoutServerSocket(int)
.
time in milliseconds
Implement this interface for configuration items that encapsulate
a batch of configuration settings or that need to be applied
to ClientObjectContainers after they are opened.
Implement this interface for configuration items that encapsulate
a batch of configuration settings or that need to be applied
to ClientObjectContainers after they are opened.
7.12Gives a chance for the item to augment the configuration.Gives a chance for the item to augment the configuration.
the configuration that the item was added to
Gives a chance for the item to configure the just opened ObjectContainer.
Gives a chance for the item to configure the just opened ObjectContainer.
the ObjectContainer to configure
factory to open C/S server and client implementations.factory to open C/S server and client implementations.Db4objects.Db4o.Db4oFactory.OpenClient(Db4objects.Db4o.Config.IConfiguration, string, int, string, string)
Configuration interface for networking configuration settings.
The network settings should be configured in exactly the same on the server and client.
Configuration interface for networking configuration settings.
The network settings should be configured in exactly the same on the server and client.
7.5
configures the client messaging system to be single threaded
or multithreaded.
configures the client messaging system to be single threaded
or multithreaded.
Recommended settings:
- true for low resource systems.
- false for best asynchronous performance and fast
GUI response.
Default value:
- .NET Compact Framework: true
- all other platforms: false
This setting can be used on both client and server.
the desired settingConfigures to batch messages between client and server.
Configures to batch messages between client and server. By default, batch
mode is enabled.
This setting can be used on both client and server.
false, to turn message batching off.Configures the maximum memory buffer size for batched message.
Configures the maximum memory buffer size for batched message. If the
size of batched messages is greater than maxSize, batched
messages will be sent to server.
This setting can be used on both client and server.
sets the MessageRecipient to receive Client Server messages.
sets the MessageRecipient to receive Client Server messages.
This setting can be used on both client and server.
the MessageRecipient to be used7.117.11Configuration interface for db4o servers.Configuration interface for db4o servers.7.5
adds ConfigurationItems to be applied when
an ObjectServer is opened.
adds ConfigurationItems to be applied when
an ObjectServer is opened.
the
IServerConfigurationItem7.12configures the timeout of the server side socket.
configures the timeout of the server side socket.
The server side handler waits for messages to arrive from the client.
If no more messages arrive for the duration configured in this
setting, the client will be disconnected.
Clients send PING messages to the server at an interval of
Math.min(timeoutClientSocket(), timeoutServerSocket()) / 2
and the server will respond to keep connections alive.
Decrease this setting if you want clients to disconnect faster.
Increase this setting if you have a large number of clients and long
running queries and you are getting disconnected clients that you
would like to wait even longer for a response from the server.
Default value: 600000ms (10 minutes)
It is recommended to use the same values for
#timeoutClientSocket(int)
and
TimeoutServerSocket(int)
.
This setting can be used on both client and server.
time in milliseconds
Implement this interface for configuration items that encapsulate
a batch of configuration settings or that need to be applied
to ObjectServers after they are opened.
Implement this interface for configuration items that encapsulate
a batch of configuration settings or that need to be applied
to ObjectServers after they are opened.
7.12Gives a chance for the item to augment the configuration.Gives a chance for the item to augment the configuration.
the configuration that the item was added to
Gives a chance for the item to configure the just opened ObjectContainer.
Gives a chance for the item to configure the just opened ObjectContainer.
the ObjectContainer to configure
Factory class to open db4o servers and to connect db4o clients
to them.
Factory class to open db4o servers and to connect db4o clients
to them.
Note:
This class is made available in db4o-X.x-cs-java.jar / Db4objects.Db4o.CS.dll7.5
creates a new
Db4objects.Db4o.CS.Config.IServerConfiguration
opens an
IObjectServer
on the specified database file and port.
a custom
Db4objects.Db4o.CS.Config.IServerConfiguration
instance to be obtained via
NewServerConfiguration()
an absolute or relative path to the database file
the port to be used or 0 if the server should not open a port, specify a value < 0 if an arbitrary free port should be chosen - see
ExtObjectServer#port()
.
an
IObjectServer
listening
on the specified port.
Configuration#readOnlyConfiguration#encryptConfiguration#passwordI/O operation failed or was unexpectedly interrupted.
the required database file is locked by
another process.
runtime
configuration
is not compatible
with the configuration of the database file.
open operation failed because the database file
is in old format and
Db4objects.Db4o.Config.IConfiguration.AllowVersionUpdates(bool)
is set to false.
database was configured as read-only.
opens a db4o server with a fresh server configuration.opens a db4o server with a fresh server configuration.OpenServer(Db4objects.Db4o.CS.Config.IServerConfiguration, string, int)NewServerConfiguration()opens a db4o client instance with the specified configuration.opens a db4o client instance with the specified configuration.
the configuration to be used
the host name of the server that is to be connected to
the server port to connect to
the username for authentication
the password for authentication
OpenServer(Db4objects.Db4o.CS.Config.IServerConfiguration, string, int)Db4objects.Db4o.IObjectServer.GrantAccess(string, string)
if the configuration passed in has already been used.
opens a db4o client instance with a fresh client configuration.opens a db4o client instance with a fresh client configuration.OpenClient(Db4objects.Db4o.CS.Config.IClientConfiguration, string, int, string, string)
NewClientConfiguration()
creates a new
Db4objects.Db4o.CS.Config.IClientConfiguration
7.127.12may return null, if no message is returned.
may return null, if no message is returned. Error handling is weak and
should ideally be able to trigger some sort of state listener (connection
dead) on the client.
Platform specific defaults.Platform specific defaults.
The default
ClientQueryResultIterator
for this platform.
This class exists to work around a decaf conversion problem
when the code was directly in ServerMessageDispatcherImp.
This class exists to work around a decaf conversion problem
when the code was directly in ServerMessageDispatcherImp.
an event that provides the name of the client being disconnected.7.12Defines a strategy on how to prefetch objects from the server.Defines a strategy on how to prefetch objects from the server.Messages with Data for Client/Server CommunicationMessages for Client/Server Communication
dummy method to allow clean override handling
without casting
to be overridden by implementors of MessageWithResponseget the classname for an internal IDSystem.IDisposable.Dispose()EventArgs => MessageEventArgsPrefetchs multiples objects at once (in a single message).Prefetchs multiples objects at once (in a single message).
db4o-8.0.184.15484+dfsg/doc/tutorial/bin/Db4objects.Db4o.Optional.xml 0000644 0001750 0001750 00000056152 11520622074 025117 0 ustar directhex directhex
Db4objects.Db4o.Optionalallows running Queries against multiple ObjectContainers.allows running Queries against multiple ObjectContainers.
use this constructor to create a Cluster and call
add() to add ObjectContainers
starts a query against all ObjectContainers in
this Cluster.
starts a query against all ObjectContainers in
this Cluster.
the Query
returns the ObjectContainer in this cluster where the passed object
is stored or null, if the object is not stored to any ObjectContainer
in this cluster
the object
the ObjectContainerStatistics for the byte usage for a single class (instances, indices, etc.) in a db4o database file.
Statistics for the byte usage for a single class (instances, indices, etc.) in a db4o database file.
the name of the persistent classnumber of bytes used slots containing the actual class instancesnumber of bytes used for the index of class instancesnumber of bytes used for field indexes, if any
number of bytes used for features that are specific to this class (ex.: the BTree encapsulated within a
Db4objects.Db4o.Internal.Collections.BigSet<E>
instance)
aggregated byte usage for this persistent classByte usage statistics for a db4o database filebytes used by the db4o file header (static and variable parts)total number of bytes registered as freespace, available for reusebytes used by the id system indicesnumber of bytes used for class metadata (class metadata repository and schema definitions)
number of bytes used for the bookkeeping of the freespace system itselfnumber of bytes used for the uuid indexnumber of bytes used for the commit timestamp indexestotal file size in bytes
number of bytes used aggregated from all categories - should always be equal to
FileSize()the statistics for each persisted class
a fully qualified class name
the statistics for the class with the given name
Collects database file usage statistics and prints them
to the console.
Collects database file usage statistics and prints them
to the console.
IoAdapter for in-memory operation.
IoAdapter for in-memory operation.
Configure db4o to operate with this in-memory IoAdapter with
MemoryIoAdapter memoryIoAdapter = new MemoryIoAdapter();
Db4oFactory.Configure().Io(memoryIoAdapter);
Use the normal #openFile() and #openServer() commands to open
ObjectContainers and ObjectServers. The names specified as file names will be
used to identify the byte[] content of the in-memory files in
the _memoryFiles Hashtable in the adapter. After working with an in-memory
ObjectContainer/ObjectServer the byte[] content is available
in the MemoryIoAdapter by using
Db4objects.Db4o.IO.MemoryIoAdapter.Get
. To add old existing
database byte[] content to a MemoryIoAdapter use
Db4objects.Db4o.IO.MemoryIoAdapter.Put
. To reduce memory consumption of memory file
names that will no longer be used call
Db4objects.Db4o.IO.MemoryIoAdapter.Put
and pass
an empty byte array.
creates an in-memory database with the passed content bytes and adds it
to the adapter for the specified name.
creates an in-memory database with the passed content bytes and adds it
to the adapter for the specified name.
the name to be use for #openFile() or #openServer() calls
the database content
returns the content bytes for a database with the given name.returns the content bytes for a database with the given name.
the name to be use for #openFile() or #openServer() calls
the content bytes
configures the length a memory file should grow, if no more free slots
are found within.
configures the length a memory file should grow, if no more free slots
are found within.
Specify a large value (100,000 or more) for best performance. Specify a
small value (100) for the smallest memory consumption. The default
setting is 10,000.
the length in bytes
for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.for internal processing only.
Delegating IoAdapter that does not pass on calls to sync
data to the underlying device.
Delegating IoAdapter that does not pass on calls to sync
data to the underlying device.
This IoAdapter can be used to improve performance at the cost of a
higher risk of database file corruption upon abnormal termination
of a session against a database.
An example of possible usage:
RandomAccessFileAdapter randomAccessFileAdapter = new RandomAccessFileAdapter();
NonFlushingIoAdapter nonFlushingIoAdapter = new NonFlushingIoAdapter(randomAccessFileAdapter);
CachedIoAdapter cachedIoAdapter = new CachedIoAdapter(nonFlushingIoAdapter);
Configuration configuration = Db4o.newConfiguration();
configuration.io(cachedIoAdapter);
db4o uses a resume-commit-on-crash strategy to ensure ACID transactions.
When a transaction commits,
- (1) a list "pointers that are to be modified" is written to the database file,
- (2) the database file is switched into "in-commit" mode,
- (3) the pointers are actually modified in the database file,
- (4) the database file is switched to "not-in-commit" mode.
If the system is halted by a hardware or power failure
- before (2)
all objects will be available as before the commit
- between (2) and (4)
the commit is restarted when the database file is opened the next time, all pointers
will be read from the "pointers to be modified" list and all of them will be modified
to the state they are intended to have after commit
- after (4)
no work is necessary, the transaction is committed.
In order for the above to be 100% failsafe, the order of writes to the
storage medium has to be obeyed. On operating systems that use in-memory
file caching, the OS cache may revert the order of writes to optimize
file performance.
db4o enforces the correct write order by calling
Sync()
after every single one of the above steps during transaction
commit. The calls to
Sync()
have a high performance cost.
By using this IoAdapter it is possible to omit these calls, at the cost
of a risc of corrupted database files upon hardware-, power- or operating
system failures.
Storage that allows to save an open database file
as another file while keeping the reference system
in place.
Storage that allows to save an open database file
as another file while keeping the reference system
in place. If anything goes wrong during copying the
storage tries to reopen the original file, so commit
operations can still take place against the original
file.
call this method to save the content of a currently
open ObjectContainer session to a new file location.
call this method to save the content of a currently
open ObjectContainer session to a new file location.
Invocation will close the old file without a commit,
keep the reference system in place and connect it to
the file in the new location. If anything goes wrong
during the copying operation or while opening it will
be attempted to reopen the old file. In this case a
Db4oException will be thrown.
the path to the old open database file
the path to the new database file
We could have nicely used BinDecorator here, but
BinDecorator doesn't allow exchanging the Bin.
We could have nicely used BinDecorator here, but
BinDecorator doesn't allow exchanging the Bin. To
be compatible with released versions we do
Contains the application-specific reflection information (that would
be generated by a bytecode enhancer), as opposed to the 'generic'
functionality contained in SelfReflector.
Contains the application-specific reflection information (that would
be generated by a bytecode enhancer), as opposed to the 'generic'
functionality contained in SelfReflector.
prints statistics about a database file to System.out.
prints statistics about a database file to System.out.
Pass the database file path as an argument.
This class is not part of db4o.jar!
It is delivered as sourcecode in the
path ../com/db4o/tools/
the main method that runs the statistics.the main method that runs the statistics.
a String array of length 1, with the name of the database
file as element 0.
Publishes performance counters for bytes read and written.
db4o-8.0.184.15484+dfsg/doc/tutorial/bin/Db4objects.Db4o.xml 0000644 0001750 0001750 00002616135 11520622074 023340 0 ustar directhex directhex
Db4objects.Db4o
Activator interface.
Db4objects.Db4o.TA.IActivatable
objects need to have a reference to
an Activator implementation, which is called
by Transparent Activation, when a request is received to
activate the host object.
Transparent Activation framework.Method to be called to activate the host object.Method to be called to activate the host object.
for which purpose is the object being activated?
ActivationPurpose.Write
will cause the object
to be saved on the next
Db4objects.Db4o.IObjectContainer.Commit()
operation.
Transparent activatable IDictionary implementation.
Transparent activatable IDictionary implementation. Implements IDictionary interface
using two arrays to store keys and values.
When instantiated as a result of a query, all the internal members
are NOT activated at all. When internal members are required to
perform an operation, the instance transparently activates all the
members.
System.Collections.IDictionary
Db4objects.Db4o.TA.IActivatable
IActivatable must be implemented by classes in order to support
Transparent Activation.
The IActivatable interface may be added to persistent classes by hand
or by using the db4o instrumentation (Db4oTools).
IActivatable must be implemented by classes in order to support
Transparent Activation.
The IActivatable interface may be added to persistent classes by hand
or by using the db4o instrumentation (Db4oTools). For further
information on the enhancer see:
The basic idea for Transparent Activation is as follows:
Objects have an activation depth of 0, i.e. by default they are not
activated at all. Whenever a method is called on such an object, the
first thing to do before actually executing the method body is to
activate the object to level 1, i.e. populating its direct members.
To illustrate this approach, we will use the following simple class.
public class Item {
private Item _next;
public Item(Item next) {
_next = next;
}
public Item Next {
get {
return _next;
}
}
}
The basic sequence of actions to get the above scheme to work is the
following:
- Whenever an object is instantiated from db4o, the database registers an
activator for this object. To enable this, the object has to implement the
IActivatable interface and provide the according Bind(IActivator) method. The
default implementation of the bind method will simply store the given
activator reference for later use.
public class Item implements IActivatable {
transient IActivator _activator;
public void Bind(IActivator activator) {
if (null != _activator) {
throw new IllegalStateException();
}
_activator = activator;
}
// ...
}
- The first action in every method body of an activatable object should be a
call to the corresponding IActivator's Activate() method. (Note that this is
not enforced by any interface, it is rather a convention, and other
implementations are possible.)
public class Item implements IActivatable {
public void Activate() {
if (_activator == null) return;
_activator.Activate();
}
public Item Next() {
get {
Activate();
return _next;
}
}
}
- The Activate() method will check whether the object is already activated.
If this is not the case, it will request the container to activate the object
to level 1 and set the activated flag accordingly.
To instruct db4o to actually use these hooks (i.e. to register the database
when instantiating an object), TransparentActivationSupport has to be
registered with the db4o configuration.
called by db4o upon instantiation.
called by db4o upon instantiation.
The recommended implementation of this method is to store the passed
Db4objects.Db4o.Activation.IActivator
in a transient field of the object.
the Activator
should be called by every reading field access of an object.
should be called by every reading field access of an object.
The recommended implementation of this method is to call
Db4objects.Db4o.Activation.IActivator.Activate(Db4objects.Db4o.Activation.ActivationPurpose)
on the
Db4objects.Db4o.Activation.IActivator
that was previously passed to
Bind(Db4objects.Db4o.Activation.IActivator)
.
TODO
Initializes a new collection with the initial capacity = 16.
Initializes a collection of the specified initial capacity.
activate basic implementation.activate basic implementation.Db4objects.Db4o.TA.IActivatablebind basic implementation.bind basic implementation.Db4objects.Db4o.TA.IActivatable System.Collections.Generic.IDictionary implementation but transparently activates
the members as required. System.Collections.Generic.IDictionary implementation but transparently activates
the members as required.Db4objects.Db4o.TA.IActivatable
Returns the hash code of the collection. Returns the hash code of the collection. Collection members
get activated as required.Db4objects.Db4o.TA.IActivatable
Returns the number of elements in the collection. Returns the number of elements in the collection. The collection gets activated. Db4objects.Db4o.TA.IActivatable
Returns the values of the collection. Returns the values of the collection. The collection gets activated.Db4objects.Db4o.TA.IActivatable
Transparent activatable ArrayList implementation.
Transparent activatable ArrayList implementation. Implements IList
interface using an array to store elements. Each ArrayList4 instance
has a capacity, which indicates the size of the internal array.
When instantiated as a result of a query, all the internal members
are NOT activated at all. When internal members are required to
perform an operation, the instance transparently activates all the
members.
System.Collections.ArrayList
Db4objects.Db4o.TA.IActivatable
activate basic implementation.activate basic implementation.Db4objects.Db4o.TA.IActivatablebind basic implementation.bind basic implementation.Db4objects.Db4o.TA.IActivatable
Initializes a new collection with the initial capacity = 10.
Initializes a collection with the members of the parameter collection.
Initializes a collection of the specified initial capacity.
Inserts an element into the collection
at the specified index. Inserts an element into the collection
at the specified index.Db4objects.Db4o.TA.IActivatable
Removes all elements from the collection. Removes all elements from the collection.Db4objects.Db4o.TA.IActivatable
Resizes the collection capacity to the specified size if the
current capacity is less than the parameter value. Resizes the collection capacity to the specified size if the
current capacity is less than the parameter value.Db4objects.Db4o.TA.IActivatable
Returns the collection element at the specified index. Returns the collection element at the specified index.Db4objects.Db4o.TA.IActivatable
Removes the collection element at the specified index. Removes the collection element at the specified index.Db4objects.Db4o.TA.IActivatable
Replaces the collection element with the specified object at the specified index. Replaces the collection element with the specified object at the specified index.Db4objects.Db4o.TA.IActivatable
Resizes the collection to its actual size. Resizes the collection to its actual size.Db4objects.Db4o.TA.IActivatable
Returns the size of the collection. Returns the size of the collection.Db4objects.Db4o.TA.IActivatable
Collection factory with methods to create collections with behaviour
that is optimized for db4o.
Example usage: CollectionFactory.forObjectContainer(objectContainer).newBigSet();returns a collection factory for an ObjectContainer
- the ObjectContainer
the CollectionFactory
creates a new BigSet.
Characteristics of BigSet:
- It is optimized by using a BTree of IDs of persistent objects.
- It can only hold persistent first class objects (no primitives, no strings, no objects that are not persistent)
- Objects are activated upon getting them from the BigSet.
creates a new BigSet.
Characteristics of BigSet:
- It is optimized by using a BTree of IDs of persistent objects.
- It can only hold persistent first class objects (no primitives, no strings, no objects that are not persistent)
- Objects are activated upon getting them from the BigSet.
BigSet is recommend whenever one object references a huge number of other objects and sorting is not required.
Defines a scope of applicability of a config setting.
Some of the configuration settings can be either:
- enabled globally;
- enabled individually for a specified class;
- disabled.
IConfiguration.GenerateUUIDs(ConfigScope)
IConfiguration.GenerateVersionNumbers(ConfigScope)
Marks a configuration feature as globally disabled.Marks a configuration feature as globally disabled.Marks a configuration feature as individually configurable.Marks a configuration feature as individually configurable.Marks a configuration feature as globally enabled.Marks a configuration feature as globally enabled.
Checks if the current configuration scope is globally
enabled or disabled.
Checks if the current configuration scope is globally
enabled or disabled.
- default result
false if disabled, true if globally enabled, default
value otherwise
encodes a String to a byte array and decodes a String
from a part of a byte array
called when a string is to be encoded to a byte array.called when a string is to be encoded to a byte array.
the string to encode
the encoded byte arraycalled when a byte array is to be decoded to a string.called when a byte array is to be decoded to a string.
the byte array
the start offset in the byte array
the length of the encoded string in the byte array
the stringAll built in String encodingsDb4objects.Db4o.Config.IConfiguration.StringEncoding(IStringEncoding)allows special comparison behaviour during query evaluation.
allows special comparison behaviour during query evaluation.
db4o will use the Object returned by the
Compare()
method for all query comparisons.
return the Object to be compared during query evaluation.return the Object to be compared during query evaluation.Marker interface to denote that a class is used for db4o internals.Marker interface to denote that a class is used for db4o internals.
db4o-specific exception.
This exception is thrown when a global configuration
setting is attempted on an open object container.
db4o-specific exception.
This exception is thrown when a global configuration
setting is attempted on an open object container.
IConfiguration.BlockSize(int)IConfiguration.Encrypt(bool)IConfiguration.Io(Db4objects.Db4o.IO.IoAdapter)
IConfiguration.Password(string)
db4o exception wrapper: Exceptions occurring during internal processing
will be proliferated to the client calling code encapsulated in an exception
of this type.
db4o exception wrapper: Exceptions occurring during internal processing
will be proliferated to the client calling code encapsulated in an exception
of this type. The original exception, if any, is available through
Db4oException#getCause().
Simple constructorConstructor with an exception message specified
exception message
Constructor with an exception cause specified
exception cause
Constructor with an exception message selected
from the internal message collection.
Constructor with an exception message selected
from the internal message collection.
internal db4o message number
Constructor with an exception message and cause specified
exception message
exception cause
Implement this interface when implementing special custom Aliases
for classes, packages or namespaces.
Implement this interface when implementing special custom Aliases
for classes, packages or namespaces.
Aliases can be used to persist classes in the running
application to different persistent classes in a database file
or on a db4o server.
Two simple Alias implementations are supplied along with
db4o:
-
TypeAlias
provides an #equals() resolver to match
names directly.
-
WildcardAlias
allows simple pattern matching
with one single '*' wildcard character.
It is possible to create
own complex
IAlias
constructs by creating own resolvers
that implement the
IAlias
interface.
Examples of concrete usecases:
// Creating an Alias for a single class
ICommonConfiguration.AddAlias(
new TypeAlias("Tutorial.Pilot", "Tutorial.Driver"));
// Accessing a Java package from a .NET assembly
ICommonConfiguration.AddAlias(
new WildcardAlias(
"com.f1.*",
"Tutorial.F1.*, Tutorial"));
// Using a different local .NET assembly
ICommonConfiguration.AddAlias(
new WildcardAlias(
"Tutorial.F1.*, F1Race",
"Tutorial.F1.*, Tutorial"));
Aliases that translate the persistent name of a class to
a name that already exists as a persistent name in the database
(or on the server) are not permitted and will throw an exception
when the database file is opened.
Aliases should be configured before opening a database file
or connecting to a server.
return the stored name for a runtime name or null if not handled.return the stored name for a runtime name or null if not handled.return the runtime name for a stored name or null if not handled.return the runtime name for a stored name or null if not handled.Interface to configure the cache configurations.Interface to configure the cache configurations.
configures the size of the slot cache to hold a number of
slots in the cache.
configures the size of the slot cache to hold a number of
slots in the cache.
the number of slots
A configuration provider that provides access
to the cache-related configuration methods.
A configuration provider that provides access
to the cache-related configuration methods.
Access to the cache-related configuration methods.Access to the cache-related configuration methods.Client/Server configuration interface.Client/Server configuration interface.
Sets the number of IDs to be pre-allocated in the database for new
objects created on the client.
Sets the number of IDs to be pre-allocated in the database for new
objects created on the client.
This setting should be used on the client side. In embedded mode this setting
has no effect.
The number of IDs to be prefetched
Sets the number of objects to be prefetched for an ObjectSet.
Sets the number of objects to be prefetched for an ObjectSet.
This setting should be used on the server side.
The number of objects to be prefetched
Sets the depth to which prefetched objects are activated.
Sets the depth to which prefetched objects are activated.
This setting should be used on the client side.
Sets the slot cache size to the given value.Sets the slot cache size to the given value.sets the MessageRecipient to receive Client Server messages.
sets the MessageRecipient to receive Client Server messages.
This setting should be used on the server side.
the MessageRecipient to be used
returns the MessageSender for this Configuration context.
returns the MessageSender for this Configuration context.
This setting should be used on the client side.
MessageSender
configures the time a client waits for a message response
from the server.
configures the time a client waits for a message response
from the server.
Default value: 600000ms (10 minutes)
It is recommended to use the same values for
TimeoutClientSocket(int)
and
TimeoutServerSocket(int)
.
This setting can be used on both client and server.
time in milliseconds
configures the timeout of the serverside socket.
configures the timeout of the serverside socket.
The serverside handler waits for messages to arrive from the client.
If no more messages arrive for the duration configured in this
setting, the client will be disconnected.
Clients send PING messages to the server at an interval of
Math.min(timeoutClientSocket(), timeoutServerSocket()) / 2
and the server will respond to keep connections alive.
Decrease this setting if you want clients to disconnect faster.
Increase this setting if you have a large number of clients and long
running queries and you are getting disconnected clients that you
would like to wait even longer for a response from the server.
Default value: 600000ms (10 minutes)
It is recommended to use the same values for
TimeoutClientSocket(int)
and
TimeoutServerSocket(int)
.
This setting can be used on both client and server.
time in milliseconds
configures the client messaging system to be single threaded
or multithreaded.
configures the client messaging system to be single threaded
or multithreaded.
Recommended settings:
- true for low resource systems.
- false for best asynchronous performance and fast
GUI response.
Default value:
- .NET Compactframework: true
- all other platforms: false
This setting can be used on both client and server.
the desired setting
Configures to batch messages between client and server.
Configures to batch messages between client and server. By default, batch
mode is enabled.
This setting can be used on both client and server.
false, to turn message batching off.
Configures the maximum memory buffer size for batched message.
Configures the maximum memory buffer size for batched message. If the
size of batched messages is greater than maxSize, batched
messages will be sent to server.
This setting can be used on both client and server.
Common configuration methods, applicable for
embedded, client and server use of db4o.
In Client/Server use it is good practice to configure the
client and the server in exactly the same way.
Common configuration methods, applicable for
embedded, client and server use of db4o.
In Client/Server use it is good practice to configure the
client and the server in exactly the same way.
7.5adds a new Alias for a class, namespace or package.
adds a new Alias for a class, namespace or package.
Aliases can be used to persist classes in the running
application to different persistent classes in a database file
or on a db4o server.
Two simple Alias implementations are supplied along with
db4o:
-
TypeAlias
provides an #equals() resolver to match
names directly.
-
WildcardAlias
allows simple pattern matching
with one single '*' wildcard character.
It is possible to create
own complex
IAlias
constructs by creating own resolvers
that implement the
IAlias
interface.
Examples of concrete usecases:
// Creating an Alias for a single class
Db4o.configure().addAlias(
new TypeAlias("com.f1.Pilot", "com.f1.Driver"));
// Accessing a .NET assembly from a Java package
Db4o.configure().addAlias(
new WildcardAlias(
"Tutorial.F1.*, Tutorial",
"com.f1.*"));
// Mapping a Java package onto another
Db4o.configure().addAlias(
new WildcardAlias(
"com.f1.*",
"com.f1.client*"));
Aliases that translate the persistent name of a class to
a name that already exists as a persistent name in the database
(or on the server) are not permitted and will throw an exception
when the database file is opened.
Aliases should be configured before opening a database file
or connecting to a server.
In client/server environment it is good practice to configure the
client and the server in exactly the same way.
Removes an alias previously added with
IConfiguration.AddAlias(IAlias)
.
the alias to remove
adds ConfigurationItems to be applied when
an ObjectContainer or ObjectServer is opened.
adds ConfigurationItems to be applied when
an ObjectContainer or ObjectServer is opened.
the ConfigurationItem
allows to mark fields as transient with custom attributes.
allows to mark fields as transient with custom attributes.
.NET only: Call this method with the attribute name that you
wish to use to mark fields as transient. Multiple transient attributes
are possible by calling this method multiple times with different
attribute names.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
- the fully qualified name of the attribute, including
it's namespace
TODO: can we provide meaningful java side semantics for this one?
TODO: USE A CLASS!!!!!!
returns an
IObjectClass
object
to configure the specified class.
The clazz parameter can be any of the following:
- a fully qualified classname as a String.
- a Class object.
- any other object to be used as a template.
class name, Class object, or example object.
an instance of an
IObjectClass
object for configuration.
configures the use of a specially designed reflection implementation.
configures the use of a specially designed reflection implementation.
db4o internally uses java.lang.reflect.* by default. On platforms that
do not support this package, customized implementations may be written
to supply all the functionality of the interfaces in the com.db4o.reflect
package. This method can be used to install a custom reflection
implementation.
In client-server environment this setting should be used on both the client and
the server side (reflector class must be available)
allows registering special TypeHandlers for customized marshalling
and customized comparisons.
allows registering special TypeHandlers for customized marshalling
and customized comparisons.
to specify for which classes and versions the
TypeHandler is to be used.
to be used for the classes that match the predicate.
Registers a
INameProvider
that assigns a custom name to the database to be used in
object.ToString()
.
sets the activation depth to the specified value.
sets the activation depth to the specified value.
Why activation?
When objects are instantiated from the database, the instantiation of member
objects needs to be limited to a certain depth. Otherwise a single object
could lead to loading the complete database into memory, if all objects where
reachable from a single root object.
db4o uses the concept "depth", the number of field-to-field hops an object
is away from another object. The preconfigured "activation depth" db4o uses
in the default setting is 5.
Whenever an application iterates through the
IObjectSet
of a query result, the result objects
will be activated to the configured activation depth.
A concrete example with the preconfigured activation depth of 5:
// Object foo is the result of a query, it is delivered by the ObjectSet
object foo = objectSet.Next();
foo.member1.member2.member3.member4.member5 will be a valid object
foo, member1, member2, member3 and member4 will be activated
member5 will be deactivated, all of it's members will be null
member5 can be activated at any time by calling
IObjectContainer.Activate(member5, depth)
.
Note that raising the global activation depth will consume more memory and
have negative effects on the performance of first-time retrievals. Lowering
the global activation depth needs more individual activation work but can
increase performance of queries.
IObjectContainer.Deactivate(object, depth)
can be used to manually free memory by deactivating objects.
In client/server environment it is good practice to configure the
client and the server in exactly the same way.
.
configuring classes individually
gets the configured activation depth.sets the activation depth to the specified value.
sets the activation depth to the specified value.
Why activation?
When objects are instantiated from the database, the instantiation of member
objects needs to be limited to a certain depth. Otherwise a single object
could lead to loading the complete database into memory, if all objects where
reachable from a single root object.
db4o uses the concept "depth", the number of field-to-field hops an object
is away from another object. The preconfigured "activation depth" db4o uses
in the default setting is 5.
Whenever an application iterates through the
IObjectSet
of a query result, the result objects
will be activated to the configured activation depth.
A concrete example with the preconfigured activation depth of 5:
// Object foo is the result of a query, it is delivered by the ObjectSet
object foo = objectSet.Next();
foo.member1.member2.member3.member4.member5 will be a valid object
foo, member1, member2, member3 and member4 will be activated
member5 will be deactivated, all of it's members will be null
member5 can be activated at any time by calling
IObjectContainer.Activate(member5, depth)
.
Note that raising the global activation depth will consume more memory and
have negative effects on the performance of first-time retrievals. Lowering
the global activation depth needs more individual activation work but can
increase performance of queries.
IObjectContainer.Deactivate(object, depth)
can be used to manually free memory by deactivating objects.
In client/server environment it is good practice to configure the
client and the server in exactly the same way.
.
configuring classes individually
gets the configured activation depth.turns automatic database file format version updates on.
turns automatic database file format version updates on.
Upon db4o database file format version changes,
db4o can automatically update database files to the
current version. db4objects does not provide functionality
to reverse this process. It is not ensured that updated
database files can be read with older db4o versions.
In some cases (Example: using ObjectManager) it may not be
desirable to update database files automatically therefore
automatic updating is turned off by default for
security reasons.
Call this method to turn automatic database file
version updating on.
If automatic updating is turned off, db4o will refuse
to open database files that use an older database file format.
In client/server environment it is good practice to configure the
client and the server in exactly the same way.
turns automatic shutdown of the engine on and off.
turns automatic shutdown of the engine on and off.
The default and recommended setting is true.
configures the size of BTree nodes in indexes.
configures the size of BTree nodes in indexes.
Default setting: 100
Lower values will allow a lower memory footprint
and more efficient reading and writing of small slots.
Higher values will reduce the overall number of
read and write operations and allow better performance
at the cost of more RAM use.
In client/server environment it is good practice to configure the
client and the server in exactly the same way.
the number of elements held in one BTree node.turns callback methods on and off.
turns callback methods on and off.
Callbacks are turned on by default.
A tuning hint: If callbacks are not used, you can turn this feature off, to
prevent db4o from looking for callback methods in persistent classes. This will
increase the performance on system startup.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
false to turn callback methods offUsing callbacks
advises db4o to try instantiating objects with/without calling
constructors.
advises db4o to try instantiating objects with/without calling
constructors.
Not all .NET-environments support this feature. db4o will
attempt, to follow the setting as good as the enviroment supports.
This setting may also be overridden for individual classes in
Db4objects.Db4o.Config.IObjectClass.CallConstructor
.
The default setting depends on the features supported by your current environment.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
Db4objects.Db4o.Config.IObjectClass.CallConstructor
tuning feature: configures whether db4o checks all persistent classes upon system
startup, for added or removed fields.
tuning feature: configures whether db4o checks all persistent classes upon system
startup, for added or removed fields.
If this configuration setting is set to false while a database is
being created, members of classes will not be detected and stored.
This setting can be set to false in a production environment after
all persistent classes have been stored at least once and classes will not
be modified any further in the future.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
Default value: truethe desired settingreturns the configuration interface for diagnostics.returns the configuration interface for diagnostics.the configuration interface for diagnostics.configures whether Exceptions are to be thrown, if objects can not be stored.
configures whether Exceptions are to be thrown, if objects can not be stored.
db4o requires the presence of a constructor that can be used to
instantiate objects. If no default public constructor is present, all
available constructors are tested, whether an instance of the class can
be instantiated. Null is passed to all constructor parameters.
The first constructor that is successfully tested will
be used throughout the running db4o session. If an instance of the class
can not be instantiated, the object will not be stored. By default,
execution will be stopped with an Exception. This method can
be used to configure db4o to not throw an
ObjectNotStorableException
if an object can not be stored.
The default for this setting is true.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
true to throw Exceptions if objects can not be stored.configures db4o to call Intern() on strings upon retrieval.
configures db4o to call Intern on strings upon retrieval if set to true.
In client/server environment the setting should be used on both
client and server.
sets the detail level of db4o messages.
sets the detail level of db4o messages. Messages will be output to the
configured output
TextWriter
.
Level 0 - no messages
Level 1 - open and close messages
Level 2 - messages for new, update and delete
Level 3 - messages for activate and deactivate
When using client-server and the level is set to 0, the server will override this and set it to 1. To get around this you can set the level to -1. This has the effect of not returning any messages.
In client-server environment this setting can be used on client or on server
depending on which information do you want to track (server side provides more
detailed information).
integer from 0 to 3TODO: replace int with enumeration
If set to true, db4o will try to optimize native queries
dynamically at query execution time, otherwise it will
run native queries in unoptimized mode as SODA evaluations.
If set to true, db4o will try to optimize native queries
dynamically at query execution time, otherwise it will
run native queries in unoptimized mode as SODA evaluations.
The following assemblies should be available for native query switch to take effect:
Db4objects.Db4o.NativeQueries.dll, Db4objects.Db4o.Instrumentation.dll.
The default setting is true.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
Db4objects.Db4o.Config.ICommonConfiguration.OptimizeNativeQueries
If set to true, db4o will try to optimize native queries
dynamically at query execution time, otherwise it will
run native queries in unoptimized mode as SODA evaluations.
If set to true, db4o will try to optimize native queries
dynamically at query execution time, otherwise it will
run native queries in unoptimized mode as SODA evaluations.
The following assemblies should be available for native query switch to take effect:
Db4objects.Db4o.NativeQueries.dll, Db4objects.Db4o.Instrumentation.dll.
The default setting is true.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
Db4objects.Db4o.Config.ICommonConfiguration.OptimizeNativeQueriesreturns the Query configuration interface.returns the Query configuration interface.
Assigns a
TextWriter
where db4o is to print its event messages.
Messages are useful for debugging purposes and for learning
to understand, how db4o works. The message level can be raised with
IConfiguration.MessageLevel(int)
to produce more detailed messages.
Use outStream(System.out) to print messages to the
console.
In client-server environment this setting should be used on the same side
where
IConfiguration.MessageLevel(int)
is used.
the new PrintStream for messages.MessageLevel(int)configures the string encoding to be used.
configures the string encoding to be used.
The string encoding can not be changed in the lifetime of a
database file. To set up the database with the correct string encoding,
this configuration needs to be set correctly before a database
file is created with the first call to
Db4objects.Db4o.Db4oFactory.OpenFile
or
Db4objects.Db4o.Db4oFactory.OpenServer
.
For subsequent open calls, db4o remembers built-in
string encodings. If a custom encoding is used (an encoding that is
not supplied from within the db4o library), the correct encoding
needs to be configured correctly again for all subsequent calls
that open database files.
In client-server mode, the server and all clients need to have the same string encoding.
Example: config.StringEncoding = StringEncodings.Utf8();Db4objects.Db4o.Config.Encoding.StringEncodings
tuning feature: configures whether db4o should try to instantiate one instance
of each persistent class on system startup.
tuning feature: configures whether db4o should try to instantiate one instance
of each persistent class on system startup.
In a production environment this setting can be set to false,
if all persistent classes have public default constructors.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
Default value: truethe desired settingspecifies the global updateDepth.
specifies the global updateDepth.
see the documentation of
for further details.
The value be may be overridden for individual classes.
The default setting is 1: Only the object passed to
Db4objects.Db4o.IObjectContainer.Store(object)
will be updated.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
the depth of the desired update.IObjectClass.UpdateDepth(int)IObjectClass.CascadeOnUpdate(bool)
Using callbacksturns weak reference management on or off.
turns weak reference management on or off.
This method must be called before opening a database.
Performance may be improved by running db4o without using weak
references durring memory management at the cost of higher
memory consumption or by alternatively implementing a manual
memory management scheme using
Db4objects.Db4o.Ext.IExtObjectContainer.Purge(object)
Setting the value to false causes db4o to use hard
references to objects, preventing the garbage collection process
from disposing of unused objects.
The default setting is true.
Ignored on JDKs before 1.2.
configures the timer for WeakReference collection.
configures the timer for WeakReference collection.
The default setting is 1000 milliseconds.
Configure this setting to zero to turn WeakReference
collection off.
Ignored on JDKs before 1.2.
the time in millisecondsDb4objects.Db4o.Foundation.IEnvironment
A configuration provider that provides access to
the common configuration methods that can be called
for embedded, server and client use of db4o.
A configuration provider that provides access to
the common configuration methods that can be called
for embedded, server and client use of db4o.
7.5Access to the common configuration methods.Access to the common configuration methods.configuration interface.
configuration interface.
This interface contains methods to configure db4o.
The global Configuration context is available with
Db4objects.Db4o.Db4oFactory.Configure()
.
When an ObjectContainer or ObjectServer is opened, the global Configuration
context is cloned and copied into the ObjectContainer/ObjectServer.
That means every ObjectContainer/ObjectServer gets it's own copy of
configuration settings.
Most configuration settings should be set before opening an
ObjectContainer/ObjectServer.
Some configuration settings can be modified on an open
ObjectContainer/ObjectServer. The local Configuration context is
available with
Db4objects.Db4o.Ext.IExtObjectContainer.Configure()
and
Db4objects.Db4o.Ext.IExtObjectServer.Configure()
.
sets the activation depth to the specified value.
sets the activation depth to the specified value.
Why activation?
When objects are instantiated from the database, the instantiation of member
objects needs to be limited to a certain depth. Otherwise a single object
could lead to loading the complete database into memory, if all objects where
reachable from a single root object.
db4o uses the concept "depth", the number of field-to-field hops an object
is away from another object. The preconfigured "activation depth" db4o uses
in the default setting is 5.
Whenever an application iterates through the
IObjectSet
of a query result, the result objects
will be activated to the configured activation depth.
A concrete example with the preconfigured activation depth of 5:
// Object foo is the result of a query, it is delivered by the ObjectSet
object foo = objectSet.Next();
foo.member1.member2.member3.member4.member5 will be a valid object
foo, member1, member2, member3 and member4 will be activated
member5 will be deactivated, all of it's members will be null
member5 can be activated at any time by calling
IObjectContainer.Activate(member5, depth)
.
Note that raising the global activation depth will consume more memory and
have negative effects on the performance of first-time retrievals. Lowering
the global activation depth needs more individual activation work but can
increase performance of queries.
IObjectContainer.Deactivate(object, depth)
can be used to manually free memory by deactivating objects.
In client/server environment the same setting should be used on both
client and server
.
the desired global activation depth.
configuring classes individually
gets the configured activation depth.gets the configured activation depth.gets the configured activation depth.the configured activation depth.
adds ConfigurationItems to be applied when
an ObjectContainer or ObjectServer is opened.
adds ConfigurationItems to be applied when
an ObjectContainer or ObjectServer is opened.
the ConfigurationItem
adds a new Alias for a class, namespace or package.
adds a new Alias for a class, namespace or package.
Aliases can be used to persist classes in the running application
to different persistent classes in a database file or on a db4o
server.
Two simple Alias implementations are supplied along with db4o:
-
TypeAlias
provides an #equals() resolver to match names directly.
-
WildcardAlias
allows simple pattern matching with one single '*' wildcard
character.
It is possible to create own complex
IAlias
constructs by creating own resolvers that implement the
IAlias
interface.
Four examples of concrete usecases:
// Creating an Alias for a single class
Db4oFactory.Configure().AddAlias(
new TypeAlias("Tutorial.F1.Pilot", "Tutorial.F1.Driver"));
// Accessing a Java package from a .NET assembly
Db4o.configure().addAlias(
new WildcardAlias(
"com.f1.*",
"Tutorial.F1.*, Tutorial"));
// Using a different local .NET assembly
Db4o.configure().addAlias(
new WildcardAlias(
"Tutorial.F1.*, Tutorial",
"Tutorial.F1.*, RaceClient"));
Aliases that translate the persistent name of a class to
a name that already exists as a persistent name in the database
(or on the server) are not permitted and will throw an exception
when the database file is opened.
Aliases should be configured before opening a database file
or connecting to a server.
Removes an alias previously added with
AddAlias(IAlias)
.
the alias to remove
turns automatic database file format version updates on.
turns automatic database file format version updates on.
Upon db4o database file format version changes,
db4o can automatically update database files to the
current version. db4objects does not provide functionality
to reverse this process. It is not ensured that updated
database files can be read with older db4o versions.
In some cases (Example: using ObjectManager) it may not be
desirable to update database files automatically therefore
automatic updating is turned off by default for
security reasons.
Call this method to turn automatic database file
version updating on.
If automatic updating is turned off, db4o will refuse
to open database files that use an older database file format.
In client-server environment this setting should be used on both client
and server.
turns automatic shutdown of the engine on and off.
turns automatic shutdown of the engine on and off.
whether db4o should shut down automatically.
sets the storage data blocksize for new ObjectContainers.
sets the storage data blocksize for new ObjectContainers.
The standard setting is 1 allowing for a maximum
database file size of 2GB. This value can be increased
to allow larger database files, although some space will
be lost to padding because the size of some stored objects
will not be an exact multiple of the block size. A
recommended setting for large database files is 8, since
internal pointers have this length.
This setting is only effective when the database is first created, in
client-server environment in most cases it means that the setting
should be used on the server side.
the size in bytes from 1 to 127
configures the size of BTree nodes in indexes.
configures the size of BTree nodes in indexes.
Default setting: 100
Lower values will allow a lower memory footprint
and more efficient reading and writing of small slots.
Higher values will reduce the overall number of
read and write operations and allow better performance
at the cost of more RAM use.
This setting should be used on both client and server in
client-server environment.
the number of elements held in one BTree node.
configures caching of BTree nodes.
configures caching of BTree nodes.
Clean BTree nodes will be unloaded on #commit and
#rollback unless they are configured as cached here.
Default setting: 0
Possible settings: 1, 2 or 3
The potential number of cached BTree nodes can be
calculated with the following formula:
maxCachedNodes = bTreeNodeSize ^ bTreeCacheHeight
This setting should be used on both client and server in
client-server environment.
the height of the cache from the root
returns the Cache configuration interface.returns the Cache configuration interface.turns callback methods on and off.
turns callback methods on and off.
Callbacks are turned on by default.
A tuning hint: If callbacks are not used, you can turn this feature off, to
prevent db4o from looking for callback methods in persistent classes. This will
increase the performance on system startup.
In client/server environment this setting should be used on both
client and server.
false to turn callback methods off
Using callbacks
advises db4o to try instantiating objects with/without calling
constructors.
advises db4o to try instantiating objects with/without calling
constructors.
Not all .NET-environments support this feature. db4o will
attempt, to follow the setting as good as the enviroment supports.
This setting may also be overridden for individual classes in
Db4objects.Db4o.Config.IObjectClass.CallConstructor
.
The default setting depends on the features supported by your current environment.
In client/server environment this setting should be used on both
client and server.
- specify true, to request calling constructors, specify
false to request not calling constructors.
Db4objects.Db4o.Config.IObjectClass.CallConstructor
turns
individual class activation depth configuration
on
and off.
This feature is turned on by default.
In client/server environment this setting should be used on both
client and server.
false to turn the possibility to individually configure class
activation depths off
Why activation?returns client/server configuration interface.returns client/server configuration interface.
configures the size database files should grow in bytes, when no
free slot is found within.
configures the size database files should grow in bytes, when no
free slot is found within.
Tuning setting.
Whenever no free slot of sufficient length can be found
within the current database file, the database file's length
is extended. This configuration setting configures by how much
it should be extended, in bytes.
This configuration setting is intended to reduce fragmentation.
Higher values will produce bigger database files and less
fragmentation.
To extend the database file, a single byte array is created
and written to the end of the file in one write operation. Be
aware that a high setting will require allocating memory for
this byte array.
amount of bytes
tuning feature: configures whether db4o checks all persistent classes upon system
startup, for added or removed fields.
tuning feature: configures whether db4o checks all persistent classes upon system
startup, for added or removed fields.
If this configuration setting is set to false while a database is
being created, members of classes will not be detected and stored.
This setting can be set to false in a production environment after
all persistent classes have been stored at least once and classes will not
be modified any further in the future.
In a client/server environment this setting should be configured both on the
client and and on the server.
Default value: true
the desired setting
returns the configuration interface for diagnostics.returns the configuration interface for diagnostics.the configuration interface for diagnostics.turns commit recovery off.
turns commit recovery off.
db4o uses a two-phase commit algorithm. In a first step all intended
changes are written to a free place in the database file, the "transaction commit
record". In a second step the
actual changes are performed. If the system breaks down during commit, the
commit process is restarted when the database file is opened the next time.
On very rare occasions (possibilities: hardware failure or editing the database
file with an external tool) the transaction commit record may be broken. In this
case, this method can be used to try to open the database file without commit
recovery. The method should only be used in emergency situations after consulting
db4o support.
configures the use of encryption.
configures the use of encryption.
This method needs to be called before a database file
is created with the first
Db4objects.Db4o.Db4oFactory.OpenFile(string)
.
If encryption is set to true,
you need to supply a password to seed the encryption mechanism.
db4o database files keep their encryption format after creation.
true for turning encryption on, false for turning encryption
off.
Password(string)configures whether Exceptions are to be thrown, if objects can not be stored.
configures whether Exceptions are to be thrown, if objects can not be stored.
db4o requires the presence of a constructor that can be used to
instantiate objects. If no default public constructor is present, all
available constructors are tested, whether an instance of the class can
be instantiated. Null is passed to all constructor parameters.
The first constructor that is successfully tested will
be used throughout the running db4o session. If an instance of the class
can not be instantiated, the object will not be stored. By default,
execution will continue without any message or error. This method can
be used to configure db4o to throw an
ObjectNotStorableException
if an object can not be stored.
The default for this setting is true.
In client/server environment this setting should be used on both
client and server.
false to not throw Exceptions if objects can not be stored (fail silently).
returns the freespace configuration interface.returns the freespace configuration interface.configures db4o to generate UUIDs for stored objects.
configures db4o to generate UUIDs for stored objects.
This setting should be used when the database is first created.
the scope for UUID generation: disabled, generate for all classes, or configure individually
configures db4o to generate version numbers for stored objects.
configures db4o to generate version numbers for stored objects.
This setting should be used when the database is first created.
the scope for version number generation: disabled, generate for all classes, or configure individually
Configures db4o to generate commit timestamps for all stored objects.
All the objects commited within a transaction will share the same commit timestamp.
Configures db4o to generate commit timestamps for all stored objects.
All the objects commited within a transaction will share the same commit timestamp.
This setting should be used when the database is first created.
Afterwards you can access the object's commit timestamp like this:
if true, commit timetamps will be generated for all stored
objects. If you already have commit timestamps for stored
objects and later set this flag to false, although you wont be
able to access them, the commit timestamps will still be taking
space in your file container. The only way to free that space
is defragmenting the container.
8.0configures db4o to call #intern() on strings upon retrieval.
configures db4o to call #intern() on strings upon retrieval.
In client/server environment the setting should be used on both
client and server.
true to intern strings
returns true if strings will be interned.returns true if strings will be interned.allows to configure db4o to use a customized byte IO adapter.
allows to configure db4o to use a customized byte IO adapter.
Derive from the abstract class
Db4objects.Db4o.IO.IoAdapter
to
write your own. Possible usecases could be improved performance
with a native library, mirrored write to two files, encryption or
read-on-write fail-safety control.
An example of a custom
io adapter can be found in xtea_db4o community project:
http://developer.db4o.com/ProjectSpaces/view.aspx/XTEA
In client-server environment this setting should be used on the server
(adapter class must be available)
- the IoAdapter
returns the configured
Db4objects.Db4o.IO.IoAdapter
.
allows to mark fields as transient with custom attributes.
allows to mark fields as transient with custom attributes.
.NET only: Call this method with the attribute name that you
wish to use to mark fields as transient. Multiple transient attributes
are possible by calling this method multiple times with different
attribute names.
In client/server environment the setting should be used on both
client and server.
- the fully qualified name of the attribute, including
it's namespace
sets the detail level of db4o messages.
sets the detail level of db4o messages. Messages will be output to the
configured output
TextWriter
.
Level 0 - no messages
Level 1 - open and close messages
Level 2 - messages for new, update and delete
Level 3 - messages for activate and deactivate
When using client-server and the level is set to 0, the server will override this and set it to 1. To get around this you can set the level to -1. This has the effect of not returning any messages.
In client-server environment this setting can be used on client or on server
depending on which information do you want to track (server side provides more
detailed information).
integer from 0 to 3
SetOut(System.IO.TextWriter)can be used to turn the database file locking thread off.false to turn database file locking off.
returns an
IObjectClass
object
to configure the specified class.
The clazz parameter can be any of the following:
- a fully qualified classname as a String.
- a Class object.
- any other object to be used as a template.
class name, Class object, or example object.
an instance of an
IObjectClass
object for configuration.
If set to true, db4o will try to optimize native queries
dynamically at query execution time, otherwise it will
run native queries in unoptimized mode as SODA evaluations.
If set to true, db4o will try to optimize native queries
dynamically at query execution time, otherwise it will
run native queries in unoptimized mode as SODA evaluations.
The following assemblies should be available for native query switch to take effect:
Db4objects.Db4o.NativeQueries.dll, Db4objects.Db4o.Instrumentation.dll.
The default setting is true.
In client-server environment this setting should be used on both client and server.
true, if db4o should try to optimize
native queries at query execution time, false otherwise
Db4objects.Db4o.Config.ICommonConfiguration.OptimizeNativeQueriesindicates whether Native Queries will be optimized dynamically.indicates whether Native Queries will be optimized dynamically.
boolean true if Native Queries will be optimized
dynamically.
OptimizeNativeQueries()protects the database file with a password.
protects the database file with a password.
To set a password for a database file, this method needs to be
called before a database file is created with the first
Db4objects.Db4o.Db4oFactory.OpenFile(string)
.
All further attempts to open
the file, are required to set the same password.
The password
is used to seed the encryption mechanism, which makes it impossible
to read the database file without knowing the password.
the password to be used.
returns the Query configuration interface.returns the Query configuration interface.turns readOnly mode on and off.
turns readOnly mode on and off.
This method configures the mode in which subsequent calls to
Db4o.openFile()
will open files.
Readonly mode allows to open an unlimited number of reading
processes on one database file. It is also convenient
for deploying db4o database files on CD-ROM.
In client-server environment this setting should be used on the server side
in embedded mode and ONLY on client side in networked mode.
true for configuring readOnly mode for subsequent
calls to
Db4o.openFile()
.
turns recovery mode on and off.
Recovery mode can be used to try to retrieve as much as possible
out of an already corrupted database.
turns recovery mode on and off.
Recovery mode can be used to try to retrieve as much as possible
out of an already corrupted database. In recovery mode internal
checks are more relaxed. Null or invalid objects may be returned
instead of throwing exceptions.
Use this method with care as a last resort to get data out of a
corrupted database.
true to turn recover mode on.
configures the use of a specially designed reflection implementation.
configures the use of a specially designed reflection implementation.
db4o internally uses System.Reflection by default. On platforms that
do not support this package, customized implementations may be written
to supply all the functionality of the interfaces in System.Reflection
namespace. This method can be used to install a custom reflection
implementation.
tuning feature only: reserves a number of bytes in database files.
tuning feature only: reserves a number of bytes in database files.
The global setting is used for the creation of new database
files. Continous calls on an ObjectContainer Configuration context
(see
Db4objects.Db4o.Ext.IExtObjectContainer.Configure()
) will
continually allocate space.
The allocation of a fixed number of bytes at one time
makes it more likely that the database will be stored in one
chunk on the mass storage. Less read/write head movement can result
in improved performance.
Note: Allocated space will be lost on abnormal termination
of the database engine (hardware crash, VM crash). A Defragment run
will recover the lost space. For the best possible performance, this
method should be called before the Defragment run to configure the
allocation of storage space to be slightly greater than the anticipated
database file size.
In client-server environment this setting should be used on the server side.
Default configuration: 0
the number of bytes to reserve
configures the path to be used to store and read
Blob data.
configures the path to be used to store and read
Blob data.
In client-server environment this setting should be used on the
server side.
the path to be used
Assigns a
TextWriter
where db4o is to print its event messages.
Messages are useful for debugging purposes and for learning
to understand, how db4o works. The message level can be raised with
MessageLevel(int)
to produce more detailed messages.
Use setOut(System.out) to print messages to the
console.
In client-server environment this setting should be used on the same side
where
MessageLevel(int)
is used.
the new PrintStream for messages.
MessageLevel(int)configures the string encoding to be used.
configures the string encoding to be used.
The string encoding can not be changed in the lifetime of a
database file. To set up the database with the correct string encoding,
this configuration needs to be set correctly before a database
file is created with the first call to
Db4objects.Db4o.Db4oFactory.OpenFile
or
Db4objects.Db4o.Db4oFactory.OpenServer
.
For subsequent open calls, db4o remembers built-in
string encodings. If a custom encoding is used (an encoding that is
not supplied from within the db4o library), the correct encoding
needs to be configured correctly again for all subsequent calls
that open database files.
Example: config.StringEncoding(StringEncodings.Utf8());Db4objects.Db4o.Config.Encoding.StringEncodings
tuning feature: configures whether db4o should try to instantiate one instance
of each persistent class on system startup.
tuning feature: configures whether db4o should try to instantiate one instance
of each persistent class on system startup.
In a production environment this setting can be set to false,
if all persistent classes have public default constructors.
In client-server environment this setting should be used on both client and server
side.
Default value: true
the desired setting
specifies the global updateDepth.
specifies the global updateDepth.
see the documentation of
for further details.
The value be may be overridden for individual classes.
The default setting is 1: Only the object passed to
com.db4o.ObjectContainer#set
will be updated.
In client-server environment this setting should be used on both client and
server sides.
the depth of the desired update.
IObjectClass.UpdateDepth(int)IObjectClass.CascadeOnUpdate(bool)
Using callbacksturns weak reference management on or off.
turns weak reference management on or off.
This method must be called before opening a database.
Performance may be improved by running db4o without using weak
references durring memory management at the cost of higher
memory consumption or by alternatively implementing a manual
memory management scheme using
IExtObjectContainer.Purge
Setting the value to false causes db4o to use hard
references to objects, preventing the garbage collection process
from disposing of unused objects.
The default setting is true.
configures the timer for WeakReference collection.
configures the timer for WeakReference collection.
The default setting is 1000 milliseconds.
Configure this setting to zero to turn WeakReference
collection off.
the time in milliseconds
allows registering special TypeHandlers for customized marshalling
and customized comparisons.
allows registering special TypeHandlers for customized marshalling
and customized comparisons.
to specify for which classes and versions the
TypeHandler is to be used.
to be used for the classes that match the predicate.
ICommonConfiguration.MaxStackDepth()
allows to configure db4o to use a customized byte IO storage mechanism.
allows to configure db4o to use a customized byte IO storage mechanism.
Implement the interface
Db4objects.Db4o.IO.IStorage
to
write your own. Possible usecases could be improved performance
with a native library, mirrored write to two files, encryption or
read-on-write fail-safety control.
- the factoryDb4objects.Db4o.IO.CachingStorage
Db4objects.Db4o.IO.MemoryStorage
Db4objects.Db4o.IO.FileStorageDb4objects.Db4o.IO.StorageDecorator
returns the configured
Db4objects.Db4o.IO.IStorage
Implement this interface for configuration items that encapsulate
a batch of configuration settings or that need to be applied
to ObjectContainers after they are opened.
Implement this interface for configuration items that encapsulate
a batch of configuration settings or that need to be applied
to ObjectContainers after they are opened.
Gives a chance for the item to augment the configuration.Gives a chance for the item to augment the configuration.
the configuration that the item was added to
Gives a chance for the item to configure the just opened ObjectContainer.
Gives a chance for the item to configure the just opened ObjectContainer.
the ObjectContainer to configure
Configuration interface for db4o in embedded use.Configuration interface for db4o in embedded use.7.5
A configuration provider that provides access
to the file-related configuration methods.
A configuration provider that provides access
to the file-related configuration methods.
Access to the file-related configuration methods.Access to the file-related configuration methods.
A configuration provider that provides access
to the IdSystem-related configuration methods.
A configuration provider that provides access
to the IdSystem-related configuration methods.
Access to the IdSystem-related configuration methods.Access to the IdSystem-related configuration methods.
adds ConfigurationItems to be applied when
a networking
EmbeddedObjectContainer
is opened.
the
IEmbeddedConfigurationItem7.12
Implement this interface for configuration items that encapsulate
a batch of configuration settings or that need to be applied
to EmbeddedObjectContainers after they are opened.
Implement this interface for configuration items that encapsulate
a batch of configuration settings or that need to be applied
to EmbeddedObjectContainers after they are opened.
7.12Gives a chance for the item to augment the configuration.Gives a chance for the item to augment the configuration.
the configuration that the item was added to
Gives a chance for the item to configure the just opened ObjectContainer.
Gives a chance for the item to configure the just opened ObjectContainer.
the ObjectContainer to configure
Configures the environment (set of services) used by db4o.Configures the environment (set of services) used by db4o.Db4objects.Db4o.Foundation.IEnvironment
Db4objects.Db4o.Foundation.Environments.My(System.Type<T>)
Contributes a service to the db4o environment.Contributes a service to the db4o environment.
File-related configuration methods, applicable
for db4o embedded use and on the server in a
Client/Server setup.
File-related configuration methods, applicable
for db4o embedded use and on the server in a
Client/Server setup.
7.5IFileConfigurationProvider.File()
turns commit recovery off.
turns commit recovery off.
db4o uses a two-phase commit algorithm. In a first step all intended
changes are written to a free place in the database file, the "transaction commit
record". In a second step the
actual changes are performed. If the system breaks down during commit, the
commit process is restarted when the database file is opened the next time.
On very rare occasions (possibilities: hardware failure or editing the database
file with an external tool) the transaction commit record may be broken. In this
case, this method can be used to try to open the database file without commit
recovery. The method should only be used in emergency situations after consulting
db4o support.
sets the storage data blocksize for new ObjectContainers.
sets the storage data blocksize for new ObjectContainers.
The standard setting is 1 allowing for a maximum
database file size of 2GB. This value can be increased
to allow larger database files, although some space will
be lost to padding because the size of some stored objects
will not be an exact multiple of the block size. A
recommended setting for large database files is 8, since
internal pointers have this length.
This setting is only effective when the database is first created.
the size in bytes from 1 to 127
configures the size database files should grow in bytes, when no
free slot is found within.
configures the size database files should grow in bytes, when no
free slot is found within.
Tuning setting.
Whenever no free slot of sufficient length can be found
within the current database file, the database file's length
is extended. This configuration setting configures by how much
it should be extended, in bytes.
This configuration setting is intended to reduce fragmentation.
Higher values will produce bigger database files and less
fragmentation.
To extend the database file, a single byte array is created
and written to the end of the file in one write operation. Be
aware that a high setting will require allocating memory for
this byte array.
amount of bytesreturns the freespace configuration interface.returns the freespace configuration interface.configures db4o to generate UUIDs for stored objects.
configures db4o to generate UUIDs for stored objects.
This setting should be used when the database is first created.
the scope for UUID generation: disabled, generate for all classes, or configure individually
configures db4o to generate version numbers for stored objects.
configures db4o to generate version numbers for stored objects.
This setting should be used when the database is first created.
the scope for version number generation: disabled, generate for all classes, or configure individually
Configures db4o to generate commit timestamps for all stored objects.
All the objects commited within a transaction will share the same commit timestamp.
Configures db4o to generate commit timestamps for all stored objects.
All the objects commited within a transaction will share the same commit timestamp.
This setting should be used when the database is first created.
Afterwards you can access the object's commit timestamp like this:
if true, commit timetamps will be generated for all stored
objects. If you already have commit timestamps for stored
objects and later set this flag to false, although you wont be
able to access them, the commit timestamps will still be taking
space in your file container. The only way to free that space
is defragmenting the container.
8.0allows to configure db4o to use a customized byte IO storage mechanism.
allows to configure db4o to use a customized byte IO storage mechanism.
You can implement the interface
Db4objects.Db4o.IO.IStorage
to
write your own. Possible usecases could be improved performance
with a native library, mirrored write to two files, encryption or
read-on-write fail-safety control.
- the storageDb4objects.Db4o.IO.FileStorageDb4objects.Db4o.IO.CachingStorage
Db4objects.Db4o.IO.MemoryStorage
returns the configured
Db4objects.Db4o.IO.IStorage
.
can be used to turn the database file locking thread off.
can be used to turn the database file locking thread off.
Caution! If database file
locking is turned off, concurrent write access to the same
database file from different sessions will corrupt the
database file immediately.
This method
has no effect on open ObjectContainers. It will only affect how
ObjectContainers are opened.
The default setting is true.
tuning feature only: reserves a number of bytes in database files.
tuning feature only: reserves a number of bytes in database files.
The global setting is used for the creation of new database
files.
Without this setting, storage space will be allocated
continuously as required. However, allocation of a fixed number
of bytes at one time makes it more likely that the database will be
stored in one chunk on the mass storage. Less read/write head movement
can result in improved performance.
Note: Allocated space will be lost on abnormal termination
of the database engine (hardware crash, VM crash). A Defragment run
will recover the lost space. For the best possible performance, this
method should be called before the Defragment run to configure the
allocation of storage space to be slightly greater than the anticipated
database file size.
Default configuration: 0
the number of bytes to reserve
configures the path to be used to store and read
Blob data.
configures the path to be used to store and read
Blob data.
the path to be usedturns readOnly mode on and off.
turns readOnly mode on and off.
This method configures the mode in which subsequent calls to
Db4objects.Db4o.Db4oEmbedded.OpenFile(IEmbeddedConfiguration, string)
will open files.
Readonly mode allows to open an unlimited number of reading
processes on one database file. It is also convenient
for deploying db4o database files on CD-ROM.
true for configuring readOnly mode for subsequent
calls to
Db4o.openFile()
.
TODO: this is rather embedded + client than base?
turns recovery mode on and off.
Recovery mode can be used to try to retrieve as much as possible
out of an already corrupted database.
turns recovery mode on and off.
Recovery mode can be used to try to retrieve as much as possible
out of an already corrupted database. In recovery mode internal
checks are more relaxed. Null or invalid objects may be returned
instead of throwing exceptions.
Use this method with care as a last resort to get data out of a
corrupted database.
true to turn recover mode on.
turns asynchronous sync on and off.
One of the most costly operations during commit is the call to
flush the buffers of the database file.
turns asynchronous sync on and off.
One of the most costly operations during commit is the call to
flush the buffers of the database file. In regular mode the
commit call has to wait until this operation has completed.
When asynchronous sync is turned on, the sync operation will
run in a dedicated thread, blocking all other file access
until it has completed. This way the commit call can return
immediately. This will allow db4o and other processes to
continue running side-by-side while the flush call executes.
Use this setting with care: It means that you can not be sure
when a commit call has actually made the changes of a
transaction durable (flushed through OS and file system
buffers). The latency time until flushing happens is extremely
short. The dedicated sync thread does nothing else
except for calling sync and writing the header of the database
file when needed. A setup with this option still guarantees
ACID transaction processing: A database file always will be
either in the state before commit or in the state after
commit. Corruption can not occur. You can just not rely
on the transaction already having been applied when the
commit() call returns.
interface to configure the freespace system to be used.
interface to configure the freespace system to be used.
All methods should be called before opening database files.
If db4o is instructed to exchange the system
(
UseBTreeSystem()
,
UseRamSystem()
)
this will happen on opening the database file.
By default the ram based system will be used.
tuning feature: configures the minimum size of free space slots in the database file
that are to be reused.
tuning feature: configures the minimum size of free space slots in the database file
that are to be reused.
When objects are updated or deleted, the space previously occupied in the
database file is marked as "free", so it can be reused. db4o maintains two lists
in RAM, sorted by address and by size. Adjacent entries are merged. After a large
number of updates or deletes have been executed, the lists can become large, causing
RAM consumption and performance loss for maintenance. With this method you can
specify an upper bound for the byte slot size to discard.
Pass Integer.MAX_VALUE to this method to discard all free slots for
the best possible startup time.
The downside of setting this value: Database files will necessarily grow faster.
Default value: 0 all space is reused
Slots with this size or smaller will be lost.
Configure a way to overwrite freed space in the database file with custom
(for example: random) bytes.
Configure a way to overwrite freed space in the database file with custom
(for example: random) bytes. Will slow down I/O operation.
The value of this setting may be cached internally and can thus not be
reliably set after an object container has been opened.
The freespace overwriting callback to use
configures db4o to use a BTree-based freespace system.
configures db4o to use a BTree-based freespace system.
Advantages
- ACID, no freespace is lost on abnormal system termination
- low memory consumption
Disadvantages
- slower than the RAM-based system, since freespace information
is written during every commit discontinued freespace system, only available before db4o 7.0.discontinued freespace system, only available before db4o 7.0.configures db4o to use a RAM-based freespace system.
configures db4o to use a RAM-based freespace system.
Advantages
- best performance
Disadvantages
- upon abnormal system termination all freespace is lost
- memory consumption Callback hook for overwriting freed space in the database file.Callback hook for overwriting freed space in the database file.Called to overwrite freed space in the database file.Called to overwrite freed space in the database file.
Handle for the freed slot
Interface to configure the IdSystem.Interface to configure the IdSystem.configures db4o to store IDs as pointers.configures db4o to store IDs as pointers.
configures db4o to use a stack of two BTreeIdSystems on
top of an InMemoryIdSystem.
configures db4o to use a stack of two BTreeIdSystems on
top of an InMemoryIdSystem. This setup is scalable for
large numbers of IDs. It is the default configuration
when new databases are created.
configures db4o to use a single BTreeIdSystem on
top of an InMemoryIdSystem.
configures db4o to use a single BTreeIdSystem on
top of an InMemoryIdSystem. This setup is suitable for
smaller databases with a small number of IDs.
For larger numbers of IDs call
UseStackedBTreeSystem()
.
configures db4o to use an in-memory ID system.
configures db4o to use an in-memory ID system.
All IDs get written to the database file on every commit.
configures db4o to use a custom ID system.
configures db4o to use a custom ID system.
Pass an
IIdSystemFactory
that creates the IdSystem.
Note that this factory has to be configured every time you
open a database that you configured to use a custom IdSystem.
Factory interface to create a custom IdSystem.Factory interface to create a custom IdSystem.createsA provider for custom database names.A provider for custom database names.
Derives a name for the given
Db4objects.Db4o.IObjectContainer
. This method will be called when
database startup has completed, i.e. the method will see a completely initialized
Db4objects.Db4o.IObjectContainer
.
Any code invoked during the startup process (for example
IConfigurationItem
instances) will still
see the default naming.
generic interface to allow returning an attribute of an object.generic interface to allow returning an attribute of an object.generic method to return an attribute of a parent object.generic method to return an attribute of a parent object.
the parent object
Object - the attributeconfiguration interface for classes.
configuration interface for classes.
Use the global
ICommonConfiguration.ObjectClass(object)
to configure
object class settings.
advises db4o to try instantiating objects of this class with/without
calling constructors.
advises db4o to try instantiating objects of this class with/without
calling constructors.
Not all .NET-environments support this feature. db4o will
attempt, to follow the setting as good as the enviroment supports.
This setting may also be set globally for all classes in
Db4objects.Db4o.Config.IConfiguration.CallConstructors
.
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
- specify true, to request calling constructors, specify
false to request not calling constructors.
Db4objects.Db4o.Config.IConfiguration.CallConstructors
sets cascaded activation behaviour.
sets cascaded activation behaviour.
Setting cascadeOnActivate to true will result in the activation
of all member objects if an instance of this class is activated.
The default setting is false.
In client-server environment this setting should be used on both
client and server.
Can be applied to an open ObjectContainer.
whether activation is to be cascaded to member objects.
IObjectField.CascadeOnActivate(bool)
Db4objects.Db4o.IObjectContainer.Activate(object, int)
Using callbacksWhy activation?sets cascaded delete behaviour.
sets cascaded delete behaviour.
Setting CascadeOnDelete to true will result in the deletion of
all member objects of instances of this class, if they are
passed to
Db4objects.Db4o.IObjectContainer.Delete
.
Caution !
This setting will also trigger deletion of old member objects, on
calls to
Db4objects.Db4o.IObjectContainer.Store
.
An example of the behaviour:
ObjectContainer con;
Bar bar1 = new Bar();
Bar bar2 = new Bar();
foo.bar = bar1;
con.Store(foo); // bar1 is stored as a member of foo
foo.bar = bar2;
con.Store(foo); // bar2 is stored as a member of foo
The last statement will also delete bar1 from the
ObjectContainer, no matter how many other stored objects hold references
to bar1.
The default setting is false.
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
whether deletes are to be cascaded to member objects.
Db4objects.Db4o.Config.IObjectField.CascadeOnDelete
Db4objects.Db4o.IObjectContainer.Delete
Using callbackssets cascaded update behaviour.
sets cascaded update behaviour.
Setting cascadeOnUpdate to true will result in the update
of all member objects if a stored instance of this class is passed
to
Db4objects.Db4o.IObjectContainer.Store(object)
.
The default setting is false. Setting it to true
may result in serious performance degradation.
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
whether updates are to be cascaded to member objects.
IObjectField.CascadeOnUpdate(bool)
com.db4o.ObjectContainer#setUsing callbacksregisters an attribute provider for special query behavior.
registers an attribute provider for special query behavior.
The query processor will compare the object returned by the
attribute provider instead of the actual object, both for the constraint
and the candidate persistent object.
In client-server environment this setting should be used on both
client and server.
the attribute provider to be used
Must be called before databases are created or opened
so that db4o will control versions and generate UUIDs
for objects of this class, which is required for using replication.
Must be called before databases are created or opened
so that db4o will control versions and generate UUIDs
for objects of this class, which is required for using replication.
generate UUIDs for stored objects of this class.
generate UUIDs for stored objects of this class.
This setting should be used before the database is first created.
generate version numbers for stored objects of this class.
generate version numbers for stored objects of this class.
This setting should be used before the database is first created.
turns the class index on or off.
turns the class index on or off.
db4o maintains an index for each class to be able to
deliver all instances of a class in a query. If the class
index is never needed, it can be turned off with this method
to improve the performance to create and delete objects of
a class.
Common cases where a class index is not needed:
- The application always works with sub classes or super classes.
- There are convenient field indexes that will always find instances
of a class.
- The application always works with IDs.
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
sets the maximum activation depth to the desired value.
sets the maximum activation depth to the desired value.
A class specific setting overrides the
global setting
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
the desired maximum activation depth
Why activation?CascadeOnActivate(bool)sets the minimum activation depth to the desired value.
sets the minimum activation depth to the desired value.
A class specific setting overrides the
global setting
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
the desired minimum activation depth
Why activation?CascadeOnActivate(bool)gets the configured minimum activation depth.
gets the configured minimum activation depth.
In client-server environment this setting should be used on both
client and server.
the configured minimum activation depth.
returns an
IObjectField
object
to configure the specified field.
the name of the field to be configured.
an instance of an
IObjectField
object for configuration.
turns on storing static field values for this class.
turns on storing static field values for this class.
By default, static field values of classes are not stored
to the database file. By turning the setting on for a specific class
with this switch, all non-simple-typed static field values of this
class are stored the first time an object of the class is stored, and
restored, every time a database file is opened afterwards, after
class meta information is loaded for this class (which can happen
by querying for a class or by loading an instance of a class).
To update a static field value, once it is stored, you have to the following
in this order:
(1) open the database file you are working agains
(2) make sure the class metadata is loaded objectContainer.Query().Constrain(typeof(Foo));
(3) change the static member
(4) store the static member explicitely objectContainer.Store(Foo.staticMember);
The setting will be ignored for simple types.
Use this setting for constant static object members.
This option will slow down the process of opening database
files and the stored objects will occupy space in the database file.
In client-server environment this setting should be used on both
client and server.
This setting can NOT be applied to an open object container.
renames a stored class.
renames a stored class.
Use this method to refactor classes.
In client-server environment this setting should be used on both
client and server.
This setting can NOT be applied to an open object container.
the new fully qualified class name.
allows to specify if transient fields are to be stored.
allows to specify if transient fields are to be stored.
The default for every class is false.
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
whether or not transient fields are to be stored.
registers a translator for this class.
registers a translator for this class.
The use of an
IObjectTranslator
is not
compatible with the use of an
internal class ObjectMarshaller.
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
this may be an
IObjectTranslator
or an
IObjectConstructorIObjectTranslatorIObjectConstructorspecifies the updateDepth for this class.
specifies the updateDepth for this class.
see the documentation of
Db4objects.Db4o.IObjectContainer.Store(object)
for further details.
The default setting is 0: Only the object passed to
Db4objects.Db4o.IObjectContainer.Store(object)
will be updated.
In client-server environment this setting should be used on both
client and server.
the depth of the desired update for this class.
IConfiguration.UpdateDepth(int)CascadeOnUpdate(bool)IObjectField.CascadeOnUpdate(bool)
Using callbacks
interface to allow instantiating objects by calling specific constructors.
interface to allow instantiating objects by calling specific constructors.
By writing classes that implement this interface, it is possible to
define which constructor is to be used during the instantiation of a stored object.
Before starting a db4o session, translator classes that implement the
ObjectConstructor or
IObjectTranslator
need to be registered.
translator interface to translate objects on storage and activation.
translator interface to translate objects on storage and activation.
By writing classes that implement this interface, it is possible to
define how application classes are to be converted to be stored more efficiently.
Before starting a db4o session, translator classes need to be registered. An example:
IObjectClass oc = config.ObjectClass("Namespace.ClassName");
oc.Translate(new FooTranslator());
db4o calls this method during storage and query evaluation.db4o calls this method during storage and query evaluation.
the ObjectContainer used
the Object to be translated
return the object to store. It needs to be of the class
StoredClass()
.
db4o calls this method during activation.db4o calls this method during activation.
the ObjectContainer used
the object to set the members on
the object that was stored
return the Class you are converting to.return the Class you are converting to.
the Class of the object you are returning with the method
OnStore(Db4objects.Db4o.IObjectContainer, object)
db4o calls this method when a stored object needs to be instantiated.
db4o calls this method when a stored object needs to be instantiated.
the ObjectContainer used
the object stored with
ObjectTranslator.onStore
.
the instantiated object.configuration interface for fields of classes.
configuration interface for fields of classes.
Use
IObjectClass.ObjectField(string)
to access this setting.
Setting cascadeOnActivate to true will result in the activation
of the object attribute stored in this field if the parent object
is activated.
The default setting is false.
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
whether activation is to be cascaded to the member object.
Why activation?IObjectClass.CascadeOnActivate(bool)
Db4objects.Db4o.IObjectContainer.Activate(object, int)
Using callbackssets cascaded delete behaviour.
sets cascaded delete behaviour.
Setting cascadeOnDelete to true will result in the deletion of
the object attribute stored in this field on the parent object
if the parent object is passed to
Db4objects.Db4o.IObjectContainer.Delete(object)
.
Caution !
This setting will also trigger deletion of the old member object, on
calls to
.
An example of the behaviour can be found in
IObjectClass.CascadeOnDelete(bool)
The default setting is false.
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
whether deletes are to be cascaded to the member object.
IObjectClass.CascadeOnDelete(bool)
Db4objects.Db4o.IObjectContainer.Delete(object)
Using callbackssets cascaded update behaviour.
sets cascaded update behaviour.
Setting cascadeOnUpdate to true will result in the update
of the object attribute stored in this field if the parent object
is passed to
Db4objects.Db4o.IObjectContainer.Store(object)
.
The default setting is false.
In client-server environment this setting should be used on both
client and server.
This setting can be applied to an open object container.
whether updates are to be cascaded to the member object.
com.db4o.ObjectContainer#setIObjectClass.CascadeOnUpdate(bool)
IObjectClass.UpdateDepth(int)Using callbacksturns indexing on or off.
turns indexing on or off.
Field indices dramatically improve query performance but they may
considerably reduce storage and update performance. The best benchmark whether
or not an index on a field achieves the desired result is the completed application
- with a data load that is typical for it's use.
This configuration setting
is only checked when the
Db4objects.Db4o.IObjectContainer
is opened. If the
setting is set to true and an index does not exist, the index will be
created. If the setting is set to false and an index does exist the
index will be dropped.
In client-server environment this setting should be used on both
client and server.
If this setting is applied to an open ObjectContainer it will take an effect on the next
time ObjectContainer is opened.
specify true or false to turn indexing on for
this field
renames a field of a stored class.
renames a field of a stored class.
Use this method to refactor classes.
In client-server environment this setting should be used on both
client and server.
This setting can NOT be applied to an open object container.
the new field name.
interface to configure the querying settings to be used by the query processor.
interface to configure the querying settings to be used by the query processor.
All settings can be configured after opening an ObjectContainer.
In a Client/Server setup the client-side configuration will be used.
configures the query processor evaluation mode.
configures the query processor evaluation mode.
The db4o query processor can run in three modes:
- Immediate mode
- Snapshot mode
- Lazy mode
In Immediate mode, a query will be fully evaluated when
Db4objects.Db4o.Query.IQuery.Execute()
is called. The complete
Db4objects.Db4o.IObjectSet
of all matching IDs is
generated immediately.
In Snapshot mode, the
Db4objects.Db4o.Query.IQuery.Execute()
call will trigger all index
processing immediately. A snapshot of the current state of all relevant indexes
is taken for further processing by the SODA query processor. All non-indexed
constraints and all evaluations will be run when the user application iterates
through the resulting
Db4objects.Db4o.IObjectSet
.
In Lazy mode, the
Db4objects.Db4o.Query.IQuery.Execute()
call will only create an Iterator
against the best index found. Further query processing (including all index
processing) will happen when the user application iterates through the resulting
Db4objects.Db4o.IObjectSet
.
Advantages and disadvantages of the individual modes:
Immediate mode + If the query is intended to iterate through the entire resulting
Db4objects.Db4o.IObjectSet
,
this mode will be slightly faster than the others. + The query will process without intermediate side effects from changed
objects (by the caller or by other transactions). - Query processing can block the server for a long time. - In comparison to the other modes it will take longest until the first results
are returned. - The ObjectSet will require a considerate amount of memory to hold the IDs of
all found objects.
Snapshot mode + Index processing will happen without possible side effects from changes made
by the caller or by other transaction. + Since index processing is fast, a server will not be blocked for a long time. - The entire candidate index will be loaded into memory. It will stay there
until the query ObjectSet is garbage collected. In a C/S setup, the memory will
be used on the server side.
Lazy mode + The call to
Db4objects.Db4o.Query.IQuery.Execute()
will return very fast. First results can be
made available to the application before the query is fully processed. + A query will consume hardly any memory at all because no intermediate ID
representation is ever created. - Lazy queries check candidates when iterating through the resulting
Db4objects.Db4o.IObjectSet
.
In doing so the query processor takes changes into account that may have happened
since the Query#execute()call: committed changes from other transactions, and
uncommitted changes from the calling transaction. There is a wide range
of possible side effects. The underlying index may have changed. Objects themselves
may have changed in the meanwhile. There even is the chance of creating an endless
loop, if the caller of the iterates through the
Db4objects.Db4o.IObjectSet
and changes each
object in a way that it is placed at the end of the index: The same objects can be
revisited over and over. In lazy mode it can make sense to work in a way one would
work with collections to avoid concurrent modification exceptions. For instance one
could iterate through the
Db4objects.Db4o.IObjectSet
first and store all objects to a temporary
other collection representation before changing objects and storing them back to db4o.
Note: Some method calls against a lazy
Db4objects.Db4o.IObjectSet
will require the query
processor to create a snapshot or to evaluate the query fully. An example of such
a call is
Db4objects.Db4o.IObjectSet.Count()
.
The default query evaluation mode is Immediate mode.
Recommendations:
- Lazy mode can be an excellent choice for single transaction read use,
to keep memory consumption as low as possible.
- Client/Server applications with the risk of concurrent modifications should prefer
Snapshot mode to avoid side effects from other transactions.
To change the evaluationMode, pass any of the three static
QueryEvaluationMode
constants from the
QueryEvaluationMode
class to this method:
-
QueryEvaluationMode.Immediate
-
QueryEvaluationMode.Snapshot
-
QueryEvaluationMode.Lazy
This setting must be issued from the client side.
EvaluationMode(QueryEvaluationMode)
the currently configured query evaluation mode
This class provides static constants for the query evaluation
modes that db4o supports.
This class provides static constants for the query evaluation
modes that db4o supports.
For detailed documentation please see
IQueryConfiguration.EvaluationMode(QueryEvaluationMode)
Constant for immediate query evaluation.
Constant for immediate query evaluation. The query is executed fully
when
Db4objects.Db4o.Query.IQuery.Execute()
is called.
For detailed documentation please see
IQueryConfiguration.EvaluationMode(QueryEvaluationMode)
Constant for snapshot query evaluation.
Constant for snapshot query evaluation. When
Db4objects.Db4o.Query.IQuery.Execute()
is called,
the query processor chooses the best indexes, does all index processing
and creates a snapshot of the index at this point in time. Non-indexed
constraints are evaluated lazily when the application iterates through
the
Db4objects.Db4o.IObjectSet
resultset of the query.
For detailed documentation please see
IQueryConfiguration.EvaluationMode(QueryEvaluationMode)
Constant for lazy query evaluation.
Constant for lazy query evaluation. When
Db4objects.Db4o.Query.IQuery.Execute()
is called, the
query processor only chooses the best index and creates an iterator on
this index. Indexes and constraints are evaluated lazily when the
application iterates through the
Db4objects.Db4o.IObjectSet
resultset of the query.
For detailed documentation please see
IQueryConfiguration.EvaluationMode(QueryEvaluationMode)
internal method, ignore please.internal method, ignore please.internal method, ignore please.internal method, ignore please.
Assigns a fixed, pre-defined name to the given
Db4objects.Db4o.IObjectContainer
.
a simple Alias for a single Class or Type, using equals on
the names in the resolve method.
a simple Alias for a single Class or Type, using equals on
the names in the resolve method.
See
IAlias
for concrete examples.
pass the stored name as the first
parameter and the desired runtime name as the second parameter.
pass the stored name as the first
parameter and the desired runtime name as the second parameter.
returns the stored type name if the alias was written for the passed runtime type name
returns the runtime type name if the alias was written for the passed stored type name
Wildcard Alias functionality to create aliases for packages,
namespaces or multiple similar named classes.
Wildcard Alias functionality to create aliases for packages,
namespaces or multiple similar named classes. One single '*'
wildcard character is supported in the names.
See
IAlias
for concrete examples.
Create a WildcardAlias with two patterns, the
stored pattern and the pattern that is to be used
at runtime.
Create a WildcardAlias with two patterns, the
stored pattern and the pattern that is to be used
at runtime. One single '*' is allowed as a wildcard
character.
resolving is done through simple pattern matchingresolving is done through simple pattern matchingBase class for all constraint exceptions.Base class for all constraint exceptions.
ConstraintViolationException constructor with a specific
message.
ConstraintViolationException constructor with a specific
message.
exception message
configures a field of a class to allow unique values only.configures a field of a class to allow unique values only.constructor to create a UniqueFieldValueConstraint.constructor to create a UniqueFieldValueConstraint.
can be a class (Java) / Type (.NET) / instance of the class / fully qualified class name
the name of the field that is to be unique.
internal method, public for implementation reasons.internal method, public for implementation reasons.
db4o-specific exception.
This exception can be thrown by a
UniqueFieldValueConstraint
on commit.
Db4objects.Db4o.Config.IObjectField.Indexed(bool)
Db4objects.Db4o.Config.IConfiguration.Add(Db4objects.Db4o.Config.IConfigurationItem)
Constructor with a message composed from the class and field
name of the entity causing the exception.
Constructor with a message composed from the class and field
name of the entity causing the exception.
class, which caused the exception
field, which caused the exception
Factory class to open db4o instances in embedded
mode. Factory class to open db4o instances in embedded mode.
Db4objects.Db4o.CS.Db4oClientServer in
Db4objects.Db4o.CS.dll for methods to open db4o servers and db4o
clients.7.5
Creates a fresh
IEmbeddedConfiguration
instance.
a fresh, independent configuration with all options set to their default values
opens an
IObjectContainer
on the specified database file for local use.
A database file can only be opened once, subsequent attempts to
open another
IObjectContainer
against the same file will result in a
DatabaseFileLockedException
.
Database files can only be accessed for readwrite access from one
process at one time. All versions except for db4o mobile edition
use an internal mechanism to lock the database file for other
processes.
a custom
IConfiguration
instance to be obtained via
newConfiguration
an absolute or relative path to the database
file
an open
IObjectContainer
Db4objects.Db4o.Config.IConfiguration.ReadOnly Db4objects.Db4o.Config.IConfiguration.Encrypt
Db4objects.Db4o.Config.IConfiguration.Password I/O operation failed or was unexpectedly
interrupted. the required database file is locked by
another process.
runtime
configuration
is not compatible with the configuration of the database file.
open operation failed because the database file is in old format
and
Db4objects.Db4o.Config.IConfiguration.AllowVersionUpdates
is set to false.
database was configured as read-only.
Same as calling
OpenFile(Db4objects.Db4o.Config.IEmbeddedConfiguration, string)
with a fresh configuration (
NewConfiguration()
).
an absolute or relative path to the database file
OpenFile(Db4objects.Db4o.Config.IEmbeddedConfiguration, string)
factory class to start db4o database engines.
factory class to start db4o database engines.
This class provides static methods to
- open single-user databases
OpenFile(string)
- open db4o servers
OpenServer(string, int)
- connect to db4o servers
OpenClient(string, int, string, string)
- provide access to the global configuration context
Configure()
- print the version number of this db4o version
Main(java.lang.String[])ExtDb4o for extended functionality.prints the version name of this db4o version to System.out.
prints the version name of this db4o version to System.out.
returns the global db4o
IConfiguration
context
for the running CLR session.
The
IConfiguration
can be overriden in each
ObjectContainer
.
the global
configuration
context
Creates a fresh
IConfiguration
instance.
a fresh, independent configuration with all options set to their default values
Creates a clone of the global db4o
IConfiguration
.
a fresh configuration with all option values set to the values
currently configured for the global db4o configuration context
Operates just like
Db4objects.Db4o.Db4oFactory.OpenClient
, but uses
the global db4o
IConfiguration
context.
opens an
IObjectContainer
client and connects it to the specified named server and port.
The server needs to
allow access
for the specified user and password.
A client
IObjectContainer
can be cast to
IExtClient
to use extended
IExtObjectContainer
and
IExtClient
methods.
This method is obsolete, see the Db4objects.Db4o.CS.Db4oClientServer class in
Db4objects.Db4o.CS.dll for methods to open db4o servers and db4o clients.
a custom
IConfiguration
instance to be obtained via
Db4objects.Db4o.Db4oEmbedded.NewConfiguration
the host name
the port the server is using
the user name
the user password
an open
IObjectContainer
Db4objects.Db4o.IObjectServer.GrantAccess
I/O operation failed or was unexpectedly interrupted.
open operation failed because the database file
is in old format and
Db4objects.Db4o.Config.IConfiguration.AllowVersionUpdates
is set to false.
password supplied for the connection is
invalid.
opens an
IObjectContainer
client and connects it to the specified named server and port.
The server needs to
allow access
for the specified user and password.
A client
IObjectContainer
can be cast to
IExtClient
to use extended
IExtObjectContainer
and
IExtClient
methods.
This method is obsolete, see the Db4objects.Db4o.CS.Db4oClientServer class in
Db4objects.Db4o.CS.dll for methods to open db4o servers and db4o clients.
a custom
IConfiguration
instance to be obtained via
Db4objects.Db4o.Db4oEmbedded.NewConfiguration
the host name
the port the server is using
the user name
the user password
an open
IObjectContainer
Db4objects.Db4o.IObjectServer.GrantAccess
I/O operation failed or was unexpectedly interrupted.
open operation failed because the database file
is in old format and
Db4objects.Db4o.Config.IConfiguration.AllowVersionUpdates
is set to false.
password supplied for the connection is
invalid.
Operates just like
Db4oFactory.OpenFile
, but uses
the global db4o
IConfiguration
context.
opens an
IObjectContainer
on the specified database file for local use.
A database file can only be opened once, subsequent attempts to open
another
IObjectContainer
against the same file will result in
a
DatabaseFileLockedException
.
Database files can only be accessed for readwrite access from one process
at one time. All versions except for db4o mobile edition use an
internal mechanism to lock the database file for other processes.
an absolute or relative path to the database file
an open
IObjectContainerIConfiguration.ReadOnlyIConfiguration.EncryptIConfiguration.Password
I/O operation failed or was unexpectedly interrupted.
the required database file is locked by
another process.
runtime
configuration
is not compatible
with the configuration of the database file.
open operation failed because the database file
is in old format and
IConfiguration.AllowVersionUpdates
is set to false.
database was configured as read-only.
opens an
IObjectContainer
on the specified database file for local use.
A database file can only be opened once, subsequent attempts to open
another
IObjectContainer
against the same file will result in
a
DatabaseFileLockedException
.
Database files can only be accessed for readwrite access from one process
at one time. All versions except for db4o mobile edition use an
internal mechanism to lock the database file for other processes.
a custom
IConfiguration
instance to be obtained via
Db4oFactory.NewConfiguration
an absolute or relative path to the database file
an open
IObjectContainerIConfiguration.ReadOnlyIConfiguration.EncryptIConfiguration.Password
I/O operation failed or was unexpectedly interrupted.
the required database file is locked by
another process.
runtime
configuration
is not compatible
with the configuration of the database file.
open operation failed because the database file
is in old format and
IConfiguration.AllowVersionUpdates
is set to false.
database was configured as read-only.
Operates just like
Db4objects.Db4o.Db4oFactory.OpenServer
, but uses
the global db4o
IConfiguration
context.
Opens an
IObjectServer
on the specified database file and port.
If the server does not need to listen on a port because it will only be used
in embedded mode with
Db4objects.Db4o.IObjectServer.OpenClient
, specify '0' as the
port number.
This method is obsolete, see the Db4objects.Db4o.CS.Db4oClientServer class in
Db4objects.Db4o.CS.dll for methods to open db4o servers and db4o clients.
an absolute or relative path to the database file
the port to be used, or 0, if the server should not open a port,
because it will only be used with
Db4objects.Db4o.IObjectServer.OpenClient
.
Specify a value < 0 if an arbitrary free port should be chosen - see
Db4objects.Db4o.Ext.IExtObjectServer.Port
.
an
IObjectServer
listening
on the specified port.
Db4objects.Db4o.Config.IConfiguration.ReadOnly
Db4objects.Db4o.Config.IConfiguration.Encrypt
Db4objects.Db4o.Config.IConfiguration.Password
I/O operation failed or was unexpectedly interrupted.
the required database file is locked by
another process.
runtime
configuration
is not compatible
with the configuration of the database file.
open operation failed because the database file
is in old format and
Db4objects.Db4o.Config.IConfiguration.AllowVersionUpdates
is set to false.
database was configured as read-only.
opens an
IObjectServer
on the specified database file and port.
If the server does not need to listen on a port because it will only be used
in embedded mode with
Db4objects.Db4o.IObjectServer.OpenClient
, specify '0' as the
port number.
This method is obsolete, see the Db4objects.Db4o.CS.Db4oClientServer class in
Db4objects.Db4o.CS.dll for methods to open db4o servers and db4o clients.
a custom
IConfiguration
instance to be obtained via
Db4objects.Db4o.Db4oEmbedded.NewConfiguration
an absolute or relative path to the database file
the port to be used, or 0, if the server should not open a port,
because it will only be used with
Db4objects.Db4o.IObjectServer.OpenClient
.
Specify a value < 0 if an arbitrary free port should be chosen - see
Db4objects.Db4o.Ext.IExtObjectServer.Port
.
an
IObjectServer
listening
on the specified port.
Db4objects.Db4o.Config.IConfiguration.ReadOnly
Db4objects.Db4o.Config.IConfiguration.Encrypt
Db4objects.Db4o.Config.IConfiguration.Password
I/O operation failed or was unexpectedly interrupted.
the required database file is locked by
another process.
runtime
configuration
is not compatible
with the configuration of the database file.
open operation failed because the database file
is in old format and
Db4objects.Db4o.Config.IConfiguration.AllowVersionUpdates
is set to false.
database was configured as read-only.
returns the version name of the used db4o version.
returns the version name of the used db4o version.
version information as a String.indexes all fieldsprints query graph information to the console
allows faking the Db4oDatabase identity object, so the first
stored object in the debugger is the actually persisted object
Changing this setting to true will fail some tests that expect
database files to have identity
prints more stack tracesmakes C/S timeouts longer, so C/S does not time out in the debuggerturns freespace debuggin on
fills deleted slots with 'X' and overrides any configured
freespace filler
checks monitor conditions to make sure only the thread
with the global monitor is allowed entry to the core
makes sure a configuration entry is generated for each persistent
class
makes sure a configuration entry is generated for each persistent
field
allows turning weak references offprints all communicated messages to the consoleallows turning NIO off on Javaallows overriding the file locking mechanism to turn it offBase class for defragment ID mappings.Base class for defragment ID mappings.DefragmentThe ID mapping used internally during a defragmentation run.The ID mapping used internally during a defragmentation run.DefragmentReturns a previously registered mapping ID for the given ID if it exists.
Returns a previously registered mapping ID for the given ID if it exists.
The original ID
The mapping ID for the given original ID or 0, if none has been registered.
Registers a mapping for the given IDs.Registers a mapping for the given IDs.
The original ID
The ID to be mapped to the original ID.
true if the given original ID specifies a class slot, false otherwise.
Maps an ID to a slotprovides a Visitable of all mappings of IDs to slots.provides a Visitable of all mappings of IDs to slots.Prepares the mapping for use.Prepares the mapping for use.Shuts down the mapping after use.Shuts down the mapping after use.returns the slot address for an IDDatabase based mapping for IDs during a defragmentation run.
Database based mapping for IDs during a defragmentation run.
Use this mapping to keep memory consumption lower than when
using the
InMemoryIdMapping
.
DefragmentWill maintain the ID mapping as a BTree in the file with the given path.
Will maintain the ID mapping as a BTree in the file with the given path.
If a file exists in this location, it will be DELETED.
Node size and cache height of the tree will be the default values used by
the BTree implementation. The tree will never commit.
The location where the BTree file should be created.
Will maintain the ID mapping as a BTree in the file with the given path.
Will maintain the ID mapping as a BTree in the file with the given path.
If a file exists in this location, it will be DELETED.
The location where the BTree file should be created.
The size of a BTree node
The number of inserts after which a commit should be issued (<=0: never commit)
defragments database files.
defragments database files.
db4o structures storage inside database files as free and occupied
slots, very much like a file system - and just like a file system it
can be fragmented.
The simplest way to defragment a database file:
Defragment.Defrag("sample.yap");
This will move the file to "sample.yap.backup", then create a
defragmented version of this file in the original position, using a
temporary file "sample.yap.mapping". If the backup file already
exists, this will throw an exception and no action will be taken.
For more detailed configuration of the defragmentation process,
provide a DefragmentConfig instance:
This will move the file to "sample.bap", then create a defragmented
version of this file in the original position, using a temporary
file "sample.map" for BTree mapping. If the backup file already
exists, it will be deleted. The defragmentation process will skip
all classes that have instances stored within the yap file, but that
are not available on the class path (through the current
classloader). Custom db4o configuration options are read from the
IConfiguration
passed as db4oConfig.
Note:
For some specific, non-default configuration settings like UUID
generation, etc., you
must
pass an appropriate db4o configuration, just like you'd use it
within your application for normal database operation.
Renames the file at the given original path to a backup file and then
builds a defragmented version of the file in the original place.
Renames the file at the given original path to a backup file and then
builds a defragmented version of the file in the original place.
The path to the file to be defragmented.
if the original file cannot be moved to the backup location
Renames the file at the given original path to the given backup file and
then builds a defragmented version of the file in the original place.
Renames the file at the given original path to the given backup file and
then builds a defragmented version of the file in the original place.
The path to the file to be defragmented.
The path to the backup file to be created.
if the original file cannot be moved to the backup location
Renames the file at the configured original path to the configured backup
path and then builds a defragmented version of the file in the original
place.
Renames the file at the configured original path to the configured backup
path and then builds a defragmented version of the file in the original
place.
The configuration for this defragmentation run.
if the original file cannot be moved to the backup location
Renames the file at the configured original path to the configured backup
path and then builds a defragmented version of the file in the original
place.
Renames the file at the configured original path to the configured backup
path and then builds a defragmented version of the file in the original
place.
The configuration for this defragmentation run.
A listener for status notifications during the defragmentation
process.
if the original file cannot be moved to the backup location
Listener for defragmentation process messages.Listener for defragmentation process messages.Defragment
This method will be called when the defragment process encounters
file layout anomalies during the defragmentation process.
This method will be called when the defragment process encounters
file layout anomalies during the defragmentation process.
The message from the defragmentation process.
Configuration for a defragmentation run.Configuration for a defragmentation run.DefragmentCreates a configuration for a defragmentation run.
Creates a configuration for a defragmentation run. The backup and mapping
file paths are generated from the original path by appending the default
suffixes. All properties other than the provided paths are set to FALSE
by default.
The path to the file to be defragmented. Must exist and must be
a valid db4o file.
Creates a configuration for a defragmentation run with in-memory mapping.
Creates a configuration for a defragmentation run with in-memory mapping.
All properties other than the provided paths are set to FALSE by default.
The path to the file to be defragmented. Must exist and must be
a valid db4o file.
The path to the backup of the original file. No file should
exist at this position, otherwise it will be OVERWRITTEN if forceBackupDelete()
is set to true!
Creates a configuration for a defragmentation run.
Creates a configuration for a defragmentation run. All properties other
than the provided paths are set to FALSE by default.
The path to the file to be defragmented. Must exist and must be
a valid db4o file.
The path to the backup of the original file. No file should
exist at this position, otherwise it will be OVERWRITTEN if forceBackupDelete()
is set to true!
The Id mapping to be used internally. Pass either a
InMemoryIdMapping
for fastest defragment or a
DatabaseIdMapping
for low memory consumption.
The path to the file to be defragmented.The path to the backup of the original file.The temporary ID mapping used internally. For internal use only.
The
IStoredClassFilter
used to select stored class extents to
be included into the defragmented file.
The
IStoredClassFilter
used to select stored class extents to
be included into the defragmented file.
true, if an existing backup file should be deleted, false otherwise.
true, if an existing backup file should be deleted, false otherwise.
allows turning on and off readonly mode.
When changed classes are likely to be detected defragment, it may be required
to open the original database in read/write mode.
allows turning on and off readonly mode.
When changed classes are likely to be detected defragment, it may be required
to open the original database in read/write mode.
Readonly mode is the default setting.
false, to turn off readonly mode.
true, if the original database file is to be opened in readonly mode.
The db4o
IConfiguration
to be applied
during the defragment process.
The db4o
IConfiguration
to be applied
during the defragment process.
The db4o
IEmbeddedConfiguration
to be applied
during the defragment process.
7.9
The number of processed object (slots) that should trigger an
intermediate commit of the target file. Default: 0, meaning: never.
Instruct the defragment process to upgrade the source file to the current db4o
version prior to defragmenting it.
Instruct the defragment process to upgrade the source file to the current db4o
version prior to defragmenting it. Use this option if your source file has been created
with an older db4o version than the one you are using.
The location for an intermediate, upgraded version of the source file.
Filter for StoredClass instances.Filter for StoredClass instances.
StoredClass instance to be checked
true, if the given StoredClass instance should be accepted, false otherwise.
A message from the defragmentation process.
A message from the defragmentation process. This is a stub only
and will be refined.
Currently instances of these class will only be created and sent
to registered listeners when invalid IDs are encountered during
the defragmentation process. These probably are harmless and the
result of a user-initiated delete operation.
DefragmentEncapsulates services involving source and target database files during defragmenting.
Encapsulates services involving source and target database files during defragmenting.
A mapping from db4o file source IDs/addresses to target IDs/addresses, used for defragmenting.
A mapping from db4o file source IDs/addresses to target IDs/addresses, used for defragmenting.
a mapping for the given id. if it does refer to a system handler or the empty reference (0), returns the given id.
if the given id does not refer to a system handler or the empty reference (0) and if no mapping is found
First step in the defragmenting process: Allocates pointer slots in the target file for
each ID (but doesn't fill them in, yet) and registers the mapping from source pointer address
to target pointer address.
First step in the defragmenting process: Allocates pointer slots in the target file for
each ID (but doesn't fill them in, yet) and registers the mapping from source pointer address
to target pointer address.
Implements one step in the defragmenting process.Implements one step in the defragmenting process.In-memory mapping for IDs during a defragmentation run.
In-memory mapping for IDs during a defragmentation run.
This is faster than the
DatabaseIdMapping
but
it uses more memory. If you have OutOfMemory conditions
with this id mapping, use the
DatabaseIdMapping
instead.
Defragment
Second step in the defragmenting process: Fills in target file pointer slots, copies
content slots from source to target and triggers ID remapping therein by calling the
appropriate db4o/marshaller defrag() implementations.
Second step in the defragmenting process: Fills in target file pointer slots, copies
content slots from source to target and triggers ID remapping therein by calling the
appropriate db4o/marshaller defrag() implementations. During the process, the actual address
mappings for the content slots are registered for use with string indices.
turning debug on makes the file format human readableDiagnostic, if class has no fields.Diagnostic, if class has no fields.base class for Diagnostic messages
Marker interface for Diagnostic messages
Diagnostic system can be enabled on a running db4o database
to notify a user about possible problems or misconfigurations.
Marker interface for Diagnostic messages
Diagnostic system can be enabled on a running db4o database
to notify a user about possible problems or misconfigurations. Diagnostic
messages must implement this interface and are usually derived from
DiagnosticBase
class. A separate Diagnostic implementation
should be used for each problem.
DiagnosticBaseIDiagnosticConfigurationreturns the reason for the messagereturns the potential problem that triggered the messagesuggests a possible solution for the possible problemDiagnostic to recommend Defragment when needed.Diagnostic to recommend Defragment when needed.Diagnostic on failed delete.Diagnostic on failed delete.
Query tries to descend into a field of a class that is configured to be translated
(and thus cannot be descended into).
Query tries to descend into a field of a class that is configured to be translated
(and thus cannot be descended into).
prints Diagnostic messsages to the Console.
prints Diagnostic messages to the Console.
Install this
Db4objects.Db4o.Diagnostic.IDiagnosticListener
with: commonConfig.Diagnostic.AddListener(new DiagnosticToConsole()); Db4objects.Db4o.Diagnostic.IDiagnosticConfiguration
listens to Diagnostic messages.
listens to Diagnostic messages.
Create a class that implements this listener interface and add
the listener by calling commonConfig.Diagnostic.AddListener().
Db4objects.Db4o.Diagnostic.IDiagnosticConfiguration
this method will be called with Diagnostic messages.this method will be called with Diagnostic messages.redirects Diagnostic messages to the Console.redirects Diagnostic messages to the Console.provides methods to configure the behaviour of db4o
diagnostics.
provides methods to configure the behaviour of db4o diagnostics.
Diagnostic system can be enabled on a running db4o database to
notify a user about possible problems or misconfigurations.
Diagnostic listeners can be be added and removed with calls to this
interface. To install the most basic listener call:
commonConfig.Diagnostic.AddListener(new
DiagnosticToConsole());IConfiguration.Diagnostic
IDiagnosticListener
adds a DiagnosticListener to listen to Diagnostic messages.adds a DiagnosticListener to listen to Diagnostic messages.removes all DiagnosticListeners.removes all DiagnosticListeners.Diagnostic, if query was required to load candidate set from class index.
Diagnostic, if query was required to load candidate set from class index.
Diagnostic if class not foundDiagnostic, if Native Query can not be run optimized.Diagnostic, if Native Query can not be run optimized.
Diagnostic if
Db4objects.Db4o.Config.IObjectClass.ObjectField(string)
was called on a
field that does not exist.
Diagnostic, if update depth greater than 1.Diagnostic, if update depth greater than 1.Argument for object related events which can be cancelled.Argument for object related events which can be cancelled.IEventRegistryICancellableEventArgsArguments for object related events.Arguments for object related events.IEventRegistryCreates a new instance for the specified object.Creates a new instance for the specified object.The object that triggered this event.The object that triggered this event.Argument for events related to cancellable actions.Argument for events related to cancellable actions.IEventRegistryCancels the action related to this event.
Cancels the action related to this event.
Although the related action will be cancelled all the registered
listeners will still receive the event.
Queries if the action was already cancelled by some event listener.Queries if the action was already cancelled by some event listener.Creates a new instance for the specified object.Creates a new instance for the specified object.ICancellableEventArgs.Cancel()ICancellableEventArgs.IsCancelled()
Arguments for commit time related events.Arguments for commit time related events.IEventRegistryReturns a iteration
db4o-specific exception.
Exception thrown during event dispatching if a client
provided event handler throws.
The exception thrown by the client can be retrieved by
calling EventException.InnerException.
db4o-specific exception.
Exception thrown during event dispatching if a client
provided event handler throws.
The exception thrown by the client can be retrieved by
calling EventException.InnerException.
Provides an interface for getting an
IEventRegistry
from an
Db4objects.Db4o.IObjectContainer
.
Returns an
IEventRegistry
for registering events with the specified container.
Provides a way to register event handlers for specific IObjectContainer events.
EventRegistry methods represent events available for registering callbacks.
EventRegistry instance can be obtained from EventRegistryFactory.
EventRegistry registry = EventRegistryFactory.ForObjectContainer(container);
A new callback can be registered for an event with the following code:
private static void OnCreated(object sender, ObjectInfoEventArgs args)
{
Object obj = args.Object;
if (obj is Pilot)
{
Console.WriteLine(obj.ToString());
}
}
registry.Created+=new System.EventHandler<ObjectInfoEventArgs>(OnCreated);
EventRegistryFactory
This event is fired upon a query start and can be used to gather
query statistics.
This event is fired upon a query start and can be used to gather
query statistics.
The query object is available from
QueryEventArgs
event parameter. eventQueryEventArgs
This event is fired upon a query end and can be used to gather
query statistics.
This event is fired upon a query end and can be used to gather
query statistics.
The query object is available from
QueryEventArgs
event parameter. eventQueryEventArgsThis event is fired before an object is saved for the first time.
This event is fired before an object is saved for the first time.
The object can be obtained from
CancellableObjectEventArgs
event parameter. The action can be cancelled using
CancellableObjectEventArgs.Cancel()
eventCancellableObjectEventArgsDb4objects.Db4o.IObjectContainer.Store(object)
This event is fired before an object is activated.
This event is fired before an object is activated.
The object can be obtained from
CancellableObjectEventArgs
event parameter. The action can be cancelled using
CancellableObjectEventArgs.Cancel()
eventCancellableObjectEventArgsDb4objects.Db4o.IObjectContainer.Activate(object, int)
This event is fired before an object is updated.
This event is fired before an object is updated.
The object can be obtained from
CancellableObjectEventArgs
event parameter. The action can be cancelled using
CancellableObjectEventArgs.Cancel()
eventCancellableObjectEventArgsDb4objects.Db4o.IObjectContainer.Store(object)
This event is fired before an object is deleted.
This event is fired before an object is deleted.
The object can be obtained from
CancellableObjectEventArgs
event parameter. The action can be cancelled using
CancellableObjectEventArgs.Cancel()
Note, that this event is not available in networked client/server
mode and will throw an exception when attached to a client ObjectContainer.
eventCancellableObjectEventArgsDb4objects.Db4o.IObjectContainer.Delete(object)
This event is fired before an object is deactivated.
This event is fired before an object is deactivated.
The object can be obtained from
CancellableObjectEventArgs
event parameter. The action can be cancelled using
CancellableObjectEventArgs.Cancel()
eventCancellableObjectEventArgsDb4objects.Db4o.IObjectContainer.Deactivate(object, int)
This event is fired after an object is activated.
This event is fired after an object is activated.
The object can be obtained from the
ObjectInfoEventArgs
event parameter.
The event can be used to trigger some post-activation
functionality.
eventObjectInfoEventArgsDb4objects.Db4o.IObjectContainer.Activate(object, int)
This event is fired after an object is created (saved for the first time).
This event is fired after an object is created (saved for the first time).
The object can be obtained from the
ObjectInfoEventArgs
event parameter.
The event can be used to trigger some post-creation
functionality.
eventObjectEventArgsDb4objects.Db4o.IObjectContainer.Store(object)
This event is fired after an object is updated.
This event is fired after an object is updated.
The object can be obtained from the
ObjectInfoEventArgs
event parameter.
The event can be used to trigger some post-update
functionality.
eventObjectInfoEventArgsDb4objects.Db4o.IObjectContainer.Store(object)
This event is fired after an object is deleted.
This event is fired after an object is deleted.
The object can be obtained from the
ObjectInfoEventArgs
event parameter.
The event can be used to trigger some post-deletion
functionality.
Note, that this event is not available in networked client/server
mode and will throw an exception when attached to a client ObjectContainer.
eventObjectEventArgsDb4objects.Db4o.IObjectContainer.Delete(object)
This event is fired after an object is deactivated.
This event is fired after an object is deactivated.
The object can be obtained from the
ObjectInfoEventArgs
event parameter.
The event can be used to trigger some post-deactivation
functionality.
eventObjectEventArgsDb4objects.Db4o.IObjectContainer.Delete(object)
This event is fired just before a transaction is committed.
This event is fired just before a transaction is committed.
The transaction and a list of the modified objects can
be obtained from the
CommitEventArgs
event parameter.
Committing event gives a user a chance to interrupt the commit
and rollback the transaction.
eventCommitEventArgsDb4objects.Db4o.IObjectContainer.Commit()
This event is fired after a transaction has been committed.
This event is fired after a transaction has been committed.
The transaction and a list of the modified objects can
be obtained from the
CommitEventArgs
event parameter.
The event can be used to trigger some post-commit functionality.
eventCommitEventArgsDb4objects.Db4o.IObjectContainer.Commit()
This event is fired when a persistent object is instantiated.
This event is fired when a persistent object is instantiated.
The object can be obtained from the
ObjectInfoEventArgs
event parameter.
eventObjectInfoEventArgsThis event is fired when a new class is registered with metadata.
This event is fired when a new class is registered with metadata.
The class information can be obtained from
ClassEventArgs
event parameter.
eventClassEventArgs
This event is fired when the
Db4objects.Db4o.IObjectContainer.Close()
is
called.
event
This event is fired when the
Db4objects.Db4o.IObjectContainer
has
finished its startup procedure.
eventArguments for container related events.Arguments for container related events.IEventRegistry
Arguments for
Db4objects.Db4o.Query.IQuery
related events.
IEventRegistry
Creates a new instance for the specified
Db4objects.Db4o.Query.IQuery
instance.
The
Db4objects.Db4o.Query.IQuery
which triggered the event.
7.12db4o-specific exception.
db4o-specific exception.
This exception is thrown when the current
backup
process encounters another backup process already running.
db4o-specific exception.
db4o-specific exception.
This exception is thrown when the object container required for
the current operation was closed or failed to open.
Db4objects.Db4o.Db4oFactory.OpenFile(string)
Db4objects.Db4o.IObjectContainer.Close()
db4o-specific exception.
this Exception is thrown during any of the db4o open calls
if the database file is locked by another process.
db4o-specific exception.
this Exception is thrown during any of the db4o open calls
if the database file is locked by another process.
Db4objects.Db4o.Db4oFactory.OpenFile(string)
Constructor with a database description message
message, which can help to identify the database
Constructor with a database description and cause exception
database description
previous exception caused DatabaseFileLockedException
db4o-specific exception.
This exception is thrown when the database file reaches the
maximum allowed size.
db4o-specific exception.
This exception is thrown when the database file reaches the
maximum allowed size. Upon throwing the exception the database is
switched to the read-only mode.
The maximum database size is configurable
and can reach up to 254GB.
Db4objects.Db4o.Config.IConfiguration.BlockSize(int)
db4o-specific exception.
This exception is thrown when a write operation is attempted
on a database in a read-only mode.
db4o-specific exception.
This exception is thrown when a write operation is attempted
on a database in a read-only mode.
Class to identify a database by it's signature.
Class to identify a database by it's signature.
db4o UUID handling uses a reference to the Db4oDatabase object, that
represents the database an object was created on.
marker interface for all special db4o types.marker interface for all special db4o types.Field is public for implementation reasons, DO NOT TOUCH!
Field is public for implementation reasons, DO NOT TOUCH!
This field is badly named, it really is the creation time.
Field is public for implementation reasons, DO NOT TOUCH!
This field is badly named, it really is the creation time.
cached ObjectContainer for getting the own ID.cached ObjectContainer for getting the own ID.cached ID, only valid in combination with i_objectContainerconstructor for persistenceconstructor for comparison and to store new onesgenerates a new Db4oDatabase object with a unique signature.generates a new Db4oDatabase object with a unique signature.comparison by signature.comparison by signature.gets the db4o ID, and may cache it for performance reasons.gets the db4o ID, and may cache it for performance reasons.the db4o ID for the ObjectContainerreturns the unique signaturemake sure this Db4oDatabase is stored.make sure this Db4oDatabase is stored. Return the ID.find a Db4oDatabase with the same signature as this one
db4o-specific exception.
This exception is thrown when a system IO exception
is encounted by db4o process.
db4o-specific exception.
This exception is thrown when a system IO exception
is encounted by db4o process.
Constructor.Constructor.Constructor allowing to specify the causing exception
exception cause
The requested operation is not valid in the current state but the database
continues to operate.
The requested operation is not valid in the current state but the database
continues to operate.
a unique universal identify for an object.
a unique universal identify for an object.
The db4o UUID consists of
two parts: - an indexed long for fast access, - the signature of the
IObjectContainer
the object was created with.
Db4oUUIDs are valid representations of objects over multiple
ObjectContainers
constructs a Db4oUUID from a long part and a signature part
the long part
the signature part
returns the long part of this UUID.
returns the long part of this UUID.
To uniquely identify an object
universally, db4o uses an indexed long and a reference to the
Db4oDatabase object it was created on.
the long part of this UUID.returns the signature part of this UUID.
returns the signature part of this UUID.
To uniquely
identify an object universally, db4o uses an indexed long and a reference to
the Db4oDatabase singleton object of the
IObjectContainer
it was created on. This method
returns the signature of the Db4oDatabase object of the ObjectContainer: the
signature of the origin ObjectContainer.
the signature of the Db4oDatabase for this UUID.Unexpected fatal error is encountered.Unexpected fatal error is encountered.
A previous IO exception has switched the database file
to read-only mode for controlled shutdown.
A previous IO exception has switched the database file
to read-only mode for controlled shutdown.
generic callback interface.generic callback interface.the callback method
the object passed to the callback method
extended client functionality for the
IExtObjectContainer
interface.
Both
Db4o.openClient()
methods always
return an ExtClient object so a cast is possible.
The ObjectContainer functionality is split into multiple interfaces to allow newcomers to
focus on the essential methods.
extended functionality for the
IObjectContainer
interface.
Every db4o
IObjectContainer
always is an ExtObjectContainer so a cast is possible.
ObjectContainer.ext()
is a convenient method to perform the cast.
The ObjectContainer functionality is split to two interfaces to allow newcomers to
focus on the essential methods.
the interface to a db4o database, stand-alone or client/server.
the interface to a db4o database, stand-alone or client/server.
The IObjectContainer interface provides methods
to store, query and delete objects and to commit and rollback
transactions.
An IObjectContainer can either represent a stand-alone database
or a connection to a
db4o server
.
An IObjectContainer also represents a transaction. All work
with db4o always is transactional. Both
Db4objects.Db4o.IObjectContainer.Commit
and
Db4objects.Db4o.IObjectContainer.Rollback
start new transactions immediately. For working
against the same database with multiple transactions, open a db4o server
with
Db4objects.Db4o.Db4o.OpenServer
and
connect locally
or
over TCP
.
IExtObjectContainer for extended functionality.
creates a new SODA
Query
.
Linq queries are the recommended main db4o query interface.
Use
QueryByExample(Object template)
for simple Query-By-Example.
a new IQuery objectactivates all members on a stored object to the specified depth.
activates all members on a stored object to the specified depth.
See
"Why activation"
for an explanation why activation is necessary.
The activate method activates a graph of persistent objects in memory.
Only deactivated objects in the graph will be touched: their
fields will be loaded from the database.
The activate methods starts from a
root object and traverses all member objects to the depth specified by the
depth parameter. The depth parameter is the distance in "field hops"
(object.field.field) away from the root object. The nodes at 'depth' level
away from the root (for a depth of 3: object.member.member) will be instantiated
but deactivated, their fields will be null.
The activation depth of individual classes can be overruled
with the methods
MaximumActivationDepth()
and
MinimumActivationDepth()
in the
ObjectClass interface
.
A successful call to activate triggers Activating and Activated callback methods,
which can be used for cascaded activation.
Why activation?Using callbacks
the object to be activated.
the member
depth
to which activate is to cascade.
closes this IObjectContainer.
closes this IObjectContainer.
A call to Close() automatically performs a
Commit()
.
Note that every session opened with Db4oFactory.OpenFile() requires one
Close()call, even if the same filename was used multiple times.
Use while(!Close()){} to kill all sessions using this container.
success - true denotes that the last used instance of this container
and the database file were closed.
commits the running transaction.
commits the running transaction.
Transactions are back-to-back. A call to commit will starts
a new transaction immedidately.
deactivates a stored object by setting all members to NULL.
deactivates a stored object by setting all members to NULL.
Primitive types will be set to their default values.
Calls to this method save memory.
The method has no effect, if the passed object is not stored in the
IObjectContainer.
Deactivate() triggers Deactivating and Deactivated callbacks.
Be aware that calling this method with a depth parameter greater than
1 sets members on member objects to null. This may have side effects
in other places of the application.
Using callbacksWhy activation?
the object to be deactivated.
the member
depth
to which deactivate is to cascade.
deletes a stored object permanently.
deletes a stored object permanently.
Note that this method has to be called for every single object
individually. Delete does not recurse to object members. Simple
and array member types are destroyed.
Object members of the passed object remain untouched, unless
cascaded deletes are
configured for the class
or for
one of the member fields
.
The method has no effect, if
the passed object is not stored in the IObjectContainer.
A subsequent call to
Store() with the same object newly stores the object
to the IObjectContainer.
Delete() triggers Deleting and Deleted callbacks,
which can be also used for cascaded deletes.
Db4objects.Db4o.Config.IObjectClass.CascadeOnDelete
Db4objects.Db4o.Config.IObjectField.CascadeOnDelete
Using callbacks
the object to be deleted from the
IObjectContainer. returns an IObjectContainer with extended functionality.
returns an IObjectContainer with extended functionality.
Every IObjectContainer that db4o provides can be casted to
an IExtObjectContainer. This method is supplied for your convenience
to work without a cast.
The IObjectContainer functionality is split to two interfaces
to allow newcomers to focus on the essential methods.
this, casted to IExtObjectContainerQuery-By-Example interface to retrieve objects.
Query-By-Example interface to retrieve objects.
QueryByExample() creates an
IObjectSet
containing
all objects in the IObjectContainer that match the passed
template object.
Calling QueryByExample(null) returns all objects stored in the
IObjectContainer.
Query Evaluation All non-null members of the template object are compared against
all stored objects of the same class.
Primitive type members are ignored if they are 0 or false respectively.
Arrays and all supported Collection classes are
evaluated for containment. Differences in Length/Count/Size() are
ignored.
Consult the documentation of the IConfiguration package to
configure class-specific behaviour.
Returned Objects
The objects returned in the
IObjectSet
are instantiated
and activated to the preconfigured depth of 5. The
activation depth
may be configured
globally
or
individually for classes
.
db4o keeps track of all instantiatied objects. Queries will return
references to these objects instead of instantiating them a second time.
Objects newly activated by QueryByExample() can respond to the Activating callback
method.
object to be used as an example to find all matching objects.
IObjectSet
containing all found objects.
Why activation?Using callbacks
creates a new SODA
Query
.
Linq queries are the recommended main db4o query interface.
Use
QueryByExample(Object template)
for simple Query-By-Example.
a new IQuery objectqueries for all instances of a class.queries for all instances of a class.
the class to query for.
the
Db4objects.Db4o.IObjectSet
returned by the query.
Native Query Interface.
Native Query Interface. Queries as with
Db4objects.Db4o.IObjectContainer.Query(Predicate)
,
but will sort the resulting
Db4objects.Db4o.IObjectSet
according to the given
Db4objects.Db4o.Query.IQueryComparator
.
the
Db4objects.Db4o.Query.Predicate
containing the native query expression.
the
Db4objects.Db4o.Query.IQueryComparator
specifiying the sort order of the result
the
Db4objects.Db4o.IObjectSet
returned by the query.
Native Query Interface.
Native Query Interface. Queries as with
Db4objects.Db4o.IObjectContainer.Query(Predicate)
,
but will sort the resulting
Db4objects.Db4o.IObjectSet
according to the given
System.Collections.IComparer
.
the
Db4objects.Db4o.Query.Predicate
containing the native query expression.
the
System.Collections.IComparer
specifiying the sort order of the result
the
Db4objects.Db4o.IObjectSet
returned by the query.
rolls back the running transaction.
rolls back the running transaction.
Transactions are back-to-back. A call to rollback will starts
a new transaction immedidately.
rollback will not restore modified objects in memory. They
can be refreshed from the database by calling
Db4objects.Db4o.Ext.IExtObjectContainer.Refresh
.
newly stores objects or updates stored objects.
newly stores objects or updates stored objects.
An object not yet stored in the IObjectContainer will be
stored when it is passed to Store(). An object already stored
in the IObjectContainer will be updated.
Updates
- will affect all simple type object members.
- links to object members that are already stored will be updated.
- new object members will be newly stored. The algorithm traverses down
new members, as long as further new members are found.
- object members that are already stored will not be updated
themselves. Every object member needs to be updated individually with a
call to Store() unless a deep
global
or
class-specific
update depth was configured or cascaded updates were
defined in the class
or in
one of the member fields
.
Depending if the passed object is newly stored or updated, Creating/Created or
Updaing/Updated callback method is triggered.
Callbacks
might also be used for cascaded updates.
the object to be stored or updated.
IExtObjectContainer#Store(object, depth)
Db4objects.Db4o.Config.IConfiguration.UpdateDepth
Db4objects.Db4o.Config.IObjectClass.UpdateDepth
Db4objects.Db4o.Config.IObjectClass.CascadeOnUpdate
Db4objects.Db4o.Config.IObjectField.CascadeOnUpdate
Using callbacksNative Query Interface.
Native Query Interface. Queries as with
Db4objects.Db4o.IObjectContainer.Query(Predicate)
,
but will sort the resulting
Db4objects.Db4o.IObjectSet
according to the given
System.Collections.Generic.IComparer
.
the
Db4objects.Db4o.Query.Predicate
containing the native query expression.
the
System.Collections.Generic.IComparer
specifiying the sort order of the result
the
Db4objects.Db4o.IObjectSet
returned by the query.
Native Query Interface.
Native Query Interface. Queries as with
Db4objects.Db4o.IObjectContainer.Query(Predicate)
,
but will sort the resulting
Db4objects.Db4o.IObjectSet
according to the given
System.Comparison
.
the
Db4objects.Db4o.Query.Predicate
containing the native query expression.
the
System.Comparison
specifiying the sort order of the result
the
Db4objects.Db4o.IObjectSet
returned by the query.
queries for all instances of the type extent, returning
a IList of ElementType which must be assignable from
extent.
queries for all instances of the type extent.
queries for all instances of the type extent sorting with the specified comparer.
activates an object with the current activation strategy.
activates an object with the current activation strategy.
In regular activation mode the object will be activated to the
global activation depth, ( see
Db4objects.Db4o.Config.IConfiguration.ActivationDepth()
)
and all configured settings for
Db4objects.Db4o.Config.IObjectClass.MaximumActivationDepth(int)
and
Db4objects.Db4o.Config.IObjectClass.MaximumActivationDepth(int)
will be respected.
In Transparent Activation Mode ( see
Db4objects.Db4o.TA.TransparentActivationSupport
)
the parameter object will only be activated, if it does not implement
Db4objects.Db4o.TA.IActivatable
. All referenced members that do not implement
Db4objects.Db4o.TA.IActivatable
will also be activated. Any
Db4objects.Db4o.TA.IActivatable
objects
along the referenced graph will break cascading activation.
deactivates an object.
deactivates an object.
Only the passed object will be deactivated, i.e, no object referenced by this
object will be deactivated.
the object to be deactivated.
backs up a database file of an open ObjectContainer.
backs up a database file of an open ObjectContainer.
While the backup is running, the ObjectContainer can continue to be
used. Changes that are made while the backup is in progress, will be applied to
the open ObjectContainer and to the backup.
While the backup is running, the ObjectContainer should not be closed.
If a file already exists at the specified path, it will be overwritten.
The
Db4objects.Db4o.IO.IStorage
used for backup is the one configured for this container.
a fully qualified path
db4o database file was closed or failed to open.
is thrown when the operation is not supported in current
configuration/environment
I/O operation failed or was unexpectedly interrupted.
backs up a database file of an open ObjectContainer.
backs up a database file of an open ObjectContainer.
While the backup is running, the ObjectContainer can continue to be
used. Changes that are made while the backup is in progress, will be applied to
the open ObjectContainer and to the backup.
While the backup is running, the ObjectContainer should not be closed.
If a file already exists at the specified path, it will be overwritten.
This method is intended for cross-storage backups, i.e. backup from an in-memory
database to a file.
the
Db4objects.Db4o.IO.IStorage
to be used for backup
a fully qualified path
db4o database file was closed or failed to open.
is thrown when the operation is not supported in current
configuration/environment
I/O operation failed or was unexpectedly interrupted.
binds an object to an internal object ID.
binds an object to an internal object ID.
This method uses the ID parameter to load the
corresponding stored object into memory and replaces this memory
reference with the object parameter. The method may be used to replace
objects or to reassociate an object with it's stored instance
after closing and opening a database file. A subsequent call to
set(Object)
is
necessary to update the stored object.
Requirements: - The ID needs to be a valid internal object ID,
previously retrieved with
getID(Object)
.
- The object parameter needs to be of the same class as the stored object.
GetID(object)
the object that is to be bound
the internal id the object is to be bound to
db4o database file was closed or failed to open.
when the provided id is outside the scope of the
database IDs.
returns the Configuration context for this ObjectContainer.
returns the Configuration context for this ObjectContainer.
Upon opening an ObjectContainer with any of the factory methods in the
Db4o class
, the global
IConfiguration
context
is copied into the ObjectContainer. The
IConfiguration
can be modified individually for
each ObjectContainer without any effects on the global settings.
IConfiguration
the Configuration
context for this ObjectContainer
Db4objects.Db4o.Db4oFactory.Configure()
returns a member at the specific path without activating intermediate objects.
returns a member at the specific path without activating intermediate objects.
This method allows navigating from a persistent object to it's members in a
performant way without activating or instantiating intermediate objects.
the parent object that is to be used as the starting point.
an array of field names to navigate by
the object at the specified path or null if no object is foundreturns the stored object for an internal ID.
returns the stored object for an internal ID.
This is the fastest method for direct access to objects. Internal
IDs can be obtained with
getID(Object)
.
Objects will not be activated by this method. They will be returned in the
activation state they are currently in, in the local cache.
Passing invalid id values to this method may result in all kinds of
exceptions being thrown. OutOfMemoryError and arithmetic exceptions
may occur. If an application is known to use invalid IDs, it is
recommended to call this method within a catch-all block.
the internal ID
the object associated with the passed ID or null,
if no object is associated with this ID in this ObjectContainer.
Why activation?
db4o database file was closed or failed to open.
when the provided id is outside the scope of the
file length.
returns a stored object for a
Db4oUUID
.
This method is intended for replication and for long-term
external references to objects. To get a
Db4oUUID
for an
object use
GetObjectInfo(object)
and
IObjectInfo.GetUUID()
.
Objects will not be activated by this method. They will be returned in the
activation state they are currently in, in the local cache.
the UUID
the object for the UUIDWhy activation?
I/O operation failed or was unexpectedly interrupted.
db4o database file was closed or failed to open.
returns the internal unique object ID.
returns the internal unique object ID.
db4o assigns an internal ID to every object that is stored. IDs are
guaranteed to be unique within one ObjectContainer.
An object carries the same ID in every db4o session. Internal IDs can
be used to look up objects with the very fast
getByID
method.
Internal IDs will change when a database is defragmented. Use
GetObjectInfo(object)
,
IObjectInfo.GetUUID()
and
GetByUUID(Db4oUUID)
for long-term external references to
objects.
any object
the associated internal ID or 0, if the passed
object is not stored in this ObjectContainer.
returns the
IObjectInfo
for a stored object.
This method will return null, if the passed
object is not stored to this ObjectContainer.
the stored object
the
IObjectInforeturns the Db4oDatabase object for this ObjectContainer.returns the Db4oDatabase object for this ObjectContainer.the Db4oDatabase identity object for this ObjectContainer.tests if an object is activated.
tests if an object is activated.
isActive returns false if an object is not
stored within the ObjectContainer.
to be tested
true if the passed object is active.tests if an object with this ID is currently cached.
tests if an object with this ID is currently cached.
the internal ID
tests if this ObjectContainer is closed.
tests if this ObjectContainer is closed.
true if this ObjectContainer is closed.tests if an object is stored in this ObjectContainer.
tests if an object is stored in this ObjectContainer.
to be tested
true if the passed object is stored.db4o database file was closed or failed to open.
returns all class representations that are known to this
ObjectContainer because they have been used or stored.
returns all class representations that are known to this
ObjectContainer because they have been used or stored.
all class representations that are known to this
ObjectContainer because they have been used or stored.
returns the main synchronization lock.
returns the main synchronization lock.
Synchronize over this object to ensure exclusive access to
the ObjectContainer.
Handle the use of this functionality with extreme care,
since deadlocks can be produced with just two lines of code.
Object the ObjectContainer lock objectopens a new ObjectContainer on top of this ObjectContainer.
opens a new ObjectContainer on top of this ObjectContainer.
The ObjectContainer will have it's own transaction and
it's own reference system.
the new ObjectContainer session.8.0
returns a transient copy of a persistent object with all members set
to the values that are currently stored to the database.
returns a transient copy of a persistent object with all members set
to the values that are currently stored to the database.
The returned objects have no connection to the database.
With the committed parameter it is possible to specify,
whether the desired object should contain the committed values or the
values that were set by the running transaction with
Db4objects.Db4o.IObjectContainer.Store(object)
.
A possible use case for this feature:
An application might want to check all changes applied to an object
by the running transaction.
the object that is to be cloned
the member depth to which the object is to be instantiated
whether committed or set values are to be returned
the objectunloads all clean indices from memory and frees unused objects.
unloads all clean indices from memory and frees unused objects.
Call commit() and purge() consecutively to achieve the best
result possible. This method can have a negative impact
on performance since indices will have to be reread before further
inserts, updates or queries can take place.
unloads a specific object from the db4o reference mechanism.
unloads a specific object from the db4o reference mechanism.
db4o keeps references to all newly stored and
instantiated objects in memory, to be able to manage object identities.
With calls to this method it is possible to remove an object from the
reference mechanism, to allow it to be garbage collected. You are not required to
call this method in the .NET and JDK 1.2 versions, since objects are
referred to by weak references and garbage collection happens
automatically.
An object removed with purge(Object) is not
"known" to the ObjectContainer afterwards, so this method may also be
used to create multiple copies of objects.
purge(Object) has
no influence on the persistence state of objects. "Purged" objects can be
reretrieved with queries.
the object to be removed from the reference mechanism.
Return the reflector currently being used by db4objects.Return the reflector currently being used by db4objects.the current Reflector.refreshs all members on a stored object to the specified depth.
refreshs all members on a stored object to the specified depth.
If a member object is not activated, it will be activated by this method.
The isolation used is READ COMMITTED. This method will read all objects
and values that have been committed by other transactions.
the object to be refreshed.
the member
depth
to which refresh is to cascade.
releases a semaphore, if the calling transaction is the owner.releases a semaphore, if the calling transaction is the owner.
the name of the semaphore to be released.
deep update interface to store or update objects.
deep update interface to store or update objects.
In addition to the normal storage interface,
ObjectContainer#set(Object)
,
this method allows a manual specification of the depth, the passed object is to be updated.
the object to be stored or updated.
the depth to which the object is to be updated
com.db4o.ObjectContainer#setattempts to set a semaphore.
attempts to set a semaphore.
Semaphores are transient multi-purpose named flags for
ObjectContainers
.
A transaction that successfully sets a semaphore becomes
the owner of the semaphore. Semaphores can only be owned
by a single transaction at one point in time.
This method returns true, if the transaction already owned
the semaphore before the method call or if it successfully
acquires ownership of the semaphore.
The waitForAvailability parameter allows to specify a time
in milliseconds to wait for other transactions to release
the semaphore, in case the semaphore is already owned by
another transaction.
Semaphores are released by the first occurrence of one of the
following:
- the transaction releases the semaphore with
ReleaseSemaphore(string) - the transaction is closed with
Db4objects.Db4o.IObjectContainer.Close()
- C/S only: the corresponding
Db4objects.Db4o.IObjectServer
is
closed. - C/S only: the client
Db4objects.Db4o.IObjectContainer
looses the connection and is timed
out.
Semaphores are set immediately. They are independant of calling
Db4objects.Db4o.IObjectContainer.Commit()
or
Db4objects.Db4o.IObjectContainer.Rollback()
.
Possible use cases
for semaphores: - prevent other clients from inserting a singleton at the same time.
A suggested name for the semaphore: "SINGLETON_" + Object#getClass().getName(). - lock
objects. A suggested name: "LOCK_" +
getID(Object) -
generate a unique client ID. A suggested name: "CLIENT_" +
System.currentTimeMillis().
the name of the semaphore to be set
the time in milliseconds to wait for other
transactions to release the semaphore. The parameter may be zero, if
the method is to return immediately.
boolean flag
true, if the semaphore could be set or if the
calling transaction already owned the semaphore.
false, if the semaphore is owned by another
transaction.
returns a
IStoredClass
meta information object.
There are three options how to use this method.
Any of the following parameters are possible:
- a fully qualified class name.
- a Class object.
- any object to be used as a template.
class name, Class object, or example object.
an instance of an
IStoredClass
meta information object.
returns an array of all
IStoredClass
meta information objects.
returns the
ISystemInfo
for this ObjectContainer.
The
ISystemInfo
supplies methods that provide
information about system state and system settings of this
ObjectContainer.
the
ISystemInfo
for this ObjectContainer.
returns the current transaction serial number.
returns the current transaction serial number.
This serial number can be used to query for modified objects
and for replication purposes.
the current transaction serial number.checks if the client is currently connected to a server.checks if the client is currently connected to a server.true if the client is alive.extended functionality for the ObjectServer interface.
extended functionality for the ObjectServer interface.
Every ObjectServer also always is an ExtObjectServer
so a cast is possible.
Db4objects.Db4o.IObjectServer.Ext()
is a convenient method to perform the cast.
The functionality is split to two interfaces to allow newcomers to
focus on the essential methods.
the db4o server interface.
the db4o server interface.
- db4o servers can be opened with
Db4oFactory.OpenServer(string, int)
.
- Direct in-memory connections to servers can be made with
OpenClient()
- TCP connections are available through
Db4oFactory.OpenClient(string, int, string, string)
.
Before connecting clients over TCP, you have to
GrantAccess(string, string)
to the username and password combination
that you want to use.
Db4o.openServerExtObjectServer for extended functionality
closes the
and writes all cached data.
true - denotes that the last instance connected to the
used database file was closed.
returns an
with extended functionality.
Use this method as a convenient accessor to extended methods.
Every
can be casted to an
Db4objects.Db4o.Ext.IExtObjectServer
.
The functionality is split to two interfaces to allow newcomers to
focus on the essential methods.
grants client access to the specified user with the specified password.
grants client access to the specified user with the specified password.
If the user already exists, the password is changed to
the specified password.
the name of the user
the password to be used
opens a client against this server.
opens a client against this server.
A client opened with this method operates within the same VM
as the server. Since an embedded client can use direct communication, without
an in-between socket connection, performance will be better than a client
opened with
Db4oFactory.OpenClient(string, int, string, string)
Every client has it's own transaction and uses it's own cache
for it's own version of all peristent objects.
backs up the database file used by the ObjectServer.
backs up the database file used by the ObjectServer.
While the backup is running, the ObjectServer can continue to be
used. Changes that are made while the backup is in progress, will be applied to
the open ObjectServer and to the backup.
While the backup is running, the ObjectContainer should not be closed.
If a file already exists at the specified path, it will be overwritten.
a fully qualified path
returns the number of connected clients.returns the number of connected clients.
returns the
Db4objects.Db4o.Config.IConfiguration
context for this ObjectServer.
Upon opening an ObjectServer with any of the factory methods in the
Db4objects.Db4o.Db4oFactory
class, the global
Db4objects.Db4o.Config.IConfiguration
context
is copied into the ObjectServer. The
Db4objects.Db4o.Config.IConfiguration
can be modified individually for
each ObjectServer without any effects on the global settings.
the Configuration context for this ObjectServerDb4objects.Db4o.Db4oFactory.Configure()
returns the ObjectContainer used by the server.
returns the ObjectContainer used by the server.
the ObjectContainer used by the serverremoves client access permissions for the specified user.
removes client access permissions for the specified user.
the name of the user
The local port this server uses, 0 if disconnected or in embedded mode
extended functionality for the
IObjectSet
interface.
Every db4o
IObjectSet
always is an ExtObjectSet so a cast is possible.
Db4objects.Db4o.IObjectSet.Ext()
is a convenient method to perform the cast.
The ObjectSet functionality is split to two interfaces to allow newcomers to
focus on the essential methods.
An ObjectSet is a representation for a set of objects returned
by a query.
An ObjectSet is a representation for a set of objects returned
by a query.
ObjectSet extends the system collection interfaces
java.util.List/System.Collections.IList where they are available. It is
recommended, never to reference ObjectSet directly in code but to use
List / IList instead.
Note that the underlying
IObjectContainer
of an ObjectSet
needs to remain open as long as an ObjectSet is used. This is necessary
for lazy instantiation. The objects in an ObjectSet are only instantiated
when they are actually being used by the application.
for extended functionality.returns an ObjectSet with extended functionality.
returns an ObjectSet with extended functionality.
Every ObjectSet that db4o provides can be casted to
an ExtObjectSet. This method is supplied for your convenience
to work without a cast.
The ObjectSet functionality is split to two interfaces
to allow newcomers to focus on the essential methods.
returns true if the ObjectSet has more elements.
returns true if the ObjectSet has more elements.
boolean - true if the ObjectSet has more
elements.
returns the next object in the ObjectSet.
returns the next object in the ObjectSet.
Before returning the Object, next() triggers automatic activation of the
Object with the respective
global
or
class specific
setting.
the next object in the ObjectSet.resets the ObjectSet cursor before the first element.
resets the ObjectSet cursor before the first element.
A subsequent call to next() will return the first element.
returns an array of internal IDs that correspond to the contained objects.
returns an array of internal IDs that correspond to the contained objects.
IExtObjectContainer.GetID(object)
IExtObjectContainer.GetByID(long)
returns the item at position [index] in this ObjectSet.
returns the item at position [index] in this ObjectSet.
The object will be activated.
the index position in this ObjectSet.
the activated object.callback methods.
callback methods.
This interface only serves as a list of all available callback methods.
Every method is called individually, independantly of implementing this interface.
Using callbacks
Simply implement one or more of the listed methods in your application classes to
do tasks before activation, deactivation, delete, new or update, to cancel the
action about to be performed and to respond to the performed task.
Callback methods are typically used for:
- cascaded delete
- cascaded update
- cascaded activation
- restoring transient members on instantiation
Callback methods follow regular calling conventions. Methods in superclasses
need to be called explicitely.
All method calls are implemented to occur only once, upon one event.
called before an Object is activated.called before an Object is activated.
the ObjectContainer the object is stored in.
false to prevent activation.called before an Object is deactivated.called before an Object is deactivated.
the ObjectContainer the object is stored in.
false to prevent deactivation.called before an Object is deleted.
called before an Object is deleted.
In a client/server setup this callback method will be executed on
the server.
the ObjectContainer the object is stored in.
false to prevent the object from being deleted.called before an Object is stored the first time.called before an Object is stored the first time.
the ObjectContainer is about to be stored to.
false to prevent the object from being stored.called before a persisted Object is updated.called before a persisted Object is updated.
the ObjectContainer the object is stored in.
false to prevent the object from being updated.called upon activation of an object.called upon activation of an object.
the ObjectContainer the object is stored in.
called upon deactivation of an object.called upon deactivation of an object.
the ObjectContainer the object is stored in.
called after an object was deleted.
called after an object was deleted.
In a client/server setup this callback method will be executed on
the server.
the ObjectContainer the object was stored in.
called after a new object was stored.called after a new object was stored.
the ObjectContainer the object is stored to.
called after an object was updated.called after an object was updated.
the ObjectContainer the object is stored in.
interface to the internal reference that an ObjectContainer
holds for a stored object.
interface to the internal reference that an ObjectContainer
holds for a stored object.
returns the internal db4o ID.returns the internal db4o ID.returns the object that is referenced.
returns the object that is referenced.
This method may return null, if the object has
been garbage collected.
the referenced object or null, if the object has
been garbage collected.
returns a UUID representation of the referenced object.
returns a UUID representation of the referenced object.
UUID generation has to be turned on, in order to be able
to use this feature:
Db4objects.Db4o.Config.IConfiguration.GenerateUUIDs(Db4objects.Db4o.Config.ConfigScope)
the UUID of the referenced object.
returns the transaction serial number ("version") the referenced object
was stored with last.
returns the transaction serial number ("version") the referenced object
was stored with last. Version number generation has to be turned on, in
order to be able to use this feature:
Db4objects.Db4o.Config.IConfiguration.GenerateVersionNumbers(Db4objects.Db4o.Config.ConfigScope)
This feature was replaced by
GetCommitTimestamp()
. The main
difference is that the old version mechamism used to assign a serial
timestamp to the object upon storing time, and the new commiTimestamp
approach, assigns it upon commit time. the version number.
The serial timestamp the object is assigned to when it is commited.
You need to enable this feature before using it in
Db4objects.Db4o.Config.IFileConfiguration.GenerateCommitTimestamps(bool)
.
All the objects commited within the same transaction will receive the same commitTimestamp.
db4o replication system (dRS) relies on this feature. the serial timestamp that was given to the object upon commit.Db4objects.Db4o.Config.IFileConfiguration.GenerateCommitTimestamps(bool)8.0
Interface to an iterable collection
IObjectInfo
objects.
ObjectInfoCollection is used reference a number of stored objects.
IObjectInfothe internal representation of a stored class.the internal representation of a stored class.returns the name of this stored class.returns the name of this stored class.returns an array of IDs of all stored object instances of this stored class.
returns an array of IDs of all stored object instances of this stored class.
returns the StoredClass for the parent of the class, this StoredClass represents.
returns the StoredClass for the parent of the class, this StoredClass represents.
returns all stored fields of this stored class.returns all stored fields of this stored class.returns true if this StoredClass has a class index.returns true if this StoredClass has a class index.renames this stored class.
renames this stored class.
After renaming one or multiple classes the ObjectContainer has
to be closed and reopened to allow internal caches to be refreshed.
.NET: As the name you should provide [Classname, Assemblyname]
the new name
returns an existing stored field of this stored class.returns an existing stored field of this stored class.
the name of the field
the type of the field.
There are four possibilities how to supply the type:
- a Class object. (.NET: a Type object)
- a fully qualified classname.
- any object to be used as a template.
- null, if the first found field should be returned.
the
IStoredField
Returns the number of instances of this class that have been persisted to the
database, as seen by the transaction (container) that produces this StoredClass
instance.
Returns the number of instances of this class that have been persisted to the
database, as seen by the transaction (container) that produces this StoredClass
instance.
The number of instancesthe internal representation of a field on a stored class.the internal representation of a field on a stored class.creates an index on this field at runtime.creates an index on this field at runtime.drops an existing index on this field at runtime.drops an existing index on this field at runtime.returns the field value on the passed object.
returns the field value on the passed object.
This method will also work, if the field is not present in the current
version of the class.
It is recommended to use this method for refactoring purposes, if fields
are removed and the field values need to be copied to other fields.
returns the name of the field.returns the name of the field.returns the Class (Java) / Type (.NET) of the field.
returns the Class (Java) / Type (.NET) of the field.
For array fields this method will return the type of the array.
Use
IsArray()
to detect arrays.
returns true if the field is an array.returns true if the field is an array.modifies the name of this stored field.
modifies the name of this stored field.
After renaming one or multiple fields the ObjectContainer has
to be closed and reopened to allow internal caches to be refreshed.
the new name
specialized highspeed API to collect all values of a field for all instances
of a class, if the field is indexed.
specialized highspeed API to collect all values of a field for all instances
of a class, if the field is indexed.
The field values will be taken directly from the index without the
detour through class indexes or object instantiation.
If this method is used to get the values of a first class object index,
deactivated objects will be passed to the visitor.
the visitor to be called with each index value.
Returns whether this field has an index or not.Returns whether this field has an index or not.true if this field has an index.provides information about system state and system settings.provides information about system state and system settings.returns the number of entries in the Freespace Manager.
returns the number of entries in the Freespace Manager.
A high value for the number of freespace entries
is an indication that the database is fragmented and
that defragment should be run.
the number of entries in the Freespace Manager.returns the freespace size in the database in bytes.
returns the freespace size in the database in bytes.
When db4o stores modified objects, it allocates
a new slot for it. During commit the old slot is freed.
Free slots are collected in the freespace manager, so
they can be reused for other objects.
This method returns a sum of the size of all
free slots in the database file.
To reclaim freespace run defragment.
the freespace size in the database in bytes.Returns the total size of the database on disk.Returns the total size of the database on disk.total size of database on disk
db4o-specific exception.
This exception is thrown when the database file format
is not compatible with the applied configuration.
db4o-specific exception.
This exception is thrown when the database file format
is not compatible with the applied configuration.
db4o-specific exception.
This exception is thrown when the supplied object ID
is incorrect (outside the scope of the database IDs).
db4o-specific exception.
This exception is thrown when the supplied object ID
is incorrect (outside the scope of the database IDs).
IExtObjectContainer.Bind(object, long)
IExtObjectContainer.GetByID(long)
Constructor allowing to specify the exception cause
cause exception
Constructor allowing to specify the offending id
the offending id
db4o-specific exception.
This exception is thrown when a client tries to connect
to a server with a wrong password or null password.
db4o-specific exception.
This exception is thrown when a client tries to connect
to a server with a wrong password or null password.
db4o-specific exception.
This exception is thrown when db4o reads slot
information which is not valid (length or address).
db4o-specific exception.
This exception is thrown when db4o reads slot
information which is not valid (length or address).
Constructor allowing to specify a detailed message.Constructor allowing to specify a detailed message.
message
Constructor allowing to specify the address, length and id.Constructor allowing to specify the address, length and id.
offending address
offending length
id where the address and length were read.
this Exception is thrown, if objects can not be stored and if
db4o is configured to throw Exceptions on storage failures.
this Exception is thrown, if objects can not be stored and if
db4o is configured to throw Exceptions on storage failures.
Db4objects.Db4o.Config.IConfiguration.ExceptionsOnNotStorable(bool)
db4o-specific exception.
This exception is thrown when an old file format was detected
and
Db4objects.Db4o.Config.IConfiguration.AllowVersionUpdates(bool)
is set to false.
Constructor with the default message.Constructor with the default message.Static constants to describe the status of objects.Static constants to describe the status of objects.
This exception is thrown while reading old database
files for which support has been dropped.
This exception is thrown while reading old database
files for which support has been dropped.
intended for future virtual fields on classes.
intended for future virtual fields on classes. Currently only
the constant for the virtual version field is found here.
the field name of the virtual version field, to be used
for querying.
the field name of the virtual version field, to be used
for querying.
Basic functionality for implementing iterators for
fixed length structures whose elements can be efficiently
accessed by a numeric index.
Basic functionality for implementing iterators for
fixed length structures whose elements can be efficiently
accessed by a numeric index.
"readFrom buffer" constructorReturns the next object in the queue that matches the specified condition.
Returns the next object in the queue that matches the specified condition.
The operation is always NON-BLOCKING.
the object must satisfy to be returned
the object satisfying the condition or null if none doesUseful as "out" or "by ref" function parameter.Useful as "out" or "by ref" function parameter.Useful as "out" or "by reference" function parameter.Useful as "out" or "by reference" function parameter.A fixed size double ended queue with O(1) complexity for addFirst, removeFirst and removeLast operations.
A fixed size double ended queue with O(1) complexity for addFirst, removeFirst and removeLast operations.
A fixed size double ended queue with O(1) complexity for addFirst, removeFirst and removeLast operations.
A fixed size double ended queue with O(1) complexity for addFirst, removeFirst and removeLast operations.
A fixed size double ended queue with O(1) complexity for addFirst, removeFirst and removeLast operations.
A fixed size double ended queue with O(1) complexity for addFirst, removeFirst and removeLast operations.
Fast linked list for all usecases.Fast linked list for all usecases.Deep clone
The parameter allows passing one new object so parent
references can be corrected on children.
The parameter allows passing one new object so parent
references can be corrected on children.
marker interface to denote that version numbers and UUIDs should
not be generated for a class that implements this interface
Adds an element to the end of this collection.Adds an element to the end of this collection.tests if the object is in the Collection.tests if the object is in the Collection. == comparison.
returns the first object found in the Collections that equals() the
passed object
makes sure the passed object is in the Collection.makes sure the passed object is in the Collection. equals() comparison.
Iterates through the collection in reversed insertion order which happens
to be the fastest.
Iterates through the collection in reversed insertion order which happens
to be the fastest.
Removes all the elements from this collection that are returned by
iterable.
Removes all the elements from this collection that are returned by
iterable.
Removes all the elements from this collection that are returned by
iterator.
Removes all the elements from this collection that are returned by
iterator.
removes an object from the Collection equals() comparison returns the
removed object or null, if none found
This is a non reflection implementation for more speed.
This is a non reflection implementation for more speed. In contrast to
the JDK behaviour, the passed array has to be initialized to the right
length.
Leaner iterator for faster iteration (but unprotected against
concurrent modifications).
Leaner iterator for faster iteration (but unprotected against
concurrent modifications).
A dynamic variable is a value associated to a specific thread and scope.
A dynamic variable is a value associated to a specific thread and scope.
The value is brought into scope with the
With(object, IClosure4)
method.
Resolves a service interface to its default implementation using the
db4o namespace convention:
interface foo.bar.Baz
default implementation foo.internal.bar.BazImpl
the convention based type name for the requested serviceIterates through all the values.Iterates through all the values.value iterator
Iterates through all the
entries
.
IEntry4
iterator
HashtableBase.Values()
#see
HashtableBase.ValuesIterator()true to continue traversal, false otherwise
Returns negative number if x < y
Returns zero if x == y
Returns positive number if x > y
Non boxing/unboxing version of
System.Collections.IComparer<T>
for
faster id comparisons.
a prepared comparison, to compare multiple objects
with one single object.
a prepared comparison, to compare multiple objects
with one single object.
return a negative int, zero or a positive int if
the object being held in 'this' is smaller, equal
or greater than the passed object.
Typical implementation: return this.object - obj;
Useful as "out" or "by ref" function parameter.Useful as "out" or "by ref" function parameter.
Adapts Iterable4/Iterator4 iteration model (moveNext, current) to the old db4o
and jdk model (hasNext, next).
Adapts Iterable4/Iterator4 iteration model (moveNext, current) to the old db4o
and jdk model (hasNext, next).
Iterator primitives (concat, map, reduce, filter, etc...).Iterator primitives (concat, map, reduce, filter, etc...).
Constant indicating that the current element in a
Map(IEnumerator, IFunction4)
operation
should be skipped.
Generates
Tuple
items with indexes starting at 0.
the iterable to be enumerated
Returns a new iterator which yields the result of applying the function
to every element in the original iterator.
Returns a new iterator which yields the result of applying the function
to every element in the original iterator.
Skip
can be returned from function to indicate the current
element should be skipped.
Yields a flat sequence of elements.
Yields a flat sequence of elements. Any
IEnumerable
or
IEnumerator
found in the original sequence is recursively flattened.
original sequence
simplest possible linked listnext element in listcarried objectdb4o constructor to be able to store objects of this classUseful as "out" or "by ref" function parameter.Useful as "out" or "by ref" function parameter.Unbounded queue.Unbounded queue.Useful as "out" or "by ref" function parameter.Useful as "out" or "by ref" function parameter.A collection of static methods that should be part of the runtime environment but are not.
A collection of static methods that should be part of the runtime environment but are not.
sleeps without checked exceptionssleeps with implicit exception
Keeps executing a block of code until it either returns true or millisecondsTimeout
elapses.
Keeps executing a block of code until it either returns true or millisecondsTimeout
elapses.
yes/no/dontknow data type
ThreadLocal implementation for less capable platforms such as JRE 1.1 and
Silverlight.
ThreadLocal implementation for less capable platforms such as JRE 1.1 and
Silverlight.
This class is not intended to be used directly, use
DynamicVariable
.
WARNING: This implementation might leak Thread references unless
Set(object)
is called with null on the right thread to clean it up. This
behavior is currently guaranteed by
DynamicVariable
.
On adding a node to a tree, if it already exists, and if
Tree#duplicates() returns false, #isDuplicateOf() will be
called.
On adding a node to a tree, if it already exists, and if
Tree#duplicates() returns false, #isDuplicateOf() will be
called. The added node can then be asked for the node that
prevails in the tree using #duplicateOrThis(). This mechanism
allows doing find() and add() in one run.
On adding a node to a tree, if it already exists, and if
Tree#duplicates() returns false, #onAttemptToAddDuplicate()
will be called and the existing node will be stored in
this._preceding.
On adding a node to a tree, if it already exists, and if
Tree#duplicates() returns false, #onAttemptToAddDuplicate()
will be called and the existing node will be stored in
this._preceding.
This node node can then be asked for the node that prevails
in the tree on adding, using the #addedOrExisting() method.
This mechanism allows doing find() and add() in one run.
returns 0, if keys are equal
uses this - other
returns positive if this is greater than a_to
returns negative if this is smaller than a_to
the number of nodes in this tree for balancingthe number of objects represented.Traverses a tree with a starting point node.
Traverses a tree with a starting point node.
If there is no exact match for the starting node, the next higher will be taken.
com.db4o.internal.blobs
Represents a local ObjectContainer attached to a
database file.
Represents a local ObjectContainer attached to a
database file.
7.10backs up a database file of an open ObjectContainer.
backs up a database file of an open ObjectContainer.
While the backup is running, the ObjectContainer can continue to be
used. Changes that are made while the backup is in progress, will be applied to
the open ObjectContainer and to the backup.
While the backup is running, the ObjectContainer should not be closed.
If a file already exists at the specified path, it will be overwritten.
The
Db4objects.Db4o.IO.IStorage
used for backup is the one configured for this container.
a fully qualified path
db4o database file was closed or failed to open.
is thrown when the operation is not supported in current
configuration/environment
I/O operation failed or was unexpectedly interrupted.
Wrapper baseclass for all classes that wrap Bin.
Wrapper baseclass for all classes that wrap Bin.
Each class that adds functionality to a Bin must
extend this class to allow db4o to access the
delegate instance with
StorageDecorator.Decorate(BinConfiguration, IBin)
.
Representation of a container for storage of db4o
database data (to file, to memory).
Representation of a container for storage of db4o
database data (to file, to memory).
returns the length of the Bin (on disc, in memory).returns the length of the Bin (on disc, in memory).
reads a given number of bytes into an array of bytes at an
offset position.
reads a given number of bytes into an array of bytes at an
offset position.
the offset position to read at
the byte array to read bytes into
the number of bytes to be read
writes a given number of bytes from an array of bytes at
an offset position
the offset position to write at
the array of bytes to write
the number of bytes to write
flushes the buffer content to the physical storage
media.
flushes the buffer content to the physical storage
media.
runs the Runnable between two calls to sync();
reads a given number of bytes into an array of bytes at an
offset position.
reads a given number of bytes into an array of bytes at an
offset position. In contrast to the normal
Read(long, byte[], int)
method, the Bin should ensure direct access to the raw storage medium.
No caching should take place.
the offset position to read at
the byte array to read bytes into
the number of bytes to be read
closes the Bin.closes the Bin.Default constructor.Default constructor.
the
IBin
that is to be wrapped.
closes the BinDecorator and the underlying
IBin
.
IBin.Read(long, byte[], int)IBin.Sync()IBin.SyncRead(long, byte[], int)
IBin.Write(long, byte[], int)converts address and address offset to an absolute addresscopies a block within a file in block modecopies a block within a file in absolute modereads a buffer at the seeked addressthe number of bytes read and returnedimplement to read a buffer at the seeked addressreads a buffer at the seeked addressthe number of bytes read and returnedimplement to read a buffer at the seeked addressreads a buffer at the seeked addressthe number of bytes read and returnedreads a buffer at the seeked addressthe number of bytes read and returnedimplement to read a buffer at the seeked addressreads a buffer at the seeked addressthe number of bytes read and returnedimplement to read a buffer at the seeked addresswrites a buffer to the seeked addressreturns the block size currently usedoutside call to set the block size of this adapterBounded handle into an IoAdapter: Can only access a restricted area.Bounded handle into an IoAdapter: Can only access a restricted area.
The delegate I/O adapter
The block offset address into the I/O adapter that maps to the start index (0) of this window
The size of this window in bytes
Size of this I/O adapter window in bytes.
Offset in bytes relative to the window start
Data to write into the window starting from the given offset
Offset in bytes relative to the window start
Data buffer to read from the window starting from the given offset
Disable IO Adapter WindowFlush IO Adapter Window
CachedIoAdapter is an IOAdapter for random access files, which caches data
for IO access.
CachedIoAdapter is an IOAdapter for random access files, which caches data
for IO access. Its functionality is similar to OS cache.
Example: delegateAdapter = new RandomAccessFileAdapter(); config.Io(new CachedIoAdapter(delegateAdapter)); Base class for database file adapters, both for file and memory databases.
Base class for database file adapters, both for file and memory databases.
converts address and address offset to an absolute addresscopies a block within a file in block modesets the read/write pointer in the file using block modesets the read/write pointer in the file using block modeoutside call to set the block size of this adapterimplement to close the adaptercopies a block within a file in absolute modedeletes the given path from whatever 'file system' is addressedchecks whether a file existsimplement to return the absolute length of the fileimplement to open the filereads a buffer at the seeked addressthe number of bytes read and returnedimplement to read a buffer at the seeked addressimplement to set the read/write pointer in the file, absolute modeimplement to flush the file contents to storagewrites a buffer to the seeked addressimplement to write a buffer at the seeked addressreturns the block size currently usedDelegated IO Adapterreference to itself
Creates an instance of CachedIoAdapter with the default page size and
page count.
Creates an instance of CachedIoAdapter with the default page size and
page count.
delegate IO adapter (RandomAccessFileAdapter by default)
Creates an instance of CachedIoAdapter with a custom page size and page
count.
delegate IO adapter (RandomAccessFileAdapter by default)
cache page size
allocated amount of pages
Creates an instance of CachedIoAdapter with extended parameters.
database file path
determines if the file should be locked
initial file length, new writes will start from this point
if the file should be used in read-onlyt mode.
delegate IO adapter (RandomAccessFileAdapter by default)
cache page size
allocated amount of pages
Creates and returns a new CachedIoAdapter
database file path
determines if the file should be locked
initial file length, new writes will start from this point
Deletes the database file
file path
Checks if the file exists
file path
Reads the file into the buffer using pages from cache.
Reads the file into the buffer using pages from cache. If the next page
is not cached it will be read from the file.
destination buffer
how many bytes to read
Writes the buffer to cache using pages
source buffer
how many bytes to write
Flushes cache to a physical storageReturns the file lengthFlushes and closes the fileMoves the pointer to the specified file position
position within the file
Reads the file into the buffer using pages from cache.
Reads the file into the buffer using pages from cache. If the next page
is not cached it will be read from the file.
start position to read
destination buffer
how many bytes to read
Writes the buffer to cache using pages
start position to write
source buffer
how many bytes to write
Flushes cache to a physical storageReturns the file length
Caching storage adapter to cache db4o database data in memory
until the underlying
IBin
is instructed to flush its
data when
IBin.Sync()
is called.
You can override the
NewCache()
method if you want to
work with a different caching strategy.
Wrapper base class for all classes that wrap Storage.
Wrapper base class for all classes that wrap Storage.
Each class that adds functionality to a Storage must
extend this class.
Base interface for Storage adapters that open a
IBin
to store db4o database data to.
opens a
IBin
to store db4o database data.
returns true if a Bin (file or memory) exists with the passed name.returns true if a Bin (file or memory) exists with the passed name.Deletes the bin for the given URI from the storage.Deletes the bin for the given URI from the storage.7.9
bin URI
if the bin could not be deletedRenames the bin for the given old URI to the new URI.
Renames the bin for the given old URI to the new URI. If a bin for the new URI
exists, it will be overwritten.
7.9
URI of the existing bin
future URI of the bin
if the bin could not be deleted
default constructor to create a Caching storage with the default
page count of 64 and the default page size of 1024.
default constructor to create a Caching storage with the default
page count of 64 and the default page size of 1024.
the
IStorage
to be cached.
constructor to set up a CachingStorage with a configured page count
and page size
the
IStorage
to be cached.
the number of pages the cache should use.
the size of the pages the cache should use.
opens a Bin for the given URI.opens a Bin for the given URI.
override this method if you want to work with a different caching
strategy than the default LRU2Q cache.
override this method if you want to work with a different caching
strategy than the default LRU2Q cache.
Strategy for file/byte array growth by a constant factorStrategy for file/byte array growth.Strategy for file/byte array growth.
returns the incremented size after the growth
strategy has been applied
the original size
the new size, after the growth strategy has been
applied, must be bigger than curSize
The constant growth size
returns the incremented size after the growth
strategy has been applied
the original size
the new sizeStrategy for file/byte array growth that will always double the current size
Storage adapter to store db4o database data to physical
files on hard disc.
Storage adapter to store db4o database data to physical
files on hard disc.
opens a
IBin
on the specified URI (file system path).
returns true if the specified file system path already exists.returns true if the specified file system path already exists.Block size registry.
Block size registry.
Accessible through the environment.
Db4objects.Db4o.Foundation.Environments.My(System.Type<T>)
7.7Returns a copy of the raw data contained in this bin for external processing.
Returns a copy of the raw data contained in this bin for external processing.
Access to the data is not guarded by synchronisation. If this method is called
while the MemoryBin is in use, it is possible that the returned byte array is
not consistent.
for internal processing only.for internal processing only.IStorage
implementation that produces
IBin
instances
that operate in memory.
Use this
IStorage
to work with db4o as an in-memory database.
returns true if a MemoryBin with the given URI name already exists
in this Storage.
returns true if a MemoryBin with the given URI name already exists
in this Storage.
opens a MemoryBin for the given URI (name can be freely chosen).opens a MemoryBin for the given URI (name can be freely chosen).Returns the memory bin for the given URI for external use.Returns the memory bin for the given URI for external use.Registers the given bin for this storage with the given URI.Registers the given bin for this storage with the given URI.
Storage adapter that does not pass flush calls
on to its delegate.
Storage adapter that does not pass flush calls
on to its delegate.
You can use this
IStorage
for improved db4o
speed at the risk of corrupted database files in
case of system failure.
IStorage
implementation that produces
IBin
instances
that operate in memory.
Use this
IStorage
to work with db4o as an in-memory database.
returns true if a MemoryBin with the given URI name already exists
in this Storage.
returns true if a MemoryBin with the given URI name already exists
in this Storage.
opens a MemoryBin for the given URI (name can be freely chosen).opens a MemoryBin for the given URI (name can be freely chosen).Returns the memory bin for the given URI for external use.Returns the memory bin for the given URI for external use.Registers the given bin for this storage with the given URI.Registers the given bin for this storage with the given URI.IO adapter for random access files.IO adapter for random access files.base class for IoAdapters that delegate to other IoAdapters (decorator pattern)
allows registration with a transaction to be notified of
commit and rollback
a buffer interface with methods to read and to position
the read pointer in the buffer.
a buffer interface with methods to read and to position
the read pointer in the buffer.
returns the current offset in the bufferthe offsetreads a byte from the buffer.reads a byte from the buffer.the bytereads an array of bytes from the buffer.
reads an array of bytes from the buffer.
The length of the array that is passed as a parameter specifies the
number of bytes that are to be read. The passed bytes buffer parameter
is directly filled.
the byte array to read the bytes into.
reads an int from the buffer.reads an int from the buffer.the intreads a long from the buffer.reads a long from the buffer.the longpositions the read pointer at the specified position
the desired position in the buffer
common functionality for
IReadContext
and
IWriteContext
and
Db4objects.Db4o.Internal.Delete.IDeleteContext
Controls how deep an object graph is activated.Controls how deep an object graph is activated.
Activates a fixed depth of the object graph regardless of
any existing activation depth configuration settings.
Activates a fixed depth of the object graph regardless of
any existing activation depth configuration settings.
Activates the full object graph.Activates the full object graph.Factory for ActivationDepth strategies.Factory for ActivationDepth strategies.Returns an ActivationDepth suitable for the specified class and activation mode.
Returns an ActivationDepth suitable for the specified class and activation mode.
root class that's being activated
activation mode
an appropriate ActivationDepth for the class and activation modeReturns an ActivationDepth that will activate at most *depth* levels.
Returns an ActivationDepth that will activate at most *depth* levels.
A special case is Integer.MAX_VALUE (int.MaxValue for .net) for which a
FullActivationDepth object must be returned.
Activates an object graph to a specific depth respecting any
activation configuration settings that might be in effect.
Activates an object graph to a specific depth respecting any
activation configuration settings that might be in effect.
Transparent Activation strategy.Transparent Activation strategy.A transaction local variable.A transaction local variable.Transaction.Get(TransactionLocal)
Transfer of blobs to and from the db4o system,
if users use the Blob Db4oType.
Transfer of blobs to and from the db4o system,
if users use the Blob Db4oType.
com.db4o.internal.blobs
the db4o Blob type to store blobs independent of the main database
file and allows to perform asynchronous upload and download operations.
the db4o Blob type to store blobs independent of the main database
file and allows to perform asynchronous upload and download operations.
Usage:
- Define Blob fields on your user classes.
- As soon as an object of your class is stored, db4o automatically
takes care that the Blob field is set.
- Call readFrom to read a blob file into the db4o system.
- Call writeTo to write a blob file from within the db4o system.
- getStatus may help you to determine, whether data has been
previously stored. It may also help you to track the completion
of the current process.
db4o client/server carries out all blob operations in a separate
thread on a specially dedicated socket. One socket is used for
all blob operations and operations are queued. Your application
may continue to access db4o while a blob is transferred in the
background.
returns the name of the file the blob was stored to.
returns the name of the file the blob was stored to.
The method may return null, if the file was never
stored.
String the name of the file.returns the status after the last read- or write-operation.
returns the status after the last read- or write-operation.
The status value returned may be any of the following: Db4objects.Db4o.Ext.Status.Unused
no data was ever stored to the Blob field. Db4objects.Db4o.Ext.Status.Available
available data was previously stored to the Blob field. Db4objects.Db4o.Ext.Status.Queued
an operation was triggered and is waiting for it's turn in the Blob queue. Db4objects.Db4o.Ext.Status.Completed
the last operation on this field was completed successfully. Db4objects.Db4o.Ext.Status.Processing
for internal use only. Db4objects.Db4o.Ext.Status.Error
the last operation failed.
or a double between 0 and 1 that signifies the current completion percentage of the currently
running operation.
the five
Db4objects.Db4o.Ext.Status
constants defined in this interface or a double
between 0 and 1 that signifies the completion of the currently running operation.
status - the current statusconstantsreads a file into the db4o system and stores it as a blob.
reads a file into the db4o system and stores it as a blob.
In Client/Server mode db4o will open an additional socket and
process writing data in an additional thread.
the file the blob is to be read from.
in case of errorsreads a file into the db4o system and stores it as a blob.
reads a file into the db4o system and stores it as a blob.
db4o will use the local file system in Client/Server mode also.
the file the blob is to be read from.
in case of errorswrites stored blob data to a file.
writes stored blob data to a file.
db4o will use the local file system in Client/Server mode also.
in case of errors and in case no blob
data was stored
the file the blob is to be written to.
writes stored blob data to a file.
writes stored blob data to a file.
In Client/Server mode db4o will open an additional socket and
process writing data in an additional thread.
in case of errors and in case no blob
data was stored
the file the blob is to be written to.
Deletes the current file stored in this BLOB.Deletes the current file stored in this BLOB.
in case of errors and in case no
data was stored
marker interface for special db4o datatypesAll instantiated nodes are held in this tree.All instantiated nodes are held in this tree.
We work with BTreeNode in two states:
- deactivated: never read, no valid members, ID correct or 0 if new
- write: real representation of keys, values and children in arrays
The write state can be detected with canWrite().
We work with BTreeNode in two states:
- deactivated: never read, no valid members, ID correct or 0 if new
- write: real representation of keys, values and children in arrays
The write state can be detected with canWrite(). States can be changed
as needed with prepareRead() and prepareWrite().
Can contain BTreeNode or Integer for ID of BTreeNode
the split node if this node is split
or this if the first key has changed
This traversal goes over all nodes, not just leafs
Iterates through all the valid pointers in
this range.
Iterates through all the valid pointers in
this range.
an Iterator4 over BTreePointer valueInterface for comparison support in queries.Interface for comparison support in queries.
creates a prepared comparison to compare multiple objects
against one single object.
creates a prepared comparison to compare multiple objects
against one single object.
the context of the comparison
the object that is to be compared
against multiple other objects
the prepared comparison
Composite key for field indexes, first compares on the actual
indexed field _value and then on the _parentID (which is a
reference to the containing object).
Composite key for field indexes, first compares on the actual
indexed field _value and then on the _parentID (which is a
reference to the containing object).
a buffer interface with write methods.a buffer interface with write methods.writes a single byte to the buffer.writes a single byte to the buffer.
the byte
writes an array of bytes to the buffer
the byte array
writes an int to the buffer.writes an int to the buffer.
the int
writes a long to the buffer
the long
non-encrypted read, used for indexes
Retrieves the value associated to the
key
from the cache. If the value is not yet
cached
producer
will be called to produce it. If the cache needs to discard a value
finalizer
will be given a chance to process it.
the key for the value - must never change - cannot be null
will be called if value not yet in the cache - can only be null when the value is found in the cache
will be called if a page needs to be discarded - can be null
the cached valueRemoves the cached value with the specified key from this cache.Removes the cached value with the specified key from this cache.the purged value or null
Simplified version of the algorithm taken from here:
http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.34.2641
Simplified version of the algorithm taken from here:
http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.34.2641
Full version of the algorithm taken from here:
http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.34.2641
For reference types, _typeHandler always holds a StandardReferenceTypeHandler
that will use the _aspects of this class to take care of its business.
For reference types, _typeHandler always holds a StandardReferenceTypeHandler
that will use the _aspects of this class to take care of its business. A custom
type handler would appear as a TypeHandlerAspect in that case.
For value types, _typeHandler always holds the actual value type handler be it
a custom type handler or a builtin one.
no any, primitive, array or other tricks.
no any, primitive, array or other tricks. overridden in YapClassAny and
YapClassPrimitive
TODO: remove this class or make it private to ClassMetadataRepositoryTraverses all index entries (java.lang.Integer references).Traverses all index entries (java.lang.Integer references).
handles reading, writing, deleting, defragmenting and
comparisons for types of objects.
Custom Typehandlers can be implemented to alter the default
behaviour of storing all non-transient fields of an object.
Db4objects.Db4o.Config.IConfiguration.RegisterTypeHandler(ITypeHandlerPredicate, ITypeHandler4)
gets called when an object gets deleted.gets called when an object gets deleted.Db4objects.Db4o.Ext.Db4oIOException
gets called when an object gets defragmented.gets called when an object gets defragmented.gets called when an object is to be written to the database.gets called when an object is to be written to the database.
the object
gets called when an object is to be activated.gets called when an object is to be activated.TypeHandler for objects with members.TypeHandler for objects with members.
will be called during activation if the handled
object is already active
will be called during querying to ask for the handler
to be used to collect children of the handled object
will be called during querying to ask for IDs of member
objects of the handled object.
will be called during querying to ask for IDs of member
objects of the handled object.
TODO: refactor for symmetric inheritance - don't inherit from YapField and override,
instead extract an abstract superclass from YapField and let both YapField and this class implement
dirty hack for com.db4o.types some of them (BlobImpl) need to be set automatically
TODO: Derive from FieldMetadata for Db4oTypes
Will raise an exception if argument class doesn't match this class - violates equals() contract in favor of failing fast.
Will raise an exception if argument class doesn't match this class - violates equals() contract in favor of failing fast.
We are running into cyclic dependancies on reading the PBootRecord
object, if we maintain MetaClass information there
Configuration template for creating new db4o filesmessage sender for client/server messaging.
message sender for client/server messaging.
db4o allows using the client/server TCP connection to send
messages from the client to the server. Any object that can be
stored to a db4o database file may be used as a message.
For an example see Reference documentation:
http://developer.db4o.com/Resources/view.aspx/Reference/Client-Server/Messaging
http://developer.db4o.com/Resources/view.aspx/Reference/Client-Server/Remote_Code_Execution
See Also: Db4objects.Db4o.Config.IClientServerConfiguration.GetMessageSender()
, IMessageRecipient
, Db4objects.Db4o.Config.IClientServerConfiguration.SetMessageRecipient(IMessageRecipient)
sends a message to the server.sends a message to the server.
the message parameter, any object may be used.
Returns an iterator for all
Db4objects.Db4o.Config.IConfigurationItem
instances
added.
Add(Db4objects.Db4o.Config.IConfigurationItem)
the iteratorThe ConfigImpl also is our messageSenderTODO: Split into separate enums with defined range and values.*only used by old handlers: OpenTypeHandler0, StringHandler0, ArrayHandler0.
only used by old handlers: OpenTypeHandler0, StringHandler0, ArrayHandler0.
Doesn't need to work with modern IdSystems.
only used by old handlers: OpenTypeHandler0, StringHandler0, ArrayHandler0.
only used by old handlers: OpenTypeHandler0, StringHandler0, ArrayHandler0.
Doesn't need to work with modern IdSystems.
Base class for balanced trees.Base class for balanced trees.
this interface is passed to internal class
Db4objects.Db4o.Typehandlers.ITypeHandler4
when instantiating objects.
Interprets the current position in the context as
an ID and returns the object with this ID.
Interprets the current position in the context as
an ID and returns the object with this ID.
the object
reads sub-objects, in cases where the
Db4objects.Db4o.Typehandlers.ITypeHandler4
is known.
FIXME: remove me from the core and make me a facade over Eventskeep the position in the array.
keep the position in the array.
Information is used to look up encodings.
Note the different implementation when compared to LatinStringIO and UnicodeStringIO:
Instead of writing the length of the string, UTF8StringIO writes the length of the
byte array.
Note the different implementation when compared to LatinStringIO and UnicodeStringIO:
Instead of writing the length of the string, UTF8StringIO writes the length of the
byte array.
Marker interface to denote that a class should not be stored by db4o.Marker interface to denote that a class should not be stored by db4o.Workaround to provide the Java 5 version with a hook to add ExtObjectContainer.
Workaround to provide the Java 5 version with a hook to add ExtObjectContainer.
(Generic method declarations won't match ungenerified YapStreamBase implementations
otherwise and implementing it directly kills .NET conversion.)
allows special handling for all Db4oType objects.
allows special handling for all Db4oType objects.
Redirected here from #set() so only instanceof check is necessary
in the #set() method.
object if handled here and #set() should not continue processing
Differentiating getActiveClassMetadata from getYapClass is a tuning
optimization: If we initialize a YapClass, #set3() has to check for
the possibility that class initialization associates the currently
stored object with a previously stored static object, causing the
object to be known afterwards.
Differentiating getActiveClassMetadata from getYapClass is a tuning
optimization: If we initialize a YapClass, #set3() has to check for
the possibility that class initialization associates the currently
stored object with a previously stored static object, causing the
object to be known afterwards.
In this call we only return active YapClasses, initialization
is not done on purpose
Objects implementing the "Internal4" marker interface are
not visible to queries, unless this flag is set to true.
Objects implementing the "Internal4" marker interface are
not visible to queries, unless this flag is set to true.
The caller should reset the flag after the call.
overridden in ClientObjectContainer
The method allows checking whether will make it easier to refactor than
an "instanceof YapClient" check.
overridden in ClientObjectContainer
The method allows checking whether will make it easier to refactor than
an "instanceof YapClient" check.
This interface is not used in .NET.
Implement to compare two arguments for sorting.
Implement to compare two arguments for sorting.
Return a negative value, zero, or a positive value if
the first argument is smaller, equal or greater than
the second.
Old freespacemanager, before version 7.0.
Old freespacemanager, before version 7.0.
If it is still in use freespace is dropped.
BTreeFreespaceManager
should be used instead.
TODO: This class was written to make ObjectContainerBase
leaner, so TransportObjectContainer has less members.
All functionality of this class should become part of
ObjectContainerBase and the functionality in
ObjectContainerBase should delegate to independent
modules without circular references.
This is the latest version, the one that should be used.This is the latest version, the one that should be used.gets called when an value type is to be read from the database.gets called when an value type is to be read from the database.the read value type
marker interface for TypeHandlers where the slot
length can change, depending on the object stored
n-dimensional arrayShared (java/.net) logic for Date handling.Shared (java/.net) logic for Date handling.Tyehandler for naked plain objects (java.lang.Object).Tyehandler for naked plain objects (java.lang.Object).This readIndexEntry method reads from the parent slot.This readIndexEntry method reads from the parent slot.This readIndexEntry method reads from the actual index in the file.This readIndexEntry method reads from the actual index in the file.
returns: -x for left is greater and +x for right is greater
FIXME: The returned value is the wrong way around.
returns: -x for left is greater and +x for right is greater
FIXME: The returned value is the wrong way around.
TODO: You will need collators here for different languages.
A weak reference to an known object.
A weak reference to an known object.
"Known" ~ has been stored and/or retrieved within a transaction.
References the corresponding ClassMetaData along with further metadata:
internal id, UUID/version information, ...
return false if class not completely initialized, otherwise trueHCTREEIDTREEfor testing purposes only.for testing purposes only.
This is the inside representation to operate against, the actual
file-based ObjectContainerBase or the client.
This is the inside representation to operate against, the actual
file-based ObjectContainerBase or the client. For all calls
against this ObjectContainerBase the method signatures that take
a transaction have to be used.
This is the outside representation to the user.
This is the outside representation to the user. This ObjectContainer
should use this transaction as it's main user transation, so it also
allows using the method signatures on ObjectContainer without a
transaction.
Retrieves the value of a transaction local variables.
Retrieves the value of a transaction local variables.
If this is the first time the variable is accessed
TransactionLocal.InitialValueFor(Transaction)
will provide the initial value.
Represents a db4o file format version, assembles all the marshallers
needed to read/write this specific version.
Represents a db4o file format version, assembles all the marshallers
needed to read/write this specific version.
A marshaller knows how to read/write certain types of values from/to its
representation on disk for a given db4o file format version.
Responsibilities are somewhat overlapping with TypeHandler's.
this interface is passed to internal class
Db4objects.Db4o.Typehandlers.ITypeHandler4
during marshaling
and provides methods to marshal objects.
makes sure the object is stored and writes the ID of
the object to the context.
makes sure the object is stored and writes the ID of
the object to the context.
Use this method for first class objects only (objects that
have an identity in the database). If the object can potentially
be a primitive type, do not use this method but use
a matching
IWriteBuffer
method instead.
the object to write.
writes sub-objects, in cases where the
Db4objects.Db4o.Typehandlers.ITypeHandler4
is known.
typehandler to be used to write the object.
the object to write
reserves a buffer with a specific length at the current
position, to be written in a later step.
reserves a buffer with a specific length at the current
position, to be written in a later step.
the length to be reserved.
the ReservedBufferWraps the low-level details of reading a Buffer, which in turn is a glorified byte array.
Wraps the low-level details of reading a Buffer, which in turn is a glorified byte array.
this interface is passed to reference type handlers.this interface is passed to reference type handlers.a reserved buffer within a write buffer.
a reserved buffer within a write buffer.
The usecase this class was written for: A null bitmap should be at the
beginning of a slot to allow lazy processing. During writing the content
of the null bitmap is not yet fully known until all members are processed.
With the Reservedbuffer the space in the slot can be occupied and writing
can happen after all members are processed.
writes a byte array to the reserved buffer.writes a byte array to the reserved buffer.
the byte array.
a node in a QLin ("Coolin") query.
a node in a QLin ("Coolin") query.
QLin is a new experimental query interface.
We would really like to have LINQ for Java instead.
8.0adds a where node to this QLin query.adds a where node to this QLin query.
can be any of the following:
executes the QLin query and returns the result
as an
Db4objects.Db4o.IObjectSet
.
Note that ObjectSet extends List and Iterable
on the platforms that support these interfaces.
You may want to use these interfaces instead of
working directly against an ObjectSet.
orders the query by the expression.
orders the query by the expression.
Use the
QLinSupport.Ascending()
and
QLinSupport.Descending()
helper methods to set the direction.
FIXME: Rename to Db4oEnhancedPredicatefor implementation of callback evaluations.
for implementation of callback evaluations.
To constrain a
IQuery
node with your own callback
Evaluation, construct an object that implements the
Evaluation interface and register it by passing it
to
IQuery.Constrain(object)
.
Evaluations are called as the last step during query execution,
after all other constraints have been applied. Evaluations in higher
level
IQuery
nodes in the query graph are called first.
Java client/server only:
db4o first attempts to use Java Serialization to allow to pass final
variables to the server. Please make sure that all variables that are
used within the
Evaluate(ICandidate)
method are Serializable. This may include
the class an anonymous Evaluation object is created in. If db4o is
not successful at using Serialization, the Evaluation is transported
to the server in a db4o
Db4objects.Db4o.IO.MemoryBin
. In this case final variables can
not be restored.
callback method during
query execution
.
reference to the candidate persistent object.
Represents an actual object in the database.
Represents an actual object in the database. Forms a tree structure, indexed
by id. Can have dependents that are doNotInclude'd in the query result when
this is doNotInclude'd.
candidate for
IEvaluation
callbacks.
During
query execution
all registered
IEvaluation
callback
handlers are called with
ICandidate
proxies that represent the persistent objects that
meet all other
IQuery
criteria.
A
ICandidate
provides access to the persistent object it
represents and allows to specify, whether it is to be included in the
Db4objects.Db4o.IObjectSet
resultset.
returns the persistent object that is represented by this query
ICandidate
.
Object the persistent object.
specify whether the Candidate is to be included in the
Db4objects.Db4o.IObjectSet
resultset.
This method may be called multiple times. The last call prevails.
inclusion.
returns the
Db4objects.Db4o.IObjectContainer
the Candidate object is stored in.
the
Db4objects.Db4o.IObjectContainerFor external interface use only.
For external interface use only. Call doNotInclude() internally so
dependancies can be checked.
Holds the tree of
QCandidate
objects and the list of
QCon
during query evaluation.
The query work (adding and removing nodes) happens here.
Candidates during query evaluation.
QCandidate
objects are stored in i_root
Base class for all constraints on queries.Base class for all constraints on queries.
constraint to limit the objects returned upon
query execution
.
Constraints are constructed by calling
Db4objects.Db4o.Query.IQuery.Constrain
.
Constraints can be joined with the methods
Db4objects.Db4o.Query.IConstraint.And
and
Db4objects.Db4o.Query.IConstraint.Or
.
The methods to modify the constraint evaluation algorithm may
be merged, to construct combined evaluation rules.
Examples:
Constraint.Smaller().Equal() for "smaller or equal"
Constraint.Not().Like() for "not like"
Constraint.Not().Greater().Equal() for "not greater or equal"
links two Constraints for AND evaluation.
links two Constraints for AND evaluation.
For example: query.Constrain(typeof(Pilot)); query.Descend("points").Constrain(101).Smaller().And(query.Descend("name").Constrain("Test Pilot0"));
will retrieve all pilots with points less than 101 and name as "Test Pilot0"
the other
Db4objects.Db4o.Query.IConstraint
a new
Db4objects.Db4o.Query.IConstraint
, that can be used for further calls
to
And
and
Orlinks two Constraints for OR evaluation.
links two Constraints for OR evaluation.
For example:
query.Constrain(typeof(Pilot)); query.Descend("points").Constrain(101).Greater().Or(query.Descend("name").Constrain("Test Pilot0"));
will retrieve all pilots with points more than 101 or pilots with the name "Test Pilot0"
the other
Db4objects.Db4o.Query.IConstraint
a new
Db4objects.Db4o.Query.IConstraint
, that can be used for further calls
to
And
and
Or
Used in conjunction with
Db4objects.Db4o.Query.IConstraint.Smaller
or
Db4objects.Db4o.Query.IConstraint.Greater
to create constraints
like "smaller or equal", "greater or equal".
For example: query.Constrain(typeof(Pilot)); query.Descend("points").Constrain(101).Smaller().Equal();
will return all pilots with points <= 101.
this
Db4objects.Db4o.Query.IConstraint
to allow the chaining of method calls.
sets the evaluation mode to >.
sets the evaluation mode to >.
For example: query.Constrain(typeof(Pilot)); query.Descend("points").Constrain(101).Greater()
will return all pilots with points > 101.
this
Db4objects.Db4o.Query.IConstraint
to allow the chaining of method calls.
sets the evaluation mode to <.
sets the evaluation mode to <.
For example: query.Constrain(typeof(Pilot)); query.Descend("points").Constrain(101).Smaller()
will return all pilots with points < 101.
this
Db4objects.Db4o.Query.IConstraint
to allow the chaining of method calls.
sets the evaluation mode to identity comparison.
sets the evaluation mode to identity comparison. In this case only
objects having the same database identity will be included in the result set.
For example: Pilot pilot = new Pilot("Test Pilot1", 100); Car car = new Car("BMW", pilot); container.Store(car); // Change the name, the pilot instance stays the same pilot.SetName("Test Pilot2"); // create a new car car = new Car("Ferrari", pilot); container.Store(car); IQuery query = container.Query(); query.Constrain(typeof(Car)); // All cars having pilot with the same database identity // will be retrieved. As we only created Pilot object once // it should mean all car objects query.Descend("_pilot").Constrain(pilot).Identity();
this
Db4objects.Db4o.Query.IConstraint
to allow the chaining of method calls.
set the evaluation mode to object comparison (query by example).set the evaluation mode to object comparison (query by example).
this
IConstraint
to allow the chaining of method calls.
sets the evaluation mode to "like" comparison.
sets the evaluation mode to "like" comparison. This mode will include
all objects having the constrain expression somewhere inside the string field.
For example: Pilot pilot = new Pilot("Test Pilot1", 100); container.Store(pilot); ... query.Constrain(typeof(Pilot)); // All pilots with the name containing "est" will be retrieved query.Descend("name").Constrain("est").Like();
this
Db4objects.Db4o.Query.IConstraint
to allow the chaining of method calls.
Sets the evaluation mode to string contains comparison.
Sets the evaluation mode to string contains comparison. The contains comparison is case sensitive.
For example: Pilot pilot = new Pilot("Test Pilot1", 100); container.Store(pilot); ... query.Constrain(typeof(Pilot)); // All pilots with the name containing "est" will be retrieved query.Descend("name").Constrain("est").Contains(); Like() for case insensitive string comparison
this
Db4objects.Db4o.Query.IConstraint
to allow the chaining of method calls.
sets the evaluation mode to string StartsWith comparison.
sets the evaluation mode to string StartsWith comparison.
For example: Pilot pilot = new Pilot("Test Pilot0", 100); container.Store(pilot); ... query.Constrain(typeof(Pilot)); query.Descend("name").Constrain("Test").StartsWith(true);
comparison will be case sensitive if true, case insensitive otherwise
this
Db4objects.Db4o.Query.IConstraint
to allow the chaining of method calls.
sets the evaluation mode to string EndsWith comparison.
sets the evaluation mode to string EndsWith comparison.
For example: Pilot pilot = new Pilot("Test Pilot0", 100); container.Store(pilot); ... query.Constrain(typeof(Pilot)); query.Descend("name").Constrain("T0").EndsWith(false);
comparison will be case sensitive if true, case insensitive otherwise
this
Db4objects.Db4o.Query.IConstraint
to allow the chaining of method calls.
turns on Not() comparison.
turns on Not() comparison. All objects not fullfilling the constrain condition will be returned.
For example: Pilot pilot = new Pilot("Test Pilot1", 100); container.Store(pilot); ... query.Constrain(typeof(Pilot)); query.Descend("name").Constrain("t0").EndsWith(true).Not();
this
Db4objects.Db4o.Query.IConstraint
to allow the chaining of method calls.
returns the Object the query graph was constrained with to
create this
IConstraint
.
Object the constraining object.Class constraint on queriesObject constraint on queriesJoin constraint on queries
Placeholder for a constraint, only necessary to attach children
to the query graph.
Placeholder for a constraint, only necessary to attach children
to the query graph.
Added upon a call to Query#descend(), if there is no
other place to hook up a new constraint.
Array of constraints for queries.
Array of constraints for queries.
Necessary to be returned to Query#constraints()
set of
IConstraint
objects.
This extension of the
IConstraint
interface allows
setting the evaluation mode of all contained
IConstraint
objects with single calls.
See also
IQuery.Constraints()
.
returns an array of the contained
IConstraint
objects.
an array of the contained
IConstraint
objects.
Query Evaluator - Represents such things as >, >=, <, <=, EQUAL, LIKE, etc.
Query Evaluator - Represents such things as >, >=, <, <=, EQUAL, LIKE, etc.
Specifies which part of the index to take.
Specifies which part of the index to take.
Array elements:
[0] - smaller
[1] - equal
[2] - greater
[3] - nulls
for C/S messaging onlyfor C/S messaging onlyfor C/S messaging onlyfor C/S messaging onlyQQuery is the users hook on our graph.
QQuery is the users hook on our graph.
A QQuery is defined by it's constraints.
QQuery is the users hook on our graph.
QQuery is the users hook on our graph.
A QQuery is defined by it's constraints.
NOTE: This is just a 'partial' base class to allow for variant implementations
in db4oj and db4ojdk1.2. It assumes that itself is an instance of QQuery
and should never be used explicitly.
Search for slot that corresponds to class.
Search for slot that corresponds to class. If not found add it.
Constrain it. Public so it can be used by the LINQ test cases.Public so it can be used by the LINQ test cases.handle to a node in a S.O.D.A.
handle to a node in a S.O.D.A. query graph.
A node in the query graph can represent multiple
classes, one class or an attribute of a class.
The graph
is automatically extended with attributes of added constraints
(see
Constrain(object)
) and upon calls to
Descend(string)
that request nodes that do not yet exist.
References to joined nodes in the query graph can be obtained
by "walking" along the nodes of the graph with the method
Descend(string)
.
Execute()
evaluates the entire graph against all persistent objects.
Execute()
can be called from any
IQuery
node
of the graph. It will return an
Db4objects.Db4o.IObjectSet
filled with
objects of the class/classes that the node, it was called from,
represents.
Note: Native queries
are the recommended main query
interface of db4o.adds a constraint to this node.
adds a constraint to this node.
If the constraint contains attributes that are not yet
present in the query graph, the query graph is extended
accordingly.
Special behaviour for:
class
System.Type<T>
: confine the result to objects of one
class or to objects implementing an interface.
interface
IEvaluation
: run
evaluation callbacks against all candidates.
the constraint to be added to this Query.
IConstraint
a new
IConstraint
for this
query node or null for objects implementing the
IEvaluation
interface.
returns a
IConstraints
object that holds an array of all constraints on this node.
IConstraints
on this query node.
returns a reference to a descendant node in the query graph.
returns a reference to a descendant node in the query graph.
If the node does not exist, it will be created.
All classes represented in the query node are tested, whether
they contain a field with the specified field name. The
descendant Query node will be created from all possible candidate
classes.
path to the descendant.
descendant
IQuery
node
executes the
IQuery
.
Db4objects.Db4o.IObjectSet
- the result of the
IQuery
.
adds an ascending ordering criteria to this node of
the query graph.
adds an ascending ordering criteria to this node of
the query graph.
If multiple ordering criteria are applied, the chronological
order of method calls is relevant: criteria created by 'earlier' calls are
considered more significant, i.e. 'later' criteria only have an effect
for elements that are considered equal by all 'earlier' criteria.
As an example, consider a type with two int fields, and an instance set
{(a:1,b:3),(a:2,b:2),(a:1,b:2),(a:2,b:3)}. The call sequence [orderAscending(a),
orderDescending(b)] will result in [(a:1,b:3),(a:1,b:2),(a:2,b:3),(a:2,b:2)].
this
IQuery
object to allow the chaining of method calls.
adds a descending order criteria to this node of
the query graph.
adds a descending order criteria to this node of
the query graph.
For semantics of multiple calls setting ordering criteria, see
OrderAscending()
.
this
IQuery
object to allow the chaining of method calls.
Sort the resulting ObjectSet by the given comparator.Sort the resulting ObjectSet by the given comparator.
The comparator to apply.
this
IQuery
object to allow the chaining of method calls.
db4o-specific exception.
This exception is thrown when one of the db4o reflection methods fails.
db4o-specific exception.
This exception is thrown when one of the db4o reflection methods fails.
Db4objects.Db4o.ReflectConstructor with the cause exception
cause exception
Constructor with message
detailed explanation
7.77.77.7
Use the methods in this class for system classes only, since they
are not ClassLoader or Reflector-aware.
TODO: this class should go to foundation.reflect, along with ReflectException and ReflectPlatform
calling this method "method" will break C# conversion with the old converter
FIXME: Check where pointers should be freed on commit.
FIXME: Check where pointers should be freed on commit.
This should be triggered in this class.
public for .NET conversion reasons
TODO: Split this class for individual usecases.
public for .NET conversion reasons
TODO: Split this class for individual usecases. Only use the member
variables needed for the respective usecase.
TODO: Check if all time-consuming stuff is overridden!
no reading
no writing
no updates
no weak references
navigation by ID only both sides need synchronised ClassCollections and
MetaInformationCaches
Additional message-related information.Additional message-related information.The container the message was dispatched to.The container the message was dispatched to.The sender of the current message.
The sender of the current message.
The reference can be used to send a reply to it.
The transaction the current message has been sent with.The transaction the current message has been sent with.message recipient for client/server messaging.
message recipient for client/server messaging.
db4o allows using the client/server TCP connection to send
messages from the client to the server. Any object that can be
stored to a db4o database file may be used as a message.
For an example see Reference documentation:
http://developer.db4o.com/Resources/view.aspx/Reference/Client-Server/Messaging
http://developer.db4o.com/Resources/view.aspx/Reference/Client-Server/Remote_Code_Execution
See Also: ClientServerConfiguration.setMessageRecipient(MessageRecipient)
, IMessageSender
, Db4objects.Db4o.Config.IClientServerConfiguration.GetMessageSender()
, MessageRecipientWithContext the method called upon the arrival of messages.the method called upon the arrival of messages.
contextual information for the message.
the message received.
support for the new experimental QLin ("Coolin") query interface.
support for the new experimental QLin ("Coolin") query interface.
We would really like to have LINQ for Java instead.
8.0
starts a
IQLin
query against a class.
creates prototype objects for classes.
creates prototype objects for classes. Each field on prototype objects is set
to a newly created object or primitive that can be identified either by it's
identity or by an int ID that is generated by the system. Creation of fields
is recursed to the depth specified in the constructor.
Allows analyzing expressions called on prototype objects to find the
underlying field that delivers the return value of the expression. Passed
expressions should not have side effects on objects, otherwise the
"prototype world" will no longer work.
We plan to supply an ImmutableFieldClassLoader to instrument the code to
throw on every modification. This ClassLoader could also supply information
about all the method calls involved.
For now our approach only works if expressions are directly backed by a
single field.
We were inspired for this approach when we saw that Thomas Mueller managed to
map expressions to fields for his JaQu query interface, Kudos!
http://www.h2database.com/html/jaqu.html
We took the idea a bit further and made it work for all primitives except for
boolean and we plan to also get deeper expressions, collections and
interfaces working nicely.
returns a prototype object for a specific class.returns a prototype object for a specific class.
analyzes the passed expression and tries to find the path to the
backing field that is accessed.
analyzes the passed expression and tries to find the path to the
backing field that is accessed.
analyzes the passed expression and tries to find the path to the
backing field that is accessed.
analyzes the passed expression and tries to find the path to the
backing field that is accessed.
analyzes the passed expression and tries to find the path to the
backing field that is accessed.
analyzes the passed expression and tries to find the path to the
backing field that is accessed.
exception for the the Prototypes world.exception for the the Prototypes world.
exceptions to signal improper use of the
IQLin
query interface.
Internal implementation class, access should not be necessary,
except for implementors.
Internal implementation class, access should not be necessary,
except for implementors.
Use the static methods in
QLinSupportQLinSupport.Ascending()
and
QLinSupport.Descending()
static import support class for
IQLin
queries.
8.0
returns a prototype object for a specific class
to be passed to the where expression of a QLin
query.
returns a prototype object for a specific class
to be passed to the where expression of a QLin
query.
IQLin.Where(object)sets the context for the next query on this thread.
sets the context for the next query on this thread.
This method should never have to be called manually.
The framework should set the context up.
sets the context for the next query on this thread.
sets the context for the next query on this thread.
This method should never have to be called manually.
The framework should set the context up.
shortcut for the
Prototype(System.Type<T>)
method.
parameter for
IQLin.OrderBy(object, QLinOrderByDirection)
parameter for
IQLin.OrderBy(object, QLinOrderByDirection)
public for implementors, do not use directlyconverts an expression to a single field.converts an expression to a single field.Base class for native queries.
Base class for native queries.
Native Queries provide the ability to run one or more lines
of code against all instances of a class. Native query expressions should
return true to mark specific instances as part of the result set.
db4o will attempt to optimize native query expressions and run them
against indexes and without instantiating actual objects, where this is
possible.
The syntax of the enclosing object for the native query expression varies
slightly, depending on the language version used. Here are some examples,
how a simple native query will look like in some of the programming languages and
dialects that db4o supports:
public class CatOccam : Predicate {
public boolean Match(Cat cat) {
return cat.Name == "Occam";
}
});
Summing up the above:
In order to run a Native Query, you can
- use the delegate notation for .NET 2.0.
- extend the Predicate class for all other language dialects
A class that extends Predicate is required to
implement the #match() / #Match() method, following the native query
conventions:
- The name of the method is "#match()" (Java) / "#Match()" (.NET).
- The method must be public public.
- The method returns a boolean.
- The method takes one parameter.
- The Type (.NET) / Class (Java) of the parameter specifies the extent.
- For all instances of the extent that are to be included into the
resultset of the query, the match method should return true. For all
instances that are not to be included, the match method should return
false.
public for implementation reasons, please ignore.public for implementation reasons, please ignore.public for implementation reasons, please ignore.public for implementation reasons, please ignore.public for implementation reasons, please ignore.public for implementation reasons, please ignore.Reflection Array representation.
Reflection Array representation
See documentation for System.Reflection API.
IReflectorReflection Class representation.
Reflection Class representation
See documentation for System.Reflection API.
IReflectorReturns the ReflectClass instance being delegated to.
Returns the ReflectClass instance being delegated to.
If there's no delegation it should return this.
delegate or this
Calling this method may change the internal state of the class, even if a usable
constructor has been found on earlier invocations.
Calling this method may change the internal state of the class, even if a usable
constructor has been found on earlier invocations.
true, if instances of this class can be created, false otherwise
We need this for replication, to find out if a class needs to be traversed
or if it simply can be copied across.
We need this for replication, to find out if a class needs to be traversed
or if it simply can be copied across. For now we will simply return
the classes that are
IsPrimitive()
and
Db4objects.Db4o.Internal.Platform4.IsSimple(System.Type<T>)
We can think about letting users add an Immutable annotation.
Reflection Constructor representation.
Reflection Constructor representation
See documentation for System.Reflection API.
IReflector
a spec holding a constructor, it's arguments
and information, if the constructor can instantiate
objects.
a spec holding a constructor, it's arguments
and information, if the constructor can instantiate
objects.
creates a new instance.creates a new instance.the newly created instance.
returns true if an instance can be instantiated
with the constructor, otherwise false.
returns true if an instance can be instantiated
with the constructor, otherwise false.
Reflection Field representation.
Reflection Field representation
See documentation for System.Reflection API.
IReflector
The ReflectClass returned by this method should have been
provided by the parent reflector.
The ReflectClass returned by this method should have been
provided by the parent reflector.
the ReflectClass representing the field type as provided by the parent reflector
The ReflectClass returned by this method should have been
provided by the parent reflector.
The ReflectClass returned by this method should have been
provided by the parent reflector.
the ReflectClass representing the index type as provided by the parent reflector
the value of the field at index, based on the fields obtained GenericClass.getDeclaredFields
db4o provides GenericReflector as a wrapper around specific
reflector (delegate).
db4o provides GenericReflector as a wrapper around specific
reflector (delegate). GenericReflector is set when an
ObjectContainer is opened. All subsequent reflector
calls are routed through this interface.
An instance of GenericReflector can be obtained through
Db4objects.Db4o.Ext.IExtObjectContainer.Reflector()
.
GenericReflector keeps list of known classes in memory.
When the GenericReflector is called, it first checks its list of
known classes. If the class cannot be found, the task is
transferred to the delegate reflector. If the delegate fails as
well, generic objects are created, which hold simulated
"field values" in an array of objects.
Generic reflector makes possible the following usecases:
running a db4o server without deploying application classes;
running db4o on Java dialects without reflection (J2ME CLDC, MIDP);
easier access to stored objects where classes or fields are not available;
running refactorings in the reflector;
building interfaces to db4o from any programming language.
One of the live usecases is ObjectManager, which uses GenericReflector
to read C# objects from Java.
root of the reflection implementation API.
root of the reflection implementation API.
The open reflection interface is supplied to allow to implement
custom reflection functionality.
Use
Db4o.Configure().ReflectWith(IReflect reflector)
to register the use of your implementation before opening database
files.
returns an ReflectArray object.
returns an ReflectArray object.
returns an ReflectClass for a Class
returns an ReflectClass class reflector for a class name or null
if no such class is found
returns an ReflectClass for an object or null if the passed object is null.
returns an ReflectClass for an object or null if the passed object is null.
Creates an instance of GenericReflector
transaction
delegate reflector,
providing specific reflector functionality. For example
Creates a clone of provided object
object to copy
copy of the submitted objectIf there is a transaction assosiated with the current refector.If there is a transaction assosiated with the current refector.true if there is a transaction assosiated with the current refector.Associated a transaction with the current reflector.Associated a transaction with the current reflector.generic reflect array instance.Returns a ReflectClass instance for the specified class
class
a ReflectClass instance for the specified classDb4objects.Db4o.Reflect.IReflectClass
Returns a ReflectClass instance for the specified class name
class name
a ReflectClass instance for the specified class nameDb4objects.Db4o.Reflect.IReflectClass
Returns a ReflectClass instance for the specified class object
class object
a ReflectClass instance for the specified class objectDb4objects.Db4o.Reflect.IReflectClass
Returns delegate reflectordelegate reflectorDetermines if a candidate ReflectClass is a collection
candidate ReflectClass
true if a candidate ReflectClass is a collection.Register a class as a collection
class to be registered
Register a predicate as a collection
predicate to be registered
Register a class
class
Returns an array of classes known to the reflectoran array of classes known to the reflectorRegisters primitive class
class id
class name
class converter
method stub: generic reflector does not have a parentPredicate representation.Predicate representation.Db4objects.Db4o.Query.PredicateIReflectorMatch method definition.
Match method definition. Used to select correct
results from an object set.
item to be matched to the criteria
true, if the requirements are metReflection Method representation.
Reflection Method representation
See documentation for System.Reflection API.
IReflector
Renaming actions are stored to the database file to make
sure that they are only performed once.
Renaming actions are stored to the database file to make
sure that they are only performed once.
RollbackStrategy to deactivate all activated objects on rollback.RollbackStrategy to deactivate all activated objects on rollback.TransparentPersistenceSupportInterface defining rollback behavior when Transparent Persistence mode is on.
Interface defining rollback behavior when Transparent Persistence mode is on.
TransparentPersistenceSupportMethod to be called per TP-enabled object when the transaction is rolled back.
Method to be called per TP-enabled object when the transaction is rolled back.
current ObjectContainer
TP-enabled object
deactivates each object.deactivates each object.
Marker interface to declare a class already implements the required TA/TP hooks
and does not want to be instrumented further.
Marker interface to declare a class already implements the required TA/TP hooks
and does not want to be instrumented further.
An
Db4objects.Db4o.Activation.IActivator
implementation that activates an object on a specific
transaction.
Configuration item that enables Transparent Activation Mode for this
session.
Configuration item that enables Transparent Activation Mode for this
session. TA mode should be switched on explicitly for manual TA implementation:
commonConfiguration.Add(new TransparentActivationSupport());
Configures the just opened ObjectContainer by setting event listeners,
which will be triggered when activation or de-activation is required.
Configures the just opened ObjectContainer by setting event listeners,
which will be triggered when activation or de-activation is required.
the ObjectContainer to configure
TransparentPersistenceSupport.Apply(Db4objects.Db4o.Internal.IInternalObjectContainer)
Enables Transparent Persistence and Transparent Activation behaviours for
the current session.
Enables Transparent Persistence and Transparent Activation behaviours for
the current session.
commonConfiguration.Add(new TransparentPersistenceSupport());
Db4objects.Db4o.TA.TransparentActivationSupport
Creates a new instance of TransparentPersistenceSupport class
RollbackStrategy interface implementation, which
defines the actions to be taken on the object when the transaction is rolled back.
Creates a new instance of TransparentPersistenceSupport class
with no rollback strategies defined.
Creates a new instance of TransparentPersistenceSupport class
with no rollback strategies defined.
Configures current ObjectContainer to support Transparent Activation and Transparent Persistence
TypeHandler for Collections.
TypeHandler for Collections.
On the .NET side, usage is restricted to instances of IList.
gets called when an object is to be written to the database.
gets called when an object is to be written to the database.
The method must only write data necessary to re instantiate the object, usually
the immutable bits of information held by the object. For value
types that means their complete state.
Mutable state (only allowed in reference types) must be handled
during
IReferenceTypeHandler.Activate(Db4objects.Db4o.Marshall.IReferenceActivationContext)
the object
Predicate to be able to select if a specific TypeHandler is
applicable for a specific Type.
Predicate to be able to select if a specific TypeHandler is
applicable for a specific Type.
return true if a TypeHandler is to be used for a specific
Type
the Type passed by db4o that is to
be tested by this predicate.
true if the TypeHandler is to be used for a specific
Type.
Typehandler that ignores all fields on a classTypehandler for classes that implement IDictionary.Typehandler for classes that implement IDictionary.allows installing a Typehandler for a single class.allows installing a Typehandler for a single class.
StoredClass instance to be checked
true, if the given StoredClass instance should be accepted, false otherwise.
prints Diagnostic messsages to the Console.
prints Diagnostic messsages to System.Diagnostics.Trace.
Install this
Db4objects.Db4o.Diagnostic.IDiagnosticListener
with: commonConfig.Diagnostic.AddListener(new DiagnosticToTrace()); Db4objects.Db4o.Diagnostic.DiagnosticConfiguration
redirects Diagnostic messages to System.Diagnostics.Traceredirects Diagnostic messages to the Console.
List based objectSet implementation
List based objectSet implementation
Reflection implementation for Class to map to .NET reflection.Reflection implementation for Class to map to .NET reflection.Reflection implementation for Constructor to map to .NET reflection.
Marks a field or event as transient.
Transient fields are not stored by db4o.
If you don't want a field to be stored by db4o,
simply mark it with this attribute.
DB4O type handler for efficiently storing and activating System.Guid values.
Judah HimangoConstructs objects by using System.Runtime.Serialization.FormatterServices.GetUninitializedObject
and bypasses calls to user contructors this way. Not available on CompactFramework
translator for types that are marked with the Serializable attribute.
The Serializable translator is provided to allow persisting objects that
do not supply a convenient constructor. The use of this translator is
recommended only if:
- the persistent type will never be refactored
- querying for type members is not necessary
db4o-8.0.184.15484+dfsg/doc/tutorial/index.html 0000644 0001750 0001750 00000000757 11520622074 021264 0 ustar directhex directhex
db4o-8.0.184.15484+dfsg/doc/tutorial/docs/ 0000755 0001750 0001750 00000000000 11520622074 020206 5 ustar directhex directhex db4o-8.0.184.15484+dfsg/doc/tutorial/docs/0Welcome.html 0000644 0001750 0001750 00000010521 11520622074 022546 0 ustar directhex directhex
db4o tutorial
Welcome
db4o is the native Java, .NET and Mono open source object database.
This tutorial was written to get you started with db4o as quickly as possible. Before you start, please make sure that you have downloaded the latest db4o distribution from the db4objects website.
Join the db4o Community
Join the db4o community for help, tips and tricks.
Ask for help in the db4o forums at any time.
And take a look at additional resources on the community website.
If you want to stay informed, subscribe to our db4o blogs
The db4o .NET distribution comes as one MSI installer file, db4o-8.0-net.msi. After you run the installer, you get the following directory structure:
Please take a look at all the supplied documentation formats to choose the one that works best for you: db4o-8.0/doc/api/db4o.chm
The API documentation for db4o is supplied as a compiled Help file. While you read through the rest of this tutorial, it may be helpful to look into the API documentation occasionally.
db4o-8.0/doc/reference/index.html
The reference documentation is a complete compilation for experienced db4o users.
db4o-8.0/doc/tutorial/Db4objects.Db4o.Tutorial.exe
This is the interactive tutorial application for .NET. Examples can be run "live" against a db4o database from within the application.
db4o-8.0/doc/tutorial/db4o-8.0-tutorial.pdf
The PDF version of the tutorial allows best fulltext search capabilities.
db4o allows to index fields to provide maximum querying performance. To request an index to be created, you would issue the following API method call in your global db4o configuration method before you open an IObjectContainer/IObjectServer:
If the configuration is set in this way, an index on the Foo#bar field will be created (if not present already) the next time you open an
IObjectContainer/IObjectServer and you use the Foo class the first time
in your application.
Contrary to all other configuration calls indexes - once created - will remain in a database even if the index configuration call is not issued before opening an IObjectContainer/IObjectServer.
To drop an index you would also issue a configuration call in your db4o configuration method:
Actually dropping the index will take place the next time the respective class is used.
db4o will tell you when it creates and drops indexes, if you choose a message level of 1 or higher:
ICommonConfiguration#MessageLevel(1);
For creating and dropping indexes on large amounts of objects there are two possible strategies:
(1) Import all objects with indexing off, configure the index and reopen the ObjectContainer/ObjectServer.
(2) Import all objects with indexing turned on and commit regularly for a fixed amount of objects (~10,000).
(1) will be faster.
(2) will keep memory consumption lower.
db4o-8.0.184.15484+dfsg/doc/tutorial/docs/OMN_Setup.jpg 0000644 0001750 0001750 00000076747 11520622074 022546 0 ustar directhex directhex JFIF ` ` C
$.' ",# (7),01444 '9=82<.342 C
2! !22222222222222222222222222222222222222222222222222 "
} !1AQa"q2#BR$3br
%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz
w !1AQaq"2B #3Rbr
$4%&'()*56789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz ? ~ %4 u9 =dYP#nP$9hψ ^[xfLCrb"nǜ*,!t zlwvnvHqV_C[~lmed9XԓIVn d
*T
i;wѿ3
J/}WOm.[ eW
4+؏ι_Y^ kC |Dd-5z^{$ʀ`
[J<;x['ӭoZ\\\I"L]( R>eMɦծb~ dg }"G +߃t\ kKy.[ o~c co5mlk&r7
8=3^oJ)}Jg%ԓ~)i6'v'we~lvJFyp|?gId$z
J(B//= 8?1 {':'?pT{? ^} 9?1 w':'?)}Jg%ןs ?NO ?NO R*= ^ާs ?NO :?O&JQGԨ{ 1}b 6 i5 kԨ{ 1}b4 iG3 DD?df 2 i1 MqG{ 1}f & {~C / MqBQ:= _ZGk w蟐 i- MqtG{ 2~W >?! W''?E(t{? [ >?! S''?}Ngw Q''?_I3 D D G \R /V# ?OO4g
MrTdv~ O Ё# ? h k
>G _u_xg M/$> D GW*)b O$ D R AtOr>G 7 3 B |Z'?¹Nt{? ong- KOsTd߂ #߆C?59ZL&v# 5
u/d j_ #'?c?"hs(./ O~ _?"h/D?
:b 7?|3 B. ~Tמ 4#EX=k C3Ҍ[I )%/:_' :=:&D9,@
I<ߥWue kcM'tG_ :cjsqX Υڞ+*Oh 3i$~t _-Y/s
J7 DQ\8ROZ)E ֊u&o7eMsJկ4/b/?HpQ O T1xS#owguq%1 3 )$bۂc] "W;5:j7ugQ^!|Gj59ʊ-w8 =$N7[jt|cڽrpj/_3 rčRTIOL bxKDZ2M~˷Qy9;>>دaqN!+*q9 o5K1My> KO
mI5)MG-q
# Z( Zq ?uEg25D0s=k8|=GS hqV!mN?W' rT?]/+ 9?* *^+# 'E Suj $ <|W # ~ {T V'# ?yXW ?U8x'_ U?5aQ?ai _# O S d@?jt Z1? X*oGx S
_OoP?Njb_؏cϦx_ $ [ Qo .O^/@@S Yq? KG AK' O k@X( )$ $ ]<(x# O '^郎#vyQb?2wc># d/!^"$ k|~T?w
uZ!-[[hy>--Ďe#˪^~n+˨HiGJ P Y>$YAUL~58
n|ԺY=N/-
P' 8 ?CUfenc=3wt~K"me keME6,MɳBIO\gr 3_;?I *kqm>O="Yt vj: 5{t;G)X1*}=+%[e)"'8M yZ9WUf=>uIvJڳ ؞ U$qF"EY׳sQ^3QVH?JTf "W׃ s]
|A-!%H[J62w sa_#fo!>Й D{ qQ[AkX\I v~iAi c@UX{r3TYol"\Ya`8AqZzh9*Lm0 >RKip2r A .;˟70m26d{[B?!(72z҆OvnZ4ɽ q &- 7g٘>7e'hVMEu$7 *2;hW]xki4R(+FHsܤ!C` ?k{ h&v#tyǦv6H_G F;e5iTl.2z| R58mƧ qVX |6
p֏ uj@fsҔm'Zv n6Jp ֠G#ڏ |O!!Vʚ3>,M#580@y5:IhgpdK! ?s֮|J7o#R h ..-b% Z߰mtwa i6e
be
rGr}k\7τ/ cN3&.5Jμ s5ЗKa)M' x j)Z'QYIukj r"rY#L.m2Bq
KO;ְ[J<0 G cvȹ)}
kBWzTk>b6Ɍ |y+KU \v 9f־ Krx4)dEtՕ Cqb/fK`IEezr^@>h;pr;zME$6$0G*Ԧ26$
}T7-C( p~nztN YEhE?.p EQ?JTf "W Q\aEb-d^][' k|2;u\7 XlfӴ_( -Ҥ2fL .QE]usH]ѺTd E:uYEV1HbY #-n #w^F/j7m}kQI2^,St~VQm*\@9>n;Sxw} #ƛ ʻuu\8# 給I<3m4z+<תc9_1rف8 ̆Q{,
1 k
q$ps7[ FmEsK;SAAr: :`[M[SHcR[bZS) 'FI]ήkS.nIL<cue8X!!A,GsW75ߙ$Irm@ i) I\{Q:RnjQ\5 -{ç[k<: _ qj%5:m]_"Jm7;r@ F>bUcb#
W|(mnKD
F*UQ!JžׯZ'[Ųwc<ăbnhso݀N@S7s\{mkclr/U;~R
E
m~ 4W/
I6Kpۜ9NsޘPIjZ6kM%*Ī`uaxYa 1ޤWЫޢ!~cq?+㺍 "
jok.쮂S)'Jxhi-V23~/vB$<~\Ao#Q- )(XtnOx/cRdm̠vm!W' e5 Ya lqfh(Y' OԷV8Y yFcm> {Z({Orb;; S%^*Ο%> \mU澉dsoiãuf ֪@GEQQ,t\| BbTb ?{z $WFex'?0TyKMKk z "5 Et-@ <:.4q q֮| & ꟇJFVRM{/_ _7 Npo"o.ϒ D]:=; {/_ _7 Ng,| & =/M Өò !g % >e >K t(po"o.ϒ D]:=; {/_ _7 Ng,| & =/M Өò !g % >e >K t(po"o.ϒ D]:=; {/_ _7 Ng,| & =/M Өò !g % >e >K t(po"o.Yϒ D]:=; k/_ 5/M Өò !g 1 tM g,? &g |_ ə (ò !v[ϱ 6 Ϲ %{8v ! o
R/ ? QO=a߹
S zާ (`m
Q} QKǰXO&9 |M c 3 tQGd+o?? Gm >3? E{8vAd ] ]'i >3? KE Y ZϧL ZϧL GdByV 3 tyV 3 tQU ] U ]-{8vAd'i >3? Gi >3? KE Y ZϧL ZϧL GdByV 3 tyV 3 tQ`
bp d|oC EX%xkp #WJFV~9z-(gחEf1C qfiմ(?4U$(279Jt+tI%q,SDd<ܻj:bj+oO29!+v# #De`m5X.ash N%~ouG9.PhÌYW?[
VsZe_ۈ!uppQtƧӮA'J3iW}ά,5pQSvV_Aa{%O-,lP_q;ܐ9*# /-TE=sԌ1>Txn9B;i_[t1Mٸ v #8,?oern. &d/$P2( `tXxS̪ǽ7-dwیټH .,xٰUc'%zzcVSB/D BC2#v Vm&f6 3M ԵEԬ-n$* H(g ZMRۑDs
۲O8RkZM 4X4xcJoS[A9Qcڡ
KaO,I$s p ѱv.
Ķ> Bpm.lRpnӥS|Q5Աi7i<drl,OqpdWw/y\zlE㚭ee~Iqq >hHd*R1#`0IC@eE B;bA":)` ٌ N&Q𦧩RKh z96:G(Y[|U%Y N QE G*J1jiM>sW"ijP/
R}tdQ / #uaqԀ`tWW/5Ou ĶЈ˙ J nݷvߗ7bbf}F-1h` 1~
}<88+z6݃u+6 Tc@/ "Cʒ̬=P۽ aiH(T`>bTz',m_ɎT%;n 1⭝&ݴFҝh 1o'#`[ı}!O|ĆY\G\
9$*O\YՍ-n C!RHdxᨅM.{249dҠ]@A^vw}]}ui!A ,T@`2ylm8W,GӃ
[oť#$ӫZ0Vrv(Ȑ3oLNo&EYX`@h4$Y2-wn<./Nьs}t1DI"F(r
34(F.n3FWd @ sKP%_Y-&rAe901 V:#pؤ]\[N
;@$w+n 85-2eO0X
N/tmBR5́
> My w1ƙsƄRj}ۀą;݃x,"2Bmn짟Ok$Y60@8r0H]I,Q,֣,H$gX7B8C S m jѻo\ʲ
0F:v{Ce~"lHU~bmP Z< ]$1\ldܕ o_ܡR c讠aQGI.bLdoj3RP9%) o$4Y]EHd|i.QXx(%!f@|e~F G j晢\$yFy$TS#$" T o\mlX%-s H_ǷnwsfYpM A<V46ex2UF }/khc/.7mp%grT NT~\y~B۪,hmAPrrqh`Sƞ?&y,Pd"\H
3׃ڞl[\c-F*>ŀ<0^Im<8|Q$ylmPmH%TOZd e]OQ{XxPr6I&P ~R ( ( ( ( 1? AQ b(%xkp #WJFV~9z-(QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE q' "5 O Ex{D
. jQ^ \?ү/V%QEu>.ehݞ7^GC]+e T 3T/~ hZZx\̊I$ VL
1H: VV8 t e]ܲHc߀(R
V U x±//ik2ͣXy*S>yd N)^>;ۉ5lKi6p1nj|eOguqJYew9E2jЉdWz ^GSi';A^whČHU5'+ M +=UGWFMƥ3 rQW S ext} Exs +_x;k7{Acg%ꣵ{+e -|0Z) r*[2w2vz1QGk >3? Gk >3? @yv 3 tyv 3 t QGk >3? Gk >3? @yv 3 tyv 3 t QGk >3? Gk >3? @yv 3 tyv 3 t QGk >3? Gk >3? @yv 3 tyv 3 t QGk >3? Gk >3? @yv 3 tyv 3 t QGk >3? Gk >3? @D ql fvǘϙc h(?[ QF ! ?:/ȕ^> +_ ZUĶ
(Dmk WSs wA`u BpY^f۠cwdݞ x >= /:0Oۏ w'&.
pۣNO w+'WFslEݣď!`Jd T:K` QVzg_RŨu$v$(剙\ [< huR4r]S( dcx*[Į20XsbsfԜmkE?qkNccsdt| n̫1uP8 ($^ zW%Qd>Pչ
3zu`u)4:$R(dt mVRʀ ' s RH Q f-[Շ,~ꖶ:]{ MdrOwr-q4e\ a7RF@#w &ӭ!䱾v(!-懜É18
FA A ' P5lV>^W?|% A o s?}F K&i5 Ë8Mh[)+
èP8Wח/ c{vBWv}ʹvRp" g G[ ?|% A o ~vQi$q _ h4K3L$ #y2۪Ƨ
:d}#^yៃ~ muRKmyc(w!C {w}gZ=ɍ\H#EyM8liU-7W5}/QcIk:ʪpJ"4ʆdPaA q(9♤XGhdXp}8% T
{h+5 D9 |q>^=ǭAgiZvZչ"xa] Pr9 EQ]oJ}UQAc9)=*(IKͩGialnq>p#{ Ӭ ڕnĚmms{i].yfDY 8a:ze,DDe `Q}K ^ b_ sƥ Z: 3 w68=*=3^XѤ8fIFڄ 1iZDwff4C<'D&,'!y+ MkiwK;%ĎrU`9?_ˬh-{ ٭!Ϙ[t?*'8wCP2ǝy{wc,t a#q [gWG]e /#nݛ=sݻbb8`~O3u\
{+,NIsf<5GFiʉ 6(|& zt 'M}nݿ;gϽ.Ĵ]-ZL4Ba($ Pt棟7Zlhd˘ب@0ÀIa{Zu-.%`IFmwd$yGt)E1y{Ug&cWv` fע) QE QE QE E R ף ب/ FE QE q' "5 O Ex{D
. jQ^ \?ү/V%QE?#k_ ʽFg2@7|:=0F8_.z?Wm1ݻ Ga v qI{zdm cz#to%aRc9;9M3cӚ ӤҼ}IuBD\^2b|*zu> N4ٵ[TwFw-lykl林croD6 j:0[ Ҕ17n1'wkE 6c &6Z= [=0钤{b A9aSfG}~w 6я. *Wb
cyqјxy#ʅsmŹ GQxMR+YfQ `+`x CFѐU#bgCM*Fv ' sܒ M|#OBXae2]%:'aXIHϭ7WĒjX^ nkxeE?#eBh-Ϧ kdFco9vD N5rZզK{elĖI{r9K\JVU K^óI - ,t `vq1$5FEҵ {2܃[D FGĠA\J#y8nbXt4j&wVk{aMp+X~hn1z[ A4a8P* vן ymuq OKo
íMy&-̄6 ?0ǭ /e )9" lTQ}K ^ b<۫ǪI25A/ل@bv-Ӷ*Մ
l8go>9wP=ܖz|zqfӸ7r WxqQMcg<ܡDIr NWwE nGM .CV\7@q6F$MV{4wȐ;P8Ҋ;[hxJB+yZXejDZ7$?" 9ji[lhh '/1z%EgϧO4{ʌHyJn G6}k zL(EPEPEPEPEP}K ^ b_ QE ( 1? APE5 `G%xkp #WJ XEVc9 ȍף *Q
+",Fٱu~^? c#oxDmk WvKûl$c=26౽˺Si7W
1 Tp:r3ԬsCZX-oTExɜ}11 |?@MêaT Uh|WhzE,ZRGbAXXX X-v - * ? \I7moO$Mwafg«FNF06S x4= և)5-F"Iexـ~6" |j obtuI^ͪ\$2R3h3c]g / 4z dU|ֹfqI=kӪ퍦hְ][Itl zss1툱hI<eB96kM&ͬڊ^ B@t銡T* vo[ _Kc%? `Yw42G'4$Ca`Ny%#>^OI_b5x$uD[Y 3>E ivQ X ʣp8usvi5Ca [ena,<# ƽVyoy{Y\[`kuw([Cn+^.ڞ۱:}#J$6 #sO{_Eom.+yh(3 +VCk>'U=Œ[\%)t2-p7?7'c]kHzuXcQ@p!rv|ƽZ:[p_ sXj3^Zmf%
Qv#sràdTԬty4s[
Rk]Dd;qz =A V0ƑDET tӳ 5kkb}z[xn mmkߏ& 1nd!d wn=lu B)>8kVh^ o0 .ÕEl IϡBv=UKQ.P[uߗw;$ -=oJ
,7XZE|UUmKM{y[)%@?t
Y+=O>Cy}A4 1>`7O "&@ Ų[/:n k%XJHn
fd) 3עB
?Gy?`5-Exa2ҽ̮:Ldyp;w;,s?J:XOWs/ FEԿ 6* ( ( ( ( ( ( ( ( ( ( ( " lTQ}K ^ b
(8oC E' " = "W5z{D
. jiW㗫(g?^^A^@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@`xԭ/@ Կ 6*(> G ѱPuψ4[;!\ (22>Rs#QKi
̢ ݾ]۱sPV
Ŕ\)bgUik-j*HIO UK]Jx-Ghk7< X^Pk7>?1bqp3Y ,r>SN
FS#9|R+JNFA W+Ye'Famt3|7͕*Xc9 4[
cv.ˉ҆\ÎNH&@;+χ/.LblV0K}Aݜ օwMa'k<20L#s 'JvnQRu
F`S w1rT$ ȪڤMYuY&U
$ !'H ;ז8Ui8
}pqq.pySwyS`wlo?[`ԡ CQX*uv|\ g.8 r(`;z`y*q\u s'ljnħPZYF8ڂ7m##jEm|!U]upT`,)0x:59eAJ6Jg988 Q:]qyY۔ 0uM@9} fᮭwǷseIȒn˒vr'7&H ^IFVlk#(Ü kzqI
pXT`P= *:
2AI";Inbo m'=RΡ-[_lv^$
*w
9=R[]=MRVhGI_ɗ `B
oOfY&fp"fnР8V8 *t1YN [MpAgy{ިO#iHnb!# &rF}.-ܴoH y7MO$+xu{{KA lŁ I\|dvkJ +_ ZUĶ
(Dmk WאxDmk WEPEPEPEPEPEPEPEPEPEPEPEPEPX /e +~92sAK ? o % esPA / ( @ $ l _ W?E t H? \AK ? o % esPA / ( @ $ l _ W?E t H? \AK ? o % esPA / ( @ $ lZٙ!+ iȉf_)_-z{}M*W IҀ;XM ^)E JB :>V
>u4qj)i O9sӶ> Vׯ/ C_M,6JAERو3* :PԿ 6*(> G ѱPEPEPEPEPEPEPEPEPEPEPEP}K ^ b_ QE ( 1? APE5 `G%xkp #WJ XEVc*jdΙsK$V(c S?皨 dgo VwkI.W)`
H`z]sy͜(ޡ"_YIo wfAb`.38$$se ſ [P?" C &E MlQ@ / # - ?_ ݬGp #
*xKxϑo l$D9s OF {mׄI-Q_H#? n(qΤeȒUacv,9?nvN(Z P1].i1̻0Hc `㳓8ciVyVɩt qBS&8pOR@!*}lqe50P( H'jms%
[].͉jr$0|ޘ普wkqzCc RC8 +1jhVVe f!FN?7_j`xJ7Rۛr CP/4nUPX1T[!=*߅^&k֒Zy8ʲJ h2N9G{Xj A ~J8TNB zu ӭ&+'ČZʨBWk9$})-`2TQ8<ź?'CH79+.אYWp (&D]۳ +nsy(K/^MݤELbR|^Y*K/ g@!KXe<ܶw`FpMjX}Kw}o7qU^~ρ#Wxq71=yȴ;avqMh;pqY!>ǥA9KX5э1`Qar{m|9-
\Zjij`2a6b k e%z^AխmR[[-n\m>ӗ%N ҇"};ŶWRE#̉lCƎC 8e5:$e,d;+*E x x|,Itibxf5@ߌf5'^i 罎%- Z&Dѕ1m 1S;0ekWfp-%2 @a9_Cߛ?Ÿ]ء>q'+g+F+ƾU[ټϴ;Y1F
ym/ۤ6k6$IBE,![#8
$q6$VeR+i]goINr>lrV0ӥ2NPTIF*_2zpNil:Xӭ(
30(A͞[9*ׅn_-5teH6$md"nH=Πh zY/Ry7 "(Ud U1ҳ4$}a(m/<2pv "yoSo.5;)?Ycr. IЌ>Q|%x#갵f;mI m_rh@ixMJ,rγ3HJ>=2>oNլUڼFFA 3@Q@Q@Q@Q@Q@Q@]v!
"
HUbz ( vG% ?¹S "3k
rd$e}FEaxu%
a$x W,pNNz;_l߄
>/` 疞 xe~cWH>" _0ao9fֵuI}F<;cUYY
eRF@$@wl߄
>/` RxTux-1mJx`Ky%ct [!gnڽb]ɝ-·>ݫӜ^zsNk}_ ~(d݃'U.๖(_s0F ֧6yqyxH_Ԍq D1p xIkf ?*&( 1? AQ b(%xkp #WJFV~9z-(QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE QE x+XkjLPFAp{dV ]k @s S 4]k @s S 5Q@ %ֿ ?U? G%ֿ ?U? ] ]k @s S 4]k @s S 5Q@ %ֿ ?U? G%ֿ ?U? ]L+kwMms\j&X
º*(?[ QF ! ?:/ȕ^x`W|c:\8gVg ?pZUĶ,QUg ?pG +1( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ?b?
>g ?p@( o ? )5Wզe
A6(A
R tsy ?s Y> +_ ZUĶ,}~ z+1>y ?s G?jc?4}~ ՈR ,#muP } o ?4o ѾxO @?h}
4o >y ?s F?? M 4 }~ ѾxO F?? M o ?5jiv>pI
WLE >y ?s U o ?5^ >y ?s U o ?5^ >y ?s U o ?5^ >y ?s D)Uz>ҍ? >y ?s G?hg <' } & 7 hg <' ?4}~ ?7 h }
o } &i
qϪjqY4YcW8UIv> '?h}
cX A ? %P?h}
cX A ? %P?h}
cX A ? %P?h}
cX A ? %P?h}
q^0յ
nUMJdUob-2z ]m X}
o nE4S3V$J Pzm}~ ѾxO F?? M o ?4o ѾxO @?h}
4o >y ?s F?? M 4 }~ 6y#Fē۰ S@ bKy'h[ Q@ JFU ȕ^*rb[QY( *>o zRæLȑ1`p_}~ 9jvC"DGl ;ȡdrh$(no tTYSmK:tΌ\>KiBCHt?:v \%ӬI`!l)`A-(y#ҦC7cXpX sV5NVlJ;bpp8l AU Q?
@c3x_ y+oWM*X Z( ( ( ( ( ( (>o zRæLȑ1`pKbSVU$ ga'}Oݏ jU U{ҮYy`mI {#=@ 5-VV^s
ۘPiw0}pz?c[a% 6dl)b1s,4;us8i
:HI0V =i^ Qgسǻf6#-d19.NZK8 h٣w- E dV3XI}"xjm䔪d)g%~ꑌc V^Y"* HQ`OIɧZ?0# o WQ?
mg 뇻`]yd2 `Ic r})Q\ '> soX @MkQje#x6F;m⋛NK[m&W4G3,ʥ#o+b*FCq
^#EݽΫZo@P^0zcj3O M6*!,0N`94k(]v۸mϛi >p ۻGARdݧ/ R;q띧8r9c,THXY1a#k `9Ux2- R,ۃc~9RoJ!
3JRGl/W? υ=c E [?P?ů'/Wq^c/ [
Vs$l#@X8 U \ ӵ hIq0,8|@
jk--(4č ʩwT FF@ݜgX} Es6ym%ֲ*twR w=߇i5 5)$eHbP[",s9QSKs;h>eF7:#8=jF7Rn $mNc"\fjHt{h~Tn ܹcWn} \kq|r=J`eM?k IuS[żq"a {ՙtggɒ1z2p@U 99-)VXȊʯ=1RF]?4/?@{U Q?
x a 爙H*uRA +_ ZUĶ
(QE U;'M<
>ϴBm3~Ur O/_ Q _ҿ
?( ?
пG"~ J ( ¶( D7 B Q o+
آ1 WG'+b ͵cr6>o:gl"2`"
(
(
(
(
(
():n hi~^v}nqd go+
آ1 WG'+b O/_ Q _ҿ
?( ?
пG"~ J ( ¶( D7 B Q o+
آ1 WG'+b O/_ Q _ҿ
?( ?
пG"~ J ( ¶( D7 B Q o+
آ1 WGE VT.&i=2IdbifbrI$rMj@ o+
? WGE c '( O/_ V _ҿ
??
п[P?"~ J ( D7 B Q lQ@-2
LAƥp^Vh8oC E' " ɱ F ^%*j(*rb[QY( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( db4o-8.0.184.15484+dfsg/doc/tutorial/docs/docs.css 0000644 0001750 0001750 00000003071 11520622074 021651 0 ustar directhex directhex body, p, td
{
font-family: Arial, Helvetica, Verdana;
font-size: 10pt;
color: #666666;
}
H1
{
font-family: "Segoe UI","Lucida Grande",Arial,Helvetica,Sans-Serif;
color: #BB0000;
font-size: 180%;
font-weight: normal;
}
H2
{
font-family: "Segoe UI","Lucida Grande",Arial,Helvetica,Sans-Serif;
color: #BB0000;
font-size: 160%;
font-weight: normal;
border-bottom: double #CCC 3px;
}
H3
{
font-family: "Segoe UI","Lucida Grande",Arial,Helvetica,Sans-Serif;
color: #BB0000;
font-size: 140%;
font-weight: normal;
border-bottom: solid #CCC 1px;
}
H4
{
font-family: "Segoe UI","Lucida Grande",Arial,Helvetica,Sans-Serif;
color: #BB0000;
font-size: 130%;
font-weight: normal;
}
H5
{
font-family: "Segoe UI","Lucida Grande",Arial,Helvetica,Sans-Serif;
color: #BB0000;
font-size: 120%;
font-weight: normal;
}
H6
{
font-family: "Segoe UI","Lucida Grande",Arial,Helvetica,Sans-Serif;
color: #BB0000;
font-size: 100%;
font-weight: normal;
}
small
{
margin-top: 2em;
padding: 0.5em;
font-size: 90%;
color: #CCCCCC;
}
code
{
font-size: 100%;
color: black;
background-color: #F4F4F4;
}
a, a:link, a:active {
color:#698DB6;
font-weight:normal;
text-decoration:none;
}
a:visited{
color: #394DB6;
text-decoration:none;
}
.lg{background-color:#F4F4F4}
.co{background-color:#a0a0a0}
.console {
z-index:1;
float:none;
width:100%;
position:fixed;
height:150px;
bottom:0px;
left:0px;
overflow: hidden;
}
.button {
background-color: #BB0000;
color: #FFFFFF;
}
#footer {
border: 1px solid #F6F6F6;
background-color: 1px solid #F6F6F6;
padding: 2px;
} db4o-8.0.184.15484+dfsg/doc/tutorial/docs/Configuration.html 0000644 0001750 0001750 00000007567 11520622074 023722 0 ustar directhex directhex
14. Configuration
db4o provides a wide range of configuration methods to request special behaviour. For a complete list of all available methods see the API documentation for the Db4objects.Db4o.Config and Db4objects.Db4o.CS.Config namespaces.
A more complete description of Configuration usage and scope can also be obtained from the Reference documentation.
Some hints around using configuration calls:
14.1. Scope
Configuration should be created and passed to an opening ObjectContainer or ObjectServer:
A separate configuration instance should be created for each new IObjectContainer ObjectServer It is recommended to use a factory method with all the necessary settings.
14.2. Calling Methods
Configurations that influence the database file format will have to take place, before a database is created, before the first #OpenXXX() call. Some examples:
Configuration settings are not stored in db4o database files. Accordingly the same configuration has to be submitted every time an IObjectContainer ObjectServer is opened.
Our setup code has not changed at all, just the internal workings of a snapshot.
// storeFirstCar
Car car1 = new Car("Ferrari");
Pilot pilot1 = new Pilot("Michael Schumacher", 100);
car1.Pilot = pilot1;
db.Store(car1);
// storeSecondCar
Pilot pilot2 = new Pilot("Rubens Barrichello", 99);
Car car2 = new Car("BMW");
car2.Pilot = pilot2;
car2.Snapshot();
car2.Snapshot();
db.Store(car2);
7.2. Retrieving
db4o will provide us with all objects of the given type. To collect all instances of a given class, no matter whether they are subclass members or direct instances, we just provide a corresponding prototype.
// retrieveTemperatureReadoutsQBE
SensorReadout proto = new TemperatureSensorReadout(DateTime.MinValue, null, null, 0.0);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
// retrieveAllSensorReadoutsQBE
SensorReadout proto = new SensorReadout(DateTime.MinValue, null, null);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
This is one more situation where QBE might not be applicable: What if the given type is an interface or an abstract class? Well, there's a little trick to keep in mind: Type objects receive special handling with QBE.
// retrieveAllSensorReadoutsQBEAlternative
IObjectSet result = db.QueryByExample(typeof(SensorReadout));
ListResult(result);
is just the same for all objects, no matter where they are situated in the inheritance tree.
Just like we retrieved all objects from the database above, we can delete all stored objects to prepare for the next chapter.
// deleteAll
IObjectSet result = db.QueryByExample(typeof(Object));
foreach (object item in result)
{
db.Delete(item);
}
7.4. Conclusion
Now we have covered all basic OO features and the way they are handled by db4o. We will complete the first part of our db4o walkthrough in the next chapter by looking at deep object graphs, including recursive structures.
7.5. Full source
using System;
using System.IO;
using Db4objects.Db4o;
using Db4objects.Db4o.Query;
namespace Db4odoc.Tutorial.F1.Chapter5
{
public class InheritanceExample : Util
{
readonly static string YapFileName = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"formula1.yap");
public static void StoreFirstCar(IObjectContainer db)
{
Car car1 = new Car("Ferrari");
Pilot pilot1 = new Pilot("Michael Schumacher", 100);
car1.Pilot = pilot1;
db.Store(car1);
}
public static void StoreSecondCar(IObjectContainer db)
{
Pilot pilot2 = new Pilot("Rubens Barrichello", 99);
Car car2 = new Car("BMW");
car2.Pilot = pilot2;
car2.Snapshot();
car2.Snapshot();
db.Store(car2);
}
public static void RetrieveAllSensorReadoutsQBE(IObjectContainer db)
{
SensorReadout proto = new SensorReadout(DateTime.MinValue, null, null);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
}
public static void RetrieveTemperatureReadoutsQBE(IObjectContainer db)
{
SensorReadout proto = new TemperatureSensorReadout(DateTime.MinValue, null, null, 0.0);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
}
public static void RetrieveAllSensorReadoutsQBEAlternative(IObjectContainer db)
{
IObjectSet result = db.QueryByExample(typeof(SensorReadout));
ListResult(result);
}
public static void RetrieveAllSensorReadoutsQuery(IObjectContainer db)
{
IQuery query = db.Query();
query.Constrain(typeof(SensorReadout));
IObjectSet result = query.Execute();
ListResult(result);
}
public static void RetrieveAllObjects(IObjectContainer db)
{
IObjectSet result = db.QueryByExample(new object());
ListResult(result);
}
}
}
Now that we have seen how transactions work in db4o conceptually, we are prepared to tackle concurrently executing transactions.
We start by preparing our database in the familiar way.
// setFirstCar
Pilot pilot = new Pilot("Rubens Barrichello", 99);
Car car = new Car("BMW");
car.Pilot = pilot;
db.Store(car);
// setSecondCar
Pilot pilot = new Pilot("Michael Schumacher", 100);
Car car = new Car("Ferrari");
car.Pilot = pilot;
db.Store(car);
12.1. Embedded server
From the API side, there's no real difference between transactions executing concurrently within the same runtime and transactions executed against a remote server. To use concurrent transactions within a single runtime , we just open a db4o server on our database file, directing it to run on port 0, thereby declaring that no networking will take place.
// accessLocalServer
using(IObjectServer server = Db4oClientServer.OpenServer(YapFileName, 0))
{
using(IObjectContainer client = server.OpenClient())
{
// Do something with this client, or open more clients
}
}
Again, we will delegate opening and closing the server to our environment to focus on client interactions.
The transaction level in db4o is read committed . However, each client container maintains its own weak reference cache of already known objects. To make all changes committed by other clients immediately, we have to explicitly refresh known objects from the server. We will delegate this task to a specialized version of our #ListResult() method.
public static void ListRefreshedResult(IObjectContainer container, IObjectSet items, int depth)
{
Console.WriteLine(items.Count);
foreach (object item in items)
{
container.Ext().Refresh(item, depth);
Console.WriteLine(item);
}
}
// demonstrateLocalReadCommitted
using(IObjectContainer client1 =server.OpenClient(),
client2 =server.OpenClient())
{
Pilot pilot = new Pilot("David Coulthard", 98);
IObjectSet result = client1.QueryByExample(new Car("BMW"));
Car car = (Car)result.Next();
car.Pilot = pilot;
client1.Store(car);
ListResult(client1.QueryByExample(new Car(null)));
ListResult(client2.QueryByExample(new Car(null)));
client1.Commit();
ListResult(client1.QueryByExample(typeof(Car)));
ListRefreshedResult(client2, client2.QueryByExample(typeof(Car)), 2);
}
Simple rollbacks just work as you might expect now.
// demonstrateLocalRollback
using (IObjectContainer client1 = server.OpenClient(),
client2 = server.OpenClient())
{
IObjectSet result = client1.QueryByExample(new Car("BMW"));
Car car = (Car) result.Next();
car.Pilot = new Pilot("Someone else", 0);
client1.Store(car);
ListResult(client1.QueryByExample(new Car(null)));
ListResult(client2.QueryByExample(new Car(null)));
client1.Rollback();
client1.Ext().Refresh(car, 2);
ListResult(client1.QueryByExample(new Car(null)));
ListResult(client2.QueryByExample(new Car(null)));
}
12.2. Networking
From here it's only a small step towards operating db4o over a TCP/IP network. We just specify a port number greater than zero and set up one or more accounts for our client(s).
// accessRemoteServer
using(IObjectServer server = Db4oClientServer.OpenServer(YapFileName, ServerPort))
{
server.GrantAccess(ServerUser, ServerPassword);
using(IObjectContainer client = Db4oClientServer.OpenClient("localhost", ServerPort, ServerUser, ServerPassword))
{
// Do something with this client, or open more clients
}
}
The client connects providing host, port, user name and password.
Sometimes a client needs to send a special message to a server in order to tell the server to do something. The server may need to be signalled to perform a defragment or it may need to be signalled to shut itself down gracefully.
This is configured bysetting MessageRecipient parameter to the object that will process client-initiated messages.
public void RunServer()
{
lock(this)
{
IServerConfiguration config = Db4oClientServer.NewServerConfiguration();
// Using the messaging functionality to redirect all
// messages to this.processMessage
config.Networking.MessageRecipient = this;
IObjectServer db4oServer = Db4oClientServer.OpenServer(config, FILE, PORT);
db4oServer.GrantAccess(USER, PASS);
try
{
if (! stop)
{
// wait forever until Close will change stop variable
Monitor.Wait(this);
}
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
db4oServer.Close();
}
}
The message is received and processed by a #ProcessMessage() method:
public void ProcessMessage(IMessageContext con, object message)
{
if (message is StopServer)
{
Close();
}
}
Db4o allows a client to send an arbitrary signal or message to a server by sending a plain object to the server. The server will receive a callback message, including the object that came from the client. The server can interpret this message however it wants.
public static void Main(string[] args)
{
IObjectContainer IObjectContainer = null;
try
{
// connect to the server
IObjectContainer = Db4oClientServer.OpenClient(Db4oClientServer.NewClientConfiguration(),
HOST, PORT, USER, PASS);
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
if (IObjectContainer != null)
{
// get the messageSender for the IObjectContainer
IMessageSender messageSender = IObjectContainer.Ext()
.Configure().ClientServer().GetMessageSender();
// send an instance of a StopServer object
messageSender.Send(new StopServer());
// close the IObjectContainer
IObjectContainer.Close();
}
}
12.4. Putting it all together: a simple but complete db4o server
Let's put all of this information together now to implement a simple standalone db4o server with a special client that can tell the server to shut itself down gracefully on demand.
First, both the client and the server need some shared configuration information. We will provide this using an interface:
namespace Db4odoc.Tutorial.F1.Chapter6
{
/// <summary>
/// Configuration used for StartServer and StopServer.
/// </summary>
public class ServerInfo
{
/// <summary>
/// the host to be used.
/// If you want to run the client server examples on two computers,
/// enter the computer name of the one that you want to use as server.
/// </summary>
public const string HOST = "localhost";
/// <summary>
/// the database file to be used by the server.
/// </summary>
public const string FILE = "formula1.yap";
/// <summary>
/// the port to be used by the server.
/// </summary>
public const int PORT = 4488;
/// <summary>
/// the user name for access control.
/// </summary>
public const string USER = "db4o";
/// <summary>
/// the pasword for access control.
/// </summary>
public const string PASS = "db4o";
}
}
Now we'll create the server:
using System;
using System.Threading;
using Db4objects.Db4o;
using Db4objects.Db4o.CS;
using Db4objects.Db4o.CS.Config;
using Db4objects.Db4o.Messaging;
namespace Db4odoc.Tutorial.F1.Chapter6
{
/// <summary>
/// starts a db4o server with the settings from ServerInfo.
/// This is a typical setup for a long running server.
/// The Server may be stopped from a remote location by running
/// StopServer. The StartServer instance is used as a MessageRecipient
/// and reacts to receiving an instance of a StopServer object.
/// Note that all user classes need to be present on the server side
/// and that all possible Db4oFactory.Configure() calls to alter the db4o
/// configuration need to be executed on the client and on the server.
/// </summary>
public class StartServer : ServerInfo, IMessageRecipient
{
/// <summary>
/// setting the value to true denotes that the server should be closed
/// </summary>
private bool stop = false;
/// <summary>
/// starts a db4o server using the configuration from
/// ServerInfo.
/// </summary>
public static void Main(string[] arguments)
{
new StartServer().RunServer();
}
/// <summary>
/// opens the IObjectServer, and waits forever until Close() is called
/// or a StopServer message is being received.
/// </summary>
public void RunServer()
{
lock(this)
{
IServerConfiguration config = Db4oClientServer.NewServerConfiguration();
// Using the messaging functionality to redirect all
// messages to this.processMessage
config.Networking.MessageRecipient = this;
IObjectServer db4oServer = Db4oClientServer.OpenServer(config, FILE, PORT);
db4oServer.GrantAccess(USER, PASS);
try
{
if (! stop)
{
// wait forever until Close will change stop variable
Monitor.Wait(this);
}
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
db4oServer.Close();
}
}
/// <summary>
/// messaging callback
/// see com.db4o.messaging.MessageRecipient#ProcessMessage()
/// </summary>
public void ProcessMessage(IMessageContext con, object message)
{
if (message is StopServer)
{
Close();
}
}
/// <summary>
/// closes this server.
/// </summary>
public void Close()
{
lock(this)
{
stop = true;
Monitor.PulseAll(this);
}
}
}
}
And last but not least, the client that stops the server.
using System;
using Db4objects.Db4o;
using Db4objects.Db4o.CS;
using Db4objects.Db4o.Messaging;
namespace Db4odoc.Tutorial.F1.Chapter6
{
/// <summary>
/// stops the db4o Server started with StartServer.
/// This is done by opening a client connection
/// to the server and by sending a StopServer object as
/// a message. StartServer will react in it's
/// processMessage method.
/// </summary>
public class StopServer : ServerInfo
{
/// <summary>
/// stops a db4o Server started with StartServer.
/// </summary>
/// <exception cref="Exception" />
public static void Main(string[] args)
{
IObjectContainer IObjectContainer = null;
try
{
// connect to the server
IObjectContainer = Db4oClientServer.OpenClient(Db4oClientServer.NewClientConfiguration(),
HOST, PORT, USER, PASS);
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
if (IObjectContainer != null)
{
// get the messageSender for the IObjectContainer
IMessageSender messageSender = IObjectContainer.Ext()
.Configure().ClientServer().GetMessageSender();
// send an instance of a StopServer object
messageSender.Send(new StopServer());
// close the IObjectContainer
IObjectContainer.Close();
}
}
}
}
12.5. Conclusion
That's it, folks. No, of course it isn't. There's much more to db4o we haven't covered yet: schema evolution, custom persistence for your classes, writing your own query objects, etc. A much more thorough documentation is provided in the reference that you should have also received with the download or online.
We hope that this tutorial has helped to get you started with db4o. How should you continue now?
- You could browse the remaining chapters. They are a selection of themes from the reference that very frequently come up as questions in our http://developer.db4o.com/Forums.aspx.
-(Interactive version only)While this tutorial is basically sequential in nature, try to switch back and forth between the chapters and execute the sample snippets in arbitrary order. You will be working with the same database throughout; sometimes you may just get stuck or even induce exceptions, but you can always reset the database via the console window.
- The examples we've worked through are included in your db4o distribution in full source code. Feel free to experiment with it.
public static void SetFirstCar(IObjectContainer db)
{
Pilot pilot = new Pilot("Rubens Barrichello", 99);
Car car = new Car("BMW");
car.Pilot = pilot;
db.Store(car);
}
public static void SetSecondCar(IObjectContainer db)
{
Pilot pilot = new Pilot("Michael Schumacher", 100);
Car car = new Car("Ferrari");
car.Pilot = pilot;
db.Store(car);
}
public static void AccessLocalServer()
{
using(IObjectServer server = Db4oClientServer.OpenServer(YapFileName, 0))
{
using(IObjectContainer client = server.OpenClient())
{
// Do something with this client, or open more clients
}
}
}
public static void DemonstrateLocalReadCommitted(IObjectServer server)
{
using(IObjectContainer client1 =server.OpenClient(),
client2 =server.OpenClient())
{
Pilot pilot = new Pilot("David Coulthard", 98);
IObjectSet result = client1.QueryByExample(new Car("BMW"));
Car car = (Car)result.Next();
car.Pilot = pilot;
client1.Store(car);
ListResult(client1.QueryByExample(new Car(null)));
ListResult(client2.QueryByExample(new Car(null)));
client1.Commit();
ListResult(client1.QueryByExample(typeof(Car)));
ListRefreshedResult(client2, client2.QueryByExample(typeof(Car)), 2);
}
}
public static void DemonstrateLocalRollback(IObjectServer server)
{
using (IObjectContainer client1 = server.OpenClient(),
client2 = server.OpenClient())
{
IObjectSet result = client1.QueryByExample(new Car("BMW"));
Car car = (Car) result.Next();
car.Pilot = new Pilot("Someone else", 0);
client1.Store(car);
ListResult(client1.QueryByExample(new Car(null)));
ListResult(client2.QueryByExample(new Car(null)));
client1.Rollback();
client1.Ext().Refresh(car, 2);
ListResult(client1.QueryByExample(new Car(null)));
ListResult(client2.QueryByExample(new Car(null)));
}
}
public static void AccessRemoteServer()
{
using(IObjectServer server = Db4oClientServer.OpenServer(YapFileName, ServerPort))
{
server.GrantAccess(ServerUser, ServerPassword);
using(IObjectContainer client = Db4oClientServer.OpenClient("localhost", ServerPort, ServerUser, ServerPassword))
{
// Do something with this client, or open more clients
}
}
}
db4o supplies three querying systems, Query-By-Example (QBE) Native Queries (NQ), and the SODA API. In the previous chapter, you were briefly introduced to Query By Example(QBE).
Query-By-Example (QBE) is appropriate as a quick start for users who are still acclimating to storing and retrieving objects with db4o.
LINQ is the recommended db4o querying interface for .NET platforms.
SODA is the underlying internal API. It is provided for backward compatibility and it can be useful for dynamic generation of queries, where LINQ and NQ are too strongly typed.
4.1. Query by Example (QBE)
When using Query By Example (QBE) you provide db4o with a template object. db4o will return all of the objects which match all non-default field values. This is done via reflecting all of the fields and building a query expression where all non-default-value fields are combined with AND expressions. Here's an example from the previous chapter:
// retrievePilotByName
Pilot proto = new Pilot("Michael Schumacher", 0);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
Querying this way has some obvious limitations:
- db4o must reflect all members of your example object.
- You cannot perform advanced query expressions. (AND, OR, NOT, etc.)
- You cannot constrain on values like 0 (integers), "" (empty strings), or nulls (reference types) because they would be interpreted as unconstrained.
- You need to be able to create objects without initialized fields. That means you can not initialize fields where they are declared. You can not enforce contracts that objects of a class are only allowed in a well-defined initialized state.
- You need a constructor to create objects without initialized fields.
To get around all of these constraints, db4o provides the Native Query (NQ) system.
4.2. Native Queries
Wouldn't it be nice to pose queries in the programming language that you are using? Wouldn't it be nice if all your query code was 100% typesafe, 100% compile-time checked and 100% refactorable? Wouldn't it be nice if the full power of object-orientation could be used by calling methods from within queries? Enter Native Queries.
Native queries are the main db4o query interface and they are the recommended way to query databases from your application. Because native queries simply use the semantics of your programming language, they are perfectly standardized and a safe choice for the future.
Native Queries are available for all platforms supported by db4o.
4.2.1. Concept
The concept of native queries is taken from the following two papers:
Native Queries provide the ability to run one or more lines of code against all instances of a class. Native query expressions should return true to mark specific instances as part of the result set. db4o will attempt to optimize native query expressions and run them against indexes and without instantiating actual objects, where this is possible.
4.2.3. Simple Example
Let's look at how a simple native query will look like in some of the programming languages and dialects that db4o supports:
List <Pilot> pilots = db.query(new Predicate<Pilot>() {
public boolean match(Pilot pilot) {
return pilot.getPoints() == 100;
}
});
Java JDK 1.2 to 1.4
List pilots = db.query(new Predicate() {
public boolean match(Pilot pilot) {
return pilot.getPoints() == 100;
}
});
Java JDK 1.1
ObjectSet pilots = db.query(new PilotHundredPoints());
public static class PilotHundredPoints extends Predicate {
public boolean match(Pilot pilot) {
return pilot.getPoints() == 100;
}
}
C# .NET (not using generics)
IList pilots = db.Query(new PilotHundredPoints());
public class PilotHundredPoints : Predicate {
public boolean Match(Pilot pilot) {
return pilot.Points == 100;
}
}
VB .NET (not using generics)
Dim pilots As IList = db.Query(new PilotHundredPoints())
Public Class PilotHundredPoints
Inherits Predicate
Public Function Match (pilot As Pilot) as Boolean
If pilot.Points = 100 Then
Return True
Else
Return False
End Function
End Class
A side note on the above syntax:
For all dialects without support for generics, Native Queries work by convention. A class that extends the com.db4o.Predicate class is expected to have a boolean #Match() method with one parameter to describe the class extent:
bool Match(Pilot candidate);
When using native queries, don't forget that modern integrated development environments (IDEs) can do all the typing work around the native query expression for you, if you use templates and auto-completion.
The following example shows how to create an autocompletion code snippet in Visual Studio 2005.
Create a "nq.snippet" file in any text editor.
Paste the following code:
Save the file.
In the Visual Studio 2005 open Tools/Code SnippetsManager
Select language "Visual c#" if not yet selected. Press "Import..." button and select the newly created file. Select "Visual c#" as the location and press "Finish" button.
Now you can use the snippet by selecting it from "Edit/InstelliSense/Insert Snippet..." menu.
4.2.4. Advanced Example
For complex queries, the native syntax is very precise and quick to write. Let's compare to a SODA query that finds all pilots with a given name or a score within a given range:
Here is how the same query will look like with native query syntax, fully accessible to autocompletion, refactoring and other IDE features, fully checked at compile time:
List <Pilot> result = db.query(new Predicate<Pilot>() {
public boolean match(Pilot pilot) {
return pilot.getPoints() > 99
&& pilot.getPoints() < 199
|| pilot.getName().equals("Rubens Barrichello");
}
});
4.2.5. Arbitrary Code
Basically that's all there is to know about native queries to be able to use them efficiently. In principle you can run arbitrary code as native queries, you just have to be very careful with side effects - especially those that might affect persistent objects.
Let's run an example that involves some more of the language features available.
using Db4objects.Db4o.Query;
namespace Db4odoc.Tutorial.F1.Chapter1
{
public class ArbitraryQuery : Predicate
{
private int[] _points;
public ArbitraryQuery(int[] points)
{
_points=points;
}
public bool Match(Pilot pilot)
{
foreach (int points in _points)
{
if (pilot.Points == points)
{
return true;
}
}
return pilot.Name.StartsWith("Rubens");
}
}
}
4.2.6. Native Query Performance
One drawback of native queries has to be pointed out: Under the hood db4o tries to analyze native queries to convert them to SODA. This is not possible for all queries. For some queries it is very difficult to analyze the flowgraph. In this case db4o will have to instantiate some of the persistent objects to actually run the native query code. db4o will try to analyze parts of native query expressions to keep object instantiation to the minimum.
The development of the native query optimization processor will be an ongoing process in a close dialog with the db4o community. Feel free to contribute your results and your needs by providing feedback to our db4o forums(Forums are accessible through free db4o membership ).
With the current implementation, all above examples will run optimized, except for the "Arbitrary Code" example - we are working on it.
4.2.7. Full source
using System;
using System.IO;
using Db4objects.Db4o;
using Db4objects.Db4o.Query;
using Db4odoc.Tutorial;
namespace Db4odoc.Tutorial.F1.Chapter1
{
public class NQExample : Util
{
readonly static string YapFileName = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"formula1.yap");
public static void Main(string[] args)
{
using(IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))
{
StorePilots(db);
RetrieveComplexSODA(db);
RetrieveComplexNQ(db);
RetrieveArbitraryCodeNQ(db);
ClearDatabase(db);
}
}
public static void RetrieveComplexSODA(IObjectContainer db)
{
IQuery query=db.Query();
query.Constrain(typeof(Pilot));
IQuery pointQuery=query.Descend("_points");
query.Descend("_name").Constrain("Rubens Barrichello")
.Or(pointQuery.Constrain(99).Greater()
.And(pointQuery.Constrain(199).Smaller()));
IObjectSet result=query.Execute();
ListResult(result);
}
public static void RetrieveComplexNQ(IObjectContainer db)
{
IObjectSet result = db.Query(new ComplexQuery());
ListResult(result);
}
public static void RetrieveArbitraryCodeNQ(IObjectContainer db)
{
IObjectSet result = db.Query(new ArbitraryQuery(new int[]{1,100}));
ListResult(result);
}
public static void ClearDatabase(IObjectContainer db)
{
IObjectSet result = db.QueryByExample(typeof(Pilot));
while (result.HasNext())
{
db.Delete(result.Next());
}
}
}
}
using Db4objects.Db4o.Query;
namespace Db4odoc.Tutorial.F1.Chapter1
{
public class ComplexQuery : Predicate
{
public bool Match(Pilot pilot)
{
return pilot.Points > 99
&& pilot.Points < 199
|| pilot.Name=="Rubens Barrichello";
}
}
}
using Db4objects.Db4o.Query;
namespace Db4odoc.Tutorial.F1.Chapter1
{
public class ArbitraryQuery : Predicate
{
private int[] _points;
public ArbitraryQuery(int[] points)
{
_points=points;
}
public bool Match(Pilot pilot)
{
foreach (int points in _points)
{
if (pilot.Points == points)
{
return true;
}
}
return pilot.Name.StartsWith("Rubens");
}
}
}
4.3. LINQ
db4o querying syntax has got even easier with the introduction of .NET LINQ queries. LINQ allows you to write compile checked db4o queries, which can be refactored automatically when a field name changes and which are supported by code auto-completion tools.
In order to use LINQ you will need to add reference to Db4objects.Db4o.Linq.dll and usage to your program class:
using System.Linq;
using Db4objects.Db4o.Linq;
If you are already familiar with LINQ syntax, you can just start writing LINQ to query db4o. Otherwise you may want to familiarise yourself with LINQ resources on http://msdn2.microsoft.com/en-us/library/bb397926.aspx MSDN.
Note that LINQ requires at least .NET 3.5.
4.3.1. Linq Examples
Let's prepare some objects in our database to query against:
// storeObjects
db.Store(new Car("Ferrari", (new Pilot("Michael Schumacher", 100))));
db.Store(new Car("BMW", (new Pilot("Rubens Barrichello", 99))));
The simplest LINQ query will look like this:
// retrievePilot
IEnumerable<Pilot> result = from Pilot p in db
where p.Name.StartsWith("Michael")
select p;
ListResult(result);
You can see that we are using db4o object container as a datasource, the rest of the syntax is generic to all LINQ queries.
Now let's try a bit more complex selection:
// retrievePilotByCar
IEnumerable<Pilot> result = from Car c in db
where c.Model.StartsWith("F")
&& (c.Pilot.Points > 99 && c.Pilot.Points <150)
select c.Pilot;
ListResult(result);
So we can constrain on one object and retrieve a list of others. You can even create completely new objects based on the retrieved information using select new MyObject(field1, field2...). Try to experiment with different LINQ queries against db4o database.
4.3.2. Performance
db4o query processor is based on SODA queries, therefore LINQ query is analysed and converted to SODA syntax in the runtime. However, in some cases this conversion is not possible. This can happen when query is constrained against aggregates or projections of a field value and in other cases when SODA equivalent does not exists. For example:
// retrievePilotUnoptimized
IEnumerable<Pilot> result = from Pilot p in db
where (p.Points - 81) == p.Name.Length
select p;
ListResult(result);
The query still works, but it requires instantiation of all candidate objects, which is much less performant than SODA query.
4.3.3. LINQ for Compact Framework
Compact Framework version 3.5 contains LINQ implementation for querying objects, however it does not contain the namespace System.Linq.Expressions, which is used by all optimized LINQ providers. Luckily there is a solution to this problem. Mono implementation of System.Core can be used to support optimized LINQ providers and expression interpreter contributed by Mainsoft to Mono's System.Core can be used to support full LINQ expression trees.
These assemblies were used by db4o team to compile a new assembly, System.Linq.Expressions.dll, which provides LINQ support to .NET Compact Framework 3.5. In order to use the full LINQ functionality including optimisation, add a reference to System.Linq.Expressions.dll in your project and enjoy.
System.Linq.Expressions.dll can be found in bin\compact-3.5 folder of your distribution. You can also examine the code in src\Libs\compact-3.5\System.Linq.Expressions or db4o SVN .
4.4. SODA Query API
The SODA query API is db4o's low level querying API, allowing direct access to nodes of query graphs. Since SODA uses strings to identify fields, it is neither perfectly typesafe nor compile-time checked and it also is quite verbose to write.
For most applications LINQ andNative Queries will be the better querying interface.
However there can be applications where dynamic generation of queries is required, that's why SODA is explained here.
4.4.1. Simple queries
Let's see how our familiar QBE queries are expressed with SODA. A new Query object is created through the #Query() method of the ObjectContainer and we can add Constraint instances to it. To find all Pilot instances, we constrain the query with the Pilot class object.
Basically, we are exchanging our 'real' prototype for a meta description of the objects we'd like to hunt down: a query graph made up of query nodes and constraints. A query node is a placeholder for a candidate object, a constraint decides whether to add or exclude candidates from the result.
Our first simple graph looks like this.
We're just asking any candidate object (here: any object in the database) to be of type Pilot to aggregate our result.
To retrieve a pilot by name, we have to further constrain the candidate pilots by descending to their name field and constraining this with the respective candidate String.
What does #Descend mean here? Well, just as we did in our 'real' prototypes, we can attach constraints to child members of our candidates.
So a candidate needs to be of type Pilot and have a member named'_name' that is equal to the given String to be accepted for the result.
Note that the class constraint is not required: If we left it out, we would query for all objects that contain a'_name' member with the given value. In most cases this will not be the desired behavior, though.
Now there are occasions when we don't want to query for exact field values, but rather for value ranges, objects not containing given member values, etc. This functionality is provided by the Constraint API.
First, let's negate a query to find all pilots who are not Michael Schumacher:
The query API also allows to query for field default values.
// retrieveByDefaultFieldValue
Pilot somebody = new Pilot("Somebody else", 0);
db.Store(somebody);
IQuery query = db.Query();
query.Constrain(typeof(Pilot));
query.Descend("_points").Constrain(0);
IObjectSet result = query.Execute();
ListResult(result);
db.Delete(somebody);
It is also possible to have db4o sort the results.
// retrieveSorted
IQuery query = db.Query();
query.Constrain(typeof(Pilot));
query.Descend("_name").OrderAscending();
IObjectSet result = query.Execute();
ListResult(result);
query.Descend("_name").OrderDescending();
result = query.Execute();
ListResult(result);
All these techniques can be combined arbitrarily, of course. Please try it out. There still may be cases left where the predefined query API constraints may not be sufficient - don't worry, you can always let db4o run any arbitrary code that you provide in an Evaluation. Evaluations will be discussed in a later chapter.
To prepare for the next chapter, let's clear the database.
// clearDatabase
IObjectSet result = db.QueryByExample(typeof(Pilot));
foreach (object item in result)
{
db.Delete(item);
}
4.4.3. Conclusion
Now you have been provided with the following alternative approaches to query db4o databases: Query-By-Example,.? net LINQ, Native Queries, SODA.
Which one is the best to use? Some hints:
- LINQ is a standard typesafe queries for .NET languages and is recommended for use with .NET version of db4o.
- Native queries are targeted to be the primary interface for db4o, so they should be preferred.
- With the current state of the db4o query optimizer there may be queries that will execute faster in SODA style, so it can be used to tune applications. SODA can also be more convenient for constructing dynamic queries at runtime.
- Query-By-Example is nice for simple one-liners, but restricted in functionality. If you like this approach, use it as long as it suits your application's needs.
Of course you can mix these strategies as needed.
We have finished our walkthrough and seen the various ways db4o provides to pose queries. But our domain model is not complex at all, consisting of one class only. Let's have a look at the way db4o handles object associations in the next chapter .
4.4.4. Full source
using System;
using System.IO;
using Db4objects.Db4o;
using Db4objects.Db4o.Query;
using Db4odoc.Tutorial;
namespace Db4odoc.Tutorial.F1.Chapter1
{
public class QueryExample : Util
{
readonly static string YapFileName = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"formula1.yap");
public static void Main(string[] args)
{
using(IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))
{
StoreFirstPilot(db);
StoreSecondPilot(db);
RetrieveAllPilots(db);
RetrievePilotByName(db);
RetrievePilotByExactPoints(db);
RetrieveByNegation(db);
RetrieveByConjunction(db);
RetrieveByDisjunction(db);
RetrieveByComparison(db);
RetrieveByDefaultFieldValue(db);
RetrieveSorted(db);
ClearDatabase(db);
}
}
public static void StoreFirstPilot(IObjectContainer db)
{
Pilot pilot1 = new Pilot("Michael Schumacher", 100);
db.Store(pilot1);
Console.WriteLine("Stored {0}", pilot1);
}
public static void StoreSecondPilot(IObjectContainer db)
{
Pilot pilot2 = new Pilot("Rubens Barrichello", 99);
db.Store(pilot2);
Console.WriteLine("Stored {0}", pilot2);
}
public static void RetrieveAllPilots(IObjectContainer db)
{
IQuery query = db.Query();
query.Constrain(typeof(Pilot));
IObjectSet result = query.Execute();
ListResult(result);
}
public static void RetrievePilotByName(IObjectContainer db)
{
IQuery query = db.Query();
query.Constrain(typeof(Pilot));
query.Descend("_name").Constrain("Michael Schumacher");
IObjectSet result = query.Execute();
ListResult(result);
}
public static void RetrievePilotByExactPoints(IObjectContainer db)
{
IQuery query = db.Query();
query.Constrain(typeof(Pilot));
query.Descend("_points").Constrain(100);
IObjectSet result = query.Execute();
ListResult(result);
}
public static void RetrieveByNegation(IObjectContainer db)
{
IQuery query = db.Query();
query.Constrain(typeof(Pilot));
query.Descend("_name").Constrain("Michael Schumacher").Not();
IObjectSet result = query.Execute();
ListResult(result);
}
Probably you have already wondered how db4o handles concurrent access to a single database. Just as any other DBMS, db4o provides a transaction mechanism. Before we take a look at multiple, perhaps even remote, clients accessing a db4o instance in parallel, we will introduce db4o transaction concepts in isolation.
9.1. Commit and rollback
You may not have noticed it, but we have already been working with transactions from the first chapter on. By definition, you are always working inside a transaction when interacting with db4o. A transaction is implicitly started when you open a container, and the current transaction is implicitly committed when you close it again. So the following code snippet to store a car is semantically identical to the ones we have seen before; it just makes the commit explicit.
// storeCarCommit
Pilot pilot = new Pilot("Rubens Barrichello", 99);
Car car = new Car("BMW");
car.Pilot = pilot;
db.Store(car);
db.Commit();
// listAllCars
IObjectSet result = db.QueryByExample(typeof(Car));
ListResult(result);
However, we can also rollback the current transaction, resetting the state of our database to the last commit point.
// storeCarRollback
Pilot pilot = new Pilot("Michael Schumacher", 100);
Car car = new Car("Ferrari");
car.Pilot = pilot;
db.Store(car);
db.Rollback();
// listAllCars
IObjectSet result = db.QueryByExample(typeof(Car));
ListResult(result);
9.2. Refresh live objects
There's one problem, though: We can roll back our database, but this cannot automagically trigger a rollback for our live objects.
// carSnapshotRollback
IObjectSet result = db.QueryByExample(new Car("BMW"));
Car car = (Car)result.Next();
car.Snapshot();
db.Store(car);
db.Rollback();
Console.WriteLine(car);
We will have to explicitly refresh our live objects when we suspect they may have participated in a rollback transaction.
What is this #Ext() construct good for? Well, it provides some functionality that is in itself stable, but the API may still be subject to change. As soon as we are confident that no more changes will occur, #Ext() functionality will be transferred to the common IObjectContainer API.
Finally, we clean up again.
// deleteAll
IObjectSet result = db.QueryByExample(typeof(Object));
foreach (object item in result)
{
db.Delete(item);
}
9.3. Conclusion
We have seen how transactions work for a single client. In the Client/Server chapter we will see how the transaction concept extends to multiple clients, whether they are located within the same runtime or on a remote machine.
Let't first revisit Activation again in the next chapter and take a look at how db4o can take care of our Object lifecycle automatically.
9.4. Full source
using System;
using System.IO;
using Db4objects.Db4o;
namespace Db4odoc.Tutorial.F1.Chapter6
{
public class TransactionExample : Util
{
readonly static string YapFileName = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"formula1.yap");
public static void Main(string[] args)
{
File.Delete(YapFileName);
using (IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))
{
StoreCarCommit(db);
}
using (IObjectContainer db = Db4oEmbedded.OpenFile( YapFileName))
{
ListAllCars(db);
StoreCarRollback(db);
}
using (IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))
{
ListAllCars(db);
CarSnapshotRollback(db);
CarSnapshotRollbackRefresh(db);
}
}
public static void StoreCarCommit(IObjectContainer db)
{
Pilot pilot = new Pilot("Rubens Barrichello", 99);
Car car = new Car("BMW");
car.Pilot = pilot;
db.Store(car);
db.Commit();
}
public static void ListAllCars(IObjectContainer db)
{
IObjectSet result = db.QueryByExample(typeof(Car));
ListResult(result);
}
public static void StoreCarRollback(IObjectContainer db)
{
Pilot pilot = new Pilot("Michael Schumacher", 100);
Car car = new Car("Ferrari");
car.Pilot = pilot;
db.Store(car);
db.Rollback();
}
public static void CarSnapshotRollback(IObjectContainer db)
{
IObjectSet result = db.QueryByExample(new Car("BMW"));
Car car = (Car)result.Next();
car.Snapshot();
db.Store(car);
db.Rollback();
Console.WriteLine(car);
}
public static void CarSnapshotRollbackRefresh(IObjectContainer db)
{
IObjectSet result=db.QueryByExample(new Car("BMW"));
Car car=(Car)result.Next();
car.Snapshot();
db.Store(car);
db.Rollback();
db.Ext().Refresh(car, int.MaxValue);
Console.WriteLine(car);
}
}
}
Let's get started as simple as possible. We are going to demonstrate how to store, retrieve, update and delete instances of a single class that only contains primitive and String members. In our example this will be a Formula One (F1) pilot whose attributes are his name and the F1 points he has already gained this season.
First we create a class to hold our data. It looks like this:
namespace Db4odoc.Tutorial.F1.Chapter1
{
public class Pilot
{
string _name;
int _points;
public Pilot(string name, int points)
{
_name = name;
_points = points;
}
public string Name
{
get
{
return _name;
}
}
public int Points
{
get
{
return _points;
}
}
public void AddPoints(int points)
{
_points += points;
}
Notice that this class does not contain any db4o-related code.
2.1. Opening the database
To access a db4o database file or create a new one, call DB4OEMBEDDED.OPENFILE() and provide Db4oEmbedded.newConfiguration() as a configuration template and the path to your database file as the second parameter, to obtain an IObjectContainer instance. IObjectContainer represents "The Database", and will be your primary interface to db4o. Closing the IObjectContainer with the #Close() method will close the database file and release all resources associated with it.
// accessDb4o
using(IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))
{
// do something with db4o
}
Db4oFileName is just a string value representing any filename. If the file with this name already exists, it will be opened as db4o database, otherwise a new db4o database will be created.
For the following examples we will assume that our environment takes care of opening and closing the IObjectContainer automagically, and stores the reference in a variable named 'db'.
2.2. Storing objects
To store an object, we simply call #Store() on our database, passing any object as a parameter.
// storeFirstPilot
Pilot pilot1 = new Pilot("Michael Schumacher", 100);
db.Store(pilot1);
Console.WriteLine("Stored {0}", pilot1);
We'll need a second pilot, too.
// storeSecondPilot
Pilot pilot2 = new Pilot("Rubens Barrichello", 99);
db.Store(pilot2);
Console.WriteLine("Stored {0}", pilot2);
2.3. Retrieving objects
The easiest way to see the content of our database is to use Object Manager Enterprise, which will be introduced in the next chapter . For now let's continue with the API overview and learn how to build db4o queries.
db4o supplies several different querying systems, Query by Example (QBE), LINQ, Native Queries (NQ) and the SODA Query API (SODA). In this first example we will introduce QBE. Once you are familiar with storing objects, we encourage you to use LINQ .
When using Query-By-Example, you create a prototypical object for db4o to use as an example of what you wish to retrieve. db4o will retrieve all objects of the given type that contain the same (non-default) field values as the example. The results will be returned as an IObjectSet instance. We will use a convenience method #ListResult() to display the contents of our result IObjectSet :
public static void ListResult(IObjectSet result)
{
Console.WriteLine(result.Count);
foreach (object item in result)
{
Console.WriteLine(item);
}
}
To retrieve all pilots from our database, we provide an 'empty' prototype:
// retrieveAllPilotQBE
Pilot proto = new Pilot(null, 0);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
Note that we specify 0 points, but our results were not constrained to only those Pilots with 0 points; 0 is the default value for int fields.
db4o also supplies a shortcut to retrieve all instances of a class:
// retrieveAllPilots
IObjectSet result = db.QueryByExample(typeof(Pilot));
ListResult(result);
For .NET there also is a generics shortcut, using the query method:
IList <Pilot> pilots = db.Query<Pilot>(typeof(Pilot));
To query for a pilot by name:
// retrievePilotByName
Pilot proto = new Pilot("Michael Schumacher", 0);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
And to query for Pilots with a specific number of points:
// retrievePilotByExactPoints
Pilot proto = new Pilot(null, 100);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
Of course there's much more to db4o queries. They will be covered in more depth in later chapters.
2.4. Updating objects
Updating objects is just as easy as storing them. In fact, you use the same #Store() method to update your objects: just call #Store() again after modifying any object.
// updatePilot
IObjectSet result = db.QueryByExample(new Pilot("Michael Schumacher", 0));
Pilot found = (Pilot)result.Next();
found.AddPoints(11);
db.Store(found);
Console.WriteLine("Added 11 points for {0}", found);
RetrieveAllPilots(db);
Notice that we query for the object first. This is an importaint point. When you call #Store() to modify a stored object, if the object is not 'known' (having been previously stored or retrieved during the current session), db4o will insert a new object. db4o does this because it does not automatically match up objects to be stored, with objects previously stored. It assumes you are inserting a second object which happens to have the same field values.
To make sure you've updated the pilot, please return to any of the retrieval examples above and run them again.
2.5. Deleting objects
Objects are removed from the database using the #Delete() method.
// deleteFirstPilotByName
IObjectSet result = db.QueryByExample(new Pilot("Michael Schumacher", 0));
Pilot found = (Pilot)result.Next();
db.Delete(found);
Console.WriteLine("Deleted {0}", found);
RetrieveAllPilots(db);
Let's delete the other one, too.
// deleteSecondPilotByName
IObjectSet result = db.QueryByExample(new Pilot("Rubens Barrichello", 0));
Pilot found = (Pilot)result.Next();
db.Delete(found);
Console.WriteLine("Deleted {0}", found);
RetrieveAllPilots(db);
Please check the deletion with the retrieval examples above.
As with updating objects, the object to be deleted has to be 'known' to db4o. It is not sufficient to provide a prototype object with the same field values.
2.6. Conclusion
That was easy, wasn't it? We have stored, retrieved, updated and deleted objects with a few lines of code. Now you are probably interested to see how the database looks like. Let's have a look using db4o graphical tool - Object Manager in the next chapter .
2.7. Full source
using System;
using System.IO;
using Db4objects.Db4o;
using Db4objects.Db4o.Query;
using Db4odoc.Tutorial;
namespace Db4odoc.Tutorial.F1.Chapter1
{
public class FirstStepsExample : Util
{
readonly static string YapFileName = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"formula1.yap");
public static void Main(string[] args)
{
File.Delete(YapFileName);
AccessDb4o();
File.Delete(YapFileName);
using(IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))
{
StoreFirstPilot(db);
StoreSecondPilot(db);
RetrieveAllPilots(db);
RetrievePilotByName(db);
RetrievePilotByExactPoints(db);
UpdatePilot(db);
DeleteFirstPilotByName(db);
DeleteSecondPilotByName(db);
}
}
public static void AccessDb4o()
{
using(IObjectContainer db = Db4oEmbedded.OpenFile(YapFileName))
{
// do something with db4o
}
}
public static void StoreFirstPilot(IObjectContainer db)
{
Pilot pilot1 = new Pilot("Michael Schumacher", 100);
db.Store(pilot1);
Console.WriteLine("Stored {0}", pilot1);
}
public static void StoreSecondPilot(IObjectContainer db)
{
Pilot pilot2 = new Pilot("Rubens Barrichello", 99);
db.Store(pilot2);
Console.WriteLine("Stored {0}", pilot2);
}
public static void RetrieveAllPilotQBE(IObjectContainer db)
{
Pilot proto = new Pilot(null, 0);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
}
public static void RetrieveAllPilots(IObjectContainer db)
{
IObjectSet result = db.QueryByExample(typeof(Pilot));
ListResult(result);
}
public static void RetrievePilotByName(IObjectContainer db)
{
Pilot proto = new Pilot("Michael Schumacher", 0);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
}
public static void RetrievePilotByExactPoints(IObjectContainer db)
{
Pilot proto = new Pilot(null, 100);
IObjectSet result = db.QueryByExample(proto);
ListResult(result);
}
public static void UpdatePilot(IObjectContainer db)
{
IObjectSet result = db.QueryByExample(new Pilot("Michael Schumacher", 0));
Pilot found = (Pilot)result.Next();
found.AddPoints(11);
db.Store(found);
Console.WriteLine("Added 11 points for {0}", found);
RetrieveAllPilots(db);
}
public static void DeleteFirstPilotByName(IObjectContainer db)
{
IObjectSet result = db.QueryByExample(new Pilot("Michael Schumacher", 0));
Pilot found = (Pilot)result.Next();
db.Delete(found);
Console.WriteLine("Deleted {0}", found);
RetrieveAllPilots(db);
}
public static void DeleteSecondPilotByName(IObjectContainer db)
{
IObjectSet result = db.QueryByExample(new Pilot("Rubens Barrichello", 0));
Pilot found = (Pilot)result.Next();
db.Delete(found);
Console.WriteLine("Deleted {0}", found);
RetrieveAllPilots(db);
}
}
}
