Extending enums in IDL

[Stephan Bergmann]

On 11/23/2016 12:04 PM, Jan Holesovsky wrote:
> But you caught my interest now - so if I understand that correctly, it
> is not a terrible breakage what's going on here: The client just gets an
> unknown value; ie. the same thing as when we add a constant to the IDL,
> and return this unknown new value - right?

No, there are differences between (incompatibly) extending an UNOIDL 
enum and (compatibly) extending a UNOIDL constants group; both technical 
and contractual differences:

The Java UNO runtime represents UNOIDL enum values as non-null 
references to specific Java class instances (where those classes are 
derived from com.sun.star.uno.Enum).  The bytecode generated for those 
classes contains functions that map from enum integer values (as 
obtained through the UNO bridges) to instances of those classes.  For 
invalid values, that bytecode happens to return null references (it 
could also throw exceptions, say).  So Java code confronted with an 
extended UNOIDL enum will likely throw NullPointerExceptions and fail.

And in other languages like C++ too, client code can rely on the 
contract that a published UNOIDL enum will not change and have code like

   switch (e) { // exhaustively cover all cases
   case E1: ...;
   case E2: ...;
   case E3: ...;
   default: std::abort();
   }

that will fail when the enum does change.

(Whether the consequences of such an incompatible change are considered 
dramatic enough to forbid the change is another matter.  Forbidding such 
a change and installing an alternative solution can have negative 
consequences too, so the pros and cons need to be weighed.)

On the other hand, a UNOIDL constant group is just that---a group of 
named constants.  Extending it, by definition, does not have 
compatibility implications.  A constant group is typically not used in 
isolation:  There is some concept that is represented (in method 
parameters and return values, struct members, etc.) by some UNOIDL 
integer type, and, for convenience, the supported values and their 
meanings are bundled in a constant group.  The places in .idl files that 
use that concept (by declaring method parameters and return values, 
struct members, etc. of that underlying integer type) will carry 
documentation pointing at the constant group, and will (implicitly or 
explicitly) state that the set of supported values is not fixed and can 
expand over time.

For client code that means:  When consuming such an integer value it 
must be prepared to be presented with a value it does not know.  And 
when producing such an integer value it must be prepared that any 
consumer does not know the value.  Code written in such a way that it 
does not support those requirements is broken.