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.