| Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal 10g Release 3 (10.3.6) E14245-05 |
|
|
View PDF |
| Oracle® Fusion Middleware Production Operations Guide for Oracle WebLogic Portal 10g Release 3 (10.3.6) E14245-05 |
|
|
View PDF |
The propagation Ant tasks provide a full set of tools that you can use to propagate WebLogic Portal assets from one environment to another using Ant scripts.
This chapter introduces the propagation Ant tasks and discusses related topics such as scoping and policies. This chapter includes the following sections:
The Ant tasks let you perform all of the functions that you can perform with the Oracle Enterprise Pack for Eclipse propagation tools, plus additional options and functions, such as placing the server into maintenance mode. The Ant tasks:
Allow you to automate the propagation process.
Provide a richer set of features than the Oracle Enterprise Pack for Eclipse propagation tools.
Note:
The Administration Server must be running when you perform a propagation to allow certain LDAP data to be updated. A propagation can cause the following kinds of LDAP data to be added, deleted, or updated: visitor roles, delegated administration roles, entitlement policies, and delegated administration policies.
Before you attempt to propagate a portal web application using the Ant tasks described in this chapter, it is important to be familiar with the basic concepts of WebLogic Portal propagation. For detailed information on planning a propagation strategy, see Chapter 5, "Developing a Propagation Strategy." The Ant tasks provide the same basic features as the Oracle Enterprise Pack for Eclipse propagation tools. The basic concepts and considerations outlined in Chapter 6, "Propagation Topics" apply to both the propagation tools and to the Ant tasks.
Note:
We also recommend that you read Chapter 7, "Using Oracle Enterprise Pack for Eclipse Propagation Tools" before designing an Ant-based propagation script. This chapter describes how to propagate a portal using the Oracle Enterprise Pack for Eclipse propagation tools. These tools step you through the propagation process and provides a visual interface for merging, viewing, and tuning inventories. Reviewing and understanding the workflow used by the propagation tools can be useful to you as you plan your Ant-based propagation.
The Ant tasks are divided into two categories: online and offline. The online tasks interact with a WebLogic Portal application that is deployed and running. For example, the OnlineDownloadTask lets you extract a portal inventory from a live server and store it in a file. To accomplish this, the task communicates with a servlet that is deployed with the enterprise application. The online tasks are summarized in Section 8.4, "Overview of Online Tasks."
The offline tasks operate on inventory files that have already been extracted and saved. The offline tasks do not require network connectivity. Note that online tasks require a running server with the propagation servlet deployed; offline tasks to not. The offline tasks are summarized in Section 8.5, "Overview of Offline Tasks."
To use either the online or offline Ant tasks, you need to put the JAR files containing the tasks in your CLASSPATH. To use the online tasks, you also need to deploy a library module with the Portal EAR Project on the source and destination systems.
This section includes these installation topics:
A servlet that handles propagation requests is provided with your WebLogic Portal installation. If you intend to use the online Ant tasks, this servlet must be deployed in the Portal EAR Project that contains the portal application(s) you want to propagate.
By default, the Propagation Service facet is included in a Portal EAR Project, as shown in Figure 8-1. This facet includes the propagation servlet. If you created the Portal EAR Project with the Propagation Service facet selected, then the propagation servlet is automatically deployed when you deploy the EAR to the server.
When it is deployed, you can access the servlet as follows:
http://server:port/earProjectNamePropagation/inventorymanagement
Where earProjectName is the name of the EAR project that contains the portal application that you are propagating. For example: myEARProjectPropagation
Tip:
You can see that the servlet has been added to your application by looking in the application's META-INF/weblogic-application.xml file. Example 8-0 shows the stanzas added for the example application, myEarProject.
Example 8-1 Propagation Servlet Configuration
<library-ref>
<library-name>wlp-propagation-app-lib</library-name>
</library-ref>
<library-context-root-override>
<context-root>propagation</context-root>
<override-value>myEarProjectPropagation</override-value>
</library-context-root-override>
You need to know the name of the propagation servlet when you use the online Ant tasks, because these tasks use the propagation servlet to process their requests. For example, the online tasks take a serverURL parameter that requires the propagation servlet address. The servlet address is as follows:
http://server:port/earProjectNamePropagation/inventorymanagement
Where earProjectName is the name of the EAR project that contains the portal application that you are propagating. For example: myEARProjectPropagation
You can check whether the propagation servlet is included in your EAR project by doing the following:
Open Oracle Enterprise Pack for Eclipse.
Right-click the EAR project in the Package Explorer, and select Properties. The Project Facets dialog appears.
In the Project Facets dialog, be sure that the Propagation Service facet is included.
Click OK to complete the operation.
WebLogic Portal provides a sample Ant build script that you can use to execute each of the propagation Ant tasks. This section explains how to use the sample build script to test that the propagation servlet is installed correctly. The sample build script is:
<WLPORTAL_HOME>/propagation/bin/propagation_ant.xml
Start the WebLogic Portal server in which your portal EAR project is deployed.
Edit the sample build script appropriately to include correct values for your WebLogic Portal installation directory, a directory in which to write script output, the propagation servlet URL, and other information.
Tip:
The script file includes detailed information about the variables you need to provide. Be sure to read the instructions in the script carefully.
After you have properly configured the build script variables, run the OnlinePingTask. To do this, enter the following command.
ant -f propagation_ant.xml pingSrc
If the operation succeeds, the server was contacted successfully.
Tip:
You can copy the propagation_ant.xml build script and use it as a basis for creating your own custom propagation build scripts. Note that the sample script includes examples of running each task both with and without a condition property. The condition property, provided by the Ant ConditionTask, allows you to implement simple flow control in the Ant script.
To use the online or offline Ant tasks outside of a WebLogic Portal environment, you need to copy a set of JAR files from a WebLogic Portal installation to your local environment. These JAR files must be placed in the CLASSPATH for the Ant tasks on the system where you intend to use them.
<WLPORTAL_HOME>/p13n/lib/system/p13n_common.jar <WLPORTAL_HOME>/propagation/lib/propagation.jar <WLPORTAL_HOME>/propagation/lib/propagation_ant.jar <WLPORTAL_HOME>/propagation/lib/content_prop.jar <WLPORTAL_HOME>/propagation/lib/netuix_prop.jar
<WLPORTAL_HOME>/p13n/lib/system/p13n_common.jar <WLPORTAL_HOME>/propagation/lib/propagation.jar <WLPORTAL_HOME>/propagation/lib/propagation_ant.jar <WLPORTAL_HOME>/propagation/lib/content_prop.jar <WLPORTAL_HOME>/propagation/lib/netuix_prop.jar <WEBLOGIC_HOME>/server/lib/api.jar <WEBLOGIC_HOME>/server/lib/webserviceclient.jar <MW_HOME>/modules/com.bea.core.xml.beaxmlbeans_2.2.0.0.jar <MW_HOME>/modules/com.bea.core.weblogic.stax_1.4.0.0.jar <MW_HOME>/modules/com.bea.core.utils_1.4.0.0.jar
The online tasks operate on a WebLogic Portal application that is deployed and running. They communicate with the portal application through a servlet that is deployed with the enterprise application. For example, online tasks let you create and download inventory files from the server to another machine. For information on the propagation servlet, see Section 8.3.1, "Deploying the Propagation Servlet."
Note:
The online Ant tasks use HTTP or HTTPS to contact the propagation servlet, therefore you must make sure that the intervening firewalls allow that.
This section includes these topics:
Table 8-1 summarizes the online propagation Ant tasks. See Chapter 9, "Propagation Ant Task Reference" for details on each task.
| Task | Description |
|---|---|
|
Verifies that the propagation servlet is not currently in use by another process. |
|
|
Commits an inventory to a server. |
|
|
Downloads the inventory from a currently running WebLogic Portal application to a specified ZIP file. |
|
|
Prevents administrators from making changes to the portal through the WebLogic Portal Administration Console. |
|
|
Tests if the propagation management servlet is running on the designated server. |
|
|
Uploads an inventory to a running server. |
To use HTTPS with the online Ant tasks, follow the standard WebLogic SSL instructions found in the WebLogic Server document, "Configuring Identity and Trust" in Oracle Fusion Middleware Securing Oracle WebLogic Server.
Note:
When formatting the URL to the remote WebLogic server, be sure to specify the actual host name of the system rather than localhost if you are on the same system. Also, be sure to use the HTTPS port number for the server. The default is 7002.
If an online propagation Ant task fails, typically the failure is caused by one of these reasons:
The server on which the source or destination portal application is deployed has not been started. Verify that the server or cluster has been started.
The propagation servlet is not deployed. Follow the instructions in Section 8.3.1, "Deploying the Propagation Servlet" to deploy the servlet.
There is a network problem. Use an operating system utility to make sure the server can be reached.
The propagation servlet is in use by another process. Only one thread can use the propagation servlet at one time. You can use the OnlineCheckMutexTask to check to see if another process is currently using the servlet.
Offline Ant tasks operate exclusively on previously exported inventory files. These tasks operate on a single inventory file or on two inventory files to explore and manipulate the contents of the inventor(ies). The offline tasks provide features similar to the Oracle Enterprise Pack for Eclipse propagation tools. See Chapter 9, "Propagation Ant Task Reference" for details on each task.
These tasks do not require connectivity to a running WebLogic Portal application. For instance, you can use offline tasks to combine and compare source and destination inventory files.
This section includes these topics:
Table 8-2 lists the offline propagation Ant tasks.
| Task | Description |
|---|---|
|
Tests for the presence of manual elections (changes). |
|
|
Combines |
|
|
Differences |
|
|
Allows for algebraic operations on two change manifest files. |
|
|
Extracts the working artifacts out of |
|
|
Inserts updated working artifacts into |
|
|
Exports the valid policies from an inventory file. |
|
|
Creates a list of all the taxonomies in an inventory. |
|
|
Finds nodes with a specific string in their name, to help verify the wanted node was exported. |
|
|
Makes sure |
If an offline propagation Ant task fails, typically the failure is caused by one of these reasons:
The input parameters are not properly specified.
An unexpected error occurred, such as encountering a full disk.
A missing JAR file in the class path.
Scoping refers to limiting the number of artifacts in an exported WebLogic Portal inventory, and, therefore, the number of artifacts that must be added, deleted, or updated during propagation. In general, scoping reduces both the duration and complexity of propagation operations.
Tip:
Before continuing, we recommend you review the detailed discussion of scoping, in Section 6.5, "Understanding Scope."
This section includes these topics:
Several of the Ant tasks either create or use a property file, by default called scope.properites, that specifies scoping rules.
For example, you can edit the scope.properties file to adjust the propagation scope and then use the file as a parameter to the OnlineDownloadTask. This file declares how the task is to treat each node in the inventory as either in scope or out of scope. The task looks at the scoping rules and applies them to the exported inventory. As a result, the scoped inventory file is usually a subset of the full inventory. For more information on the scope.properties file, see Section 8.6.3, "Understanding a Scope Property File."
This section explains the basic workflow for scoping an inventory using the Ant tasks. The objective of this workflow is to reduce the size and complexity of an inventory file through scoping. The result of this workflow is a scope.properties file. This file contains a set of scoping rules that you can then use when you combine two inventories to produce a final merged inventory.
The Ant tasks used in this workflow include:
OnlineDownloadTask – This task is used to retrieve an inventory file from a WebLogic Portal application that is running on a server.
OfflineListScopesTask – This task exports the valid scopes from an inventory file. You can specify the depth of the scope. The depth limits how far into the inventory tree the task traverses. This task produces a scope.properties file, which you can edit.
OfflineExtractTask – This task exports files that are stored in the top level of an inventory ZIP file. One of these files is a scope.properties file.
Figure 8-2 illustrates the basic steps involved in scoping an inventory file. This procedure uses Ant tasks in a chain to produce the final output: a scope.properties file containing the scoping information needed to combine inventories.
The steps shown in Figure 8-2 include the following:
Call the OnlineDownloadTask. The first time you call this task, do not specify the scopeFile attribute. If you do not specify this attribute, the task retrieves the entire inventory from the server. The retrieved inventory is stored in a ZIP file, which is shown in Figure 8-2 as fullInventory.zip.
Use OfflineListScopesTask to extract a scope.properties file from the inventory file. The scope.properties file specifies the scoping rules that were used to produce the inventory. See Section 8.6.3, "Understanding a Scope Property File" for more information on the contents of a scope.properties file. To produce a scoped inventory, edit the scope.properties file and use the edited file as input to the OnlineDownloadTask again.
Run the OnlineDownloadTask again with the edited scope.properties file as input. The result of this operation is a new inventory file that only includes the artifacts that were within the specified scope.
The final step in this workflow is optional. It is included in Figure 8-2 to show that you can extract the scope.properties file from the scoped inventory file. In fact, the properties file that is returned is identical to the one that was used as input to the OnlineDownloadTask in Step 3.
After you have obtained a scoped source inventory file, you can combine it with a destination inventory file to produce a merged inventory file.
The taxonomies listed in a scope.properties file indicate that the given taxonomy and all of its children will be included in the inventory. For example, Example 8-2 shows a one-line scope.properties file, with only the taxonomy value Application specified. This taxonomy indicates that the entire application will be included in the inventory.
Example 8-3 is another simple scope file instruction, that indicates that all content from every repository associated with the application will be included in the inventory.
Example 8-4 indicates that only the content node node1 and its children and content type typeA and its children will be included.
Example 8-4 Excerpt from a scope.properties File
scope_0=Application\:ContentServices\:Tools_Repository\:ContentNodes\:node1 scope_1=Application\:ContentServices\:Tools_Repository\:ContentTypes\:typeA
In summary, the taxonomies listed in the previous examples have the following meanings:
Application
Application is the root of all taxonomies and includes everything. If you scope to this taxonomy value, the entire application will be included in the inventory.
Application\:ContentServices
Includes all content from every repository.
Application\:ContentServices\:Tools_Repository
Includes all content from the Tools_Repository content repository.
Application\:ContentServices\:Tools_Repository\:ContentNodes
Includes all content nodes in the Tools_Repository content repository.
Application\:ContentServices\:Tools_Repository\:ContentNodes\:node1
Includes node1 and all its children in the Tools_Repository content repository.
Policies let you control how source and destination inventories are merged when they are combined into a final inventory file. To use policies, export a policy.properties file using the OfflineListPoliciesTask. This task lets you set global policies to apply to all assets in the inventory. For example, you can elect to accept all additions, but reject deletions, and updates. See Section 8.7.1, "Understanding a Policies Property File." You can then edit the policy.properties file to modify the policy elections for specific assets, if you want to.
Tip:
Before continuing, we recommend you review the detailed discussion of policies in Section 6.6, "Using Policies."
Policies let you elect how to handle the following three merge cases. Each merge case can be set to true or false in the policy file.
Additions – If an asset exists in the source inventory, but not in the destination inventory, add it to the destination.
Deletions – If an asset exists in the destination inventory, but not in the source inventory, delete it from the destination.
Updates – If an asset exists in the source inventory and in the destination inventory, update the destination with the artifact in the source inventory.
Example 8-5 Shows an excerpt from a policies.properties file. As you can see, in every case, the policy for this propagation is to accept (Y) adds and deletes, but to ignore (N) updates. A policy is set on each asset of the portal. You can change the policy on an asset by editing this file.
Example 8-5 Excerpt from a policies.properties File
policy_0_taxonomy=Application policy_0_adds=Y policy_0_updates=N policy_0_deletes=Y policy_1_taxonomy=Application:ContentServices policy_1_adds=Y policy_1_updates=N policy_1_deletes=Y policy_2_taxonomy=Application:ContentServices:Tools_Repository policy_2_adds=Y policy_2_updates=N policy_2_deletes=Y policy_3_taxonomy=Application:ContentServices:Tools_Repository:ContentNodes policy_3_adds=Y policy_3_updates=N policy_3_deletes=Y policy_4_taxonomy=Application:ContentServices:Tools_Repository:ContentTypes policy_4_adds=Y policy_4_updates=N policy_4_deletes=Y policy_5_taxonomy=Application:ContentServices:Tools_Repository:GlobalEntitlements policy_5_adds=Y policy_5_updates=N policy_5_deletes=Y
You can think of propagation as a combining operation. When you propagate a portal, you combine the contents of a source inventory with a destination inventory. The combining is governed by scoping and policy rules. The previous section, Section 8.6, "Scoping an Inventory," explained how to create a scope.properties file, which contains the scoping rules for an inventory. You can use this file as input to the OfflineCombineTask, which uses scoping information to decide which artifacts to combine to produce the final inventory file.
This section explains the basic workflow for combining and committing inventories using propagation Ant tasks. The Ant tasks used in this workflow include:
OfflineCombineTask – Combines a source with a destination inventory file. Optional task attributes let you specify a scope.properties and a policy.properties file. These files control how the two inventories are combined.
OnlineUploadTask – This task moves an inventory file to a specified server, and is similar to an FTP transfer. The inventory file is stored in a temporary directory on the target server.
OnlineCommitTask – Updates the application on the target server with the inventory that was uploaded with the OnlineUploadTask.
Figure 8-3 shows the basic workflow for combining and committing inventories. The workflow assumes that you have already exported (using the OnlineDownloadTask) a source and a destination inventory file.
Figure 8-3 Combining and Committing an Inventory
After you have a source and destination inventory file, you can combine them using the OfflineCombineTask. The result of this task is a combined inventory file. This file is a combination of the source and destination inventory files with scope and policy rules (if they were specified) applied.
Tip:
The OnlineCombineTask performs the same function as exporting a propagation session to an inventory file with the propagation tool in Oracle Enterprise Pack for Eclipse. See Chapter 7, "Using Oracle Enterprise Pack for Eclipse Propagation Tools."
Use the OnlineUploadTask to move the combined inventory to the destination server. Use the OnlineCommitTask to commit the combined inventory on the destination server.
The OfflineCombineTask, OnlineUploadTask, and OnlineCommitTask are explained in Chapter 9, "Propagation Ant Task Reference."
|
 Copyright © 2010, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
