You can declare, migrate, and populate databases that the Lotus® Expeditor Client applications used by your organization 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 also migrate the database. Database interaction is broken down into three types of tasks: create, migrate, and populate. Create
tasks run first and typically 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 typically 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 have multiple versions. 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. Because the schemas are applied sequentially, successive versions of schemas contain only the changes 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 are not removed from the platform because 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. Because this application is a new application and a new database definition, users using this application apply schema 1.0 to the database. Later, an application update is required and schema version 2.0 is deployed. Existing users apply only schema version 2.0 to the database because they have already applied version 1.0. Because 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, applies version 1.0 first (because the database has not been created) and then version 2.0.
With the Lotus Expeditor Client, 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 involve using the Lotus Expeditor Client 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 default Derby database of the platform, you must implement this extension. After the extension is implemented, users of the platform can access the provided database using 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 the schema of a specific database vendor, but form the logical unit of a database that undergoes life cycle events. Each schema is versioned independently, and can 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 custom applications to connect a database provider with associated schemas to manage the life cycle of the data source. If declared, the data source is created and associated with a ManagedDatasourceObjectFactory. From this data source, an instantiated version of the Datasource object can be retrieved from JNDI using 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 might 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 provide 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 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 might 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 table references. If the configuration of the default datasource is not suitable, then you 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 updates and migrates your schema after the managed data source is accessed. As an administrator, you are expected to 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 sequence:
- Administrator deploys a managed data source jdbc/MyDataSource with schema version 1.0.
- Developer uses the jdbc/MyDataSource but finds later 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 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 ensure that the managed data sources are at a state in which developers want them.
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 deployment ensures that when the old managed data source is updated, developers do not see any problems. It is important to interact with a developer during this testing period to ensure that the developer understands what managed data sources are used in testing and production.
Security considerations for managed data sources
Depending on the managed data source definition, the data source can 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 might be inaccessible because 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 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 about accessing the Secure KeyStore.
When testing managed data sources and working with new managed data sources, you might 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 that you have been working with and to start from a clean slate. IBM® 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 deletion effectively clears the cache that the managed data source uses for its databases and schemas. After this step is completed, you effectively start with a fresh system that acts as if no managed data sources have been accessed yet. This series of steps can be useful when testing new managed data sources before deploying them. If troubles arise from testing managed data source, look at the logs for important error information.
Parent topic: Extending the platform: XPD622
Defining a managed data source: XPD622
Defining an encrypted managed data source: XPD622
Defining an encrypted managed data source with authentication: XPD622
Defining a database: XPD622
Defining a database schema for initial population using a database task: XPD622
Defining a database provider: XPD622
Migrating a managed data source to a new schema: XPD622