Database Explorer

ObjectDB Database Explorer is a visual GUI tool for managing ObjectDB databases. It can be used to view data in ObjectDB databases, execute JPQL and JDOQL queries and edit the content of databases.

Running the Explorer

The ObjectDB Explorer is contained in the explorer.jar executable jar file, which is located in the bin directory of ObjectDB. It depends on the objectdb.jar file.

You can run it from the command line as follows:

> java -jar explorer.jar

If explorer.jar is not in the current directory a path to it has to be specified.

Alternatively, you can run the Explorer by double clicking explorer.jar or by running explorer.exe (on Windows) or explorer.sh (on Unix/Linux, after editing the shell file, setting the paths to the objectdb.jarfile and to the JVM).

Connecting to the Database

Opening a Database Connection

To open a local database file in embedded mode use the File > Open Embedded... command and select a local database file.

To open a database in client-server mode select File > Open C/S Connection... and provide host, port, username and password for a client-server connection. You also have to specify a database path on the server, possibly using the Browse button.

Recently used databases can also be opened using the File > Recent Connections command. By default, when the Explorer starts it tries to open a connection to the most recently used database automatically.

Tabbed Windows

Three tabbed windows are displayed on the left side of the Explorer when a database is open:

• The [Database] window is split into two sub windows. The top sub window displays general information about the database and the bottom sub window displays a list of bookmarked entity objects.
• The [Schema] window shows the user defined persistable types (entity and embeddable classes) in the database and their persistent fields and indexes.
• The [Query] window enables running JPQL and JDOQL queries, as discussed below.

Closing a Database Connection

Use the File > Close menu command to close a currently open database connection.

Viewing Database Content

Viewer Windows

The Explorer provides two types of viewer windows for viewing the database data.

The Table window follows the approach of traditional visual database tools. Every row in the table represents a single object, every column represents a persistent field, and the content of a cell is the value of a single field in a single database object. This type of viewer is useful for viewing data of a simple object model.

In most cases, the Tree window, which is designed to handle more complex object models, is preferred. A Tree window displays objects as a tree. Every database object is represented by a tree node and the values of its persistent fields are represented as child nodes. Tree windows provide easier navigation. Because every reference between two database objects is represented by a parent-child relationship in the tree, you can navigate among objects by expanding nodes in the tree, similar to exploring objects in a visual debugger. Notice that the same database object may be accessed using different paths in the tree and therefore may be represented by more than one node. To help identify circles in the graph of objects, a special {R} sign (indicating recursive) is displayed for an object that is already shown in a higher level of the same tree path (i.e. the object is a descendant of itself in the tree).

To open a new viewer window either write a query in the [Query] tabbed window or select an element for viewing (an entity class in the [Schema] tabbed window, a bookmark in the [Database] tabbed window or an object in a currently open Table or Tree window). You can open a new viewer window using the Window > Open Tree Window and Window > Open Table Window commands. When the target element is an object in an open viewer window the Window > Focus Selection command switches the current viewer to focus on the selected object.

Executing Queries

The [Query] window on the left side enables execution of JPQL and JDOQL queries.

To execute a query:

• Enter a query string.
• In the [Parameters] table provide arguments for parameters (if any). An entity object can be specified by type and primary key separated by # (e.g. Point#1). A collection can be specified as a comma separated list of elements.
• Use the [First] and [Max] fields to set the result range.
• Check [Disable Cache] to bypass query program and result caches.
• Click the Execute button to run the query.

If the query is valid, a default viewer (a Tree window by default) is opened with the query results, and the size of the result collection and the query execution time are displayed on the query window. If the query compilation fails, an error is displayed in the query window and no viewer window is opened. You can also execute a query using the Window > Open Tree Window or the Window > Open Table Window commands in order to specify a preferred viewer window type for the results.

On the bottom of the query window there is a log panel that displays the selected query execution plan. This is useful, for example, for checking which indexes are used.

The Reset button clears the content of all the fields.

Refreshing the Cache

When a database is open in the Explorer in client server mode, it can be accessed simultaneously by other applications. If the database is modified by another process the viewer windows in the Explorer might display cached content that does not reflect the up to date data in the database. In this case you can refresh the cache and the viewer windows using the File > Refresh Data menu command.

Using Bookmarks

To bookmark an entity object for easier future access - first select it in a viewer window and then select the Tools > Bookmark... command, specify a bookmark name and click OK. Bookmarked entity objects can be accessed from the [Database] tabbed window.

Editing Database Content

The Explorer is used mainly as a viewer of databases but it can also function as an editor.

New Entity Objects

To construct new entity objects and store them in the database, open the [Create New Entity Objects] dialog box using the Edit > New Entity Objects... command. In the dialog box select the entity class and specify the number of objects to construct. Click the Create and Persist button to construct and store the new entity objects.

