Find JSRs
Submit this Search

Ad Banner

JSRs: Java Specification Requests
JSR 284: Resource Consumption Management API

Original Java Specification Request (JSR)

Identification | Request | Contributions

Section 1. Identification

Submitting Member: Sun Microsystems

Name of Contact Person: Grzegorz Czajkowski

E-Mail Address:

Telephone Number: +1-650-786-0957

Fax Number: +1-650-786-2141

Specification Lead: Grzegorz Czajkowski

E-Mail Address:

Telephone Number: +1-650-786-0957

Fax Number: +1-650-786-2141

Initial Expert Group Membership:

Doug Lea
Miles Sabin
Sun Microsystems

Supporting this JSR:

Doug Lea

Section 2: Request

2.1 Please describe the proposed Specification:

Software systems in many circumstances need awareness of their resource usage. Meeting performance requirements often requires the ability to manage consumption of resources provided by the environment. Resource management is traditionally handled by operating systems, but the growing need to use the Java platform in the systems programming domain adds increased pressure to equip it with resource management capabilities at a level of abstraction that fits gracefully with the language.

Preventing denial of service attacks, providing load balancing, and monitoring the usage of a given resource are all difficult to do in the current version of the Java platform. In general, these and other features cannot be provided without going beyond the Java language proper, through mechanisms such as native code or shell scripts that ask the OS to handle matters related to resource management. The lack of a standard, programmatic way to partition resources available to virtual machine(s) among Java applications has led to a number of ad-hoc solutions.

The Resource Management API for J2SE Applications should address the above and be characterized by the following:

  • Wide applicability. The interface should be applicable to a variety of resource management scenarios and allow the expression of numerous resource management policies.
  • Flexibility. The interface should enable managing a broad range of resource types. For example, for some applications resources such as the CPU time and heap memory matter most, while other applications may find it more meaningful to manage higher-level resources, such as the number of open JDBC connections or the number of transactions per second, and the API should accommodate this entire spectrum.
  • Extensibility. The resource management interface should support the addition of new resources in a uniform manner.
  • Completeness of abstraction. The interface should hide from applications whether a given resource is managed by the underlying operating system (OS), by the Java Virtual Machine (JVM), by a core library, or by trusted middleware code. As a consequence, it should be possible to write resource policies for resources exhibiting common behavior abstractly, without regard for how those resources are implemented.
  • Lack of specialization. The interface should not require an implementation to depend on specialized support from an OS or from hardware, although implementations should be free to take advantage of such support if available.
  • Ease of exposing resources through the API in a low-overhead fashion.
  • Diagnosability. It should be straightforward to determine cause(s) of an application running into resource constraints.
  • Simplicity of use. While excercising the full power of the API may require expert knowledge, it should be simple to perform common resource management tasks.
Concrete examples are given below to demonstrate the need for and usefulness of the proposed specification. None of them can be realized by current APIs.

  • An application management environment needs to confine each application to at most 32MB of heap memory and would like to detect applications that use more than 90% of CPU time in order to terminate them. Moreover, a minimal quantity of heap and CPU should be reserved for each application to ensure a basic level of service.
  • An application would like to be notified when its usage of network resources exceedes 10MB/s, so that it can start compressing data before sending it, but only if the total CPU time consumption is below 50% (effectively this policy is about trading one resource for another).
  • A service provider would like to understand (for profiling or billing purposes) how much of each resource of interest (memory, CPU time, SQL statements submitted over JDBC connections, etc.) each user is consuming.
  • A service provider would like to distinguish between users with "platinum", "gold", and "silver" contracts and offer them different QoS level. This translates into the need to partition resources according to the contractually agreed upon QoS.
The API should enable resource management policies to be programmed. In particular, such a policy should have the ability to define when an application may gain access to, or consume, a unit of a specific resource. It should be possible to bind computations dynamically to policies. Programs should be able to reserve resources in advance and thus ensure predictable execution. Applications should be able to install resource monitoring code so that proactive programs can observe resource availability and take any actions required to ensure performance and availability or to ward off denial of service attacks. Existing applications should run without modification, even if the Java platform classes or the Java runtime environment they depend depend on exploits the resource management framework. The interface should not impact in any way how actual resource providers (schedulers, automatic memory subsystems, etc.) should be written - it should be possible to make these providers become "RM-enabled" by inserting calls to appropriate API methods to convey information about resource consumption attempts. The effort required to retrofit existing resource managers should thus be minimized.

The specification will build upon the abstraction of an isolate, as defined in JSR 121. An isolate is an encapsulated Java program or application component that shares no state with other isolates. Isolates are a convenient abstraction on which to develop resource management: isolation allows unambiguous resource usage accounting and clean reclamation upon program termination. The expert group will also look at enabling the API to operate on platforms that do not support the Isolate API. In particular, a single JVM could be viewed as a special case of a single isolate.

