SQL Query Builder Component API

← Back to SQL Development Tools page

Introduction

The SQL Query Builder is a component for visually editing SQL DML statements. It can be consumed by other UI components such as editors, dialogs and wizards. As input, it can accept .sql files created by the DTP SQL File Editor or it can accept SQL statements passed in the form of strings.

The API described here is currently provisional and is subject to change until this notice of provisional status is removed.

CVS Location

The SQL Query Builder is located in the datatools part of the Eclipse CVS repository

Host: dev.eclipse.org

Repository path: /cvsroot/datatools

The SQL Query Builder plugin is in

org.eclipse.datatools.sqltools/plugins/org.eclipse.datatools.sqltools.sqlbuilder

There is also an examples plugin in

org.eclipse.datatools.sqltools/examples/org.eclipse.datatools.sqltools.sqlbuilder.examples

For up to date information about how to use the SQL Builder Editor, see

org.eclipse.datatools.sqltools/prototype/devnotes/sqlbuilder_notes.txt

SQLBuilder Component and Example Consumers

SQLBuilder component

The main component class is

org.eclipse.datatools.sqltools.sqlbuilder.SQLBuilder

This class is a graphical editing component to which a SQL statement is passed for editing. It can be hosted in an editor, a dialog or a wizard. Examples of the SQLBuilder class hosted in a dialog and an editor are described below. These examples demonstrate all the API functions described in this document.

The sequence of function calls required to host the SQLBuilder is as follows:

_sqlBuilder = new SQLBuilder();

_sqlBuilder.addContentChangeListener(this);

_sqlBuilder.setInput(_editorInput);

_sqlBuilder.createClient(editComposite);

where _sqlBuilder is a variable of type SQLBuilder, this is the containing class, _editorInput is the input and editComposite is the composite which will contain the SQLBuilder.

Depending on the consumer, these function calls may not all be called in a single sequence, but may be split into groups called from other functions. For example if the consumer is an EditorPart, setInput should be called during the editor's init(IEditorSite, IEditorInput) method and createClient should be called during createPartControl(Composite). See Example SQLBuilder editor below.

Constructor

The constructor takes no parameters.

addContentChangeListener(IContentChangeListener)

addContentChangeListener should be passed an object which implements the interface

org.eclipse.datatools.sqltools.sqlbuilder.IContentChangeListener.

This interface has a single method notifyContentChange which is invoked when the content model being edited by the SQLBuilder changes. This allows the client to be notified of changes to the SQL statement being edited so that it can update its own dirty status and handle user requests to save the statement.

setInput(ISQLBuilderEditorInput)

Passes an EditorInput to the SQLBuilder. See Input Types below.

createClient(Composite)

Constructs the SQLBuilder UI inside the Composite passed as a parameter.

Other functions

A further two functions are useful for editors. These are:

setLoadOnConnection(boolean);

connectIfNeeded(IWorkbenchPart)

The problem these functions are designed to solve is that of the workbench opening when its saved state includes an instance of an editor which hosts the SQLBuilder. When the Workbench opens it will try to open the editor and the SQLBuilder will need to make a connection to a database. setLoadOnConnection tells the SQLBuilder to delay loading the input until a database connection has been obtained. connectIfNeeded should be invoked as soon as possible after the editor has initialized inside the Workbench.

setLoadOnConnection should be called before calling setInput and connectIfNeeded should be called after the editor has been initialized in the Workbench. In the example editor, setLoadOnConnection is called during setFocus.

Input Types

SQLBuilder.setInput takes an org.eclipse.datatools.sqltools.sqlbuilder.ISQLBuilderEditorInput parameter, for which two implementations are provided:

org.eclipse.datatools.sqltools.sqlbuilder.SQLBuilderFileEditorInput

org.eclipse.datatools.sqltools.sqlbuilder.SQLBuilderStorageEditorInput

