ej.kf

Class Kernel

java.lang.Object

ej.kf.Module

ej.kf.Kernel

public class Kernel
extends Module

The Kernel represents the atomic part of an application. Kernel code is assumed to be reliable. The Kernel class provides core methods to manage Features. It is intended to be used only by the Kernel code, and not viewed from the Feature.

Method Summary

Modifier and Type	Method and Description
static void	addConverter(Converter<?> converter) Adds the Converter to the list of converters.
static void	addFeatureStateListener(FeatureStateListener listener) Adds the given FeatureStateListener to the list of listeners that are notified when the state of a Feature has changed.
static void	addResourceControlListener(ResourceControlListener listener) Adds the given ResourceControlListener to the list of listeners that are notified when a Feature is stopped by the Resource Control Manager.
static boolean	areEquivalentSharedInterfaces(Class<?> si1, Class<?> si2) Tells whether the given classes are equivalent shared interfaces.
static <T> T	bind(T o, Class<T> targetType, Feature targetOwner) Binds an Object owned by a Feature to another Feature.
static boolean	canUninstall(Feature f) Tells whether the given Feature can be uninstalled.
static <T> T	clone(T from, Module toOwner) Creates and returns a copy of the given object, so that the newly created object is owned by the given Module.
static void	enter() Enters in Kernel mode: the current thread context is switched to be owned by the Kernel.
static void	exit() Exits from Kernel mode: the current thread context is restored to the owner of the caller of the method (which can remain the Kernel).
static FeatureStateListener[]	getAllFeatureStateListeners() Returns an array containing all the FeatureStateListener that are notified when the state of a Feature has changed.
static Feature[]	getAllLoadedFeatures() Returns the set of Features currently loaded.
static Module	getContextOwner() Returns the owner of the current thread context.
static Class<?>	getEquivalentSharedInterface(Class<?> si, Feature target) Gets the equivalent shared interface in the given target Feature.
static Class<?>	getImplementedSharedInterface(Class<?> fromClass, Class<?> topInterface) Gets the first shared interface implemented by the given class under the hierarchy of topInterface.
static Kernel	getInstance() Returns the singleton instance representing the Kernel.
static Module	getOwner(Object o) Returns the owner of the given Object.
long	getReservedMemory() Gets the minimum amount of memory heap reserved for the Kernel.
static Class<?>	getSharedInterface(Class<?> si, Class<?> topInterface, Feature target) From a shared interface, gets the closest shared interface in the given target Feature.
static Feature	install(InputStream is) Installs a Feature from an InputStream.
static boolean	isAPI(Class<?> c) Tells whether the given class is a Kernel API.
static boolean	isInKernelMode() Tells whether the current thread context is currently in Kernel mode.
static boolean	isSharedInterface(Class<?> c) Tells whether the given class is a shared interface (i.e.
static Feature	load(InputStream is) Installs a Feature from an InputStream and starts it.
static <T> Proxy<T>	newProxy(T ref, Module owner) Allocates a new Proxy and sets its reference to the given object.
static void	removeConverter(Converter<?> converter) Removes the Converter to the list of converters.
static void	removeFeatureStateListener(FeatureStateListener listener) Removes the FeatureStateListener to the list of listeners that are notified when the state of a Feature has changed.
static void	removeResourceControlListener(ResourceControlListener listener) Removes the ResourceControlListener to the list of listeners that are notified when a Feature is stopped by the Resource Control Manager.
static void	runUnderContext(Module contextOwner, Runnable runnable) Calls the Runnable.run() method with current context set to the given Module.
boolean	setReservedMemory(long size) Sets the minimum amount of memory heap reserved for the Kernel.
static void	uninstall(Feature f) Uninstalls a Feature.
static boolean	unload(Feature f) Stops a Feature and uninstalls it if its state is Feature.State.INSTALLED after Feature.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

Method Detail

addConverter

public static void addConverter(Converter<?> converter)

Adds the Converter to the list of converters. Registered converters are used by bind(Object, Class, Feature).

Parameters:

converter - the new converter to add

Throws:

NullPointerException - if converter is null

IllegalArgumentException - if a converter managing the same type is already registered

See Also:

Converter.getType()

addFeatureStateListener

public static void addFeatureStateListener(FeatureStateListener listener)

Adds the given FeatureStateListener to the list of listeners that are notified when the state of a Feature has changed.

Parameters:

listener - the new listener to add

Throws:

NullPointerException - if listener is null

addResourceControlListener

public static void addResourceControlListener(ResourceControlListener listener)

Adds the given ResourceControlListener to the list of listeners that are notified when a Feature is stopped by the Resource Control Manager.

Parameters:

listener - the new listener to add

Throws:

NullPointerException - if listener is null

areEquivalentSharedInterfaces

public static boolean areEquivalentSharedInterfaces(Class<?> si1,
                                                    Class<?> si2)

Tells whether the given classes are equivalent shared interfaces.

Two classes are equivalent shared interfaces if they are shared interfaces and have the same fully qualified name.

Parameters:

si1 - a class to test

si2 - a class to test

Returns:

true if the given classes are equivalent shared interfaces, false otherwise

bind

@Nullable
public static <T> T bind(@Nullable
                                   T o,
                                   Class<T> targetType,
                                   Feature targetOwner)

Binds an Object owned by a Feature to another Feature.

When the target type is owned by the Kernel, the object is converted using the most accurate registered converter.

When the target type is owned by the Feature, it must be a shared interface. In this case, a Proxy instance is returned. Object identity is preserved across Features: calling multiple times this method with the same parameters returns the same object.

Type Parameters:

T - the Kernel type of the object to bind

Parameters:

o - the object to be converted

targetType - the type of the converted object

targetOwner - the owner of the converted object

Returns:

an object owned by the target owner, or null if o is null or is a Proxy that refers to a dead object

Throws:

IllegalAccessError - if the given object cannot be bounded to the given type

IllegalArgumentException - if the given type is not a shared interface

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

canUninstall

public static boolean canUninstall(Feature f)

Tells whether the given Feature can be uninstalled.

Parameters:

f - the Feature to test

Returns:

true if the Feature can be uninstalled, false otherwise.

Since:

1.6

clone

public static <T> T clone(T from,
                          Module toOwner)
                   throws CloneNotSupportedException

Creates and returns a copy of the given object, so that the newly created object is owned by the given Module. The source object class must be String or must implement Cloneable. Otherwise, a CloneNotSupportedException is thrown. If the source object owner and the target owner are the same, this method is equivalent to Object.clone() method applied on the source object. Otherwise, the object can be cloned if the source object class is owned by the Kernel and all its object references are accessible to the new owner. In all other cases, an IllegalAccessError is thrown.

Type Parameters:

T - the Kernel type of the object to clone

Parameters:

from - the object to clone

toOwner - the owner of the cloned object

Returns:

the cloned object

Throws:

CloneNotSupportedException - if the source object cannot be cloned

IllegalAccessError - if the creation of the new object would break access rules

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

NullPointerException - if one of the arguments is null

enter

public static void enter()

Enters in Kernel mode: the current thread context is switched to be owned by the Kernel. If the current context was already in Kernel mode, this method does nothing.

The context owner is automatically restored when returning from the method (equivalent to calling exit() before returning).

See Also:

exit()

exit

public static void exit()

Exits from Kernel mode: the current thread context is restored to the owner of the caller of the method (which can remain the Kernel). If the restored context is owned by a Feature, all the locals that refer to an object owned by another Feature are reset to null.

See Also:

enter()

getAllFeatureStateListeners

public static FeatureStateListener[] getAllFeatureStateListeners()

Returns an array containing all the FeatureStateListener that are notified when the state of a Feature has changed.

Returns:

an array of FeatureStateListener[] with all the listeners

getAllLoadedFeatures

public static Feature[] getAllLoadedFeatures()

Returns the set of Features currently loaded.

Returns:

all Features that are not in the state Feature.State.UNINSTALLED.

getContextOwner

public static Module getContextOwner()

Returns the owner of the current thread context.

Returns:

the context owner.

getEquivalentSharedInterface

@Nullable
public static Class<?> getEquivalentSharedInterface(Class<?> si,
                                                              Feature target)

Gets the equivalent shared interface in the given target Feature.

The equivalent shared interface is the interface owned by the target Feature such as areEquivalentSharedInterfaces(Class, Class) is true.

Parameters:

si - a shared interface

target - the target Feature where to find the equivalent shared interface of si

Returns:

the equivalent shared interface, null if not found

Throws:

IllegalArgumentException - if si is not a shared interface

getImplementedSharedInterface

@Nullable
public static Class<?> getImplementedSharedInterface(Class<?> fromClass,
                                                               Class<?> topInterface)

Gets the first shared interface implemented by the given class under the hierarchy of topInterface.

If fromClass is a shared interface it is directly returned.

Parameters:

fromClass - a class or an interface owned by a Feature that implements topInterface

topInterface - an interface implemented by fromClass

Returns:

the shared interface type as described or null if no shared interface found

Throws:

IllegalArgumentException - if the given class is an array or is owned by the Kernel or if topInterface is not an interface or if topInterface is not assignable from fromClass

getInstance

public static Kernel getInstance()

Returns the singleton instance representing the Kernel.

Returns:

the singleton instance representing the Kernel

getOwner

public static Module getOwner(Object o)

Returns the owner of the given Object.

Parameters:

o - the object.

Returns:

the owner of the object.

getReservedMemory

public long getReservedMemory()

Gets the minimum amount of memory heap reserved for the Kernel. By default, the minimum amount of memory heap is equal to 0 (disabled).

Returns:

the minimum amount of memory heap reserved for the Kernel (in bytes)

Since:

1.7

See Also:

setReservedMemory(long)

getSharedInterface

@Nullable
public static Class<?> getSharedInterface(Class<?> si,
                                                    Class<?> topInterface,
                                                    Feature target)

From a shared interface, gets the closest shared interface in the given target Feature.

The closest shared interface is computed by returning the first equivalent shared interface in the target Feature, starting from the interface si to the interface topInterface (included).

If the owner of the given shared interface is the target, the same shared interface is returned.

Parameters:

si - a shared interface that extends topInterface interface

topInterface - a shared interface or an interface owned by the Kernel, which is assignable from si.

target - the target Feature where to find the closest equivalent shared interface of si

Returns:

the closest shared interface as described, null if not found.

Throws:

IllegalArgumentException - if si is not a shared interface or if topInterface is not an interface or if topInterface is not assignable from fromClass

See Also:

getEquivalentSharedInterface(Class, Feature)

install

public static Feature install(InputStream is)
                       throws IOException,
                              InvalidFormatException,
                              IncompatibleFeatureException,
                              AlreadyLoadedFeatureException

Installs a Feature from an InputStream. Feature shall have been generated against the current Kernel classes. Feature data is read and linked to the Kernel. The Feature is added to the list of loaded features and its state is set to Feature.State.INSTALLED. The given input stream is let open.

Parameters:

is - the input stream from where the Feature data is loaded.

Returns:

the loaded Feature, in the Feature.State.INSTALLED state.

Throws:

IOException - if something occurs when reading InputStream

AlreadyLoadedFeatureException - if Feature is already loaded

IncompatibleFeatureException - if Feature is not compatible with the current Kernel

InvalidFormatException - if Feature content is invalid

See Also:

getAllLoadedFeatures()

isAPI

public static boolean isAPI(Class<?> c)

Tells whether the given class is a Kernel API.

Parameters:

c - the class to test

Returns:

true if the class is a Kernel API, false otherwise

isInKernelMode

public static boolean isInKernelMode()

Tells whether the current thread context is currently in Kernel mode.

Returns:

the result of Kernel.getContextOwner() == Kernel.getInstance()

isSharedInterface

public static boolean isSharedInterface(Class<?> c)

Tells whether the given class is a shared interface (i.e. an interface owned by a Feature and defined as shared).

Parameters:

c - the class to test

Returns:

true if the class is a shared interface, false otherwise

load

public static Feature load(InputStream is)
                    throws IOException,
                           InvalidFormatException,
                           IncompatibleFeatureException,
                           AlreadyLoadedFeatureException

Installs a Feature from an InputStream and starts it.

Parameters:

is - the input stream from where the Feature data is loaded.

Returns:

the loaded Feature, in the Feature.State.STARTED state.

Throws:

IOException - if something occurs when reading InputStream

AlreadyLoadedFeatureException - if Feature is already loaded

IncompatibleFeatureException - if Feature is not compatible with the current Kernel

InvalidFormatException - if Feature content is invalid

See Also:

install(InputStream), Feature.start()

newProxy

public static <T> Proxy<T> newProxy(T ref,
                                    Module owner)

Allocates a new Proxy and sets its reference to the given object.

Type Parameters:

T - the reference type

Parameters:

ref - the Proxy reference

owner - the owner of the Proxy instance

Returns:

the new Proxy instance initialized with the given reference

Throws:

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

removeConverter

public static void removeConverter(Converter<?> converter)

Removes the Converter to the list of converters.

Does nothing if the converter is not registered or null.

Parameters:

converter - the converter to be removed

removeFeatureStateListener

public static void removeFeatureStateListener(FeatureStateListener listener)

Removes the FeatureStateListener to the list of listeners that are notified when the state of a Feature has changed.

Does nothing if the listener is not registered or null.

Parameters:

listener - the listener to be removed

removeResourceControlListener

public static void removeResourceControlListener(ResourceControlListener listener)

Removes the ResourceControlListener to the list of listeners that are notified when a Feature is stopped by the Resource Control Manager.

Does nothing if the listener is not registered or null.

Parameters:

listener - the listener to be removed

runUnderContext

public static void runUnderContext(Module contextOwner,
                                   Runnable runnable)

Calls the Runnable.run() method with current context set to the given Module.

Parameters:

contextOwner - the context owner that will execute the method

runnable - the Runnable instance to run under the given Feature context.

Throws:

IllegalAccessError - if the Runnable instance is not accessible to the context owner, or if the Runnable is owned by a Feature and must run in Kernel context.

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

setReservedMemory

public boolean setReservedMemory(long size)

Sets the minimum amount of memory heap reserved for the Kernel.
This method may trigger the garbage collector. The minimum amount of memory heap reserved for the Kernel is not updated if the given value is greater than Module.getAllocatedMemory() + Runtime.freeMemory().
An OutOfMemoryError is thrown during an allocation made by a Feature if the memory available to the Kernel is lower than this limit. The memory available for the Kernel is equal to Module.getAllocatedMemory() + Runtime.freeMemory().

Parameters:

size - the minimum amount of memory heap reserved for the Kernel (in bytes)

Returns:

true if minimum amount of memory heap reserved for the Kernel has been updated, false otherwise.

Throws:

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

Since:

1.7

See Also:

getReservedMemory()

uninstall

public static void uninstall(Feature f)

Uninstalls a Feature. When this method returns, the Feature code has been unlinked from the Kernel and reclaimed. The Feature is removed from the list of loaded features and its state is set to Feature.State.UNINSTALLED.

Parameters:

f - the feature to be uninstalled.

Throws:

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

See Also:

getAllLoadedFeatures()

unload

public static boolean unload(Feature f)
                      throws UnknownFeatureException

Stops a Feature and uninstalls it if its state is Feature.State.INSTALLED after Feature.stop().

Parameters:

f - the feature to be unloaded.

Returns:

true if Feature state is Feature.State.UNINSTALLED, false otherwise.

Throws:

UnknownFeatureException - if the given Feature is unknown.

IllegalStateException - if Feature state is Feature.State.UNINSTALLED

See Also:

uninstall(Feature), Feature.stop()