Team Development Guide

Team development of a portal Web site revolves around good source control. Proper use of a source control management system has many benefits, such as close integration between team members, the ability to quickly scale the size of a development team, and protection against data loss.

This guide shows you how to configure, store, and manage a common development domain, database data, and portal applications in source control, letting you quickly and consistently develop, build, and update your portal applications.

Use this guide in conjunction with the guide to "Deploying Portal Applications" at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/deploy/index.html for full coverage of deployment issues.

This document contains the following sections:

Choosing a Source Control Vendor

There are a number of source control providers, such as CVS, Perforce, Starteam, Visual Source Safe (VSS), and PVCS. This guide should assist you with using any of those vendors. However, each vendor has different characteristics when it comes to storing code. An important consideration when choosing your source control management system for team development of portal applications is that it must support an unreserved checkout model for files. There are numerous files in the domain and application that need to be checked into source control management but must be writable by the server.

Note: Even if your source control management tool does not directly integrate with WebLogic Workshop (see http://dev2dev.bea.com for information on "Visual Studio Source Control Provider for WebLogic Workshop"), you can still use it to manage your WebLogic domains and applications.

Creating a Shared Portal Domain

The first activity to be done with a source control management system is to have the development team lead create the appropriate portal domain for the group. The important consideration before creating and storing domain assets is determining the BEA home directory—where the team will install WebLogic.

The BEA Home Directory

There are a number of implications around where you create your BEA home that affect any WebLogic Workshop applications and domains that reference that location. When installing WebLogic, each developer can determine which drive and directory to install to.

When creating a new portal domain with the domain Configuration Wizard, you choose which BEA home directory you want to reference for that domain. The physical path to this directory is contained in any portal domain's config.xml file on each development machine and in domain batch scripts such as startWeblogic.cmd.

Why a Common BEA Home Matters

Team members will share these domain files using source control, so that all modifications to existing deployed applications, the addition of new applications, and other settings stored in config.xml and the start scripts can be shared.

Note: When development environments require different domain configuration settings, and you want to use config templating as a solution, do not store config.xml in source control. For more information see Setting up Config Templating (config-template.xml) on page 16.

Following are snippets from config.xml and startWebLogic.cmd that show hard-coded paths:

config.xml

<Application Name="JWSQueueTransport" Deployed="true"
    LoadOrder="1000" Path="C:\bea812\weblogic81\server\lib\" TwoPhase="true">
    <EJBComponent Name="QueueTransportEJB" Targets="portalServer"
    URI="QueueTransportEJB.jar"/>
</Application>

startWebLogic.cmd

set DOMAIN_HOME=C:\bea812\weblogic81\samples\domains\portal

If the config.xml and startWeblogic.cmd files are shared in source control, all team members must have installed WebLogic to the path shown in those files. However, there are circumstances where developers cannot install WebLogic to a particular drive, such as when they have multiple partitions with not enough space left on their C drive.

In addition, pointbase.ini in the domain root directory is a configuration file that may contain a documentation.home property that points to a hard-coded location on the file system.

Table 1 shows which files in a domain contain hard-coded paths.

Table 1 Domain files with hard-coded paths

backup_config.xml

config.xml

create_db.*

installService.cmd

set-dbenv.*

setDomainEnv.*

setDomainEnvQS.*

startManagedWebLogic.*

startManagedWebLogicQS.*

startPointBaseConsole.*

startPointBaseConsoleQS.*

startWebLogic.*

startWebLogicQS.*

stopManagedWebLogic.*

stopManagedWebLogicQS.*

stopWebLogic.*

stopWebLogicQS.*

uninstallService.*

webappCompile.*

webappCompileQS.*

domain-info.xml (in /_cfgwiz_donotdelete)

startscript.xml (in /_cfgwiz_donotdelete)

The next section contains strategies to employ when not all team members can use the same BEA home.

If all team members can use the same BEA home, you may skip Creating and Sharing the Portal Domain on page 7.

Managing Multiple BEA Home Locations for Your Team

There are a number of different techniques for sharing a common domain with team members with different BEA home directories, described in the following sections.

Option 1: Config Templating BEA Home

Config templating avoids many of the problems associated with other solutions, but it requires you to implement search and replace activities on your config.xml and other files. By creating a template for your config.xml which contains tokens that represent your BEA home directory, you can create a process to create a config.xml from a combination of the template and developer specified token values.

Config templating can be used for much more than setting up machines with different BEA home directories: It can provide a way for each developer to work with a separate database instance that shares a common data source configuration.

With config templating, config.xml is not stored in source control. For information on setting up config templating, see Setting up Config Templating (config-template.xml) on page 16.

Option 2: (Windows) Using a Common Virtual Drive for BEA Home

Windows developers may consider setting up a substitute drive letter to map to their BEA home directory.

From the command prompt, the Windows OS lets you create a virtual drive and map it to an existing drive and path using the subst command. Your team can configure a common virtual drive letter not currently in use and use that drive for application and domain activities.

For example, you can create a drive letter P: that maps to a directory on the C drive, such as C:\bea812, by executing the following command from a DOS prompt:

subst P: C:\bea812

Now, after creating a new domain, you can change all references to C:\bea812 to P: in the domain files listed in Table 1.

The previously listed config.xml and startWebLogic.cmd entries would now look like the following:

config.xml

<Application Name="JWSQueueTransport" Deployed="true"
    LoadOrder="1000" Path="P:\weblogic81\server\lib\" TwoPhase="true">
    <EJBComponent Name="QueueTransportEJB" Targets="portalServer"
    URI="QueueTransportEJB.jar"/>
</Application>

startWebLogic.cmd

set DOMAIN_HOME=P:\weblogic81\samples\domains\portal

Note: The new hard-coded paths do not contain \bea812, because C:\bea812 was mapped to P: using the subst command.

When you want to use the domain, switch to the P drive and go into the domain directory. If another developer installs WebLogic to D:\bea, he can simply substitute that directory for P:\ by executing subst P: d:\bea and share the same config.xml and start scripts with ease.

This virtual drive option has a number of drawbacks:

Users must run the subst command upon each reboot, though they can type the command in a text file, save the text file with a .cmd extension, and put it in their program \Startup folder so the command runs automatically at system startup.
The created domain and application must be run from the new virtual drive. Running the domain from the "true" install drive and path will result in errors.
Does not support UNIX developers, though UNIX developers can use the link command.

Option 3: Using Relative Paths

If team members need to install different paths on the same drive, and the domain and application are located in a common relative path to the WebLogic directory, it is possible to change all file paths in config.xml and your start scripts to be relative. However, this solution is limited in its scope.

Assuming the domain is installed to C:\bea812\user_projects\mydomain, the previously listed config.xml and startWebLogic.cmd entries would now look like the following:

config.xml

<Application Name="JWSQueueTransport" Deployed="true"
    LoadOrder="1000" Path="..\..\weblogic81\server\lib\" TwoPhase="true">
    <EJBComponent Name="QueueTransportEJB" Targets="portalServer"
    URI="QueueTransportEJB.jar"/>
</Application>

startWebLogic.cmd

set DOMAIN_HOME=..\..\weblogic81\samples\domains\portal

Problems with this solution include:

No ability to span multiple drives.
Project domain directory must always be in the exact same relative location to the server, even in a deployed production environment.

Creating and Sharing the Portal Domain

The first step the team lead needs to take is the creation of the new portal domain. There are several phases of domain creation, including the possible creation of your own domain template, the domain Configuration Wizard process, initial check-in to source control, and domain configuration tasks.

Best Practices for Creating a Portal Domain to Share with a Team

Before creating a domain with the domain Configuration Wizard, you can create a custom template that determines what is in the domain you create, and you can store that template in source control. The domain Configuration Wizard builds the domain using your template. For instructions on using the Configuration Template Builder to create a domain template, see "Creating Configuration Templates Using the WebLogic Configuration Template Builder" at http://download.oracle.com/docs/cd/E13196_01/platform/docs81/confgwiz/tempbuild.html.
When creating a new domain for team development using the Configuration Wizard, be sure to select "development mode." For instructions on running the Configuration Wizard to create a new portal domain, see "Creating WebLogic Configurations Using the Configuration Wizard" at http://download.oracle.com/docs/cd/E13196_01/platform/docs81/confgwiz/index.html.
Creating the domain and the application so that they are peers to each and share a common parent directory makes sharing them with source control management systems easier to manage.

For example, install your domain to <BEA_HOME>\<WEBLOGIC_HOME>\user_projects\<PROJECT>\domain\<DOMAIN>
And your application to <BEA_HOME>\<WEBLOGIC_HOME>\user_projects\<PROJECT>\application\<APP>

Note: Your paths can be shorter and outside the BEA installation hierarchy.
This approach lets you have a common root directory (%PROJECTNAME) in your source control system's project for both the domain and application.

After you create the domain, but before you start the server, check the domain into source control. WebLogic server creates a number of temporary files and directories in the domain directory at server startup that you are unlikely to want in source control. Table 2 lists the post-startup files to exclude.
If you have a shared parent directory for your domains and applications, use that as your root in source control.
After establishing your initial baseline for the domain in source control, check the domain back out of source control and start the domain using the startWeblogic command. With the server running, you may want to configure the domain so it is ready to use for your project. Using the WebLogic Server Administration Console (http://<server>:<port>/console), you can set up the domain to support the development team, including the addition of needed data sources.

Common tuning activities for a development domain include setting the server logging mode to `Info' from `Warn' (for more verbose console output and outputting JVM messages to the console). Additionally, you may want to limit the file size of the logging. Most developers do not want endless growth of their log files.
For information on server configuration, see WebLogic Server "System Administration" at http://download.oracle.com/docs/cd/E13222_01/wls/docs81/admin.html.
After you make changes to the server configuration, check in config.xml (or a hand-modified version of a templated config-template.xml).

Before configuring your portal application, have another developer validate the changes by checking out the domain and starting the server without error.

Excluding Domain Files From Source Control Management

Exclude the following domain files from source control:

Table 2 Domain files to exclude from source control

Path	Wildcard
`/` (domain root)	`config.xml`(ONLY if you are using config templating. See Setting up Config Templating (config-template.xml) on page 16.)
`/`	`config.xml.booted`
`/`	`config.xml.original`
`/`	`*.log`
/logs	*
`/portalServer/pstore/` (persistent file store for session beans)	*
`/<servername>/`	*.log
`/<servername>/`	`.app_poller_lastrun`
`/<servername>/.wlnotdelete/`	*
`/<servername>/.internal/`	*
`/<servername>/ldap/`	`LDAPBackup.zip`
`/<servername>/ldap/log/`	*
`/<servername>/logs/`	*

Binary Files in Source Control Management

There are a number of binary files in the WebLogic domain that need to be checked into source control management for the domain to function properly. These binary files may change over time for user-initiated reasons, automatic growth of index files, and so on. For this reason, it is important that developers have a good understanding of what these files are, why they change, and when to check them in and out. The emphasis of this section is explaining how to determine when you will need to update those files in source control management.

Examples of binary files that are updated are LDAP, security, and database configuration files.

Working with Binary Files

With all binary files, there is a consistent process to follow when you make changes to them so they can be shared in source control. Changes to binaries should be initiated by a single user, typically the team lead. This reduces the chances of merge conflicts over the project lifecycle. To modify domain binary files in source control:

Stop the server.

Do a clean checkout of the binary files from source control to ensure you are working from a common base.

Start the server.

Make your changes.

Stop the server.

Check-in any modified binary files to source control management.

Test a clean checkout from another machine.

Users, Groups, Roles, and Entitlements - Updating LDAP

A common activity in development is the creation of a base set of users that are used to test the system. By default, WebLogic stores user, group, role, and entitlement information in an LDAP server provided by BEA. This LDAP server persists its data store to the file system in the <domain>/ldap directory.

For information on BEA's LDAP server, see "Managing the Embedded LDAP Server" at http://download.oracle.com/docs/cd/E13222_01/wls/docs81/secmanage/ldap.html.

As the LDAP server contains information that needs to be shared by team members, check the files in the LDAP directory into source control, excluding backup and log files (see Table 2). During project development, there may be occasion to modify the existing users, groups, roles, and entitlements. You can configure users, groups, roles, and entitlements with the WebLogic Administration Portal and check in the updated LDAP files to source control.

For instructions on using the WebLogic Administration Portal, see "Getting Started with Portal Administration" at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/startadm/index.html.

Other Security Information

Other important security files located in the domain are the SerializedSystemIni.dat, DefaultAuthenticatorInit.ldift, DefaultAuthorizerInit.ldift, and DefaultRoleMapperInit.ldift files, which contain essential security information needed to start the domain. While not typically modified during the course of development, these files must exist for the server to be started. The boot.properties file in the domain root contains encrypted username and password information for starting the domain. That file is not mandatory, but it is typically used in development environments to provide automatic login at server startup.

Databases

Portal stores much of its configuration information in the database, and there are occasions where development teams need to share access to this configuration. However, WebLogic Portal does not support running multiple instances of a portal server against the same single database server. For that reason there are several options for a development team to use individual instances of the PointBase database or separate instances of an enterprise-quality database for development.

PointBase

When creating a new portal domain, an instance of the PointBase database is created that is persisted in the root directory of the domain. This PointBase instance contains a number of tables that store base WebLogic Portal and WebLogic Workshop data. In most development environments, each developer will use this PointBase instance. It is possible to use a production database instance for each developer, which this section will cover later.

The two files which PointBase uses to persist the database to the file system are workshop$1.wal and workshop.dbn. Since the database is persisted to the file system, sharing copies of the database can easily be accomplished using source control management. However, PointBase files grows incrementally over time when PointBase is used, which means that the files always appear to have been modified by the user. Over time, the PointBase files can grow from about 3 MB to 10 or more. Developers need to be aware that they should not check in the database unless they explicitly are making changes to the underlying data directly through the WebLogic Administration Portal or the PointBase console. When a change does need to be made, there is a process to follow to keep the size of the updates to a minimum which is outlined below.

Making Changes to the Database - Stop the servers (WebLogic and PointBase). Do a clean checkout of the binary files from source control to ensure you are working from a common base. This is especially important as your PointBase files may have grown significantly since the last checkout, so a new checkout will reduce the size of those files before making your additions. To modify those files in source control, follow the procedure in Working with Binary Files on page 9.

Knowing when You Are Making Changes to PointBase - In general, most activities that are accomplished using the WebLogic Administration Portal are persisted to the PointBase database, with the exception of user, group, and entitlements, which are persisted to LDAP. As the guide to "Deploying Portal Applications" points out at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/deploy/index.html, most of the work with the WebLogic Server Administration Console is done in a staging or production environment. However, there may be times when you want to develop against a portal desktop or have test users with user property values (the values are stored in the database).

Developing Against an Enterprise-Quality Database

Rather than share the PointBase database between developers as a binary file, it is common for each developer to work against their own unique instance of the portal database using Oracle, SQL Server, or another enterprise-quality database. In this case, there is no support for developers sharing a single instance of a database—each developer needs his own instance.

There are several advantages to using this methodology: greater performance, easier maintenance of a baseline of data (with proper support from a database administrator and scripts), and the ability to propagate database data from a production or staging environment to a development environment using the WebLogic Portal Propagation Utility, assuming the production or staging environments use the same type of database as the development environment.

Each development machine is configured to use a specific database, contained in config.xml, which is a shared file in source control management. Setting up Config Templating (config-template.xml) on page 16 can help provide some mechanisms for allowing developers to share config.xml while still pointing to their unique database instance.

Sharing Information Using Unique Enterprise Quality Database Instances

To share information, a database administrator sets up a process where a developer can snapshot his database instance. This snapshot can then be applied to other developer instances as part of a process that those developers can initiate. Snapshots of partial pieces of the database, or the storing of a common set of DDL scripts, are also common practices.

For a description of the database objects for each component of WebLogic Portal, see the "Data Dictionary" at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/db/4Schemas.html.

In addition, WebLogic Workshop stores some of its internal state in the database. The following topic in the WebLogic Workshop help system, "How Do I: Configure WebLogic Workshop to Use a Different Database for Internal State?" addresses how to move that internal state store to another database: http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/workshop/guide/howdoi/howConfigWLWToUseADifferentDBForInternalState.html.

Creating and Sharing the Portal Application

After configuring the portal domain, the team lead needs create a new portal application. There are several phases of application creation, including creating the application and any number of portal Web projects with WebLogic Workshop and initial check-in to source control.

For instructions on creating a new portal application and Web project, see "Creating a Portal Application and Portal Web Project" at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/addPortalApp.html.

Be sure to install any services necessary to your application, such as Commerce and Pipeline, as well as any necessary tag libraries in each portal Web project, such as Commerce and Webflow (for compatibility with legacy portal Web applications).

Where to Create the Workshop Application

As mentioned in the domain configuration section, creating the domain and the application so that they are peers to each and share a common parent directory makes sharing them in source control management systems easier to manage.

For example, install your domain to: <BEA_HOME>/<WEBLOGIC_HOME>/user_projects/<PROJECT>/domain/<DOMAIN>

and your application to: <BEA_HOME>/<WEBLOGIC_HOME>/user_projects/<PROJECT>/application/<APP>

This approach lets you have a common root directory (%PROJECTNAME) in your source control system's project for both the domain and application.

Checking in the Workshop Application

Once the Workshop application has been constructed, the team lead should check the application into source control. This should be done before doing a build of the application, because there are a number of files which are created during a build which should not be checked into source control.

Excluding Portal Application Files From Source Control Management

Exclude the following application files from source control:

Table 3 Application files to exclude from source control

Path	Wildcard
`/` (portal application root)	Each "EJB Project" contains a `.jar` file. These should be excluded.
`/`	`.beabuild.txt`
`/APP-INF/lib/`	Each "Java Project" contains a `.jar` file. These should be excluded.
`/<project>/WEB-INF/ .pageflow-struts-generated/`	`*`
`/.workshop/`	*

Files that are excluded from source control include compiled JARs, temporary configuration files, and the output directory for workshop.

Managing Checkouts of the Workshop Application

The fundamental idea when working with source control management and a WebLogic Workshop application is that developers should be able to check out the application, initiate a build, and start the server without error.

A background on what is created when a build is executed is important to review. When a build is initiated in Workshop, a number of JAR files and temporary directories are created inside the WebLogic Workshop application itself. These files are listed in Table 3. In addition, WebLogic Workshop creates some additional files such as stateless session beans for controls in the .workshop directory of the application. These stateless beans often have names like TimerControl_-1n8kn2z7skxv.

When the application is deployed to the domain by WebLogic Workshop, it is registered in config.xml. This deployment happens automatically when the server is started and the application is built. At this point, the application is added to config.xml in a new XML block. The following example shows the block added to config.xml for an application named portalpm.

    <Application Name="portalpm" Path="P:\user_projects\applications"
        StagingMode="nostage" TwoPhase="true">
        <WebAppComponent Name="portalpmAdmin" Targets="portalServer"
         URI="adminPortal.war"/>
        <EJBComponent Name="content.jar" Targets="portalServer"
         URI="content.jar"/>
        <EJBComponent Name="content_repo.jar" Targets="portalServer"
         URI="content_repo.jar"/>
        <WebAppComponent Name="portalpmDatasync" Targets="portalServer"
        URI="datasync.war"/>
        <EJBComponent Name="netuix.jar" Targets="portalServer"
         URI="netuix.jar"/>
        <EJBComponent Name="p13n_ejb.jar" Targets="portalServer"
         URI="p13n_ejb.jar"/>
        <EJBComponent Name="prefs.jar" Targets="portalServer"
         URI="prefs.jar"/>
        <WebServiceComponent Name="portalpmTool" Targets="portalServer"
         URI="wps-toolSupport.war"/>
        <EJBComponent Name="wps.jar" Targets="portalServer" URI="wps.jar"/>
        <ApplicationConfiguration Name="portalpm" Targets="portalServer"/>
    </Application>

As WebLogic Workshop will update the config.xml for the domain automatically, it is not necessary to check in a config.xml that contains the application name XML block. Instead, a developer checks out the application, does a build, and starts the server against a domain without this application reference. His application is then deployed to config.xml with all the required references to the newly built application components. If the application name XML block is checked in with config.xml, WebLogic Workshop will automatically update it if necessary to add or remove components.

Note about config templating - If you are using config templating (page 16), the basic config.xml has already been created on each development machine using the config template, and application modifications or additions are correctly added to each developer's config.xml file.

There are two other files that store the components for the application: application.xml and weblogic-application.xml, which are found in the application's META-INF directory. These files need to be shared in source control, and when new components are added to the application (such as a new EJB), the updated application.xml and weblogic-application.xml must be checked back in to source control.

Portal Coding Practices

This section provides best practices guidance for portal application source code storage.

Java Projects

If you have a number of general-purpose Java libraries that will be used by your portals, it is recommended that they be stored in a Java project inside the portal enterprise archive. This enables portability of your Java libraries across multiple instances of the server and is a convenient mechanism for packaging libraries for reuse.

Cross-Platform Support

When coding to develop and deploy in a cross-platform environment, you observe the following best practices:

Do not use spaces in filenames.
Keep filenames short (older versions of TAR do not support long filenames).
Use forward slashes in paths when possible.

Cluster Configuration

Any code you write should be tested often in a clustered environment. Also important is keeping session data to a manageable size and configuring your Web applications to support session sharing across the cluster. For clustering information, see "Deploying Portal Applications" at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/deploy/index.html.

Setting up Config Templating (config-template.xml)

When working in a team development environment, your team members need to work with the same config.xml file so that all modifications to existing deployed applications, the addition of new applications, and other settings stored in config.xml file can be shared. However, there are configuration settings that may need to vary from user to user. The most common variations are when developers are using different BEA home directories or their own database instances. Developers typically have different database logins and need different settings for their JDBC connection pools.

Config templating addresses this problem by letting you distribute a templatized domain configuration file, config-template.xml. Developers share this config-template.xml file through source control.

Exclude config.xml From Source Control

When you need unique domain configurations in each developer environment, exclude the config.xml file from source control. Check in config-template.xml instead.

You can use ant or other script language to set up a process that copies the config-template.xml over the config.xml file. Next, certain strings in the config.xml file are replaced with strings that the user defines in a properties file.

For example, we can start with a config-template.xml file that contains the following:

<JDBCConnectionPool DriverName="weblogic.jdbc.oci.Driver"

MaxCapacity="10" Name="Arcadia"

Properties="user=ARCADIAUSER;password=ARCADIAPASSWORD;server=arcadia"

RefreshMinutes="10" Targets="myserver"

URL="jdbc:weblogic:oracle"/>

and a particular user has a local.configtemplate.properties file with the following two entries:

ARCADIAUSER=john

ARCADIAPASSWORD=mypassword

After running the replacement process, that user ends up with a config.xml file that reads:

<JDBCConnectionPool DriverName="weblogic.jdbc.oci.Driver"

MaxCapacity="10" Name="Arcadia"

Properties="user=john;password=mypassword;server=arcadia"

RefreshMinutes="10" Targets="myserver"

URL="jdbc:weblogic:oracle"/>

Each user need only keep his own copy of the local.configtemplate.properties file, which should not be checked into source control. A file named configtemplate.properties should be distributed in source control to serve as an example of a valid local.configtemplate.properties file.