Title: RE: [sdo] Re: SDO 3 CD review
Hello All,
See my (late) comments below:
4.11.8 Orphan Serialization
Serializing an SDO data graph using the XMLHelper.save() method may result in an error in the event that the graph includes noncontainment references to DataObjects which are not also reachable via some containment reference (i.e., the graph is not closed). To av a oid such serialization errors, one or more elements in the corresponding XML schema may be annotated with the sdox:orphanHolder attribute to indicate that it should be used to serialize orphan objects, instead of generating an error.
Additionally I would say 'orphan object' is not defined properly. The sentence suggests that the orphan object is the object which is referenced in the data graph to be serialized by noncontainment references only. From Ron's mail http://www.oasis-open.org/apps/org/workgroup/sdo/email/archives/200805/msg00015.html I would add: Each orphan object is serialized as part of the containment tree in which it is located, and any DataObjects referenced but not contained in this tree must also be included among the( DataGraph’s) orphans, so that the transitive closure is obtained.
7.2 Generating static SDOs from an XSD
These principles apply when generating static SDOs from an XSD:
1. SDO does not specify any name any mangling but enables and sometimes requires name overrides through annotations.
Best regards,
Ulf
-----Original Message-----
From: Frank Budinsky [mailto:]
Sent: Monday, December 08, 2008 11:30 PM
To:
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" <>
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
