Driver Definition

Identifier:

Since:

Description:

The driverExtension is used by developers to define templates that describe the mechanical components necessary for opening connections to servers. Users create specific driver definitions using these templates.

The driver definitions are intended to be used in conjunction with connection profiles, where the driver definition specifies the mechanics (e.g. JAR files, driver class names, etc.) necessary for opening the connection and where the connection profile specifies the particulars for connecting to a specific server (e.g. host, port, user ID, password, etc.).

In addition, using the driverTemplateOverride functionality, adopters can take existing driver templates (such as for one of the Enablement projects) and update the driver's jar list to actually point to a wrapped jar, or update individual properties of a template to fit a particular use.

Configuration Markup:

<!ELEMENT extension (category* , driverTemplate* , driverTemplateOverride*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED

<!ELEMENT category EMPTY>

<!ATTLIST category

id             CDATA #REQUIRED

name           CDATA #IMPLIED

description    CDATA #IMPLIED

parentCategory CDATA #IMPLIED

This element is used to identify a category. Categories are used to group related connection profile types (e.g. databases).

• id - The id of this category. This value is referenced by driverTemplate elements.
• name - The display name for this category.
• description - The description of this category. This value will be used in the UI to describe a particular category.
• parentCategory - The id of a parent category, if this category has a parent.

<!ELEMENT driverTemplate (properties? , migration?)>

<!ATTLIST driverTemplate

id                    CDATA #REQUIRED

name                  CDATA #IMPLIED

description           CDATA #IMPLIED

parentCategory        CDATA #IMPLIED

jarList               CDATA #IMPLIED

createDefault         (true | false) "true"

emptyJarListIsOK      (true | false) "false"

valuesProvider        CDATA #IMPLIED

defaultDefinitionName CDATA #IMPLIED

This element is used to identify a template.

• id - The id of this driver type.
• name - The display name for this driver type.
• description - The description of this driver type. This value will be used in the UI to describe a particular type.
• parentCategory - The id of the category to which this template belongs.
• jarList - The list of JAR files used to create the classpath used when connecting using this driver.
• createDefault - Specifies whether or not this template should be used to create a default driver definition instance. If set to true, a driver definition instance with the name specified in the template is guaranteed to exist in the list of driver definitions. Default is true.
• emptyJarListIsOK - Specifies whether or not it is valid for the jarList property to be empty. Default is false.
• valuesProvider -
• defaultDefinitionName -

<!ELEMENT properties (property+)>

Parent container for specific driver definition properties.

<!ELEMENT property EMPTY>

<!ATTLIST property

id                       CDATA #REQUIRED

name                     CDATA #REQUIRED

description              CDATA #IMPLIED

value                    CDATA #IMPLIED

visible                  (true | false) "true"

example                  CDATA #IMPLIED

required                 (true | false) "true"

generated                (true | false) "false"

customPropertyDescriptor CDATA #IMPLIED

category                 CDATA #IMPLIED

A property definition for a driver definition.

• id - The id of this property. Used to identify this property in the driver definition.
• name - The display name for this property.
• description - The description of this property. This value will be used in the UI to describe a particular type.
• value - The default value for this property.
• visible - Specifies whether or not this property is visible and editable to the user. Default is true.
• example - Specifies an example value for this property.
• required - Specifies whether or not this is a required property. Default is true.
• generated - currently unused and undefined.
• Deprecated customPropertyDescriptor - Provides a way to specify a custom property descriptor that extends the class org.eclipse.ui.views.properties.PropertyDescriptor. An example of this is the class org.eclipse.datatools.connectivity.ui.PasswordTextPropertyDescriptor, which provides a property editor that masks the characters for a password property. Anything you can implement as a property descriptor for the Properties Viewer, you can use here. Or if you want to make the property values read-only, you can use org.eclipse.ui.views.properties.PropertyDescriptor directly. Note that your property descriptor must implement a zero-argument constructor in order to be created correctly. This zero-argument constructor should provide the id and display name of the property you are editing. For example: private static String DRIVER_CLASS_PROP_ID = "org.eclipse.datatools.connectivity.db.driverClass"; //$NON-NLS-1$ public DriverClassBrowsePropertyDescriptor() { super(DRIVER_CLASS_PROP_ID, ConnectivityUIPlugin.getDefault().getResourceString("DriverClassBrowsePropertyDescriptor.property.label")); //$NON-NLS-1$ } Also note that there is a new interface that your Property Descriptor can extend called org.eclipse.datatools.connectivity.drivers.IDriverInstancePropertyDescriptor. This interface allows you to pass the Driver Instance to your descriptor when it is instantiated in the Edit Driver Definition dialog.
• category - The category tag is used to provide an optional category for your template properties. The default is "General" if no category is specified for the property. You can use this to group properties in arbitrary categories.

<!ELEMENT driverTemplateOverride (propertyOverrides)?>

<!ATTLIST driverTemplateOverride

targetId              CDATA #REQUIRED

name                  CDATA #IMPLIED

description           CDATA #IMPLIED

parentCategory        CDATA #IMPLIED

jarList               CDATA #IMPLIED

createDefault         (true | false)

emptyJarListIsOK      (true | false)

valuesProvider        CDATA #IMPLIED

priority              CDATA "1"

defaultDefinitionName CDATA #IMPLIED

id                    CDATA #IMPLIED

remove                (true | false)

This element is used to identify a template override

• targetId - The id of the driver template to be overridden.
• name - The overridden display name for this driver type.
• description - The overridden description of this driver type. This value will be used in the UI to describe a particular type.
• parentCategory - The id of the category to which this template belongs.
• jarList - The list of JAR files used to create the classpath used when connecting using this driver.
• createDefault - Specifies whether or not this template should be used to create a default driver definition instance. If set to true, a driver definition instance with the name specified in the template is guaranteed to exist in the list of driver definitions. Default is true.
• emptyJarListIsOK - Specifies whether or not it is valid for the jarList property to be empty. Default is false.
• valuesProvider -
• priority - The value for priority should be a value of 1 to 5, with 1 being low and 5 being high, indicating the priority for this override. If there are other overrides for the particular target driver template, the priority will be used to indicate which override should take precedence. If no priority is specified, the priority will default to "1". If multiple overrides have the same priority, the one with the lowest plug-in ID alphabetically (IDs will be sorted in ascending alphabetical order) will take precedence.
• defaultDefinitionName -
• id - The id attribute, though optional, is required to allow one driverTemplateOverride instance to override another. For example, if driver A has an override B that changes or removes a property, another adopter might implement override C that uses the id of override B as the targetId, thus replacing the overridden driver template with their own. In the case of multiple overrides or overrides of overrides, the priority is taken into account.
• remove - Removes the template from the list of available templates.

<!ELEMENT propertyOverrides (propertyOverride)+>

Parent container for specific driver definition overridden properties

<!ELEMENT propertyOverride EMPTY>

<!ATTLIST propertyOverride

targetId                 CDATA #REQUIRED

name                     CDATA #IMPLIED

description              CDATA #IMPLIED

value                    CDATA #IMPLIED

visible                  (true | false)

example                  CDATA #IMPLIED

required                 (true | false)

customPropertyDescriptor CDATA #IMPLIED

category                 CDATA #IMPLIED

remove                   (true | false)

A property override definition for a driver template

• targetId - The id of the property to override. Must match the property ID from the driver template you are overriding. Used to identify this property in the driver definition.
• name - The overridden display name for this property.
• description - The overridden description of this property. This value will be used in the UI to describe a particular type.
• value - The overridden default value for this property.
• visible - Specifies whether or not this property is visible and editable to the user. Default is true.
• example - Specifies an example value for this property.
• required - Specifies whether or not this is a required property. Default is true.
• Deprecated customPropertyDescriptor - Provides a way to override a custom property descriptor that extends the class org.eclipse.ui.views.properties.PropertyDescriptor. An example of this is the class org.eclipse.datatools.connectivity.ui.PasswordTextPropertyDescriptor, which provides a property editor that masks the characters for a password property. Anything you can implement as a property descriptor for the Properties Viewer, you can use here. Or if you want to make the property values read-only, you can use org.eclipse.ui.views.properties.PropertyDescriptor directly. Note that your property descriptor must implement a zero-argument constructor in order to be created correctly. This zero-argument constructor should provide the id and display name of the property you are editing. For example: private static String DRIVER_CLASS_PROP_ID = "org.eclipse.datatools.connectivity.db.driverClass"; //$NON-NLS-1$ public DriverClassBrowsePropertyDescriptor() { super(DRIVER_CLASS_PROP_ID, ConnectivityUIPlugin.getDefault().getResourceString("DriverClassBrowsePropertyDescriptor.property.label")); //$NON-NLS-1$ } Also note that there is a new interface that your Property Descriptor can extend called org.eclipse.datatools.connectivity.drivers.IDriverInstancePropertyDescriptor. This interface allows you to pass the Driver Instance to your descriptor when it is instantiated in the Edit Driver Definition dialog.
• category - The category tag is used to override the category for your template properties. The default is "General" if no category is specified for the property. You can use this to group properties in arbitrary categories.
• remove - Indicates if this property should be removed

<!ELEMENT migration (propertyMigration*)*>

<!ATTLIST migration

newDriverTemplateID CDATA #IMPLIED

class               CDATA #IMPLIED

Use this element to add migration support for a deprecated driver type (e.g. ID changes, property changes, etc.). Make sure if you are migrating driver definitions of one template to another and the first driver template was set to "createDefault = true", that you set the old driver template to createDefault = false or the driver manager will attempt to recreate the older template and then migrate it.

• newDriverTemplateID - The ID of the new driver template to which the old driver template should be associated with. If this attribute is not specified, the ID of the driver template is not changed. However, propertyMigration elements, if any, will still be processed and applied.
• class - A migration implementation that allows the provider to perform a specialized migration. Use this method if you require a more complex migration algorithm (i.e. anything other than simple name and property mapping).

<!ELEMENT propertyMigration EMPTY>

<!ATTLIST propertyMigration

oldPropertyKey CDATA #IMPLIED

newPropertyKey CDATA #IMPLIED

newValue       CDATA #IMPLIED

This element is used to specify a simple mapping for property key names from a source driver definition to a target driver definition

• oldPropertyKey - The key name in the source driver definition If this property is not specified, the new property will be defaulted with the value of newValue.
• newPropertyKey - The key name in the target driver definition If this value is not specified, the old property will be deleted.
• newValue - Use this attribute for populating a default property value for a new property. newPropertyKey must be set.

Examples:

API Information:

Supplied Implementation:

Copyright (c) 2004-2007 Sybase, Inc.

All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-2.0/

Contributors: brianf - initial API and implementation