org.jboss.cache
Interface Region

All Superinterfaces:

Cloneable, Comparable<Region>

All Known Implementing Classes:

RegionImpl

public interface Region
extends Comparable<Region>, Cloneable

Defines characteristics such as class loading and eviction of Nodes belonging to a Region in a Cache. A Region is described by an Fqn relative to the root of the cache. All nodes and child nodes of this Fqn belong to this region.

If a region is to be recognised as an eviction region (region of type Region.Type.EVICTION then it must have an EvictionRegionConfig set using setEvictionRegionConfig(org.jboss.cache.config.EvictionRegionConfig).

Similarly, to be recognised as a marshalling region (region of type Region.Type.MARSHALLING then it must have a ClassLoader registered using registerContextClassLoader(ClassLoader).

Note that a single region can be both an eviction and marshalling region at the same time.

Since:

2.0.0

Author:

Manik Surtani (manik AT jboss DOT org)

See Also:

RegionManager

Nested Class Summary

static class	Region.Status Region status
static class	Region.Type Types of regions.

Method Summary

void	activate() Activates this region for replication.
void	activateIfEmpty() Activates this region for replication, but if the Fqn that represents this region already exists and either contains data or children, no state transfers take place.
Region	clone() Deprecated.
Region	copy(Fqn newRoot) copies the region - including eviction queue events - to a new Region instance, attached to a new Fqn root.
void	deactivate() Deactivates this region from being replicated.
Configuration	getCacheConfiguration()
ClassLoader	getClassLoader() Returns the configured ClassLoader for this region.
EvictionPolicy	getEvictionPolicy() Deprecated.
EvictionPolicyConfig	getEvictionPolicyConfig() Deprecated.
EvictionRegionConfig	getEvictionRegionConfig()
Fqn	getFqn() Returns the Fqn of this region.
Region.Status	getStatus()
boolean	isActive() Returns true if this region has been activated.
void	markNodeCurrentlyInUse(Fqn fqn, long timeout) Marks a Node as currently in use, by adding an event to the eviction queue.
int	nodeEventQueueSize() Deprecated.
void	processEvictionQueues() Processes the eviction queues (primary and recycle queues) associated with this region.
void	putNodeEvent(EvictedEventNode event) Deprecated.
void	registerContextClassLoader(ClassLoader classLoader) Registers a specific ClassLoader for this region, overridding the default cache class loader.
EvictionEvent	registerEvictionEvent(Fqn fqn, EvictionEvent.Type eventType) An overloaded version of registerEvictionEvent(Fqn, org.jboss.cache.eviction.EvictionEvent.Type, int) which uses a default elementDifference value.
EvictionEvent	registerEvictionEvent(Fqn fqn, EvictionEvent.Type eventType, int elementDifference) Registers an eviction event on the region's eviction event queue for later processing by processEvictionQueues().
void	resetEvictionQueues() Clears the node event queue used for processing eviction.
void	setActive(boolean b) Sets this region as active - this only marks a flag and does not actually activates or deactivates this region.
void	setEvictionPolicy(EvictionPolicyConfig evictionPolicyConfig) Deprecated.
void	setEvictionRegionConfig(EvictionRegionConfig evictionRegionConfig) Configures this region for eviction.
void	setStatus(Region.Status status) A mechanism to set status of a region, more fine grained control than just setActive();
EvictedEventNode	takeLastEventNode() Deprecated.
void	unmarkNodeCurrentlyInUse(Fqn fqn) Adds an event to the eviction queue indicating that a node is no longer in use.
void	unregisterContextClassLoader() Unregisters a registered ClassLoaders for this region.

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

registerContextClassLoader

void registerContextClassLoader(ClassLoader classLoader)

Registers a specific ClassLoader for this region, overridding the default cache class loader.

Parameters:

classLoader - specific class loader

getCacheConfiguration

Configuration getCacheConfiguration()

Returns:

the cache-wide configuration

Since:

2.1.0

unregisterContextClassLoader

void unregisterContextClassLoader()

Unregisters a registered ClassLoaders for this region.

activate

void activate()
              throws RegionNotEmptyException

Activates this region for replication. By default, the entire cache is activated for replication at start-up.

Throws:

RegionNotEmptyException - if the Fqn that represents this region already exists and contains data or children.

activateIfEmpty

void activateIfEmpty()

Activates this region for replication, but if the Fqn that represents this region already exists and either contains data or children, no state transfers take place. The region is simply marked as active in this case.

deactivate

void deactivate()

Deactivates this region from being replicated.

setActive

void setActive(boolean b)

Sets this region as active - this only marks a flag and does not actually activates or deactivates this region. Use activate() and deactivate() for the full process.

Parameters:

b -

isActive

boolean isActive()

Returns true if this region has been activated.

Returns:

true if this region has been activated.

getClassLoader

ClassLoader getClassLoader()

Returns the configured ClassLoader for this region.

Returns:

a ClassLoader

processEvictionQueues

void processEvictionQueues()

Processes the eviction queues (primary and recycle queues) associated with this region. A no-op if this is not an eviction region.

Since:

3.0

resetEvictionQueues

void resetEvictionQueues()

Clears the node event queue used for processing eviction.

setEvictionRegionConfig

void setEvictionRegionConfig(EvictionRegionConfig evictionRegionConfig)

Configures this region for eviction.

Parameters:

evictionRegionConfig - configuration to set

getEvictionRegionConfig

EvictionRegionConfig getEvictionRegionConfig()

Returns:

the eviction region config, if any, set on the current region.

registerEvictionEvent

EvictionEvent registerEvictionEvent(Fqn fqn,
                                    EvictionEvent.Type eventType,
                                    int elementDifference)

Registers an eviction event on the region's eviction event queue for later processing by processEvictionQueues().

Parameters:

fqn - passed in to the constructor of EvictionEvent

eventType - passed in to the constructor of EvictionEvent

elementDifference - passed in to the constructor of EvictionEvent

Returns:

an EvictedEventNode that has been created for this queue

registerEvictionEvent

EvictionEvent registerEvictionEvent(Fqn fqn,
                                    EvictionEvent.Type eventType)

An overloaded version of registerEvictionEvent(Fqn, org.jboss.cache.eviction.EvictionEvent.Type, int) which uses a default elementDifference value.

Parameters:

fqn - passed in to the constructor of EvictionEvent

eventType - passed in to the constructor of EvictionEvent

Returns:

an EvictedEventNode that has been created for this queue

markNodeCurrentlyInUse

void markNodeCurrentlyInUse(Fqn fqn,
                            long timeout)

Marks a Node as currently in use, by adding an event to the eviction queue. If there is an EvictionRegionConfig associated with this region, and it respects this event (e.g., LRUAlgorithm does), then the Node will not be evicted until unmarkNodeCurrentlyInUse(Fqn) is invoked.

This mechanism can be used to prevent eviction of data that the application is currently using, in the absence of any locks on the Node where the data is stored.

Parameters:

fqn - Fqn of the node.

See Also:

unmarkNodeCurrentlyInUse(Fqn)

unmarkNodeCurrentlyInUse

void unmarkNodeCurrentlyInUse(Fqn fqn)

Adds an event to the eviction queue indicating that a node is no longer in use.

Parameters:

fqn - Fqn of the node.

See Also:

markNodeCurrentlyInUse(Fqn,long)

getFqn

Fqn getFqn()

Returns the Fqn of this region.

Returns:

the Fqn

setStatus

void setStatus(Region.Status status)

A mechanism to set status of a region, more fine grained control than just setActive();

Parameters:

status - status of the region

Since:

2.1.0

getStatus

Region.Status getStatus()

Returns:

the region's status

copy

Region copy(Fqn newRoot)

copies the region - including eviction queue events - to a new Region instance, attached to a new Fqn root. Typically used with Buddy Replication where region roots need to be adjusted.

Parameters:

newRoot - new root for the region - e.g., a buddy backup root.

Returns:

a new Region instance.

setEvictionPolicy

@Deprecated
void setEvictionPolicy(EvictionPolicyConfig evictionPolicyConfig)

Deprecated.

Configures an eviction policy for this region.

Note: This is deprecated since this is an internal method and never was meant to be a part of the public API. Please do not treat this as public API, it may be removed in a future release and its functionality is not guaranteed.

Parameters:

evictionPolicyConfig - configuration to set

getEvictionPolicyConfig

@Deprecated
EvictionPolicyConfig getEvictionPolicyConfig()

Deprecated.

Returns an eviction policy configuration.

Note: This is deprecated since this is an internal method and never was meant to be a part of the public API. Please do not treat this as public API, it may be removed in a future release and its functionality is not guaranteed.

Returns:

an eviction policy configuration

getEvictionPolicy

@Deprecated
EvictionPolicy getEvictionPolicy()

Deprecated.

Returns an eviction policy.

Note: This is deprecated since this is an internal method and never was meant to be a part of the public API. Please do not treat this as public API, it may be removed in a future release and its functionality is not guaranteed.

Returns:

an eviction policy

nodeEventQueueSize

@Deprecated
int nodeEventQueueSize()

Deprecated.

Returns the size of the node event queue, used by the eviction thread.

Note: This is deprecated since this is an internal method and never was meant to be a part of the public API. Please do not treat this as public API, it may be removed in a future release and its functionality is not guaranteed.

Returns:

number of events

takeLastEventNode

@Deprecated
EvictedEventNode takeLastEventNode()

Deprecated.

Returns the most recent EvictedEventNode added to the event queue by putNodeEvent(org.jboss.cache.eviction.EvictedEventNode).

Note: This is deprecated since this is an internal method and never was meant to be a part of the public API. Please do not treat this as public API, it may be removed in a future release and its functionality is not guaranteed.

Returns:

the last EvictedEventNode, or null if no more events exist

putNodeEvent

@Deprecated
void putNodeEvent(EvictedEventNode event)

Deprecated.

Adds an EvictedEventNode to the internal queue for processing by the eviction thread.

Note: This is deprecated since this is an internal method and never was meant to be a part of the public API. Please do not treat this as public API, it may be removed in a future release and its functionality is not guaranteed.

Parameters:

event - event to add

clone

@Deprecated
Region clone()
             throws CloneNotSupportedException

Deprecated.

Returns:

a clone

Throws:

CloneNotSupportedException