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

This topic describes how to modify the configuration of an existing WebLogic Server 7.0 domain such 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?

# Overview

You may configure any WebLogic Server domain to support WebLogic Workshop web services. To enable support of WebLogic Workshop web services in a domain, you must complete the following steps:

1. Configure a collection of resources in WebLogic Server in the target domain. See Configuring WebLogic Server Resources, below.

2. Create and configure the jws-config.properties file in the target domain. See Setting WebLogic Workshop Properties, below.

3. Make changes to the startWebLogic.cmd or startWebLogic.sh script to set appropriate Java classpaths and start a database server to manage WebLogic Workshop runtime information. See Editing the startWebLogic Script, below.

4. Create the database used to store WebLogic Workshop runtime information. See Creating the PointBase Database, below.

After you have completed all of these steps, use the startWebLogic script in the domain directory to start WebLogic Server.

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

Note: The Domain Configuration Wizard requires you to specify a "listen address" for the server. However, best results are obtained if the resulting <Server> element in the new domain's config.xml file does not specify a ListenAddress attribute. We recommend that after creating the domain you stop the server, then edit config.xml and remove the ListenAddress attribute from the <Server> element in config.xml.

# Configuring WebLogic Server Resources

In order for a WebLogic Server 7.0 domain to be able to host WebLogic Workshop web service, the domain must be configured with the resources described in the following sections.

These resources may be configured using the WebLogic Server console (recommended) or by editing the domain's config.xml file directly. You can learn more about configuring WebLogic Server on e-docs.bea.com at Creating and Configuring WebLogic Server Domains. The instructions below assume you are configuring these resources from the WebLogic Server 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.

## Connection Pool

A JDBC connection pool must be configured to support JDBC data sources used by the WebLogic Workshop runtime. In the WebLogic Server console, navigate to <domain>->Services->JDBC->Connection Pools. You can refer to the XML fragment below to see what values to enter in the console.

You can learn how to configure a connection pool on e-docs.bea.com at Configuring and Managing JDBC Connection Pools, MultiPools, and DataSources Using the Administration Console.

After configuring the connection pool, the resulting entry in config.xml should resemble the following:

    <JDBCConnectionPool Name="cgPool"
        DriverName="com.pointbase.jdbc.jdbcUniversalDriver"
        InitialCapacity="5" MaxCapacity="20" CapacityIncrement="1"
        Properties="user=cajun;password=abc" RefreshMinutes="0"
        ShrinkPeriodMinutes="15" ShrinkingEnabled="true"
        SupportsLocalTransaction="true" Targets="cgServer"
        TestConnectionsOnRelease="false"
        TestConnectionsOnReserve="false" URL="jdbc:pointbase:server://localhost:9093/cajun"/>

This example illustrates configuration of a connection pool on the PointBase database that is installed with WebLogic Server. You may use a different database such as Oracle or SQL Server. To learn how to configure WebLogic Workshop to use a different database, see How Do I: Configure WebLogic Workshop to Use a Different Database for Internal State?.

## 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). In the WebLogic Server console, navigate to <domain>->Services->JDBC->Tx Data Sources. You can refer to the XML fragment below to see what values to enter in the console.

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

You can learn how to configure a data source on e-docs.bea.com at Configuring and Managing JDBC Connection Pools, MultiPools, and DataSources Using the Administration Console.

After configuring the conversation data source, the resulting entry in config.xml should resemble the following:

    <JDBCTxDataSource EnableTwoPhaseCommit="true"
        JNDIName="cgDataSource" Name="cgDataSource" PoolName="cgPool" Targets="cgServer"/>

Note that the PoolName attribute refers to the connection pool configured above.

## 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 named cgSampleDataSource. To create this data source, follow the same procedure as when creating the Conversation Data Source, above. You can refer to the XML fragment below to see what values to enter in the console.

After configuring the sample data source, the resulting entry in config.xml should resemble the following:

    <JDBCTxDataSource EnableTwoPhaseCommit="true"
        JNDIName="cgSampleDataSource" Name="cgSampleDataSource" PoolName="cgPool" Targets="cgServer"/>

Note that the PoolName attribute refers to the connection pool configured above.

Note also that you may change the default JDBC Data Source name used by the WebLogic Workshop visual development environment in the Workshop.properties file. To learn more, see Workshop.properties Configuration File.

## JMS Data Store

A JMS JDBC data store must be configured to support state persistence by JMS controls. In the WebLogic Server console, navigate to <domain>->Services->JMS->Stores. You can refer to the XML fragment below to see what values to enter in the console.

