Additional Configuration Steps - Updated June 13, 2001


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary \| What's New

WLCS Doc Home \| Installation Guide \| Previous Topic \| Next Topic \| Contents

Additional Configuration Steps

This chapter explains the initial configuration steps you perform after installing the WebLogic Commerce Server software. Some of the steps are required, such as adding the license file to the right directory. Other steps are optional, depending on your environment and requirements. For example, you might need to modify some configuration files or perform other tweaks to the default installation.

Database configuration steps are covered in the next chapter, Database Configuration.

The following topics are covered:

Licensing WebLogic Commerce Server

After you install the product software and before you start the server for the first time, you must copy the WebLogicCommerceLicense.xml license file to the following directory, where WL_COMMERCE_HOME is the directory in which you installed the WebLogic Commerce Server software:

%WL_COMMERCE_HOME%\license (Windows)
$WL_COMMERCE_HOME/license (UNIX)

When you register to download WebLogic Commerce Server on the BEA download site, you should also download a current evaluation license. If you received the product on a CD, you will receive a license file via e-mail to the e-mail account specified on the purchase order.

Note: If you need a new evaluation license, revisit http://commerce.bea.com, go through the download process, and download only the evaluation license.

License Types

WebLogic Commerce Server and WebLogic Personalization Server share a common installation procedure. After the installation completes and the server is started, the license file that you purchased is checked at run-time and determines which features you can use. The type of licenses are:

WebLogic Commerce Server with WebLogic Personalization Server license, which enables you to use all features.
WebLogic Personalization Server only license, which enables you to use the portal and personalization features.
30-day evaluation license from the BEA download site.

If you purchased the WebLogic Personalization Server Only license, attempts to use WebLogic Commerce Server features will result in:

An appropriately adjusted display of the administration options, with the WebLogic Commerce Server Catalog Management, Order Management, and Payment Management options omitted.

Or an error on the browser session if you attempt to run the WLCS Webapp. The following error appears in the WebLogic Server console window at run-time if you try to start the WebLogic Commerce Server WLCS Web Application:

<T3Services> COMMERCE_SERVER_FRAMEWORK,LOG_FATAL,
"BEA WebLogic Commerce Server license exception.com.beasys.commerce.licensing.
LicenseException: A License for BEA product <BEA WebLogic Commerce
 Server> has NOT been found."

Web Applications

The WebLogic Commerce Server and WebLogic Personalization Server software includes three Web applications (Webapps):

The WLCS e-commerce Webapp
The WLPS example portal Webapp
The common WLCS and WLPS administration tools Webapp

These Webapps are located in separate directories under the WL_COMMERCE_HOME\server\webapps directory.

The WLCS e-commerce Webapp is located in the wlcs directory and is deployed as a Webapp only, using a directory hierarchy. It is not deployed as a Web Archive (WAR) file. To run the WLCS e-commerce web application, use the following URL:

http://<wl-host>:7501/wlcs

The WLPS example portal Webapp is located in the examples\portal directory and is deployed as a Webapp in a WAR file named portal.war. (Note: the example portal Webapp is also deployed in the directory style, starting in WL_COMMERCE_HOME/server/public_html/portals.) To run the example portal web application, use the following URL:

http://<wl-host>:7501/portal

The WLPS/WLCS administration tools web application is located in the admin directory and is deployed as a Webapp in a WAR file named tools.war. To run the administration tools web application, use the following URL:

http://<wl-host>:7501/tools

Performance Considerations

This section describes performance considerations when you use Webapps.

The JSP Precompile Option

All the WLCS and WLPS Webapps are deployed with the precompile option turned off. This allows for a fast server startup, but results in a 'page lag' the first time each JavaServer Page (JSP) in the Webapp is accessed. This lag is due to a real-time compile the first time the page is accessed.

With the precompile option turned on, all of the Java Server Pages in the Webapp are compiled during server startup. This 'batch' mode can cause a timely delay in server startup but only occurs if the pages need to be compiled. Once the pages are compiled, subsequent server start ups will check each file to determine if it needs to be compiled and the compile step is skipped if the page is up-to-date. This mode will result in no initial page lag when the page is accessed in real-time.

To turn the precompile option on in a Webapp, follow these steps:

