$Author: bastafidli $
$Date: 2006/08/31 06:34:08 $
$Revision: 1.13 $
$RCSfile: j2eesetup_weblogic.html,v $
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 9.1 is a popular commercial application server developed by BEA Corp. It is J2EE 1.4 certified and used by many commercial clients.
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
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.
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
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
where domain_name is the name of the domain you are using. Modify line at the very end of each file starting with
in the .cmd file and
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:
DO NOT place your JDBC driver into directory
Even though the test of the connection when defining data source will succeed, the data source deploy to the target server will fail.
Next configure settings
required to access your database. You have to copy the default
OpenSubsystems configuration file
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:
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
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
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
This is because if no other datasource name is specified in the requestConnection or setDefaultDataSourceName methods of
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
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.
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
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
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
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
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
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
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
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
and start the server again. WebLogic will deploy and start you application automatically when it starts.
WebLogic 9.1 is affected by following defects in WebLogic code:
|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().|