How Do I: WebLogic Workshop-Enable an Existing WebLogic Server Domain?

WebLogic Workshop applications require that the domain in which they are deployed include the WebLogic Workshop runtime components. This topic describes how to modify the configuration of an existing WebLogic Server domain so that it can host WebLogic Workshop web services.

If you want to create a new domain, see How Do I: Create a New WebLogic Workshop-enabled WebLogic Server Domain?

WebLogic Workshop-Enabling a WebLogic Server 8.1 Domain

To enable the WebLogic Workshop runtime in an existing WebLogic Server 8.1 domain that you created with the WebLogic Server 8.1 Configuration Wizard, you may use the Configuration Wizard and extend the domain using a Workshop-enabled template. The Configuration Wizard can add the WebLogic Workshop Extension to any WebLogic Server 8.1 domain. To learn more about the Configuration Wizard, see How Do I: Create a New WebLogic Workshop-Enabled WebLogic Server Domain?

WebLogic Workshop-Enabling an Earlier WebLogic Server Domain

If you have a WebLogic Server domain that you did not create with the WebLogic Server 8.1 Configuration Wizard, you can enable the WebLogic Workshop runtime components in this WebLogic Server domain by completing the following steps. Each of these steps is described in greater detail in subsequent sections in this topic:

  1. Configure a collection of resources in the target domain. See the Configuring WebLogic Server Resources section, below.
  2. Create and configure the jws-config.properties file in the target domain to refer to this collection of resources. See the Setting WebLogic Workshop Properties section, below.
  3. Make changes to the WebLogic start script(s) to set appropriate Java classpaths, and start a database server to manage WebLogic Workshop runtime information. See the Editing the Start Script section, below.
  4. Create a database used to store WebLogic Workshop runtime information. See the Creating the Runtime Database section, below.
  5. If you have existing web applications that you want to use in the WebLogic Workshop-enabled domain, see Configuring Web Applications.

Note: The steps above have been tested in a new "WLS Domain" created with the Domain Configuration Wizard.

Configuring WebLogic Server Resources

In order for a WebLogic Server 8.1 domain to be able to host WebLogic Workshop applications, the domain must be configured with the resources described in the following sections, including a connection pool, a conversation data source, a sample data source, a JMS data store, a JMS server, and a JMS Connection Factory.

These resources may be configured using the WebLogic console (recommended) or by editing the domain's config.xml file directly. You can learn more about configuring WebLogic Server on http://www.oracle.com/technology/documentation/index.html at Creating and Configuring WebLogic Server Domains. The instructions below assume you are configuring these resources from the WebLogic console.

Note: The cg prefix is used in all resource names in the steps below. You may name the resources anything you wish, but using a common prefix can help you subsequently identify resources as a group.

Configuring a Connection Pool

A JDBC connection pool must be configured to support JDBC data sources used by the WebLogic Workshop runtime. The default database used to store this runtime information is the PointBase database that is shipped with the WebLogic platform.

From the WebLogic Server console home page, select Connection Pools under Services Configurations, JDBC, and on the next page select Configure a new JDBC Connection Pool:

For more information on how to configure a connection pool, see Configuring and Managing JDBC Connection Pools, MultiPools, and DataSources Using the Administration Console at http://www.oracle.com/technology/documentation/index.html, or you click the help icon in the WebLogic Server console. You can also find more instructions at How Do I: Configure WebLogic Workshop to Use a Different Database for Internal State?

Configuring a Conversation Data Source

A JDBC data source must be configured to support persistence of web service conversation state. The data source must be a JDBCTxDataSource (a transacted data source). From the WebLogic Server console home page, select Data Sources under Services Configurations, JDBC, and on the next page select Configure a new JDBC Data Source:

For more information on configuring a data source, see Configuring and Managing JDBC Connection Pools, MultiPools, and DataSources Using the Administration Console at http://www.oracle.com/technology/documentation/index.html, or you can click the help icon in WebLogic Server console for detailed instructions. You can also find more instructions at How Do I: Configure WebLogic Workshop to Use a Different Database for Internal State?

The name of the data source must also be specified as the value of the weblogic.jws.JMSControlDataSource property in the jws-config.properties file, as described below in Setting WebLogic Workshop Properties.

Note: A single conversational database table may be shared by multiple applications and servers because values for the conversation ID (stored in the CG_ID column) will be globally unique. System-generated values for CG_ID will be unique; values supplied by application code must also be unique, or there may be unexpected results. See How Do I: Deploy a WebLogic Workshop Application to a Production Server? for more specific information on database schema.

Configuring a Sample Data Source

