We are pleased to announce the first version of a new component. "DPL
Assistant" is an IDE plug-in that is intended to help developers use,
and learn to use, the Direct Persistence Layer of Oracle Berkeley DB
Java Edition. The DPL Assistant is initially provided as an Eclipse
plug-in.

This first version of the plug-in performs validation of DPL
annotations in Java source code. Each time you save changes from the
Java source code editor, the validator analyzes annotations (@Entity,
@Persistent, etc.) and reports any errors or warnings that it can
detect, in a similar way to how the IDE reports Java compilation
errors.

Of course there are many more things that the DPL Assistant could do.
We are requesting your feedback. Please see the Possible Future
Enhancements section at the end of this message and send us your
thoughts by replying to this forum thread.

Installation

You can install the DPL Assistant using the Eclipse update manager.
Start by adding our update site to your configuration:

    http://download.oracle.com/berkeley-db/eclipse/

The DPL Assistant was developed on Eclipse version 3.3, and has been
tested with both 3.3 and 3.4. It of course requires at least Java 1.5
(since it works with Java annotations).

Usage

Once installed, the DPL Assistant may be enabled on a per-Java-project
basis. From the Project Explorer, right-click on the name of a Java
project, and choose Properties from the pop-up menu. In the
Properties dialog, choose the "DPL Assistant" page, and turn on the
"Use DPL Assistant" check-box.

Now you can create a Java source file and type in some Java code,
using DPL annotations. Whenever you save your changes in the Java
source code editor, the validation tool checks the code, and adds
error/warning markers for any problems that it finds.

If you have your Eclipse workspace set up to build automatically, you
only need to save your changes. (See the Project -> Build
Automatically menu item.) Otherwise you need to do an explicit Build
to run the validator.

When the tool reports a problem, you should be able to see a marker in
the margin on the left-hand side of the editor, and if you show the
Eclipse "Problems" view you should see it there too. Also, a few --
but not all -- of the problem types also appear as squiggly underlines
in the source code.

As a simple example, if you were to type in (and Save) the following
code:

    @Entity public class A {

        String foo;

    }

you should see an error marker, complaining that "Entity class lacks a
primary key".

Known Issues

There is one significant known issue: if you have multiple Java
projects in your Eclipse workspace, with entity or persistent classes
from one project referring to classes in another project, then
sometimes DPL Assistant can get confused. In such a case, it may fail
to notice changes in one project that ought to cause a refresh of the
validation for classes in another project, resulting in the retention
of stale results from a previous validation.

If this happens, a simple workaround is to manually request a clean
build of the Java project (from the menu bar: Project -> Clean ...).

Possible Future Enhancements

At this point these are only some ideas, and do not represent any sort
of commitment or definite plan. We would especially like to get
opinions and feedback from the community. What features do you think
would be useful?

* the DPL Assistant is initially provided as an Eclipse plug-in, but
we could add support for other IDE's, such as NetBeans or
JDeveloper. Again, this depends on the level of interest from the
community. Please let us know what would be useful to you.

* instead of merely complaining about errors, in many cases it could
fix the code automatically. Sometimes there are several possible
fixes, depending on the developer's intent. These could be
presented to the user in a multiple-choice pop-up menu.

* "content assist": instead of waiting until an error has been made,
it is sometimes possible to help the user get it right the first
time. In the same way that the IDE helps in writing Java
expressions (e.g., presenting a multiple-choice list of known
methods, given an object reference of a known class), it could
present a list of valid completions during typing of annotations.

* wizards: instead of having to type entity classes by hand, a wizard
could lead you through the process of defining the desired fields,
and then generate the basic Java source code automatically.

By analyzing an application's overall schema, a wizard might also
help generate code for a test harness. Or, by comparing the current
schema to a previous schema extracted from an old database
environment, it might help generate conversion code ("mutations").

* ultimately, it would be sweet to be able to render an abstract
graphical "picture" (like a UML diagram) from an existing schema,
and even (conversely) to support interactive drawing of such a
diagram from which entity and persistent classes could then be
generated automatically.

Alan Bram
Oracle