OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

sdo message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [sdo] SDO 3 CD review

Hello All,

Below are a few additional comments:

SDO Core Specification

Section 4.5.4
This:  "1) If neither T1 nor T2 is a DataType, then the implementation type (in Java, the instanceClass) may differ, or may be absent in on of the types."
Should be: 
"1) If neither T1 nor T2 is a DataType, then the implementation type (in Java, the instanceClass) may differ, or may be absent in one of the types."


SDO Java Specification

Section 2.1.2
This section contains some information that appears out of place:

Section 2.2.1
Much of the content here does not appear to be Java specific.

Section 2.3.1
Why is the following DataGraph method Java specific?
DataGraph.getType(String uri, String typeName) 

Section 2.6.1
This:  "core SOD specification"
Should be: 
"core SDO specification"


Radu Preotiuc-Pietro wrote:
20081208114339484.00000001084@RADUP02" type="cite">
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,

To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]