The name of the JMS store must 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.

You can learn how to configure a JMS JDBC data store on e-docs.bea.com at Create a JMS JDBC Store.

After configuring the JMS JDBC data store, the resulting entry in config.xml should resemble the following:

    <JMSJDBCStore ConnectionPool="cgPool" Name="cgJDBCStore"/>

Note that the ConnectionPool attribute refers to the connection pool configured above.

## JMS Server

A JMS server must be configured to support message buffers, timer controls, JMS controls and JMS as a web service message transport. In the WebLogic Server console, navigate to <domain>->Services->JMS->Servers. You can refer to the XML fragment below to see what values to enter in the console.

You can learn how to configure WebLogic JMS servers on e-docs.bea.com at Configuring WebLogic JMS.

The name of the JMS server must 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.

After configuring the JMS server, the resulting entry in config.xml should resemble the following:

    <JMSServer Name="cgJMSServer" Store="cgJDBCStore" Targets="cgServer">

Note that the Store attribute refers to the JMS Data Store configured above.

## JMS Connection Factory

A JMS connection factory must be configured to provide JMS connections. In the WebLogic Server console, navigate to <domain>->Services->JMS->Connection Factories. You can refer to the XML fragment below to see what values to enter in the console.

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

You can learn how to configure WebLogic JMS connection factories on e-docs.bea.com at Configuring WebLogic JMS.

After configuring the JMS connection factory, the resulting entry in config.xml should resemble the following:

    <JMSConnectionFactory JNDIName="weblogic.jws.jms.QueueConnectionFactory" Name="cgQueue"
        Targets="cgServer"/>

# 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 startWebLogic Script

The following additions must be made to the startWebLogic.cmd file on Windows hosts or the startWebLogic.sh file on Unix.

Only the Windows version of the procedure is shown. There are several differences you should be aware of when performing these procedures on Unix:

- Environment variable references are of the form $WL_HOME instead of %WL_HOME%

- The path separator is / instead of \

- Unix scripts use # to denote comments instead of REM

- @ as the first character on a line is specific to Windows. Do not use it on Unix systems.

- Unix path environment variables like PATH and CLASSPATH use colon (:) to separate path elements instead of semicolon (;)

Paste all of the code fragments described below into startWebLogic.cmd 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\weblogic700
    set BEAHOME=C:\bea
    set JAVA_HOME=C:\bea\jdk131_03
    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 JwsCompile 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\weblogic700\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 startWebLogic.cmd. Add the 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.

## Starting the WebLogic Workshop Debugging Proxy

If you want to use the WebLogic Workshop debugger in this domain, you must also start the WebLogic Workshop Debugging Proxy from the startWebLogic.cmd script. To start the WebLogic Workshop Debugging Proxy, add the line below to startWebLogic.cmd. 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 PointBase 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 startWebLogic.cmd if you want WebLogic Workshop to use the default PointBase database that is installed with WebLogic. You may optionally configure 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\weblogic700\samples\server\eval\pointbase
    set PB_CLASSPATH=%POINTBASEDIR%\lib\pbserver42ECF183.jar;%POINTBASEDIR%\lib\pbclient42ECF183.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 PointBase Database

You must create the database used by the WebLogic Workshop runtime. This is the database named at the end of the URL specified for the Connection Pool which you configured above. The default database name is cajun.

## 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\weblogic700
    set JAVA_HOME=C:\bea\jdk131_03
    set POINTBASEDIR=%WL_HOME%\samples\server\eval\pointbase
    set PB_CLASSPATH=%POINTBASEDIR%\lib\pbserver42ECF183.jar;%POINTBASEDIR%\lib\pbclient42ECF183.jar
    set PB_TOOLSCLASSPATH=%POINTBASEDIR%\lib\pbtools42ECF183.jar;
        %POINTBASEDIR%\lib\pbserver42ECF183.jar;%POINTBASEDIR%\lib\pbclient42ECF183.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:

    startWebLogic

# Configuring WebLogic Workshop to Use a Different Domain

To learn how to configure the WebLogic Workshop visual development environment to work with a different domain from the default, see To Run WebLogic Workshop in the New Domain in How Do I: Create a New WebLogic Workshop-enabled WebLogic Server Domain?.

Related Topics

jws-config.properties Configuration File
How Do I: Create a New WebLogic Workshop-enabled WebLogic Server Domain?