17 Maintaining the MDS Repository

The following topics provide guidance for maintaining the Metadata Services (MDS) repository for Oracle Web services:

About the MDS Repository

Oracle Web Services Manager (WSM) uses an MDS repository to store policies, assertion templates, and policy usage data. Policies, assertion templates, and usage data can be stored either as files in the file system (supported for development) or to the Oracle Fusion Middleware database (supported for production).

For a list of the databases that are supported for this release, see Oracle Fusion Middleware Supported System Configurations at: http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html

Within the repository, each policy has a URI that is evaluated to form a path in which to locate a particular XML document containing the policy. Oracle WSM does not use the MDS customization feature, so all policies are stored as complete documents. Although MDS supports the ability to store multiple versions of a given document, Oracle WSM only accesses the latest version during policy enforcement.

Details about managing the MDS repository are provided in the following documents:

Understanding the Different Mechanisms for Importing and Exporting Policies

You can use Fusion Middleware Control or MDS WebLogic Scripting Tool (WLST) commands to import and export policies to and from the MDS repository. While both mechanisms perform the same basic functions, you should understand the subtle differences in their behavior before deciding which one to use.

The following sections describe the differences between the two mechanisms.

Using Fusion Middleware Control

Oracle Enterprise Manager Fusion Middleware Control provides the ability to selectively import and export one policy at a time. When you import or export a policy using Fusion Middleware Control, the operation is routed through an instance of the Oracle WSM Policy Manager application. At runtime, when a request for a policy is made, the Policy Manager guarantees that the latest policy is always provided. Therefore, the latest policies are always enforced.

The procedures for importing and exporting policies using Fusion Middleware Control are described in the following sections:

Using MDS Custom WLST Commands

The MDS custom WLST commands provide a command-line interface that you can use to make direct modifications to the MDS repository. Unlike Fusion Middleware Control, when you import or export policies using importMetadata and exportMetadata MDS WLST commands, the operation is not routed through an instance of the Oracle WSM Policy Manager. Consequently, Oracle Web Services Manager may not be aware of the changes and may continue to enforce outdated policies. To ensure that only the latest polices are enforced, you must restart all the servers to which the MDS repository is registered.

An example for using these commands is provided in "Migrating Policies".

For more information about the importMetadata and exportMetadata commands, see "Metadata Services (MDS) Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Migrating Policies Between Application Environments

Policies can be migrated through the different stages of the application development and deployment cycles, such as from development to production. Policy migration is described in more detail in "Migrating Policies"

