--- a/usr/src/doc/rad-dev/a-protocol.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/a-protocol.xml Tue Jun 19 17:37:39 2012 -0400
@@ -625,18 +625,18 @@
</section>
- <section><title><acronym>API</acronym> definitions</title>
+ <section><title>Interface definitions</title>
<para>
The ultimate description of the interactions permitted with a
- particular object is its <acronym>API</acronym> definition. An
- <acronym>API</acronym> definition contains many elements: an
- interface name, a list of versioned <acronym>API</acronym> names
- the <acronym>API</acronym> supports, and definitions of the
- <acronym>API</acronym>'s attributes, methods, and events.
+ particular object is its interface definition. An
+ interface definition contains many elements: an
+ <acronym>API</acronym> name, a list of versioned interface names
+ the interface supports, and definitions of the
+ interface's attributes, methods, and events.
</para>
<para>
- Each <acronym>API</acronym> name has a set of stabilities and
+ Each interface name has a set of stabilities and
versions:
</para>
@@ -662,12 +662,12 @@
</rm:data>
</rm:proto>
- <rm:proto name="APINAME-DATA">
- <rm:data field="api_name" size="varies" type="string<>">
- API name
+ <rm:proto name="INTERFACENAME-DATA">
+ <rm:data field="interface_name" size="varies" type="string<>">
+ interface name
</rm:data>
<rm:data field="versions" size="varies" type="VERSION-DATA<>">
- API versions by stability
+ interface versions by stability
</rm:data>
</rm:proto>
@@ -759,27 +759,28 @@
</rm:proto>
<para>
- Finally, an API definition combines all the above elements.
+ Finally, an interface definition combines all the above elements.
</para>
- <rm:proto name="API-TYPE">
- <rm:data field="ifname" size="varies" type="string<>">
- interface name (domain)
+ <rm:proto name="INTERFACE-TYPE">
+ <rm:data field="api_name" size="varies" type="string<>">
+ API name (domain)
</rm:data>
- <rm:data field="apis" size="varies" type="APINAME-DATA<>">
- API names and versions implemented
+ <rm:data field="interfaces" size="varies"
+ type="INTERFACENAME-DATA<>">
+ interface names and versions implemented
</rm:data>
<rm:data field="types" size="varies" type="TYPESET<>">
- Types used by API definition
+ Types used by interface definition
</rm:data>
<rm:data field="attributes" size="varies" type="ATTRIBUTE-TYPE<>">
- API attributes
+ interface attributes
</rm:data>
<rm:data field="methods" size="varies" type="METHOD-TYPE<>">
- API methods
+ interface methods
</rm:data>
<rm:data field="events" size="varies" type="EVENT-TYPE<>">
- API events
+ interface events
</rm:data>
</rm:proto>
@@ -1134,11 +1135,11 @@
<para>
LOOKUP attempts to find the named object in the server's namespace,
- returning the object and API IDs of the object if it exists. Since
- an object isn't usable until its API has been DEFINEed, the client
- may request the API definition be provided as part of the LOOKUP
+ returning the object and interface IDs of the object if it exists. Since
+ an object isn't usable until its interface has been DEFINEed, the client
+ may request the interface definition be provided as part of the LOOKUP
response. For the same reason, the server may unilaterally decide
- to provide the API definition if it believes the client hasn't seen
+ to provide the interface definition if it believes the client hasn't seen
it yet.
</para>
@@ -1155,11 +1156,11 @@
<rm:data field="objectid" size="8" type="hyper">
ID of the object
</rm:data>
- <rm:data field="apiid" size="8" type="hyper">
- ID of the object's API
+ <rm:data field="interfaceid" size="8" type="hyper">
+ ID of the object's interface
</rm:data>
- <rm:data field="definition" size="varies" type="API-TYPE *">
- the definition of the object's API
+ <rm:data field="definition" size="varies" type="INTERFACE-TYPE *">
+ the definition of the object's interface
</rm:data>
</rm:proto>
@@ -1181,25 +1182,25 @@
<section><title>DEFINE</title>
<para>
- DEFINE requests a definition of the specified API ID.
+ DEFINE requests a definition of the specified interface ID.
</para>
<rm:proto name="DEFINE-REQUEST">
- <rm:data field="apiid" size="8" type="hyper">
- API ID
+ <rm:data field="interfaceid" size="8" type="hyper">
+ interface ID
</rm:data>
</rm:proto>
<rm:proto name="DEFINE-RESPONSE">
- <rm:data field="definition" size="varies" type="API-TYPE">
- the definition of the API
+ <rm:data field="definition" size="varies" type="INTERFACE-TYPE">
+ the definition of the interface
</rm:data>
</rm:proto>
<rm:errors op="DEFINE">
<rm:error code="EC-NOTFOUND">
- <literal>apiid</literal> isn't a known
- <acronym>API</acronym> ID.
+ <literal>interfaceid</literal> isn't a known
+ interface ID.
</rm:error>
<rm:error code="EC-NOMEM">
The server had insufficient resources to complete the
@@ -1228,7 +1229,7 @@
<rm:proto name="LIST-RESPONSE">
<rm:data field="names" size="varies" type="NAME-DATA<>">
- the definition of the API
+ the definition of the interface
</rm:data>
</rm:proto>
--- a/usr/src/doc/rad-dev/c-adr-idl.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-adr-idl.xml Tue Jun 19 17:37:39 2012 -0400
@@ -31,45 +31,49 @@
<section><title>Overview</title>
<para>
The top level element in an <acronym>ADR</acronym> definition
- document is an <sgmltag class='element'>interface</sgmltag>. The
- <sgmltag class='element'>interface</sgmltag> element has one
+ document is an
+ <sgmltag class='element'>api</sgmltag>. The
+ <sgmltag class='element'>api</sgmltag> element
+ has one
attribute, <sgmltag class='attribute'>name</sgmltag>, which is used
to name the output files. The element contains one or more derived
- type or <acronym>API</acronym> definitions. As there is no
- requirement that an <acronym>API</acronym> use derived types, there
+ type or interface definitions. As there is no
+ requirement that an interface use derived types, there
is no requirement that any derived types be specified in an
- interface document. To let consumers use the data typing defined
- by <acronym>ADR</acronym> for non-<acronym>API</acronym> purposes,
- there is no requirement that an <acronym>API</acronym> is defined
+ <acronym>API</acronym> document.
+ To let consumers use the data typing defined
+ by <acronym>ADR</acronym> for non-interface purposes,
+ there is no requirement that an interface is defined
either. (At least one thing, derived type or
- <acronym>API</acronym>, <emphasis>must</emphasis> be defined,
+ interface, <emphasis>must</emphasis> be defined,
though.)
</para>
<para>
As discussed in the previous chapter, three derived types are
- available for definition and use by <acronym>API</acronym>s: a
+ available for definition and use by interfaces: a
<type>structured</type> type can be defined with a <sgmltag
class='element'>struct</sgmltag> element, an
<type>enumeration</type> type can be defined with an <sgmltag
class='element'>enum</sgmltag> element, and a <type>union</type>
type can be defined with a <sgmltag
- class='element'>union</sgmltag> element. <acronym>API</acronym>s
- are defined using <sgmltag class='element'>api</sgmltag> elements.
- The derived types defined in an interface document are available
- for use by all <acronym>API</acronym>s defined in that document.
+ class='element'>union</sgmltag> element. Interfaces
+ are defined using <sgmltag class='element'>interface</sgmltag> elements.
+ The derived types defined in an <acronym>API</acronym>
+ document are available
+ for use by all interfaces defined in that document.
</para>
- <example><title>Skeleton interface document</title>
+ <example><title>Skeleton <acronym>API</acronym> document</title>
<programlisting><![CDATA[
-<interface xmlns="http://xmlns.oracle.com/radadr" name="example">
+<api xmlns="http://xmlns.oracle.com/radadr" name="example">
<struct>...</struct>
<struct>...</struct>
<enum>...</enum>
<union>...</union>
- <api>...</api>
- <api>...</api>
-</interface>
+ <interface>...</interface>
+ <interface>...</interface>
+</api>
]]></programlisting>
</example>
</section>
@@ -81,7 +85,7 @@
class='attribute'>name</sgmltag>. The <sgmltag
class='attribute'>name</sgmltag> is used when referring to the
<type>enumeration</type> from other derived type or
- <acronym>API</acronym> definitions. An <sgmltag
+ interface definitions. An <sgmltag
class='element'>enum</sgmltag> contains <emphasis>one or
more</emphasis> <sgmltag class='element'>value</sgmltag> elements,
one for each user-defined enumerated value. A <sgmltag
@@ -150,7 +154,7 @@
class='attribute'>name</sgmltag>. The <sgmltag
class='attribute'>name</sgmltag> is used when referring to the
<type>structure</type> from other derived type or
- <acronym>API</acronym> definitions. A <sgmltag
+ interface definitions. A <sgmltag
class='element'>struct</sgmltag> contains <emphasis>one or
more</emphasis> <sgmltag class='element'>field</sgmltag> elements,
one for each field of the <type>structure</type>. A <sgmltag
@@ -167,7 +171,8 @@
There are multiple ways to define the type of a field. If a field
is a plain base type, that type is defined with a
<sgmltag class='attribute'>type</sgmltag> attribute. If a field is
- a derived type defined elsewhere in the interface document, that
+ a derived type defined elsewhere in the <acronym>API</acronym>
+ document, that
type is defined with a <sgmltag class='attribute'>typeref</sgmltag>
attribute. If a field is an <type>array</type> of some type (base
or derived), that type is defined with a nested
@@ -266,31 +271,32 @@
</para>
</section>
- <section><title><acronym>API</acronym> definitions</title>
+ <section><title><acronym>Interface</acronym> definitions</title>
<para>
- An <acronym>API</acronym> definition has a name, <emphasis>zero or
+ An interface definition has a name, <emphasis>zero or
more</emphasis> version specifications, and <emphasis>one or
more</emphasis> attributes, methods, or events. An
- <acronym>API</acronym>'s name is defined with the <sgmltag
- class='element'>api</sgmltag> element's
+ interface's name is defined with the <sgmltag
+ class='element'>interface</sgmltag> element's
<emphasis>mandatory</emphasis> <sgmltag
- class='attribute'>name</sgmltag> attribute. This name isn't
- referred to elsewhere in the interface document; it is used only in
+ class='attribute'>name</sgmltag> attribute. This name is used
+ when referring to the (inherited) interface from other interface
+ defintions, as well as in
the server and various client environments. The other
- characteristics of an <acronym>API</acronym> are defined using
- child elements of the <sgmltag class='element'>api</sgmltag>
+ characteristics of an interface are defined using
+ child elements of the <sgmltag class='element'>interface</sgmltag>
element.
</para>
<section><title>Version</title>
<para>
- An <acronym>API</acronym> <emphasis>may</emphasis> define one
+ An interface <emphasis>may</emphasis> define one
version for each commitment level. It is not necessary to
define a version for every commitment level, but it is
recommended that one be specifed for every commitment level
- assigned to the features defined in the <acronym>API</acronym>
+ assigned to the features defined in the interface
(i.e. the features defined in the enclosing <sgmltag
- class='element'>api</sgmltag> element).
+ class='element'>interface</sgmltag> element).
</para>
<para>
@@ -320,7 +326,7 @@
<section><title>Methods</title>
<para>
- Each method in an <acronym>API</acronym> is defined by a
+ Each method in an interface is defined by a
<sgmltag class='element'>method</sgmltag> element. The name of
a method is defined by this element's
<emphasis>mandatory</emphasis> <sgmltag
@@ -381,7 +387,7 @@
<section><title>Attributes</title>
<para>
- Each attribute in an <acronym>API</acronym> is defined by a
+ Each attribute in an interface is defined by a
<sgmltag class='element'>property</sgmltag> element. The name
of an attribute is defined by this element's
<emphasis>mandatory</emphasis> <sgmltag
@@ -450,7 +456,7 @@
<section><title>Events</title>
<para>
- Each event in an <acronym>API</acronym> is defined by a
+ Each event in an interface is defined by a
<sgmltag class='element'>event</sgmltag> element. The name of
an event is defined by this element's
<emphasis>mandatory</emphasis> <sgmltag
@@ -474,14 +480,15 @@
Occasionally it is necessary to provide auxilliary information to a
specific <acronym>ADR</acronym> consumer. The
<acronym>ADR</acronym> <acronym>IDL</acronym> has a pragma
- mechanism that lets an interface creator specify that information
+ mechanism that lets an <acronym>API</acronym> creator specify that
+ information
in-line.
</para>
<para>
A pragma is specified with a <sgmltag
class='element'>pragma</sgmltag> child element of the <sgmltag
- class='element'>interface</sgmltag>. A <sgmltag
+ class='element'>api</sgmltag>. A <sgmltag
class='element'>pragma</sgmltag> has no child elements, and three
<emphasis>mandatory</emphasis> attributes. The <sgmltag
class='attvalue'>domain</sgmltag> attribute indicates which
--- a/usr/src/doc/rad-dev/c-adr-radadrgen.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-adr-radadrgen.xml Tue Jun 19 17:37:39 2012 -0400
@@ -25,8 +25,8 @@
generate <acronym>API</acronym>-specific language bindings for the
<command>rad</command> server and various client environments. It can
also generate documentation, and can audit changes to interfaces for
-consistency with their versions. See the <command>radadrgen</command> man
-page (<xref linkend="man.radadrgen" />) for details on all its options.
+consistency with their versions. See the <command>radadrgen(1)</command> man
+page for details on all its options.
</para>
<section><title>Code generation</title>
@@ -43,7 +43,7 @@
<para>
Because the <command>rad</command> server has complete knowledge of
- the <acronym>API</acronym>s and data types used, and that knowledge
+ the interfaces and data types used, and that knowledge
is explicitly shared with clients, it is possible for any client to
be written to manipulate those data types and communicate with the
server without the need for generated code. However, the
@@ -59,12 +59,12 @@
The first is a generic definitions-only context — perhaps
easiest to think of as a <quote>client</quote> context —
where only the code needed to manipulate datatypes and
- <acronym>API</acronym>s is created. The second is a
+ interfaces is created. The second is a
<command>rad</command>-specific context that, in addition to the
definitions generated in the generic context, generates server
definitions that include references to functions that form the
<emphasis>implementation</emphasis> of the
- <acronym>API</acronym>s.
+ interfaces.
</para>
</section>
--- a/usr/src/doc/rad-dev/c-adr.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-adr.xml Tue Jun 19 17:37:39 2012 -0400
@@ -25,7 +25,7 @@
takes the concepts discussed in the previous chapter and (contrary to
its name) makes them concrete by defining a formal
<acronym>IDL</acronym> for describing types and
-<acronym>API</acronym>s; by supplying a toolchain for operating on that
+interfaces; by supplying a toolchain for operating on that
<acronym>IDL</acronym>; and by providing libraries used by
<command>rad</command>, its extension modules, and its clients.
</para>
--- a/usr/src/doc/rad-dev/c-best-practices.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-best-practices.xml Tue Jun 19 17:37:39 2012 -0400
@@ -57,16 +57,16 @@
<para>
This section contains specific guidance on how to use RAD.
</para>
- <section id="best-practices.how.interface">
- <title>Interface Guidelines</title>
+ <section id="best-practices.how.api">
+ <title>API Guidelines</title>
<para>
- Designing a RAD interface requires judgement and the
+ Designing a RAD API requires judgement and the
application of domain knowledge.
</para>
<section id="best-practices.how.who">
<title>Target Audience</title>
<para>
- The users of the interface represent the primary
+ The users of the API represent the primary
goal driving the design. There are two broad
categories of consumers:
<itemizedlist>
@@ -306,14 +306,14 @@
<title>Naming</title>
<para>
- When naming an interface, API, or <link
+ When naming an API, interface, or <link
linkend="concepts-namespace.naming">object</link>, module developers have
broad leeway to choose names that make sense for their modules. However,
some conventions can help avoid pitfalls that might arise when retrieving
objects from the RAD server.
</para>
- <section>
+ <section id="best-practices.naming.object">
<title>Object names</title>
<para>
@@ -331,32 +331,34 @@
</informalexample>
<para>
- To distinguish a RAD interface from a "native" interface designed and
+ To distinguish a RAD API from a "native" API designed and
implemented for a specific language, it is customary to include a
- "<literal>rad.</literal>" component in the interface name.
+ "<literal>rad.</literal>" component in the API name.
</para>
<para>
With the goal of storing objects with names consumers would expect, it
- is recommended that interfaces, and the domains of the objects defined
+ is recommended that APIs, and the domains of the objects defined
within, share the same name. This makes the mapping between the two
easily identifiable by both the module consumer and module developer.
</para>
<para>
- With the same goal of simplicity, identifying an API object is made
- easier by adhering to a "<code>type</code>=<emphasis>api</emphasis>"
+ With the same goal of simplicity, identifying an interface object is made
+ easier by adhering to a
+ "<code>type</code>=<emphasis>interface</emphasis>"
convention within the object name.
</para>
<para>
- Applying both conventions, a typical interface will look like:
+ Applying both conventions, a typical API will look like:
</para>
- <programlisting format='linespecific'><interface xmlns="http://xmlns.oracle.com/radadr"
+ <programlisting format='linespecific'><api
+ xmlns="http://xmlns.oracle.com/radadr"
name="<emphasis role="strong">com.oracle.solaris.rad.zfs</emphasis>">
- <api name="<emphasis role="strong">ZPool</emphasis>">
+ <interface name="<emphasis role="strong">ZPool</emphasis>">
<summary>
zpool administration
</summary>
@@ -400,7 +402,7 @@
<manvolnum>1</manvolnum>
</citerefentry>
- uses the interface name as the Java package name by default.
+ uses the <acronym>API</acronym> name as the Java package name by default.
</para>
<section>
@@ -419,7 +421,7 @@
<listitem>
<para>
The base of the <link
- linkend="best-practices.naming.case.interface">interface</link>/domain
+ linkend="best-practices.naming.case.api">api</link>/domain
name. For a module describing an interface
"<emphasis>domain.prefix.base</emphasis>.xml", module spec files
should be named "<emphasis>base</emphasis>.xml", and the resulting
@@ -439,8 +441,8 @@
</listitem>
</varlistentry>
- <varlistentry id="best-practices.naming.case.interface">
- <term>interface</term>
+ <varlistentry id="best-practices.naming.case.api">
+ <term>api</term>
<listitem>
<para>
Reverse-dotted domain, all lowercase.
@@ -460,7 +462,7 @@
</varlistentry>
<varlistentry id="best-practices.naming.case.type">
- <term>api, struct, union, enum</term>
+ <term>interface, struct, union, enum</term>
<listitem>
<para>
Non qualified, camel case, starting with uppercase.
@@ -509,7 +511,7 @@
</varlistentry>
<varlistentry id="best-practices.naming.case.member">
- <term>api property and method, struct field, event</term>
+ <term>interface property and method, struct field, event</term>
<listitem>
<para>
Non qualified, camel case, starting with lowercase.
@@ -553,13 +555,15 @@
<itemizedlist>
<listitem>
<para>
- JMX: API-defined method names that resemble derived method names
+ JMX: Interface-defined method names that resemble derived
+ method names
</para>
<para>
A JMX MXBean Proxy has a single namespace for both methods defined
- by the API, and derived methods used for accessing attributes
- defined by the API. If a method defined by the API has a name and
+ by the interface, and derived methods used for accessing attributes
+ defined by the interface. If a method defined by the interface
+ has a name and
signature that is consistent with the JavaBeans-style naming of a
derived attribute-access method:
</para>
@@ -593,11 +597,11 @@
<section>
<title>Relationships to other agents</title>
</section>
- <section><title>Interface Design Examples</title>
+ <section><title>API Design Examples</title>
<para>
Given the tools described so far in this document, it should be
- clear how they can be combined to construct an interface with a
+ clear how they can be combined to construct an API with a
known design. Arriving at that design, however, can be a
challenge. There is seldom a single solution for a particular
problem, and of the available solutions there may not even be a
@@ -606,7 +610,7 @@
</para>
<section><title>User Management Example</title>
<para>
- Object/<acronym>API</acronym> granularity is subjective. Imagine
+ Object/<acronym>Interface</acronym> granularity is subjective. Imagine
an interface for managing a user. The user has a few modifiable
properties:
</para>
@@ -636,8 +640,8 @@
</tgroup></table>
<para>
- The API for managing this user might consist solely of a set of
- attributes corresponding the the above properties. Alternatively,
+ The interface for managing this user might consist solely of a set of
+ attributes corresponding to the above properties. Alternatively,
it could consist of a single attribute that is a
<type>structure</type> containing fields that correspond to the
properties (possibly more efficient if all properties are usually
@@ -699,8 +703,8 @@
<para>
A cleaner alternative would be to separate the global operations
from the user-specific operations and create two
- <acronym>API</acronym>s. The UserManagement object would use the
- global operations <acronym>API</acronym>:
+ interfaces. The UserManagement object would use the
+ global operations interface:
</para>
<programlisting>
@@ -710,7 +714,7 @@
<para>
… and a separate object for each user would implement the
- user-specific <acronym>API</acronym>:
+ user-specific interface:
</para>
<programlisting>
--- a/usr/src/doc/rad-dev/c-client-java.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-client-java.xml Tue Jun 19 17:37:39 2012 -0400
@@ -332,33 +332,55 @@
</para>
<informaltable>
- <tgroup cols='2'>
+ <tgroup cols='3'>
<thead>
- <row><entry>Element</entry><entry><command>/usr/bin/radadrgen</command> generates...</entry></row>
+ <row><entry>Element</entry><entry><command>radadrgen</command>-generated class</entry><entry>Description</entry></row>
</thead>
<tbody>
<row>
- <entry><code><api></code></entry>
+ <entry><code><interface> </code></entry>
+ <entry><emphasis>package.interface</emphasis>MXBean</entry>
<entry><code>MXBean</code> interface, implemented by object returned
by the RAD server</entry>
</row>
<row>
<entry><code><struct></code></entry>
- <entry>interface (always), implementation (if <option>-i</option> is
+ <entry><emphasis>package.struct</emphasis></entry>
+ <entry>struct interface</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><emphasis>package.struct</emphasis>Impl</entry>
+ <entry>struct implementation (if <option>-i</option> is
used)</entry>
</row>
<row>
<entry><code><union></code></entry>
- <entry>interface and implementation</entry>
+ <entry><emphasis>package.union</emphasis></entry>
+ <entry>union interface</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><emphasis>package.union</emphasis>_impl</entry>
+ <entry>union implementation</entry>
</row>
<row>
<entry><code><enum></code></entry>
- <entry>enums</entry>
+ <entry><emphasis>package.enum</emphasis></entry>
+ <entry>enum class</entry>
</row>
</tbody>
</tgroup>
</informaltable>
+ <para>
+ ...where <emphasis>package</emphasis> is determined from the
+ <code><api></code> name or a supplied
+ <link linkend="adr-idl.pragmas">pragma</link>.
+ See the section on <link linkend="best-practices.naming.object">object
+ naming</link> for details.
+ </para>
+
<section>
<title>Enums</title>
@@ -368,7 +390,7 @@
</para>
<programlisting><![CDATA[
-<interface xmlns="http://xmlns.oracle.com/radadr"
+<api xmlns="http://xmlns.oracle.com/radadr"
name="com.example.foo">
<enum name="Color">
@@ -377,7 +399,7 @@
<value name="Blue" />
</enum>
...
-</interface>
+</api>
]]></programlisting>
<para>
@@ -563,15 +585,15 @@
</section>
<section>
- <title>APIs</title>
+ <title>Interfaces</title>
<para>
- APIs are a module's <emphasis>raison d’être</emphasis>. For an
- <code><api></code> added to a module:
+ Interfaces are a module's <emphasis>raison d’être</emphasis>. For an
+ <code><interface></code> added to a module:
</para>
<programlisting><![CDATA[
-<api name="Population">
+<interface name="Population">
<property name="groupName" access="rw" type="string"/>
<property name="people" access="ro">
<list typeref="Person" />
@@ -579,7 +601,7 @@
<method name="add">
<argument typeref="Person" name="person" />
</method>
-</api>
+</interface>
]]></programlisting>
<para>
--- 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>
--- a/usr/src/doc/rad-dev/c-concepts-data.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-concepts-data.xml Tue Jun 19 17:37:39 2012 -0400
@@ -19,12 +19,12 @@
<section><title>Data</title>
<para>
-All data returned submitted to or obtained from <command>rad</command>
+All data returned, submitted to or obtained from <command>rad</command>
<acronym>API</acronym>s adheres to a strong typing system similar to
that defined by <citation>XDR</citation>. This makes it simpler to
define interfaces that have precise semantics, and makes server
extensions (which are written in C) easier to develop. Of course, the
-rigidity of the typing exposed to an <acronym>API</acronym>'s consumer
+rigidity of the typing exposed to an interface's consumer
is primarily a function of the client language and implementation.
</para>
@@ -162,7 +162,7 @@
compatible change, forfeiting some of the benefits offered by
<command>rad</command>'s versioning scheme. Excessive use of
fallback values will unnecessarily complicate the use and
- maintenance of a <command>rad</command> interface.
+ maintenance of a <command>rad</command> <acronym>API</acronym>.
</caution>
<para>
@@ -208,8 +208,9 @@
data cannot be <literal>NULL</literal>. Only data of type <type>opaque</type>,
<type>string</type>, <type>secret</type>, <type>array</type>,
<type>union</type> or <type>structure</type> may be declared nullable.
- Additionally, only <type>structure</type> fields and certain API
- (see below) types can be nullable. Specifically, <type>array</type>
+ Additionally, only <type>structure</type> fields and certain
+ <acronym>API</acronym> (see below) types can be nullable.
+ Specifically, <type>array</type>
data cannot be nullable (the <type>array</type> type is actually more
like a list than an array).
</para>
--- a/usr/src/doc/rad-dev/c-concepts-namespace.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-concepts-namespace.xml Tue Jun 19 17:37:39 2012 -0400
@@ -22,10 +22,10 @@
A <command>rad</command> server may provide access to several objects
that in turn expose a variety of different components of the system or
even third-party software. It isn't sufficient for a client to merely
-know that <acronym>API</acronym>s exist, or even that a specific
-<acronym>API</acronym> exists. A simple, special-purpose client needs
+know that interfaces exist, or even that a specific
+interface exists. A simple, special-purpose client needs
some way to identify the object implementing the correct
-<acronym>API</acronym> with the correct behavior, and an adaptive or
+interface with the correct behavior, and an adaptive or
general-purpose client needs some way to determine what functionality
the <command>rad</command> server has made available to it.
</para>
@@ -125,7 +125,7 @@
<term><literal>DESCRIBE</literal></term>
<listitem><para>
Requests a description of a specific object, by name. Returns
- an API description.
+ an interface description.
</para></listitem>
</varlistentry>
--- a/usr/src/doc/rad-dev/c-concepts.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-concepts.xml Tue Jun 19 17:37:39 2012 -0400
@@ -23,17 +23,16 @@
<section><title>Overview</title>
<para>
The three concepts most fundamental to <command>rad</command> are
-<acronym>API</acronym>s, objects that implement those
-<acronym>API</acronym>s, and the namespace in which those objects can
-be found and operated upon. An <acronym>API</acronym> is analogous to
-an interface in an object-oriented programming language. It defines
+<emphasis>interfaces</emphasis>, objects that implement those
+interfaces, and the namespace in which those objects can
+be found and operated upon. An interface defines
how a <command>rad</command> client can interact with an object. An
-object implements an <acronym>API</acronym>, providing a concrete
+object implements an interface, providing a concrete
behavior to be invoked when a client makes a request. Lastly, the
namespace acts as <command>rad</command>'s gatekeeper, associating a
name with each object, dispatching requests to the proper object, and
providing meta-operations that let the client make queries about what
-objects are available and what <acronym>API</acronym>s they implement.
+objects are available and what interfaces they implement.
</para>
<para>
--- a/usr/src/doc/rad-dev/c-intro.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-intro.xml Tue Jun 19 17:37:39 2012 -0400
@@ -90,7 +90,7 @@
support asynchronous calls due to limitations of the underlying
technology.
</para></footnote>.
-Third, the APIs exported by the server objects are fully inspectable.
+Third, the interfaces exported by the server objects are fully inspectable.
This facilitates interactive use, rich debugging environments, and
clients using dynamically-typed languages such as Python. Finally, in
addition to defining procedure calls, <command>rad</command> objects
@@ -128,9 +128,9 @@
</para></listitem>
<listitem><para>
<acronym>XML</acronym>-based <acronym>IDL</acronym>
- <acronym>ADR</acronym> supports formally defining interfaces.
+ <acronym>ADR</acronym> supports formally defining <acronym>API</acronym>s.
<acronym>IDL</acronym> compiler <command>radadrgen</command> generates
- code and analyzes compatibility of interface changes.
+ code and analyzes compatibility of <acronym>API</acronym> changes.
</para></listitem>
</itemizedlist></listitem>
--- a/usr/src/doc/rad-dev/c-modules.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/c-modules.xml Tue Jun 19 17:37:39 2012 -0400
@@ -29,9 +29,10 @@
</para>
-<section><title>Interface definition and implementation</title>
+<section><title>API definition and implementation</title>
<para>
-Though an interface can be constructed manually, it is much simpler to
+Though an <acronym>API</acronym> can be constructed manually,
+it is much simpler to
use <command>radadrgen</command> to generate the necessary type
definitions. If requested, <command>radadrgen</command> can also generate
stubs for the entry points referenced by the generated types.
@@ -42,7 +43,7 @@
All entry points take a pointer to the object instance and a
pointer to the internal structure for the method or attribute. The
former is essential for distinguishing different objects that
- implement the same API. The latter is theoretically useful for
+ implement the same interface. The latter is theoretically useful for
sharing the same implementation across multiple methods or
attributes, but isn't used and may be removed.
</para>
@@ -629,7 +630,7 @@
interested parties via events.
</para>
<example>
- An API has a method which returns a Task object. The method is
+ An interface has a method which returns a Task object. The method is
called installpkg and takes one argument, the name of the package
to install. This can be summarised as:
<funcsynopsis>
@@ -676,7 +677,7 @@
<function>cont_insert()</function> adds an object to the
namespace. In turn, objects are created by calling
<function>instance_create()</function> with a name, a pointer
- to the API the object implements, and a pointer to
+ to the interface the object implements, and a pointer to
object-specific callback data. For example:
</para>
@@ -688,7 +689,7 @@
<para>
<function>cont_insert_singleton()</function> is a convenience
- routine that creates an object instance for the specified API
+ routine that creates an object instance for the specified interface
with the specified name and adds it to the namespace. The
callback data is set to <constant>NULL</constant>.
</para>
--- a/usr/src/doc/rad-dev/rad-devguide.xml Tue May 22 04:45:02 2012 -0700
+++ b/usr/src/doc/rad-dev/rad-devguide.xml Tue Jun 19 17:37:39 2012 -0400
@@ -25,7 +25,9 @@
<xi:include href="c-client.xml" />
<xi:include href="c-modules.xml" />
<xi:include href="c-best-practices.xml" />
+<!--
<xi:include href="c-manpage.xml" />
+-->
<xi:include href="a-protocol-proc.xml" />
<xi:include href="b-references.xml" />
</book>