Fusion Middleware Documentation
Advanced Search


Domain Template Reference
Close Window

Table of Contents

Show All | Collapse

1 Introduction

This document provides information about Fusion Middleware domain and extension templates, which are Java Archive (JAR) files that contain the files and scripts required to create or extend a WebLogic domain.

This document contains the following topics:

Types of Templates

The types of template include:

  • Domain template—defines the full set of resources within a domain, including infrastructure components, applications, services, security options, and general environment and operating system options.

    The WebLogic Server product installation includes a predefined Basic WebLogic Server Domain template. This template defines the core set of resources within a WebLogic domain, including an Administration Server and basic configuration information. For more information on the Basic WebLogic Server Domain template, see Basic WebLogic Server Domain Template.

    You can create a custom domain template from an existing domain by using the Domain Template Builder or the pack command. You can also create a domain template from an existing domain template by using the Domain Template Builder.

  • Extension template—defines the applications and services that you can add to an existing domain, including product component functionality and resources such as JDBC or JMS.

    The WebLogic Server product installation includes several predefined extension templates. The templates that are available to you in the Configuration Wizard depend on the product you are installing. WebLogic Server installations include the templates described in WebLogic Server Templates.

    You can create a custom extension template from an existing domain or template by using the Domain Template Builder.

  • Managed Server template—defines the subset of resources within a domain that are required to create a Managed Server domain directory on a remote machine.

    You can create a custom Managed Server template by using the pack command. For more information, see Creating Templates and Domains Using the Pack and Unpack Commands.

  • Reconfiguration template—Reconfiguration templates are automatically implemented if you are upgrading a WebLogic domain from a previous WebLogic Server version. If a currently installed product, such as WebLogic Advanced Web Services for JAX-WS, requires updates to be compatible with the domain you are upgrading, a reconfiguration template is supplied to automatically make the product compatible with the current release, such as implementing new product features. When running the reconfiguration wizard, as described in "Reconfiguring a WebLogic Domain in Graphical Mode" in Upgrading Oracle WebLogic Server, the wizard automatically detects all products that are installed, determines whether or not there is an available reconfiguration template for each product, and then applies the reconfiguration template to update that product.

    Reconfiguration templates are also provided for all Fusion Middleware products that are configured via the Fusion Middleware Configuration Wizard, such as SOA and Web Center. This makes it easy for you to update the domains for your Fusion Middleware products when upgrading to a new release of WebLogic Server.

    The JAR file name for the reconfiguration template is base_template_name_reconfig_version. For example the Web Services for JAX-WS template is wls_webservices_jaxws.jar, and the associated reconfiguration template for WebLogic Server 12.1.2 is wls_webservices_jaxws_reconfig_12.1.2.jar.

Location of Installed WebLogic Server Templates

The following table identifies the location of the predefined template JAR files provided with the WebLogic Server installation, where WL_HOME represents the product installation directory.

Table 1-1 Location of Templates

Type of Template Directory Location

WebLogic Server Domain, Extension, and Reconfiguration

WL_HOME\common\templates\wls

Fusion Middleware Extension and Reconfiguration

ORACLE_HOME\oracle _common\common\templates\wls

ORACLE_HOME\PRODUCT_HOME\common\templates\wls

Template Tools

The following table identifies the tools with which you can create templates and the tools with which you can use templates to create or extend a domain.

Table 1-2 Template Tools

To Use this tool

Create a domain

  • Configuration Wizard

  • WLST Offline

  • unpack command

Extend an existing domain

  • Configuration Wizard

  • WLST Offline

Create a Managed Server domain on a remote machine

  • unpack command

  • WLST writeTemplate command (online)

Create a domain template

  • Domain Template Builder

  • pack command

  • WLST Offline

Create an extension template

Domain Template Builder

Create a Managed Server template

pack command

Upgrade a domain

Reconfiguration Wizard


Note:

All the tools used to create or extend a domain leverage a common underlying infrastructure, which is referred to as the configuration framework.

Template Dependencies

WebLogic Server resources must be set up in your domain before you can add resources from an extension template. This is known as a template dependency. For example, all extension templates provided with your product are dependent on, at the very least, the Administration Server and security realm resources that are configured by the Basic WebLogic Server Domain template. Other extension templates depend on resources from multiple templates. For example, to extend a domain to support the WebLogic Server Examples, the existing domain must already contain the resources from the Basic WebLogic Server Domain template and the WebLogic Server Default Domain extension template.

