You can declare, migrate, and populate databases that your organization's Lotus® Expeditor applications access using the Database Life Cycle Management component.
The Database Life Cycle Management component allows Lotus Expeditor Client applications to interoperate with a relational database. As administrator, you can specify the required database structure (schema) and then populate the database before client access. You can migrate the database as well. Database interaction is broken down into three type of tasks: create, migrate, and populate. Create
tasks run first and usually contain instructions that are responsible for creating tables in a database. Migrate
tasks run after the create tasks and are responsible for migrating any data that currently exists in the database.Populate
tasks run last and usually contain instructions that are responsible for populating the database with new data. If one of these tasks fails, an error message is logged and the data source is not accessible.
An advantage of using the schemas is that they are versioned. If multiple schema versions are deployed on the system, the schemas are applied sequentially based on the version. For example, if you deploy both a 1.0 version and 2.0 version of the schema, the 1.0 schema tasks run first, followed by the 2.0 schema tasks. Since the schemas are applied sequentially, successive versions of schemas should contain only the deltas from the previous versions. For example, if schema version 1.0 creates table TABLE1
in the database, then schema version 2.0 does not need to create table TABLE1
because it was already created by schema version 1.0. Prior schema versions should not be removed from the platform, since they might need to be applied by new users on the platform.
Consider the following scenario. An application is initially deployed and uses schema version 1.0. Since this is a new application and a new database definition, users using this application will apply schema 1.0 to the database. Later, an application update is required and schema version 2.0 is deployed. Existing users will only apply schema version 2.0 to the database, since they have already applied version 1.0. Since version 1.0 is already deployed, the instructions in schema version 2.0 do not need to repeat version 1.0 instructions. A new user, however, will apply version 1.0 first (since the database has not been created) and then version 2.0.
With the Lotus Expeditor, a database can be a specific instance of any type of SQL database, tabular data source, spreadsheet, or flat file that can provide access to its content using a JDBC-compliant driver.
The steps involved in defining data sources involves using the Lotus Expeditor Toolkit with extension point schemas. Extensions are the key mechanism that a plug-in uses to add new features to the platform. Extensions cannot be arbitrarily created. They are declared using a clear specification defined by an extension point. Each extension must conform to the specification of the extension point that it is extending Each extension point defines attributes and expected values that must be declared by an extension. This information is maintained in the platform plug-in registry. Extension point providers query these values from the registry, so it's important to ensure that your plug-in has provided the expected information.
Table 1. Database Life Cycle Management Extension points
|com.ibm.rcp.database.core.provider||This extension point allows for the definition of new database providers. If you want to use another database besides the platform's default Derby database, you must implement this extension. Once the extension is implemented, users of the platform may access the provided database via the database provider ID. |
|com.ibm.rcp.database.core.schema||This extension point allows for the definition of schemas. A schema is a set associated create, populate and migrate tasks. Schema definitions do not necessarily correspond to a specific database vendor’s schema, but form the logical unit of a database that undergoes life cycle events. Each schema is versioned independently, and may contain its own set of tasks to maintain its life cycle.|
|com.ibm.rcp.database.core.datasource||This extension point is used to declare a managed data source to the database infrastructure. A managed data source allows your company's custom applications to connect a database provider with associated schemas to manage life cycle of the data source. If declared, the data source will be created and associated with a ManagedDatasourceObjectFactory. From this, an instantiated version of the Datasource object can be retrieved from JNDI, via a context.lookup().|
|com.ibm.rcp.database.core.listener ||This extension point allows your custom applications to define listeners to hook into data sources. Listeners are useful when you want to know the status of operations being applied to their data source. For example, you may want to inform the user of some progress if extensive schema processing on a data source is about to occur.|
For information about declaring extension points, refer to the Platform Plug-in Developer Guide
and to Eclipse ( http://help.eclipse.org/help32/index.jsp
Choosing between datasource types
The Managed Datasource components provides a default managed datasource definition (JNDI name jdbc/DerbyDS) that can be used by all applications. If you want to use the Managed Data Source schema extensions with the default datasource, then you will need to define a virtual datasource whose parentDatasource is the default datasource.
Even if you choose not to use schemas with the default datasource, you may still want to define a virtual datasource so that your application has a consistent, unique name to use to access the managed datasource. If you later choose to use a different database than the default, you can still use the same data source name to access the database, but have the virtual datasource refer to a different parent data source.
The default managed datasource provides for an encrypted database stored within the workspace directory. Multiple applications could share the single instance of the database, by defining schemas within the database to provide unique to the table references. If the configuration of the default datasource is not suitable, then you will need to define a new datasource using the extension. Virtual datasources do not allow you to change the database configuration, such as encryption, or location.
One of the main values of using the Managed Datasource is the definitions of the schemas that can be associated with the virtual or actual datasource definitions. If you choose not to use the schema capability, you can still use the Managed Datasource and create your own code to perform definition, migration, and population tasks.
If you are using managed data sources with schemas, to iteratively update the database, it is recommended that you provide updates in the form of incremented schema versions. The database management life cycle framework will properly update and migrate your schema once the managed data source is accessed. As an administrator, it is expected that you work with the developer that is using the managed data source to make sure that all the data required by the developer is in the managed data source. An example workflow would be this:
- Administrator deploys a managed data source jdbc/MyDataSource with schema version 1.0.
- Developer uses the jdbc/MyDataSource but finds later on that the managed data source needs another table and contacts the administrator.
- The administrator updates the schema to version 2.0 and adds a task to create a new table as the developer requested.
- Developer uses the jdbc/MyDataSource again and finds that the managed data source contains the table.
Proper interactions between an administrator and developer insures that the managed data sources are at a state that developers want them in.
In terms of testing, it is recommended that administrators deploy their updates to a new managed data source for testing before deploying to the original data source. This will ensure that when the old managed data source is updated, developers won't see any problems. It is important to interact with a developer during this testing period to ensure the developer understands what managed data sources should be used in testing and production.
Security considerations for managed data sources
Depending upon the managed data source definition, the data source may use the platform keystore to store password or encryption key information. By associating a particular platform keystore alias with a data source connection attribute, such as a bootPassword
for the Derby managed data source provider, the information can be securely stored within a keystore. Only after the appropriate password is used to unlock the platform keystore, can the database password or encryption key information be obtained.
If the keystore alias is allowed to be created on first access with a random value, it is important to retain both the keystore and the password to the keystore to continue access to the database. If the keystore is no longer accessible, then the database may be completely inaccessible, since the necessary keys are available only in the keystore.
The value associated with the alias needs to remain constant from the initial creation, as the managed data source component does not currently provide a mechanism to change the password or encryption key associated with a database.
If the database needs to be accessed external to the managed data source component, or outside of the Lotus Expeditor runtime, and aliases to the platform keystore are used to contain the password, then applications must first access the keystore to obtain the appropriate values to supply when accessing the database.
Refer to Managing secure keystore
for more information on accessing the Secure KeyStore.
When testing managed data sources and working with new managed data sources, you may find yourself in situations where there were errors due to a bad script or database task. Sometimes it is necessary to clear out managed data sources you have been working with and to start from a clean slate. Lotus Expeditor stores all databases in the workspace directory (mostly under the db directory unless specified otherwise). To start fresh, it is necessary to delete the directory in which the databases you are interested in reside. This will effectively clear out the cache the managed data source uses for its databases and schemas. Once this is completed, you are effectively starting with a fresh system that will act like no managed data sources have been accessed yet. This series of steps can be very useful when testing new managed data sources before deploying them. If troubles arise from testing managed data source, it is recommended to look at the logs for important error information.
Parent topic: Extending the platform: XPD621
Defining a managed data source: XPD621
Defining an encrypted managed data source: XPD621
Defining an encrypted managed data source with authentication: XPD621
Defining a database: XPD621
Defining a database schema for initial population using a database task: XPD621
Defining a database provider: XPD621
Migrating a managed data source to a new schema: XPD621