#
Data Source UI Extension point

###### Identifier:

org.eclipse.birt.report.designer.ui.odadatasource

###### Since:

1.0

###### Description:

The data source extension allows providers to add their own type of data source support to the BIRT designer.
The extension can optionally provide the following implementations for the data source.
1) A wizard for creating the data source
2) A set of pages for editing the data source
3) A list of data sets that this data source supports
For each data set that is defined, it can optionally provide
1) A wizard for creating the data set.
2) A set of pages for editing the data set.

###### Configuration Markup:

<!ELEMENT extension (odaDataSourceUI , odaDataSetUI+)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

Data Source Extension point

<!ELEMENT odaDataSourceUI (newDataSourceWizard? , dataSourceEditorPage*)>

<!ATTLIST odaDataSourceUI

id CDATA #REQUIRED>

This extension allows providers to add support for a new data source. It defines child elements for the data source wizard, one or more editor pages and for data sets that this data source supports.

- id - The fully qualified name of this data source type.
  This has to be the same as defined in the ODA extension for the same driver.

<!ELEMENT newDataSourceWizard EMPTY>

<!ATTLIST newDataSourceWizard

class CDATA #REQUIRED>

This element provides the wizard class that will allow a BIRT user to create a data source object of this type.

- class - A fully quailfied class name which provides a wizard for creating a new data Source
  This class should be an extension of org.eclipse.birt.report.designer.ui.views.data.wizards.AbstractDataSourceConnectionWizard

<!ELEMENT dataSourceEditorPage EMPTY>

<!ATTLIST dataSourceEditorPage

name CDATA #REQUIRED

path CDATA #IMPLIED

class CDATA #REQUIRED

displayName CDATA #REQUIRED

image CDATA #IMPLIED>

This element identifies an editor page that is to be added to the editor dialog for this data source. The pages are added to the dialog in the order they are defined.

- name - A unique name for this page.
  This identifier should be unique within the dialog. It doesn't need to be globally unique.
- path - The path within the dialog to which this page should be added.
  If it is to be added to the root node then this should just be "/". If it is to be added as a child of some other node then the full path starting with the / and separated by / should be provided.
  For e.g. If the dialog has a node with the id "one" and you wish to add a page with the id "two" under this, then you need to enter the path as "/one". This will add the page with the id "two" under the page with the id "one".
  Note: The page with the id "one" should already have been added before attempting to add page "two".
- class - The fully qualified class name of this editor page. The class should be an implementation of org.eclipse.birt.report.designer.ui.dialogs.properties.IPropertyPage. It can also extend the abstract class org.eclipse.birt.report.designer.ui.dialogs.properties.AbstractPropertyPage.
- displayName - The display name of this page. This is what will be displayed in the dialog.
- image - An image to be shown before the name if any.

<!ELEMENT odaDataSetUI (newDataSetWizard? , dataSetEditorPage*)>

<!ATTLIST odaDataSetUI

id CDATA #REQUIRED>

This element identifies a data set type that is supported by this data source. It provides the New data set wizard and a set of one or more editor pages. A data source can have one or more data sets.

- id - The fully qualified name of this data set.
  This has to be the same as the ODA Data Set extension name for the same driver.

<!ELEMENT newDataSetWizard EMPTY>

<!ATTLIST newDataSetWizard

class CDATA #REQUIRED>

This element provides the wizard class that will allow a BIRT user to create a data set object of this type.

- class - A fully quailfied class name which provides a wizard for Creating a new data set.
  This class should be an extension of org.eclipse.birt.report.designer.ui.views.data.wizards.AbstractDataSetWizard

<!ELEMENT dataSetEditorPage EMPTY>

<!ATTLIST dataSetEditorPage

name CDATA #REQUIRED

path CDATA #IMPLIED

class CDATA #REQUIRED

displayName CDATA #REQUIRED

image CDATA #IMPLIED

initFocus CDATA #IMPLIED>

This element identifies an editor page that is to be added to the editor dialog for this data set. The pages are added to the dialog in the order they are defined.

- name - A unique name for this page.
  This identifier should be unique within the dialog. It doesn't need to be globally unique.
- path - The path within the dialog to which this page should be added.
  If it is to be added to the root node then this should just be "/". If it is to be added as a child of some other node then the full path starting with the / and separated by / should be provided.
  For e.g. If the dialog has a node with the id "one" and you wish to add a page with the id "two" under this, then you need to enter the path as "/one". This will add the page with the id "two" under the page with the id "one".
  Note: The page with the id "one" should already have been added before attempting to add page "two".
- class - The fully qualified class name of this editor page. The class should be an implementation of org.eclipse.birt.report.designer.ui.dialogs.properties.IPropertyPage. It can also extend the abstract class org.eclipse.birt.report.designer.ui.dialogs.properties.AbstractPropertyPage.
- displayName - The display name of this page. This is what will be displayed in the dialog.
- image - An image to be shown before the name if any.
- initFocus - An boolean string indicates whether this page needs to be focused.

###### Examples:

The following is an example of the JDBC data source extension.

    <extension point="org.eclipse.birt.report.designer.ui.odadatasource">
      <odaDataSourceUI id="org.eclipse.birt.report.data.oda.jdbc">
        <newDataSourceWizard class="org.eclipse.birt.report.data.oda.jdbc.ui.wizards.JdbcDataSourceWizard"/>
          <dataSourceEditorPage
                class="org.eclipse.birt.report.data.oda.jdbc.ui.wizards.JdbcDataSourcePage"
                path="/"
                displayName="%datasource.editor.page.connection"
                name="org.eclipse.birt.report.data.oda.jdbc.ui.data-source-editor.connection"/>
      </odaDataSourceUI>
      <odaDataSetUI id="org.eclipse.birt.report.data.oda.jdbc.JdbcSelectDataSet">
        <dataSetEditorPage
                class="org.eclipse.birt.report.data.oda.jdbc.ui.editors.SQLDataSetEditorPage"
                path="/"
                displayName="%dataset.editor.page.query"
                name="org.eclipse.birt.report.data.oda.jdbc.ui.data-set-editor-page1"/>
      </odaDataSetUI>
    </extension>

###### API Information:

The new data source wizard should extend the org.eclipse.birt.report.designer.ui.odadatasource.wizards.AbstractDataSourceConnectionWizard class.
The new data set wizard should extend the org.eclipse.birt.report.designer.ui.odadatasource.wizards.AbstractDataSetWizard class
The editor pages should be an implementation of org.eclipse.birt.report.designer.ui.dialogs.properties.IPropertyPage. They can also extend from the abstract class org.eclipse.birt.report.designer.ui.dialogs.properties.AbstractPropertyPage.

###### Supplied Implementation:

An abstract implementation of `org.eclipse.birt.report.designer.ui.dialogs.properties.IPropertyPage` is provided as `org.eclipse.birt.report.designer.ui.dialogs.properties.AbstractPropertyPage`. This class contains get and set methods for the name, the image and the container.
A default JDBC data source implementation plugin is also provided

Copyright (c) 2005 Actuate Corporation. 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 http://www.eclipse.org/legal/epl-v10.html
Contributors: Actuate Corporation - initial API and implementation