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

All Methods Static Methods Concrete Methods Deprecated Methods
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`.
`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`.
`static void`	`setUncaughtExceptionHandler(UncaughtExceptionHandler handler)` Deprecated. Use `Thread.setUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler)`
`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
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
  - getInstance
```
public static Kernel getInstance()
```
    Returns the singleton instance representing the Kernel.
    
    Returns:
    
    the singleton instance representing the Kernel
  - 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()
  - 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()
  - 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()
  - 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
  - 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()
  - getAllLoadedFeatures
```
public static Feature[] getAllLoadedFeatures()
```
    Returns the set of Features currently loaded.
    
    Returns:
    
    all Features that are not in the state Feature.State.UNINSTALLED.
  - 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()
  - isInKernelMode
```
public static boolean isInKernelMode()
```
    Tells whether the current thread context is currently in Kernel mode.
    
    Returns:
    
    the result of Kernel.getContextOwner() == Kernel.getInstance()
  - getOwner
```
public static Module getOwner(Object o)
```
    Returns the owner of the given Object.
    
    Parameters:
    
    o - the object.
    
    Returns:
    
    the owner of the object.
  - getContextOwner
```
public static Module getContextOwner()
```
    Returns the owner of the current thread context.
    
    Returns:
    
    the context owner.
  - setUncaughtExceptionHandler
```
@Deprecated
public static void setUncaughtExceptionHandler(@Nullable
                                                            UncaughtExceptionHandler handler)
```
    Deprecated. Use Thread.setUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler)
    
    Sets the handler invoked when a Feature thread abruptly terminates due to an uncaught exception.
    
    Parameters:
    
    handler - the handler to register, or null if no explicit handler.
  - 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
  - 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
  - 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
  - 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.
  - 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
  - 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()
  - 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
  - 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.
  - 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
  - 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.
  - 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
  - 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)
  - 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
  - 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
  - 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

Class Kernel

Method Summary

Methods inherited from class ej.kf.Module

Methods inherited from class java.lang.Object

Method Detail

getInstance

load

install

uninstall

canUninstall

unload

getAllLoadedFeatures

enter

exit

isInKernelMode

getOwner

getContextOwner

setUncaughtExceptionHandler

addFeatureStateListener

addResourceControlListener

removeFeatureStateListener

removeResourceControlListener

getAllFeatureStateListeners

runUnderContext

clone

addConverter

removeConverter

bind

isSharedInterface

newProxy

isAPI

getSharedInterface

getEquivalentSharedInterface

areEquivalentSharedInterfaces

getImplementedSharedInterface