14 Managing the Metadata Repository

14.3.1.1 Databases Supported by MDS

The MDS Repository supports Oracle databases, as well as non-Oracle databases, including SQL Server, DB2, and MySQL.

For information about the supported databases and the supported versions, as well as using these databases with the MDS Repository, see "Supported Databases for the MDS Schema" in the Oracle Fusion Middleware System Requirements and Specifications.

14.3.1.2 Understanding MDS Operations

You can use Fusion Middleware Control or WLST commands to perform most operations on the MDS Repository. However, for some operations that do not have a custom user interface in Fusion Middleware Control or do not have WLST commands, you must use the System MBeans.

The sections that follow describe using Fusion Middleware Control and WLST commands to perform the operations, unless only System MBeans are supported. In that case, the sections describe how to use System MBeans to perform the operation.

You can view information about the repositories, including the partitions and the applications deployed to each partition. You can also perform operations on the partitions, such as purging, deleting, importing metadata, or exporting metadata.

Note the following when you use the MDS operations described in the sections that follow:

• The export operation exports a versioned stripe (either the tip version or based on a label) of metadata documents from an MDS Repository partition to a file system directory or archive. If you export to a directory, the directory must be accessible from the host where the application is running. If you export to an archive, the archive can be located on the system on which you are executing the command.

  Because versioning of metadata is not supported for file-based repositories, the tip version (which is also the only version) is exported from a file-based repository.

• The import operation imports metadata documents from a file system directory or archive to an MDS Repository partition. If you exported to a directory, the directory must be accessible from the host where the application is running. If you exported to an archive, the archive can be located on the system on which you are executing the command.

  If the target repository is a database-based repository, the metadata documents are imported as new tip versions. If the target repository is a file-based repository, the metadata documents are overwritten.

Table 14-1 lists the logical roles needed for each operation. The roles apply whether the operations are performed through the WLST commands, Fusion Middleware Control, or MBeans.

For information about how these roles map to WebLogic Server roles, see "Mapping of Logical Roles to WebLogic Roles" in Securing Applications with Oracle Platform Security Services.

14.3.2.1 Registering a Database-Based MDS Repository

Before you can deploy an application to an MDS Repository, you must register the repository with the Oracle WebLogic Server domain. You can register a database-based MDS Repository using Fusion Middleware Control or WLST, as described in the following topics:

• Registering a Database-Based MDS Repository Using Fusion Middleware Control

• Registering a Database-Based MDS Repository Using WLST

registerMetadataDBRepository(name='mds-repos1', dbVendor='ORACLE',
    host='hostname', port='1521', dbName='ora11', 
    user='username', password='password', targetServers='server1')

14.3.2.2 Targeting Additional Servers to an MDS Repository

When you register an MDS Repository using Fusion Middleware Control, the repository is targeted to the Administration Server. You can target the repository to additional servers.

To target the MDS Repository to additional servers:

1. From the navigation pane, expand Metadata Repositories.

2. Select the repository.

   The repository home page is displayed, as shown in the following figure:

   
   Description of the illustration ''mr_home1.gif''
   
   

3. In the Targeted Servers section, click Add.

   The Target the Repository dialog box is displayed.

4. Select the server or cluster and click Target.

   You can expand the cluster to see the servers in the cluster. However, if you select a cluster, the repository is targeted to all servers in the cluster.

5. When the operation completes, click Close.

   The server is now listed in the Targeted Servers section.

14.3.2.3 Removing Servers Targeted to a Metadata Repository

To remove a server as a target for the repository:

1. From the navigation pane, expand Metadata Repositories.

2. Select the repository.

   The repository home page is displayed.

3. In the Targeted Servers section, select the target server and click Remove.

   The Untarget the Repository dialog box is displayed.

4. Select the server or cluster and click Untarget.

   You can expand the cluster to see the servers in the cluster. However, if you select a cluster, the repository will be untargeted from all servers in the cluster.

5. When the operation completes, click Close.

14.3.2.4 Deregistering a Database-Based MDS Repository

Deregistration does not result in loss of data stored in the repository. However, any applications using a deregistered repository will not function after the repository is deregistered. You must ensure that no application is using the repository before you deregister it.