Locate the web.xml file in the Webapp's WEB-INF directory.
Open this file and insert the following element:
```
<context-param>
  <param-name>weblogic.jsp.precompile</param-name>
  <param-value>true</param-value>
</context-param>
```
Note: Some of the web.xml files shipped with the product already have this element in the file, but the value is set to false; in this case, change the <param-value> from false to true.
Save the file and restart the server.

To turn the precompile option on in a Webapp that is deployed in a WAR file:

Save the current .war file to a safe place and copy the .war file to a new temporary directory where you will unjar it.

Unjar the file using the command:

<path to jar.exe utility>\jar -xf WarFileName

For example:

c:\jdk1.2.2\bin\jar -xf tools.war

Locate the web.xml file in the Webapp's WEB-INF directory.
Open this file and insert the following element:
```
<context-param>
  <param-name>weblogic.jsp.precompile</param-name>
  <param-value>true</param-value>
</context-param>
```
Note: Some of the web.xml files shipped with the product already have this element in the file, but the value is set to false; in this case, change the <param-value> from false to true.
Save the file.
Create a WAR file for the Webapp by using the following command:
```
<path to jar.exe utility>\jar -cf WarFileName *.*
```
For example:
```
c:\jdk1.2.2\bin\jar -cf tools.war *.*
```
Tips: However, before you JAR the WAR file again by entering this command, consider these suggestions:
- Look to see if there is a _tmp_war directory under the WEB-INF directory after you have unjarred the .war file. This directory contained compiled JSPs. Remove this directory before re-jarring the .war file to ensure that all files are compiled the next time the server is started.
- Make sure you do not JAR the old .war file in your new .war file. That is, remove the old .war file from the temporary directory before creating the new .war file.
Move the new .war file back to its original directory.
Remove any other files in this directory that may have been left over from previous .war extractions. For example, there may be a WEB-INF directory remaining from the last time you ran the web application from the .war file.
Restart the server.

When the server is restarted, each resource in the the web application is checked to see if it needs to be compiled. The server console will log a message for each file compiled. Ignore any [JSP Enum] no match messages. These are displayed for files that do not match the .jsp file extension.

Overriding the Default JSP Compile Command

You can override the default JSP compile command in your web application by using the following element in the web application's web.xml file:

     <context-param>
         <param-name>weblogic.jsp.compileCommand</param-name>
         <param-value>c:/jdk1.2.2/bin/javac.exe</param-value>
     </context-param>

Change the <param-value> to point to the Java Compiler that will override the default.

See the section The JSP Precompile Option for information on how to edit the web.xml file.

Note: Some of the web.xml files shipped with the product already have this element in the file. In this case, change the <param-value>.

Configuring Startup Files

WebLogic Commerce Server uses two files to set environment variables when it starts the server: set-environment.bat (set-environment.sh for UNIX) and StartCommerce.bat (StartCommerce.sh for UNIX). Use StartCommerce to start WebLogic Commerce Server.

StartCommerce.bat (StartCommerce.sh for UNIX)
- This file starts the server. It calls set-environment.bat or set-environment.sh to configure the environment settings and then starts the server. You do not need to make changes to the StartCommerce.bat or StartCommerce.sh file.
set-environment.bat in WL_COMMERCE_HOME\bin\win32) and set-environment.sh (UNIX systems in WL_COMMERCE_HOME/bin/unix)
Note: This file contains most of the environment settings and is called by the StartCommerce script. The installation program configures the settings during installation. You should not have to change it if you use the Cloudscape database that ships with WebLogic Commerce Server 3.1.1.
- If you have problems with the server starting, ensure WL_COMMERCE_HOME is set to the directory that contains the installed WLCS software. Also ensure the DB_CLASSPATH property points to your database drivers and the JDK_HOME points to your JDK. All other settings should work as shipped.

Configuring Properties Files

This section contains detailed reference information for configuring the properties files for WLCS. The topics here discuss setting up connection pools, servlets, and portals, deploying EJBs, and setting up security realms, in addition to other WLCS properties.

To run the Cloudscape database with the reference DMS that ships with the system, you should not have to configure any of the properties files here. The configuration options in this document cover database setup information for Oracle and a variety of smaller topics relating to realms and security.