The template-info.xml file in a template JAR defines the template dependencies for a given template. Dependencies are chained. For example:

  • Template A defines a dependency on Template B and Template C in its template-info.xml file.

  • Template B defines a dependency on Template D and Template E in its template-info.xml file.

  • Template C defines a dependency on Template F in its template-info.xml file.

In this example, if you select Template A on the Configuration Wizard's Templates screen, templates B, C, D, E, and F are automatically included in the domain. If any of these templates are displayed on the Templates screen, you will see the check boxes for those template automatically selected. This ensures that when you select a product template on the Configuration Wizard Templates screen, the Configuration Wizard automatically includes in the domain all other product templates that configure resources required by the product you selected.

Similarly, if you specify a template JAR in a WLST script, all other templates that are dependencies of that template (either directly or indirectly) are included in the domain. Using the above example, if you specify Template A in a WLST script, templates B, C, D, E, and F are also included in the domain without you having to explicitly specify them in the script.

Files Typically Included in a Template

The basic files included in any template are config.xml and template-info.xml. A domain is created or extended based on these files, as well as additional files that are included in the template. The following table describes the files typically included in domain and extension templates.

Table 1-3 Files Included in a Template

Filename Description

product component files

Various files used to complete the domain setup for a specific Oracle product component. Such files may provide information for security and default database settings.

*-jdbc.xml

Sets up or extends a domain with JDBC system resources required by a product component. In a template, the *-jdbc.xml files must be located in the config\jdbc directory. There is one XML file for each JDBC resource in the domain. These files are present only if the domain includes JDBC resources.

*-jms.xml

Sets up or extends a domain with JMS system resources required by a product component. In a template, the *-jms.xml files must be located in the config\jms directory. This is applicable only if the domain requires JMS resources.

clusters.script

Used to modify the Configuration Wizard framework's default auto-configuration of a cluster. By default, resources are targeted to the cluster. You can unassign a resource from the cluster and then assign it to another component. To specify a target, you can use the following replacement variables:

  • %AManagedServer%—Any Managed Server

  • %AllManagedServers%—Comma-separated list of all Managed Servers

  • %AdminServer%—Administration Server name

  • %Cluster%—Cluster name

  • %ProxyServer%—Proxy server name

  • %HTTPProxyApp%—http proxy application definition

Note the following additional considerations:

  • You must use the name attribute of an object that is to be replaced.

  • You can use an asterisk (*) as a wildcard for "All."

This file is not required. When used, it must be located in the script directory. If it is not present, default targeting is used.

config.xml

Defines the resources that the template creates or adds to a domain. In a template, the config.xml file must be located in the config directory.

config-groups.xml

This file contains definitions of applications, services, servers, clusters, and mappings that create a relationship among these items. It enables movement of functionally related applications and services as a single operation when transitioning from one topology to another (for example, from a single server to multiple servers, or from a single server to a cluster). This ensures that all application and service dependencies are met when scaling a domain configuration.

Note: Do not modify this file in any way. It must be used as provided in the template.

An Application/Service group specifies a set of functionally related applications and services. The applications and services are grouped together on a particular server or cluster.

The Domain Topology section contains definitions of servers, as well as the targeting of applications and services to a specific server, group or servers or clusters. It contains the following definitions:

  • Server group definitions—Specifies a server or servers that can house functionally related sets of applications and services, thereby enabling automatic server creation.

  • Cluster group definitions—Specifies a cluster that can house functionally related sets of applications and services, thereby enabling automatic cluster creation.

  • Application/Service group mapping definitions—Specifies targeting of an Application/Service group to a specific server, group of servers, or cluster, via the name of the Application/Service group.

As of WebLogic Server 12.1.2, the domain topology section may define separate server groups, startup groups, and application/service group mapping definitions for compact and expanded domain profiles. For more information about domain profiles, see config-groups.xml and startup-plan.xml.

config-mapping.xml

This file is used to dynamically assign values to custom variables that are defined in a deployment plan, using name/value pairs.

database.xml

This file is included only in Fusion Middleware product templates that require JDBC data source definitions. It groups data sources into component schemas that are required to configure and load data into database objects via the Oracle Repository Creation Utility (RCU). It also contains the eligible database vendors and drivers, eliminating the possibility of selecting an unsupported database in the Fusion Middleware Configuration Wizard.

Note: Do not modify this file in any way. It must be used as provided in the template.

file-definition.xml

Applies only to Fusion Middleware product templates. It defines file copy and string substitution operations that are done during domain creation or extension. String substitution operations are supported only for WebLogic Server and not supported in a WebSphere environment.

jdbc.index

