The common thing between the three feature types — methods, attributes, and events — is that they are named. All three feature types name exist in the same Interface namespace and must therefore be unique. You can not have both a method and an attribute called “foo”. This exclusion avoids the majority of conflicts that could arise when trying to naturally map these interface features to a client environment. As in the API namespace, features must not begin with “_rad”, since this is reserved for use by the RAD toolchain.
A method is a procedure call made in the context of the object it is called on. In addition to a name, a method may define a return type, can define zero or more arguments, and may declare that it returns an error, optionally with an error return type.
If a method does not define a return type, it returns no value. It is effectively of type void. If a method defines a return type and that type is permitted to be nullable, the return value may be defined to be nullable.
Each method argument has a name and a type. If any argument's type is permitted to be nullable, that argument may be defined to be nullable.
If a method does not declare that it returns an error, it theoretically cannot fail. However, because the connection to rad could be broken either due to a network problem or a catastrophic failure in rad itself, all method calls can fail with an I/O error. If a method declares that it returns an error but does not specify a type, the method may fail due to API-specific reasons. Clients will be able to distinguish this failure type from I/O failures.
Finally, if a method also defines an error return type, data of that type may be provided to the client in the case where the API-specific failure occurs. Error payloads are implicitly optional, and must therefore be of a type that is permitted to be nullable.
An attribute is metaphorically a property of the object. Attributes have the following characteristics:
A name
A type
A definition as read-only, read-write, or write-only
Like a method may declare that accessing the attribute returns an error, optionally with an a error return type
Reading a read-only or read-write attribute returns the value of that attribute. Writing a write-only or read-write attribute sets the value of that attribute. Reading a write-only attribute or writing a read-only attribute is invalid. Clients may treat attempts to write to a read-only attribute as a write to an attribute that does not exist. Likewise, attempts to read from a write-only attribute may be treated as an attempt to read from an attribute that does not exist.
If an attribute's type is permitted to be nullable, its value may be defined to be nullable.
An attribute may optionally declare that it returns an error, with the same semantics as declaring (or not declaring) an error for a method. Unlike a method, an attribute may have different error declarations for reading the attribute and writing the attribute.
Attribute names may not be overloaded. Defining a read-only attribute and a write-only attribute with the same name is not valid.
Given methods, attributes are arguably a superfluous interface feature. Writing an attribute of type X can be implemented with a method that takes one argument of type X and returns nothing, and reading an attribute of type X can be implemented with a method that takes no arguments and returns a value of type X. Attributes are included because they have slightly different semantics.
In particular, an explicit attribute mechanism has the following characteristics:
Enforces symmetric access for reading and writing read-write attributes.
Can be easily and automatically translated to a form natural to the client language-environment.
Communicates more about the nature of the interaction. Reading an attribute ideally should not affect system state. The value written to a read-write attribute should be the value returned on subsequent reads unless an intervening change to the system effectively writes a new value.
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 interface. In addition to a name, each event has a type.
Events have the following characteristics:
Sequential
Volatile
Guaranteed
A client can rely on sequential delivery of events from a server as long as the connection to the server is maintained. If the connection fails, then events will be lost. On reconnection, a client must resubscribe to resume the flow of events.
Once a client has subscribed to an event, event notifications will be received until the client unsubscribes from the event.
On receipt of a subscribed event, a client receives a payload of the defined type.