9 Metadata Services (MDS) Custom WLST Commands

Use the Oracle Metadata Services (MDS) commands in the categories listed in Table 9-1 to manage Oracle Metadata Services (MDS).

For additional details about creating and managing an MDS repository, see the chapter "Managing the Oracle Metadata Repository" in the Oracle Fusion Middleware Administrator's Guide. For information about the roles needed to perform each operation, see "Understanding MDS Operations" in the Oracle Fusion Middleware Administrator's Guide.

Note:

To use these commands, you must invoke WLST from the Oracle home in which the component has been installed. See "Using Custom WLST Commands" in the Oracle Fusion Middleware Administrator's Guide.

Table 9-1 MDS Command Categories

Command category Description

Repository Management Commands

Manage the MDS repository.

Application Metadata Management Commands

Manage the application metadata in the MDS repository.

Application Label Management Commands

Manage the labels for the application.

Application Management Deployment Commands

Manage the application deployment.


Repository Management Commands

Use the MDS commands listed in Table 9-2 to manage the MDS repository. In the Use with WLST column, online means the command can only be used when connected to a running server. Offline means the command can only be used when not connected to a running server. Online or offline means the command can be used in both situations.

Table 9-2 Repository Management Commands

Use this command... To... Use with WLST...

createMetadataPartition

Create a metadata repository partition.

Online

deleteMetadataPartition

Delete a metadata repository partition.

Online

deregisterMetadataDBRepository

Deregister a database-based MDS repository.

Online

registerMetadataDBRepository

Register a database-based MDS repository.

Online


createMetadataPartition

Command Category: Repository Management

Use with WLST: Online

Description

An application needs a metadata partition in the repository to manage its metadata. This command creates a partition with the given name in the specified repository. Each deployed application uses a logical partition in metadata repository. A metadata repository is used as a common repository for managing metadata of different applications. This logical partition also helps in maintaining the metadata lifecycle. Before deploying a application, you create a partition for it in MDS repository.

Syntax

createMetadataPartition(repository, partition)
Argument Definition
repository
The name of the repository where the partition will be created.
partition
The name of the partition to create in the repository.

Example

The following example creates the metadata partition "part1" in repository "mds-myrepos":

wls:/weblogic/serverConfig> createMetadataPartition(repository='mds-myrepos',
                              partition='part1')
Executing operation: createMetadataPartition
Metadata partition created: part1
"part1"
wls:/weblogic/serverConfig>

deleteMetadataPartition

Command Category: Repository Management

Use with WLST: Online

Description

Deletes a metadata partition in the specified repository. When you delete a repository partition, all of the metadata in that partition is lost.

Syntax

deleteMetadataPartition(repository, partition)
Argument Definition
repository
The name of the repository that contains the partition.
partition
The name of the partition to delete in the repository.

Example

The following example deletes the metadata partition "part1" from the repository "mds-myrepos":

wls:/weblogic/serverConfig> deleteMetadataPartition(repository='mds-myrepos',
                                partition='part1')
Executing operation: deleteMetadataPartition
Metadata partition deleted: part1
wls:/weblogic/serverConfig>

deregisterMetadataDBRepository

Command Category: Repository Management

Use with WLST: Online

Description

Removes the database metadata repository registration as a System JDBC data source in the domain. After this command completes successfully, applications can no longer use this repository.

Syntax

deregisterMetadataDBRepository(name)
Argument Definition
name
The name of the repository to deregister.

Example

The following example deregisters the metadata repository "mds-myrepos":

wls:/weblogic/serverConfig> deregisterMetadataDBRepository('mds-myrepos')
Executing operation: deregisterMetadataDBRepository.
Metadata DB repository "mds-myrepos" was deregistered successfully.
wls:/weblogic/serverConfig>

registerMetadataDBRepository

Command Category: Repository Management

Use with WLST: Online

Description

A database metadata repository should be registered with WebLogic servers before the application can use it. This command registers a System JDBC data source with the domain for use as database-based metadata repository.

Syntax

