| <html> |
| |
| <head> |
| <meta http-equiv=Content-Type content="text/html; charset=windows-1252"> |
| <meta name=Generator content="Microsoft Word 11 (filtered)"> |
| <title>Introduction to the Driver Management Framework</title> |
| <style> |
| <!-- |
| /* Font Definitions */ |
| @font-face |
| {font-family:Wingdings; |
| panose-1:5 0 0 0 0 0 0 0 0 0;} |
| /* Style Definitions */ |
| p.MsoNormal, li.MsoNormal, div.MsoNormal |
| {margin:0in; |
| margin-bottom:.0001pt; |
| font-size:12.0pt; |
| font-family:"Times New Roman"; |
| color:windowtext;} |
| h1 |
| {margin-top:3.75pt; |
| margin-right:0in; |
| margin-bottom:.75pt; |
| margin-left:0in; |
| font-size:18.0pt; |
| font-family:Arial; |
| color:black; |
| font-weight:bold;} |
| h6 |
| {margin-right:0in; |
| margin-left:0in; |
| font-size:10.0pt; |
| font-family:Arial; |
| color:black; |
| font-weight:bold;} |
| a:link, span.MsoHyperlink |
| {color:blue; |
| text-decoration:underline;} |
| a:visited, span.MsoHyperlinkFollowed |
| {color:purple; |
| text-decoration:underline;} |
| p |
| {margin-top:7.5pt; |
| margin-right:0in; |
| margin-bottom:7.5pt; |
| margin-left:0in; |
| font-size:10.0pt; |
| font-family:Arial; |
| color:black;} |
| samp |
| {font-family:"Courier New";} |
| p.code, li.code, div.code |
| {margin-top:0in; |
| margin-right:0in; |
| margin-bottom:0in; |
| margin-left:15.0pt; |
| margin-bottom:.0001pt; |
| font-size:10.0pt; |
| font-family:"Courier New"; |
| color:#4444CC;} |
| p.configmarkup, li.configmarkup, div.configmarkup |
| {margin-top:7.5pt; |
| margin-right:0in; |
| margin-bottom:7.5pt; |
| margin-left:0in; |
| font-size:10.0pt; |
| font-family:Arial; |
| color:black;} |
| @page Section1 |
| {size:8.5in 11.0in; |
| margin:1.0in 1.25in 1.0in 1.25in;} |
| div.Section1 |
| {page:Section1;} |
| /* List Definitions */ |
| ol |
| {margin-bottom:0in;} |
| ul |
| {margin-bottom:0in;} |
| --> |
| </style> |
| |
| </head> |
| |
| <body lang=EN-US link=blue vlink=purple> |
| |
| <div class=Section1> |
| |
| <p class=MsoNormal align=center style='text-align:center'><b><span |
| style='font-size:14.0pt'>Eclipse Data Tools Platform Project Component: Driver |
| Management Framework</span></b></p> |
| |
| <p class=MsoNormal align=center style='text-align:center'>Rob Cernich (Sybase), |
| John Graham (Sybase)</p> |
| |
| <p class=MsoNormal><b><span style='font-size:14.0pt'> </span></b></p> |
| |
| <p class=MsoNormal><b><span style='font-size:14.0pt'>Introduction</span></b></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal>This document provides an overview of the Driver Management |
| Framework (<b>DMF</b>) components found in the DTP M1.101205 (Iteration 1) |
| build. The purpose is to describe current functionality, extension points, and |
| API so that the community can evaluate and provide feedback on this component. |
| DMF is housed in the <i>org.eclipse.datatools.connectivity</i> plug-in.</p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal><b><span style='font-size:14.0pt'>Environment</span></b></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <ul style='margin-top:0in' type=disc> |
| <li class=MsoNormal>Eclipse 3.1</li> |
| <li class=MsoNormal>DTP M1 Iteration 1 build (M1.101205)</li> |
| </ul> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal><b><span style='font-size:14.0pt'>DMF Purpose</span></b></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal>There is a large class of tools which need access to |
| run-time specific libraries. For example, the DTP Connection Management |
| Framework (<b>CMF</b>) needs to define connection configuration properties for |
| data sources, and the data access components (or drivers) required to complete |
| the connection also need to be specified. This can be though of as a |
| generalization of the class path notion in Java. In most cases, users will |
| not want to redefine driver details for every tool requiring these components. |
| It would be much more convenient, and consistent, to define these values in |
| manner accessible through the Eclipse instance. DMF provides this capability |
| for drivers.</p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal><b><span style='font-size:14.0pt'>DMF User Interface</span></b></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal>After installing DMF, you will find a new preference page |
| for driver definitions:</p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal align=center style='text-align:center'><img width=581 |
| height=338 src="images/dmf_prefs.JPG"></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal>Selecting this entry opens the driver definition preference |
| page:</p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal align=center style='text-align:center'><img width=581 |
| height=338 src="images/dmf_pref_page.JPG"></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal>In the current build, only one driver template (JDBC) is |
| provided. This template registers itself under a Database category, though |
| other templates are free to add whatever categories are appropriate for their |
| case. At the moment, we do not have any driver definitions, so we will create |
| one by choosing the category (Database) and selecting Add
:</p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal align=center style='text-align:center'><img width=586 |
| height=339 src="images/new_driver_entry.JPG"></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal>Again, only one driver template has been installed, so we |
| will choose that one and enter a name:</p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal align=center style='text-align:center'><img width=586 |
| height=339 src="images/new_driver_entry_values.JPG"></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal>Leaving the Edit New Driver Instance Immediately option |
| checked will launch a wizard to complete the driver details when the OK |
| button is selected:</p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal align=center style='text-align:center'><img width=699 |
| height=505 src="images/edit_driver_entry.JPG"></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal>In this case the driver file is going to be the JDBC driver |
| archive. The template specifies any configuration values necessary via the DMF |
| extension point (discussed below) and these are surfaced in the Properties |
| table. In this simple example, we are asked for the driver class and the model |
| instance for the given database type (currently these properties are for |
| illustration purposes only, and will be fleshed out in later builds). Providing |
| a required values and selecting OK completes the driver definition. It now |
| appears in the list of available driver templates:</p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal align=center style='text-align:center'><img width=581 |
| height=338 src="images/dm_prefs_complete.JPG"></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal>The driver definition First Test can then be reused by |
| other components requiring data access.</p> |
| |
| <p class=MsoNormal> </p> |
| |
| <p class=MsoNormal><b><span style='font-size:14.0pt'>DMF Extension Point</span></b></p> |
| |
| <p class=MsoNormal> </p> |
| |
| <h6 style='margin-top:3.0pt;margin-right:0in;margin-bottom:11.0pt;margin-left: |
| 0in;vertical-align:baseline'><i><span style='font-size:9.0pt'>Identifier: </span></i></h6> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'>org.eclipse.datatools.connectivity.driverExtension |
| </span></p> |
| |
| <h6 style='margin-top:3.0pt;margin-right:0in;margin-bottom:11.0pt;margin-left: |
| 0in;vertical-align:baseline'><i><span style='font-size:9.0pt'>Since: </span></i></h6> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'>DTP |
| 0.x </span></p> |
| |
| <h6 style='margin-top:3.0pt;margin-right:0in;margin-bottom:11.0pt;margin-left: |
| 0in;vertical-align:baseline'><i><span style='font-size:9.0pt'>Description: </span></i></h6> |
| |
| <p>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. </p> |
| |
| <p>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.). </p> |
| |
| <h6 style='margin-top:3.0pt;margin-right:0in;margin-bottom:11.0pt;margin-left: |
| 0in;vertical-align:baseline'><i><span style='font-size:9.0pt'>Configuration |
| Markup:</span></i></h6> |
| |
| <p class=code><!ELEMENT <a name=e.extension>extension</a> (<a |
| href="#e.category">category</a>* |
| , <a |
| href="#e.driverTemplate">driverTemplate</a>)></p> |
| |
| <p class=code><!ATTLIST extension</p> |
| |
| <p class=code>point CDATA #REQUIRED </p> |
| |
| <p class=code>id CDATA #IMPLIED </p> |
| |
| <p class=code>name CDATA #IMPLIED></p> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'><br> |
| <br> |
| </span></p> |
| |
| <p class=code><!ELEMENT <a name=e.category>category</a> EMPTY></p> |
| |
| <p class=code><!ATTLIST category</p> |
| |
| <p class=code>id CDATA |
| #REQUIRED </p> |
| |
| <p class=code>name CDATA |
| #IMPLIED </p> |
| |
| <p class=code>description CDATA #IMPLIED </p> |
| |
| <p class=code>parentCategory CDATA #IMPLIED></p> |
| |
| <p class=configmarkup>This element is used to identify a category. Categories |
| are used to group related connection profile types (e.g. databases).</p> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'><br> |
| <br> |
| </span></p> |
| |
| <ul style='margin-top:0in' type=disc> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>id</span></b><span style='font-size:10.0pt;font-family: |
| Arial'> - The id of this category. This value is referenced by </span><samp><span |
| style='font-size:10.0pt'>driverTemplate</span></samp><span |
| style='font-size:10.0pt;font-family:Arial'> elements. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>name</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The display name for this category. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>description</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The description of this category. This value will be |
| used in the UI to describe a particular category. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>parentCategory</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The id of a parent category, if this category has a |
| parent. </span></li> |
| </ul> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'><br> |
| <br> |
| </span></p> |
| |
| <p class=code><!ELEMENT <a name=e.driverTemplate>driverTemplate</a> (<a |
| href="#e.properties">properties</a>?)></p> |
| |
| <p class=code><!ATTLIST driverTemplate</p> |
| |
| <p class=code>id CDATA |
| #REQUIRED </p> |
| |
| <p class=code>name CDATA |
| #IMPLIED </p> |
| |
| <p class=code>description CDATA #IMPLIED </p> |
| |
| <p class=code>parentCategory CDATA #IMPLIED </p> |
| |
| <p class=code>jarList CDATA |
| #IMPLIED </p> |
| |
| <p class=code>createDefault (true | false) |
| "true" </p> |
| |
| <p class=code>emptyJarListIsOK (true | false) "false"></p> |
| |
| <p class=configmarkup>This element is used to identify a template.</p> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'><br> |
| <br> |
| </span></p> |
| |
| <ul style='margin-top:0in' type=disc> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>id</span></b><span style='font-size:10.0pt;font-family: |
| Arial'> - The id of this driver type. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>name</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The display name for this driver type. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>description</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The description of this driver type. This value will |
| be used in the UI to describe a particular type. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>parentCategory</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The id of the category to which this template |
| belongs. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>jarList</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The list of JAR files used to create the classpath |
| used when connecting using this driver. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>createDefault</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - 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. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>emptyJarListIsOK</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - Specifies whether or not it is valid for the jarList |
| property to be empty. Default is false. </span></li> |
| </ul> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'><br> |
| <br> |
| </span></p> |
| |
| <p class=code><!ELEMENT <a name=e.properties>properties</a> (<a |
| href="#e.property">property</a>+)></p> |
| |
| <p class=configmarkup>Parent container for specific driver definition |
| properties.</p> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'><br> |
| <br> |
| <br> |
| </span></p> |
| |
| <p class=code><!ELEMENT <a name=e.property>property</a> EMPTY></p> |
| |
| <p class=code><!ATTLIST property</p> |
| |
| <p class=code>id CDATA |
| #REQUIRED </p> |
| |
| <p class=code>name CDATA |
| #REQUIRED </p> |
| |
| <p class=code>description CDATA #IMPLIED </p> |
| |
| <p class=code>value CDATA #IMPLIED </p> |
| |
| <p class=code>visible (true | false) |
| "true" </p> |
| |
| <p class=code>example CDATA #IMPLIED </p> |
| |
| <p class=code>required (true | false) "true" </p> |
| |
| <p class=code>generated (true | false) "false"></p> |
| |
| <p class=configmarkup>A property definition for a driver definition.</p> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'><br> |
| <br> |
| </span></p> |
| |
| <ul style='margin-top:0in' type=disc> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>id</span></b><span style='font-size:10.0pt;font-family: |
| Arial'> - The id of this property. Used to identify this property in the |
| driver definition. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>name</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The display name for this property. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>description</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The description of this property. This value will be |
| used in the UI to describe a particular type. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>value</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - The default value for this property. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>visible</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - Specifies whether or not this property is visible |
| and editable to the user. Default is true. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>example</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - Specifies an example value for this property. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>required</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - Specifies whether or not this is a required |
| property. Default is true. </span></li> |
| <li class=MsoNormal style='color:black'><b><span style='font-size:10.0pt; |
| font-family:Arial'>generated</span></b><span style='font-size:10.0pt; |
| font-family:Arial'> - currently unused and undefined. </span></li> |
| </ul> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'><br> |
| <br> |
| </span></p> |
| |
| <h6 style='margin-top:3.0pt;margin-right:0in;margin-bottom:11.0pt;margin-left: |
| 0in;vertical-align:baseline'><i><span style='font-size:9.0pt'>Examples: </span></i></h6> |
| |
| <h6 style='margin-top:3.0pt;margin-right:0in;margin-bottom:11.0pt;margin-left: |
| 0in;vertical-align:baseline'><i><span style='font-size:9.0pt'>API Information: </span></i></h6> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'>[Enter |
| API information here.] </span></p> |
| |
| <h6 style='margin-top:3.0pt;margin-right:0in;margin-bottom:11.0pt;margin-left: |
| 0in;vertical-align:baseline'><i><span style='font-size:9.0pt'>Supplied |
| Implementation: </span></i></h6> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'>[Enter |
| information about supplied implementation of this extension point.] </span></p> |
| |
| <p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial;color:black'><br> |
| <br> |
| </span></p> |
| |
| <p>Copyright (c) 2004-2005 Sybase, Inc.</p> |
| |
| <p>All rights reserved. This program and the accompanying materials are made |
| available under the terms of the Eclipse Public License v1.0 which accompanies |
| this distribution, and is available at <a |
| href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a></p> |
| |
| <p>Contributors: brianf - initial API and implementation</p> |
| |
| <p class=MsoNormal> </p> |
| |
| </div> |
| |
| </body> |
| |
| </html> |