CLDC 8 (JSR360 Final Release)

Package java.lang.ref

Provides reference-object classes, which support a limited degree of interaction with the garbage collector.

See: Description

Package java.lang.ref Description

Provides reference-object classes, which support a limited degree of interaction with the garbage collector. A program may use a reference object to maintain a reference to some other object in such a way that the latter object may still be reclaimed by the collector. A program may also arrange to be notified some time after the collector has determined that the reachability of a given object has changed.

Package Specification

A reference object encapsulates a reference to some other object so that the reference itself may be examined and manipulated like any other object. Whereas Java SE supports three different types of reference types, CLDC supports weak references as the only reference type. Weak references are useful for implementing canonicalizing mappings that do not prevent their keys (or values) from being reclaimed.

An instance of a weak reference encapsulates a single reference to a particular object, called the referent. Every reference object provides methods for getting and clearing the reference. Aside from the clearing operation reference objects are otherwise immutable, so no set operation is provided. A program may further subclass these subclasses, adding whatever fields and methods are required for its purposes, or it may use these subclasses without change.

Notification

A program may request to be notified of changes in an object's reachability by registering an appropriate reference object with a reference queue at the time the reference object is created. Some time after the garbage collector determines that the reachability of the referent has changed to the value corresponding to the type of the reference, it will add the reference to the associated queue. At this point, the reference is considered to be enqueued. The program may remove references from a queue either by polling or by blocking until a reference becomes available. Reference queues are implemented by the ReferenceQueue class.

The relationship between a registered reference object and its queue is one-sided. That is, a queue does not keep track of the references that are registered with it. If a registered reference becomes unreachable itself, then it will never be enqueued. It is the responsibility of the program using reference objects to ensure that the objects remain reachable for as long as the program is interested in their referents.

While some programs will choose to dedicate a thread to removing reference objects from one or more queues and processing them, this is by no means necessary. A tactic that often works well is to examine a reference queue in the course of performing some other fairly-frequent action. For example, a hashtable that uses weak references to implement weak keys could poll its reference queue each time the table is accessed.

Automatically-cleared references

Weak references are automatically cleared by the collector before being added to the queues with which they are registered, if any. Therefore weak references need not be registered with a queue in order to be useful.

Reachability

Going from strongest to weakest, the different levels of reachability reflect the life cycle of an object. They are operationally defined as follows:
Since:
1.2
CLDC 8 (JSR360 Final Release)
April 15, 2014

Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.