[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: SDO 3 CD review
Hi Frank, I have updated the references in the sdo-java doc and also removed the capitalization for Java primitive types from section 6.1 and XSD types from section 7.3. I have added section number for the "DataHelper" section, it was missing. There are a few things outstanding, but we can take care of them post-CD1. My proposal would be to remove all the references to the INSTANCE fields from the spec, but leave them in the Java code potentially, to avoid any compatibility problems. 8 - ". If the Types also have a javaPackage specified then the additional sdoj:package attribute will be present in the generated schema declaration." This part is not clear to me. I don't think that Type has such a "javaPackage" property. That, however, is not a new issue, it exists in 2.1.1 as well, therefore we don't have to fix it now. Radu > -----Original Message----- > From: Frank Budinsky [mailto:frankb@ca.ibm.com] > Sent: Wednesday, December 10, 2008 7:42 PM > To: radu.preotiuc-pietro@oracle.com > Cc: sdo@lists.oasis-open.org > Subject: Re: SDO 3 CD review > > Hi Radu, > > I've updated the Java spec to address your issues and a few > of my own and attached the latest version below. The only > things I didn't address are the refrerence issues: > > 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) > > Can you update those ones? > > > > 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 > > > > > > > Thank you for getting this far, > Radu > > > > >
sdo-java-3.0-spec-wd04-121308.doc
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]