Re: [cmis] Proposal on how children are represented in hierarchical feeds

[Al Brown <albertcbrown@us.ibm.com>]

Cornelia,

Thank you for posting this.

I think there are two principles that are unfortunately conflicting here:
1. Keep it simple -> don't have redundant information or extra structures
2. Avoid special cases

My view is that:
1. This an interim solution until Atom figures out a way to do this in a standard way
2. This interim solution could live a couple of years until it is replaced
3. Clients have to understand our extension element and its semantics (whatever they may be)
4. Feed information does not provide any net new information not shared elsewhere on the enclosing atom entry
5. The feed information added 2kb out of 31kb (29 vs 31) on a very simple flat hierarchy which decreases the ability to quickly generate hierarchies (granted it is not much, but it is some)
6. The code to get info out of a feed seems simple (get title, updated, url) and reasonable to be duplicated
7. The majority of the code (processing entries, rendering feeds) can be modularized/refactored on a client and not monolithic as identified below
8.There does not seem to be a good reason to use feeds except for directive #2 above for clients
9. Given the above, I don't see a reason to make the interim solution more complex than necessary since the clients have to understand the semantics anyway of the cmis extension to use it.

There is a follow-on discussion Monday @ 7:30AM PST for those interested.

Best,
-Al


Al Brown
Emerging Standards and Industry Frameworks
CMIS: https://w3.tap.ibm.com/w3ki07/display/ECMCMIS/Home
Industry Frameworks: https://w3.tap.ibm.com/w3ki07/display/ECMIF/Home

Office 714 327 3453
Mobile 714 263 6441
Email albertcbrown@us.ibm.com
CONFIDENTIAL NOTICE: The contents of this message, including any attachments, are confidential and are intended solely for the use of the person or entity to whom the message was addressed. If you are not the intended recipient of this message, please be advised that any dissemination, distribution, or use of the contents of this message is strictly prohibited. If you received this message in error, please notify the sender. Please also permanently delete all copies of the original message and any attached documentation.

---07/09/2009 10:31:49 AM---Hello all.

From:	<Davis_Cornelia@emc.com>
To:	<cmis@lists.oasis-open.org>
Date:	07/09/2009 10:31 AM
Subject:	[cmis] Proposal on how children are represented in hierarchical feeds

---

Hello all.
 
We had a WG meeting on the subject this morning with
 
Al Brown
Ryan McVeigh
Julian Reschke
David Choy 
Cornelia Davis 
 
in attendance.
 
I committed to writing up my arguments for one option over the other.  I have done that in a new issue, # 329, so that the arguments and proposal don’t get lost in the email archive.  For your convenience, the argument is included here as well.  
 
We are meeting again on Monday at 7:30 Pacific to get final opinions so that we can close the issue in the Monday CMIS call.  If you are interested in the topic please chime in on the issue and/or join us Monday.
 
Thanks,
Cornelia
 
------------------------------------ issue #329 --------------------------------
 
As has been previously posted (http://lists.oasis-open.org/archives/cmis/200906/msg00347.html , http://lists.oasis-open.org/archives/cmis/200906/msg00371.html ), we are really down to two options on the format for representing hierarchy in CMIS.
 
What we refer to as option 3 is one where a folder entry has a cmis:children element that contains multiple atom:entry elements.  In outline form it looks like:
 
<atom:entry>
  <atom:title>Folder A</atom:title>
  ...
  <cmis:children>
    <atom:entry>
      <atom:title>Folder B</atom:title>
      …
    </atom:entry>
    … more atom entries …
  </cmis:children>
</atom:entry>
 
What we refer to as option 4 is one where a folder entry has a cmis:children element that wraps an atom:feed element that then contains multiple atom:entry elements.
 
<atom:entry>
  <atom:title>Folder A</atom:title>
  ...
  <cmis:children>
    <atom:feed>
      … a bunch of feed stuff …
      <atom:entry>
        <atom:title>Folder B</atom:title>
        …
      </atom:entry>
      … more atom entries …
    <atom:feed>
  </cmis:children>
</atom:entry>
 
Option 3 has at least two advantages over option 4:
•           Option 3 will have a smaller representation because it does not include the feed and the elements that are required of a feed (i.e. the “bunch of feed stuff” shown in option 4 above)
•           Option 3 results in a simpler server side implementation (see Al’s previous post on the subject)
 
In spite of these advantages I believe that option 3 has one significant disadvantage over option 4, and that is that we fundamentally have two different representations for the same resource requiring that client developers must have two implementations of a function depending on how the resource representation was retrieved.  Let me explain with an example.
 
Suppose a client developer has written some code to display certain things about a children collection – they want to display the name of the collection, the last updated value, a list of the children and they want to have a button that allows the user to select this location as a target of a new item creation.  This code executes against a feed retrieved via the URL to that child collection (URL could have been bookmarked for example).  The pseudocode for this is something like:
 
void processCollectionResource(feed childrenResource) {
 
  String title = childrenResource.getTitle();
  Date lastModified = childrenResource.getUpdated();
  // get the URL of the link relation with rel=”self”
  URL postURL = childrenResource.getLinkURL(“self”);
  Iterate childrenResource.getEntries() {
    // so something with each child 
    //      (this will be the same in both cases) 
  }
  // do something with all of this – render, etc.
 
}
 
Now the client realizes they want to do the same thing but against a set of children that are embedded within a hierarchical representation.  Let’s first look at the pseudocode for option 4.
 
There is code that has to parse the child collection out – it is something along the lines of:
 
feed childrenResource = folderResource.getChildren().getFeed();
processCollectionResource(childrenResource);
 
And the processCollectionResource method can be used as is.
 
For option 3, I need to pass in the folder resource and start parsing from there, because some of the information I need is at the folder and some of it is in the cmis:children element.  So I’d make a call something like:
 
processCollectionResourceEmbedded(folderResource);
 
And the new code to process this slightly different representation is:
 
void processCollectionResourceEmbedded(entry folderResource) {
 
  String title = folderResource.getTitle();
  Date lastModified = folderResource.getUpdated();
  // get the URL of the link relation with rel=”down”
  // NOTE!!!! that the code is less self contained here – self
  // is more direct than down
  URL postURL = folderResource.getLinkURL(“down”);
  Iterate folderResource.getChildren().getEntries() {
    // so something with each child 
    //      (this will be the same in both cases) 
  }
  // do something with all of this – render, etc.
 
}
 
Of course, the developer COULD have written the original method to take in a folder resource but then that says that the client shouldn’t write anything that goes against collection resource, instead they should write everything to go against the entry resource.  I think that is a bad constraint and one, that quite frankly, won’t be understood by a great many people.
 
Some might say that writing the second instantiation of this code is no big deal and sure, it’s not that hard.  But consider that I might have several such processor methods and now I have 2x bodies of code to test, maintain, etc. and we are required to do this because CMIS defines a proprietary container element instead of using the standardized container element of atom:feed.
 
Sure, embedding a feed duplicates some of the values from the folder entry to the feed, but I think that is a reasonable trade for the simplicity and elegance that it offers the client.
 
I strongly suspect that it is exactly this analysis that drive gData to embed an atom:feed inside of their children element.
 
So my closing arguments are these.  Let’s not define a proprietary container element – let’s use feeds to represent sets of entries.  Let’s not trade sever implementation ease for client burden.  And let’s pay the penalty of some duplication of feed properties for the benefits we get in return.
 
Thoughts?
 
Cornelia Davis
Senior Technologist
EMC Corporation, Office of the CTO
davis_cornelia@emc.com
p: 805.560.9039
m: 805.452.8941
f: 805.880.0390