Robbie,
I think that I will move the code that obtains a DataObject representing a
DataGraph into a spec snipet example with comments.
This is probably the right thing to do and I think we are on the same
wavelength, but just to be clear we have the same understanding of the
situation, the issue about the DataGraph is that the example in the spec
doesn't use the Java interface commonj.sdo.DataGraph. If you look at the
first lines of code it says ....
DataObject datagraph = XMLHelper.INSTANCE.load(stream).getRootObject();
DataObject company = datagraph.getDataObject("company");
I think that thesample should demonstrate the creation, and use of both
the DataGaph and
DataObject representation of the company.
so where you say "both" we actually have three situations, one where the
root element is the rootObject of a DataGraph, one where the root element is
the value of a Property of an instance of DataObject which models DataGraph
and one where the root element of the document is implicit in the instance
of DataObject.
whilst the DataGraph example in the spec might be valid it requires a lot of
understanding or explaining, especially when it is the first example
encountered. The user having seen the interface descriptions in the earlier
part of the spec is going to look at the first line of code and think that
there is a misprint, and that it should have said
DataGraph datagraph = ......
So I think it is possible to include that example, but I think if we do,
we should attempt to lead the reader into it at a later stage and to tell
the story of how to use a real Java DataGraph instance as well.
Cheers, Kelvin.
On 7/12/06, Robbie J Minshall <[EMAIL PROTECTED]> wrote:
Thanks very much for the comments Frank and Kelvin. I hope that this
message gets added to the same thread as the other messages , if not then
this is in reference to
http://www.mail-archive.com/tuscany-dev@ws.apache.org/msg04438.html.
I like the comment about being explicit about the context for each sample
and will do so whereever I have not in the javaDoc.
I have mixed feelings about how to handle the DataGraph. I think that the
sample should demonstrate the creation, and use of both the DataGaph and
DataObject representation of the company. This is because this particular
example in spec goes over the use of both and it would seem strange not to
cover both in the sample. Secondly, the area is so grey in the
specification that demonstating to the user how they can obtain an actual
DataGraph using the SDOUtil method or avoid it's use are both important. I
like the thought about simply encouraging the user to edit the code but
think that we would have to provide good example code in the commetns for
them to do so and perhaps we may as well just include working code.
I think that I will move the code that obtains a DataObject representing a
DataGraph into a spec snipet example with comments.
If people feel strongly that there should not be user input to determine
which is used ( DataObject vrs DataGraph ) for this specific example then
my preference would be to use the DataObject as this more closely follows
the spec example and also adhere's to the specification. If this path is
followed I would also create an additional sample which goes over various
means of obtaining a DataGraph from xml in the spec snipet section.
I will wait on some replies and then post an update. Thanks very much for
all the feedback - anyone else ?
Robbie.
--
Best Regards
Kelvin Goodson