You can deregister a database-based MDS Repository using Fusion Middleware Control or WLST, as described in the following topics:

• Deregistering a Database-Based MDS Repository Using Fusion Middleware Control

• Deregistering a Database-Based MDS Repository Using WLST

deregisterMetadataDBRepository(name='mds-repos1')

14.3.3.1 Creating and Registering a File-Based MDS Repository

You can create a file-based MDS Repository and register it with an Oracle WebLogic Server domain using Fusion Middleware Control.

To create and register a file-based repository using Fusion Middleware Control:

1. From the WebLogic Domain menu, choose Other Services, then Metadata Repositories.

   The Metadata Repositories page is displayed.

2. In the File-Based Repository section, click Register.

   The Register Metadata Repository page is displayed.

3. Enter the following information:

   • For Name, enter a name. For example, enter repos1. The prefix mds- is added to the name and a repository with the name mds-repos1 is registered. If you enter a name that begins with mds-, a repository with the given name is registered.

   • For Directory, specify the directory. The Administration Server and Managed Servers that run the applications that use this repository must have write access to the directory.

     Note the following:

     • If an absolute path is not given, the directory will be created under the DOMAIN_HOME directory.

     • If the specified path exists on the file system, the metadata file repository is registered; all the subdirectories under this path are automatically loaded as partitions of this file-based repository.

     • If the path specified does not exist, a directory with this name is created on the file system during the registration. Because there are no partitions created yet, there are no subdirectories to load.

     • If the specified path is invalid and cannot be created for some reason, such as permission denied, an error is displayed and the registration fails.

     • If the specified path exists, but as a file not a directory, an error is not displayed and the registration succeeds.

4. Click OK.

The repository is created and registered and is displayed on the Metadata Repositories page.

You can now create and delete partitions. Those changes are reflected in the directory on the file system.

You can also create a file-based repository using system MBeans. For information about using the System MBean Browser, see Section 14.3.5.

14.3.3.2 Deregistering a File-Based MDS Repository

You can deregister a file-based MDS Repository using Fusion Middleware Control.

To deregister a file-based repository using Fusion Middleware Control:

1. From the WebLogic Domain menu, choose Other Services, then Metadata Repositories.

   The Metadata Repositories page is displayed.

2. In the File-Based Repository section, select the repository and click Deregister.

3. Click OK in the Confirmation dialog box.

   If the file-based repository is valid, it is removed from the repository list. Otherwise, an error is displayed.

You can also deregister a file-based repository using system MBeans. For information about using the System MBean Browser, see Section 14.3.5.

14.3.6.1 Viewing Information About an MDS Repository Using Fusion Middleware Control

To view information about an MDS Repository using Fusion Middleware Control:

1. From the navigation pane, expand Metadata Repositories.

2. Select the repository.

   The following figure shows the home page for an MDS Repository:

   
   Description of the illustration ''mds_home.gif''
   
   

3. To see which applications use the repository, click the icon in the Applications column. The Applications using the partition dialog box is displayed, with tabs for Deployed Applications and Referenced by Applications:

   • The Deployed Applications tab shows the list of applications whose metadata is deployed to the repository partition.

   • The Referenced by Applications tab shows the list of applications that refer to the metadata stored in the repository partition.

From this page, you can also:

• Delete partitions, as described in Section 14.3.10.1.

• Delete labels, as described in Section 14.3.12.6.

• Add or remove targeted servers, as described in Section 14.3.2.2.

14.3.6.2 Viewing Information About an MDS Repository Using System MBeans

You can use the System MBean operations listPartitions, listRepositories, and listRepositoryDetails to get a list of partitions in the repository, a list of repositories, and details of the repository registered with the domain:

1. From the WebLogic Domain menu, choose System MBean Browser.

   The System MBean Browser page is displayed.

2. In the page's navigation pane, expand Application Defined MBeans, then expand oracle.mds.lcm. Expand the domain, then MDSDomainRuntime, and then select MDSDomainRuntime.

3. In the Application Defined MBeans pane, select the Operations tab.

