This chapter includes the following sections:
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 Oracle WebLogic Server Multitenant.
The Domain to Partition Conversion Tool (D-PCT) provides the ability to migrate an existing WebLogic Server release 10.3.6, 12.1.2, or 12.1.3 domain to a partition in a WebLogic Server 12.2.1.x 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.x 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.x partition.
The Domain to Partition Conversion tool has introduced new features in 12.2.1.1.0. The following are the significant changes:
D-PCT now provides support for targeting resources and applications to multiple virtual targets.
In the previous release, you could use D-PCT to target all the resources in the source domain to only one virtual target. As of 12.2.1.1.0, you can use this tool for targeting resources and applications to multiple WebLogic Servers and clusters using multiple virtual targets, where each virtual target is associated to a single WebLogic Server instance or a cluster. All application deployments and resources targeted to that particular WebLogic Server instance or cluster in the source domain corresponds to a resource group in the target domain.
In order to accomplish this, the structure of the JSON file generated by D-PCT in 12.2.1.1.0 is modified. Therefore, any archive generated from the initial release of D-PCT cannot be imported into a 12.2.1.1.0 domain. An error will be reported during the import operation. For existing domain archives, you must regenerate a new domain archive using the D-PCT 12.2.1.1.0 tooling to enable it to be imported into the 12.2.1.1.0 domain.
D-PCT has enhanced support for JMS resources targeted to clusters and migratable targets. For more information, see Considerations and Limitations for Importing a Domain with JMS Resources.
The JSON file generated by D-PCT in 12.2.1.1.0 gives more flexibility to the users, by exposing the JDBC System Resources, SAF Agents, Mail Sessions and JDBC Stores. These resources are available as JSON objects, jdbc-system-resource, saf-agent, mail-session, and jdbc-store respectively.
Before you configure D-PCT, you must fulfill the following prerequisites:
The target domain must be configured on a WebLogic Server 12.2.1.x 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.
The target WebLogic Server 12.2.1.x 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:
Perform the following tasks to prepare to export the WebLogic Server domain application environment:
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}] [WL_HOME]
or
export-domain.sh -oh {ORACLE_HOME} -domainDir {DOMAIN_HOME} [-keyFile {KEYFILE}] [-toolJarFile {TOOL_JAR}] [-appNames {APP_NAMES}] [-includeAppBits {INCLUDE_APP_BITS}] [-wlh {WL_HOME}]
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}] [WL_HOME]
or
export-domain.cmd -oh {ORACLE_HOME} -domainDir {WL_DOMAIN_HOME} [-keyFile {KEYFILE}] [-toolJarFile {TOOL_JAR}] [-appNames {APP_NAMES}] [-includeAppBits {INCLUDE_APP_BITS}] [-wlhL_HOME}]
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. The default value is |
TOOL_JAR
|
Path to the |
app_name
|
Optional. The list of application names to export. On Windows, the list of applications must be specified as [myapp1 |
INCLUDE_APP_BITS |
Optional. A flag to indicate whether the application binary files are included in the archive file. This value defaults to |
WL_HOME
|
Optional. The full path to the directory where WebLogic Server is installed. This value must be specified only if WebLogic Server 10.3.6 is installed in a directory other than the default location, |
Note:
While specifying optional arguments for the exportDomainForPartition.cmd and exportDomainForPartition.sh scripts, ensure that you specify None for any optional argument that you do not wish to supply, before passing the next optional argument. If you pass an optional argument with a valid value without specifying None for the previous optional argument, then the value you specified may get wrongly assigned to the previous argument. However, you do not need to specify None for the optional argument that appears after the last optional argument with a valid value.
Exporting the WebLogic Server Domain Applications: Examples
Note:
While running the export domain script on a Windows command shell, you must escape the path separators.
Example 18-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
Or
export-domain.sh -oh /Oracle_Home -domainDir /Oracle_Home/user_projects/domains/base_domain -keyFile /usr/myUserKeyFile
Example 18-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
Or
export-domain.cmd -oh C:\\Oracle_Home -domainDir C:\\Oracle_Home\\user_projects\\domains\\base_domain -keyFile myKeyfile
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 these 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}"
}],
"resource-group": [{
"name": "${PARTITION_NAME}-AdminServer-RG",
"target": [{
"virtual-target": {
"name": "${PARTITION_NAME}-AdminServer-virtualTarget"
}
}],
"app-deployment": [{
"name": "sampleStandaloneApplication1",
"exclude-from-import": "false",
"sub-module-targets": [
{
"name": "sampleAppSubdeployment1",
"targets": "__EXISTING_VALUE__"
}
]
},
{
"name": "sampleJMSApplication1",
"exclude-from-import": "false",
"jms-modules": [
{
"name": "sampleAppJmsModule1",
"sub-module-targets": [
{
"name": "sampleAppJmsModuleSubdeployment1",
"targets": "__EXISTING_VALUE__"
}
]
},
{
"name": "sampleAppJmsModule2",
"sub-module-targets": [
{
"name": "sampleAppJmsModuleSubdeployment2",
"targets": "__EXISTING_VALUE__"
}
]
}
]
}],
"library": [{
"name": "sampleCustomLibrary1",
"exclude-from-import": "false"
},
{
"name": "sampleSharedLibrary1",
"exclude-from-import": "false",
"source-path": "${WL_HOME}\/common\/deployable-libraries\/sampleSharedLibrary1.war",
"require-exact-version": "false"
}],
"file-store": [{
"name": "sampleFileStore1",
"exclude-from-import": "false"
},
{
"name": "sampleFileStore2",
"exclude-from-import": "false"
}],
"jdbc-store": [{
"name": "sampleJDBCStore1",
"exclude-from-import": "false",
"prefix-name": "__EXISTING_VALUE__"
},
{
"name": "saf_jdbc_store_3",
"exclude-from-import": "false",
"prefix-name": "__EXISTING_VALUE__"
}],
"messaging-bridge": [{
"name": "SampleJMSMsgBridge",
"exclude-from-import": "false",
"jms-bridge-destination": [{
"name": "SrcBridgeDestn",
"connection-url": "__EXISTING_VALUE__",
"user-name": "__EXISTING_VALUE__",
"user-password": "__EXISTING_VALUE__"
},
{
"name": "TgtBridgeDestn",
"connection-url": "__EXISTING_VALUE__",
"user-name": "__EXISTING_VALUE__",
"user-password": "__EXISTING_VALUE__"
}]
}],
"jms-server": [{
"name": "sampleJMSServer1",
"exclude-from-import": "false"
},
{
"name": "sampleJMSServer2",
"exclude-from-import": "false"
}],
"jdbc-system-resource": [{
"name": "SampleDataSourceXA",
"exclude-from-import": "false"
}],
"jms-system-resource": [{
"name": "sampleJMSModule1",
"exclude-from-import": "false",
"sub-deployment": [{
"name": "sampleSubDeployment1",
"exclude-from-import": "false"
}]
},
{
"name": "sampleJMSModule2",
"exclude-from-import": "false",
"sub-deployment": [{
"name": "sampleSubDeployment2",
"exclude-from-import": "false"
}],
"saf-remote-context": [{
"name": "sample_saf_remote_ctx",
"loginURL": "__EXISTING_VALUE__",
"username": "__EXISTING_VALUE__",
"password": "__EXISTING_VALUE__"
}]
}],
"resource-group-template": {
"name": "${PARTITION_NAME}-AdminServer-RGTemplate"
}
}],
"partition": {
"default-target": [{
"virtual-target": {
"name": "${PARTITION_NAME}-AdminServer-virtualTarget"
}
}],
"jdbc-system-resource-override": [{
"name": "SampleDataSourceXA",
"url": "__EXISTING_VALUE__",
"user": "__EXISTING_VALUE__",
"password-encrypted": "__EXISTING_VALUE__"
}],
"jms-system-resource-override": [{
"name": "sampleJMSModule1",
"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"
}
}]
},
"implementation-version": "12.2.1.2"
}
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 |
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 |
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 |
To override the default resource group template name, edit the |
|
Object |
|
|
Attribute |
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 and Considerations for restrictions on JMS and JDBC resource targeting in partitions. Set this value to |
|
Attribute |
This attribute determines whether to use the shared library with a different implementation version that is available at the target or use the shared library imported from the source domain. Set this value to The default value is |
Prior to importing the domain application archive file ensure that the target WebLogic Server 12.2.1.x domain is up and running.
To create a new partition in the WebLogic Server 12.2.1.x domain and import the applications archive file to the newly created domain partition, perform the following steps using WLST commands in the online mode.
Example 18-3 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' )
You can monitor and analyze the export and import operation using the reports generated by D-PCT. The export and import reports provide useful information when you migrate resources from the source domain to the target domain partition using D-PCT.
The export report gets stored in the directory where the domain archive is created under the D-PCT installation directory, in the format domain name-ExportLogReport.html. It contains information such as, the domain location, the source WebLogic Server version, along with a list of all resources that are supported or not supported for export by the tool. You can use the export report to view the list of servers and resources that were successfully exported or the ones that failed to export. You can also view the list of resources that were untargeted and not exported, or the resources that were targeted (to more than one server or cluster) but were not exported.
The import report gets stored in the domain directory in the format, PartitionName_MigrationImportReport.html. This report contains information about the virtual targets that get created during the import operation, along with the resource group and their targeting information. You can use this report to view the list of resources that were successfully imported to the domain partition. It also lists the resources that were excluded by the user, or the ones which were ignored by the tool because they were not compatible in a multitenant environment.
This section describes the limitations of the Domain to Partition Conversion Tool (D-PCT). The following scenarios are not supported by this tool:
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.
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.
This section lists the limitations and other behaviors that you must consider before exporting a domain containing one or more JMS resources.
If a subdeployment within a JMS system module is targeted to one or more cluster(s) or migratable target(s) or WebLogic Server instances, and if it is referred by a uniform distributed destination, then you must modify the subdeployment targeting to the respective JMS servers that are targeted to the cluster or migratable target or WebLogic Server.
Uniform Distributed Destinations and SAF Imported Destinations using default targeting in the source domain will be left untargeted after successful import. If a uniform distributed destination or a SAF imported destination or a Foreign Server is default targeted, then you must modify them to use subdeployment targeting by targeting the resources to appropriate JMS servers or SAF Agents.
Ensure that a single JMS server does not host conflicting JMS Resources, such as hosting a standalone destination and a uniform distributed destination. During the export operation, if D-PCT finds a JMS server hosting one of the conflicting resources, then the corresponding JMS system module is omitted from export. This is because each of these resources require a JMS server that references a persistence store with varying distribution policies. For more information, see Configuring JMS Servers.
Weighted distributed destinations are deprecated and are not supported by JMS in a multitenant environment. Therefore, D-PCT ignores weighted distributed destinations. Oracle recommends that you convert any weighted distributed destination resource to its equivalent uniform distributed destination resource. For information about configuring the different types of distributed destination resources, see Configuring Distributed Destination Resources in Administering JMS Resources for Oracle WebLogic Server.
At the domain level, JMS resources can be targeted to multiple WebLogic servers or clusters. However in a partitioned environment, the JMS resources are not supported if the resource group is targeted to multiple virtual targets. Therefore, D-PCT ignores the application deployments and all other resources targeted to more than one WebLogic Server instance or cluster or migratable targets in the source domain.
JMS does not support the Replicated forwarding policy for a uniform distributed topic in a partitioned environment. Therefore, in such cases, D-PCT converts the forwarding policy to Partitioned. For information about the uniform distributed topic message forwarding policy, see Configuring Partitioned Distributed Topics in Administering JMS Resources for Oracle WebLogic Server.
If there are more than one JMS servers, each targeted to a migratable target or a WebLogic Server member of the same cluster, then the import operation consolidates all JMS servers to a single JMS server configured with a store having the distribution policy Distributed. The other JMS servers are ignored during the import operation.
In a partitioned environment, JMS allows a subdeployment to have only one JMS server or one SAF agent as its target. If the source domain has a subdeployment targeted to more than one JMS server or SAF Agent, then they would be sorted alphabetically and the first one would be chosen as the target of the subdeployment. Default targeted Connection Factories are migrated as it is and are referenced to the target of the resource group under which the JMS system module is created.
In a partitioned environment, only the JMS server referencing the persistence store with distribution policy Singleton can host standalone destinations. The source domains supported by D-PCT do not support distribution policy since the concept of distribution policy is introduced recently in WebLogic Server 12.2.1. To workaround this limitation set by JMS, D-PCT automatically sets the distribution policy of the persistence store referenced by JMS Servers hosting standalone destinations.
At the domain level configuration, JMS allows multiple messaging bridges to use the same bridge destination as the source or the target destination. However, the new validation introduced by JMS requires that when the messaging bridge and bridge destinations are configured in a partitioned environment, the bridge destination can be used either as a source or the target destination by only one messaging bridge. Keeping this in mind, D-PCT takes the following approach during migration to a partition:
A bridge destination from the source domain is created in the target partition only when a message bridge references that bridge destination.
When D-PCT finds a bridge destination that is already used by a messaging bridge as a source or a target destination, the name of the bridge destination is internally modified to original bridge destination name_the name of the messaging bridge that references this bridge destination.
Note:
D-PCT allows you to exclude one or more application deployments or resources from importing if those resources are not supported by the tool. You can exclude such resources from importing by setting the exclude-from-import attribute in the JSON file to true. Such resources can, then, be manually created within the partition as needed.