The weblogic.properties and weblogiccommerce.properties files that ship with the system contain the default Cloudscape database configuration information. For details about switching to Oracle, see the section Database Configuration.

Setting Properties in the weblogic.properties File

The following values need to be set in the weblogic.properties file for the WebLogic Server instance to use as the host for the WLCS components. A weblogic.properties file is provided in the installation.

Setting the Listen Port

Look in the entry for the TCP/IP port number in the weblogic.properties file in the Core System Properties section. You can change this value, and the default is 7501. The default entry looks like the following snippet:

# TCP/IP port number at which the WebLogic Server listens 
    for connections
weblogic.system.listenPort=7501

See the WebLogic Commerce Server Release Notes for information about other files that must be updated if you change the listenPort value.

Setting the Document Root

The document root must be set to include pages for the portal pages and other pages to be accessible via the Web server. For example, if you create create a new portal, then its entries for homepage, workingdir, and defaultdest will be relative to the document root.

weblogic.httpd.documentRoot=/WeblogicCommerceServer3.1/server/public_html

Note: The document root should be set correctly by the installation. This is the default location and should not change unless you move the directory.

Deploying EJBs

The following jar files must be included in the weblogic.ejb.deploy property value to properly deploy the WLCS beans.

Note: There is no need for a drive specification if you are deploying jar files from the same file system of the WL_COMMERCE_HOME. However, if you want to deploy jar files from another file system, then you should specify the complete path.

Example (installation directory file system):

# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# BEA WEBLOGIC COMMERCE SERVER EJB PROPERTIES
# -------------------------------------------------
# CLUSTER USERS: Note that ALL EJB deployment should be done in the
# *per-cluster* properties file ONLY.
#
weblogic.ejb.deploy=\
        D:/WebLogicCommerceServer3.1/lib/foundation.jar,\
        D:/WebLogicCommerceServer3.1/lib/axiom.jar,\
        D:/WebLogicCommerceServer3.1/lib/ebusiness.jar,\
        D:/WebLogicCommerceServer3.1/lib/advisor.jar,\
        D:/WebLogicCommerceServer3.1/lib/bridge.jar,\
        D:/WebLogicCommerceServer3.1/lib/document.jar,\
        D:/WebLogicCommerceServer3.1/lib/p13nadvisor.jar,\
        D:/WebLogicCommerceServer3.1/lib/portal.jar,\
        D:/WebLogicCommerceServer3.1/lib/ruleeditorbeans.jar,\
        D:/WebLogicCommerceServer3.1/lib/rulesservice.jar,\
        D:/WebLogicCommerceServer3.1/lib/servicemgr.jar

Setting Up the Security Realm for User Management

The weblogic.security.realmClass must be set to the appropriate WLCS class to handle authentication and to provide user and group information. It is unlikely a developer needs to change this value unless using external sources such as LDAP.

Example (in weblogiccommerce.properties):

weblogic.security.realmClass=com.beasys.commerce.axiom.contact.
security.RDBMSRealm

Note: This is for the default realm only.

The RDBMSRealm properties must be set according to the database setup for the installation. A developer is likely to need to adjust these values based on the deployment configuration. The example below shows entries for both Cloudscape and Oracle. Note that the dbUrl must match that of the JDBC connection pools as defined in the weblogiccommerce.properties file.

Example (in weblogiccommerce.properties):

#------WebLogic jDriver for Oracle 8.1.5---------#
#commerce.usermgmt.RDBMSRealm.driver=weblogic.jdbc.oci.Driver
#commerce.usermgmt.RDBMSRealm.dbUrl=jdbc:weblogic:oracle
#commerce.usermgmt.RDBMSRealm.dbServer=@ORACLE_NET_SERVICE_NAME@
#commerce.usermgmt.RDBMSRealm.dbUser=@ORACLE_USER@
#commerce.usermgmt.RDBMSRealm.dbPassword=@ORACLE_PASSWORD@
#--------------Cloudscape------------------#
commerce.usermgmt.RDBMSRealm.driver=COM.cloudscape.core.JDBCDriver
commerce.usermgmt.RDBMSRealm.dbUrl=jdbc:cloudscape:Commerce;create=true;autocommit=false
commerce.usermgmt.RDBMSRealm.dbUser=none
commerce.usermgmt.RDBMSRealm.dbPassword=none

