Kernel APIs

Kernel API files (kernel.api) specify among all types owned by the Kernel which ones must be used by Features, and for those types which members (method, and static fields) are allowed to be accessed by Features. When a type is not declared in a Kernel API, the Kernel and each Feature can have their own version of that type, but if a type is declared in a Kernel API file only the Kernel version will be used by the Kernel and all the Features.

For mode details refer to the Class Spaces chapter of the Kernel & Features Specification.

Kernel API Definition

A Kernel API file is an XML file named kernel.api declared at the root of one or more path composing the Application classpath.

Kernel API Example for exposing System.out.println API
 <require>
     <type name="java.io.PrintStream"/>
     <type name="java.lang.String"/>
     <type name="java.lang.System"/>
     <field name="java.lang.System.out"/>
     <method name="java.io.PrintStream.println(java.lang.String)void"/>
 </require>

The table below describes the format of the XML elements. The full XML schema is available in the Kernel & Features Specification.

XML elements specification
Tag Attributes Description
require   The root element
field   Static field declaration. Declaring a field as a Kernel API automatically sets the declaring type as a Kernel API
name Fully qualified name on the form [type].[fieldName]
method   Method or constructor declaration. Declaring a method or a constructor as a Kernel API automatically sets the declaring type as a Kernel API
name Fully qualified name on the form [type].[methodName]([typeArg1,...,typeArgN) typeReturned. Types are fully qualified names or one of a base type as described by the Java language (boolean, byte, char, short, int, long, float, double) When declaring a constructor, methodName is the single type name. When declaring a void method or a constructor, typeReturned is void
type   Type declaration, allowed to be loaded from a Feature using Class.forName()
name Fully qualified name on the form [package].[package].[typeName]

Writing Kernel APIs

This section lists different ways to help to write kernel.api files.

Default Kernel APIs Derivation

MicroEJ Corp. provides predefined kernel API files for the most common libraries provided by a Kernel. These files are packaged as MicroEJ modules in the Developer Repository under the com/microej/kernelapi organisation.

The packaged file kernel.api can be extracted from the JAR file and edited in order to keep only desired types, methods and fields.

Kernel API Generator

MicroEJ Kernel API Generator is a tool that help to generate a kernel.api file based on a Java classpath.

In MicroEJ SDK, create a new MicroEJ Tool launch, Run > Run Configurations > MicroEJ Tool, choose your Platform, select Kernel API Generator for the Settings options, and don’t forget to set the output folder.

../_images/kernelapi_launch.png

Define the classpath to use in the Configuration tab, and Press Run. A kernel.api file is generated in the output folder and it contains all classes, methods and fields found in the given classpath.

Category: Kernel API Generator

../_images/img115.png
Group: Classpath
Option(list):

Option Name: kernel.api.generator.classpath

Default value: (empty)

Group: Types Filters
Option(text): Includes Patterns

Option Name: kernel.api.generator.includes.patterns

Default value: **/*.class

Description: Comma separated list of ANT Patterns for types to include.

Option(text): Excludes Patterns

Option Name: kernel.api.generator.excludes.patterns

Default value: (empty)

Description: Comma separated list of ANT Patterns for types to exclude.