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 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


sdo-core-3.0-spec-wd02-081208.doc



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