Home / Middleware / Oracle WebLogic Server

20 Configuring Partition Concurrent Managed Objects

This chapter describes how to configure partition-level concurrent managed object templates and concurrent constraints in WebLogic Server Multitenant (MT). You can use the WebLogic Server Administration Console to configure partition CMOs, as described in this chapter.

This chapter includes the following sections:

• Configuring Partition Concurrent Managed Templates: Overview

• Configuring Partition CMO Templates: Main Steps

• Configuring Partition Concurrent Constraints: Main Steps

• Configuring Partition Concurrent Managed Objects: Related Tasks and Links

Configuring Partition Concurrent Managed Templates: Overview

The Concurrency Utilities for Java EE 1.0 (JSR 236) implements a standard API for providing asynchronous capabilities to Java EE application components, such as servlets and EJBs. In WebLogic Server, concurrent managed objects (CMOs) provide concurrency capabilities to Java EE applications. You can configure concurrent managed objects and then make them available for use by application components.

In addition to providing support for domain and server-level CMOs, WebLogic Server also provides partition-level CMO templates to perform partition scoped task execution. This document will only discuss CMO templates as they apply to partitions.

Concurrent Managed Object Components

The primary components of the concurrency utilities are:

• ManagedExecutorService (MES)—Used by applications to execute submitted tasks asynchronously. Tasks are executed on threads that are started and managed by the container. The context of the container is propagated to the thread executing the task.

• ManagedScheduledExecutorService (MSES)—Used by applications to execute submitted tasks asynchronously at specific times. Tasks are executed on threads that are started and managed by the container. The context of the container is propagated to the thread executing the task.

• ManagedThreadFactory (MTF)—Used by applications to create managed threads. The threads are started and managed by the container. The context of the container is propagated to the thread executing the task.

• ContextService—Used to create dynamic proxy objects that capture the context of a container and enable applications to run within that context at a later time or be submitted to a Managed Executor Service. The context of the container is propagated to the thread executing the task.

For more detailed information, see "Concurrency Utilities for Java EE" in The Java EE 7 Tutorial. Also see the Java Specification Request 236: Concurrency Utilities for Java EE 1.0 (http://jcp.org/en/jsr/detail?id=236).

Partition-Level Asynchronous Task Management by CMOs

In WebLogic Server, asynchronous task management is provided by four types of CMOs, as summarized in Table 20-1.

Table 20-1 CMOs That Provide Asynchronous Task Management

Managed Object	Context Propagation	Self Tuning	Thread Interruption While Shutting Down	Limit of Concurrent Long-Running New Threads
Managed Executor Service (MES)	Contexts are propagated based on configuration.	Only short-running tasks are dispatched to the single self-tuning thread pool by a specified Work Manager.	When Work Manager is shutting down, all the unfinished task will be canceled.	The maximum number of long-running threads created by MES/MSES can be configured to avoid excessive number of these threads making negative effect on server.
Managed Scheduled Executor Service (MSES)	Contexts are propagated based on configuration.	Same behavior as MES.	Same behavior as MES.	Same behavior as MES.
Context Service	Contexts are propagated based on configuration.	n/a	n/a	n/a
Managed Thread Factory (MTF)	Contexts are propagated based on configuration.	Threads returned by the newThread() method are not from the single self-tuning thread pool and will not be put into the thread pool when the task is finished.	Threads created by the newThread() method will be interrupted when the MTF is shutting down.	The maximum number of new threads created by MTF can be configured to avoid excessive number of these threads making negative effect on server.

There are three types of JSR236 CMOs in WebLogic Server, each one characterized by its scope and how it is defined and used.

• Default Java EE CMOs—Required by the Java EE standard that default resources be made available to applications, and defines specific JNDI names for these default resources.

• Customized CMOs in Configuration Files—Can be defined at the application and module level or referenced from an application component environment (ENC) that is bound to JNDI.

• Global CMO Templates—Can be defined globally as templates in the domain, server, and partition level configuration by using the WLS Administration Console and configuration MBeans.

Note:

This document only discusses Global CMO Templates as they apply to domain partitions For detailed conceptual information about Default Java EE CMOs and Customized CMOs in Configuration Files, see "Configuring Concurrent Managed Objects" in Administering Server Environments for Oracle WebLogic Server.

Similar to Work Managers, global CMO templates can be defined at the domain, server, and partition level using the WLS Administration Console or configuration MBeans. For more information about configuring CMOs at the partition level, see Configuring Partition CMO Templates: Main Steps.

Partition-Level MES Template Configuration Elements

This section defines the configuration elements for a partition-level MES template.

Table 20-2 Managed Executor Service Configuration Elements

Name	Description	Required	Default Value	Range
name	Name of the MES. The name should not be DefaultManagedExecutorService, otherwise the server cannot be started normally. Partition-level MES with the same name can NOT be configured in the same partition, otherwise the server cannot be started normally. An ManagedExecutorService can have the same name as other types of managed objects such as a ContextService in any partition with no relationship between them. An partition-level MES and a JSR236 MES can have the same name with no relationship between them. If a partition-level MES with the same name is defined in both <resource-group-template> and one partition's <resource-group>, then the <resource-group> definition will override <resource-group-template> definition in that partition.	Yes	n/a	An arbitrary non-empty string.
dispatch-policy	Name of the Work Manager. The partition-level Work Manager will be picked by this name. If the Work Manager does not exists, use the partition-level default Work Manager.	No	Default Work Manager	n/a
max-concurrent-long-running-requests)	Maximum number of concurrent long running tasks.	No	10	[0-65534]. When out of range, the default value will be used.
long-running-priority	An integer that specifies the long-running daemon thread's priority. If specified, all long-running threads will be affected.	No	Thread.NORM_PRIORITY	1-10 Range between Thread.MIN_PRIORITY and Thread.MAX_PRIORITY. When out of range, the default value will be used.

