Creating your own database plug-in

If you want to develop a plug-in to support your own database, you can create one based on the wasdb2 plug-in.

The wasdb2 plug-in includes parts for connections with an existing DB2® or Informix® database. It also supports connections with a pattern-deployed DB2 database, meaning a virtual machine that is running DB2 is deployed in the same virtual application as the one running IBM® WebSphere® Application Server. You can choose to include either or both implementations in your custom plug-in.

For a pattern-deployed database, there are two virtual machines, one running WebSphere Application Server with the user's application, and the other running DB2 to manage data for the application. In the existing database case, the database is already up and running on another system, either in the cloud, as a shared service, or outside the cloud that is managed by Cloud Pak System Software for Power®. In either case, WebSphere Application Server needs to have the IP address, port number, database name, and database credentials (user ID and password) to connect to the database. In the application model, the WebSphere Application Server node and the database node are modeled as components. The link between them in the application model represents the connection between them, and provides the foundation for this data transfer of required access information.

Pattern-deployed database connection

Roles provide capabilities to orchestrate application startup, lifecycle management, and undeployment. For a database deployed with the IBM Web Application Pattern, a WebSphere Application Server role manages and interacts with WebSphere Application Server instance deployed on its node, and a DB2 role interacts with the DB2 instance deployed on its node. The wasdb2 plug-in provides a link between the WebSphere Application Server and DB2 components. It inserts a dependency of the WebSphere Application Server role on the DB2 role in the topology document. At the start of the deployment, when both the WebSphere Application Server and DB2 roles change to the RUNNING state, the WAS/DB2/changed.py script runs. The DB2 role lifecycle scripts export DB2 characteristics, like the host name/IP address, port number, database name, user ID, and password that are required to use the DB2 database on this deployed instance. The WAS/DB2/changed.py script gets this exported data, and passes the values into wsadmin scripts to configure the information so that applications in the WebSphere Application Server node can access the database.

Roles can also contribute operations to the deployment inlet. These operations can be used to modify the running deployment. For example, you can change the password of your DB2 database. The DB2 plug-in offers this operation, which changes the database password and exports this changed data. The WAS/DB2/changed.py script is notified on this update, and invokes a wsadmin script to update the changed password in the WebSphere Application Server instance that is using the database.

Existing database connection

Web Application Pattern supports connecting to two existing database types: DB2 or Informix. It uses a role for each: xDB2 and xInformix. These roles work like the DB2 role that is used for a pattern-deployed database. An application model component is available on the Pattern Builder pane for each type of database, with host name/IP address, port number, database name, and user ID and password attributes. These values are specified at virtual application design time. A link transform makes the WebSphere Application Server role dependent on these roles for existing databases. The xDB2 role start.py script exports the values that are specified in xDB2 component on the Pattern Builder pane, by using the same mechanism and key names as the DB2 role. The existing database roles offer configuration settings and deployment inlet change operations to dynamically change these configuration values just like the DB2 role. As with a pattern-deployed DB2 database, WAS/xDB/changed.py scripts get the exported xDB values (IP address, port number, database name, user ID, and password) and invoke appropriate WebSphere Application Server configuration scripts so that the applications on the WebSphere Application Server node can access the database.

Two attributes can be added to dependent roles.
"asDependency" : "DB"
Normally, each dependent role provides its own dependent role scripts. The wasdb plug-in provides these scripts for all databases, and they are delivered as WAS/DB scripts. While the topology document has the WebSphere Application Server role, which is dependent on the appropriate DB role (DB2, xDB2, or xInformix), the "asDependency" attribute maps all dependent role script calls to WAS/DB, for example for changed.py. Database-dependent information, unique to each database, is passed to the wasdb link in a dblink_metadata JSONObject.
"localOnly" : true
This attribute is used in the existing resource or surrogate role cases to indicate that this role is local to the WebSphere Application Server node. It is especially important with scaling to invoke WAS/DB/changed.py only once per local WebSphere Application Server node. The next section describes surrogate roles.
The wasdb plug-in contributes a WASDB link to the Web Application Pattern pattern type. The source component is a WebSphere Application Server node (vm-template). The target component is a JSONObject with two elements:
dblink_metadata (required
A JSONObject with two elements:
packages (optional)
A JSONArray of package names to be installed on the WebSphere Application Server node. The packages are added in the usual way to the $sourcePackages variable in the wasdb_link.vm velocity template.
parms (required)
The database-specific parameters that are required by the scripts to configure Web Application Pattern to connect to the database
role (optional)
The role to insert into the WebSphere Application Server template. It is also made a dependent role to the WebSphere Application Server role in the source WebSphere Application Server template, as is usual in Velocity template link transforms. The role element is used in the existing database case, for xDB2 or xInformix.

A pattern-deployed database does not need an extra role. It uses the DB2 role for the WebSphere Application Server role to depend on. A targetRole parameter is included in the dblink_metadata parms element for a pattern-deployed database. Its value is the name of the pattern-deployed DB role of the dependency added to the WebSphere Application Server role.

Using a surrogate role

The surrogate role is an option if your database pattern deployment plug-in does not provide a role that closely mimics the DB2 role, or the data it exports does not use the same names as the DB2 role and our xDB roles. A surrogate role is added to reflect status and changes in the target database role back to the wasdb plug-in in the manner it expects. For example, a database that is called DB3 has a DB3 role, that we want to use with our wasdb plug-in. We create a role, DB3Surrogate, that depends on the DB3 role. It has a DB3Surrogate/DB3/changed.py script that gets changed, exported data from DB3. The WebSphere Application Server role is dependent on the DB3Surrogate role, which exports changed data from DB3, convert it to names and formats that are expected by wasdb, and export it in names wasdb expects. To realize this configuration with WASDB link, targetRole in dblink_metadata parms would be DB3, and the DB3Surrogate role would be passed in as the role element.