| Skip Navigation Links | |
| Exit Print View | |
|
Remote Administration Daemon Developer Guide Oracle Solaris 11.1 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Remote Administration Daemon Developer Guide Oracle Solaris 11.1 Information Library |
The APIs used by rad are defined using an XML-based IDL. The normative schema for this language can be found in /usr/share/lib/xml/rng/adr.rng.1. The namespace name is http://xmlns.oracle.com/radadr.
The top-level element in an ADR definition document is an api. The api element has one attribute, name, which is used to name the output files. The element contains one or more derived type or interface definitions. Because there is no requirement that an interface use derived types, there is no requirement that any derived types be specified in an API document. To enable consumers to use the data typing defined by ADR for non-interface purposes, there is no requirement that an interface is defined either. However, note that either a derived type or an interface must be defined.
Three derived types are available for definition and use by interfaces: a structured type that can be defined with a struct element, an enumeration type that can be defined with an enum element, and a union type that can be defined with a union element. Interfaces are defined using interface elements. The derived types defined in an API document are available for use by all interfaces defined in that document.
Example 3-1 Skeleton API document
<api xmlns="http://xmlns.oracle.com/radadr" name="example">
<struct>...</struct>
<struct>...</struct>
<enum>...</enum>
<union>...</union>
<interface>...</interface>
<interface>...</interface>
</api>
The enum element has a single mandatory attribute, name. The name is used when referring to the enumeration from other derived type or interface definitions. An enum contains one or more value elements, one for each user-defined enumerated value. A value element has a mandatory name attribute that gives the enumerated value a symbolic name. The symbolic name isn't used elsewhere in the API definition, only in the server and various client environments. How the symbolic name is exposed in those environments is environment-dependent. An environment offering an explicit interface to rad should provide an interface that accepts the exact string values defined by the value elements' name attributes.
An enum also contains zero or one fallback elements, indicating that the enumeration has a fallback value. The fallback element must appear after all value elements when present. Like value elements, a fallback element has a name attribute.
Some language environments support associating scalar values with enumerated type values, for example C. To provide richer support for these environments, ADR supports this concept as well. By default, an enumerated value has an associated scalar value 1 greater than the preceding enumerated value's associated scalar value. The first enumerated value is assigned a scalar value of 0. Any enumerated value element may override this policy by defining a value with the desired value. A value attribute must not specify a scalar value already assigned, implicitly or explicitly, to an earlier value in the enumeration.
value elements contain no other elements.
Example 3-2 Enumeration Definition
<enum name="Colors"> <value name="RED" /> <!-- scalar value: 0 --> <value name="ORANGE" /> <!-- scalar value: 1 --> <value name="YELLOW" /> <!-- scalar value: 2 --> <value name="GREEN" /> <!-- scalar value: 3 --> <value name="BLUE" /> <!-- scalar value: 4 --> <value name="VIOLET" value="6" /> <!-- indigo was EOLed --> <fallback name="UNKNOWN" /> <!-- for compatibility --> </enum>
Like the enum element, the struct element has a single mandatory attribute, name. The name is used when referring to the structure from other derived type or interface definitions. A struct contains one or more field elements, one for each field of the structure. A field element has a mandatory name attribute that gives the field a symbolic name. The symbolic name isn't used elsewhere in the API definition, only in the server and various client environments. In addition to a name, each field must specify a type.
You can define the type of a field in multiple ways. If a field is a plain base type, that type is defined with a type attribute. If a field is a derived type defined elsewhere in the API document, that type is defined with a typeref attribute. If a field is an array of some type (base or derived), that type is defined with a nested list element. The type of the array is defined in the same fashion as the type of the field: either with a type attribute, a typeref attribute, or another nested list element.
A field's value may be declared nullable by setting the field element's nullable attribute to true.
Note - Structure fields, methods return values, method arguments, attributes, error return values, and events all have types, and in the IDL, use identical mechanisms for defining those types.
Example 3-3 struct Definition
<struct name="Name">
<field name="familyName" type="string" />
<field name="givenNames">
<list type="string" />
</field>
</struct>
<struct name="Person">
<field name="name" typeref="Name" />
<field name="title" type="string" nullable="true" />
<field name="shoeSize" type="int" />
</struct>
The union element has the structure shown in the following example:
Example 3-4 union Definition
<!-- For booleans -->
<union name="boolunion" type="boolean">
<arm value="true" type="int" />
<arm value="false" typeref="banana" />
</union>
<!-- For enumerations -->
<enum name="enumname">
<value name="eval1" />
<value name="eval2" />
...
</enum>
<union name="enumunion" typeref="enumname">
<arm value="eval1">
<list type="string" />
<arm value="eval2" typeref="boolunion">
<default type="int" />
</union>
The type of the union discriminator is designated by the type attribute, or typeref attribute, and may only be a boolean or enumerated type. The names of unions are in the same namespace as enumerated types and structures, and must be unique. arms are identified with their associated value's name. One default arm may be specified for unions with an enumerated discriminator. When no arm is defined for a value and no default arm is defined, the arm for that value is void. The default arm is optional.
An interface definition has a name, zero or more version specifications, and one or more attributes, methods, or events. An interface's name is defined with the interface element's mandatory name attribute. This name is used when referring to the inherited interface from other interface definitions, as well as in the server and various client environments. The other characteristics of an interface are defined using child elements of the interface element.
An interface may define one version for each commitment level. You do not have to define a version for every commitment level, but one should be specified for every commitment level assigned to the features defined in the interface, that is, the features defined in the enclosing interface element.
A version is defined using a version element. The commitment level being versioned is defined by the mandatory stability attribute, which takes a value of committed, uncommitted, or private. The major and minor version numbers are non-negative integers, defined separately by the mandatory major and mandatory minor attributes.
Example 3-5 Version Definition
<version stability="committed" major="2" minor="1" />
Each method in an interface is defined by a method element. The name of a method is defined by this element's mandatory name attribute. The other properties of a method are defined by child elements of the method.
If a method has a return value, it is defined using a single result element. The type of the return value is specified in the same way the type is specified for a structure field. If no result element is present, the method has no return value.
If a method can fail for an API-specific reason, it is defined using a single error element. The type of an error is specified the same way the type is specified for a structure field. Unlike a structure field, an error need not specify a type — such a situation is indicated by an error element with no attributes or child elements. If no error element is present, the method will only fail if there is a connectivity problem between the client and the server.
A method's arguments are defined, in order, with zero or more argument elements. Each argument element has a mandatory name attribute. The type of an argument is specified in the same way the type is specified for a structure field.
Example 3-6 Method Definition
<struct name="Meal">...</struct>
<struct name="Ingredient">...</struct>
<method name="cook">
<result typeref="Meal" />
<error />
<argument type="string" name="name" nullable="true" />
<argument name="ingredients">
<list typeref="Ingredient" />
</argument>
</method>
Each attribute in an interface is defined by a property element. The name of an attribute is defined by this element's mandatory name attribute. The types of access permitted are defined by the mandatory access attribute, which takes a value of ro, wo, or rw, corresponding to read-only access, write-only access, or read-write access, respectively.
The type of an attribute is specified in the same way the type is specified for a structure field.
If access to an attribute can fail for an API-specific reason, it is defined using one or more error elements. An error element in a property may specify a for attribute, which takes a value of ro, wo, or rw, corresponding to the types of access the error return definition applies to. An error element with no for attribute is equivalent to one with a for attribute set to the access level defined on the property. Two error elements may not specify overlapping access types. For example, on a read-write property it is invalid for one error to have no for attribute (implying rw) and one to have a for attribute of wo — they both specify an error for writing.
The type of an error is specified the same way the type is specified for a method. It is identical to defining the type of a structure, with the exception that a type need not be defined.
Example 3-7 Attribute Definition
<struct name="PrivilegeError">...</struct>
<property name="VIPList" access="rw">
<list type="string" />
<error for="wo" typeref="PrivilegeError" />
<!-- Reads cannot fail -->
</property>
Each event in an interface is defined by a event element. The name of an event is defined by this element's mandatory name attribute. The type of an event is specified in the same way the type is specified for a structure field.
Example 3-8 Event Definition
<struct name="TremorInfo">...</struct> <event name="earthquakes" typeref="TremorInfo" />
Occasionally you need to provide auxiliary information to a specific ADR consumer. The ADR IDL pragma mechanism lets an API creator specify that information in-line.
A pragma is specified with a pragma child element of the api. A pragma has no child elements, and three mandatory attributes. The domain attribute indicates which consumer the pragma is intended for, and a name and a value specify a consumer-specific name/value pair.
The only supported pragma specifies a package for generated Java classes. The domain of this pragma is java and its name is package.
Example 3-9 Pragma Definition
<pragma domain="java" name="package" value="com.example" />
Example 3-10 Complete API Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<api xmlns="http://xmlns.oracle.com/radadr" name="example">
<pragma domain="java" name="package" value="com.example" />
<struct name="StringInfo">
<field type="integer" name="length" />
<field name="substrings">
<list type="string" />
</field>
</struct>
<struct name="SqrtError">
<field type="float" name="real" />
<field type="float" name="imaginary" />
</struct>
<enum name="Mood">
<value name="IRREVERENT" />
<value name="MAUDLIN" />
</enum>
<struct name="MoodStatus">
<field typeref="Mood" name="mood" />
<field type="boolean" name="changed" />
</struct>
<interface name="GrabBag">
<version major="1" minor="2" stability="private" />
<method name="sqrt">
<result type="integer" />
<error typeref="SqrtError" />
<argument type="integer" name="x" />
</method>
<method name="parseString">
<result typeref="StringInfo" nullable="true" />
<argument type="string" name="str" nullable="true" />
</method>
<property typeref="Mood" name="mood" access="rw">
<error for="wo" />
</property>
<event typeref="MoodStatus" name="moodswings" />
</interface>
</api>
|