This configuration step is optional. When a Database control is created in the WebLogic Workshop visual development environment, the control will default to using a JDBC data source named cgSampleDataSource. If you want new Database controls created in the visual development environment to function without modification, you should configure a JDBC data source with the JNDI name cgSampleDataSource. To create this data source, follow the same procedure as above for the Conversation Data Source.

Configuring a JMS Data Store

A JMS JDBC data store must be configured to support state persistence by JMS controls. From the WebLogic Server console home page, select Stores under Services Configurations, JMS, and on the next page select Configure a new JMS JDBC Store. Provide a unique name for the data store and associate it to the connection pool you created.

You can learn more about configuring a JMS JDBC data store on http://www.oracle.com/technology/documentation/index.html at Create a JMS JDBC Store, or you can click the help icon in WebLogic console.

The name of the JMS store must also be specified as the value of the weblogic.jws.JMSControlDataSource property in the jws-config.properties file, as described below in Setting WebLogic Workshop Properties.

Configuring a JMS Server

A JMS server must be configured to support message buffers, timer controls, JMS controls and JMS as a web service message transport. From the WebLogic Server console home page, select Servers under Services Configurations, JMS, and on the next page select Configure a new JMS Server. Enter a unique name for the server on the first page and associate it to the target server on the next page.

You can learn more about configuring WebLogic JMS servers on http://www.oracle.com/technology/documentation/index.html at Configuring WebLogic JMS, or you can click the help icon in WebLogic console.

The name of the JMS server must also be specified as the value of the weblogic.jws.InternalJMSServer property in the jws-config.properties file, as described below in Setting WebLogic Workshop Properties.

Configuring a JMS Connection Factory

A JMS connection factory must be configured to provide JMS connections. From the WebLogic Server console home page, select Connection Factories under Services Configurations, JMS, and on the next page select Configure a new JMS Connection Factory:

You can learn more about configuring WebLogic JMS connection factories on http://www.oracle.com/technology/documentation/index.html at Configuring WebLogic JMS, or you can click the help icon in WebLogic console.

The name of the JMS connection factory must also be specified as the value of the weblogic.jws.InternalJMSConnFactory property in the jws-config.properties file, as described next.

Setting WebLogic Workshop Properties

The resources defined in the previous sections are referred to from the WebLogic Workshop configuration file jws-config.properties. Create a file named jws-config.properties in the domain directory (the directory that contains config.xml for your domain). In the file, configure the following properties:

weblogic.jws.InternalJMSServer=<name of JMS server configured above>
weblogic.jws.InternalJMSConnFactory=<JNDI name of JMS Connection Factory configured above>
weblogic.jws.ConversationDataSource=<JNDI name of Conversation Data Source configured above>
weblogic.jws.JMSControlDataSource=<Name of JMS JDBC Store configured above>
weblogic.jws.ConversationMaxKeyLength=768

For a complete description of the jws-config.properties file, see jws-config.properties Configuration File.

Editing the Start Script

The following additions must be made to the .cmd start script(s) on Windows hosts or .sh start script(s) on UNIX. The default names of these scripts are startWebLogic.cmd and startWebLogic.sh. Only the Windows version of the procedure is shown. There are several differences you should be aware of when performing these procedures on UNIX:

Paste all of the code fragments described below into you start script between the line containing:

SETLOCAL

and the line containing

@rem Set SERVER_NAME.

Setting Environment Variables

You must define a number of environment variables that will be used by WebLogic Workshop. Replace c:\bea with the directory in which you installed WebLogic (default on Windows is c:\bea).

The following SET commands should each be one line with no spaces. If you cut and paste from this topic, you will need to join lines manually.

set WL_HOME=C:\bea\weblogic81
set BEAHOME=C:\bea
set JAVA_HOME=C:\bea\jdk141_05
set ARDIR=%WL_HOME%\server\lib
REM
REM These commands convert to the windows short form of paths with no spaces.
REM These commands are only necessary on Windows.
REM
for %%i in (%0) do set CONFIGDIR=%%~dpi
for %%i in ("%CONFIGDIR%") do set CONFIGDIR=%%~fsi
pushd %CONFIGDIR%
REM
set PRE_CLASSPATH=%WL_HOME%\common\lib\log4j.jar;%ARDIR%\knex.jar;%ARDIR%\JDIProxy.jar
set POST_CLASSPATH=%PB_CLASSPATH%;%ARDIR%\webservices.jar;%ARDIR%\webserviceclient.jar;
    %ARDIR%\webserviceclient+ssl.jar
REM
REM Augment class path to enable generation of client proxy JAR files using ant
REM
set CLASSPATH=%ARDIR%\ant\ant.jar;%JAVA_HOME%\jre\lib\rt.jar

