Naming Guidelines

When naming an API, interface, or object, 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.

Object Names

The domain portion of rad object names follows a reverse-dotted naming convention that prevents collisions in rad's flat object namespace. This convention typically resembles a Java package naming scheme:

com.oracle.solaris.rad.zonemgr
com.oracle.solaris.rad.usermgr
org.opensolaris.os.rad.ips
...

To distinguish a rad API from a native API designed and implemented for a specific language, include a "rad." component in the API name.

With the goal of storing objects with names consumers would expect, APIs, and the domains of the objects defined within them, should share the same name. This practice makes the mapping between the two easily identifiable by both the module consumer and module developer.

With the same goal of simplicity, identifying an interface object is made easier by adhering to a "type=interface" convention within the object name.

Applying both conventions, a typical API will look like the following example.

    <api  xmlns="http://xmlns.oracle.com/radadr"
       name="com.oracle.solaris.rad.zonemgr">
      <version major="1" minor="0"/>
      <interface name="ZoneInfo"> <!-- Information about the current zone  -->
      <property name="name" access="ro" type="integer"/>

          ...

        </interface>
</api>

Within the module, the API appears as follows:

int
_rad_init(void)

    {
    ...
          adr_name _t *zname = adr_name_vcreate(MOD_DOMAIN, 1, "type", "ZoneInfo");
          conerr_t cerr = rad_cont_insert_singleton(&rad_container, zname, &interface_ZoneInfo_svr);
          adr_name_rele(zname);
 

         if (cerr != CE_OK) {
             rad_log(RL_ERROR, "failed to insert module in container");
             return(-1);
         }
        return (0);
}

On the consumer side (Python), the API appears as follows:

import rad.connect as radcon
import rad.bindings.com.oracle.solaris.rad.zonemgr as zonemgr

# Create a connection and retrieve the ZoneInfo object
with radcon.connect_unix() as rc:
    zinfo = rc.get_object(zonemgr.ZoneInfo())
    print zinfo.name

Case

In an effort to normalize the appearance of like items across development boundaries, and to minimize the awkwardness in generated language-specific interfaces, several case strategies have been informally adopted.