ej.kf

Class Feature

java.lang.Object

ej.kf.Module

ej.kf.Feature

public class Feature
extends Module

A Feature represents an optional part of an application that adds new features and services.

A Feature only depends on Kernel code. A Feature is considered as unreliable code from Kernel point of view.

Instances of this class are owned by the Kernel.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Feature.State A Feature state.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_CRITICALITY The maximum criticality that a feature can have.
static int	MIN_CRITICALITY The minimum criticality that a feature can have.
static int	NORM_CRITICALITY The default criticality that is assigned to a feature.

Method Summary

Modifier and Type	Method and Description
Thread[]	getAllAliveThreads() Gets a snapshot of all alive threads owned by this Feature (some threads included in the returned array may have been terminated when this method returns, some new threads may have been created when this method returns).
int	getCriticality() Returns the criticality of this feature.
long	getMemoryLimit() Gets the maximum amount of memory heap that can be allocated by this Feature.
InputStream	getResourceAsStream(String name) Finds in this feature the resource with the given name.
Feature.State	getState() Returns the current Feature state.
void	setCriticality(int criticality) Sets the criticality of this feature.
boolean	setMemoryLimit(long size) Sets the maximum amount of memory heap that can be allocated by this Feature.
void	start() Causes this Feature to start.
void	stop() Causes this Feature to stop.

Methods inherited from class ej.kf.Module

getAllocatedMemory, getExecutionCounter, getExecutionQuota, getName, getProvider, getUID, getVersion, setExecutionQuota

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_CRITICALITY

public static final int MAX_CRITICALITY

The maximum criticality that a feature can have.

See Also:

getCriticality(), Constant Field Values

MIN_CRITICALITY

public static final int MIN_CRITICALITY

The minimum criticality that a feature can have.

See Also:

getCriticality(), Constant Field Values

NORM_CRITICALITY

public static final int NORM_CRITICALITY

The default criticality that is assigned to a feature.

See Also:

getCriticality(), Constant Field Values

Method Detail

getAllAliveThreads

public Thread[] getAllAliveThreads()

Gets a snapshot of all alive threads owned by this Feature (some threads included in the returned array may have been terminated when this method returns, some new threads may have been created when this method returns).

Returns:

the threads owned by this Feature

Throws:

IllegalStateException - if the Feature is not in the Feature.State.STARTED state

getCriticality

public int getCriticality()

Returns the criticality of this feature.

The criticality is used by the system to determine which feature to kill when there is memory pressure. The features with the lowest criticality will be killed first. The features with a criticality set to MAX_CRITICALITY are not killed automatically by the system when there is memory pressure.

The default criticality of a feature is NORM_CRITICALITY.

Returns:

the criticality.

Throws:

IllegalStateException - if this feature is in Feature.State.UNINSTALLED state.

getMemoryLimit

public long getMemoryLimit()

Gets the maximum amount of memory heap that can be allocated by this Feature. By default, the maximum amount of memory heap is equal to Runtime.maxMemory() (disabled).

Returns:

the maximum amount of memory heap that can be allocated by this Feature (in bytes)

Throws:

IllegalStateException - if this feature is in Feature.State.UNINSTALLED state.

Since:

1.7

See Also:

setMemoryLimit(long)

getResourceAsStream

@Nullable
public InputStream getResourceAsStream(String name)

Finds in this feature the resource with the given name. A resource is some data (images, audio, text, etc) that can be accessed from code.

The name of a resource is a '/'-separated path name that identifies the resource. This path must be absolute (i.e., begins with a '/'); if not, this method returns null.

This method will search this feature for the resource. It will not search the Kernel for the resource.

The returned input stream is automatically closed when this feature is uninstalled.

Parameters:

name - The resource name

Returns:

An input stream for reading the resource, or null if the resource could not be found.

Throws:

IllegalStateException - if this feature is in Feature.State.UNINSTALLED state.

getState

public Feature.State getState()

Returns the current Feature state.

Returns:

this Feature's state.

See Also:

Feature.State

setCriticality

public void setCriticality(int criticality)

Sets the criticality of this feature.

Parameters:

criticality - the new criticality of this feature.

Throws:

IllegalArgumentException - If the criticality is not in the range MIN_CRITICALITY to MAX_CRITICALITY.

IllegalStateException - if this feature is in Feature.State.UNINSTALLED state.

See Also:

getCriticality()

setMemoryLimit

public boolean setMemoryLimit(long size)

Sets the maximum amount of memory heap that can be allocated by this Feature.
This method may trigger the garbage collector. The maximum amount of memory heap is not updated if the given limit is lower than Module.getAllocatedMemory().
An OutOfMemoryError is thrown during an allocation made by a Feature if its memory usage would exceed this limit.

Parameters:

size - the maximum amount of memory heap that can be allocated by this Feature (in bytes)

Returns:

true if the maximum amount of memory heap has been updated, false otherwise.

Throws:

IllegalArgumentException - if the requested size is negative or greater than the memory heap (Runtime.maxMemory())

IllegalStateException - if this feature is in Feature.State.UNINSTALLED state.

Since:

1.7

See Also:

getMemoryLimit(), Module.getAllocatedMemory()

start

public void start()

Causes this Feature to start. A new thread owned by the Feature is created and started. The Feature is switched in the Feature.State.STARTED state and this method returns. Next steps are executed asynchronously within the new thread context:

• Feature clinits are executed
• Entry point is instantiated
• FeatureEntryPoint.start() is called

Throws:

IllegalStateException - if the Feature state is not in Feature.State.INSTALLED state

stop

public void stop()

Causes this Feature to stop. The following steps are executed:

• A new thread owned by the Feature is created and FeatureEntryPoint.stop() is executed.
• Wait until this thread is normally terminated or timeout occurred.
• ej.lang.Resource.reclaim() is called for each resource that remains open by the Feature.
• A DeadFeatureException is thrown in threads that are running Feature code or in threads that want to call Feature code.
• Wait until all threads owned by this Feature are terminated.
• Feature state is set to Feature.State.STOPPED.
• Objects owned by the Feature are reclaimed. If there are no remaining alive objects, the Feature state is set to Feature.State.INSTALLED.

When the new Feature state is Feature.State.INSTALLED, the Feature runtime has been fully reclaimed (threads and objects). Otherwise, the new Feature state is Feature.State.STOPPED and there are some remaining Feature objects references from Kernel.

This method can be called multiple times by the Kernel to reclaim objects again and thus to try to switch the Feature in the Feature.State.INSTALLED state.

When Feature state is set to Feature.State.STOPPED, Kernel application shall remove all its references to objects owned by this Feature, through the calls of FeatureStateListener.stateChanged(ej.kf.Feature, ej.kf.Feature.State).

Throws:

IllegalStateException - if the Feature is in the Feature.State.INSTALLED or Feature.State.UNINSTALLED state