Identifies the locations of SQL scripts used to set up a database. The file lists the scripts in the order in which they must be run. If the scripts are not contained in the template, but are located in the product installation directory, that directory can be represented by a tilde ( ~ ) in the pathname for the scripts, as shown in the following example:

~/integration/common/dbscripts/oracle/reporting_runtime.sql

Specifically, the tilde represents the directory path identified by the $USER_INSTALL_DIR$ variable in the stringsubs.xml file.

In a template, a jdbc.index file must be located in the _jdbc_\dbtype\dbversion directory, where dbtype is the type of database, such as Oracle, and dbversion is the database version, such as 9i.

In addition to listing the SQL files related to a data source, the jdbc.index file contains information about the categories associated with the data source. The default dbCategories that are available are:

  • 'Drop/Create P13N Database Objects' category associated with the p13nDataSource data source, which is a part of the p13n.jar domain template.

  • 'Drop/Create Portal Database Objects' category associated with the "p13nDataSource" data source, which is a part of the wlp.jar domain template.

  • 'Drop/Create GroupSpace Database Objects' category associated with the appsGroupSpaceDataSource data source, which is a part of the wlp_groupspacedb.jar domain template.

All these template jar files are located in the WL_HOME\common\templates\applications directory.

jvm-config.xml

This file is specific to FMW product installations in a WebSphere environment, and can be ignored in a WebLogic Server environment.

security.xml

Used to create user groups and roles that establish identity and access to domain resources. You can create the default Admin user only through the security.xml file in a domain template. However, you can create user groups and roles through the security.xml file included in either a domain or an extension template.

startscript.xml

Used to create the *.cmd and *.sh files that are placed into a domain's root and bin directories.

startup-plan.xml

Defines startup parameters for WebLogic Server instances, at the domain level or server group level. One or more of the following startup parameters may be defined in this file:

  • Environmental variables

  • Java system properties

  • Java protocol handlers

  • WLS PRE_CLASSPATH

  • WLS POST_CLASSPATH

  • Java library path

  • WLS JVM initial heap size

  • WLS JVM maximum heap size

  • WLS JVM perm size

  • WLS JVM maximum perm size

  • Other java arguments

If the template defines both compact and expanded domain profiles, separate groups of startup parameter definitions are defined, one group for each profile type. The startup parameters used for your domain may differ depending on whether you create a compact or expanded domain. For more information about domain profiles and startup groups, see config-groups.xml and startup-plan.xml.

stringsubs.xml

Identifies string substitution values and files that will receive string substitutions during domain creation or extension. The files that will receive string substitutions must already be prepared with replacement variables. During domain creation or extension, the Configuration Wizard framework runs macros to replace variables with the appropriate string substitution, using information from WL_HOME\common\lib\macrorules.xml, where WL_HOME is the WebLogic Server installation directory.

template-info.xml

Provides template identification information, such as the template name, software version, type of template (domain or application), author, description, and so on. This file also includes template dependency information (if applicable).

was-variable.xml

This file is specific to FMW product installations in a WebSphere environment, and is ignored in a WebLogic Server environment.


config-groups.xml and startup-plan.xml

Many templates contain a config-groups.xml file. If present, it defines one or more of the following items:

  • domain topology profile

  • one or more server groups

  • application service groups

  • one or more startup groups

Some templates also contain a startup-plan.xml file, which defines server startup parameters at a global (domain-wide) level or server group level.

When you create a domain using multiple templates, the config-group.xml files from all templates included in the domain are used to create the config-groups.xml file for the domain.

Similarly, the startup-plan.xml files from all templates included in the domain are merged to create the startup-plan.xml file for the domain. At domain creation, the merged startup plan is used to generate the appropriate scripts for the domain.

The merged config-groups.xml and startup-plan.xml files are stored in the domain's init-info directory.

Note:

Do not manually edit either the config-groups.xml or startup-plan.xml files in the init-info directory.

The following sections describe each of these items in detail and how they work together in a domain.

Domain Topology Profiles

When creating a domain, you specify the domain topology profile (Compact or Expanded) to use for that domain. Domain profiles are defined only in some Fusion Middleware product templates, and do not apply to domains in which no Fusion Middleware products are installed with WebLogic Server.

Note:

You can explicitly specify the domain topology profile only if you use WLST to create the domain. Graphical interfaces automatically configure the appropriate profile. For example, when creating a domain using the JDeveloper domain creation utility, the domain is created with a Compact profile; when creating a domain using the Fusion Middleware Configuration Wizard, the domain is created with an Expanded profile.