These input types are EditorInputs supplemented with two extra pieces of information required by the SQLBuilder - connection information and OmitSchemaInfo (see Omit Current Schema ). Connection information is a reference to a database connection profile. It is represented by the SQLEditor class ISQLEditorConnectionInfo. OmitSchemaInfo information specifies whether the current schema name should be omitted from SQL generated by the SQLBuilder. It is represented by the SQLBuilder interface and class org.eclipse.datatools.sqltools.sqlbuilder.model.IOmitSchemaInfo and OmitSchemaInfo.

The contents of the editor input (i.e. file or storage object) are the SQL statement. Connection information and OmitSchemaInfo are stored as properties associated with the input.

In inputs passed to the SQLBuilder, the ConnectionInfo part must be populated with a reference to a connection profile, but the OmitSchemaInfo part may be empty. If it is empty, a new OmitSchemaInfo object will be created using the Eclipse Preference settings defined for the SQL Builder.

File inputs: SQLBuilderFileEditorInput

SQLBuilderFileEditorInput sub-classes FileEditorInput. Connection Information and OmitSchemaInfo information are stored as Eclipse persistent properties associated with the .sql resource.

For reference, after creating a .sql file in the SQL File Editor and editing it in the SQL Query Builder, these properties can be found in

.metadata\.plugins\org.eclipse.core.resources\.projects\<proj_name>\.indexes\properties.index

For examples of file inputs, see the Example Dialog or Editor described below.

Non file-based inputs: SQLBuilderStorageEditorInput

SQLBuilderStorageEditorInput is a class designed so that the SQL Builder can accept non file-based inputs. It allows clients to create SQLBuilder inputs from strings.

SQLBuilderStorageEditorInput persists itself as an XMLMemento which is an XML document containing the SQL Statement, ConnectionInfo and OmitSchemaInfo. The XMLMemento can be serialized or loaded to/from a string.

The class

org.eclipse.datatools.sqltools.sqlbuilder.util.SQLBuilderEditorInputUtil

contains utility functions for creating SQLBuilderStorageEditorInput objects from strings and files, saving them to XMLMementos and serializing XMLMementos to strings.

See the Example Dialog below for examples of how SQLBuilderStorageEditorInput and SQLBuilderEditorInputUtil are used.

Example SQLBuilder Editor

The example of an editor which consumes the SQLBuilder class is in the main org.eclipse.datatools.sqltools.sqlbuilder plugin. The main class is:

org.eclipse.datatools.sqltools.sqlbuilder.SQLBuilderEditor

This editor is invoked when a .sql file is opened using the Open with ->SQL Query Builder popup menu. It demonstrates how to embed the SQLBuilder component in an EditorPart. The SQLBuilderEditor opens .sql files which have previously been created in the DTP SQL File Editor and it relies on connection profile information having previously been persisted by the SQL File Editor. To use the SQLBuilder Editor, see

org.eclipse.datatools.sqltools/prototype/devnotes/sqlbuilder_notes.txt

Example SQLBuilder Dialog

In the org.eclipse.datatools.sqltools.sqlbuilder.examples plugin, there is an example of a dialog which hosts the SQLBuilder component:

org.eclipse.datatools.sqltools.sqlbuilder.examples.dialogs.SQLBuilderDialog

When this plugin is loaded, the popup menu for .sql files in the Navigator or Project Explorer View has a new entry SQLBuilder Dialog. Under this menu item are two sub-entries Open File and Open StorageInput. Open File loads the currently selected .sql file in SQLBuilderDialog. Open StorageInput also loads the currently selected .sql file, but it does so in a roundabout way to demonstrate how to use the SQLBuilderStorageEditorInput class. It creates a SQLBuilderStorageEditorInput based on the file, serializes the SQLBuilderStorageEditorInput to a string via an XMLMemento, then creates a new SQLBuilderStorageEditorInput from the string. This is done in the class

SQLBuilderDialogStorageAction

in the method call

EditorInputUtil.createSQLBuilderEditorInputFromStringViaFile(IFile)

SQLBuilderDialog has a Save button which demonstrates how to save the dialog's data, i.e. the SQL Statement, ConnectionInfo and OmitSchemaInfo to a string.

Comments / Suggestions

Please add your comments / suggestions here.