Package ej.kf

Class 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 Detail

      • getInstance

        public static Kernel getInstance()
        Returns the singleton instance representing the Kernel.
        Returns:
        the singleton instance representing the Kernel

      • 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

      • 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.

      • 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

      • 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

      • 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

      • 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()

      • 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)