Partition-Level MSES Template Configuration Elements

This section defines the configuration elements for a partition-level MSES template, which are similar to a partition-level MES template.

Table 20-3 Managed Scheduled Executor Service Configuration Elements

Name	Description	Required	Default Value	Range
name	The name of the MSES. For naming convention rules, see Table 20-2.	Yes	n/a	An arbitrary non-empty string.
dispatch-policy	The name of the Work Manager. For Work Manager usage rules, see Table 20-2.	No	Default Work Manager	n/a
max-concurrent-long-running-requests	Maximum number of concurrent long running tasks.	No	10	[0-65534]. When out of range, the default value is used.
long-running-priority	An integer that specifies the long-running daemon thread's priority. If specified, all long-running threads will be affected.	No	5 Thread.NORM_PRIORITY	1-1 Range between Thread.MIN_PRIORITY and Thread.MAX_PRIORITY. When out of range, the default value is used.

Partition-Level MTF Template Configuration Elements

This section defines the configuration elements for a partition-level MTF template.

Table 20-4 Managed Thread Factory Configuration Elements

Name	Description	Required	Default Value	Range
name	The name of the MTF. For naming convention rules, see Table 20-2.	Yes	n/a	An arbitrary non-empty string.
priority	The priority to assign to the thread. (The higher the number, the higher the priority.)	No	5 Thread.NORM_PRIORITY	1-10 Range between Thread.MIN_PRIORITY and Thread.MAX_PRIORITY. When out of range, the default value is used.
max-concurrent-new-threads	The maximum number of threads created by the MTF and are still executing the run() method of the tasks.	No	10	[0-65534] When out of range, the default value is used.

This section defines the configuration elements for a partition-level MTF.

Table 20-5 Managed Thread Factory Configuration Elements

Name	Description	Required	Default Value	Range
name	The name of the MTF. For naming convention rules, see Table 20-2.	Yes	n/a	An arbitrary non-empty string.
priority	The priority to assign to the thread. (The higher the number, the higher the priority.)	No	5 Thread.NORM_PRIORITY	1-10 Range between Thread.MIN_PRIORITY and Thread.MAX_PRIORITY. When out of range, the default value is used.
max-concurrent-new-threads	The maximum number of threads created by the MTF and are still executing the run() method of the tasks.	No	10	[0-65534] When out of range, the default value is used.

Partition-Level CMO Constraints for Long-Running Threads

Long-running tasks submitted to MES and MSES and the calling of newThread() method of MTF need to create new threads that will not be managed as a part of the self-tuning thread pool. Because an excessive number of running threads can have a negative affect on server performance and stability, configurations are provided to specify the maximum number of running threads that are created by concurrency utilities API.

Setting Limits for Maximum Concurrent Long-Running Requests

The limit of concurrent long-running requests submitted to MES and MSES can be specified in partitions. All levels of configurations are independent and the maximum of the concurrent long-running requests cannot exceed any of them.

Table 20-6 summarizes the limit of concurrent long-running requests with the max-concurrent-long-running-requests element that can be defined in the deployment descriptors.

Table 20-6 Limit of Concurrent Long-Running Requests in Partitions

Scope	Deployment Descriptor	Description	<max-concurrent-long-running-requests> Element Details
Partition	In config.xml: As the sub-element of <domain><partition> for common partition. As the sub-element of <domain> for global runtime.	Limit of concurrent long-running requests specified for that partition in that server.	Optional Range: [0-65534]. When out of range, the default value will be used Default value: 50

