RE: [sdo] Re: SDO 3 CD review

["Radu Preotiuc-Pietro" <radu.preotiuc-pietro@oracle.com>]

Great. Here are a few more comments on the new stuff:

4.8 Is this section the best place for the two constants? They look decidedly out of place, but I guess once we decide to add a sentence saying that for illustration purposes the code examples are in Java, we can also say that there are these two constants etc
4.4.13 Who's P1?
4.4.14 "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" "Entity" is not defined in the spec, I think we should stick to DataObject for the spec prose. And, I think that saying  that a reference to an entity can be replaced with a reference to a type was not what was meant.
4.15 It feels like a discussion about HelperContexts has to precede the discussion about projection
5.3 We should be maintaining a list of spec-defined open content properties on Types and Properties and how to map those to/from Schema: xml-element, key, embeddedkey, keyType, orphan. We should  also have Schema definitions for them. Then, we need to specify the constraints in the dedicated chapter (6.4) (such as: orphan implies xml-element true, keyType implies some keys etc)
7.6.1 My bad, the two simple Schema types (MyGregorianCalendar and SKU) are not useless per se, because they are referenced from the other types. They are not illustrating anything special anymore.
8.2 "rendered as attributes"->"rendered as an attribute","whose type correspond"->"whose types correspond","key type of the referenced object"->"key type corresponding to the type of the property";  maybe the whole paragraph needs some re-wording
8.2 third example, change was not made
10 Do we need to review the SDO Path syntax to allow for function calls inside predicates?
11 What happened to my comment here? New issue is needed?
A I had some comments on references needed in the annex. Frank, did you not get to these or do you think the references are not needed?

Thanks,
Radu 

