Production Operations User Guide
Team development of a WebLogic Portal web site revolves around good source control. Proper use of a source control 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 section 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.
This document contains the following sections:
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 also Visual Studio Source Control Provider for WebLogic Workshop), you can still use it to manage your WebLogic Server domains and applications.
Have the development team lead create the appropriate portal domain for the group. Before creating and storing domain assets, determine the BEA home directory—where the team will install WebLogic software.
The directory where WebLogic Platform software is installed is called the BEA home directory. WebLogic Workshop applications and domains each reference the BEA home directory. It is important to carefully consider where to put the BEA home directory. When installing WebLogic Platform, 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
.
Team members 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 a configuration file template as a solution, do not store config.xml
in source control. For more information see Setting up a Configuration File Template (config-template.xml).
Following code fragments from config.xml
and startWebLogic.cmd
show hard-coded paths:
<Application Name="JWSQueueTransport" Deployed="true"
LoadOrder="1000" Path="C:\bea812\weblogic81\server\lib\" TwoPhase="true">
<EJBComponent Name="QueueTransportEJB" Targets="portalServer"
URI="QueueTransportEJB.jar"/>
</Application>
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 Server to the path shown in those files. However, there are circumstances when developers cannot install WebLogic Server 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 filesystem.
Table 3-1 shows which files in a domain contain hard-coded paths.
The next section contains strategies to employ when not all team members can use the same BEA home directory.
If all team members can use the same BEA home directory, skip to Creating and Sharing the Portal Domain.
There are a number of different techniques for sharing a common domain with team members with different BEA home directories, which are described in the following sections:
Creating a configuration file template 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.
A configuration file template 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 a configuration file template, config.xml
is not stored in source control. For information on setting up a configuration file template, see Setting up a Configuration File Template (config-template.xml).
Windows-based developers may consider setting up a substitute drive letter to map to their BEA home directory.
From the command prompt, Windows 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 Windows Command 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 3-1.
The previously listed config.xml
and startWebLogic.cmd
entries would now look like the following, with the changes highlighted in bold type:
<Application Name="JWSQueueTransport" Deployed="true"
LoadOrder="1000" Path="P:
\weblogic81\server\lib\" TwoPhase="true">
<EJBComponent Name="QueueTransportEJB" Targets="portalServer"
URI="QueueTransportEJB.jar"/>
</Application>
set DOMAIN_HOME=
P:
\weblogic81\samples\domains\portal
Note: The new hard-coded paths do not contain C:\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 more developers install WebLogic Server to D:\bea
, they 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:
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.link
command.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 Server 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, with the changes highlighted in bold type:
<Application Name="JWSQueueTransport" Deployed="true"
LoadOrder="1000" Path="..\..
\weblogic81\server\lib\" TwoPhase="true">
<EJBComponent Name="QueueTransportEJB" Targets="portalServer"
URI="QueueTransportEJB.jar"/>
</Application>
set DOMAIN_HOME=.
.\..
\weblogic81\samples\domains\portal
Problems with this solution include:
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 creating your own domain template, performing the domain Configuration Wizard process, initially checking-in to source control, and configuring the domain.
drive
:\ourDomain
.For example, install your domain to
WEBLOGIC_HOME
\user_projects\
PROJECT
\domain\
DOMAIN
And install your application to 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.
startWebLogic
script in a text editor and add a path for the WLS_REDIRECT_LOG
file before the if "%WLS_REDIRECT_LOG%"
line. For example:WLS_REDIRECT_LOG=D:\logs\admin
if "%WLS_REDIRECT_LOG%"=="" (
startWeblogic
command after establishing your initial baseline for the domain in source control. 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). In addition, you can limit the maximum size of the log files.
For information on server configuration, see WebLogic Server System Administration.
After you make changes to the server configuration, check in config.xml
(or a hand-modified version of a templated config-template.xml
).
Exclude the following domain files from source control:
|
|
|
|
There are a number of binary files in the WebLogic Server 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 need to update those files in source control management. Some kinds of binary files you can update include: LDAP files, security-related files, and database configuration 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 life cycle.
To modify domain binary files in source control:
A common activity in development is the creation of a base set of users that are used to test the system. By default, WebLogic Server stores user, group, role, and entitlement information in an embedded LDAP provided by BEA. This LDAP server persists its data store to the filesystem in the domain
/ldap
directory.
For information on BEA's LDAP server, see Managing the Embedded LDAP Server.
Because 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 3-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.
Other important security files located in the domain are the SerializedSystemIni.dat
, DefaultAuthenticatorInit.ldift
, DefaultAuthorizerInit.ldift
, and DefaultRoleMapperInit.ldift
files. These files 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 start. 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 allow server startup without requiring authentication.
WebLogic 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 or database schema. Although the default database for a WebLogic Portal domain is PointBase, it is recommended that an Enterprise-quality database be used for development efforts, because moving data between heterogeneous databases can be a labor-intensive manual effort. See Developing Against an Enterprise-Quality Database on page 12.
When creating a new portal domain, an instance of a PointBase database is created that is persisted in the root directory of the domain. New domains can also create the database objects necessary for an Enterprise-quality database. For details on configuring an Oracle, SQL Server, DB2 or Sybase database, see the Database Administration Guide. For details on creating new domains, see Creating WebLogic Configurations Using the Configuration Wizard.
The database contains a number of tables that store base WebLogic Portal and WebLogic Workshop data. For a description of the database objects for each component of WebLogic Portal, see the Data Dictionary. In addition, WebLogic Workshop stores some of its internal state in the database. The topic How Do I: Configure WebLogic Workshop to Use a Different Database for Internal State? in the WebLogic Workshop help system addresses how to move that internal state store to another database.
PointBase Development Considerations
PointBase uses two files to persist the database to the filesystem: workshop$1.wal
and workshop.dbn
. Because the database is persisted to the filesystem, 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 in the following paragraph steps:
To make changes to the database:
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.
Knowing When You Are Making Changes to PointBase
In general, most activities that are accomplished using the WebLogic Administration Portal are persisted to the database, with the exception of user data, group data, entitlements, and delegated administration policies, which are persisted to the embedded LDAP. However, there may be times when you want to develop with test users with user property, which are stored in the 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.
The same Enterprise-quality DBMS used in production should be used for development. For example, if you plan to deploy your application on Oracle you should develop your application on Oracle as well.
Note: For Oracle and DB2, a separate database schema for each developer on a development database instance is recommended. For Sybase and SQL Server, a separate database and database log file for each developer on the development database instance is recommended.
This methodology allows greater performance and easier maintenance of a baseline of data (with proper support from a database administrator and scripts).
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 a Configuration File Template (config-template.xml) can help provide some mechanisms for allowing developers to share config.xml
while still pointing to their unique database instance.
To share information, a database administrator sets up a process where a developer can save an instance of his database schema. This snapshot can then be applied to other developer schemas 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.
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.
After configuring the portal domain, the team lead needs to 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.
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).
As mentioned in Best Practices for Creating a Portal Domain to Share with a Team, placing the domain and application directories in a common parent directory makes sharing them in source control management systems easier to manage.
For example, install your domain to: drive
:\ourDomain
and your application to: drive
:\ourApp
This approach lets you have a common root directory (%
PROJECTNAME
) in your source control system's project for both the domain and application.
Note: To avoid path length exceptions, store the domain and application directories in a short path. For example, drive
:\ourDomain
.
Once the WebLogic 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 a number of the files created during a build should not be checked into source control.
Exclude the following application files from source control:
Each "EJB Project" contains a |
|
Each "Java Project" contains a |
|
Files that are excluded from source control include compiled JARs, temporary configuration files, and the output directory for WebLogic Workshop.
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.
When a build is initiated in WebLogic Workshop, a number of JAR files and temporary directories are created inside the WebLogic Workshop application itself. These files are listed in Table 3-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.
Listing 3-1 shows the block added to config.xml
for an application named portalpm
.
Listing 3-1 Application Added to config.xml File
<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>
Because WebLogic Workshop updates 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, performs a build, and starts the server against a domain without this application reference. The developer's 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 automatically updates it if necessary to add or remove components.
Note: If you are using a configuration file template, as described in Setting up a Configuration File Template (config-template.xml), the basic config.xml
has already been created on each development machine using the configuration file 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.
This section provides best practices guidance for storing portal application source code.
If you have a number of general-purpose Java libraries that will be used by your portals, it is recommended 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.
When coding to develop and deploy in a cross-platform environment, you observe the following best practices:
myPortletContent.jsp
and specify the file MyPortletContent.jsp
as the Content URI on windows without problems. However, when this same application is deployed on UNIX, an error that the file MyPortletContent.jsp
cannot be found is generated.As you add books, pages, and portlets to portal desktops in WebLogic Workshop, a Definition Label (unique ID) is automatically generated for each component (which appears in the Property Editor window). With multiple developers creating new portal components, it is possible that different components can have the same automatically generated Definition Labels. To avoid duplicate Definition Labels, manually change the Definition Label for each new component using your own naming conventions.
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 Configuring a Portal Cluster.
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.
A configuration file template 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.
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 another 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 each developer defines in a properties file.
For example, you 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"
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"
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.
You can create and run multiple enterprise applications in a single-cluster domain. As shown in Figure 3-1, a single domain can host multiple enterprise applications (EARs). Each EAR deployment can host multiple web applications, and any number of desktops can be created based on the web applications. The web applications and desktops associated with one enterprise application (EAR) are not dependent on those in another enterprise application (they are decoupled).
Figure 3-1 Multiple Enterprise Applications in a Single Domain
The following restrictions apply to this configuration of multiple enterprise applications in a single domain:
context-root
names and their associated CookieName
names. For each enterprise application, the WebLogic Administration Portal shows all of the portal web applications that are deployed to the server. Note: Each enterprise application must be managed through its respective Administration Portal. Some domain-level resources, such as content, users, and groups, can be viewed and managed across enterprise applications from a single Administration Portal; however, be aware that data in one application may be cached, and updates to the same data made from another application's Administration Portal may not be immediately visible.
Note: Content for each enterprise application is managed through its respective Portal Administration tool and Virtual Content Repository. Virtual Content Repositories (as well as Portal Administration tools) are unique to each application cannot be shared.
For releases prior to SP4, BEA recommended not storing the class files in the path WEB-INF/classes
because these are built automatically by WebLogic Workshop. However, in SP4 several new classes were added in the path:
for which source files are not provided, specifically:
PortalManager.class
PortalLogger.class
PortalBeanManager.class
PortalAdminLogger.class
DefaultPortalLogger.class
Because of this change, SP4 portal projects based on WebLogic Workshop will not build successfully when extracted from their source control repository.
To ensure a successful build of your portal project while using source control, you can create a .jar
file containing the class files listed above, and check the .jar
file into the source control system repository.