diff --git a/org.fortiss.tooling.kernel/html/developer/.ratings b/org.fortiss.tooling.kernel/html/developer/.ratings index 6837296741c714d72d3091c42e9a72168bd3fa34..b9e314150bb0a3c7e86f6bd2e30c64b8a192af5e 100644 --- a/org.fortiss.tooling.kernel/html/developer/.ratings +++ b/org.fortiss.tooling.kernel/html/developer/.ratings @@ -1 +1 @@ -documentation.html ee511ed8eee3730d1c9c56b794319b68d5d64db6 RED +documentation.html 33dd7b679fd34f6c10d31776950fb9a01607f8a6 YELLOW diff --git a/org.fortiss.tooling.kernel/html/developer/documentation.html b/org.fortiss.tooling.kernel/html/developer/documentation.html index ee511ed8eee3730d1c9c56b794319b68d5d64db6..33dd7b679fd34f6c10d31776950fb9a01607f8a6 100644 --- a/org.fortiss.tooling.kernel/html/developer/documentation.html +++ b/org.fortiss.tooling.kernel/html/developer/documentation.html @@ -1,4 +1,157 @@ -<html><body> -<H1>Developer Documentation for <I>org.fortiss.tooling.kernel</I></H1> -<P>// TODO -</body></html> +<html> +<body> +<h1>Developer Documentation for <i>Tooling Kernel</i> (org.fortiss.tooling.kernel)</h1> + +<h2> Plugin description </h2> +<p> +This plugin provides the non-UI services of the tooling kernel. +</p> +<p> +Each service is identified by a service interface, which provides the public interface to the +service (see <code>org.fortiss.tooling.kernel.service</code> package). +Most of the services are related to an Eclipse extension point and allow the application (built +on top of the kernel) to extend its functionality with specific implementations. +For example, the kernel provides an interface to cope with different storage solutions, which itself +uses to provide a file based storage solution based on the Eclipse workspace. +The extension point schemas for the kernel extensions can found in the <code>schema</code> folder of +the plugins. +</p> +<p> +Extensions to the kernel services are realized by implementing a handler interface provided by the +kernel (see <code>org.fortiss.tooling.kernel.extension</code> package). +In the communication between the kernel and its extensions, additional data may be required +(see <code>org.fortiss.tooling.kernel.extension.data</code> package) or exceptions may be raised +(see <code>org.fortiss.tooling.kernel.extension.exception</code> package). +The kernel also provides abstract base implementations for most of the handler interfaces, +which are located in the <code>org.fortiss.tooling.kernel.extension.base</code> package. +</p> + +<h2>Package Overview</h2> +<h3>constraint</h3> +Package for constraint checkers of the kernel. + +<h3>extension</h3> +<p> +Interface definitions for extension classes of kernel extension points. +</p> +<p> +Each interface corresponds to one extendable service from the <code>kernel.service</code> package +and therefore to one extension point schema definition. +</p> +<p> +A plugable extension must implement the methods of the respective interface in order to work +properly with the kernel implementation. These methods are called by the kernel at the appropriate time, +e.g., a <code>IPrototypeProvider</code> is required to provide its prototype elements when the kernel +calls the <code>getPrototypes()</code> method. +</p> +<p> +The communication between the kernel and extensions usually involves some kind of +data (e.g. <code>Prototype</code>). These data-related classes and interfaces can be +found in the <code>kernel.extension.data</code> package. +</p> +<p> +For some extensions the kernel provides abstract base implementations in the +<code>kernel.extension.base</code> package. +</p> + +<h4>extension.base</h4> +Base implementations for extension classes of kernel extension points. + +<h4>extension.data</h4> +<p> +Interfaces and classes for data transfer between the kernel and extensions. +</p> +<p> +The classes and interfaces of this package appear as parameter and result types of the +interfaces in the <code>kernel.extension</code> package. Parameter objects resemble +additional context data provided to the extension, while result objects are required from the +extension. +</p> +<p> +On the kernel level the context information is usually empty, i.e., the respective interface +is only a marker interface. Higher layers of the tool architecture may extend these interfaces +with additional pieces of information. Here, the kernel is only the mediator between plugable +parts of the tool. +</p> +<p> +Some of the result objects provide additional methods, which are used by the +kernel at a later time after requesting it from the extension (e.g. once the +<code>ITopLevelElement</code> is known to the kernel, the <code>runAsCommand</code> +method will be called whenever some change to the model must be applied). +</p> +<h4>extension.exception</h4> +Exception classes for failure reporting between the kernel and extensions. + +<h3>internal</h3> +Implementations of the kernel services defined in the <code>kernel.service</code> package. +Kernel services are only accessible through the singletons defined in the <code>kernel.service</code> package. +The implementation in this package are not intended to be used directly. +Therefore they are not exported in the <code>plugin.xml</code> + +<h4>internal.storage.eclipse</h4> +<p> +Implementation of the <code>IStorageProvider</code> interface using Eclipse file resources as storage mechanism for models. +</p> +<p> +This storage provider searches all projects in the Eclipse workspace for model files. +Only files in the project's root folder are considered. +For each such files the set of registered <code>eclipseResourceStorageLocationProvider</code> extensions is +asked whether the respective file should be considered a model file. This extension mechanism is used +to allow independent tools (running in the same Eclipse instance or two RCPs running independently) to use +different file extensions for their models, e.g., tool A uses file pattern <code>*.toolA</code>, +while tool B uses the file pattern <code>*.toolB</code>. The file extension is usually a hint on +the meta-model class of the contained root model element. +</p> + +<h3>introspection</h3> +<p> +Interface definitions of the +<a href="https://af3-developer.fortiss.org/projects/autofocus3/wiki/Kernel_Introspection_System_Service"> +kernel introspection system service (KISS)</a>. +</p> +<p> +Each kernel service should implement the <code>IIntrospectiveKernelService</code> interface to provide +useful runtime information and a brief documentation its design and objectives. +</p> +<p> +KISS is intended to be used by the tool developers to ease the development of kernel based tools. +</p> + +<h4>introspection.items</h4> +<p> +Item definitions for the kernel introspection system service (KISS). +</p> +<p> +Each kernel service may provide specific runtime information items, which are presented by some tool developer view or console. +</p> +<p> +Classes in this package are public, since they need to be shared by the user interface implementation. +</p> + +<h3>service</h3> +<p> +Interface definitions of the kernel services. Each interface corresponds to a certain functionality of the kernel. +</p> +<p> +Some of the services provide extension points. Extension implementors should refer to the <code>kernel.extension</code> +and <code>kernel.extension.base</code> packages. Kernel services are implemented by classes from the <code>kernel.internal</code> package. +</p> + +<h4>service.base</h4> +Abstract base implementations for the kernel services. +These classes my also be used for implementing plugability in higher layers of the tool architecture. + +<h4>service.listener</h4> +<p> +Classes in this packages are listener interfaces for kernel services. +</p> +<p> +Sometimes higher layers of the tool architecture must be able to know what is happening in the kernel layer. +Therefore, they can implement the respective listener interface and register themselves with the respective +kernel service. +</p> + +<h3>utils</h3> +Utility methods provided by the kernel. + +</body></html> \ No newline at end of file