OpenSubsystems

This document will help you get started with WebLogic application server supported by OpenSubsystems. It will walk you through obtaining, installing and configuring the application server so that it can be used to run OpenSubsystems components and applications. It also describes how OpenSubsystems can integrate with and utilize transaction manager and connection pools provided by the application server to access your databases.

WebLogic Application Server

Official page | Download | Documentation
Tested version: WebLogic Application Server 9.1

WebLogic Application Server 9.1 is a popular commercial application server developed by BEA Corp. It is J2EE 1.4 certified and used by many commercial clients.

Installation

Download the trial installation package from the WebLogic Application Server download page. Start the installation by launching the downloaded installation file. Follow the easy to use installation wizard to install the application server on your system. We recommend to perform the complete installation to make sure all the necessary functionality is available.

After the installation is finished, you will have to create WebLogic server domain, which can be then used to develop and deploy applications. The domain can be created quickly and easily using configuration template that provides domain configuration information as an input to the Configuration Wizard. The Configuration Wizard is a stand-alone application that can be run independently of WebLogic Server to simplify the creation of domains. Start the Configuration Wizard using shortcut in the Windows Start menu, that can be accessed by navigating folders

BEA Products -> Tools -> Configuration Wizard

Once the wizard starts, leave selected all the default options and proceed through the pages of the wizard entering on the way your desired administration username and password and a domain name. Once the domain is created you are ready to start using the WebLogic application server.

Database Configuration

JDBC driver

Before you can use OpenSubsystems with WebLogic you will have to configure the persistence layer so that OpenSubsystems can access your database. Copy the JDBC driver for the database you want to use into directory

[WEBLOGIC_ROOT]/weblogic91/server/ext/jdbc

folder, where WEBLOGIC_ROOT symbolizes the directory where WebLogic application server is installed. You should have this driver available if you have followed the Database Setup instructions. Next modify files

[WEBLOGIC_ROOT]/user_projects/domains/[domain_name]/bin/setDomainEnv.cmd

and

[WEBLOGIC_ROOT]/user_projects/domains/[domain_name]/bin/setDomainEnv.sh

where domain_name is the name of the domain you are using. Modify line at the very end of each file starting with

set CLASSPATH=...

in the .cmd file and

CLASSPATH=...

in the .sh file. At the very end of the line add the full path to your JDBC driver. For example when using jTDS driver in Windows environment, this line will look like this:

                  
   set CLASSPATH=%PRE_CLASSPATH%;%WEBLOGIC_CLASSPATH%;%POST_CLASSPATH%;%WLP_POST_CLASSPATH%;%WL_HOME%\integration\lib\util.jar;C:\bea\weblogic91\server\ext\jdbc\jtds.jar                  
               

DO NOT place your JDBC driver into directory

[WEBLOGIC_ROOT]/user_projects/domains/[domain_name]/lib

Even though the test of the connection when defining data source will succeed, the data source deploy to the target server will fail.

OpenSubsystems

Next configure settings required to access your database. You have to copy the default OpenSubsystems configuration file oss.properties into directory

[WEBLOGIC_ROOT]/user_projects/domains/[domain_name]/lib

Once the OpenSubsystem configuration file is in place, make sure that the uncommented database related settings in this file match the database you want to use. If you decide to use third party transaction manager or connection pool supported by OpenSubsystems, uncomment them in the configuration file as well. If all the connection pools and transaction managers supported by OpenSubsystems are commented out OpenSubsystems will detect if it is running inside of J2EE server and it will use the transaction management and connection pooling capabilities provided by WebLogic as part of the J2EE implementation.

You will have to modify property oss.datasource.admindatasource and make sure its value is set to true. This is due to the fact that WebLogic doesn't propagate requested user credentials to the JDBC drivers and therefore OpenSubsystems has to use separate data source for administration tasks. The property will look like this:

   oss.datasource.admindatasource=true               
               

The critical step is that once you are done with changing the OpenSubsystems configuration file, you have to compress it to a file with .jar extension. You can do it by first creating a .zip file (e.g. ossproperties.zip) using WinZip, 7-Zip, Windows built-in compression or other similar tool and then rename this file so that it has .jar extension (the final name will be e.g. ossproperties.jar). You can achieve the same effect by opening command prompt in directory

[WEBLOGIC_ROOT]/user_projects/domains/[domain_name]/lib

