Package oracle.jdeveloper.offlinedb

Database API extension for saving database object definitions in XML files.

See:
Description

Interface Summary

OfflineDBUpdateManager.Processor
OfflineDBValidationManager.Validator	Interface to be implemented for any class wishing to be registered to provide extra validation in the offlinedb.

Class Summary

OfflineDBObjectFactory	Factory class with methods for creating DBObjects for use in the offline API.
OfflineDBObjectID	Deprecated. use IdentifierBasedID if a subclass of DBObjectID is *really* needed.
OfflineDBObjectProvider	Extension of DBObjectProvider for the offline projects.
OfflineDBPropertyInitializationManager
OfflineDBUpdateManager	Allows registration of user-code to update offline database objects after they have been commited to the OfflineDBObjectProvider but before the Validation phase begins.
OfflineDBUtil	Utility class for the offline database project.
OfflineDBValidationManager	Manager that can be used to extend the offline databases's validation logic.

Enum Summary

OfflineDBObjectFactory.IDScheme

Deprecated.

Exception Summary

DependentProviderUpdateException

If an attempt is made to update or delete an object that exists in a dependent offline provider, rather than the current provider then this exception is thrown.

Package oracle.jdeveloper.offlinedb Description

Database API extension for saving database object definitions in XML files.

Since JDeveloper 9.0.5 you have been able to store database object definitions in a Project using XML files. This support started as just Tables, and has now grown to support many database objects. It is known as the "Offline Database" (offlinedb). The reason for the name is to avoid user confusion with a live database connection (to a running database) in the database navigator.

The offlinedb is built on top of the underlying JDeveloper database metadata API which from 10.1.3 is found in the oracle.javatools.db package.

(The examples in this document contain code that does no error handling. This makes it easier to read for the purposes of this document but proper error handling should be included in real code.)

Getting Started (DBObjectProvider)

The starting point for using the oracle.javatools.db api is the DBObjectProvider interface. Once you have a DBObjectProvider (provider) you can list, create, update and delete object definitions in that provider, be it a live Database or a Project containing xml files.

An offline database exists as an XML file within a project with the extension ".offlinedb". To retrieve the DBObjectProvider for that file you use the DBOBjectProviderFactory and pass the URL in as the identifier.

  import java.net.URL;
  import oracle.javatools.db.DBObjectProviderFactory;
  import oracle.jdeveloper.offlinedb.OfflineDBObjectProvider;
...

  URL url = ...
  OfflineDBObjectProvider provider =
    (OfflineDBObjectProvider)DBObjectProviderFactory.findOrCreateProvider( url );

To list the providers in a given project, there are static methods on OfflineDBObjectProvider for searching the project's content set:

java.util.Iterator<OfflineDBObjectProvider> getProviderIterator(Project p)
java.util.List<OfflineDBObjectProvider> listDBObjectProviders(Project p)

See the javadoc for these methods for more information.

Refer to the DBObjectProvider javadoc for more method information. Most provider methods throw the DBException class which should be handled appropriately for the case where an operation causes an error.

Examples Of Using A Provider

For information on using a DBObjectProvider see the oracle.javatools.db package documentation for the database API.

In the offlinedb specifically you can also do:

  URL url = ... // url to fred.table xml file
  Table fred = (Table)( (OfflineDBObjectProvider)provider ).getObject( url );

Letting the User Choose/Create A Provider

The oracle.jdeveloper.offlinedb.wizard.ProviderWizard class provides the ability to fire create/edit/chooser dialogs for the user to manage their OfflineDBObjectProvider instances. These can be used by an extension to prompt the user.

For example the following code will prompt the user to choose (or create) a provider in the given project and return you the result:

  OfflineDBObjectProvider provider = ProviderWizard.chooseProvider( project, true );

To provide this choice as part of a wizard process, the panel to use is oracle.jdeveloper.offlinedb.panels.OfflineDBChooserPanel. It is a Traversable, and requires the oracle.ide.Context in the namespace under oracle.ide.db.UIContants.WIZARD_CONTEXT_KEY. It will place the chosen provider under the UIConstants.PROVIDER_KEY.

Storing References

All objects in the API extend the DBObject interface which includes the method getID(). This returns a DBObjectID which is used to uniquely identify objects. The resolveID() method on DBObjectID returns the original object. All objects that reference other objects in the API (FKConstraints, Synonyms, etc) use DBObjectIDs to store the reference.

By default the IDs used by the offline database are UUID based, not name based. This means that a programatic user of the offlinedb should store the DBObjectID for a given object as a reference and NOT its name and Schema, or URL. This will protect against renaming, as on rename the ID remains the same.

See Also:

oracle.javatools.db