4. Click one of the operations, such as listPartitions, listRepositories, and listRepositoryDetails.

   The Operations page is displayed.

5. Click Invoke.

   The information is displayed in the Return Value table.

For information about changing the MDS configuration attributes for an application, see Section 10.9.

14.3.7.1 Cloning a Partition

You can clone a partition to the same repository or a different repository using the system MBean cloneMetadataPartition. Both the original repository and the target repository must be a database-based repository.

To clone the partition, and then redeploy the application to a new repository or to the same repository:

1. Clone the partition, using the cloneMetadataPartition operation on the system MBean. The following example clones partition1 from the old repository to the new repository:

   1. In Fusion Middleware Control, from the navigation pane, navigate to the Managed Server from which the application is deployed. From the WebLogic Server menu, choose System MBean Browser.

      The System MBean Browser page is displayed.

   2. In the System MBean Browser's navigation pane, expand Application Defined MBeans, then expand oracle.mds.lcm. Expand the domain, and then MDSDomainRuntime. Select MDSDomainRuntime.

   3. In the Application Defined MBeans pane, select the Operations tab.

      The following figure shows the System MBeans Browser with the Application Defined MBeans pane:

      
      Description of the illustration ''mds_mbean.gif''
      
      

   4. Select cloneMetadataPartiton.

      The Operation: cloneMetadataPartiton page is displayed.

   5. In the Parameters table, enter the following values:

      • For fromRepository, enter the name of the metadata repository that contains the metadata partition from which the metadata documents are to be cloned.

      • For fromPartition, enter the name of the partition from which the metadata documents are to be cloned.

      • For toRepository, enter the name of the metadata repository to which the metadata documents from the source repository partition are to be cloned.

      • For toPartition, enter the name of metadata repository partition to be used for the target partition. The name must be unique within the repository. If you do not supply a value for this parameter, the name of the source partition is used for the target partition.

        If the toRepository name is the same as the original repository, you must enter a partition name and the name must be unique within the repository.

   6. Click Invoke.

   7. Verify that the partition has been created by selecting the repository in the navigation pane. The partition is listed in the Partitions table on the Metadata Repository home page.

2. Redeploy the application, as described in Section 10.4.3 or Section 10.5.3, depending on the type of application. When you do so, you specify the new partition and repository in the Application Attributes page:

   1. To change the repository, click the icon next to the Repository Name. In the Metadata Repositories dialog box, select the repository and click OK.

   2. To change the partition, enter the partition name in Partition Name.

14.3.7.2 Creating a New Partition and Reassociating the Application to It

You can create a new partition in the same or a different repository by redeploying the application and specifying the new partition. Then, you transfer the metadata to the new partition using WLST.

You can use this procedure to transfer metadata between two different types of repositories (file-based to database-based or from an Oracle Database to another database.)

To create a new partition and reassociate the application to it:

1. Export the metadata from the source partition to a directory on the file system using the WLST exportMetadata command:

   exportMetadata(application='sampleApp', server='server1',
          toLocation='/tmp/myrepos/mypartition', docs='/**')
   

2. Redeploy the application, as described in Section 10.4.3 or Section 10.5.3, depending on the type of application. When you do so, you specify the new partition and repository in the Application Attributes page:

   1. To change the repository, click the icon next to the Repository Name. In the Metadata Repositories dialog box, select the repository and click OK.

   2. To change the partition, enter the partition name in Partition Name.

3. Import the metadata from the file system to the new partition using the WLST importMetadata command:

   importMetadata(application='sampleApp', server='server1',
          fromLocation='/tmp/myrepos/mypartiton', docs='/**')
   

4. Optionally, deregister the original repository, as described in Section 14.3.3.2 or Section 14.3.2.4.

Alternatively, you can create a new partition using the WLST command createMetadataPartition. The partition name must be unique within the repository. If the partition parameter is missing, the name of the source partition is used for the target partition. The following example creates the partition partition1:

createMetadataPartition(repository='mds-repos1', partition='partition1')

14.3.8.1 Transferring Metadata Using Fusion Middleware Control

To use Fusion Middleware Control to transfer metadata:

1. From the navigation pane, expand Application Deployments, then select the application.

2. From the Application Deployment menu, choose MDS Configuration.

   The MDS Configuration page is displayed, as shown in the following figure:

   
   Description of the illustration ''mds_config.gif''
   
   

3. In the Export section, select one of the following:

   • Export metadata documents to an archive on the machine where this web browser is running.

     Click Export.

     The export operation exports a zip file. Depending on the operating system and browser, a dialog box is displayed that asks you if you want to save or open the file.

   • Export metadata documents to a directory or archive on the machine where this application is running.

     Enter a directory location or archive to which the metadata can be exported.

     The target directory or archive file (.jar, .JAR, .zip or .ZIP) to which to transfer the documents selected from the source partition. If you export to a directory, the directory must be a local or network directory or file where the application is physically deployed. If you export to an archive, the archive can be located on a local or network directory or file where the application is physically deployed, or on the system on which you are executing the command.

     If the location does not exist in the file system, a directory is created except that when the names ends with .jar, .JAR, .zip or .ZIP, an archive file is created. If the archive file already exists, the exportMetadata operation overwrites the file.

     Click Export. Then, in the Confirmation dialog box, click Close.

   If you check Exclude base documents, this operation exports only the customizations, not the base documents. See Section 14.3.1 for information about base documents and customizations.

4. If the target application is on a different system, copy the exported metadata to that system.

5. From the navigation pane for the target system, expand Application Deployments, then select the application.

6. From the Application Deployment menu, choose MDS Configuration.

   The MDS Configuration page is displayed

7. In the Import section, select one of the following:

   • Import metadata documents from an archive on the machine where this web browser is running.

   • Import metadata documents from a directory or archive on the machine where this application is running.

   Enter the location of the directory or archive that contains the exported metadata. If you specify a directory, include the subdirectory with the partition name in the specification. The directory or archive file must be a local or network directory or file where the application is physically deployed.

8. Click Import.

9. In the Confirmation dialog box, click Close.

14.3.8.2 Transferring Metadata using WLST

To use WLST to transfer metadata:

1. Export the metadata from the original partition using the exportMetadata command:

   exportMetadata(application='sampleApp', server='server1',
          toLocation='/tmp/myrepos/mypartition', docs='/**')
   

   This command exports a versioned stripe of the metadata documents from the metadata partition to a file system directory. Only customization classes declared in the cust-config element of adf-config.xml are exported. If there is no cust-config element declared in adf-config.xml, all customization classes are exported.

   To export all customizations, use the option restrictCustTo="%".

2. If the production application is on a different system, copy the exported metadata to that system.

3. Import the metadata to the other partition using the WLST importMetadata command:

   importMetadata(application='sampleApp', server='server1',
          fromLocation='/tmp/myrepos/mypartiton', docs='/**')
   

   The value of the fromLocation parameter must be on the same system that is running WLST or on a mapped network drive or directory mount. You cannot use direct network references such as \\mymachine\repositories\.

   Only customization classes declared in the cust-config element of adf-config.xml are imported. If there is no cust-config element declared in adf-config.xml, all customization classes are imported.

   To import all customizations, use the option restrictCustTo="%".

14.3.10.1 Deleting a Metadata Partition Using Fusion Middleware Control

To delete a metadata partition from a repository partition using Fusion Middleware Control:

1. From the navigation pane, expand Metadata Repositories.

2. Select the repository.

   The repository home page is displayed.

3. In the Repository Partitions section, select the partition and click Delete.

4. In the confirmation dialog box, click OK.

14.3.10.2 Deleting a Metadata Partition Using WLST

To delete a metadata partition from a repository, you can use the WLST command deleteMetadataPartition. For example, to delete the metadata partition from the file-based repository mds-repos1, use the following command:

deleteMetadataPartition(repository='mds-repos1', partition='partition1')

14.3.11.1 Purging Metadata Version History Using Fusion Middleware Control

To use Fusion Middleware Control to purge the metadata version history:

1. From the navigation pane, expand Application Deployments, then select the application.