> -----Original Message-----
> From: Frank Budinsky [mailto:frankb@ca.ibm.com] 
> Sent: Monday, December 08, 2008 5:30 PM
> To: sdo@lists.oasis-open.org
> Subject: [sdo] Re: SDO 3 CD review
> 
> Hi Guys,
> 
> Attached is the latest version of the core spec. I've updated 
> to include the remaining issues (124 and 145), Ulf, Blaise, 
> and many of Radu's changes. The following issues from Radu 
> still need attention. I've grouped the issues under the name 
> who I think is best equiped to address it. We can discuss how 
> to proceed with them in tomorrow's call.
> 
> Ron:
> 
> 1.2 - Are the MOF2 XMI and EMOF references still appropriate? 
> [1] EMOF is actually never referenced in the rest of the doc 
> and [4]MOF2 is only referenced in a section that talks about 
> non-goals (and it is referenced as [2]), so at most it should 
> be given a correct reference name and included among the 
> non-normatives.
> 4.14.4 - I think the example has to be cleaned up to at least 
> remove the 1st person references
> 
> Bryan:
> 
> 4.1.4 - I don't think this is language-independent, but then 
> again, it is difficult to explain in a non-language-dependent way
> 4.1.12 - The isNull() and setNull() methods; when did we 
> introduce those?
> I can't remember, it could be me
> 4.3.7 - What happened to getChangedObjects()? What about 
> getOldValue()?
> 6.1 - The conversion rules between String and List are 
> missing, but I assume they are the same in every language 
> (part of the reason they were modeled after XMLSchema)
> 7.5.2 - The sentence ". In the case where Date and 
> java.lang.String are insufficient, sdox:dataType can be used 
> to override the datatype to one with a custom implementation 
> class." was left out. Was that intentional?
> 8.1 - If we disregard the "SDO Java types", then the two 
> cases in which "sdo:dataType" needs to be used are "Date" and 
> "Character"; maybe this warrants a new issue to be opened, 
> but I think it's fairly clear
> 12 - Again, I think conversions of List to String should be 
> kept because they are not Java-specific; there are plenty of 
> references to Lists throughout the core spec
> NOTE: I also added a few TODOs to update more diagrams. I 
> guess that's another TODO for Bryan :-)
> 
> Rick (or whoever is working on improving the key section(s):
> 
> 4.6.3 - Needs a better introduction than "A property marked 
> with sdo:key="true" is called a key property" What does it 
> mean for a property to be "marked with sdo:key"? At this 
> point the spec never talked in any detail about XSD to SDO 
> mapping, nor about open-content on Properties. I think part 
> of the section needs to be moved after the section that talks 
> about open-content (4.6.7) and the sample moved in the 
> Examples section (and the prefix changed to sdox probably)
> 7.3 - Do we want to add "key" here so that examples from 
> chapter 4 make sense?
> 7.4 -7.5 - How to specify an element/attribute as key and 
> examples should be moved here IMO
> 
> Thanks,
> Frank.
> 
> 
> 
> 
> 
> 
> "Radu Preotiuc-Pietro" <radu.preotiuc-pietro@oracle.com>
> 12/08/2008 11:43 AM
> Please respond to
> "radu.preotiuc-pietro@oracle.com" <radu.preotiuc-pietro@oracle.com>
> 
> 
> To
> Frank Budinsky/Toronto/IBM@IBMCA, "sdo@lists.oasis-open.org"
> <sdo@lists.oasis-open.org>
> cc
> 
> Subject
> SDO 3 CD review
> 
> 
> 
> 
> 
> 
> Hi Frank, everyone,
> 
> This is my list of comments, most of them have to do with the 
> core/java split. The Java portion of the specification, in 
> particular, needs some more work, because in some parts right 
> now is just a collection of disjoint sentences which were 
> removed from the core spec. The Java spec also has some 
> missing SDO 2.1.1 updates, as indicated below. On the other 
> hand, I have noticed some out-of-place things which also 
> exist in the current SDO 2.1.1 (marked accordingly), so I am 
> going to fix them in there too (if everyone agrees of course).
> 
> The SDO-core doc:
> Abstract - should be "to handle data" and there is an extra 
> space before "This document"
> 1.3 - Missing SDO 2.1.1 update - we have removed all the 
> links other than ibm, oracle and sap from the SDO 2.1.1 doc
> 1.2 - Are the MOF2 XMI and EMOF references still appropriate? 
> [1] EMOF is actually never referenced in the rest of the doc 
> and [4]MOF2 is only referenced in a section that talks about 
> non-goals (and it is referenced as [2]), so at most it should 
> be given a correct reference name and included among the 
> non-normatives.
> 2.3 - "Generating Java from XMLSchemas" row should be removed
>       "DataType Conversion Tables" row should be moved up
> 4.1.2 - "[...] can be a path expression based on a subset of 
> XPath" This is unnecessarily vague. It should point to the 
> chapter describing SDO path. (this is also a valid 2.1.1 comment)
> 4.1.4 - I don't think this is language-independent, but then 
> again, it is difficult to explain in a non-language-dependent way
> 4.1.12 - The isNull() and setNull() methods; when did we 
> introduce those?
> I can't remember, it could be me
> 4.1.13 - Table - first row - note; I don't think the note is 
> necessary, it needs to be removed (also a valid 2.1.1 comment)
> 4.3.5 - References to "XML path expressions" can now be 
> changed to "XPath expressions" (also a valid 2.1.1 comment)
> 4.3.7 - What happened to getChangedObjects()? What about 
> getOldValue()?
> 4.5.5 - Paragraph 2 - It should include a link to the chapter
> 4.5.8 - Second code example: why getString() and not get()
> 4.5.9 - getURI() is missing the parans (also in SDO 2.1.1)
> 4.6.3 - Needs a better introduction than "A property marked 
> with sdo:key="true" is called a key property" What does it 
> mean for a property to be "marked with sdo:key"? At this 
> point the spec never talked in any detail about XSD to SDO 
> mapping, nor about open-content on Properties. I think part 
> of the section needs to be moved after the section that talks 
> about open-content (4.6.7) and the sample moved in the 
> Examples section (and the prefix changed to sdox probably)
> 4.7.2 - Talks about Java a few times
> 4.8.4 - Reference to section 3.1.9 needs to be replaced with a link
> 4.8.6 - getTypes(URI: String): List should not be there
> 4.12.1 - formatting error, there should be 2 blocks of code
> 4.13.4 - getNamespace() should be getNamespaceURI()
> 4.14.4 - I think the example has to be cleaned up to at least 
> remove the 1st person references
> 5 - aliasName property should be String*
> 6.1 - The conversion rules between String and List are 
> missing, but I assume they are the same in every language 
> (part of the reason they were modeled after XMLSchema)
> 6.1.1,6.1.2 - Title of the chapters is obviously wrong (also 
> a valid 2.1.1
> comment) they should be: "6.1.1 Conversion from SDO type 
> Bytes to SDO type String" and "6.2.2 Conversion from SDO type 
> String to SDO type Bytes"
>     - Also there is a question if it makes sense to leave the 
> Date conversions out but keep the Bytes and Character conversions in
> 7.3 - Do we want to add "key" here so that examples from 
> chapter 4 make sense?
> 9.2.1 - Row 1, cell 2, there is a typo (also a valid 2.1.1 
> comment), it should be something like: "[URI] is the 
> (non-null) type.uri for the types defined by this Schema"
> 7.4 - "When creating a Property..." should not be bulleted
> 7.5.2 - The sentence ". In the case where Date and 
> java.lang.String are insufficient, sdox:dataType can be used 
> to override the datatype to one with a custom implementation 
> class." was left out. Was that intentional?
> 7.4 -7.5 - How to specify an element/attribute as key and 
> examples should be moved here IMO
> 7.6.1 - The "MyGregorianDate" and "SKU" types now have to be 
> removed altogether once their sdoj annotations have been 
> removed 8, table 2 - Why is the declaration for sdox prefix removed?
> 8.1 - Hm, really a "2.1.1 comment", the names of the XSD 
> types should not, of course, be capitalized
> 8.1 - If we disregard the "SDO Java types", then the two 
> cases in which "sdo:dataType" needs to be used are "Date" and 
> "Character"; maybe this warrants a new issue to be opened, 
> but I think it's fairly clear
> 8.2 - I think the third example is wrong 11, line 2886 - I 
> only now realize how strange this Note looks, for SDO 3 we 
> should seriously think about eliminating it.
> 12 - Again, I think conversions of List to String should be 
> kept because they are not Java-specific; there are plenty of 
> references to Lists throughout the core spec
> A1 - I have noticed a few times that references no longer 
> include the chapter #, which was actually useful to quickly 
> locate the reference
> A2 - Missing reference to chapter 11, "the datagraph" not 
> clear what it means.
> A3 - This should probably be moved to the java spec. It 
> should be "no change summary information [...]"
> 
> For the SDO-java doc:
> 2.1.2 - An SDO 2.1.1 update is missing here: "Specifically, 
> it is the same type as would be returned [...]" needs to be 
> removed and the following
> added: "When deriving a property type from a value, if the 
> value is an instance of DataObject, the type of the 
> DataObject (returned by
> DataObject.getType()) is used; otherwise a DataType with a 
> compatible instance class is used. Compatibility is based on 
> the mapping tables shown in section 8.1. For 
> java.lang.String, the SDO type "String" is used."
> 2.3.1 - The ChangeSummary.Setting interface and associated 
> methods need to be moved to the core spec, maybe as a 
> separate interface. We can then say that, for 
> backwards-compatibility, the interface is an inner interface 
> in Java; but it does not make sense to move all the 
> functionality in the Java spec, IMO
> 2.3.1 - "getValue() on setting is used instead of 
> getOldValue<T>" What does this mean?
> 2.5 - "The Java "extends" keyword maps to base types." What 
> does this mean?
> 2.7.1 - Maybe we can remove the INSTANCE field kludge from 
> the spec altogether; just leave it in the API for backwards-compat
> 2.7.2 - Why is create(Class) removed?
> 2.8.2 - Why is getType(Class) removed?
> 2.16.1 - Should be "HelperProvider Interface"
> 3, line 741 - JavaBeans needs to be introduced as a normative 
> reference and the link re-formatted.
> 3, line 763 - The link to another chapter should contain the 
> chapter number 3, line 773 - Replace "uses the sdo and sdoj 
> annotations" with "uses SDO-specific Schema annotations (see 
> chapter 7)" (also a valid SDO 2.1.1
> comment)
> 3.2 - "For the purchaseOrder XSD" needs a reference to that 
> XSD (also a valid SDO 2.1.1 comment)
> 5 - This is a strange chapter; it needs a reference to the 
> corresponding chapter in the core spec and a reiteration of 
> the main ideas.
> 6 - Missing SDO 2.1.1 update: remove the "DataGraph.getType[...]"
> reference
> 6.1 - Any reason the sentence "When code is generated with 
> accessors of type XXX, the behavior is identical to the 
> getXXX(property) and
> setXXX(property) methods." is removed from the end of the 
> second paragraph?
> 6.1, line 1031 - "[...] are additional types" is a good 
> example of how splitting the spec into two documents has 
> impacted the readability: it's not clear additional to what 
> if don't look at the 2.1.1 version of the spec. Taking some 
> sentences out of the paragraph makes it impossible to gather 
> any meaning from the remaining ones.
> 6.1 first table - Second row should be "byte or 
> java.lang.Byte" row 20 should be "List<String>" since we are 
> on JDK 1.5 now; also I don't see the reason why int would map 
> to either "int or java.lang.Integer" etc, after in the 
> previous paragraph we have said that an implementation can 
> choose either SDO Int or IntObject types; we may need to open 
> an issue on that, but in the meantime, this should not be changed
> 7.1 - Again, reference is needed to what principles exactly 
> are extended
> 7.1 - Missing SDO 2.1.1 update, the first cell in the first 
> row should be "Target namespace" instead of "Schema"
> 7.2 - Missing SDO 2.1.1 update: "Use sdox:name" instead of 
> "Use sdo:name"
> 7.2.2 - sdoj:instanceClass can have effect on what the SDO 
> type relationship is; we need to open issue to see if that 
> should continue to be the case and if so, then the table 
> needs a column for the SDO type as well
> 7.2.3 - Again missing the SDO 2.1.1 update that replaced uses 
> of "sdo:name" with "sdox:name"
> 8 - Also needs a bit of an introduction
> 8, line 1271 - "The simple type is based on the following" 
> needs to be rewritten; Come to think of it, the entire 
> chapter 8 needs to be rewritten (it is very short anyway)
> 9 - Remove this "chapter"
> 10 - Do we need this chapter in both the core and java specs? 
> I thought the idea behind the SDO data types was that they 
> are able to represent data in a language-independent manner. 
> If so, then everything should be in the core spec A - XMLDAS 
> reference, we should have removed this (also a 2.1.1 comment)
> A1 - "See section 13 for details" It's not section 13 
> anymore. It's [SDO] A9, line 1906 - This is not part of the 
> schema, there should be two separate XML blocks here
> 
> Thank you for getting this far,
> Radu
> 
> 
> 
> 
>