View source for 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
* [[Voyager_API_Basics|The Voyager API Basics]] - containing the basic ideas for the Voyager API
* [[Voyager_API_Design|The Voyager API Design]] containing the design/coverage of the upcoming Voyager API

[[Voyager|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 'base 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 a specific file must implement the method readfilecontents).

The complete API will be spearated into major parts by [[Voyager_API_Design|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:
* ''<not yet determined>''

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 ==
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. The name clash problem is not completely solved by the member name prefix, but eased a lot.

Within a major part of the Voyager API, 
* class names are prepended with a mixed case prefix, like Svc, Sys, Wp
* member names are prepended with a lower case prefix, like svc, sys, wp
* symbols are prepended with an uppercase prefix with a trailing underscore,  like SVC_, SYS_, WP_


== 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  ==
''<to be edited>''
* documentation
** design
** per testcase
*** description (including prerequisites)
*** how to execute
*** expected result
* compiled binaries


== Appendix: Building the Voyager API ==
''<to be edited>''
* 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