Editing Values and References

You can edit simple field values inline in the Tree and Table viewer windows. Double click the field, press F2, or simply type the new value. Use the Edit > Edit Multi Line String command to edit a multi-line string.

Reference fields can be edited using the following commands:

• The Edit > Set Reference > Set to Null command is used to set a reference to null.
• The Edit > Set Reference > Set to Existing Entity... command is used to set a reference to an existing entity object, which has to be specified by type and primary key separated by # (e.g. Point#1).
• The Edit > Set Reference > Set to New Object... command is used to set a reference to a new object (not necessarily an entity object).

Field values can also be set using standard clipboard commands (Cut, Copy and Paste). For example, an entity object can be selected and copied as a reference into the clipboard (in any viewer window) and then pasted on a reference that has to be set.

The functionality of the Edit > Delete command depends on the context. Deleting a reference field sets the value to null without deleting any referenced entity object. On the other hand, deleting an entity object that is represented by a child of an Extent node in a viewer window deletes the object itself from the database.

Editing Collections

Elements can be added to collections by using the following commands:

• The Edit > Add to Collection > Add Null command is used to add a null value.
• The Edit > Add to Collection > Add Existing Entity... command is used to add a reference to an existing entity object, which has to be specified by type and primary key separated by # (e.g. Point#1).
• The Edit > Add to Collection > Add New Object... command is used to add a reference to a new object (not necessarily an entity object).

Elements can be removed from the collection using the Edit > Delete command.

The order of elements in an ordered collection can be modified by using the Edit > Move Element commands.

Saving Changes

The Explorer manages an active transaction for every open database file. All the editing operations are associated with the active transaction. The File > Save menu command commits the transaction (applying all the changes to the database). The File > Discard Changes menu command rolls back the transaction (discarding all the changes). After File > Save and File > Discard Changes, the Explorer automatically begins a new transaction for the next editing session.

Options and Settings

The Explorer settings are organized in the [Options] dialog box, which can be opened using the Tools > Options... menu command.

The [Options] dialog box contains three tabbed pages: [General], [Fonts] and [Views].

The [General] Page

The [General] page contains the following settings:

• The [Encoding] combo box is useful when strings in the database are not encoded using Unicode. ObjectDB stores String instances in the database using the same encoding that they have in memory, which is usually Unicode. If you store in the database String instances that have a different memory representation, you have to set that encoding to manage these strings in the Explorer. This setting is relevant only in the Explorer. In your applications - retrieved String instances always have the same encoding as they had when they have been persisted.
• The [Automatically open recently used database at startup] check box specifies whether or not to open the last opened database when the Explorer starts.
• The [Table (instead of Tree) as a default viewer window] check box specifies if Table windows should be used by default rather than Tree windows.
• The [Darker colors for open branches in Tree windows] check box specifies whether or not to use different colors for open and close nodes in Tree windows.

• The [Classpath for persistent classes and metadata] field specifies a path to locate persistent classes and XML metadata. Setting this field is not mandatory because you can browse and edit ObjectDB database files when class and metadata files are not available. Some features of the Explorer, however, do require setting the classpath. For instance, executing queries that include user defined methods can be supported by the Explorer only when the code of these methods is available using the specified classpath.

The [Fonts] Page

The [Fonts] page is used to set the appearance of different Explorer components. Select one or more elements on the left side and then use the combo boxes on the right side to choose font face, font size, font style, background color and foreground color. Click the Reset button to apply the default settings to the selected elements. To discard all changes and apply the default settings to all the elements, click the Reset All button.

The [Views] Page

In the [Views] page you can select the persistent fields that are shown in the viewer windows and their order of appearance. This may be useful when working with classes with a large number of fields where displaying all the fields is problematic (for instance, in a row in the table viewer).

There are three views. The [Table View] determines which fields in each persistent class are displayed as columns in Table viewer windows. The [Tree View] determines which fields are displayed as child nodes when browsing persistent objects using the Tree viewer windows. The [Summary] view is also used for the Tree viewer. It determines which fields are displayed as a summary of a persistent object in the node that represents the object itself. The [Table View] and the [Tree View] are initialized to contain all the persistent fields, but the [Summary] view is initialized as an empty view. Therefore, unless set, persistent objects are presented in the Tree viewer as an empty set of fields (using "{}").

To set a view for a class, first select one of the three supported views and then select the persistable class in the list of classes. You can change the visibility of persistent fields of the class (in the selected view) using the Left and Right arrow buttons to move fields between the [Shown Fields] and the [Hidden Fields] lists. You can change the order of the fields shown by using the Up and Down arrow buttons or the [Field Ordering] combo box. A view for a class can also be set by right clicking one of its instances in the viewer window (Table or Tree) and using the [Set View] context menu command.