and executing one of the following commands:

   [WEBLOGIC_ROOT]\jdk150_04\bin\jar cvf ossproperties.jar oss.properties
               

where you need to substitue the actual WebLogic installation directory instead of [WEBLOGIC_ROOT]. The other option (assuming you have followed the Development Environment setup instructions) is to execute

   
   %JAVA_HOME%\bin\jar cvf ossproperties.jar oss.properties
               

Data source

If the WebLogic connection pool is being used you have to configure WebLogic data source that matches the database enabled in the configuration file. The entire configuration can be done from the Admin Server console, which is running on top of WebLogic application server. Start the server using shortcut in the Windows Start menu, which can be accessed by navigating folders

BEA Products -> User Projects -> [domain name] -> Start Admin Server for Weblogic Server Domain

Next start the Admin Server Console using another Windows Start menu shortcut

BEA Products -> User Projects -> [domain name] -> Admin Server Console

Once you login to the Administration console, click the Lock and Edit button in the upper left corner of the console. The server is now ready to accept configuration changes. Expand the Services and JDBC nodes in the Domain Structure menu on the left side of the console and click on the Data Sources link. Click on the New button and on the Create a New JDBC Data Source dialog enter OSSDS as the data source name and in the JNDI Name field enter value

OSSDS

This is because if no other datasource name is specified in the requestConnection or setDefaultDataSourceName methods of

org.opensubsystems.core.persist.db.DatabaseConnectionFactory

interface the default connection pool is always looked up for OSSDS JNDI datasource name. If your application sets different default datasource name, adjust this property accordingly.

Select Database Type and Database Driver that correspond to your database. Unfortunately WebLogic doesn't allow you to define database, which is not supported by the server directly. You may need to trick it by selecting for example PostgreSQL and selecting Other as your database driver. You need to select Other as your database driver also in a case when you want to use JDBC driver currently not supported by WebLogic application server directly, e.g. jTDS driver for MS SQL Server. In this case you have had to already copy the driver into appropriate directory as described earlier. Click on the Next button and if asked configure Transaction Options. If you do not know what kind of transactions your driver supports, check the Supports Global Transactions checkbox and select the Emulate Two-Phase Commit. Do not select the Logging Last Resource option since if the server cannot for whatever reason connect to the database when starting it will not start and will shutdown automatically effectively disabling any reconfiguration since the Administration console cannot be accessed. Click on the Next button to confirm your selection and proceed to the next page.

The connection properties you are asked to configure on this page must match the values in the OpenSubsystems configuration file you have setup previously and the database you intend to use. Once you click the Next button and you have earlier chosen to use your own JDBC driver you will be asked to enter driver class name and url, which you can again find in the uncommented section of the OpenSubsystems configuration file.

Now the critical step is to specify the user name to use to connect to the database also using the Properties. This is due to the fact, that WebLogic doesn't propagate the user name you have entered earlier to the JDBC driver and without this setting, the driver wouldn't know how to connect to the database. The user name property is listed in the OpenSubsystems configuration file comments in the section for your database and JDBC driver. For example when using jTDS driver your Properties need to look similar to this

   user=basta
               

otherwise when deploying the datasource you will receive error

   I/O Error: SSO Failed: Native SSPI library not loaded. Check the java.library.path system property.
               

Before completing the configuration you can test the connection by entering test table name and then clicking on the Test Configuration button. Do not get confused if the Test Connection succeed even if you do not specify the Properties mentioned above. WebLogic is using the actual user name you have entered earlier during connection test but ignores it afterwards. The connection test will of course succeed only if you have manually created the user you have specified earlier. If the specified user doesn't exist you may receive an error message, e.g.

   Connection test failed.  
   Login failed for user 'basta' 
               

which is still a good sign, signaling that WebLogic tried to connect to the specified database and the database properly refused the connection. You may safely ignore this error since OpenSubsystems will create the configured user when it tries to access the database for the first time. When done testing click on the Next button and on the Select Targets page select all the available servers. The data source creation will be complete once you click the Finish button.