Note: This is for the default realm only.

Setting Properties in the weblogiccommerce.properties File

The weblogiccommerce.properties file is used to set values for the WLCS components. A sample weblogiccommerce.properties file is included in the installation.

Setting Up Internal Values

These properties are used to set up values to be used internally to identify pools, classes, and home names. It is unlikely a developer would ever need to change these values, so these lines should remain unchanged.

Example:

commerce.jdbc.pool.name=jdbcPool
commerce.jts.pool.name=commercePool
   .
   .
   .
commerce.home.content.ContentHome=com.beasys.commerce.axiom.document.Document
commerce.home.content.ContentManagerHome=com.beasys.commerce.axiom.document.DocumentManager
commerce.home.content.ContentSchemaHome=com.beasys.commerce.axiom.document.DocumentSchema
commerce.home.document.DocumentHome=com.beasys.commerce.axiom.document.Document
commerce.home.document.DocumentManagerHome=com.beasys.commerce.axiom.document.DocumentManager
commerce.home.document.DocumentSchemaHome=com.beasys.commerce.axiom.document.DocumentSchema
commerce.content.defaultReadOnly=true
commerce.content.cache.useSoftHashMap=false
commerce.xml.entity.basePath=d:/WebLogicCommerceServer3.1/lib/dtd

Setting Up Portals

The portal component has a number of properties that it uses as defaults for when a new portal gets created. A developer might want to adjust these values based on the nature of the portal being built. The defaults can be overridden using the portal administration tools.

Note: These portals will be copied from the weblogic.httpd.documentRoot/<repository> directory into the corresponding portal/ directories if they do not exist already.

Example:

# Entries taken from PortalProperties
commerce.default.portal.schemaName=_DEFAULT_PORTAL_SCHEMA
commerce.default.portal.headerURL=header.jsp
commerce.default.portal.contentURL=portalcontent.jsp
commerce.default.portal.footerURL=footer.jsp
commerce.default.portal.cols=3
commerce.default.portal.suspendedURL=suspended.jsp
commerce.default.portlet.dir=portlets/
commerce.default.portlet.image.dir=portlets/images/
commerce.default.portlet.titlebarURL=titlebar.jsp
commerce.default.banner.color=#666666
commerce.default.titlebar.bgcolor=#333399
commerce.default.show.borders=false
commerce.default.content.bgcolor=#CCCCCC
commerce.default.titlebar.font.color=#FFFFFF
commerce.default.body.bgcolor=#FFFFFF
commerce.default.profile.group.property=portal.profile.group
commerce.default.portal.password=guest
commerce.application.minimum.build=83914
commerce.default.category.name=Home
commerce.portalservicemanager.fast.portal.get=true

The following property tells the portal component which property set to use as the default for portal users. A developer may want to change this value based on property sets created using the Property Set Management administration tool.

Example:

commerce.default.portal.schemaName=_DEFAULT_PORTAL_SCHEMA

The following portal properties are for internal use and should not be altered by a developer. Example:

commerce.application.minimum.build=83914
commerce.default.category.name=Home

Setting Up the RDBMS Realm

If you need to change the settings in the weblogiccommerce.properties file for the RDBMSRealm, change the database settings in a similar fashion to the database pools in weblogic.properties. Set the dbDriver, dbUrl, dbUser, and dbPassword to use the same database that the commercePool uses in weblogic.properties.

Setting Up User Management Tables

The following properties are used to identify the internal names for tables for use by the user management component. It is unlikely a developer would ever need to change these values.

Example:

commerce.usermgmt.UserTable=WLCS_USER
commerce.usermgmt.GroupTable=WLCS_GROUP
commerce.usermgmt.UserGroupHierarchyTable=WLCS_USER_GROUP_HIERARCHY
commerce.usermgmt.GroupHierarchyTable=WLCS_GROUP_HIERARCHY
commerce.usermgmt.EntityIdTable=WLCS_ENTITY_ID
commerce.usermgmt.ProfileTypeTable=WLCS_UNIFIED_PROFILE_TYPE