This chapter describes how to migrate a WebLogic Server domain to a domain partition. The Domain to Partition Conversion Tool (D-PCT) provides the ability to migrate existing applications and resources from a non-multitenant domain to a multitenant domain partition.
This chapter includes the following sections:
Migrating a WebLogic Server Domain to a Domain Partition: Overview
Migrating a WebLogic Server Domain to a Domain Partition: Prerequisites
Migrating a WebLogic Server Domain to a Domain Partition: Main Steps
Migrating a WebLogic Server Domain to a Domain Partition: Limitations
Migrating a WebLogic Server Domain to a Domain Partition: Use Cases
WebLogic Server Multitenant (MT) supports multiple independent partitions within a WebLogic Server domain. Partitions provide isolation of applications, resources, security, and so on, from other partitions in the same domain. For information about configuring WebLogic Server MT, see Configuring WebLogic Server Multitenant (MT): The Big Picture.
The Domain to Partition Conversion Tool (D-PCT) provides the ability to migrate an existing WebLogic Server release 10.3.6, 12.1.2, 12.1.3 or 12.2.1 domain to a partition in a WebLogic Server 12.2.1 domain. It consists of two tools: an export tool, which is used on the WebLogic Server installation that hosts the source domain; and an import tool, which is used on the target WebLogic Server 12.2.1 installation.
You can use D-PCT to create and configure partitions, resource groups, and resource group templates. By default, D-PCT moves all applications, libraries, and resources to the new partition. Optionally, it also provides a mechanism for selecting individual applications, libraries, and resources.
Note:
The domain's cluster and server configurations are not applicable to a partition. Therefore, they are not mapped to the new 12.2.1 partition.Before you configure D-PCT, you must fulfill the following prerequisites:
The target domain must be configured on a WebLogic Server 12.2.1 installation.
You must download and install JDK 8 on the host machine of the source domain. This is required for running the export tool on WebLogic Server 10.3.6.
Download and install patch 22644507 on the target WebLogic Server 12.2.1 installation. This patch enables the correct operation of the partition importing functionality. You can download this patch by specifying the patch ID from My Oracle Support at http://support.oracle.com.
Oracle recommends using OPatch to install this patch. For more information, see "About OPatch" in Patching with OPatch.
The target WebLogic Server 12.2.1 domain must be up and running.
For a straightforward conversion from a domain to a partition and to ensure correct operation of the import tool to create a virtual target based on the JavaScript Object Notation (JSON) file, it is important that the target and source domains have identical cluster and server names.
By default, the import tool creates virtual targets with the specified name and target in the JSON file. However, Oracle recommends that you manually configure virtual targets before the import operation. If you preconfigure virtual targets before using the import tool, then you must ensure that you modify the partition attribute of the JSON file, where you must specify the name of the existing virtual target that you created at the target domain for this partition to use.
Before using the import tool to create a new partition, you must ensure that the new domain is configured the same as the source domain with regard to servers, clusters, virtual targets, and security realms. For information about importing partitions, see Exporting and Importing Partitions.
The main steps for configuring the Domain to Partition Conversion Tool (D-PCT) are as follows:
Preparing to Export the WebLogic Server Domain Applications Environment
Exporting the WebLogic Server Domain Applications Environment
Importing an Applications Archive File to a Domain Partition
Perform the following tasks to prepare to export the WebLogic Server domain application environment:
Download the domain export tool zip distribution to the host machine where the source WebLogic Server domain is configured. The domain export tool is available for download from Oracle Technical Network at the following location:
http://www.oracle.com/technetwork/middleware/weblogic/downloads/wls-for-dev-1703574.html
Unzip the wls1221_D-PCTx.zip file that you downloaded. You can unzip this file to any preferred directory. Oracle recommends creating a separate directory for the export tool. You must unzip the export tool zip distribution into this directory, and then run the export tool script from it as well.
This zip distribution consists of the following files:
README.txt -a file that contains documentation for installing and running the Domain to Partition Conversion Tool (D-PCT).
exportDomainForPartition.sh - a UNIX script that executes at the source WebLogic Server domain to export domain applications.
exportDomainForPartition.cmd - a Windows script that executes at the source WebLogic Server domain to export domain applications.
com.oracle.weblogic.management.tools.migration.jar - a JAR file that contains the Python script and Java classes used for exporting the source domain to a domain archive file.
Note:
The classes incom.oracle.weblogic.management.tools.migration.jar are built with JDK 8. Therefore, to run the export tool on WebLogic Server 10.3.6, the export script must be run with JDK 8 which might not be the JDK version used normally with WebLogic Server 10.3.6 installation. Before running the export script, ensure that you set the JAVA_HOME variable accordingly.Create a key file that contains a string to use as the encryption key to encrypt attributes in the partition archive file. The path must be reachable by the Administration Server. The size of the key string must range between 1to 32 characters.
To export the WebLogic Server domain applications, you must run the export script on the host machine where the source WebLogic Server domain Administration Server resides.
The syntax for the arguments passed to this script on UNIX is:
exportDomainForPartition.sh ORACLE_HOME DOMAIN_HOME [keyFile] [TOOL_JAR] [app_name] [INCLUDE_APP_BITS={true|false}]
The syntax for the arguments passed to this script on Windows is:
exportDomainForPartition.cmd ORACLE_HOME DOMAIN_HOME [keyFile] [TOOL_JAR] [app_name] [INCLUDE_APP_BITS={true|false}]
Before running the script on Windows, perform the following tasks:
Open a command shell and change to the directory where you unzipped the export tool distribution.
Set the JAVA_HOME environment variable to the path of your JDK 8 installation as shown in the following example:
C:\> set JAVA_HOME=C:\jdk1.8.0
Note:
Oracle recommends that you do not make any configuration changes at the source domain during the export operation.This script accepts the arguments described in the following table.
| Argument | Description |
|---|---|
ORACLE_HOME
|
The name of the Oracle home directory where WebLogic Server is installed.
This argument can be specified as the |
DOMAIN_HOME
|
The full path to the source WebLogic Server domain.
This argument can be specified as the |
keyFile
|
Optional. The full path to a file containing a string to use as the encryption key to encrypt attributes in the partition archive file. The Administration Server must have access to this path. |
TOOL_JAR
|
Path to the com.oracle.weblogic.management.tools.migration.jar file. This argument is optional if the JAR file is located in the same directory as the exportDomainForPartition.sh script. |
app_name
|
Optional. The list of application names to export. If not specified, all applications in the domain are exported. |
INCLUDE_APP_BITS |
Optional. A flag to indicate whether the application binary files are included in the archive file. This value defaults to true, which means the binary files are included. If false, then those files are excluded. |
Exporting the WebLogic Server Domain Applications: Examples
Example 19-1 Running the Export Domain Script on UNIX
In UNIX, the following example exports the domain from the path, /Oracle_Home/user_projects/domains/base_domain. The argument /usr/myUserKeyFile is the path to the encryption key file and download/com.oracle.weblogic.management.tools.migration.jar is the path to the export tool JAR file.
exportDomainForPartition.sh /Oracle_Home /Oracle_Home/user_projects/domains/base_domain /usr/myUserKeyFile /download/com.oracle.weblogic.management.tools.migration.jar
Example 19-2 Running the Export Domain Script on Windows
In Windows, the following example exports the domain from the path, Oracle_Home\\user_projects\\domains\\base_domain. The argument myKeyfile is the encryption key file and oracle.weblogic.management.tools.migration.jar is the export tool JAR file.
exportDomainForPartition.cmd C:\\Oracle_Home C:\\Oracle_Home\\user_projects\\domains\\base_domain myKeyfile C:\\com.oracle.weblogic.management.tools.migration.jar
Note:
While running the export domain script on a Windows command shell, you must escape the path separators.During the operation of exporting the WebLogic Server domain applications, a JSON text file is generated and stored both as an archive file and a separate file that can be edited and modified. This file specifies default values for the partition that is created during the import operation. However, you can edit the JSON file to override the default values. For instance, the JSON file specifies a default virtual target name. If you want to create a virtual target with a different name, then you can edit the JSON file to alter the value in the virtual-target section.
The following example shows a sample JSON file that is generated by the export tool and illustrates both the JSON file objects and attributes, and how they can be overridden:
{
"virtual-target" :
[ { "name":"${PARTITION_NAME}-AdminServer-virtualTarget" , "target":"AdminServer" , "uri-prefix":"/${PARTITION_NAME}" } ]
"app-deployment":
[{"name":"testApp1","exclude-from-import":"false"}],
"persistence-store":
[{"name":"WseeSoapjmsFileStore_auto_1","exclude-from-import":"false"},{"name":"WseeSoapjmsFileStore_auto_2","exclude-from-import":"false"}],
"jms-server":
[{"name":"WseeSoapjmsJmsServer_auto_1","exclude-from-import":"false"},{"name":"WseeSoapjmsJmsServer_auto_2","exclude-from-import":"false"}],
"jms-system-resource":
[{"name":"testJMSModule", "exclude-from-import":"false",
"sub-deployment":[{"name":"testJmsServer","exclude-from-import":"false"}]},
{"name":"WseeSoapjmsJmsModule","exclude-from-import":"false",
"sub-deployment":[{"name":"WseeSoapjmsJmsServer649564037","exclude-from-import":"false"}]}],
"resource-group-template" : { "name":"${PARTITION_NAME}-RGTemplate" },
"partition" : {
"default-target" : [ {"virtual-target":{ "name":"${PARTITION_NAME}-AdminServer-virtualTarget" }} ],
"jdbc-system-resource-override" : [ { "name":"MedRecGlobalDataSourceXA" ,
"url":"__EXISTING_VALUE__" ,
"user" : "__EXISTING_VALUE__" ,
"password-encrypted" : "__EXISTING_VALUE__" } ],
"jms-system-resource-override":[
{"name":"testJMSModule",
"foreign-server-override":[
{"name":"ForeignServer1",
"foreign-destination-override":[
{"name":"ForeignDestination1",
"remote-jndi-name":"__EXISTING_VALUE__"},
{"name":"ForeignDestination2",
"remote-jndi-name":"__EXISTING_VALUE__"}],
"foreign-connection-factory-override":[
{"name":"ForeignConnectionFactory1",
"remote-jndi-name":"__EXISTING_VALUE__",
"username":"__EXISTING_VALUE__" }]
}]
}],
"realm":"__EXISTING_VALUE__",
"available-target":[ {"virtual-target":{ "name":"${PARTITION_NAME}-AdminServer-virtualTarget" }} ]
}
}
The following table describes the objects and attributes that can be edited or modified in the JSON file.
| Objects and Attributes in the JSON File that Can Be Edited | Notes |
|---|---|
Root level object "virtual-target" |
By default, the import tool creates virtual targets as shown in the sample file. Oracle recommends that you manually configure virtual targets before the import operation. For information about configuring virtual targets, see Configuring Virtual Targets.
Ensure that you remove this object and any related value to prevent the automatic creation of virtual targets during the import operation. |
Object "partition" |
This object specifies elements and values required for the creation of the partition.
If you have already manually created virtual targets for this partition, then replace the |
Object "resource-group-template" |
To override the default resource group template name, edit the "name" value. |
Attribute "exclude-from-import" |
This attribute determines whether to exclude a particular object or resource from importing to a partition. See Migrating a WebLogic Server Domain to a Domain Partition: Limitations for restrictions on JMS and JDBC resource targeting in partitions.
Set this value to |
Prior to importing the domain application archive file ensure that the target WebLogic Server 12.2.1 domain is up and running.
To create a new partition in the WebLogic Server 12.2.1 domain and import the applications archive file to the newly created domain partition, perform the following steps using WLST commands in the online mode.
Connect to the target WebLogic Server domain where you want to import the domain archive file, as shown in the following example:
connect('user', 'mypassword', 't3://myserver:7001')
Run the importPartition command using the following syntax:
importPartition( archiveFileName , partitionName , createRGT=true|false , userKeyFile )
The command is asynchronous and returns the MBean ImportExportPartitionTaskMBean. This command can be used to obtain the result of the import operation in the following manner:
result = importPartition( .... )
You can use print result.getState() to obtain the import result state or print result.getError() to see the error message in case the import operation fails. For more information about this command, see WLST Command Reference for WebLogic Server.
The following table describes the arguments that must be specified for the importPartition command.
| Argument | Description |
|---|---|
archiveFileName
|
The full path to the domain archive file you want to import.
This command looks for the <domain name> |
partitionName
|
The name for the partition that is created in the target domain. |
createRGT
|
A flag that indicates whether to create a resource group template for all the resources in the archive file.
Set to |
userKeyFile
|
The absolute path to the user key file containing the same clear-text passphrase specified during the export operation. This file is used to decrypt attributes in the archive file. |
Importing an Applications Archive File to a Domain Partition: WLST Example
The following WLST command imports the outDir/<domain>.zip archive file to the new partition called testPartition. It also creates a resource group template and uses /usr/myUserKeyFile as the encryption key.
wls:/wsDomain/> importPartition( '/outDir/<domain>.zip', 'testPartition', true, '/usr/myUserKeyFile' )
The limitations for configuring the Domain to Partition Conversion Tool (D-PCT) are as follows:
While the tools support the migration of a WebLogic Server 12.2.1 domain to a WebLogic Server 12.2.1 domain partition, any existing resource groups in the source domain are omitted and not included.
The domain upgrade of libraries and resources to a new release is not supported at import. Administrators and users are responsible for possible necessary domain upgrades from the source domain before exporting the archive file.
Neither the application runtime state nor the application specific runtime configuration is exported to the archive file. For example, the JMS messages in queues or users in an embedded LDAP realm are not exported.
The remote clients compiled with WebLogic Server versions prior to 12.2.1 are not able to look up JNDI resources deployed on a partition. They need to be recompiled with the WebLogic Server releases 12.2.1 or later.
Limitations when importing JMS and JDBC resources targeted to a cluster or migratable-targets in their source domain:
Multiple JMS resources in a resource group cannot be targeted to more than one virtual target; all JMS file stores must use the same distribution policy.
JDBC does not support the use of the Logging Last Resource (LLR) feature in WebLogic Server Multitenant. Data sources with this option need to be converted to use a substitute setting that may or may not be an adequate replacement.
To avoid errors, the JMS and JDBC resources that fall within these limitations must be excluded from the import operation by using the exclude-from-import attribute in the JSON file. Such resources must be manually created within the partition as needed by the application.
The following table lists the use cases that are supported and not supported for migrating a WebLogic Server domain to a partition.
Table 19-1 Use Cases for Migration
| Source | Target | Status |
|---|---|---|
|
A single Server with no JMS servers |
A virtual target targeted to a single server |
Supported |
|
A single Server with a JMS server |
A virtual target targeted to a single server |
Supported |
|
A single Server with no JMS servers |
A virtual target targeted to a cluster |
Supported |
|
A single Server with a JMS server |
A virtual target targeted to a cluster |
Supported |
|
A cluster with no JMS servers |
A virtual target targeted to a single server |
Supported |
|
(Windows) A cluster with no JMS servers |
A virtual target targeted to a cluster |
Supported |
|
Cross platform domain migration from Windows to Linux |
A virtual target targeted to a single server |
Supported |
|
A cluster with JMS servers |
A virtual target targeted to a single server |
Not Supported |
|
A cluster with JMS servers |
A virtual target targeted to a cluster |
Not Supported |