If the user you have configured for the datasource doesn't exist you have to click on the data source name name in the list of available data sources to adjust the connection pool configuration. Once the Settings for OSSDS data source dialog is displayed, click on the Connection Pool link and adjust the Initial Capacity to 0. This will ensure that WebLogic will not try to connect to the database until it is asked after the user was created by OpenSubsystems. Save the dialog by clicking on the Save button. Now go back to the Data Sources list and create another data source called OSSADMDS with JNDI name OSSADMDS using the adminuser and adminpassword settings from the OpenSubsystems configuration files (or your database administration and password if it differs, which you should know if you have followed the Database Setup instructions. Do not forget to specify the adminiuser name in the Properties section. This data source will be used by OpenSubsystems to create the user you have configured for the default data source as well as configure all the required database objects.

You will complete and save all the configuration changes you have made so far by clicking on the Activate Changes button in the upper left corner of the Administration console.

Server Configuration

OpenSubsystems logs lots of useful information to troubleshoot problems during development. If you want to change the details of what is being logged you need to copy the OpenSubsystems logging configuration file osslog.properties into directory

[WEBLOGIC_ROOT]/user_projects/domains/[domain_name]/lib

where you have already previously copied the default OpenSubsystems configuration file oss.properties. Now you can open the logging configuration file in your favorite editor and adjust its settings to match your needs. As you have done before, you will need to compress this file into a .jar file before WebLogic makes these settings available to OpenSubsystems.

WebLogic stores all its activity in the log files, which are very handy during the troubleshooting of problems with your application or subsystems. All the logs are by default located in directory

[WEBLOGIC_ROOT]/user_projects/domains/[domain_name]/servers/[server_name]/logs

where [server_name] is the name of the server you are using (the default server name is called 'AdminServer').

Ability to debug applications or subsystems running inside of WebLogic application server is essential during the development and the testing phase. To enable this capability you have to setup several properties required by WebLogic. These properties can be modified by changing the files setDomainEnv.cmd and setDomainEnv.sh mentioned earlier. Open these files in your favorite editor and at the beggining of the .cmd file insert line

   set debugFlag=true
               

and at the beggining of the .sh file insert lines

   debugFlag="true"
   export debugFlag
               

To adjust setting for remote debugger, search in each file for

DEBUG_PORT=

and

JAVA_DEBUG=

and change the configuration to match your needs. For more information about particular options read the Java application launcher documentation. You can use Eclipse IDE to debug application running under WebLogic that was started in the debug mode. Follow the Debugging Remote Application guide for step by step instructions to configure your environment.

Any change to the configuration mentioned in this section requires restart of the application server

Deploying Application

The last step is to deploy your application to WebLogic application server. In the Administration console click the Lock and Edit button in the upper left corner of the console. The server is now again ready to accept configuration changes. Click on the Deployments link in the menu on the left. Once the Summary of Deployments page loads, click on the Install button and on the next page click the upload your files(s) link. On the next page click the Browse button next to Deployment Archive field and locate the war or ear file for the OpenSubsystems-based application or subsystem you want to deploy. Remember the name of the file you are deploying, since the application or subsystem deployed using file [applicationname].ear or [applicationname].war can be by default accessed using url

http://localhost:7001/[applicationname]/

once the application is deployed and started. If you are deploying one of the default OpenSubsystem demo applications with names such as [subsystemname].ear, [subsystemname].war, [subsystemname]-app.ear or [subsystemname]-app.war, the default url is

http://localhost:7001/[subsystemname]/

Click on the Next button then select the radio button next to the application and click the Next button again. When asked to choose the targeting style, select to install this deployment as an application and click the Next button twice. Once you review your choices start the installation procedure by clicking the Finish button.

Complete and save all the configuration changes you have made so far by clicking on the Activate Changes button in the upper left corner of the Administration console. Next click on the Deployments link and in the Summary of Deployments select the checkbox next to your application. Click on the Start button and select the Servicing all requests item. Confirm the request and verify that once the page is refreshed the state of the application is Active.

Once the application is started, you can access it by copying the URL http://localhost:7001/[applicationname]/ to your browser address bar and modify it to reference your application.

If during development cycle you want to update your application quickly, you just have to shutdown the server, copy the new version of the application to directory

[WEBLOGIC_ROOT]/user_projects/domains/[domain_name]/servers/[server_name]/uploac

and start the server again. WebLogic will deploy and start you application automatically when it starts.

Defects

WebLogic 9.1 is affected by following defects in WebLogic code:

ID	Description	Workaround
1491821	WebLogic doesn't enroll Connection requested before transaction in the transaction.	Always use only connections that are acquired within a transaction, that is after the call to UserTransaction.begin().