Voyager API Design Guide

This page contains a first draft for the Design and Implementation Guide for the Voyager API. Please note that the codename Voyager will not appear in the resulting document anylonger, once this document has reached the final version.

Please see also the pages
 * The Voyager API Basics - containing the basic ideas for the Voyager API
 * The Voyager API Design containing the design/coverage of the upcoming Voyager API

Voyager Main Page

Foreword
The Voyager API will be implemented as an object oriented class library, using the Netlabs Object Model (NOM).

In the progress of ongoing development, for different reasons it may be required that the Voyager API could use extensions, due to
 * changes within the system, applications require additional interfaces to
 * the underlying kernel or
 * supporting libraries
 * new hardware or file formats requiring support
 * new concepts requiring implementation of new classes and/or frameworks (sets of classes)

In order to keep a high quality standard within the Voyager API, it is vital to ensure that contributions match the way the current Voyager API is designed and implemented. This is the task of the maintainers of the Voyager API, and is done by
 * maintaining this document, defining the rules and methods for design and implementation
 * providing expertise before or during the design and/or implementation of an extension (the earlier involved, the better)
 * deciding if a given contribution can be accepted or has to be modified to meet the requirements for a contribution to the Voyager API

About this document
This document is intended for the following people:
 * developers, for understanding
 * the methods and rules that are used for and apply to the task of designing and implementing additions to the Voyager API
 * how to contribute extensions to the maintainers of the Voyager API
 * maintainers of the Voyager API, for
 * ensuring that contributed extensions apply to the rules of design and implementation described in this document and meet the requirements for a contribution
 * performing the defined methods/procedures when accepting a contribution

Design Goals for the Voyager API
The design goals for the Voyager API are:
 * the API is implemented as an object oriented class library
 * using Netlabs Object Model (NOM)
 * allows bindings for non-OO compiler and script languages
 * allows better binary compatibility for external extensions
 * no 1-1 implementation of (one of) the underlying libraries
 * trade in some flexibility for simplicity
 * cover approx. 60-80% of the used cases of the supported libraries
 * gain the same reputation concerning quality like the OS/2 API
 * see this API as advertisement for Voyager as an exemplary development platform

Implementing the Voyager API as an object oriented class library
The Voyager API will be implemented using the Netlabs Object Model (NOM), implementing a runtime for an object oriented class library. Thus the API itself will be implemented as software classes, allowing access to data and functionality by their interface, being implemented by methods (kind of functions) and members (variables).

Within the class library, all software classes are part of the class hierarchy, where specialized subclasses are derived from parent classes. Subclasses inherit the behaviour from the parent class, and extend an/or modify the behaviour of the parent class. Some of the parent classes are so-called 'abstract classes' that is they are not intended to create instances of it, but only for implementing base functionality for subclasses. A special form of this are 'virtual base classes', which do not implement any code, but only define the mandantory interface of a subclass (e.g. a virtual base class for file decoder defines that a subclass for handling of a specific file must implement the method ReadFileContents).

The complete API will be spearated into major parts by groups of classes. When the API is to be extended, this can happen by
 * implementing the extension in a new or existing method in an existing class
 * derive a new class from an existing one, and implementing the extension in this class
 * define a new major API or framework and derive a complete new group of classes from the root class, implementing the extension in these classes

The following rules apply when deciding which of these options are applicable for a given extension:

Another design issue is to decide when using native compiler types (or appropriate typedef's) instead of classes for data types. In general, for maximum performance and minimum complexity, the native compiler data types should be used for simple data types. For complex data types, or where compiler implemented operators are not sufficient, data type classes should be implemented. In general, data type classes will be implemented by the Netlabs Object Model (NOM), if they are not specific to a special part of the Voyager API implemented with it.

The Voyager API Classes and Interface Namespace
Cinc: this part must be reviewed and should be considered a proposal only. cla: all of this document must be considered as a proposal :-)

The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.

The reasons for the member name prefix is that the IDL compiler creates access macros with the method or member name prepended by an underscore only. If the members would not be prefixed, two classes within the entire class hierarchy could not have a method with the same name without resorting to the full method name which is built from the class name followed by the method name. Secondly using prefixes helps identifying the class group a method belongs to.

Within a major part of the Voyager API,
 * class names are prepended with an all upper case prefix, like SVC, SYS, WP, e.g. SYSObject
 * member names are prepended with a lower case prefix, like svc, sys, wp, e.g. sysQueryUniverseSize
 * symbol names are prepended with an uppercase prefix with a trailing underscore, like SVC_, SYS_, WP_
 * API function names are prepended with a mixed case prefix, like Svc, Sys, Wp, e.g. SysCalculateNewUniverseSize
 * Prefix for helper functions (internal, maybe static, functions not visible to the world) needs to be defined

The class hierarchy of a major part of the Voyager API starts with the class XXXObject, where XXX is the all uppercase prefix of the API Part. Most class of this API part are derived from this base class.

In addition to that the following rules apply to naming methods:
 * where methods return a pointer to an object or data type
 * *query* methods return a pointer to original data that may not be altered or freed
 * *get* methods return a pointer to a copy of original data where the copy has to be released by the caller (destroy the object or free memory. A dedicated method to do that is ususally appropriate).

Extending the Voyager API
 

The following tasks are to be processed when suggesting an extension to the Voyager API:
 * document new functionality
 * used case
 * requirements
 * (*) search for (base) classes for either to
 * implement it in a new or existing method in an existing class
 * derive a new class from an existing one for it
 * define a new major API or framework, derive from root class for it
 * (*) analyse and document design options
 * define testcases per design option
 * (*) decide for one option, document the reasons for the decision
 * implement the extension within a testcase
 * perform the testcase, document results
 * send contribution to the API maintainers, including
 * the testcase with source
 * all documentation items

For the steps marked with (*) it may make sense to discuss the existing results with the maintainers of the API, to make sure that the testcase implementation already meets all requirements and design and implementation rules.

Accepting contributions for the Voyager API
 

When a proposal for an extension is being sent to the maintainer team, the team will determine the maintainer for that extension (not necessarily one of the team). The proposal can be sent in as an idea only, when asking for expertise and feedback, or already as a fully implemented extension.

In order to process the extension proposal, 'the maintainer' will perform the following steps, where generally one major step will be performed only when the predecessor has been finished:
 * provide expertise and feedback to the author of the extension
 * review the contribution for the following aspects (if already available)
 * usability of new functionality
 * design options analysis and decision
 * testcase implementation and results
 * develop further design and implementation alternative(s), where applicable
 * pass back to author for review and modification, where required
 * discuss changes to this Design and Implementation Guide, where applicable/required
 * perform final discussion in maintainer team
 * within the maintainer team, decide to accept or reject the contribution, concerning design and implementation


 * when accepted
 * request further documentation for the API docs, where required
 * add the extension and documentation to the Voyager API code archive
 * extend the build environment in the source archive, where required
 * when rejected, document reasons and, where applicable, either
 * request modification
 * propose design alternative(s)

It may be necessary to perform this procedure several times, before an extension is completely accepted or rejected.

Appendix: Requirements for testcase packages
 
 * documentation
 * design
 * per testcase
 * description (including prerequisites)
 * how to execute
 * expected result
 * compiled binaries

Appendix: Building the Voyager API
 
 * define the standard build environment for the Voyager API
 * required programs
 * provided methods
 * build all, docs,
 * call debugger ?
 * build/maintain release packages
 * document how to technically extend the build system for to add a new class and/or method