registerMetadataDBRepository(name, dbVendor, host, port, dbName, user, password, [targetServers])
Argument Definition
name
The name of the repository to register.
dbVendor
The database vendor. The acceptable values are ORACLE or MSSQL.
host
The host name or the IP address of the database.
port
The port number used by the database.
dbName
The service name of the database. For example, orcl.hostname.com
user
The database user name.
password
The password for the database user.
targetServers
Optional. The WebLogic servers to which this repository will be registered. If this argument is not specified, then the repository will be registered only to the Administration Server. To specify multiple servers, separate the names with a comma.

Example

The following example registers the metadata repository myrepos, to two servers, with the database parameters:

wls:/weblogic/serverConfig> registerMetadataDBRepository('myrepos','ORACLE',
              'test.oracle.com','1521','mds', 'user1','x','server1, server2')
Executing operation: registerMetadataDBRepository.
Metadata DB repository "mds-myrepos" was registered successfully.
'mds-myrepos'
wls:/weblogic/serverConfig>

Application Metadata Management Commands

Use the commands in Table 9-3 to manage application metadata.

Table 9-3 Application Metadata Commands

Use this command... To... Use with WLST...

deleteMetadata

Deletes the metadata in the application repository.

Online

exportMetadata

Exports metadata for an application.

Online

importMetadata

Imports metadata for an application.

Online

purgeMetadata

Purge metadata.

Online


deleteMetadata

Command Category: Application Metadata

Use with WLST: Online

Description

Deletes the selected documents from the application repository. When this command is run against repositories that support versioning, that is a database-based repository, delete is logical and marks the tip version (the latest version) of the selected documents as "deleted" in the MDS repository partition.

You may want to delete metadata when the metadata is moved from one repository to another. In such a case, after you have exported the metadata, you can delete the metadata in the original repository.

Syntax

