Re: [cmis-comment] on property definitions / query object resolving / andothers

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

Gregor,

Thank you for reviewing CMIS specification.

>Required tag vs. "MUST be set on the object vs. read-only
>=========================================================
>First of all, I was also a bit confused on the meaning of the "required" tag. E.g. "createdBy", "creationDate" etc. should be always >required on the level of the data model. It seems, that the "required" tag is defined on API level and not on persistency / repository >level, i.e. the application programmer is not enforced to (or must not) set this value. In my opinion, this distinction is not clearly >defined. Moreover, the "updateability" tag with read_only defines the same on the API level (=> must not set on API level) so that I would >prefer to have the properties like creationDate etc as required instead of the comment "MUST be set on the object".
>
>However, "MUST be set on the object" is listed also in (2.1.4.3.3) for those tag which "always have a value"
The idea was that for those system properties ("createdBy', "creationDate", etc) the system/server/repository MUST always return those properties with non-empty values when an object is requested and the property filter does not exclude them.  The required is more from a UI/data quality perspective and identifies the properties that MUST contain a valid value by the client on creates, updates, and checkin operations.  The wording should be clarified.

>Small errata in description of atom entries for result sets
>==============================================================
>
>5462 The feed returned MUST contain a set of atom entries representing the result set from the query.
>
>5464 The atom entries should contain the bare minimum necessary for Atom compliance [RFC4287]. The
>5465 atom entries MUST contain the CMIS extension element (cmis:object) containing the properties specified
>5466 by the query in the select clause of the query statement.
>
>=> I guess "cmisra:object" instead of "cmis:object" would be correct.
Yes, I agree. This should be cmisra:object.  I will update this in the subversion repository for release after the current public review.


>How to provide Object-related information in Queries which do not result in list of objects?
>============================================================================================
>Though the virtual relational mapping of the CMIS data model is an interesting approach, it causes some confusion to me when I looked >deeper into the SQL syntax and the Atom(Pub) mapping. The result of the SQL query is not a list of (queryable) objects but just a relation >of properties ("pseudo objects"). Since JOINs are allowed, the resulting relation may contain properties from different objects in one row.
>
>Let's take the following sample from the spec:
>
>2464 SELECT Y.CLAIM_NUM, X.PROPERTY_ADDRESS, Y.DAMAGE_ESTIMATES
>2465 FROM POLICY AS X JOIN CLAIMS AS Y ON ( X.POLICY_NUM = Y.POLICY_NUM )
>2466 WHERE ( 100000 = ANY Y.DAMAGE_ESTIMATES )
>
>How to resolve
>- includeAllowableActions
>- includeRelationships
>- renditionFilter
>in this case?
>Is it always empty because the SELECT clause does not refer to one object per row?
>Is it the intersection (or union) of all objects which are virtually part of the row?
>Or it is not allowed to use includeAllowableActions etc. in such a query (i.e. error status code will be returned)
Yes, since the select clause contains properties from more than one object instance, those flags are not available. I believe, but would have to validate, that document specifies throwing an error in that case.

Please see lines (3908-3980) in the svn version.  It has this text:

· Enum includeRelationships: See section ý2.2.1.2.2 Relationships.
o Note: For query statements where the SELECT clause contains properties from only one virtual table reference (i.e. referenced object-type), any value for this enum may be used. If the SELECT clause contains properties from more than one table, then the value of this parameter MUST be “none”.
· String renditionFilter: See section ý2.2.1.2.4 Renditions.
o If the SELECT clause contains properties from more than one table, then the value of this parameter MUST not be set.
· Boolean includeAllowableActions: See section ý2.2.1.2.6 Allowable Actions.
o Note: For query statements where the SELECT clause contains properties from only one virtual table reference (i.e. referenced object-type), any value for this parameter may be used. If the SELECT clause contains properties from more than one table, then the value of this parameter MUST be “FALSE”.

Since the spec states MUST, I believe the server should throw an exception in those conditions even though it is not stated.

>In general, this query approach may cause problems with permission control (when to check what ACLs?). 
How so?  ACL's and security must always be respected.  It is expected that the results returned are the ones the user has authorization to see.  Traditionally ECM has in the past offered 'secured' and 'unsecured search'.  Secured is what is commonplace today where security is respected as part of search and acl/security model is checked.  


>Is it a design goal that the CMIS REST binding provides only a subset of the CMIS functionality?
No, it is desired that all CMIS functionality be provided through the REST/AtomPub binding. It takes time to adjust to a resource-based model from a services orientation.

>================================================================================================
>I do not find any create methods and also e.g. discardCheckout is not provided (maybe I am blind to see)
This is cancelCheckout functionality. This can be done by performing a delete on the Private Working Copy (PWC) resource. 

>I guess there have been several discussion on this topic but I do not find any explanation in chapter 3 that the RESTful binding does not >support any service and operation of part I. In contrast, chapter 4 for the WS binding explicitly states that "ALL services and operations >defined in part I of the CMIS specification are presented in this Web Services binding." (line 9372)

>I am not a friend of RESTful services in case the service has no RESTful style (but this is another discussion). Therefore, I would >appreciate when the CMIS REST binding focuses only on a subset of the functionality, BUT this circumstance should be clearly mentioned - >Which is not so far.
There is a section in the document that states the discrepencies from the domain model.  Please see section section 3.19:

The following services are not exposed in this binding:

· getRenditions: This is exposed as part of getObject

· getProperties: This is exposed as part of getObject

· createDocumentFromSource: This is not exposed in this binding except as the client saving the resource and resubmitting it without the cmis:objectId.

· Setting ACL on Create or Checkin operations

o This is currently not possible with the REST binding. The Create or Checkin operation must be performed first, then the dependent resource, ACL, must be retrieved and updated.
· setContentStream: This does not return the new object id and change token as specified by the domain model. This is not possible without introducing a new HTTP header.

· deleteContentStream: This does not return the new object id and change token as specified by the domain model. This is not possible without introducing a new HTTP header.

· checkOut: This does not return whether or not content was copied. This is not possible without introducing a new HTTP header.

>By the way, the introduction does not even mention the WebService binding (ok, nobody reads the introduction typically...)
Interesting point.

2 The Content Management Interoperability Services (CMIS) ReSTful AtomPub binding specification
3 defines a specification based on AtomPub that can be used by applications to work with one or more
4 Content Management Repositories.
>This is fixed in the public review that will come out shortly.

Thanks for all the feedback!
-Al

Al Brown
Office 714 327 3453
Mobile 714 251 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.

"JOERIS, Gregor" ---01/26/2010 06:34:56 AM---Hi! I like to provide some comments on CMIS as well - even if I am a bit late. I studied the CMIS v0

From:	"JOERIS, Gregor" <gregor.joeris@ser.de>
To:	"cmis-comment@lists.oasis-open.org" <cmis-comment@lists.oasis-open.org>
Date:	01/26/2010 06:34 AM
Subject:	[cmis-comment] on property definitions / query object resolving / and others

---

Hi!

I like to provide some comments on CMIS as well - even if I am a bit late. I studied the CMIS v0.5 draft sometimes ago and had no time to look at v1.0 so far. I really appreciate the work done by the OAIS TC and the progress from 0.5 to 1.0!

Maybe some of my comments are valuable either (otherwise it's just for the archive):


Required tag vs. "MUST be set on the object vs. read-only
=========================================================
First of all, I was also a bit confused on the meaning of the "required" tag. E.g. "createdBy", "creationDate" etc. should be always required on the level of the data model. It seems, that the "required" tag is defined on API level and not on persistency / repository level, i.e. the application programmer is not enforced to (or must not) set this value. In my opinion, this distinction is not clearly defined. Moreover, the "updateability" tag with read_only defines the same on the API level (=> must not set on API level) so that I would prefer to have the properties like creationDate etc as required instead of the comment "MUST be set on the object".

However, "MUST be set on the object" is listed also in (2.1.4.3.3) for those tag which "always have a value"



Small errata in description of atom entries for result sets
==============================================================

5462 The feed returned MUST contain a set of atom entries representing the result set from the query.

5464 The atom entries should contain the bare minimum necessary for Atom compliance [RFC4287]. The
5465 atom entries MUST contain the CMIS extension element (cmis:object) containing the properties specified
5466 by the query in the select clause of the query statement.

=> I guess "cmisra:object" instead of "cmis:object" would be correct.


How to provide Object-related information in Queries which do not result in list of objects?
============================================================================================
Though the virtual relational mapping of the CMIS data model is an interesting approach, it causes some confusion to me when I looked deeper into the SQL syntax and the Atom(Pub) mapping. The result of the SQL query is not a list of (queryable) objects but just a relation of properties ("pseudo objects"). Since JOINs are allowed, the resulting relation may contain properties from different objects in one row.

Let's take the following sample from the spec:

2464 SELECT Y.CLAIM_NUM, X.PROPERTY_ADDRESS, Y.DAMAGE_ESTIMATES
2465 FROM POLICY AS X JOIN CLAIMS AS Y ON ( X.POLICY_NUM = Y.POLICY_NUM )
2466 WHERE ( 100000 = ANY Y.DAMAGE_ESTIMATES )

How to resolve 
- includeAllowableActions
- includeRelationships
- renditionFilter
in this case?
Is it always empty because the SELECT clause does not refer to one object per row?
Is it the intersection (or union) of all objects which are virtually part of the row?
Or it is not allowed to use includeAllowableActions etc. in such a query (i.e. error status code will be returned)

In general, this query approach may cause problems with permission control (when to check what ACLs?). 


Is it a design goal that the CMIS REST binding provides only a subset of the CMIS functionality?
================================================================================================
I do not find any create methods and also e.g. discardCheckout is not provided (maybe I am blind to see)

I guess there have been several discussion on this topic but I do not find any explanation in chapter 3 that the RESTful binding does not support any service and operation of part I. In contrast, chapter 4 for the WS binding explicitly states that "ALL services and operations defined in part I of the CMIS specification are presented in this Web Services binding." (line 9372)

I am not a friend of RESTful services in case the service has no RESTful style (but this is another discussion). Therefore, I would appreciate when the CMIS REST binding focuses only on a subset of the functionality, BUT this circumstance should be clearly mentioned - Which is not so far.
 
By the way, the introduction does not even mention the WebService binding (ok, nobody reads the introduction typically...)

2 The Content Management Interoperability Services (CMIS) ReSTful AtomPub binding specification
3 defines a specification based on AtomPub that can be used by applications to work with one or more
4 Content Management Repositories.


Best regards
Gregor


Dr. Gregor Joeris | Product Manager  
SER Solutions Deutschland GmbH
Innovationspark Rahms | D-53577 Neustadt/Wied
Tel: +49 (0)2683 984-352 | Fax: +49 (0)2683 984-222
gregor.joeris@ser.de | www.ser.de
SER Solutions Deutschland GmbH * Innovationspark Rahms *  D-53577 Neustadt/Wied




-- 
This publicly archived list offers a means to provide input to the
OASIS Content Management Interoperability Services (CMIS) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: cmis-comment-subscribe@lists.oasis-open.org
Unsubscribe: cmis-comment-unsubscribe@lists.oasis-open.org
List help: cmis-comment-help@lists.oasis-open.org
List archive: http://lists.oasis-open.org/archives/cmis-comment/
Feedback License: http://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: http://www.oasis-open.org/maillists/guidelines.php
Committee: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=cmis