When the specified limit is exceeded, the MES or MSES will take following actions for new long-running tasks submitted to them:

• The java.util.concurrent.RejectedExecutionException will be thrown when calling the task submission API.

• If the user registered the task with the ManagedTaskListener, then this listener will not be notified because the submit method failed.

Note that above rule is not applied for the invokeAll() and invokeAny() methods. If any of the tasks submitted by these methods is rejected by the specified limit, the following events will occur:

• The user-registered ManagedTaskListener's taskSubmitted() method will be called.

• The user-registered ManagedTaskListener's taskDone() method will be called and the throwableParam will be javax.enterprise.concurrent.AbortedException.

• Other submitted tasks will not be affected.

• The method will not throw the RejectedExecutionException.

Example 20-1 demonstrates how the value specified for the max-concurrent-long-running-requests element in config.xml can affect the maximum number of long-running requests.

Example 20-1 Sample Placements of max-concurrent-long-running-requests in config.xml

<domain>
    <server>
        <name>myserver</server>
        <max-concurrent-long-running-requests>50</max-concurrent-long-running-requests> (place 1)
    </server>
    <max-concurrent-long-running-requests>10</max-concurrent-long-running-requests> (place 2)
    <partition>
        <name>mypartition</name>
    <max-concurrent-long-running-requests>5</max-concurrent-long-running-requests> (place 3)

    </partition>
    <server-template>
        <name>mytemplate</name>
        <max-concurrent-long-running-requests>50</max-concurrent-long-running-requests> (place 4)
    </server-template>
</domain>

• place 1—Affects the MES and MSES defined in the server instance myserver. All the MES and MSES running in that server instance can only create a maximum of 50 long-running-requests in total.

• place 2—Only affects MES and MSES defined in the domain. It does not affect partition-level MES and MSES. All the MES and MSES running in the domain can create a maximum of 10 long-running-requests in total.

• place 3—Only affects MES & MSES defined in mypartition. All the MES & MSES running in partition mypartition can create maximally 5 long-running-requests in total.

• place 4—Affects MES & MSES defined in the server instances that apply to the template mytemplate. All the MES and MSES running in that server instance can only create a maximum of 50 long-running-requests in total.

Example 20-2 demonstrates how the value specified for the max-concurrent-long-running-requests element in the config.xml can affect the maximum number of long-running requests.

Example 20-2 Sample Configurations of max-concurrent-long-running-requests

server1(100)
    |---partition1(50)
         |---application1
              |---managed-scheduled-executor-service1(not specified)
              |---module1
                   |---managed-executor-service1(20)
                   |---managed-scheduled-executor-service2(not specified)
        |---application2
    |---partition2(70)

In the following cases, none of the limits are exceeded and the above actions will not be taken:

• Assume 120 long-running tasks were submitted to managed-executor-service1, 115 of them were finished, 5 of them are being executed, if one more long-running task is submitted to managed-executor-service1, it will be executed because no limit is exceeded.

In the following cases, one of the limits is exceeded and the above actions will be taken:

• Assume 10 long-running tasks are being executed by managed-scheduled-executor-service1, if one more long-running task is submitted to managed-scheduled-executor-service1, then the limit of managed-scheduled-executor-service1 is exceeded.

• Assume 10 long-running tasks are being executed by application1, 40 are being executed by application2, if one more long-running task is submitted to application1 or application2, then the limit of partition1 is exceeded.

• Assume 10 long-running tasks are being executed by application1, 30 are being executed by application2, 60 are being executed by partition2, if one more long-running task is submitted to application1, or application2, or partition2, then the limit of server1 is exceeded.

Setting Limits for Maximum Concurrent New Threads

The limit of concurrent new running threads created by calling the newThread() method of the MTF can be specified in a managed object, domain, and server level. All levels of configurations are independent and the maximum of the concurrent new running threads cannot exceed any of them.

Note that the meaning of running thread is a thread that has been created by the MTF and which has not finished its run() method.

Table 20-7 summarizes the limit of concurrent new running threads with an element <max-concurrent-new-threads> that can be defined in the deployment descriptors.

Table 20-7 Limit of Concurrent New Running Threads

Scope	Deployment Descriptor	Description	<max-concurrent-long-running-requests> Element Details
Partition	in config.xml: As the sub-element of <domain><partition> for common partition. As the sub-element of <domain> for global runtime.	Limit of concurrent new running threads specified for that partition in that server.	Optional Range: [0-65534], when out of range default value will be used Default value: 50

When the specified limit is exceeded, calls to the newThread() method of the MTF will return null to be consistent with the ThreadFactory.newThread Javadoc.

To see a sample snippet of using max-concurrent-new-threads, refer to Sample Configurations of max-concurrent-long-running-requests.

