--- a/usr/src/doc/rad-dev/c-concepts-apis.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-concepts-apis.xml Tue Jun 19 17:37:39 2012 -0400
@@ -16,7 +16,7 @@
Copyright (c) 2010, 2012, Oracle and/or its affiliates. All rights reserved.
-->
-<section><title>APIs</title>
+<section><title>Interfaces</title>
<para>
The primary purpose of <command>rad</command> is to consistently expose
@@ -30,13 +30,13 @@
</para>
<para>
-An <acronym>API</acronym> is a formal definition of how a client may
+An interface is a formal definition of how a client may
interact with a <command>rad</command> server object. An
-<acronym>API</acronym> may be shared amongst several objects, e.g. when
+interface may be shared amongst several objects, e.g. when
maintaining a degree of uniformity is possible and useful, or may be
implemented by only one. It is analogous to an interface or pure
abstract class in an object oriented programming language. In the case
-of <command>rad</command>, an <acronym>API</acronym> consists of a
+of <command>rad</command>, an interface consists of a
name, the set of features a client may interact with, optionally a set
of derived types referenced by the features, and a version. The
features supported include methods (procedure calls made in the context
@@ -46,20 +46,20 @@
<section><title>Name</title>
<para>
- Each <acronym>API</acronym> has a name. This name is used by the
+ Each interface has a name. This name is used by the
toolchain to construct indentifier names when generating code, and
is returned by the server along with the rest of the
- <acronym>API</acronym> definition when an object is examined by a
+ interface definition when an object is examined by a
client. There isn't a global namespace for
- <acronym>API</acronym>s, however. A client is expected either to
- know which objects implement which <acronym>API</acronym>s (typical
+ interfaces, however. A client is expected either to
+ know which objects implement which interfaces (typical
consumer) or to query <command>rad</command> for the object's full
- <acronym>API</acronym> definition (debugger or interactive tools).
+ interface definition (debugger or interactive tools).
</para>
<para>
Though in the future <command>rad</command> may establish a
- namespace for <acronym>API</acronym>s, the lack of a namespace
+ namespace for interfaces, the lack of a namespace
doesn't present a serious problem today. A <trademark
class='trade'>Unix</trademark> executable isn't going to open every
library in <filename class='directory'>/usr/lib</filename> until it
@@ -67,9 +67,9 @@
it is going to open <filename
class='libraryfile'>/usr/lib/libc.so.1</filename>. Likewise, the
typical client isn't going to search for objects claiming to export
- a particular <acronym>API</acronym>, it will be acting on the
+ a particular interface, it will be acting on the
specific object documented to have not just the desired
- <acronym>API</acronym>, but the desired behavior as well.
+ interface, but the desired behavior as well.
</para>
</section>
@@ -78,7 +78,7 @@
Three classes of derived types may be defined for use by features:
<type>structure</type>s, <type>union</type>s, and
<type>enumeration</type>s. Each type defined must be uniquely
- named. As with <acronym>API</acronym>s, there isn't a global type
+ named. As with interfaces, there isn't a global type
namespace. The types defined in an <acronym>API</acronym> are only
available to the features defined in that <acronym>API</acronym>.
</para>
@@ -98,10 +98,10 @@
<note>
<para>
- Enforcing a common namespace for <acronym>API</acronym> features
+ Enforcing a common namespace for interface features
isn't always enough. Some language environments place additional
constraints on naming. For instance, a <acronym>JMX</acronym>
- client using MXBean proxies will see an <acronym>API</acronym> with
+ client using MXBean proxies will see an interface with
synthetic methods of the form <function>getXXX()</function> or
<function>setXXX()</function> for accessing attribute XXX that must
coexist with other method names — explicitly defining methods
@@ -205,7 +205,7 @@
<para>
Given methods, attributes are arguably a superfluous
- <acronym>API</acronym> feature. Writing an attribute of type
+ interface feature. Writing an attribute of type
<type>X</type> can be implemented with a method that takes one
argument of type <type>X</type> and returns nothing, and reading an
attribute of type <type>X</type> can be implemented with a method
@@ -240,7 +240,7 @@
An event is an asynchronous notification generated by rad and
consumed by clients. A client may subscribe to events by name to
register interest in them. The subscription is performed on an
- object which implements an API. In addition to a name, each event
+ object which implements an interface. In addition to a name, each event
has a type.
</para>
<para>
@@ -287,7 +287,7 @@
represent committed interfaces whose compatibility is paramount,
others are private interfaces that are changed only in lockstep
with the software that uses them. To address all these issues,
- <command>rad</command> <acronym>API</acronym>s are versioned.
+ <command>rad</command> interfaces are versioned.
</para>
<section><title>Numbering</title>
@@ -296,14 +296,14 @@
needs to be solved. <command>rad</command> uses a simple
<replaceable>major</replaceable>.<replaceable>minor</replaceable>
versioning scheme. When a compatible change to an
- <acronym>API</acronym> is made, its minor version number is
+ interface is made, its minor version number is
incremented. When an incompatible change is made, its major
version number is incremented and its minor version number is reset
to 0.
</para>
<para>
- In other words, an implementation of an API that claims to be
+ In other words, an implementation of an interface that claims to be
version <replaceable>X</replaceable>.<replaceable>Y</replaceable>
(where <replaceable>X</replaceable> is the major version and
<replaceable>Y</replaceable> is the minor version) must support any
@@ -313,7 +313,7 @@
</para>
<para>
- The following <acronym>API</acronym> changes are considered
+ The following interface changes are considered
compatible:
<itemizedlist>
@@ -344,7 +344,7 @@
</para>
<para>
- The following <acronym>API</acronym> changes are considered
+ The following interface changes are considered
incompatible:
<itemizedlist>
@@ -386,10 +386,10 @@
<note>
<para>
- An <acronym>API</acronym> is more than just a set of methods,
+ An interface is more than just a set of methods,
attributes, and events. Associated with those features are
well-defined behaviors. If those behaviors change, even if the
- structure of the <acronym>API</acronym> remains the same, a change
+ structure of the interface remains the same, a change
to the version number may be required to honor the above
guarantee.
</para>
@@ -402,8 +402,8 @@
To solve the problem wherein different features are intended for
different consumers, <command>rad</command> defines three
commitment levels: private, uncommitted, and committed. Each
- method, attribute, and event in an <acronym>API</acronym> defines
- its commitment level independently. The <acronym>API</acronym> is
+ method, attribute, and event in an interface defines
+ its commitment level independently. The interface is
assigned a separate version number, as described in the previous
section, per commitment level.
</para>
@@ -423,7 +423,7 @@
When a feature changes commitment level, it is treated as if the
feature was removed from the old commitment level and added to the
new one. If a feature becomes less committed, then that implies an
- incompatible change for the every commitment level that no longer
+ incompatible change for every commitment level that no longer
includes that feature, but no change for every commitment level
that still includes the feature (due to the implicit nesting of
commitment levels). If a feature becomes more committed, then that
@@ -433,7 +433,7 @@
</para>
<para>
- In the simple case of an <acronym>API</acronym> containing
+ In the simple case of an <acronym>API</acronym>containing
interfaces of only a single commitment level, this reduces to
traditional commitment-agnostic major/minor versioning.
</para>
@@ -442,11 +442,12 @@
<section><title>Clients and Versioning</title>
<para>
- A <command>rad</command> client can ask for <acronym>API</acronym>
+ A <command>rad</command> client can ask for interface
version information (if the protocol in use doesn't automatically
provide it). What the client does with this information is
entirely up to it. It can expose that information directly to
- interface consumers, or it can provide interfaces that encapsulate
+ interface consumers, or it can provide <acronym>API</acronym>s
+ that encapsulate
verifying that the version the client expects is the version the
server is providing.
</para>