deleteMetadata(application, server, [docs], [restrictCustTo], [excludeAllCust],
 [excludeBaseDocs], [excludeExtendedMetadata], [cancelOnException], [applicationVersion]
Argument Definition
application
The name of the application for which the metadata is to be deleted.
server
The target server on which this application is deployed.
docs
Optional. A list of comma-separated, fully qualified document names or document name patterns, or both. The patterns can have the following wildcard characters: * and **.

The "*" represents all documents under the current namespace. The"**" represents all documents under the current namespace and also recursively includes all documents in sub-namespaces.

For example, "/oracle/*" will include all documents under "/oracle/" but not include documents under "/oracle/mds/".

As another example, "/oracle/**" will include all documents under "/oracle/" and also under "/oracle/mds/" and any other documents further in the namespace chain.

restrictCustTo
Optional. A list of comma-separated customization layer names used to restrict the delete operation so that it deletes only customization documents that match the specified customization layers.

This argument will be ignored if the excludeAllCust argument is also specified.

excludeAllCust
Optional. A Boolean value (true or false) that specifies whether or not to delete all customization documents.

This argument defaults to false. It overrides the restrictCustTo option.

excludeBaseDocs
Optional. A Boolean value (true or false) that specifies whether or not to delete base documents. This argument defaults to false.
excludeExtendedMetadata
Optional. A Boolean value (true or false) that specifies whether or not to delete the Extended Metadata documents. This argument defaults to false.
cancelOnException
Optional. A Boolean value (true or false) that specifies whether or not to abort the delete operation when an exception is encountered. On abort, the delete is rolled back if that is supported by the target store. This argument defaults to true.
applicationVersion
Optional. The application version, if multiple versions of the same application are deployed.

Examples

The following example deletes metadata files under the package "mypackage" from sampleApp deployed in the server "srg":

wls:/weblogic/serverConfig> deleteMetadata(application='mdsapp',
           server='srg', docs='/mypackage/*')
Executing operation: deleteMetadata.
"deleteMetadata" operation completed. Summary of "deleteMetadata" operation is:
List of documents successfully deleted:
/mypackage/jobs.xml
/mypackage/mo.xml
2 documents successfully deleted.
wls:/weblogic/serverConfig>

The following example deletes metadata files under the package "mypackage" from sampleApp deployed in the server "srg" and specifies to exclude extended metadata and all customizations:

wls:/weblogic/serverConfig> deleteMetadata(application='mdsapp',
        server='srg', docs='/mypackage/*', cancelOnException='false',
        excludeExtendedMetadata='true',
        excludeAllCust='true')
Executing operation: deleteMetadata.
"deleteMetadata" operation completed. Summary of "deleteMetadata" operation is:
List of documents successfully deleted:
/mypackage/jobs.xml
/mypackage/mo.xml
2 documents successfully deleted.
wls:/weblogic/serverConfig>

exportMetadata

Command Category: Application Metadata

Use with WLST: Online

Description

The application metadata can be transferred from one server location (for example, testing) to another server location (for example, production) by exporting and importing the metadata.

Use this command to export metadata.

Syntax

exportMetadata(application, server, toLocation, [docs,] [restrictCustTo],
 [excludeAllCust], [excludeBaseDocs], [excludeExtendedMetadata], [fromLabel],
 [toLabel], [applicationVersion])
Argument Definition
application
The name of the application for which the metadata is to be exported.
server
The target server on which this application is deployed.
toLocation
The target directory to which documents selected from the source partition will be transferred. The directory must be a local or network directory where the application is physically deployed.

This argument can be used as temporary file system for transferring metadata from one server to another.

docs
Optional. A list of comma-separated, fully qualified document names or document name patterns, or both. The patterns can have the following wildcard characters: * and **.

This argument defaults to "/**".

The "*" represents all documents under the current namespace. The"**" represents all documents under the current namespace and also recursively includes all documents in sub-namespaces.

For example, "/oracle/*" will include all documents under "/oracle/" but not include documents under "/oracle/mds/".

"/oracle/**" will include all documents under "/oracle/" and also under "/oracle/mds/" and any other documents further in the namespace chain.

restrictCustTo
Optional. A list of comma-separated customization layer names used to restrict the export operation to export only customization documents that match the specified customization layers. This argument will be ignored if the excludeAllCust argument is also specified.
excludeAllCust
Optional. A Boolean value (true or false) that specifies whether or not to export all customization documents. This argument defaults to false. This argument overrides the restrictCustTo argument.
excludeBaseDocs
Optional. A Boolean value (true or false) that specifies whether or not to export base documents. This argument defaults to false.
excludeExtendedMetadata
Optional. A Boolean value (true or false) that specifies whether or not to export the Extended Metadata documents. This argument defaults to false.
fromLabel
Optional. Transfers the documents from the source partition that is associated with this label.
toLabel
Optional. Works with the fromLabel argument to transfer the delta between fromLabel to toLabel from the source partition.
applicationVersion
Optional. The application version, if multiple versions of the same application are deployed.

Examples

The following example exports all metadata files from the application "mdsapp" deployed in the server "srg".

wls:/weblogic/serverConfig> exportMetadata(application='mdsapp', 
                            server='srg',toLocation='/tmp/myrepos',docs='/**')
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root.
For more help, use help(domainRuntime)
Executing operation: exportMetadata.
"exportMetadata" operation completed. Summary of "exportMetadata" operation is:
List of documents successfully transferred:
/mypackage/write.xml
/mypackage/write1.xml
/sample1.jspx
3 documents successfully transferred.
wls:/weblogic/serverConfig>

The following example exports only the customization documents under the layer user without any base documents from label label1 to label label2:

wls:/weblogic/serverConfig> exportMetadata(application='mdsapp',
                       server='srg',toLocation='/tmp/myrepos',
                       restrictCustTo='user',
                       excludeBaseDocs='true',
                       fromLabel='label1',
                       toLabel='label2',
                       applicationVersion='11.1.1')
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean 
as the root.
For more help, use help(domainRuntime)
Executing operation: exportMetadata.
"exportMetadata" operation completed. Summary of "exportMetadata" operation is:
List of documents successfully transferred:
/mypackage/mdssys/cust/user/user1/write1.xml.xml
/mypackage/mdssys/cust/user/user2/write2.xml.xml
/sample1.jspx
3 documents successfully transferred.

importMetadata

Command Category: Application Metadata

Use with WLST: Online

Description

The application metadata can be transferred from one server location (for example, testing) to another server location (for example, production) by exporting and importing the metadata.

Use this command to import metadata.

Syntax

importMetadata(application, server, fromLocation, [docs,] [restrictCustTo],
    [excludeAllCust], [excludeBaseDocs], [excludeExtendedMetadata],
    [cancelOnException], [applicationVersion])
Argument Definition
application
The name of the application for which the metadata is to be imported.
server
The target server on which this application is deployed.
fromLocation
The source directory from which documents will be selected for transfer. The directory must be a local or network directory where the application is physically deployed. This argument can be used as a temporary file system location for transferring metadata from one server to another.
docs
Optional. A list of comma-separated, fully qualified document names or document name patterns, or both. The patterns can have the following wildcard characters: * and **. This argument defaults to "/**".

The "*" represents all documents under the current namespace. The"**" represents all documents under the current namespace and also recursively includes all documents in sub-namespaces.

For example, "/oracle/*" will include all documents under "/oracle/" but not include documents under "/oracle/mds/".

"/oracle/**" will include all documents under "/oracle/" and also under "/oracle/mds/" and any other documents further in the namespace chain.

restrictCustTo
Optional. A list of comma-separated customization layer names used to restrict the import operation to import only customization documents that match the specified customization layers. This argument will be ignored if the excludeAllCust argument is also specified.
excludeAllCust
Optional. A Boolean value (true or false) that specifies whether or not to import all customization documents. This argument defaults to false. This argument overrides the restrictCustTo argument.
excludeBaseDocs
Optional. A Boolean value (true or false) that specifies whether or not to import base documents. This argument defaults to false.
excludeExtendedMetadata
Optional. A Boolean value (true or false) that specifies whether or not to import the Extended Metadata documents. This argument defaults to false.
cancelOnException
Optional. A Boolean value (true or false) that specifies whether or not to abort the import operation when an exception is encountered.
applicationVersion
Optional. The application version, if multiple versions of the same application are deployed.

Example

The following example imports all metadata available in '/tmp/myrepos' to the application "mdsapp" deployed in the server "srg":

wls:/weblogic/serverConfig> importMetadata(application='mdsapp', server='srg',
                             fromLocation='/tmp/myrepos',docs="/**")
Executing operation: importMetadata.
"importMetadata" operation completed. Summary of "importMetadata" operation is:
List of documents successfully transferred:
/app1/jobs.xml
/app1/mo.xml
2 documents successfully transferred.
wls:/weblogic/serverConfig>

purgeMetadata

Command Category: Application Metadata

Use with WLST: Online

Description

Purges the unlabeled document's version from the application's repository. All documents will be purged if they are expired, based on Time-To-Live (the olderThan argument). Document versions that are attached to a label and those which are tip (latest version) are not purged. This command is applicable only for repositories that support versioning, that is, a database-based repository.

Syntax

purgeMetadata(application, server, olderThan, [applicationVersion])
Argument Definition
application
The name of the application, used to identify the partition in the repository on which the purge operation will be run.
server
The target server on which this application is deployed.
olderThan
Document versions that are older than this value will be purged.
applicationVersion
Optional. The application version, if multiple versions of the same application are deployed.

Example

The following example purges the document version history for the application "mdsapp" deployed in the server "srg," if the version is older than 10 seconds:

wls:/weblogic/serverConfig> purgeMetadata('mdsapp', 'srg', 10)
Executing operation: purgeMetadata.
Metadata purged:Total number of versions: 10.
Number of versions purged: 0.
wls:/weblogic/serverConfig>

Application Label Management Commands

Use the commands in Table 9-4 to manage labels for applications.

Table 9-4 Application Label Management Commands

Use this command... To... Use with WLST...

createMetadataLabel

Creates a metadata label.

Online

deleteMetadataLabel

Deletes a metadata label from the repository partition

Online

listMetadataLabels

Lists metadata labels in the repository partition.

Online

promoteMetadataLabel

Promotes the metadata associated with a label to tip.

Online


createMetadataLabel

Command Category: Application Label Management

Use with WLST: Online

Description

Creates a new label for the documents in the application's repository partition. This command is applicable only for repositories that support versioning.

Syntax

createMetadataLabel(application, server, name, [applicationVersion])
Argument Definition
application
The name of the application for which a label will be created in the partition configured for this application.
server
The target server on which this application is deployed.
name
The name of the label to create in the repository partition.
applicationVersion
Optional. The application version, if multiple versions of the same application are deployed.

Example

The following example creates the label "labe11" for the application "mdsapp" deployed in the server "srg":

wls:/weblogic/serverConfig> createMetadataLabel('mdsapp','srg','label1')
Executing operation: createMetadataLabel.
Created metadata label "label1".
wls:/weblogic/serverConfig>

deleteMetadataLabel

Command Category: Application Label Management

Use with WLST: Online

Description

Deletes a label for the documents in the application's repository partition. This command is applicable only for repositories that support versioning.

Syntax

deleteMetadataLabel(application, server, name, [applicationVersion])
Argument Definition
application
The name of the application from whose associated partition the label is to be deleted.
server
The target server on which this application is deployed.
name
The name of the label to delete in the repository partition.
applicationVersion
Optional. The application version, if multiple versions of the same application are deployed.

Example

The following example deletes the metadata label "label1" from the application "mdsapp" deployed in the server "srg":

wls:/weblogic/serverConfig> deleteMetadataLabel('mdsapp','srg','label1')
Executing operation: deleteMetadataLabel.
Deleted metadata label "label1".
wls:/weblogic/serverConfig>

listMetadataLabels

Command Category:

Use with WLST: Online

Description

Lists all of the metadata labels in the application's repository partition. This command is applicable only for repositories that support versioning.

Syntax

listMetadataLabels(application, server, [applicationVersion])
Argument Definition
application
The name of the application for which all of the labels in the repository partition associated with this application will be deleted.
server
The target server on which this application is deployed.
applicationVersion
Optional. The application version, if multiple versions of the same application are deployed.

Example

The following example lists the metadata labels available for the application "mdsapp" deployed in the server "srg":

wls:/weblogic/serverConfig> listMetadataLabels('mdsapp', 'srg')
Executing operation: listMetadataLabels.
Database Repository partition contains the following labels:
label2
label3
wls:/weblogic/serverConfig>

promoteMetadataLabel

Command Category: Application Label Management

Use with WLST: Online

Description

Promotes documents associated with a label to the tip version in the repository. This command is useful to achieve rollback capability. This command is applicable only for repositories that support versioning.

Syntax

promoteMetadataLabel(application, server, name, [applicationVersion])
Argument Definition
application
The name of the application in whose associated repository the metadata is to be promoted to tip.
server
The target server on which this application is deployed.
name
The name of the label to promote in the repository partition.
applicationVersion
Optional. The application version, if multiple versions of the same application are deployed.

Example

The following example promotes the metadata label "label1" to tip in the application "mdsapp" deployed in the server "srg":

wls:/weblogic/serverConfig> promoteMetadataLabel('mdsapp', 'srg','label1')
Executing operation: promoteMetadataLabel.
Promoted metadata label "label1" to tip.
wls:/weblogic/serverConfig>

Application Management Deployment Commands

Use the commands in Table 9-5 to manage deployment.

Table 9-5 Application Management Deployment Commands

Use this command... To... Use with WLST...

getMDSArchiveConfig

Returns an MDSArchiveConfig object.

Offline

importMAR

Imports a MAR.

Online


getMDSArchiveConfig

Command Category: Application Management Deployment

Use with WLST: Offline

Description

Returns a handle to the MDSArchiveConfig object for the specified archive. The returned MDSArchiveConfig object's methods can be used to change application and shared repository configuration in an archive.

The MDSArchiveConfig object provides the following methods:

  • setAppMetadataRepository—This method sets the connection details for the application metadata repository.

    If the archive's existing adf-config.xml file does not have any configuration for the application's metadata repository, then you must provide all necessary arguments to define the target repository. To define a database-based repository, provide the repository, partition, type, and jndi arguments. For a file-based repository, provide the path argument instead of jndi.

    If the adf-config.xml file already contains some configuration for the application's metadata repository, you can provide only a subset of arguments that you want to change. You do not need to provide all arguments in such a case. However, if the store type is changed, then the corresponding jndi or path argument is required.

  • setAppSharedMetadataRepository—This method sets the connection details for the shared repository in the application archive that is mapped to specified namespace.

    If the archive's existing adf-config.xml file does not have any configuration for a shared metadata repository mapped to the specified namespace, you must provide all required arguments (in this case, repository, partition, type, and jndi or path). For a database-based repository, provide the jndi argument. For a file-based repository, path is a required argument.

    If the adf-config.xml file already contains some configuration for a shared metadata repository mapped to the specified namespace and you want to change some specific arguments, you can provide only a subset of those arguments; all others are not needed.

  • save—If you specify the toLocation, then the changes will be stored in the target archive file and the original file will remain unchanged. Otherwise, the changes will be saved in the original file itself.

Syntax

archiveConfigObject = getMDSArchiveConfig(fromLocation)
Argument Definition
fromLocation
The name of the ear file, including its complete path.

The syntax for setAppMetadataRepository is:

archiveConfigObject.setAppMetadataRepository([repository], [partition], [type], [jndi], [path])
Argument Definition
repository
Optional. The name of the application's repository.
partition
Optional. The name of the partition for the application's metadata.
type
Optional. The type of connection, file or database, to the repository. Valid values are 'File' or 'DB' (case insensitive).
jndi
Optional. The JNDI location for the database connection. This argument is required if the type is set to DB. This argument will not be considered if the type is set to File.
path
Optional. The location of the file metadata store. This argument is required if the type is set to File. This argument will not be considered if the type is set to DB.

The syntax for setAppSharedMetadataRepository is:

archiveConfigObject.setAppSharedMetadataRepository(namespace, [repository], [partition], [type], [jndi], [path])
Argument Definition
namespace
The namespace used for looking up the shared repository to set connection details.
repository
Optional. The name of the application's shared repository.
partition
Optional. The name of the partition for the application's shared metadata.
type
Optional. The type of connection, file or database, to the repository. Valid values are 'File' or 'DB' (case insensitive).
jndi
Optional. The JNDI location for the database connection. This argument is required if the type is set to DB. This argument will not be considered if the type is set to File.
path
Optional. The location of the file metadata store. This argument is required if the type is set to File. This argument will not be considered if the type is set to DB.

The syntax for save is:

archiveConfigObject.save([toLocation])
Argument Definition
toLocation
Optional. The file name along with the absolute path to store the changes. If this option is not provided, the changes are written to the archive represented by this configuration object.

Examples

In the following example, if the adf-config.xml file in the archive does not have the application and shared metadata repositories defined, then you should provide the complete connection information.

wls:/offline> archive = getMDSArchiveConfig(fromLocation='/tmp/testArchive.ear')

wls:/offline> archive.setAppMetadataRepository(repository='AppRepos1',
        partition='partition1', type='DB', jndi='mds-jndi1') 

wls:/offline> archive.setAppSharedMetadataRepository(namespace='/a',
        repository='SharedRepos1', partition='partition2', type='File',
        path='/temp/dir')
wls:/offline> archive.save() 

In the following example, if the adf-config.xml file in the archive already has the application and shared metadata repositories defined, all arguments are optional. You can set only the arguments you want to change.

wls:/offline> archive = getMDSArchiveConfig(fromLocation='/tmp/testArchive.ear')
wls:/offline> archive.setAppMetadataRepository(partition='MDS-partition2')
wls:/offline> archive.setAppSharedMetadataRepository(namespace='/a',
         repository='SharedRepos2') 
wls:/offline> archive.save(toLocation='/tmp/targetArchive.ear')

importMAR

Command Category: Application Management Deployment

Use with WLST: Online

Description

Imports the metadata from the MAR packaged along with the application's EAR file.

Syntax

importMAR(application, server, [applicationVersion])
Argument Definition
application
The name of the application for which the metadata is to be imported.
server
The target server on which this application is deployed.
applicationVersion
Optional. The application version, if multiple versions of the same application are deployed.

Example

The following example imports metadata from the MAR to the application "mdsapp":

wls:/weblogic/serverConfig> importMAR('mdsapp','srg')
Executing operation: importMAR.
"importMAR" operation completed. Summary of "importMAR" operation is:
/app1/jobs.xml
/app1/mo.xml
2 documents successfully transferred.
wls:/weblogic/serverConfig>