Logical Type Model
The logical type model of the remote framework is relatively simple and straightforward. It consists of four primitive scalar types and two compound types. It is not meant to represent any kind of object-oriented structure directly. It's only purpose is to provide a logical representation of the kinds of structured data which will commonly be transmitted by the remote framework.
Primitive types
The four primitive scalar types in the logical type model are as follows:
Null | Your standard null value |
Integer | Any integer, positive or negative |
Real | Any real number |
String | A Unicode character string |
Since we are describing a logical, theoretical type model here, there are no explicit bounds on the size of the integer, real, and string types. (There is, of course, a bound on the size of the null type, since there is only a single possible null value.) However, the remote methods are allowed to place additional semantic constraints on values in each type; for instance, declaring that a returned integer value will always fit within a standard signed 32-bit field. This implies that unless a transfer protocol can also express values of boundless size, the protocol will implicitly limit the set of remote methods that can be used by a server-client pair. (For instance, a transfer protocol which can only transmit 32-bit integers will not be able to properly communicate with a method which returns a 64-bit integer value.)
Compound types
In addition to the four primitive types, there are two compound types in the type model:
Array | An ordered sequence of values |
Hash | An unordered dictionary of key-value pairs |
These compound types are relatively straightforward. Arrays and hashes are heterogeneous: the individual elements of an array or hash do not all have to be of the same type. Compound types can be nested; an array can contain another array or hash, and vice versa. Like the primitive types, there is no implicit bound of the size of an array or hash.
Also like the primitive types, remote methods can, and usually will, place additional constraints on the form and content of an array or hash, by specifying the types of each element and/or the size of the value. However, neither of these concepts are represented directly in the type model. Therefore, arrays and hashes with incorrect sizes or inappropriately typed contents cannot be detected automatically by remote method dispatch code; these error conditions must be handled and signalled explicitly by the code which implements the remote method.
Another thing to be aware of is ordering -- arrays are ordered, hashes are not. Any transfer protocol must maintain the order of any array which it encodes, but is free to permute the values in a hash if necessary. A remote method is allowed to specify that the ordering of a returned list is arbitrary and meaningless, but this arbitrary ordering must still be maintained by the transfer protocol.
Error conditions
Remote methods are also able to signal any error conditions which arise during their execution. These are handled by exception results, which a remote framework client must be able to receive and interpret. Currently, exceptions are merely string values; these strings contain the human-readable description of the error which occurred.
We are investigating the possibility of adding a more strongly-typed exception system to the logical type model. This exception system would provide, at the very least, some kind of exception identifier which would be easier for remote framework and application code to interpret. However, this capability does not exist as of the 2.2 version of the OME remote framework.