![]() ![]() ![]() ![]() ![]() ![]() |
This chapter discusses how to configure and manage a common environment for WebLogic Portal development. A common development environment allows developers to share the same WebLogic Portal domain, database, and application configuration, and maintain these elements in a source control system. A well-planned team environment allows you to quickly and consistently develop, build, and update your WebLogic Portal applications.
Tip: | See also the Developer’s Quick Start Guide. The Quick Start Guide provides guidance, best practices, and tips to developers for setting up, using, and increasing productivity when using WebLogic Portal. It shows one example of accomplishing these functions. Because of the WLP’s versatility, you can accomplish the same thing in other ways. This guide provides a minimal amount of step-by-step instructions—just enough to get you started. |
This chapter contains the following sections:
The basic tasks required to configure a team development environment for WebLogic Portal include:
These tasks are described in the following sections.
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.
There are a number of source control providers, such as CVS, Subversion (SVN), Perforce, StarTeam, Visual Source Safe (VSS), and PVCS. This chapter assists 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. This is because 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. An unreserved checkout model means that multiple users can check out and edit a file simultaneously– individual users do not “lock” the file from other users when they check it out.
Tip: | For information on sharing project files using Workshop for WebLogic’s Eclipse-based integrated source control features, see the Workshop for WebLogic document “Working with Source Control.” |
This section describes the basic steps in creating a shared WebLogic Portal domain, and includes the following topics:
A WebLogic Portal domain is the foundation upon which you build portals. The domain includes the configuration files, database, and scripts that define and run your server environment, provides a default security realm and predefined system administrators, and provides server administration tools. The domain also includes files and services for building portals and related functionality.
A basic domain infrastructure consists of one Administration Server and optional Managed Servers and clusters. For a more detailed description of these components, as well as a more complete introduction to domains, see the WebLogic Server document, “Creating WebLogic Domains Using the Configuration Wizard.”
In a team development environment, domain-related files are stored in source control, and checked out to individual development machines. 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 configuration files and scripts can be shared.
Tip: | It is a recommended practice to use domain templates, rather than the domain files themselves, to create and distribute domains to members of a development team. Check these templates into source control. For information on creating domain templates, see Creating a WebLogic Portal Domain Template. |
Every developer on the team must first install WebLogic Portal on their development machines. It is a recommended practice, but not required, that all developers install WebLogic Portal in a common home directory.
The recommended approach to distributing a commonly configured domain among team members is to create a domain template and check it in to source control.
Tip: | If members of your team only require a default WebLogic Portal domain, they can simply create the default WebLogic Portal domain using the WebLogic Configuration Wizard on their individual machines. In this case, no domain files need to be checked into source control. On the other hand, if you need special domain configurations, such as JDBC, JMS, or extra shared libraries, a custom domain template is recommended. For detailed information on using the Configuration Wizard, see the WebLogic Server document “Creating WebLogic Configurations Using the Configuration Wizard.” |
A domain template is used to create a new domain. A domain template defines the full set of resources within a domain, including infrastructure components, applications, services, security options, and general environment and operating system parameters. You can create a domain template from an existing template or from an existing domain. Given a shared domain template, all developers on a team can effectively create the same domain configuration on their individual development machines.
For detailed information on creating domain templates, see the WebLogic Server document “Creating Configuration Templates Using the WebLogic Configuration Template Builder.”
After a domain template is created and checked into source control, each developer can check out the template and create their own local domain. Because developers use the same template to create their domains, the contents of their domains are equivalent.
Each developer uses the domain template to create a local domain using either the WebLogic Configuration Wizard or a script. For detailed information on using the Configuration Wizard, see the WebLogic Server document “Creating WebLogic Configurations Using the Configuration Wizard.” For an overview of the files that are installed with a domain, see the WebLogic Server document “Domain Configuration Files.”
Tip: | For detailed information on building a domain programmatically with a script, see the WebLogic Server document, “Creating and Configuring WebLogic Domains Using WLST Offline.” |
Tip: | A common activity in development is the creation of a base set of users that are used to test the system. See also Updating Users, Groups, Roles, and Entitlements. |
Start WebLogic Server using the domain’s DOMAIN_ROOT/bin/startWeblogic
command.
With the server running, you can configure the domain. Using the WebLogic Server Administration Console (http://
server
:
port/console
), you can set up the domain to support the development effort, including the addition of needed data sources. For information on server configuration, see the WebLogic Server document
“System Administration for Oracle WebLogic Server.”
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.
The changes you make are captured in the file DOMAIN_ROOT/config/config.xml
. You can check this file into source control to share it with members of the development team. Note, however, that the config.xml
file contains hard-coded paths that each developer might need to modify locally. One technique for sharing this file is to create and check in a string-substitution template and provide a script that each developer can run locally to create their own config.xml
file.
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, you might require an Enterprise-quality database for development efforts.
For detailed information on database management for WebLogic Portal, including information on size restrictions imposed by the evaluation version of PointBase that is distributed with WebLogic Portal, see the WebLogic Portal Database Administration Guide. For more information on working with the PointBase database, see Using the PointBase Database.
This section includes these sections:
Rather than share the PointBase database between developers as a binary files, it is common for each developer to work against their own portal database using Oracle, SQL Server, or another Enterprise-quality database.
Note: | For Oracle and DB2, a separate database schema for each developer on a development database is recommended. For Sybase and SQL Server, a separate database and database log file for each developer on a development database instance is recommended. For MySQL a separate database for each developer is recommended. |
Each development domain is configured through the domain template to use a specific database, listed in multiple XML files in the directory <DOMAIN_HOME>/config/jdbc
. For details, see the
WebLogic Portal Database Administration Guide.
Generally, it is a good practice to use the same Enterprise-quality DBMS in development that you plan to use in staging and production. For example, if you plan to deploy your application on Oracle it is a good practice to develop your application on Oracle as well. This methodology allows greater performance and easier maintenance of a baseline of data (with proper support from a database administrator and scripts).
It is also possible to use one type of database in development and another in staging and production and use the propagation tools to move data between them. In this scenario, developers might use PointBase in development while the staging and production systems use an Enterprise quality database, such as Oracle. Using the propagation tools, you can export the database inventory from the development system and import it into the staging or production system. For detailed information on using the propagation tools, see Using Workshop for WebLogic Propagation Tools.
In general, most activities that are accomplished using the WebLogic Portal Administration Console are persisted to the database, with the exception of entitlements, which are persisted to the embedded LDAP. However, there may be times when you want to develop using test users with user properties assigned to them.
These properties are stored in the database. In addition, service administration configurations are persisted in the application’s deployment plan, not to the database. Content repository configurations are also not persisted in the database, although actual content stored in the WLP repository is in the database. (If you are using a File System Repository, only the content metadata is stored in the database.)
For detailed information on entitlements, see the WebLogic Portal Security Guide.
A development licence for PointBase is installed with WebLogic Portal. Note that with the development license, the database size is limited to 30 MB. To increase this limit, you need to purchase a full license. Also, note that PointBase stores data in binary files that grow as you use the database. For information on handling binary files in a team environment, see Managing Binary Files in Source Control.
To prevent the PointBase database server from starting and stopping automatically, set your domain’s POINTBASE_FLAG
to false
(the default is true
). To do this:
On a Windows system, in the file <DOMAIN_HOME>/bin/setDomainEnv.cmd
, enter:
On a UNIX system, in the file <DOMAIN_HOME>/bin/setDomainEnv.sh
, enter:
You can also achieve the same result by running the startWebLogic
command with the nopointbase
option.
When you create a WebLogic Portal domain using the default domain template, a datasource called samplesDataSource is automatically included in the domain. You can remove this datasource from the domain if you wish. To remove it, use the WebLogic Server Administration Console. From the main page of the Administration Console, select JDBC > Data Sources. Click Lock & Edit, then select samplesDataSource from the table and click Delete.
A sample PointBase database is also installed with the default WebLogic Portal domain. This database is typically used for example and testing purposes only. If all of your domain’s data sources are pointed to a non-PointBase database, it is recommended that you remove this database before deploying your application to a production server. To remove the database, simply delete the following files from your domain:
After configuring the portal domain, you need to create a new portal application that will be shared by all members of the development team.
Tip: | To plan for the sharing of portal application code among team members, it is important to understand the role of Shared J2EE Libraries in a WebLogic Portal application. See the WebLogic Server document “Creating Shared J2EE Libraries and Optional Packages” for information on this important topic. Shared Libraries are also discussed in the WebLogic Portal Development Guide and Deploying J2EE Shared Libraries. |
Like domain creation, application creation occurs in several steps. These steps are explained in this section. They include:
All projects created with Workshop for WebLogic are created inside a Workspace directory. For more information on creating workspaces and projects, see the WebLogic Portal Development Guide.
Use Workshop for WebLogic to create one or more Portal EAR Projects. An EAR Project primarily consists of configuration files that reference Web applications and J2EE Shared Libraries.
When you create an EAR project, you select the Project Facets you want to include in the project, including a set of WebLogic Portal facets, as shown in Figure 2-1.
A facet is a convenient way to group a set of J2EE Shared Libraries and IDE functionality that are required for a specific feature. For example, the Admin Console facet groups the J2EE Shared Libraries that are required to deploy and run the WebLogic Portal Administration Console. If you do not want to include a facet, you can deselect it. Note that some facets depend on other facets. If you try to remove a facet that has dependencies, the dialog box alerts you and prohibits you from making that particular change.
Tip: | It is recommended that, for development purposes, you select all of the WebLogic Portal facets when you create a Portal EAR Project. You can selectively remove some facets before you move your portal to a production environment. For example, you can remove the WebLogic Portal Administration Console before you deploy to your production environment. For information on adding and removing facets, see the WebLogic Portal Development Guide. See also Using J2EE Shared Libraries in a Team Environment. |
For more detailed information on creating Portal EAR Projects, see the WebLogic Portal Development Guide.
Use Workshop for WebLogic to create Portal Web Projects. A Portal Web Project includes your portal’s source code and configuration files that reference J2EE Shared Libraries used by the project.
When you create a Web project, you select the Project Facets you want to include in the project, including the WebLogic Portal facets, as shown in Figure 2-2.
Tip: | It is recommended that, for development purposes, you select all of the WebLogic Portal facets when you create a Portal Web Project. You can selectively remove some facet components (features) when you move your portal to a production environment. For more information, see Using J2EE Shared Libraries in a Team Environment. |
Any application code you write is stored in files within the web project. In a typical application, your code is placed in the WebContent
directory of the web project. Any domain and application specific code supplied by Oracle is stored in J2EE Shared Libraries and referenced by your application.
For more detailed information on creating Portal Web Projects, see the WebLogic Portal Development Guide.
A datasync project is an optional project that stores general purpose portal services data that are used in the development of personalized applications and portals. These portal services include user profiles, session properties, campaigns and others.
Tip: | You can share a single datasync project among several EAR projects if you wish. |
Datasync data must be associated with an EAR to be deployed. If a datasync project is not associated with an EAR, when the EAR is deployed, the datasync data will not be deployed.
You can add a new datasync project to an EAR in two ways:
For more detailed information on creating Datasync Projects and the Datasync Project Wizard, see the WebLogic Portal Development Guide.
The code you write is physically separated from the domain and application code Oracle provides in J2EE Shared Libraries. You only need to store the application code written by you and members of your team in a source control system. Be default, your application code is placed in the WebContent
directory of your web application. Any Java source code is placed in the src
directory. Eclipse also stores project settings and other configurations in the project. These files include:
.project
files – Contains the Eclipse project information..classpath
– Contains the Java classpath settings..settings
– Contains a list of files for the project’s facets, J2EE settings, Datasync settings, and other project-specific information..datasync-project.propeties
– Used in Datasync projects.As new components are created, many of these new components need to be checked into source control. Developers need to be aware of which files that are created need to be shared in source control.
Exclude from source control any Java output directories that are specific to the web project. Typically, these directories are named build
or bin
. Also, avoid checking in any files that contain hard coded paths.
Tip: | For more information on files to exclude from source control and on creating a portable workspace ZIP file, see the Workshop for WebLogic document “Working with Source Control.” |
Three files that are commonly updated during development and need to be checked into source control include the following. These files are located in the enterprise application’s META-INF
directory.
Tip: | If you want to modify a file that is inside a J2EE Shared Library, you can copy it to your filesystem and modify it. From that point on, the file-based copy takes precedence over the version stored in the J2EE Shared Library. In a development environment, be careful to check any copied J2EE Shared Library files into source control, so that they can be shared by other developers. Not all files can be copied from a shared library. For example, .class and .jar files cannot be copied. |
The fundamental idea when working with source control management and a Workshop for WebLogic application is that developers must be able to check out the application, initiate a build, and start the server without error.
When the EAR project is deployed to the domain by Workshop for WebLogic, it is registered in the domain’s DOMAIN_ROOT/config/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 2-1 shows the block added to config.xml
for an enterprise application named myPortalEAR
.
<app-deployment>
<name>myPortalEAR</name>
<target>AdminServer</target>
<module-type>ear</module-type>
<source-path>D:\users\projects\applications\myWorkspace\.metadata\.plugins\
org.eclipse.core.resources\.projects\myPortalEAR\beadep
</source-path>
<security-dd-model>DDOnly</security-dd-model>
</app-deployment>
Because Workshop for WebLogic updates the config.xml
for the domain automatically, it is not necessary to check a config.xml
that contains the application name XML block back into source control. 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 published to the server. Workshop for WebLogic automatically updates it if necessary to add or remove components.
After checking out an application from source control, each developer needs to import it into Workshop for WebLogic. To do this, select File > Import. In the Import dialog, select Existing Projects into Workspace. Then, follow the online help instructions to locate and import the project.
Tip: | Refer to the Eclipse documentation for additional information on sharing projects in Eclipse. |
This section includes these topics:
A J2EE Shared Library is a reusable portion of a J2EE application or web application. At the enterprise application level, a J2EE Shared Library is an EAR file that can include Java classes, EJB deployments, and web applications. At the web application level, a J2EE Shared Library is a WAR file that can include servlets, JSPs, and tag libraries. The difference between a standard EAR or WAR file and a J2EE Shared Library is that shared libraries can be included in an application by reference, and multiple applications can reference a single J2EE Shared Library.
One of the most useful aspects of shared libraries for WebLogic Portal development teams is that the code developed by your team and the code that is distributed by Oracle remain physically separated. When a WebLogic Portal upgrade or patch is distributed as shared libraries, all you need to do is add the new libraries to the installation directory. The referencing applications, and the code written by your developers, automatically pick up the new modules when the application is redeployed.
Tip: | For additional detailed information on J2EE Shared Libraries, see the WebLogic Server document “Creating Shared J2EE Libraries and Optional Packages” and the WebLogic Portal Development Guide. |
Your WebLogic Portal application can reference multiple shared libraries. In turn, libraries can reference other libraries, and so on. Because the J2EE Shared Library code and your own application code is assembled at runtime, rules must exist to resolve potential conflicts. These rules are:
META-INF/weblogic-application.xml
file (for enterprise applications) or the WEB-INF/weblogic.xml
file (for web applications). These precedence rules have an important implication for the development team. For example, the team can choose to copy specific files, such as CSS files, from a J2EE Shared Library. If developers change those files in their development areas, those changes take precedence over the original shared library versions.
Tip: | Where possible, copy resources for shared libraries to a new name in your application. This practice can avoid confusion about which version is being used: the local copy or the shared library version. Sometimes this is not possible, and the precedence rules then apply. |
In addition to code and other modules and resources, shared libraries include deployment descriptors. The deployment descriptors describe the contents of the library. The following example illustrates the basic structure of an enterprise application that references a J2EE Shared Library.
For this example, assume there is an enterprise application called myApp.ear
that has the structure shown in Listing 2-2. The application includes two modules, myEjb.jar
and myWebApp.war
, plus some additional Java code in myClasses.jar
.
Note the element shown in bold in the META-INF/weblogic-application.xml
descriptor. The <library-ref>
element specifies a reference to a J2EE Shared Library called AppLibOne
.
Listing 2-3 shows the actual J2EE Shared Library, AppLibOne.ear
, referenced by the enterprise application. As you can see, this library includes a META-INF/MANIFEST.MF
file, shown in bold type, which includes the library name and version information. After a shared library is deployed, it is through this manifest that the server is able to identify it and to assemble it into the deployed application.
Tip: | See Shared Library Manifest File Contents for detailed information on the manifest file. For more information on deploying shared libraries, see Deploying J2EE Shared Libraries. |
Listing 2-4 shows the effective configuration of the final deployed application, after the deployment descriptors in the libraries have all been read and interpreted. The server deploys two EJB JAR files. The file myEjb.jar
comes from the myApp.ear
archive, and the other libEjb.jar
comes from the J2EE Shared Library. Furthermore, the application’s classpath is also ordered so that the classes in myApp
’s myClasses.jar
override any classes from the code.jar
file in the AppLibOne
J2EE Shared Library.
You can enable a J2EE module, such a WAR or EAR, to be a J2EE Shared Library by creating or modifying the archive’s META-INF/MANIFEST.MF
file. This section explains the variables that you can put in the manifest file of a J2EE Shared Library.
A sample MANIFEST.MF
file is shown in the following listing:
META-INF/MANIFEST.MF
Extension-Name: SomePortlets
Specification-Version: 1.0
Implementation-Version: 1.0
Table 2-1describes the contents of the file:
Tip: | For a more detailed description of creating a MANIFEST.MF file, see the WebLogic Server document
“Creating Shared J2EE Libraries”. |
In addition to the MANIFEST.MF
variables shown in Table 2-1, you can also use the following variables to explicitly include or exclude particular files from the Copy to Project function. This function lets you copy certain files from a shared library directly to your project workspace. To explicitly include or exclude files from Copy to Project, use these variables:
If you specify neither include nor exclude, then all files in the library that can be copied will be copied. If both include and exclude are provided, then first all the files that match the include’s regular expression will be found and the excludes will be removed from the list of included files.
The format of the BEA-EXTRACT-INCLUDE/EXCLUDE
is a regular expression (from javax.util.regex.Pattern) specifies what to exclude or include. For example if the library’s directory structure looks like the one shown in Listing 2-5:
/WEB-INF/web.xml
/WEB-INF/classes/log4j.properties
/includes/test.jsp
/includes/bob.jsp
/css/some.css
BEA-EXTRACT-INCLUDE: (/WEB-INF/[_0-9a-zA-Z ]*)|(css)
extracts all files that match /WEB-INF/
and any number of letters
that have a "_" or 0-9 or a-z or A-Z, or any file that contains /css/
. In this case, the following files will be extracted during a Copy to Project operation:
/WEB-INF/web.xml
/WEB-INF/classes/log4j.properties
/css/some.css
The regular expression is not matched against the full path of the file so in the example above, the /css/
matches all files that are in a path that include “css” somewhere; therefore, these example directories/files would also match the regular expression:
/adirectory1/css/bob.joe
/main.css
If you want to match against the full path of the file, use the ^
and $
regular expression characters. For example: ^/hiddenFolder/.*$
Listing 2-6 illustrates a manifest that includes both variables:
Extension-Name: p13n-app-lib
Specification-Version: 10.3.0
Implementation-Version: 10.3.0
BEA-EXTRACT-INCLUDE: (/META-INF/p13n-config.xml)|(css)
BEA-EXTRACT-EXCLUDE: xml
Shared libraries provide a convenient mechanism for development teams to share the portal resources that they develop with other teams.
This section includes these topics:
For example, suppose a team environment consists of one or more portlet development teams and a team that is responsible for assembling and maintaining the overall portal. Figure 2-3 illustrates the example scenario. The portal development team delivers a Shared Library (WAR) file to a portlet development team. This library file contains the portal and its associated resources, such as the portal look & feel. The portlet team receives this file and imports it as a Shared Library into its project space, making it available to the team members and providing a portal in which to test their portlets.
After the portlet team builds a set of portlets, they deliver a Shared Library (WAR) file back to the portal team. The portal team receives the WAR, imports it as a module, and adds the portlets to the portal. For detailed information on creating J2EE Shared Libraries, see the WebLogic Server document “Creating J2EE Libraries and Optional Packages.”
The basic steps involved in sharing resources as shared libraries includes the following:
MANIFEST/MANIFEST.MF
file to enable the WAR as a J2EE Shared Library. See Using J2EE Shared Libraries in a Team Environment for information on enabling a WAR as a J2EE Shared Library. For example:META-INF/MANIFEST.MF
Extension-Name: SomePortlets
Specification-Version: 1.0
Implementation-Version: 1.0
Tip: | Choose a naming convention for your portlet development that includes consistent subdirectory names. A consistent naming convention simplifies the process of packaging and delivering your source files. |
Upon receiving the Shared Library WAR file, the portal team references the Shared Library WAR file (and, optionally, its version number) in the appropriate configuration files. References to the Shared Library WAR file go in the portal web application’s weblogic.xml
and the domain’s config.xml
files.
The weblogic.xml
file contains the library name (and, optionally, version number) and the domain’s config.xml
file contains the actual path of the Shared Library WAR file. See Using J2EE Shared Libraries in a Team Environment for information on referencing a J2EE Shared Library.
Tip: | Before beginning their development phase, the portlet team might receive from the portal team a set of look & feel files, libraries, and menus to use with their portlets. If these resources are delivered to the portlet team in a J2EE Shared Library file, the portlet team can simply receive and install it by following the same procedures described in this section. In this case, the portlet team may have fewer items to remove from its Shared Library WAR file. |
You need to add the library to the Java Build Path of your project, as follows:
To incorporate the portlets into a deployed portal, the portal team uses the WebLogic Server Console to deploy the WAR file as a J2EE Shared Library.
This section provides guidance for managing portal application source code in a team development environment.
This section includes the following sections:
Tip: | For information on sharing project files using Workshop for WebLogic’s Eclipse-based integrated source control features, see the Workshop for WebLogic document “Working with Source Control.” |
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 or packaged as J2EE Shared Libraries. This enables portability of your Java libraries across multiple instances of the server and is a convenient mechanism for packaging libraries for reuse and sharing.
The best practice is to place a JAR file containing your Java libraries in the APP-INF/lib
directory of your enterprise application, or configure the JAR file as a J2EE Shared Library. For detailed information on creating J2EE Shared Libraries, see the WebLogic Server document
“Creating J2EE Libraries and Optional Packages.”
When coding to develop and deploy in a cross-platform environment, 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.A unique identifier called a definition label is generated automatically for each book, page, and portlet that you add to a portal in Workshop for WebLogic. You can view the definition label for a component in Workshop for WebLogic in the Properties view.
With multiple developers creating new portal components, it is possible that different components can have the same automatically generated definition label. To avoid duplicate definition labels, manually change the definition label for each new component using your own naming conventions.
For information on modifying definition labels, see the Portal Development Guide.
WARNING: | Once you have used the propagation tools to propagate changes among your environments, it is very important that you do not change the definition labels for portlets, pages, and books. The propagation tools use definition labels and instance labels to identify differences between source and destination systems; inconsistent results might occur if you change these labels after propagating a portal. |
Any code you write should be tested often in a clustered environment. Also, keep session data to a manageable size and configure your web applications to support session sharing across the cluster. Be sure that session data is serializable. For clustering information, see Configuring a Portal Cluster.
Tip: | WebLogic Server provides a session monitor tool that is useful for debugging HTTP session problems. See the WebLogic Server document “Class SessionMonitor” for more information. |
A number of binary files in the WebLogic Server domain need to be checked into source control management for the domain to function properly. Some of these files, such as database files, can be modified during the course of WebLogic Portal development.
These binary files may change for various reasons: user-initiated reasons, automatic growth of index files, and so on. It is important to understand what these files are, why they change, and when to check them in and out.
This section explains how to determine when you need to update specific binary files in source control management. Some of these files include: LDAP files, security-related files, and database configuration files.
This section includes these topics:
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. To reduce the chances of merge conflicts over the project life cycle, it is recommended that changes to binaries be initiated consistently by a single user.
If, for any reason, you need to modify domain binary file(s) in source control, follow this procedure:
A common activity in development is the creation of a base set of users and groups that are used to test the system. By default, WebLogic Server stores users and groups in the PointBase RDMBS. A relationship exists between LDAP policy data and database data to support user entitlements. An embedded LDAP server is provided with WebLogic Portal. This LDAP server persists its data store to the filesystem in the <DOMAIN_HOME>/servers/
AdminServerName
/data/ldap
directory.
For information on Oracle’s LDAP server, see the WebLogic Server document Managing the Embedded LDAP Server.
Because the LDAP server contains information, including role and security policies, 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-4, Domain Files to Exclude from Source Control, on page 2-34).
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 Portal Administration Console. It is important to maintain database and LDAP changes in source control.
For detailed information on entitlements, see the WebLogic Portal Security Guide. For detailed information on users and groups, see the WebLogic Portal User Management Guide.
Other important security files located in the domain are the SerializedSystemIni.dat
, DefaultAuthenticatorInit.ldift
, DefaultAuthorizerInit.ldift
, and DefaultRoleMapperInit.ldift
files. These files are located in the <DOMAIN_HOME>/security
directory, where <DOMAIN_HOME>
is the root directory for your domain.
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 <DOMAIN_HOME>/servers/AdminServer/security/boot.properties
file 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.
For more information about security, see the WebLogic Portal Security Guide.
Using Shared J2EE Libraries to share resources among development teams, as well as third-party development teams, will be sufficient for many cases. In some cases, however, you might want to develop a project facet that includes a bundle of features you have developed and that can be installed by developers when they create a new project in Workshop for WebLogic.
Before WebLogic Portal 9.2, you could create project templates and include them in your project from Workshop for WebLogic. The equivalent feature in WebLogic Portal 9.2 and later versions is handled using an Eclipse plugin. Workshop for WebLogic uses the concept of facets (from the Eclipse Web Tools Platform (WTP): http://www.eclipse.org/webtools
).
A facet is a set of functionality you can add to your project. The facets show up in the wizard when you create a new project. When you select a facet, Workshop for WebLogic installs all of the facet’s components into your project.
Facet development is the next step for those partners and developers who want to integrate features directly into Workshop for WebLogic.
WebLogic Portal includes a Library Modules for Project Features extension point, which allows you to define a facet to include one or more J2EE Shared Libraries, as well as other resources to go into the project classpath. Developing such a plugin is straightforward, and does not necessarily involve any code. Typically, you just need to write a plugin.xml
file. Of course, you can also include code for views or editors or other tools in your plugin, but to simply have your facet show up in Workshop for WebLogic, no code is required.
If the recommended approach to creating and sharing a portal domain among team members, as discussed in Creating a Shared WebLogic Portal Domain, is not sufficient, this section presents alternative techniques.
This section includes these topics:
The directory where WebLogic Platform software is installed on a given system is called the BEA home directory. Figure 2-4 shows an example of a home directory. Each development machine in your team environment will have its own BEA home directory.
Because Workshop for WebLogic applications and domains each reference the BEA home directory, it is important to carefully consider where to put the BEA home directory. The simplest configuration occurs when every machine in your team environment uses exactly the same BEA home directory (the same drive/directory name). If this is not the case, then you need to choose a strategy for managing the different BEA home directory locations. These strategies are explained in this section.
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 a portal domain’s config/config.xml
file on each development machine, in domain batch scripts such as startWeblogic.cmd
, and in other domain files (see Table 2-3 for a complete list).
For example, Listing 2-7 shows part of a config.xml
file. In this example, the <source-path>
element points to a J2EE Shared Library file in a subdirectory of D:\myBeaHome
. In this case D:\myBeaHome
is the BEA home directory.
<library>
<name>p13n-app-lib#10.3.0@10.3.0</name>
<target>AdminServer</target>
<source-path>D:\myBeaHome\wlportal_10.3\p13n\lib\j2ee-modules\p13n-app-lib.ear
</source-path>
<deployment-order>1</deployment-order>
<security-dd-model>DDOnly</security-dd-model>
</library>
If the config.xml
and other domain files are shared in source control, either all team members must have installed WebLogic Server to the BEA home directory path hard-coded in those files, or another strategy must be used. Strategies for maintaining different BEA home directories on different machines are discussed later in the next section Managing Multiple BEA Home Directory Locations for Your Team.
Table 2-3 lists all of the files in a domain that contain hard-coded BEA home directory paths. The files listed in Table 2-3 are relative to the root directory of the domain.
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 content-equivalent domain with team members with different BEA home directories. These options are described in the following sections.
You can use a string substitution script to execute search and replace activities on your config.xml
and other domain files. For example, you can use the Ant Copy task with a filter to perform the string substitutions. You can make a copy of config.xml
(for example, renaming it config-subst.xml
), replace hard-coded paths with variables, and check in the copy. Then, each developer can check out the copy with the variables and run the string substitution script.
A string substitution script can be used for 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 this option, developers on a team each configure on their machines a common virtual drive letter. This drive is then used as a substitute for the true BEA home directory, which any given developer can place anywhere they wish. The configuration files and start scripts shown in Table 2-3, Domain Files with Hard-Coded Paths, on page 2-30 can then be edited to use the virtual drive in place of the BEA home directory, and these files can then be shared among all team members.
For example, if your BEA home directory is currently D:\<BEA-HOME>
, the general procedure for creating a substitute drive letter to map to your BEA home directory is as follows:
where <BEA_HOME>
is the name of your BEA home directory, for example: D:\myBEA
. And where newDrive
is the letter of the drive to which you want to map the BEA home directory, for example P
.
Tip: | If other developers install WebLogic Server to a different location, such as D:\bea , they can make a similar substitution, such as subst P: d:\bea , and share the same config.xml and start scripts. |
Drawbacks of this option include the following:
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.ln
command.
If the domain and application directories on each developer’s machine are located in a common relative path to the BEA home directory, it is possible to change all file paths in config.xml
and your start scripts to be relative paths.
Assuming the domain is installed to D:\myBeaHome\user_projects\mydomain
, where the BEA home directory is D:\myBeaHome
, the sample config.xml
entries shown in Listing 2-7 would now look like Listing 2-8, with the changes highlighted in bold type:
<library>
<name>p13n-app-lib#10.3.0@10.3.0</name>
<target>AdminServer</target>
<source-path>../../wlportal_10.3/common/deployable-libraries/p13n-app-lib.ear
</source-path>
<deployment-order>1</deployment-order>
<security-dd-model>DDOnly</security-dd-model>
</library>
Of course, as with the previous option, all files listed in Table 2-3, Domain Files with Hard-Coded Paths, on page 2-30 would have to be modified in the same way.
Drawbacks of this option include the following:
This section explains an approach to sharing a portal domain among team members. This approach is an alternative to the recommended approach discussed in Creating a Shared WebLogic Portal Domain.
Create a common domain root directory (%DOMAINNAME
) in your source control system for the domain.
Note: | Domain creation is discussed in Creating a Shared WebLogic Portal Domain. Application creation is discussed in detail in Creating and Sharing the Portal Application. |
Create the domain using the WebLogic Configuration Wizard or a script. For detailed information on using the Configuration Wizard, see the WebLogic Server document “Creating WebLogic Configurations Using the Configuration Wizard.” For detailed information on building a domain programmatically with a script, see the WebLogic Server document, “Creating and Configuring WebLogic Domains Using WLST Offline.” For an overview of the files that are installed with a domain, see the WebLogic Server document “Domain Configuration Files.”
Tip: | For information on sharing project files using Workshop for WebLogic’s Eclipse-based integrated source control features, see the Workshop for WebLogic document “Working with Source Control.” |
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-4 lists some files that are created after you start the server, and that you will want to exclude from source control.
Start WebLogic Server using the domain’s DOMAIN_ROOT/bin/startWeblogic
command. You can find this command in the domain’s root directory.
See Configuring and Tuning the Domain.
![]() ![]() ![]() |