Tuesday, June 24, 2008

The DTP Driver Framework (Repost)

Hi all...

In this article, we're going to cover an introduction to the DTP Driver Framework. What are Driver Templates/Driver Definitions? What do we do with them? Where does the UI fit in? Where does the properties provider fit in? Can I make a Driver Template into a hat? Where does the Database Definition fit in?

All of these questions and more will be answered by the end of the article, I hope.

So let's start with an easy one. What is a Driver Template? A Driver Template is a named collection of properties needed to define a usable Driver Definition.

A Driver Definition is a real instance of a Driver Template, with specific paths to driver jars or particular information to help users of that driver to create a Connection Profile that uses it.

We'll cover Connection Profiles in another article, but note that Driver Templates and Driver Definitions are optional for Connection Profiles. We use them for JDBC Connection Profiles because they provide an easy way to manage drivers and driver jars without duplicating that information in each Connection Profile instance.

Basically we have ([] = optional):

[Driver Template -> Driver Definition] -> Connection Profile

Each Driver Template can fall into one parent category, but categories can be split up in many ways. For example, we have a Database category, and then break that down by Vendor (IBM, Sybase, etc.) and Version (DB2 8.1, ASE 15, etc.). These categories provide groupings for Templates so we can refer to a parent category of Templates in particular controls used for Connection Profile creation/editing - like the DriverListCombo. You can give the DriverListCombo a category ID (like the one for Derby driver templates for example) and it will grab all of the Driver Definitions that use Driver Templates that fall under that category or any of its child categories.

(Brief sidebar... In Europa and before, we used to display Driver Definitions on the Driver Definitions preference page in a tree that followed this scheme... Databases -> Vendor -> Version -> Driver Definition, but now in Ganymede we arrange this differently so it's easier to sort by vendor or version or category to get at what you're looking for.)

Think of a Driver Template as a basic set of properties needed for a driver. Driver Templates require a unique ID, a name, and a parent category. Though jar lists are required for managing JDBC drivers, they're not mandatory for all Driver Templates, so you can specify if an empty jar list is ok. You can also provide a default name for Driver Definitions that use the Template as well as a class that can programmatically provide values for properties when Driver Definitions are created.

In addition, you can provide a list of other properties for the Driver Template. It's quite customizable. For JDBC templates, we require:
  • Driver Class
  • Vendor
  • Version
  • Database Name
  • Connection URL
  • User ID
  • Password
As an example, the Derby Embedded JDBC Driver template for version 10.0 of Derby has the following basic properties:
  • id = org.eclipse.datatools.connectivity.db.derby.genericDriverTemplate
  • name = %DERBY_EMBEDDED_DRIVER_TEMPLATE_NAME (which resolves to "Derby Embedded JDBC Driver")
  • description = (but this may be used in the future in the Driver Definition UI as a tooltip)
  • parentCategory = org.eclipse.datatools.connectivity.db.derby.10_0.driverCategory, which is a child category of org.eclipse.datatools.connectivity.db.derby.driverCategory, which is a child category of org.eclipse.datatools.connectivity.db.driverCategory (so you can see the hierarchy - all Database drivers fall under "org.eclipse.datatools.connectivity.db.driverCategory", and then Derby further defines it to a "Derby" category and then a category for "10.0" beneath that)
  • jarList = derby.jar (multiple jars could be specified here, and this property can be further modified by the valuesProvider class)
  • createDefault = false (indicates whether we should create a default Driver Definition for this template when a new workbench is created for the first time)
  • emptyJarListIsOK = false (indicates that a jar list is required for this Derby 10.0 template)
  • valuesProvider = org.eclipse.datatools.connectivity.apache.internal.derby.driver.DerbyDriverValuesProvider101 (this is a class that implements the IDriverValuesProvider interface and is used in the Derby case to see if one of two JDBC driver file plug-in wrappers exists in the workbench - if it does, it will create a Driver Definition by default, changing the jarList to have a valid path to the jar and setting createDefault to true)
  • defaultDefinitionName = %DERBY_EMBEDDED_DRIVER_DEFAULT_INSTANCE_NAME (resolves to "Derby Embedded JDBC Driver 10.0" and is used if the valuesProvider finds the right plug-ins and creates a default Driver Definition)
Then when a Driver Definition is instantiated for that Driver Template, it uses the values from the Driver Template as defaults and allows the user to modify them. Think of this as a concrete instance of a template. Sort of like a Microsoft Word template used to create a Microsoft Word document. The template just suggests some defaults for the document, but the document is the actual file being modified.

So with our Derby example, we create an instance of the Derby Driver Template that takes those defaults and allows the user to modify the values to make the Driver Definition "valid". This means in effect that a) any jar files specified in the jar/zip files list are accessible and b) any required properties have values. We point to a concrete path for our derby.jar file, maybe modify the default JDBC url and user name for our basic installation, and we're on our way.

As we mentioned earlier, if the valuesProvider class finds an appropriate plug-in wrapper for the Derby driver, it will create the Driver Definition by default and the user won't have to modify it unless they need to tweak the defaults for their installation.

Once we have a Driver Definition defined for a given database type, we can then create a Connection Profile that uses the properties of the Driver Definition as defaults (jar list and driver class are shared between the Driver Definition and the Connection Profile), and we can specialize our Profile details further, perhaps adding some optional properties to the url, a unique port or database name/path, or providing a more specific user name/password combination.

Now... I mentioned in my introduction last week that you can do more with Driver Templates and Driver Definitions than just use them in database Connection Profiles.

What if you want to define some basic communication protocols for a particular Connection Profile to consume? For example, you might define an "e-mail" driver that doesn't have any jars, but defines the basic properties of an SMTP server vs. a POP3 server vs. some other e-mail server type. So you could have two or three Driver Definitions that get consumed by an e-mail Profile (nobody's written one yet, want to volunteer?) to access and display e-mail sitting on a server somewhere.

Or maybe you want to use DTP to help manage connections to application servers? There's a wide variety of those... JBoss or Tomcat or EAServer or any number of others... Why not come up with a common Connection Profile that consumes "application server" Driver Definitions to show... message queues or provide administration functionality to start/stop a server, or view the log for the server.

Perhaps you're playing with social networking sites and you want to come up with a common set of functionality across them... Would you be able to perhaps use OpenSocial with DTP to provide that functionality?

There are a ton of possibilities to explore.

Think of Driver Templates and Driver Definitions as helpers for Connection Profiles. They're not required, but they can provide a place to share common details among profiles so you don't have to duplicate it in a bunch of profiles. For example, what if you have a bunch of database Profiles that don't use the Driver Framework and you want to update your driver class/jar list for a new version of the JDBC driver? Depending on how you implemented it, your user might have to go into each and every Profile that references the old files/driver class and update them by hand. Or if you use the Driver Framework, you update it in one place and the very next time you connect, it gets picked up automatically by the Profile.

So what do you think? Can you think of places where it would be handy to use DTP's Connection Profile and Driver Frameworks to meet a need?

As always, holler if you have questions or think I'm making this stuff up as I go along. I value the input of the community. There's LOTS of room to explore to see where we can take the DTP frameworks and I'm happy to be along for the ride!

Next week we'll start talking about how to implement your own custom Driver Templates.
Until next time...
--Fitz

1 comment:

Ray da Costa said...

Hi, okay?
My name is Ray da Costa(raimundo.costa@totvs.com.br), I live in Brazil Sao Paulo, my boss was participant of Eclipse2009 and came here in Brazil with a task.
Requested an application to load a txt file via Eclipse semparado by "." I found a tutorial with this feature.
You have a step by step to accomplish this task?