2. From the Application Deployment menu, choose MDS Configuration.

   For Oracle SOA Suite, you can expand SOA in the navigation tree, then select soa-infra. From the SOA Infrastructure menu, select Administration, then MDS Configuration.

   The MDS Configuration page is displayed.

3. In the Purge section, in the Purge all unlabeled past versions older than field, enter a number and select the unit of time. For example, enter 3 and select months.

4. Click Purge.

5. In the Confirmation dialog box, click Close.

14.3.11.2 Purging Metadata Version History Using WLST

To use WLST to purge metadata version history, use the purgeMetadata command. You specify the documents to be purged by using the olderThan parameter, specifying the number of seconds. The following example purges all documents older than 100 seconds:

purgeMetadata(application='sampleApp', server='server1', olderThan=100)

14.3.11.3 Enabling Auto-Purge

You can enable automatic purging using the MDSAppConfig MBean:

1. From the WebLogic Domain menu, choose System MBean Browser.

   The System MBean Browser page is displayed.

2. Expand Application Defined MBeans, then oracle.adf.share.config, then Server: name, then Application: name, then ADFConfig, then ADFConfig, and ADFConfig.

3. Select MDSAppConfig.

   The Application Defined MBeans page is displayed.

4. For AutoPurgeTimeToLive, enter a value, in seconds.

5. Navigate up to ADFConfig (the parent of MDSAppConfig) and select it.

6. In the Operations tab, click Save.

14.3.12.1 Understanding Metadata Labels

A metadata label is a means of selecting a particular version of each object from a metadata repository partition. Conceptually, it is a collection of document versions, one version per document, representing a horizontal stripe through the various document versions. This stripe comprises the document versions which were the tip versions (latest versions) at the time the label was created.

You can use a label to view the metadata as it was at the point in time when the label was created. You can use the WLST commands to support logical backup and recovery of an application's metadata contained in the partition.

Labels are supported only in database-based repositories.

Document versions belonging to a label are not deleted by automatic purging, unless the label is explicitly deleted. In this way, creating a label guarantees that a view of the metadata as it was at the time the label was created remains available until the label is deleted.

When an application that contains a MAR is deployed, a label with the prefix postDeployLabel_ is created. For example: postDeployLabel_mdsappdb_mdsappdb.mar_2556916398.

Each time you patch the MAR, a new deployment label is created, but the previous deployment label is not deleted Similarly, when you undeploy an application that contains a MAR, the application is undeployed, but the label remains in the metadata repository partition.

If you delete a deployment label, when the application is restarted, the MAR is automatically redeployed, and the deployment label is also re-created.

14.3.12.2 Creating Metadata Labels

To create a label for a particular version of objects in a partition in an MDS Repository, you use the WLST command createMetadataLabel. For example, to create a label named prod1 for the application my_mds_app, use the following command:

createMetadataLabel(application='my_mds_app', server='server1', name='prod1')
Executing operation: createMetadataLabel.

Created metadata label "prod1".

If the application has more than one version, you must use the applicationVersion parameter to specify the version.

14.3.12.3 Listing Metadata Labels

You can list the metadata labels for a particular application. To do so, use the WLST command listMetadataLabel. For example, to list the labels for the application my_mds_app, use the following command:

listMetadataLabels(application='my_mds_app', server='server1')
Executing operation: listMetadataLabels.

Database Repository partition contains the following labels:
prod1
prod2
postDeployLabel_mdsappdb_mdsappdb.mar_2556916398

If the application has more than one version, you must use the applicationVersion parameter to specify the version.

14.3.12.4 Promoting Metadata Labels

You can promote documents associated with a metadata label so that they become the latest version. That is, you can promote them to the tip. Promote a label if you want to roll back to an earlier version of all of the documents captured by the label.

To promote a label to the tip, use the WLST command promoteMetadataLabel. For example to promote the label prod1, use the following command:

promoteMetadataLabel(application='my_mds_app', server='server1', name='prod1')
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root. 
For more help, use help(domainRuntime)

Executing operation: promoteMetadataLabel.

Promoted metadata label "prod1" to tip.

If the application has more than one version, you must use the applicationVersion parameter to specify the version.

