Jump to: navigation, search

Scout/HowTo/3.8/Write a jdbc connection bundle

< Scout‎ | HowTo‎ | 3.8
Revision as of 10:05, 7 May 2012 by Mvi.bsiag.com (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Wiki Home

Eclipse Scout is shipped with support for the Apache Derby database. When creating a Sql Service (compare the Set up a SQL service step of the minicrm tutorial), you need to define the JDBC driver name as well as the JDBC mapping name. To be able to actually connect to the database you need to include a bundle providing the JDBC driver in your project definition. Bundle org.eclipse.scout.rt.jdbc.derby provides the JDBC driver for Derby (derby.jar) and derby-specific subclasses of AbstractSqlService and AbstractSqlStyle (the derby specific Sql Style).

JDBC drivers for other database engines are available at the Eclipse Marketplace, ready to be included in your Eclipse Scout projects (see the Add JDBC Drivers for Eclipse Scout tutorial).

It is also possible to create your own JDBC connection bundles (in order to support other database engines or if the specific version of the required driver is not provided by the sources above).

You can

  • create a fragment bundle providing the JDBC connector library directly to the host bundle org.eclipse.scout.rt.server
  • create a normal bundle containing the JDBC connector library as well as additional sources which you like to export to other bundles.

Choose the second option if you need specific implementations of AbstractSqlService and AbstractSqlStyle, choose the first option if you don't. Have a look at bundle org.eclipse.scout.jdbc.derby for an example.

Providing JDBC Connector in a Fragment Bundle

In this example we will create a fragment bundle containing the MySQL JDBC connector.

  1. Download the current MySql jdbc driver, e.g. mysql-connector-java-5.1.16-bin.jar
  2. Create a new fragment project in eclipse: File -> New -> Other... (or hit [Ctrl+N])
  3. Choose Plug-in Development -> Fragment Project in the wizard, click 'next'
  4. Choose a project name, e.g. com.example.myproject.jdbc.mysql.fragment
  5. Untick checkbox 'Create a java project', keep the other settings, click 'next'
  6. Fill the 'Properties' section
    1. Set the Version to '5.1.16' (or whatever version of MySql you are using)
    2. Set a name for the fragment, e.g. 'MySql jdbc connector'
    3. Set a Provider (or keep empty)
  7. Fill the 'Host Plug-in' section
    1. Set Plug-in ID to system.bundle (this is important!)
    2. Minimum and maximum version can be left empty
  8. Finish the wizard. A new fragment project is created in your workspace (it should contain a folder META-INF with the MANIFEST.MF file and also a build.properties file)
  9. Create a 'lib' folder in your project: Choose New -> Folder from the context menu of the fragment project
  10. Drag and drop the MySql library to the lib folder
  11. Open the MANIFEST.MF file (double-click). The manifest editor opens, it has multiple tabs (at the bottom). Switch to the Runtime tab.
  12. Add the MySql library to the bundle class path (section 'Classpath' on the right). Use the Add.. button and select the jar file from the lib folder. Save the changes.
  13. Switch to the MANIFEST.MF tab in the manifest editor to see the manifest file in plain text. It should look similar to this:
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Mysql jdbc connector
Bundle-SymbolicName: com.example.myproject.server.jdbc.mysql.fragment
Bundle-Version: 5.1.16
Fragment-Host: org.eclipse.scout.rt.server
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Bundle-ClassPath: lib/mysql-connector-java-5.1.16-bin.jar

You can now add the new fragment to the product dependencies: Open the product configuration file of the server bundle (e.g. com.example.myproject.server -> products -> development, open the .product file) Add the new fragment in the Dependencies tab. Switch to the Overview tab, click the 'Synchronize' link in the 'Testing' section, then click the link to 'Launch an eclipse application in debug mode'.

Providing JDBC Connector in a Bundle (With Additional Sources)

In this example we will create a bundle containing the SQL driver for Microsoft SQL Server. This bundle will also provide the classes AbstractMicrosoftSqlService and MicrosoftSqlStyle which will be exported and can be used in your Eclipse Scout projects.

  • 1. Download the current MS SQL Server JDBC driver (say sqljdbc.jar)
  • 2. Create a plugin project: File -> New -> Other... (or hit [Ctrl+N]) lets say 'org.eclipse.scout.rt.jdbc.mssql2008'.
  • 3. Create the folder 'lib' and put the JDBC driver jar into the folder.
  • 4. Open the file 'META-INF/MANIFEST.MF', the manifest editor opens.
  • 5. Switch to the 'Runtime' tab and add the sqljdbc.jar to the 'Classpath' box.
  • 6. Switch to the 'Dependencies' tab and add 'org.eclipse.scout.rt.server' to the 'Required Plug-ins' box.
  • 7. Switch to the 'MANIFEST.MF' tab and add the line:
Eclipse-RegisterBuddy: org.eclipse.scout.rt.server
  • 8. Create a new class org.eclipse.scout.rt.jdbc.mssql2008.AbstractMicrosoftSqlService (the SQL Service):
public abstract class AbstractMicrosoftSqlService extends AbstractSqlService {
  protected Class<? extends ISqlStyle> getConfiguredSqlStyle() {
    return org.eclipse.scout.rt.jdbc.mssql2008.MicrosoftSqlStyle.class;
  protected String getConfiguredJdbcDriverName() {
    return "com.microsoft.sqlserver.jdbc.SQLServerDriver";
  protected String getConfiguredJdbcMappingName() {
    return "jdbc:sqlserver://[host][:port];DatabaseName=[database]";
  • 9. Create a new class org.eclipse.scout.rt.jdbc.mssql2008.MicrosoftSqlStyle (the SQL Style):
public class MicrosoftSqlStyle extends AbstractSqlStyle {
  public String getConcatOp() {
    return "+";
  public String getLikeWildcard() {
    return "%";
  protected int getMaxListSize() {
    return 1000;
  public boolean isLargeString(String s) {
    return (s.length() > 4000);
  public boolean isBlobEnabled() {
    return true;
  public boolean isClobEnabled() {
    return true;
  public String createDateTimeIsNow(String attribute) {
    return "TRUNC(" + attribute + ", 'MI')=TRUNC(SYSDATE, 'MI')";
  public String createDateTimeIsNotNow(String attribute) {
    return "TRUNC(" + attribute + ", 'MI')!=TRUNC(SYSDATE, 'MI')";
  public void testConnection(Connection conn) throws SQLException {
    Statement testStatement = null;
      try {
        testStatement = conn.createStatement();
        testStatement.execute("SELECT count(1) FROM dbo.sysobjects");
      finally {
        if (testStatement != null) try {
        catch (Throwable t) {
  • 10. Open the manifest editor again. Switch to the 'Runtime' tab. Add the package which contains the two created classes to the exported packages.
  • 11. Open the '*.product' files of your server bundle. Switch to the 'Dependencies' tab and add the created plugin org.eclipse.scout.rt.jdbc.mssql2008. (If you do not need the derby sql service you can remove the bundle org.eclipse.scout.rt.jdbc.derby from the dependencies).
  • 12. Switch to the Scout perspective and create a new SqlService: server/Common Services/Sql Services. Use AbstractMicrosoftSqlService as a super type.
  • 13. Override the getConfiguredJdbcMappingName method and replace <servername> and <port>. If username and password are required, override the methods getConfiguredUsername and getConfiguredPassword.

Bundles, Fragments and Class Loading

The above two examples take care to allow the bundle org.eclipse.scout.rt.server to load the JDBC driver class provided by the external jar library. The Eclipse Scout server bundle explicitly loads the JDBC driver in class SqlConnectionBuilder through a method call to Class.forName(String). This call will fail if the JDBC driver class is not available in the bundle classpath. The first example works because a fragment's bundle classpath is directly added to the host bundle. The second example works because of the equinox-specific buddy classloading mechanism. for more information about buddy classloading, see: Context Class Loader Enhancements.