WL#4115: Plug-in Service Guidelines

When developing service interfaces into the server, it is essential that the
services are robust, well-defined, and future-proof. To this end, a set of
guidelines for how to ensure that the interface satisfy these properties should
be developed.

Note that the end goal is *not* to produce a complete and all-encompassing
procedure that should be followed, this is not possible due to the nature of the
problem, but rather to give support and provide *some* formal steps in order to
avoid the most obvious mistakes before we deploy the service interface.

Deliverables
============

For this worklog, we expect the deliverables described in this section. Note
that these documents are not final in the sense that they do not change; we are
bound to make mistakes initially and need to devise various ways of avoiding or
at least reducing the risk of making them again.


Guidelines for the development of service interfaces for the MySQL server
--------------------------------------------------------------------------

This document should describe:

- a set of guidelines for developing new service interfaces

- a set of requirements that should be met for service interfaces to be
  deployed with the server


Examples of services interfaces with use cases
----------------------------------------------

This document describes some services that will be deployed initially and will
be accompanied with a more extensive description of the design decisions made
during development. All in order to demonstrate how to approach the problem of
writing good services.

Open Issues
===========

Implementation identifier
~~~~~~~~~~~~~~~~~~~~~~~~~

We probably want to have a short name of the service, as well as a unique
identifier that identifies exactly what incarnation of the interface we're
using. To illustrate, let me give a simple example. Suppose that we deploy a
logging interface called "syslog" that in the basic implementation just calls
syslog(). For machines where syslog does not exist, we decide to not implement
it, but some third-party vendor decides that it is needed and therefore writes
an implementation for, say, PalmOS. In this case, we have a default
implementation that is not used, but we would like to be able to identify
exactly what incarnation of the interface that is actually being used.

For this case, I see only two alternatives: use a URI (or IRI), or use the Java
package naming convention. To identify an implementation using delivered by
NiftyGadgets Inc. (who owns the domain niftygadgets.com) the alternatives
would be::

   http://niftygadgets.com/mysql/service/syslog
   urn:mysql:logging:syslog:niftygadgets
   service:/logging/syslog:niftygadgets
   com.niftygadgets.mysql.service.syslog

Here I'm demonstrating a few different alternatives for the URIs, but just one
example of the Java package naming convention. The first example is a URL, the
second a URN, the third is a URI inspired by Solaris Service FMRI identifiers,
and the fourth is a Java package naming convention.


Service Interface Attributes
============================

All services should have:

- A unique *name*
- A set of one or more *methods* [is it reasonable to have zero methods?],
  where each method has zero or more *parameters*.


Service implementation attributes
=================================

All service implementaitons should have at least:

- A unique *identifier* that identifies this implementation of an interface.
  Note that this is not the same as the service version.


Service Deliverables
====================

Each service interface consists of a set of *deliverables*, where each
deliverable is a document, a piece of code, or other tangible asset.

- A *service interface specification* as described in _`Service Implementation
  Attriutes`.

Handle structure
================

From the perspective of the registry, the handle is treated as an opaque
sequence of bytes. However, for administrative purposes, it makes sense to
encourage a certain structure on the handle.