Configuring Partition CMO Templates: Main Steps

You can define global CMOs as templates in the partition's configuration by using the WLS Administration Console and configuration MBeans. CMO templates can be assigned to any application, or application component in the partition.

You can define three types of CMO templates in a partition:

• Managed Executor Service Template

• Managed Scheduled Executor Service Template

• Managed Thread Factory Template

For example, if you define a managed-executor-service-template, a unique MES instance is created for each application deployed in the partition.

Using the WLS Administration Console to Configure a Partition-Scoped CMO Template

CMO templates can be configured and scoped to a partition using the WLS Administration Console.

1. In the Domain Structure tree, expand Environment and click Concurrent Templates.

2. Click New and choose one of the following template options:

   • Managed Executor Service Template

   • Managed Scheduled Executor Service Template

   • Managed Thread Factory Template

3. On the Create New Template page, enter the template properties as required. The properties vary depending on which type of concurrent template you are creating.

   • See Partition-Level MES Template Configuration Elements.

   • See Partition-Level MSES Template Configuration Elements

   • See Partition-Level MTF Template Configuration Elements.

4. Click Next.

5. Select the partition that you want to target the concurrent template to.

   Only applications that have been deployed to the selected partition can use this concurrent template.

6. Click Finish. The Summary of Concurrent Templates page displays and the new partition-scoped concurrent template is listed.

7. Repeat these steps to create other concurrent templates as necessary.

For more detailed information about configuring CMO templates for a domain and server scope, see "Global CMO Templates" in Administering Server Environments for Oracle WebLogic Server.

Using MBeans to Configure CMO Templates

CMO templates can be configured using the following configuration MBeans under the PartitionMBean.

• ManagedExecutorServiceTemplateMBean

• ManagedScheduledExecutorServiceTemplateMBean

• ManagedThreadFactoryTemplateMBean

For more information, see the "PartitionMBean" section in the MBean Reference for Oracle WebLogic Server.

Configuring Partition Concurrent Constraints: Main Steps

Constraints can also be defined for a partition scope using the WLS Administration Console and configuration MBeans.

• Using the WLS Administration Console to Configure Concurrent Constraints for a Partition

• Using MBeans to Configure Concurrent Constraints

Using the WLS Administration Console to Configure Concurrent Constraints for a Partition

Concurrent constraints can be configured per partition using the WLS Administration Console.

1. In the Domain Structure tree, click Domain Partitions.

2. In the Summary of Domain Partitions table, select the partition you want to configure.

3. In the Settings for partition-name page, open the Configuration > Concurrency page for the partition

4. Specify a value for any or all of the concurrent constraint options:

   • Max Concurrent Long Running Requests—The maximum number of concurrent long-running requests that can be submitted to all of the Managed Executor Services or Managed Scheduled Executor Services in the partition scope.

     See Setting Limits for Maximum Concurrent Long-Running Requests.

   • Max Concurrent New Threads—The maximum number of concurrent new threads that can be created by all of the Managed Thread Factories in the partition scope.

     See Setting Limits for Maximum Concurrent New Threads.

5. Click Save.

Using MBeans to Configure Concurrent Constraints

Concurrent constraints can be configured per partition using the following methods under the PartitionMBean:

• maxConcurrentLongRunningRequests()—The maximum number of concurrent long-running requests that can be submitted to all of the Managed Executor Services or Managed Scheduled Executor Services in the partition scope.

  See Setting Limits for Maximum Concurrent Long-Running Requests.

• maxConcurrentNewThreads()—The maximum number of concurrent new threads that can be created by all of the Managed Thread Factories in the partition scope.

  See Setting Limits for Maximum Concurrent New Threads.

For more information about using WebLogic Server MBeans, see "Accessing WebLogic Server MBeans with JMX" in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.

Configuring Partition Concurrent Managed Objects: Related Tasks and Links

See the following sections for additional information:

• "Configuring Concurrent Managed Objects" in Administering Server Environments for Oracle WebLogic Server.

• For more information about CMO-related configuration and runtime MBeans, see the ManagedExecutorServiceTemplateMBean, ManagedScheduledExecutorServiceTemplateMBean, ManagedThreadFactoryTemplateMBean, and the PartitionMBean in the MBean Reference for Oracle WebLogic Server.

• For more information about using WLST commands, see "WebLogic Server WLST Online and Offline Command Reference" in the WLST Command Reference for WebLogic Server.

• "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server

• "Concurrency Utilities for Java EE" in The Java EE 7 Tutorial

• The Java Specification Request 236: Concurrency Utilities for Java EE 1.0 (http://jcp.org/en/jsr/detail?id=236).