ISSUE 119: Projection and Keys

["Barack, Ron" <ron.barack@sap.com>]

Title: ISSUE 119: Projection and Keys

Use Cases for Keys and Projection
We begin with a motivating use case.
Domain models tend to be larger and complex than the views used by individual clients. Moreover, when going from a large server-side model, it is necessary to define the scope of the data which should be transmitted to a remote client. The boundaries of the data which should be transmitted in a single packet must somehow be defined. On the other hand, the door must be left open for clients to further explore the model in succeeding calls to the server.

Imagine a service that returns an Employee object. In the domain model, Employee has a refence to Department, and Department in turn has a list of all Employees. If we define the transmission packet to be the transient closure reachable from Employee, then we can never send a single employee, we will always send the complete list of employees in the department.

Our approach is to use keys to represent the boundary points in a transmission packet. It is assumed that clients that wish to explore the model beyond these boundaries will be able to use the keys to somehow perform lookups, but the API through which this is done is out-of-scope for SDO (being more of a DAS issue).

As an example, we can imagine that the server has a SDO type system in which Employee has a property with type Department. In the client's type system, however, the corresponding property has type {commonj.sdo}string. This value would represent the identity of the Department. The basic functionality we wish to achive is to allow projection between these two HelperContexts.

Keys and Projection
A type and its keyType are compatible with each other.  That mean, an object with a reference to an entity in one context can be projected onto an object with a reference to the key type in another context.

We illustrate this with an example.

HelperContext #1

Type Employee
* property - id (Integer) - KEY
* property - name (String)
* property - direct-report (List of Employee)

is compatible with the metamodel

HelperContext #2

Type Employee
* property - id (Integer) - KEY
* property - name (String)
* property - direct-report (List of Integer)

Here we see the type of the direct-report property has been replaced in the second HelperContext with the corresponding key type.

The projection from an entity to its key has some important semantic differences when compared with projection between entities.  Projection between entities creates a new view of the same underlying data.  By contrast, a key does not represent a view, but rather a reference to an entity in the underlying data model.  When working with different views of the same underlying data, it is natural that changes in one view are reflected in all other views.  By contrast, changing the value of a key changes the target of the reference rather than the value of the key property in the referenced data object.  When projecting from an entity to a key, a new instance of the key is always created.  By contrast, when we project from entity to entity, we get the same number of objects in the target HelperContext that we had in the source HelperContext.

We illustrate with an example.  Note that the example uses containment relationships in both contexts.  This is done for clarity, since it allows an XML representation of the data.  The use-case, however, is stronger when the contexts have different (or perhaps no) containment structures.  Imagine the following data in HelperContext #1

<employee id="11">
        <name>Foo Bar</name>
        <direct-report id="21">
                <name>Jane Doe</name>
        </direct-report>
        <direct-report id="31">
                <name>Jim Jones</name>
        </direct-report>
        <direct-report id="22">
                <name>John Smith</name>
        </direct-report>
</employee>
After projecting to HelperContext #2, we have the following data
<employee id="11">
        <name>Foo Bar</name
        <direct-report>21</direct-report>
        <direct-report>31</direct-report>
        <direct-report>22</direct-report>
</employee>
If we imagine the client changes the list of direct reports, so that the second item in the list has value “41” instead of “31”, then the meaning of the change is not that the employee with name “Jim Jones” now has a new ID, but that “Jim Jones” has been replaced by another employee.

On projecting from context 2 back into context 1, the instance of Employee with id="22" would be detached from the Employee with id="11" (tracked as a delete in the ChangeSummary if applicable). Also a new Employee with id="41" would be created and added as a direct report to the Employee with id="11" (tracked as a create in the ChangeSummary if applicable).  The created entity has default values for all properties other than the key fields.  Projecting this data from context 2:

<employee id="11">
        <name>Foo Bar</name
        <direct-report>21</direct-report>
        <direct-report>41</direct-report>
        <direct-report>22</direct-report>
</employee>
Into context 1 yields:
<employee id="11">
        <name>Foo Bar</name>
        <direct-report id="21">
                <name>Jane Doe</name>
        </direct-report>
        <direct-report id="41"/>
        <direct-report id="22">
                <name>John Smith</name>
        </direct-report>
</employee>
Before the specification goes final, I think we want to add a further API so that users can specify additional logic so that, using the key, the appropriate entity can by found, eg, using an EntityManager.  The API used to add the resolver will be dependent on the resolution to ISSUE 134.  Therefore, for the CD, I believe we should specify this default behavior, leaving the door open to adding a further API.  If anyone is interested in the API that has previously proposed, you may find it detailed here: 

http://www.oasis-open.org/apps/org/workgroup/sdo/email/archives/200806/msg00033.html
Best Regards,
Ron