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?
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?
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:
Note: The steps above have been tested in a new "WLS Domain" created with the Domain Configuration Wizard.
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 e-docs.bea.com 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.
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 e-docs.bea.com, 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?
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 e-docs.bea.com, 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.
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.
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 e-docs.bea.com 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.
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 e-docs.bea.com 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.
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 e-docs.bea.com 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.
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.
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.
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
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"
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.
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
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.
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.
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.
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.
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.
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
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>
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>