Specifying WebLogic Workshop Production Mode

WebLogic Workshop may be run in Development Mode or Production Mode. This is not the same as WebLogic Server Development Mode and Production Mode. If you want to support deployed WebLogic Workshop applications (applications built with wlwBuild and deployed to a production server as an EAR file), you must run the target server in WebLogic Workshop Production Mode. To do so, specify the following weblogic.jws.ProductionMode=true property to be used when WebLogic Server is started. You may add this property to the JAVA_OPTIONS variable as shown below (add the bold portion). The quotes are necessary if the variable previously had a single value and will now have more than one.

set JAVA_OPTIONS=
    "-Dweblogic.security.SSL.trustedCAKeyStore=C:\bea\weblogic81\server\lib\cacerts
    -Dweblogic.jws.ProductionMode=true"

Enabling WebLogic Workshop Logging

WebLogic Workshop logging is disabled by default. To enable logging, you must set the log4j.configuration and weblogic.jws.logging Java properties. You can set these properties by adding the line below to the start script. Add this text as a single line, replacing the line breaks below with spaces.

set JAVA_OPTIONS=%JAVA_OPTIONS%
    -Dlog4j.configuration=file:%WL_HOME%\common\lib\workshopLogCfg.xml
    -Dweblogic.jws.logging=true

To learn more about WebLogic Workshop logging, see workshopLogCfg.xml Configuration File.

Enabling WebLogic Workshop Debugging

If you want to use the WebLogic Workshop debugger in this domain,you must modify the server startup command and start the WebLogic Workshop Debugging Proxy.

To modify the server startup command, first set the following variables in the start script:

set DEBUG_PORT=8453
set JAVA_DEBUG="-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=$DEBUG_PORT,server=y,suspend=n -Djava.compiler=NONE"

Then modify the startup command in the start script to include the JAVA_DEBUG argument as shown in bold below:

%JAVA_HOME%\bin\java %JAVA_VM% %JAVA_DEBUG% %MEM_ARGS% %JAVA_OPTIONS% -Dwlw.testConsole=true -Dwlw.iterativeDev=true 
   -Dweblogic.Name=%SERVER_NAME% -Dweblogic.management.username=%WLS_USER% -Dweblogic.management.password=%WLS_PW% 
   -Dweblogic.ProductionModeEnabled=%STARTMODE% -Djava.security.policy="%WL_HOME%\server\lib\weblogic.policy" 
   weblogic.Server

To start the WebLogic Workshop Debugging Proxy, add the line below to the start script. Add the text as a single line, replacing the line breaks below with spaces.

@start "WebLogic Workshop Debugger..." /MIN %JAVA_HOME%\bin\java
    -classpath %PRE_CLASSPATH%;%WL_HOME%\server\lib\weblogic.jar;%JAVA_HOME%\lib\tools.jar
    JDIProxy.DbgMain

Starting the Runtime Database Server with WebLogic Server

WebLogic Workshop requires a database to store web service conversational state and provide a JMS store. The following code should be added to your start script if, in Configuring a Connection Pool above, you decided to use the PointBase database that is installed with WebLogic. If you configured WebLogic Server to use a database other than PointBase, but you must configure analogous resources to those described here.

Note: Depending on the Service Pack level of WebLogic Platform you have installed, the actual names of the PointBase JAR files in the definition of PB_CLASSPATH may be different. Please verify that the JAR files named in PB_CLASSPATH exist in your installation.

The following SET commands should each be one line with no spaces:

set POINTBASEDIR=C:\bea\weblogic81\common
set PB_CLASSPATH=%POINTBASEDIR%\lib\pbserver44.jar;%POINTBASEDIR%\lib\pbclient44.jar

Note: PB_CLASSPATH is referenced in POST_CLASSPATH, defined above. So the definition of POINTBASEDIR and PB_CLASSPATH must occur before the definition of POST_CLASSPATH in the file. You need to move the definition of POST_CLASSPATH.

The START command should be a single line with spaces in place of the line breaks shown:

@REM
@REM START POINTBASE
@REM
start "Pointbase" /B /MIN cmd /c %JAVA_HOME%\bin\java
    -classpath %WL_HOME%\server\lib\weblogic.jar;%PB_CLASSPATH% com.pointbase.net.netServer
    /port:9093 /d:3 /pointbase.ini=%CONFIGDIR%\pointbase.ini > %CONFIGDIR%\pointbase.log 2>&1

Before you can start WebLogic Server successfully, you must also create the database used by the WebLogic Workshop runtime as described in the next section.

Creating the Runtime Database