In addition to defining an API, which will be a framework through which resources can be uniformly exposed to client programs as entities subject to management, the outcome of this JSR will include a non-empty set of resources deemed core and required by compatible implementations.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

Java SE

2.3 The Executive Committees would like to ensure JSR submitters think about how their proposed technology relates to all of the Java platform editions. Please provide details here for which platform editions are being targeted by this JSR, and how this JSR has considered the relationship with the other platform editions.

This JSR is submitted to the Java SE EC. It is likely that this functionality will be used by Java EE as well.

Should this JSR be voted on by both Executive Committees?


2.5 What need of the Java community will be addressed by the proposed specification?

Inability to manage computational resources, to impose constraints on Java applications, to reserve quantities of resources so that Java applications can have predictable performance, and to provide means of querying about resource availability.

2.6 Why isn't this need met by existing specifications?

The existing specifications haven't addressed this problem yet. Several specifications allow for some for of monitoring of a specific resource, but these are isolated cases. There is a lack of a uniform and comprehensive approach.

We duly note the existence and usefulness of the JSR 174. However, its scope - monitoring the health of the JVM as well as exposing certain JVM-wide statistics - is different from the goals stated above. For example, JSR 174 cannot asist in reserving resources, constraining their usage, and partitioning their availability among Java applications.

Another related technology is the JMX API (JSR 3, JSR 160, JSR 255). We view the proposed specification as complementary to the JMX API, as it provides missing controls and functionality that can be inserted into the framework defined by the JMX API.

The OSS technology JSRs (in particular 90, 210) are also related as they may be clients of the low-level functionality and information provided by this JSR.

The Java Platform Profiling Architecture (JSR 163) allows for gathering information about various low-level events (object construction, method invocation, etc). The API, expressed in C/C++, is meant to be a building block for tools (profilers, debuggers) and does not provide the functionality requested in this proposal and exposes limited information only about a small, fixed number of resources. However, simple proof-of-concept implementations of some resources could use JSR 163 to gather usage information.

Finally, there is the recently started JSR 278 (Resource Management Framework for J2ME). Its scope, despite the name, is much narrower than what's proposed above. In essence 278 aims at determining which applications (actually their intent is to encapsulate each application within an isolate) excessively use certain types of resources and to reclaim these resources upon (forced) termination of certain apps. In particular, there is no provision for application-level (self-) monitoring, expressing notifications, constraints, and reservations.

2.7 Please give a short description of the underlying technology or technologies:

Implementation details of exposing a resource through the API will depend on the resource's implementation. For some resources modifying core libraries will suffice, for others it may be necessary to modify the virtual machine code. The rest of the API (the mechanics of setting constraints, reservations, notifications, etc) can be realized entirely in the Java programming language.

2.8 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)


2.9 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?


2.10 Are there any security issues that cannot be addressed by the current security model?


2.11 Are there any internationalization or localization issues?


2.12 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?


2.13 Please describe the anticipated schedule for the development of this specification.

October 2005: EG formed.
October 2006: Specification complete.
December 2006: TCK, RI ready.

2.14 Please describe the anticipated working model for the Expert Group working on developing this specification.

A combination of e-mail and weekly phone meetings.

2.15 It is important to the success of the community and each JSR that the work of the Expert Group be handled in a manner which provides the community and the public with insight into the work the Expert Group is doing, and the decisions that the Expert Group has made. The Executive Committees would like to ensure Spec Leads understand the value of this transparency and ask that each JSR have an operating plan in place for how their JSR will address the involvement of the community and the public. Please provide your plan here, and refer to the Spec Lead Guide for a more detailed description and a set of example questions you may wish to answer in your plan.

Updates will be sent to the interest list set up for this JSR. The list will be archived and the members will be able to post questions to the EG.

2.16 Please describe how the RI and TCK will de delivered, i.e. as part of a profile or platform edition, or stand-alone, or both. Include version information for the profile or platform in your answer.

Both the RI and the TCK will be delivered stand-alone.

2.17 Please state the rationale if previous versions are available stand-alone and you are now proposing in 2.13 to only deliver RI and TCK as part of a profile or platform edition (See sections 1.1.5 and 1.1.6 of the JCP 2 document).


2.18 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

The RI for this JSR will be made available in binary form at no charge. The TCK for this JSR will be made available at no charge to J2SE TCK licensees and at $50K to others. In addition, qualified individuals and not for profit organizations will receive access to the TCK at no charge.

Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

Several research projects, closely related to the objectives of this JSR, exist. Reports on three of them are listed below; others can be found by following references in these papers.

3.2 Explanation of how these items might be used as a starting point for the work.

The RM API, described in the Sun Microsystems Laboratories TR 2003-124, will be a starting point for the EG work.