When using the MDS WLST commands to perform the migration, it is important to ensure that only the desired policies are transferred. You specify the set of metadata objects that are exported (using the exportMetadata command) or imported (using the importMetadata command) using the docs parameter. If the value /** is provided (the default), all objects, including policies, assertion templates, and policy usage data are transferred. While it may be desirable to transfer all of the policies and assertion templates, transferring the policy usage data will introduce errors into the usage analysis numbers reported in Fusion Middleware Control if the source and target environments are not identical. Therefore, it is recommended that you use a more specific path when you are exporting policies (or assertion templates).

If you adhered to the recommended naming conventions described in "Recommended Naming Conventions for Policies" when you named your policies, and you placed all custom policies into their own directory, then you can easily limit the export to the required documents by specifying the directory name. For example, to export only the policies under the mycompany directory, specify the following command:

exportMetadata(application='wsm-pm',server='myserver', docs='/policies/mycompany/**',toLocation='/exported/owsm_policies')

If it is not possible to specify all of the necessary objects in a single command (for example, if policies reside in more than one directory or it is necessary to export both policies and assertion templates), you can specify the exportMetadata command multiple times.

Note:

The Policy Manager requires that all policies be located in a /policies directory. Therefore, although you can use any directory name that you choose when exporting policies, any policies to be imported must be located in a /policies directory. For example, if you export policies to a directory named /somedir/mypolicies and you want to import these policies, you must either rename the directory to somedir/policies or copy the policies to a /policies directory.

You should not specify the /policies directory with the importMetadata command. For example:

importMetadata (application='wsm-pm',server='myserver',docs='/somedir/**)

For more information about the importMetadata and exportMetadata commands, see "Metadata Services (MDS) Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Exporting Policies from the MDS Repository for Use in JDeveloper

In JDeveloper, you can add custom policies to the default policy store location at:

C:\Documents and Settings\user-dir\ApplicationData\JDeveloper\system11.1.1.2.x.x.x\DefaultDomain\oracle\store\gmds

Within this directory, Oracle WSM policies files must be included using one of the following directory structures:

  • Predefined Oracle WSM policies: owsm/policies/oracle/policy_file

  • Custom user policies: owsm/policies/policy_file

When exporting policy files from the Oracle WSM Metadata Services (MDS) repository for use in JDeveloper, this directory structure is not maintained. You must ensure that when adding the exported policy to the JDeveloper environment that you use the required directory structure noted above. Otherwise, the policies will not be available in the JDeveloper environment.

Patching Policies in the Repository

You can patch the repository using either Fusion Middleware Control or the WLST commands, as described in "Understanding the Different Mechanisms for Importing and Exporting Policies". When you create or update a policy, there are two possible scenarios to consider when you patch the repository:

  • You create a new policy or update an existing policy that uses a new policy URI. In this scenario, the patching of the repository acts as if a new file was added to the installation and, as a result, only impacts the components that expect to use the new policy. Once loaded, the policy is available to all applications. Generally speaking, using a new policy URI is the preferred model as policies are typically named to convey the behavior they represent.

  • You create a new policy or update an existing policy that uses an existing policy URI. In this scenario, the patching of the repository acts as if an existing file was overwritten with a new version and, therefore, impacts all components that are using the existing policy. Once loaded, all applications will use the new version of the policy. Reusing an existing URI is typically only done to make minor modifications to the behavior of a policy. Note that if you use WLST commands to patch the repository, you need to restart the server to ensure that the latest version of the policy is enforced. You do not need to restart if you use Fusion Middleware Control.

Backing Up and Restoring the MDS Repository

Although the use cases are different, backing up and restoring the repository is functionally identical to migrating policies between environments. To back up the repository, use the exportMetadata command to export all repository artifacts. To restore the repository, use the importMetadata command to import all repository artifacts.

For additional information, see "Migrating Policies Between Application Environments".

For details about these commands, see "Metadata Services (MDS) Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Upgrading the Oracle WSM Policies in the MDS Repository

Both predefined and custom Oracle WSM policies are stored in the Oracle MDS repository. In subsequent releases, these predefined policies may be discontinued, changed, or additional predefined policies may be provided. You can use the Web services custom WLST commands to upgrade the repository with new or updated predefined policies when you install a new version of the Fusion Middleware software. You can also refresh the repository by deleting all Oracle WSM policies from the repository, including custom policies, and then repopulating it using the predefined policies provided in your installation. All of the policies in the repository are also revalidated when you upgrade the repository.

Note:

You should back up your existing policies to a safe location before deleting any policies. In the event you have any issues with the new policies, you can import the existing policies from the backup.

To upgrade the MDS repository:

  1. Install the new version of Oracle Fusion Middleware.

  2. Ensure that the MDS repository to be upgraded is registered with the new installation of Oracle Fusion Middleware. For more information, see "Registering a Metadata Services (MDS) Repository".

  3. Invoke WLST from the Oracle home in which you installed the new version of Oracle Fusion Middleware as described in "Accessing the Web Services Custom WLST Commands".

  4. Do one of the following:

    • To add new predefined policies that are provided in the latest installation of the Oracle Fusion Middleware software, enter the following command:

      upgradeWSMPolicyRepository()

      When you execute this command, a message is displayed indicating the policies that have been added to the repository. Note that existing predefined and user-defined custom policies in the repository are unchanged. The output message also displays a list of any existing predefined policies that have changed or discontinued in the latest release. If a policy has been discontinued and is no longer supported, Oracle recommends that you remove all references to it and then delete it using Oracle Enterprise Manager. If a predefined policy has changed in the latest release, Oracle recommends that you import the updated version of the policy using Oracle Enterprise Manager. For details about deleting and importing policies using Enterprise Manager, see Chapter 7, "Managing Web Service Policies."

    • To delete existing predefined policies stored in the repository and replace them with the latest set of predefined policies, use the following command:

      resetWSMPolicyRepository(false)

      User-defined custom policies are unchanged. An output message is displayed that lists the predefined policies that have been added, deleted, or replaced in the repository.

    • To delete all policies from the repository, including custom policies, and replace them with the latest set of predefined policies, use the following command:

      resetWSMPolicyRepository(true)

      Note:

      Before you delete a policy, Oracle recommends that you verify that the policy is not attached to any policy subjects.

    When you execute any of these commands, all existing policies are revalidated.

    For more information about these WLST commands, see "Policy Repository Upgrade Commands" in WebLogic Scripting Tool Command Reference.

Rebuilding the MDS Repository

In some circumstances, it may be desirable to rebuild the entire repository, including restoring the original predefined policies and assertion templates. For example, when starting a new project in a test environment it may be useful to reset the repository contents to their original state.

To rebuild the policy repository, perform the following steps:

  1. Connect to the Administration Server instance of the WebLogic Server domain to which the repository is registered. For instructions, see "Accessing the Web Services Custom WLST Commands".

    Note:

    You should back up your existing policies to a safe location before deleting any policies or rebuilding the repository. In the event you have any issues with the new policies, you can import the existing policies from the backup.
  2. Use the resetWSMPolicyRepository(true) command to delete all the documents from the Oracle WSM partition of the repository and repopulate it with the set of predefined policies and assertion templates that were installed with the software. This is the preferred method.

    For more information about the resetWSMPolicyRepository WLST command, see "Policy Repository Upgrade Commands" in WebLogic Scripting Tool Command Reference.

Alternatively, you can use the deleteMetadata MDS WLST command, for example:

deleteMetadata(application='wsm-pm',server='soa_server1',docs='/**') 

After you execute the deleteMetadata command, restart the Managed Server in which the Oracle WSM policy manager is running. On startup, the policy manager will detect an empty repository and will automatically install the original predefined policies and assertion templates.

Note:

Before you delete a policy, Oracle recommends that you verify that the policy is not attached to any policy subjects.

For details about the deleteMetadata command, see "Metadata Services (MDS) Custom WLST Commands" in WebLogic Scripting Tool Command Reference.