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 by consumers in the form of strings.

The API described here is currently provisional and may be changed as a result of feedback from early adopters.

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

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. 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.

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 so that it can update its own dirty status and handle user requests to save the statement being edited.

setInput(ISQLBuilderEditorInput)

createClient

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). For more details, please see the examples described below.

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 the 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 (see below), setLoadOnConnection is called during setFocus.

Input Types

File inputs

Non file-based inputs

Example SQLBuilder editor

The SQLBuilderEditor hosts the SQLBuilder component in an Eclipse editor:

org.eclipse.datatools.sqltools.sqlbuilder.SQLBuilderEditor

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

The SQLBuilderEditor opens .sql files which have previously been created in the DTP SQL File Editor. It relies on the connection profile information being persisted as persistent properties associated with the .sql resource (this is done by the SQL File Editor).