Application Controlled Data Persistence (ACDP)
Design
Designing an ACDP database involves coding subclasses for theCustomDatabase and the CustomTable classes, and optionally for the SimpleType class and the ICipherFactory
interface.
Creation
Once an ACDP database is designed, the various database files, among them the database's layout file, can be created with the help of the Setup Tool. Alternatively, the database can be created by copying an already existing layout file and creating the other database files invoking theACDP.createDBFiles(java.nio.file.Path) method.
Instead of copying the layout file, you may want to hard-code its content and
save it to the destination directory using the Layout class.
Opening
Before an ACDP database can be used, it must be opened. Invoke theDatabase.open(java.nio.file.Path, int, boolean, acdp.design.ICipherFactory) method to open the database as a
weakly typed ACDP database.
Since an ACDP database must finally be closed, you may want to apply the try-with-resources statement like this:
try (Database db = Database.open(...)) {
Table myTable = db.getTable("My Table");
do something with myTable
}
This code snippet also shows how to get a particular table (here the "My Table")
from a weakly typed database.
Compare this code snippet to the corresponding code snippet in the CustomDatabase class description.
Settings
All settings of a WR database can be inspected programmatically and some of them can be modified programmatically with the help of theSettings class.
(WR databases are the common database type and are explained in the second
chapter of the Database interface description.)
If you just want to have a quick look at the database settings and you feel
comfortable reading a layout then open the
database's layout file in a text editor.
Compacting
Insert-, update- and delete-operations can fragment the tables' file spaces, requiring defragmentation from time to time. TheTable.compactVL() and Table.compactFL() methods
compact a table's file space.
Refactoring
Refactoring a database means changing the structure of the database, for instance, removing a table from the database or inserting a new column into a table. Refactoring is usually done at a time when the database is already filled with some data. TheRefactor class provides methods for refactoring a
database.
Integrity Check
ACDP relies on the computer's file system. If ACDP behaves strangely, a reason may be that changes were made to database files from outside of ACDP, harming the integrity of the database. TheACDP.verify(java.nio.file.Path, boolean, boolean) method checks the integrity of the database
and can restore it in some cases.
Ensuring the integrity of the database should ensure general error-free
operation of ACDP within the documented exceptional situations.
Java Version and Internal Types
ACDP requires at least version 8 of Java. With the advent of modules in Java 9 the separation between internal types (classes, interfaces, enumerations, and annotation types) and API types is no longer a subject of discussion. Anyway, don't reference a type that is a member of a package containing the literal "internal" in the package name.
A Personal Note about Exceptions
All exception types in theacdp.exceptions package extend Java's
RuntimeException.
Moreover, no method of this API throws a checked exception.
The reason for this is that, according to the author, the fact of being forced
to handle an exception makes you depressed.
(For example, confronted with an IOException, I regularly don't know
what to do other than print, log, or forward the IOException to the
caller.)
However, I appreciate it if as many exceptions as possible that a method can
throw are carefully documented.
Some say that including unchecked exceptions in the throws clause of a method is considered poor programming practice. See for example the online-article "How to Write Doc Comments for the Javadoc Tool" or Item 74 of Joshua Bloch's "Effective Java", Third Edition. However, since identifying a set of exceptions that are worth documenting can involve a greater deal of intellectual effort, it seems appropriate to me to record the result of this work in the signature of the method and not just in a more or less volatile commentary section.
Don't despair if half of a method's description makes up the description of the
exceptions the method can throw.
Just ignore the Throws section for now—I tried to put any
non-trivial information on how to use a method properly into the other sections
of the method description.
But if an exception occurs then it is a good idea to look for a description of
the exception instead of reading the source code straight away.
Type interface.