14.3.12.5 Purging Metadata Labels

You can purge metadata labels that match the given name pattern or age, allowing you to purge labels that are no longer in use. This reduces the size of the database, improving performance. You must delete the labels associated with unused metadata documents before you can purge the documents and revision history from the repository.

You may want to delete a label for older applications that were undeployed, but the labels were not deleted. Each time you patch the MAR, a new label is created, but the previous label is not deleted.

You can use Fusion Middleware Control or WLST to purge metadata labels, as described in the following topics:

• Purging Metadata Labels Using Fusion Middleware Control

• Purging Metadata Labels Using WLST

purgeMetadataLabels(repository='mds-myRepos', partition='partition1',
                      namePattern='prod*', olderThanInMin='30')
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root. 
For more help, use help(domainRuntime)

Executing operation: purgeMetadataLabels.

The following metadata labels were purged: repository=mds-soa,parititon=partition1,namePattern=prod*,olderThanInMin=30: 

14.3.12.6 Deleting Metadata Labels

To delete a specified metadata label, you use the WLST command deleteMetadataLabel. For example, to delete a label named prod1 for the application my_mds_app, use the following command:

deleteMetadataLabel(application='my_mds_app', server='server1', name='prod1')

If the application has more than one version, you must use the applicationVersion parameter to specify the version.

To find the labels associated with an application, use the listMetadataLabels command, as described in Section 14.3.12.3.

14.4.1.1 Changing the Schema Passwords for Most Components

To change the schema password of most components, you change the password in the database.

For example, to change the password of the schema OFM_MDS:

1. Connect to the database using SQL*Plus. Connect as a user with SYSDBA privileges.

2. Issue the following command:

   SQL> ALTER USER schema IDENTIFIED BY new_password;
   COMMIT;
   

   For example, to change the OFM_ MDS password to abc123:

   SQL> ALTER USER OFM_MDS IDENTIFIED BY abc123;
   COMMIT;
   

3. If you change the MDS Repository schema password, you must change the password for the corresponding MDS Repository data source, using Oracle WebLogic Server Administration Console:

   1. From Domain Structure, expand Services, then Data Sources.

   2. Click the data source that is related to the MDS Repository.

   3. Click the Configuration tab, then the Connection Pool tab.

   4. For Password, enter the new password.

   5. Click Save.

   6. Restart the Managed Servers that consume the data source.

14.4.1.2 Changing the Schema Password for Oracle Platform Security Services

To change the schema password for Oracle Platform Security Services:

1. Connect to the database using SQL*Plus. Connect as a user with SYSDBA privileges.

2. Issue the following command:

   SQL> ALTER USER schema IDENTIFIED BY new_password;
   COMMIT;
   

   Be sure to issue the commit command before proceeding to the next step.

3. Run the WLST command modifyBootStrapCredential to update the JPS configuration file.

   1. Invoke WLST from the following directory:

      ORACLE_HOME/oracle_common/common/bin/wlst.sh
      

   2. Specify the full path to the JPS configuration file in the modifyBootStrapCredentials command. For example:

      modifyBootStrapCredential(jpsConfigFile='/scratch/oracle//config/domains/soa_domain/config/fmwconfig/jps-config.xml',username='schema_username',password='password')
      

      At this point, the Administration Server can be started, however, the log file will show the following exception:

      ####<Jun 30, 2014 2:15:09 PM CEST> <Error> <Deployer> <deployer> <AdminServer> <[ACTIVE] ExecuteThread: '3' for queue: 'weblogic.kernel.Default
      (self-tuning)'> <<WLS Kernel>> <>
      <f9d07f66-36d0-462e-83fd-6ca40ac15a8a-00000004> <1402936508655> <BEA-149205>
      <Failed to initialize the application "opss-data-source" due to error
      weblogic.application.ModuleException:
      weblogic.common.resourcepool.ResourceSystemException:
      Could not connect to 'oracle.jdbc.OracleDriver'.
      
      The returned message is: ORA-01017: invalid username/password; logon denied.
      

      To avoid this error, execute next step.

4. Update the data source configuration, as described in Section 14.4.1.1, step 3.