Top Description Fields Constructors Methods
org.osgi.util.tracker

pack-priv abstract Class AbstractTracked<S, T, R>

extends Object
Class Inheritance
Known Direct Subclasses
org.osgi.util.tracker.BundleTracker.Tracked, org.osgi.util.tracker.ServiceTracker.Tracked
Type Parameters
<S>
The tracked item. It is the key.
<T>
The value mapped to the tracked item.
<R>
The reason the tracked item is being tracked or untracked.
Imports
java.util.ArrayList, .HashMap, .LinkedList, .List, .Map
Abstract class to track items. If a Tracker is reused (closed then reopened), then a new AbstractTracked object is used. This class acts a map of tracked item -> customized object. Subclasses of this class will act as the listener object for the tracker. This class is used to synchronize access to the tracked items. This is not a public class. It is only for use by the implementation of the Tracker class.
Author
$Id: 687685a4755f24def9382a8132fb0740323669fe $
Since
1.4

Field Summary

Modifier and TypeField and Description
private final List<S>
adding

List of items in the process of being added.

pack-priv volatile boolean
closed

true if the tracked object is closed.

pack-priv static final boolean
DEBUG

private final LinkedList<S>
initial

Initial list of items for the tracker.

private final Map<S, T>
tracked

Map of tracked items to customized objects.

private int
trackingCount

Modification count.

Constructor Summary

AccessConstructor and Description
pack-priv
AbstractTracked()

AbstractTracked constructor.

Method Summary

Modifier and TypeMethod and Description
pack-priv void
close()

Called by the owning Tracker object when it is closed.

pack-priv <
Type of Map to hold the tracked items and associated values.
M extends Map<? super S, ? super T>> M

Returns:

The specified map.
copyEntries(final M
The map into which to copy the tracked items and associated values. This map must not be a user provided map so that user code is not executed while synchronized on this.
map)

Copy the tracked items and associated values into the specified map.

pack-priv S[]

Returns:

The specified list if it is large enough to hold the tracked items or a new array large enough to hold the tracked items.
copyKeys(final S[]
An array to contain the tracked items.
list)

Copy the tracked items into an array.

pack-priv abstract T

Returns:

Customized object for the tracked item or null if the item is not to be tracked.
customizerAdding(final S
Item to be tracked.
item, final R
Action related object.
related)

Call the specific customizer adding method.

pack-priv abstract void
customizerModified(final S
Tracked item.
item, final R
Action related object.
related, final T
Customized object for the tracked item.
object)

Call the specific customizer modified method.

pack-priv abstract void
customizerRemoved(final S
Tracked item.
item, final R
Action related object.
related, final T
Customized object for the tracked item.
object)

Call the specific customizer removed method.

pack-priv T

Returns:

The customized object for the specified item.
getCustomizedObject(final S
The item to lookup in the map
item)

Return the customized object for the specified item

pack-priv int

Returns:

The tracking count for this object.
getTrackingCount()

Returns the tracking count for this ServiceTracker object.

pack-priv boolean

Returns:

Whether the tracker is empty.
isEmpty()

Returns if the tracker is empty.

pack-priv void
modified()

Increment the modification count.

pack-priv void
setInitial(S[]
The initial list of items to be tracked. null entries in the list are ignored.
list)

Set initial list of items into tracker before events begin to be received.

pack-priv int

Returns:

The number of tracked items.
size()

Returns the number of tracked items.

pack-priv void
track(final S
Item to be tracked.
item, final R
Action related object.
related)

Begin to track an item.

private void
trackAdding(final S
Item to be tracked.
item, final R
Action related object.
related)

Common logic to add an item to the tracker used by track and trackInitial.

pack-priv void
trackInitial()

Track the initial list of items.

pack-priv void
untrack(final S
Item to be untracked.
item, final R
Action related object.
related)

Discontinue tracking the item.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

addingback to summary
private final List<S> adding

List of items in the process of being added. This is used to deal with nesting of events. Since events may be synchronously delivered, events can be nested. For example, when processing the adding of a service and the customizer causes the service to be unregistered, notification to the nested call to untrack that the service was unregistered can be made to the track method. Since the ArrayList implementation is not synchronized, all access to this list must be protected by the same synchronized object for thread-safety.

closedback to summary
pack-priv volatile boolean closed

true if the tracked object is closed. This field is volatile because it is set by one thread and read by another.