The config-groups.xml file in a Fusion Middleware product template may define the domain profiles for the domain, in the profile attribute of the <domain-topology> element. The domain profile can be either Compact (or single-instance) or Expanded (clustered). If the <domain-topology> does not define separate Custom and Expanded profiles, the configuration defined in <domain-topology> is used for both types of domains.

The domain profile defines:

  • The server groups for the profile.

  • Which server group is the Administration Server server group. The Administration Server group is not user-expandable.

  • Whether or not a server group is user-expandable, that is, whether or not you can assign Managed Servers to it. Note that if a server group is not user-expandable, you can still assign Managed Servers to it by cloning an existing server that is already assigned to the server group.

    Note:

    Use the WLST offline command listServerGroups() to list all user-expandable server groups in the domain.

  • The application service groups that are targeted to each defined server group. All servers that are assigned to a server group inherit its targets.

  • Whether or not a prefix is assigned to the name of any servers that are added to the server group. For example, if a prefix of 'xyz' is defined for the server group, and you add a server called 'server2' to the group, the server name is registered as 'xyz_server2'.

Table 1-4 describes the differences between Expanded and Compact domain profiles.

Table 1-4 Differences Between Expanded and Compact Domains

Expanded Domain Compact Domain

Also known as a clustered domain.

Also known as a single-instance domain.

Contains an Administration Server. Contains Managed Servers for the Fusion Middleware product(s) in the domain. Fusion Middleware Managed Servers can be assigned to clusters.

Contains only an Administration Server, with no Managed Servers or clusters for the Fusion Middleware product(s) in the domain. This domain type is uses primarily for development purposes.

Defines an Administration Server server group and one or more Managed Server server groups.

Defines an Administration Server server group. Although a Managed Server server group may be defined in config-groups.xml, it is not used.

All application service groups defined in config-groups.xml are targeted. Some application service groups are targeted to the Administration Server server group, other application service groups are targeted to the Managed Server server group(s).

All or a subset of the defined application service groups are targeted to the Administration Server server group. Some application service groups may not be targeted.


There are two ways to select the domain profile for a new domain:

  • When creating a domain using the FMW Configuration Wizard, you select the profile to use on the Configuration Type screen. See "Configuration Type" in Creating Domains Using the Configuration Wizard.

  • When creating a domain using WLST, you specify the profile to use in the readTemplate command. See "readTemplate" in WebLogic Scripting Tool Command Reference. The default profile type is Expanded.

Application Service Groups, Server Groups, and Application Service Mappings

The config-groups.xml file in Fusion Middleware templates may define application service groups, server groups, and application service mappings. This automates the assignment of applications and services to the appropriate servers in the domain.

  • Application service group—These are defined in the <app-svc-groups> element. Each <group> element defines a unique application service group, which contain various applications and services that will be included in the domain, such as application deployments, work managers, JMS system resources, libraries, and other items that are needed in the product domain. Application service groups are always the same for each domain profile, although some application service groups may not be used in a Compact domain. Application service groups may be mapped to multiple server groups.

  • Server Group—A named server group. Typically, there is at least one Administration Server group and at least one Managed Server group defined in a domain's config-groups.xml file. These are defined by a <server-group> element in the <domain-topology> element. Note that although a Compact profile may define both Administration Server and Managed Server server groups, only the Administration Server server group is used in a Compact domain.

    If a server group is defined as user-expandable, you can add Managed Servers to the server group. User-expandable servers are listed in the Server Groups drop-down list of the Managed Server screen of the Fusion Middleware Configuration Wizard. In WLST, you can determine which server groups are user-expandable by using the listServerGroups command.

  • Application Service Mappings—Define which application service groups are mapped to each defined server group. These mappings differ depending on the domain profile. They are defined in the <app-svc-group-mapping> elements in the <domain-topology> element of config-groups.xml.

Server groups target Fusion Middleware applications and services to one or more servers by mapping defined application service groups to each defined server group. A given application service group may be mapped to multiple server groups if needed. Any application services that are mapped to a given server group are automatically targeted to all servers that are assigned to that group.

For example, suppose that the following items are defined in config-groups.xml:

  • Server group ADMIN-SVR (the server group for the Administration Server)

  • Server group MGD-SVRS (the server group for Managed Servers)

  • Application service group ADMIN-APPS, which defines the application services that will run only on the Administration Server

  • Application service group MAIN-APPS, which defines applications that will run on Managed Servers

  • Application service group MAIN-LIBS, which defines libraries that need to be targeted to the Administration Server and Managed Servers

  • An application service mapping that maps MAIN-APPS to the MGD-SRVS server group

  • An application service mapping that maps ADMIN-APPS to the ADMIN-SVR server group

  • An application service mapping that maps MAIN-LIBS to the ADMIN-SVR server group

  • An application service mapping that maps MAIN-LIBS to the MGD-SVRS server group

