| Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal 10g Release 3 (10.3.2) Part Number E14245-02 |
|
|
View PDF |
| Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal 10g Release 3 (10.3.2) Part Number E14245-02 |
|
|
View PDF |
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 Oracle Fusion Middleware Quick Start Guide for Oracle WebLogic Portal. 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 Oracle Enterprise Pack for Eclipse-based integrated source control features, see the Oracle Enterprise Pack for Eclipse 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 Oracle Fusion Middleware Creating 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 Section 2.3.3, "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 Oracle Fusion Middleware Creating Domains 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 Oracle Fusion Middleware Creating Domain Templates Using the Domain 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 Oracle Fusion Middleware Creating Domains Using the Configuration Wizard. For an overview of the files that are installed with a domain, see "Domain Configuration Files" in Oracle Fusion Middleware Understanding Domain Configuration for Oracle WebLogic Server.
Tip:
For detailed information on building a domain programmatically with a script, see "Creating and Configuring WebLogic Domains Using WLST Offline" in Oracle Fusion Middleware Oracle WebLogic Scripting Tool.Tip:
A common activity in development is the creation of a base set of users that are used to test the system. See also Section 2.9.2, "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" in Oracle Fusion Middleware Information Roadmap 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 Oracle Fusion Middleware Database Administration Guide for Oracle WebLogic Portal. For more information on working with the PointBase database, see Section 2.4.4, "Using the PointBase Database."
This section includes these sections:
Section 2.4.1, "Developing Against an Enterprise-Quality Database"
Section 2.4.2, "Using Different Databases in Development and Production"
Section 2.4.3, "Knowing When You are Making Changes to the Database"
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 Oracle Fusion Middleware Database Administration Guide for Oracle WebLogic Portal.
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 Chapter 7, "Using Oracle Enterprise Pack for Eclipse 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 Oracle Fusion Middleware Security Guide for Oracle WebLogic Portal.
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 Section 2.9, "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:
set POINTBASE_FLAG=false
On a UNIX system, in the file <DOMAIN_HOME>/bin/setDomainEnv.sh, enter:
POINTBASE_FLAG="false"
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:
weblogic_eval.*
pointbase.*
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 "Creating Shared Java EE Libraries and Optional Packages" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server. Shared Libraries are also discussed in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal and Section 4.8, "Deploying J2EE Shared Libraries."Like domain creation, application creation occurs in several steps. These steps are explained in this section. They include:
Section 2.5.1, "Create or Locate the Eclipse Workspace Directory"
Section 2.5.6, "Check Out the Oracle Enterprise Pack for Eclipse Application"
All projects created with Oracle Enterprise Pack for Eclipse are created inside a Workspace directory. For more information on creating workspaces and projects, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Use Oracle Enterprise Pack for Eclipse 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 Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. See also Section 2.6, "Using J2EE Shared Libraries in a Team Environment."For more detailed information on creating Portal EAR Projects, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Use Oracle Enterprise Pack for Eclipse 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 Section 2.6, "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 Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
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:
When the datasync project is created, you can associate it with an EAR using the Datasync Project Wizard.
You can associate a datasync project with an EAR by right-clicking the datasync project in Oracle Enterprise Pack for Eclipse and selecting Properties. In the Properties for data dialog, select Datasync > EAR Projects. In the Ear Projects panel, select the EAR file to add the datasync project to.
For more detailed information on creating Datasync Projects and the Datasync Project Wizard, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal
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 class path 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 Oracle Enterprise Pack for Eclipse 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.
application.xml – Lists the web applications associated with the enterprise application.
weblogic-application.xml – Lists the J2EE Shared Libraries used by the enterprise application.
content-config.xml – Specifies the default content repository used by the application.
Tip:
.class.jar files cannot be copied.The fundamental idea when working with source control management and a Oracle Enterprise Pack for Eclipse 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 Oracle Enterprise Pack for Eclipse, 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.
Example 2-1 shows the block added to config.xml for an enterprise application named myPortalEAR.
Example 2-1 Application Added to config.xml File
<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 Oracle Enterprise Pack for Eclipse 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. Oracle Enterprise Pack for Eclipse 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 Oracle Enterprise Pack for Eclipse. 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 Creating Shared Java EE Libraries and Optional Packages" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server and the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.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:
Any file that is located in your application takes precedence over a file that is in a J2EE Shared Library.
Conflicts arising between referenced libraries are resolved based on the order in which the libraries are specified in the 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 Figure 2-3. 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.
Figure 2-4 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 Section 2.6.4, "Shared Library Manifest File Contents" for detailed information on the manifest file. For more information on deploying shared libraries, see Section 4.8, "Deploying J2EE Shared Libraries."Example 2-1 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 class path 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-1 describes the contents of the file:
Table 2-1 MANIFEST.MF Variables
| Variable | Description |
|---|---|
Extension-Name |
An optional string value that identifies the name of the shared J2EE library. It is a best practice to always specify a name; otherwise, a name is automatically generated based on the deployment name of the library. |
Specification-Version |
An optional String value that defines the specification version of the shared J2EE library. |
Implementation-Version |
An optional String value that defines the code implementation version of the shared J2EE library. You can provide an Implementation-Version only if you have also defined a Specification-Version. |
Tip:
For a more detailed description of creating a MANIFEST.MF file, see Creating Shared Java EE Libraries and Optional Packages" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.In addition to the MANIFEST.MF variables shown in Table 2-2, 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:
Table 2-2 MANIFEST.MF Include and Exclude Variables
| Variable | Description |
|---|---|
BEA-EXTRACT-EXCLUDE |
All files except those matching the specified regular expression will be extracted. |
BEA-EXTRACT-INCLUDE |
Only the files matching the specified regular expression will be extracted. |
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 Example 2-2:
Example 2-2 Sample Library Structure
/WEB-INF/web.xml /WEB-INF/classes/log4j.properties /includes/test.jsp /includes/bob.jsp /css/some.css
Then the manifest entry:
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/.*$
Example 2-3 illustrates a manifest that includes both variables:
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-6 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 Creating Shared Java EE Libraries and Optional Packages" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.
Figure 2-6 Sharing Portal Resources in a Team Environment
The basic steps involved in sharing resources as shared libraries includes the following:
The portlet team develops and tests portlets using a test portal environment.
The portlet team adds appropriate stanzas to the Shared Library WAR file's MANIFEST/MANIFEST.MF file to enable the WAR as a J2EE Shared Library. See Section 2.6, "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
The portlet team uses Oracle Enterprise Pack for Eclipse to export a project as a WAR file (select File > Export).
The portlet team removes from the Shared Library WAR file any files and code that are not strictly required by the portlets. For instance, any test files used by the development team can be excluded.
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.The portlet team sends the Shared Library WAR file to the portal team.
The portal team imports the library, as explained in the next section.
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 Section 2.6, "Using J2EE Shared Libraries in a Team Environment" for information on referencing a J2EE Shared Library.
Tip:
Shared Library WAR file.You need to add the library to the Java Build Path of your project, as follows:
Right-click the project in the Package Explorer and select Build Path > Add Libraries.
In the Add Library dialog, select WebLogic J2EE Library and click Next.
In the WebLogic J2EE Library dialog, browse to the library file that you want to add and select it. If you want to specify a version, enter the appropriate version information in the dialog, and click Finish.
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 Oracle Enterprise Pack for Eclipse's integrated source control features, see the Oracle Enterprise Pack for Eclipse 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 Creating Shared Java EE Libraries and Optional Packages" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.
When coding to develop and deploy in a cross-platform environment, observe the following best practices:
Do not use spaces in filenames.
Keep path names short.
When possible, do not hard code path names.
Use forward slashes ( / ) in path strings when possible.
Be aware of the difference between case-sensitive operating systems (UNIX) and other operating systems, such as Windows. For example, you could create a file called 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 Oracle Enterprise Pack for Eclipse. You can view the definition label for a component in Oracle Enterprise Pack for Eclipse 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 Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Caution:
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 Chapter 3, "Configuring a Portal Cluster."
Tip:
WebLogic Server provides a session monitor tool that is useful for debugging HTTP session problems. For information on the SessionMonitor class, see Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal.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:
Section 2.9.1, "General Procedure for Working with Binary Files"
Section 2.9.2, "Updating Users, Groups, Roles, and Entitlements"
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:
Stop the server.
Perform a clean checkout of the binary files from source control to ensure you are working from a common base.
Start the server.
Modify the configuration stored in the binary file(s).
Stop the server.
Check-in any modified binary files to source control management.
Test a clean checkout from another machine.
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 file system in the <DOMAIN_HOME>/servers/AdminServerName/data/ldap directory.
For information on Oracle's LDAP server, see "Managing the Embedded LDAP Server" in Oracle Fusion Middleware Securing Oracle WebLogic 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 2-4, "Domain Files to Exclude from Source Control").
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 Oracle Fusion Middleware Security Guide for Oracle WebLogic Portal. For detailed information on users and groups, see the Oracle Fusion Middleware User Management Guide for Oracle WebLogic Portal.
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 user name 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 Oracle Fusion Middleware Security Guide for Oracle WebLogic Portal.
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 Oracle Enterprise Pack for Eclipse.
Before WebLogic Portal 9.2, you could create project templates and include them in your project from Oracle Enterprise Pack for Eclipse. The equivalent feature in WebLogic Portal 9.2 and later versions is handled using an Eclipse plugin. Oracle Enterprise Pack for Eclipse 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, Oracle Enterprise Pack for Eclipse 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 Oracle Enterprise Pack for Eclipse.
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 class path. 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 Oracle Enterprise Pack for Eclipse, no code is required.
If the recommended approach to creating and sharing a portal domain among team members, as discussed in Section 2.3, "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 Middleware Home directory. When you install the software, you can provide this name. By convention, this directory is called MW_HOME throughout WebLogic Portal documentation. Figure 2-7 shows the default Middleware Home directory. Each development machine in your team environment will have its own Middleware Home directory.
Because Oracle Enterprise Pack for Eclipse applications and domains each reference the Middleware Home directory, it is important to carefully consider where to put the Middleware Home directory. The simplest configuration occurs when every machine in your team environment uses exactly the same Middleware Home directory (the same drive/directory name). If this is not the case, then you need to choose a strategy for managing the different Middleware Home directory locations. These strategies are explained in this section.
When creating a new portal domain with the domain Configuration Wizard, you choose which Middleware 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, Example 2-4 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:\myMwHome. In this case D:\myMwHome is the Middleware Home directory.
Example 2-4 Middleware Home Directory Referenced in a config.xml File
<library>
<name>p13n-app-lib#10.3.0@10.3.0</name>
<target>AdminServer</target>
<source-path>D:\myMwHome\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 Middleware Home directory path hard-coded in those files, or another strategy must be used. Strategies for maintaining different Middleware Home directories on different machines are discussed later in the next section Section 2.11.1.2, "Managing Multiple Middleware Home Directory Locations for Your Team."
Table 2-3 lists all of the files in a domain that contain hard-coded Middleware Home directory paths. The files listed in Table 2-3 are relative to the root directory of the domain.
Table 2-3 Domain Files with Hard-Coded Paths
| File | Notes |
|---|---|
|
create_db.* |
WL_HOME |
pointbase.ini |
|
|
config/config.xml |
|
|
bin/setDomainEnv.* |
|
|
bin/startManagedWebLogic.* |
|
|
bin/startPointBaseConsole.* |
DOMAIN_HOME |
|
bin/startWebLogic.* |
DOMAIN_HOME |
|
bin/stopManagedWebLogic.* |
DOMAIN_HOME |
|
bin/stopWebLogic.* |
DOMAIN_HOME |
|
init-info/domain-info.xml |
Output of the Domain Configuration Wizard. This file is needed if you want to use the Configuration Wizard to update the domain. |
|
init-info/startscript.xml |
Output of the Domain Configuration Wizard. This file is needed if you want to use the Configuration Wizard to update the domain. |
The next section contains strategies to employ when not all team members can use the same Middleware Home directory.
If all team members can use the same Middleware Home directory, skip to Section 2.11.2, "Creating and Sharing the Portal Domain."
There are a number of different techniques for sharing a content-equivalent domain with team members with different Middleware 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 Middleware 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 Middleware 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" can then be edited to use the virtual drive in place of the Middleware Home directory, and these files can then be shared among all team members.
For example, if your Middleware Home directory is currently D:\<BEA-HOME>, the general procedure for creating a substitute drive letter to map to your Middleware Home directory is as follows:
Run the following command from a Windows Command Prompt:
subst newDrive: D:\<MW_HOME>
where <MW_HOME> is the name of your main product installation directory, for example: D:\myBEA. And where newDrive is the letter of the drive to which you want to map the Middleware Home directory, for example P.
Create a new domain.
When you want to use the domain, switch to the new drive and go into the domain directory.
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:
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.
Users must run the created domain and application from the new virtual drive. Running the domain from the "true" install drive and path will result in errors.
This technique is Windows Operating System specific; however, UNIX developers can follow a similar technique using symbolic links with the ln command.
If the domain and application directories on each developer's machine are located in a common relative path to the Middleware 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:\myMwHome\user_projects\mydomain, where the Middleware Home directory is D:\myMwHome, the sample config.xml entries shown in Example 2-4 would now look like Example 2-5, with the changes highlighted in bold type:
Example 2-5 Middleware Home Directory Referenced in a config.xml File
<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" would have to be modified in the same way.
Drawbacks of this option include the following:
No ability to span multiple drives.
The domain directory must always be in the exact same relative location to the Middleware Home directory,
This section explains an approach to sharing a portal domain among team members. This approach is an alternative to the recommended approach discussed in Section 2.3, "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 Section 2.3, "Creating a Shared WebLogic Portal Domain." Application creation is discussed in detail in Section 2.5, "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 Oracle Fusion Middleware Creating Domains Using the Configuration Wizard. For detailed information on building a domain programmatically with a script, see the WebLogic Server document, "Creating Domains Using WLST Offline" in Oracle Fusion Middleware Oracle WebLogic Scripting Tool. For an overview of the files that are installed with a domain, see "Domain Configuration Files" in Oracle Fusion Middleware Understanding Domain Configuration for Oracle WebLogic Server.
Tip:
For information on sharing project files using Oracle Enterprise Pack for Eclipse's integrated source control features, see the Oracle Enterprise Pack for Eclipse 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.
Table 2-4 Domain Files to Exclude from Source Control
| Path Relative to the Domain Root | File or Files to Exclude from Source Control |
|---|---|
/config/config.xml |
Exclude |
/ |
*.log |
|
/servers/ |
* |
/servers/AdminServer/cache
|
|
/servers/AdminServer/tmp/
|
|
/servers/AdminServer/ldap/
log/ |
* |
Start WebLogic Server using the domain's DOMAIN_ROOT/bin/startWeblogic command. You can find this command in the domain's root directory.
|
 Copyright © 2010, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|