You must create a database used by the WebLogic Workshop runtime. This is the database named in Configuring a Connection Pool above. The below instructions assume you selected the default PointBase database and named it cajun. To create the database, you must create a pointbase.ini configuration file, start the PointBase server, and then create the database itself.

Creating the pointbase.ini Configuration File

Before you can configure the PointBase database used by the WebLogic Workshop runtime, you must create a pointbase.ini file in the domain directory with the following content:

database.home=.
transaction.isolationlevel=TRANSACTION_SERIALIZABLE
database.pagesize=4096
cache.size=2063
sort.size=1024

The domain directory is the directory containing the config.xml file for the target domain.

Starting the PointBase Server

The PointBase Server must be running in order to create the WebLogic Workshop runtime database. Start the PointBase server by executing the command below in a Windows command window. Replace c:\bea with the directory where WebLogic is installed.

Note: Depending on the Service Pack level of WebLogic Platform you have installed, the actual names of the PointBase JAR files in the definition of PB_CLASSPATH may be different. Please verify that the JAR files named in PB_CLASSPATH exist in your installation.

The following SET commands should each be one line with no spaces:

set WL_HOME=C:\bea\weblogic81
set JAVA_HOME=C:\bea\jdk141_05
set POINTBASEDIR=%WL_HOME%\common
set PB_CLASSPATH=%POINTBASEDIR%\lib\pbserver44.jar;%POINTBASEDIR%\lib\pbclient44.jar
set PB_TOOLSCLASSPATH=%POINTBASEDIR%\lib\pbtools44.jar;
    %POINTBASEDIR%\lib\pbserver44.jar;%POINTBASEDIR%\lib\pbclient44.jar

The following command should be a single line with spaces in place of the line breaks shown. Run this command while in the domain directory (the directory that contains config.xml for the target domain)

start "Pointbase" cmd /c %JAVA_HOME%\bin\java -classpath
    %WL_HOME%\server\lib\weblogic.jar;%PB_CLASSPATH% com.pointbase.net.netServer
    /port:9093 /d:3 /pointbase.ini=pointbase.ini > pointbase.log 2>&1

When you execute the command above, a new Windows command window with the title Pointbase will appear. Ignore this window until it is time to stop the PointBase Server as directed below.

Creating the Database

Now that the PointBase Server is running, you can create the database with the command shown below. The command should be entered as a single line with spaces in place of the line breaks shown.

%JAVA_HOME%\bin\java -classpath %PB_TOOLSCLASSPATH%
    com.pointbase.tools.toolsCommander com.pointbase.jdbc.jdbcUniversalDriver 
    jdbc:pointbase:server://localhost:9093/cajun,new cajun abc

The command above starts the PointBase Command Tool and also creates the required database (named cajun). The Command Tool will then display the SQL> prompt. Enter the following command to exit the PointBase Command Tool:

exit;

You may now stop the PointBase Server by typing Ctrl-C in the "Pointbase" window. If database creation was successful, a file named cajun.dbn will be present in the domain directory.

Starting WebLogic Server

If you have completed all of the steps described in this topic, you should now be able to start WebLogic Server without errors. In a Windows command window, type the name of the start script. If you used the default name:

startWebLogic

Configuring Web Applications for the Enabled Domain

Web applications that were created in the non-enabled domain can be used in the enabled domain. To do so, each web application project's web.xml file needs to contain:

<listener>
   <listener-class>
   com.bea.wlw.runtime.core.servlet.WebappContextListener
   </listener-class>
</listener>

Specifying Which JSP Compiler to Use in Your Web Application

By default JSP pages use WebLogic Workshop's JSP compiler; the web application project's weblogic.xml file should contain:

<jsp-descriptor>
<jsp-param>
<param-name>jspServlet</param-name>
<param-value>weblogic.servlet.WlwJSPServlet</param-value>
</jsp-param>
<jsp-param>
<param-name>debug</param-name>
<param-value>true</param-value>
</jsp-param>
</jsp-descriptor>

If you want to use WebLogic Server's JSP compiler instead, just comment out the entire jspServlet parameter, as follows:

<jsp-descriptor>
<!-- Comment out the jspServlet param out to go back to using WebLogic Server's JSP compiler -->
<!--<jsp-param>
<param-name>jspServlet</param-name>
<param-value>weblogic.servlet.WlwJSPServlet</param-value>
</jsp-param>-->
<jsp-param>
<param-name>debug</param-name>
<param-value>true</param-value>
</jsp-param>
</jsp-descriptor>

Related Topics

jws-config.properties Configuration File

How Do I: Create a New WebLogic Workshop-enabled WebLogic Server Domain?