Facets and Versioning Documentation Clarification

kalaxy

I'm trying to understand the use of facets. I've read over the facet and versioning chapter multiple times as well as the corresponding newsletter article and keep getting confused.

In 34.3 it discusses various ways to do versioning and the advantages and drawbacks to each type. 34.4 seems indicates that using facets is a better solution. Yet 34.5 shows an example of how one would use facets, but unless I'm really missing something, it uses "Versioning by Derivation" one of the types with drawbacks discussed in 34.3.

Can someone please clarify?

matthew

This is the code from the referenced page.

module Filesystem { // Original version
    // ...

    interface Directory extends Node {
        idempotent NodeSeq list();
        // ...
    };
};

module FilesystemV2 {
    // ...

    enum NodeType { Directory, File };

    class NodeDetails {
        NodeType type;
        string name;
        DateTime createdTime;
        DateTime accessedTime;
        DateTime modifiedTime;
        // ...
    };

    interface Directory extends Filesystem::Node {
       idempotent NodeDetailsSeq list();
       // ...
    };
};

The Directory type in FilesystemV2 is a different type from the one in Filesystem. The idea is that a client application can use Filesystem:: Directory or, if it is aware of the new type, FilesystemV2:: Directory (reached as a facet of the original type).

As far as I can see there is no versioning by derivation in this example. That would look similar to:

module Filesystem {
    // ...
    interface DirectoryV2 extends Directory {
       idempotent NodeDetailsSeq list();
       // ...
    };
};

michi

In the FilesystemV2 module, Directory extends Filesystem::Node, just as the Directory in the Filesystem module extends Filesystem::Node. What's happening here is not versioning by derivation. Instead, the version 2 definitions simply follow the version 1 convention, namely, that a Directory is-a Node.

In other words, a V2 Directory can be passed where a V1 Node is expected, just as a V1 Directory can be passed where a V1 Node is expected.

The new facet is FilesystemV2:: Directory. Note that his type is unrelated to Filesystem:: Directory: we have added a new type without disturbing the pre-existing Slice definitions in any way.

Clients can distinguish between V1 and V2 directories by doing the downcast. Everything else in the type system remains undisturbed.

Cheers,

Michi.

kalaxy

Thanks Matthew and Michi, your replies definitely help to clear the confusion.

So as I now understand, versioning by derivation isn't just about inheritance across versions (how I understood it before), but more about deriving a particular interface from the corresponding interface in a lower version.

The facet example can rightly extend the v2 directory from the v1 node because node did not change between versions. This is not versioning by derivation because the v2 directory has no relationship to the v1 directory, other then they extend from the same base. Any unchanged functionality from the v1 to v2 directory interface could be reusing code underneath but from the outside the two types remain distinct.

Furthermore if node had changed in v2, there would have had possibly been no cross version inheritance.

The two versions could exists as separate ice objects. However facets allow us to loosely tie them together and more easily make decisions based on that tie.

michi

kalaxy wrote: »

Thanks Matthew and Michi, your replies definitely help to clear the confusion.

So as I now understand, versioning by derivation isn't just about inheritance across versions (how I understood it before), but more about deriving a particular interface from the corresponding interface in a lower version.

Yes. It would be versioning by derivation if the V2 directory were to derived from the V1 directory.

Cheers,

Michi.