DEBUGback to summary
pack-priv static final boolean DEBUG
initialback to summary
private final LinkedList<S> initial

Initial list of items for the tracker. This is used to correctly process the initial items which could be modified before they are tracked. This is necessary since the initial set of tracked items are not "announced" by events and therefore the event which makes the item untracked could be delivered before we track the item. An item must not be in both the initial and adding lists at the same time. An item must be moved from the initial list to the adding list "atomically" before we begin tracking it. Since the LinkedList implementation is not synchronized, all access to this list must be protected by the same synchronized object for thread-safety.

trackedback to summary
private final Map<S, T> tracked

Map of tracked items to customized objects.

trackingCountback to summary
private int trackingCount

Modification count. This field is initialized to zero and incremented by modified.

Constructor Detail

AbstractTrackedback to summary
pack-priv AbstractTracked()

AbstractTracked constructor.

Method Detail

closeback to summary
pack-priv void close()

Called by the owning Tracker object when it is closed.

copyEntriesback to summary
pack-priv <M extends Map<? super S, ? super T>> M copyEntries(final M map)

Copy the tracked items and associated values into the specified map.

Parameters
<M>
Type of Map to hold the tracked items and associated values.
map:M

The map into which to copy the tracked items and associated values. This map must not be a user provided map so that user code is not executed while synchronized on this.

Returns:M

The specified map.

Since
1.5
copyKeysback to summary
pack-priv S[] copyKeys(final S[] list)

Copy the tracked items into an array.

Parameters
list:S[]

An array to contain the tracked items.

Returns:S[]

The specified list if it is large enough to hold the tracked items or a new array large enough to hold the tracked items.

customizerAddingback to summary
pack-priv abstract T customizerAdding(final S item, final R related)

Call the specific customizer adding method. This method must not be called while synchronized on this object.

Parameters
item:S

Item to be tracked.

related:R

Action related object.

Returns:T

Customized object for the tracked item or null if the item is not to be tracked.

customizerModifiedback to summary
pack-priv abstract void customizerModified(final S item, final R related, final T object)

Call the specific customizer modified method. This method must not be called while synchronized on this object.

Parameters
item:S

Tracked item.

related:R

Action related object.

object:T

Customized object for the tracked item.

customizerRemovedback to summary
pack-priv abstract void customizerRemoved(final S item, final R related, final T object)

Call the specific customizer removed method. This method must not be called while synchronized on this object.

Parameters
item:S

Tracked item.

related:R

Action related object.

object:T

Customized object for the tracked item.

getCustomizedObjectback to summary
pack-priv T getCustomizedObject(final S item)

Return the customized object for the specified item

Parameters
item:S

The item to lookup in the map

Returns:T

The customized object for the specified item.

getTrackingCountback to summary
pack-priv int getTrackingCount()

Returns the tracking count for this ServiceTracker object. The tracking count is initialized to 0 when this object is opened. Every time an item is added, modified or removed from this object the tracking count is incremented.

Returns:int

The tracking count for this object.

isEmptyback to summary
pack-priv boolean isEmpty()

Returns if the tracker is empty.

Returns:boolean

Whether the tracker is empty.

Since
1.5
modifiedback to summary
pack-priv void modified()

Increment the modification count. If this method is overridden, the overriding method MUST call this method to increment the tracking count.

setInitialback to summary
pack-priv void setInitial(S[] list)

Set initial list of items into tracker before events begin to be received. This method must be called from Tracker's open method while synchronized on this object in the same synchronized block as the add listener call.

Parameters
list:S[]

The initial list of items to be tracked. null entries in the list are ignored.

sizeback to summary
pack-priv int size()

Returns the number of tracked items.

Returns:int

The number of tracked items.

trackback to summary
pack-priv void track(final S item, final R related)

Begin to track an item.

Parameters
item:S

Item to be tracked.

related:R

Action related object.

trackAddingback to summary
private void trackAdding(final S item, final R related)

Common logic to add an item to the tracker used by track and trackInitial. The specified item must have been placed in the adding list before calling this method.

Parameters
item:S

Item to be tracked.

related:R

Action related object.

trackInitialback to summary
pack-priv void trackInitial()

Track the initial list of items. This is called after events can begin to be received. This method must be called from Tracker's open method while not synchronized on this object after the add listener call.

untrackback to summary
pack-priv void untrack(final S item, final R related)

Discontinue tracking the item.

Parameters
item:S

Item to be untracked.

related:R

Action related object.