In this example, all applications and other resources that are defined in ADMIN-APPS are targeted to the Administration Server. All applications and other resources that are defined in MAIN-APPS are targeted to all Managed Servers. All libraries that are defined in MAIN-LIBS are targeted to the Administration Server and all Managed Servers.

Add a Server To or Remove a Server From a Server Group

You can use the WLST setServerGroups() command to add a server to any user-expandable server group or any server group that you created. You can also remove a server from any server group. The following examples demonstrate this.

# add a server to a server group
setServerGroups('my_server4', 'XYZ-MAN-SRVS', '180000')

# remove a server from a server group by setting the group to null
serverGroup = []
setServerGroups('my_server3', serverGroup

Startup Groups

The startup-plan.xml file in a template defines the startup groups, which allow different startup parameters to be defined for different servers or groups of servers in a domain. A domain template may contain:

  • a global startup definition, which defines the domain-wide startup settings for all servers in the domain.

  • one or more server startup groups, which are associated with a server group. If present, these define the startup settings for all servers assigned to the server group. If a server startup group defines a setting that is already defined at the global level, the server-level setting takes precedence.

Different startup settings may be defined for Expanded and Compact domain profiles. In addition, when creating a domain, multiple templates may be applied to a domain. Therefore, all possible startup settings and startup groups are combined into a single startup-plan. xml file in the domain's /init-info directory. When you start a server, this file is referenced to determine:

  • The startup group (if any) to which a server is assigned, based on the server group to which the server is assigned and the startup group to which the server group is assigned.

  • The startup settings to use for the server, based on the startup group to which the server's server group is assigned.

If a server is not assigned to a server group, it is started using the global settings that are defined in startup-plan.xml.

startup-plan.xml in Table 1-3 lists the startup parameters that may be configured in this file.

Managing Server Startup Configuration

Although the merged startup-plan.xml file for a domain defines the startup parameters for the servers in the domain, in some situations, you may want to use offline WebLogic Scripting Tool (WLST) to:

  • Create your own startup groups to define unique startup parameters for one or more servers in the domain.

  • Adjust the startup parameters for a server group.

  • Add a server to or remove a server from a startup group. Note that although you can remove a server from a server group that is not user-modifiable, you can only add a server to either a user-modifiable server group or a server group that you have created.

The startup-plan.xml file for a domain is automatically updated with any changes you make to the startup configuration.

Creating and Modifying a Startup Group

You can create a new startup group from any existing server group in the domain. The new startup group inherits only the startup parameters from the server group you used to create the startup group. You can then change the startup parameter settings for the new startup group and assign individual servers to it.

There are two ways you can determine the server groups in a domain:

  • Enter the WLST command listServerGroups(). This displays only user-expandable server groups.

  • Open the domain's init-info/config-groups.xml file. Server group names are defined by the name attribute of each <server group> element in this file.

The following WLST example shows how to create a new startup group called XYZ-MGD-SVRS based on server group JRF-MAN-SVR, add a server to the group, and view and adjust the settings for the new group.

Example 1-1 Creating and Modifying a Startup Group

# Create a new startup group called XYZ-MGD-SVRS based on the startup settings 
# for server group JRF-MAN-SVR
addStartupGroup('XYZ-MGD-SRVS', 'JRF-MAN-SVR')

# Set the startup group for my_server1 to XYZ-MGD-SRVS
setStartupGroup('my_server1', 'XYZ-MGD-SRVS')
# select the XYZ-MGD-SRVS startup group for modification
cd('/StartupGroupConfig/XYZ-MGD-SRVS')

# display the setting for MaxHeapSize 
get('MaxHeapSize')
'1024'
# change the setting for MaxHeapSize
set('MaxHeapSize', '1536')

# get Java system properties for a startup group as a Python dictionary
dictionary = get('SystemProperties')

# set Java system properties for a startup group
dictionary['key.1'] = 'value.1'
dictionary['key.2'] = 'value.2'
set('SystemProperties',dictionary)

# get Java environment settings for a startup group as a Python dictionary
dictionary = get('EnvVars')

# set Java system properties for a startup group
dictionary['env.1'] = 'value.1'
dictionary['env.2'] = 'value.2'
set('EnvVars',dictionary)

Note:

Calling set('EnvVars',{}) resets all customizations, and environment variables for the startup group will revert back to the settings derived from the server groups associated with the startup group.