19 Configuring Partition Concurrent Managed Objects

This chapter describes how to configure partition-level concurrent managed object (CMO) templates and concurrent constraints in Oracle WebLogic Server Multitenant (MT). You can use the Oracle 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

The concurrency utilities for Java EE 1.0, Java Specification Request (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 discusses CMO templates only 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 19-1.

Table 19-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 the Work Manager is shutting down, all the unfinished tasks 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 effects 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.

NA

NA

NA

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 effects 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 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 WebLogic Server Administration Console and configuration MBeans.

Note:

This document discusses global CMO templates only 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 WebLogic Server 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

Table 19-2 defines the configuration elements for a partition-level MES template.

Table 19-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.

  • A 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

NA

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 exist, use the partition-level default Work Manager.

No

Default Work Manager

NA

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, then 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

Table 19-3 defines the configuration elements for a partition-level MSES template, which are similar to a partition-level MES template.

Table 19-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 19-2.

Yes

NA

An arbitrary non-empty string.

dispatch-policy

The name of the Work Manager.

For Work Manager usage rules, see Table 19-2.

No

Default Work Manager

NA

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, then 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

Table 19-4 defines the configuration elements for a partition-level MTF template.

Table 19-4 Managed Thread Factory Configuration Elements

Name Description Required Default Value Range

name

The name of the MTF.

For naming convention rules, see Table 19-2.

Yes

NA

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 that are still executing the run() method of the tasks.

No

10

[0-65534]

When out of range, the default value is used.

Table 19-5 defines the configuration elements for a partition-level MTF.

Table 19-5 Managed Thread Factory Configuration Elements

Name Description Required Default Value Range

name

The name of the MTF.

For naming convention rules, see Table 19-2.

Yes

NA

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 that 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 effect 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 19-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 19-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 subelement of <domain><partition> for common partition. As the subelement 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 takes the following actions for new long-running tasks submitted to them:

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

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

Note that the preceding 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, then the following events occur:

  • The user-registered managed task listener's taskSubmitted() method is called.

  • The user-registered managed task listener's taskDone() method is called and the throwableParam is javax.enterprise.concurrent.AbortedException.

  • Other submitted tasks are not affected.

  • The method does not throw the exception RejectedExecutionException.

The following example demonstrates how the value specified for the max-concurrent-long-running-requests element in the config.xml file can affect the maximum number of long-running requests.

<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 create only 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 and MSES defined in mypartition. All the MES and MSES running in partition mypartition can create maximally 5 long-running requests in total.

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

The following example demonstrates how the value specified for the max-concurrent-long-running-requests element in the config.xml file can affect the maximum number of long-running requests.

In the following case, none of the limits is exceeded and the prior actions are not 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, then it is executed because no limit is exceeded.

In the following cases, one of the limits is exceeded and the prior actions are 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, and 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, and 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.

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)

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 that has not finished its run() method.

Table 19-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 19-7 Limit of Concurrent New Running Threads

Scope Deployment Descriptor Description <max-concurrent-long-running-requests> Element Details

Partition

In config.xml:

As the subelement of <domain><partition> for common partition. As the subelement 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, the default value is 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 of using max-concurrent-new-threads, see Example 19-*.

Configuring Partition CMO Templates: Main Steps

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

Note:

Partitioned domains for multi-tenancy are only available in WebLogic Server Premium Edition. For more information, see LINK TO INTRO TO WEBLOGIC SERVER MT.

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

  • Managed Executor Service

  • Managed Scheduled Executor Service

  • Managed Thread Factory

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 Administration Console to Configure a Partition-Scoped CMO Template

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

  1. In the Domain Structure tree, expand Environment and click Concurrent Templates.
  2. Click New and select 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.
  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 PartitionMBean:

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 WebLogic Server Administration Console and configuration MBeans. For more information, see:

Using the Administration Console to Configure Concurrent Constraints for a Partition

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

  1. In the Domain Structure tree, click Domain Partitions.
  2. In the Summary of Domain Partitions table, select the partition that 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:
  5. Click Save.

Using MBeans to Configure Concurrent Constraints

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

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.

Monitoring Partition-level CMO Templates

Concurrent constraints can be queried using these administrative tools:

Using the Administration Console to Monitor CMO Templates

CMO templates can be monitored using the Administration Console.

To monitor the threads created by CMOs in a partition:

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

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

  3. In the Settings for partition-name page, select the Monitoring > Concurrent Templates tab.

    The table provides configuration information for CMO templates that have been targeted to the partition.

Using MBeans to Monitor CMO Templates

A a partition's CMO templates can be monitored using the ConcurrentManagedObjectsRuntimeMBean, which can be accessed from the following MBean attribute:

  • PartitionRuntimeMBean.ConcurrentManagedObjectsRuntime – Provides configuration information for CMO templates that have been targeted to the partition.

See the ConcurrentManagedObjectsRuntimeMBean in the MBean Reference for Oracle WebLogic Server

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 for additional information: