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 (KF).

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 (KF).

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
field	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
method	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()
type	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 the 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.

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

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.