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:]
> Sent: Wednesday, December 10, 2008 7:42 PM
> To:
> Cc:
> 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" <>
> 12/08/2008 11:43 AM
> Please respond to
> "" <>
>
>
> To
> Frank Budinsky/Toronto/IBM@IBMCA, ""
> <>
> 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
>
>
>
>
>
