You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by Robbie J Minshall <rj...@us.ibm.com> on 2006/06/29 20:48:15 UTC
SDO Samples
I am working on some samples for the SDO specification. Any thoughts or
comments on the following would be appreciated.
The first point of contact with SDO may or may not be the specification or
an introductory paper, regardless it of the first point of contact I would
hope that the samples are complete and usable enough that they can be used
in close conjunction with the spec, sdo papers, or on their own. With
this in mind it is very very important that the documentation generated (
I think the the project site is a good candidate here ) include a very
consumable tutorial as well as a good outline of the sample packaging and
usage so that the user can either use the samples on their own or in
reference to the paper or specification in their hand.
Currently the draft samples have a package that includes the code snipets
throughout the specification so that the user can read each section and
run or modify the very simple code snipet as it appears in the 2. 0
specification (these are essentially primatives). The next package
includes working samples from the Examples Section of the 2.0
Specification. The code in these sections is as close to the code in the
specific Example as possible with differences highlighted ( the sample you
reviewed is one example of this ). The third package includes working
samples from other sources, such as papers, with the intention that a user
could read the paper and then modify and execute the working sample
appropiately.
The current draft samples can simply be executed as a standAlone Java
application from the command line or from within eclipse.
The following is a sample of the style the Full Examples are written. I
am going to concentrate comments on this single example, then complete the
others in the same mann. If people have comments or suggestions please
let me know :
thanks,
Robbie Minshall.
Re: SDO Samples
Posted by Frank Budinsky <fr...@ca.ibm.com>.
>From below:
> choosing whether or not to wrap the root DataObject in a DataGraph. If
> there's not much gain I guess I'd prefer to take the wrapped route only,
+1
Thanks,
Frank.
kelvingoodson@gmail.com wrote on 06/30/2006 08:48:23 AM:
> Robbie,
>
> Thanks very much for the sample. Let me just clarify my understanding
if
> I may. I guess that for the 3 packages you mention above there would be
two
> styles of coding; the two packages that pick up code snippets and
samples
> from the spec would be broad coverage of the API, attempting to
succinctly
> cover as much as ground as possible, targeting primarily the reader who
is
> reasonably experienced in either the SDO spec or SDO coding or both.
This
> might be seen as a kind of reference source. The third package, drawing
on
> papers would be more educational, moving from novice to advanced
features,
> and using the API in a more natural sense, suggesting best practice for
> given scenarios. Is that reasonable? I'm not sure I have a full
> perspective on what resources we have to draw upon in the latter
category,
> although I know that there's some work in the pipeline in this respect.
>
> I'd be keen in all cases that there's no implicit context; e.g. if a set
of
> examples reflects code in the spec it should say so, up front in an
opening
> comment, with a link to the spec. If these code examples get sent around
and
> moved out of context of their distribution it would be good if there is
a
> link back to that source of info.
>
> With regards to your attached example, which is from the set of
examples in
> the spec, I think we need to deviate from the spec here. The reason I
say
> this is that it's not following the mainstream 2.0.1 concepts in that it
> talks about DataGraph but then creates a DataObject for which the Type
is
> one which models a data graph. I believe that for the 2.0.1 spec we
should
> be creating real instances of commonj.sdo.DataGraph. We can make use of
the
> SDOUtil class's loadDataGraph method, which has been provided as a
Tuscany
> extension particularly for the purpose of assisting the programmer to
> achieve this kind of wrapping (which more naturally fits into the
> responsibility of a DAS writer). There's quite a bit of thought going
into
> the 2.1 and 3 specs about the relationship between DataObject and
> DataGraph, and use of this method to abstract the detail of how the
data
> graph gets wrapped in an instance of DataGraph should help smooth the
way to
> adopting new aspects of forthcoming spec revisions.
>
> Frank queried the use of the shouldUseDataGraph() method, and I have
> concerns about this too. For my part I'd like to see as little control
code
> around the samples as possible. Perhaps this could be hived off to
> somewhere less visible just as you have done with the constants, or
maybe
> have a command line argument processing module similarly tucked away. An
> alternative which I rather like would be to include comments in the code
> which invite the reader to edit the code to observe the alternative
> behaviours.
>
> In think there's some missing code in this example, in that logging
needs to
> be turned on to get the serialization to include a populated change
> summary. I also wonder what is gained here by having the two paths of
> choosing whether or not to wrap the root DataObject in a DataGraph. If
> there's not much gain I guess I'd prefer to take the wrapped route only,
> but I'd be happy to be proved wrong here.
>
> Cheers, Kelvin.
>
> On 6/29/06, Frank Budinsky <fr...@ca.ibm.com> wrote:
> >
> > Robbie,
> >
> > Looks pretty good to me. I wonder if someone from the SCA team can
comment
> > on consistency of approach with other Tuscany and Apache samples. What
do
> > others think about using things like SdoSampleConstants. What about
the
> > shouldUseDataGraph() call to query the user to choose from two ways to
run
> > it?
> >
> > For this:
> >
> > // TODO: do you need to do this ?
> > employees.add(newEmployee);
> >
> > The answer is no. You would only need to add the newEmployee if you
> > created it by calling DataFactory.create(). Since you created it by
> > calling create() on the parent object, it's already attached, so this
call
> > to add will be a NOOP.
> >
> > Frank.
> >
> > Robbie J Minshall <rj...@us.ibm.com> wrote on 06/29/2006 02:48:15
PM:
> >
> > >
> > > I am working on some samples for the SDO specification. Any
> > > thoughts or comments on the following would be appreciated.
> > >
> > > The first point of contact with SDO may or may not be the
> > > specification or an introductory paper, regardless it of the first
> > > point of contact I would hope that the samples are complete and
> > > usable enough that they can be used in close conjunction with the
> > > spec, sdo papers, or on their own. With this in mind it is very
> > > very important that the documentation generated ( I think the the
> > > project site is a good candidate here ) include a very consumable
> > > tutorial as well as a good outline of the sample packaging and usage
> > > so that the user can either use the samples on their own or in
> > > reference to the paper or specification in their hand.
> > >
> > > Currently the draft samples have a package that includes the code
> > > snipets throughout the specification so that the user can read each
> > > section and run or modify the very simple code snipet as it appears
> > > in the 2. 0 specification (these are essentially primatives). The
> > > next package includes working samples from the Examples Section of
> > > the 2.0 Specification. The code in these sections is as close to
> > > the code in the specific Example as possible with differences
> > > highlighted ( the sample you reviewed is one example of this ). The
> > > third package includes working samples from other sources, such as
> > > papers, with the intention that a user could read the paper and then
> > > modify and execute the working sample appropiately.
> > >
> > > The current draft samples can simply be executed as a standAlone
> > > Java application from the command line or from within eclipse.
> > >
> > > The following is a sample of the style the Full Examples are
> > > written. I am going to concentrate comments on this single example,
> > > then complete the others in the same mann. If people have comments
> > > or suggestions please let me know :
> > >
> > >
> > >
> > > thanks,
> > > Robbie Minshall. [attachment "sample.zip" deleted by Frank
> > > Budinsky/Toronto/IBM]
> > >
---------------------------------------------------------------------
> > > To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> > > For additional commands, e-mail: tuscany-dev-help@ws.apache.org
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> > For additional commands, e-mail: tuscany-dev-help@ws.apache.org
> >
> >
>
>
> --
> Best Regards
> Kelvin Goodson
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: SDO Samples
Posted by kelvin goodson <ke...@thegoodsons.org.uk>.
Robbie,
Thanks very much for the sample. Let me just clarify my understanding if
I may. I guess that for the 3 packages you mention above there would be two
styles of coding; the two packages that pick up code snippets and samples
from the spec would be broad coverage of the API, attempting to succinctly
cover as much as ground as possible, targeting primarily the reader who is
reasonably experienced in either the SDO spec or SDO coding or both. This
might be seen as a kind of reference source. The third package, drawing on
papers would be more educational, moving from novice to advanced features,
and using the API in a more natural sense, suggesting best practice for
given scenarios. Is that reasonable? I'm not sure I have a full
perspective on what resources we have to draw upon in the latter category,
although I know that there's some work in the pipeline in this respect.
I'd be keen in all cases that there's no implicit context; e.g. if a set of
examples reflects code in the spec it should say so, up front in an opening
comment, with a link to the spec. If these code examples get sent around and
moved out of context of their distribution it would be good if there is a
link back to that source of info.
With regards to your attached example, which is from the set of examples in
the spec, I think we need to deviate from the spec here. The reason I say
this is that it's not following the mainstream 2.0.1 concepts in that it
talks about DataGraph but then creates a DataObject for which the Type is
one which models a data graph. I believe that for the 2.0.1 spec we should
be creating real instances of commonj.sdo.DataGraph. We can make use of the
SDOUtil class's loadDataGraph method, which has been provided as a Tuscany
extension particularly for the purpose of assisting the programmer to
achieve this kind of wrapping (which more naturally fits into the
responsibility of a DAS writer). There's quite a bit of thought going into
the 2.1 and 3 specs about the relationship between DataObject and
DataGraph, and use of this method to abstract the detail of how the data
graph gets wrapped in an instance of DataGraph should help smooth the way to
adopting new aspects of forthcoming spec revisions.
Frank queried the use of the shouldUseDataGraph() method, and I have
concerns about this too. For my part I'd like to see as little control code
around the samples as possible. Perhaps this could be hived off to
somewhere less visible just as you have done with the constants, or maybe
have a command line argument processing module similarly tucked away. An
alternative which I rather like would be to include comments in the code
which invite the reader to edit the code to observe the alternative
behaviours.
In think there's some missing code in this example, in that logging needs to
be turned on to get the serialization to include a populated change
summary. I also wonder what is gained here by having the two paths of
choosing whether or not to wrap the root DataObject in a DataGraph. If
there's not much gain I guess I'd prefer to take the wrapped route only,
but I'd be happy to be proved wrong here.
Cheers, Kelvin.
On 6/29/06, Frank Budinsky <fr...@ca.ibm.com> wrote:
>
> Robbie,
>
> Looks pretty good to me. I wonder if someone from the SCA team can comment
> on consistency of approach with other Tuscany and Apache samples. What do
> others think about using things like SdoSampleConstants. What about the
> shouldUseDataGraph() call to query the user to choose from two ways to run
> it?
>
> For this:
>
> // TODO: do you need to do this ?
> employees.add(newEmployee);
>
> The answer is no. You would only need to add the newEmployee if you
> created it by calling DataFactory.create(). Since you created it by
> calling create() on the parent object, it's already attached, so this call
> to add will be a NOOP.
>
> Frank.
>
> Robbie J Minshall <rj...@us.ibm.com> wrote on 06/29/2006 02:48:15 PM:
>
> >
> > I am working on some samples for the SDO specification. Any
> > thoughts or comments on the following would be appreciated.
> >
> > The first point of contact with SDO may or may not be the
> > specification or an introductory paper, regardless it of the first
> > point of contact I would hope that the samples are complete and
> > usable enough that they can be used in close conjunction with the
> > spec, sdo papers, or on their own. With this in mind it is very
> > very important that the documentation generated ( I think the the
> > project site is a good candidate here ) include a very consumable
> > tutorial as well as a good outline of the sample packaging and usage
> > so that the user can either use the samples on their own or in
> > reference to the paper or specification in their hand.
> >
> > Currently the draft samples have a package that includes the code
> > snipets throughout the specification so that the user can read each
> > section and run or modify the very simple code snipet as it appears
> > in the 2. 0 specification (these are essentially primatives). The
> > next package includes working samples from the Examples Section of
> > the 2.0 Specification. The code in these sections is as close to
> > the code in the specific Example as possible with differences
> > highlighted ( the sample you reviewed is one example of this ). The
> > third package includes working samples from other sources, such as
> > papers, with the intention that a user could read the paper and then
> > modify and execute the working sample appropiately.
> >
> > The current draft samples can simply be executed as a standAlone
> > Java application from the command line or from within eclipse.
> >
> > The following is a sample of the style the Full Examples are
> > written. I am going to concentrate comments on this single example,
> > then complete the others in the same mann. If people have comments
> > or suggestions please let me know :
> >
> >
> >
> > thanks,
> > Robbie Minshall. [attachment "sample.zip" deleted by Frank
> > Budinsky/Toronto/IBM]
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> > For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>
>
--
Best Regards
Kelvin Goodson
Re: SDO Samples
Posted by Fuhwei Lwo <fu...@bricemedia.com>.
Frank,
As a user learning SDO by examples, I prefer one file per one example so I don't need to be forced to understand example files directory structure and dependency.
Regards,
Fuhwei Lwo
Frank Budinsky <fr...@ca.ibm.com> wrote: Robbie,
Looks pretty good to me. I wonder if someone from the SCA team can comment
on consistency of approach with other Tuscany and Apache samples. What do
others think about using things like SdoSampleConstants. What about the
shouldUseDataGraph() call to query the user to choose from two ways to run
it?
For this:
// TODO: do you need to do this ?
employees.add(newEmployee);
The answer is no. You would only need to add the newEmployee if you
created it by calling DataFactory.create(). Since you created it by
calling create() on the parent object, it's already attached, so this call
to add will be a NOOP.
Frank.
Robbie J Minshall wrote on 06/29/2006 02:48:15 PM:
>
> I am working on some samples for the SDO specification. Any
> thoughts or comments on the following would be appreciated.
>
> The first point of contact with SDO may or may not be the
> specification or an introductory paper, regardless it of the first
> point of contact I would hope that the samples are complete and
> usable enough that they can be used in close conjunction with the
> spec, sdo papers, or on their own. With this in mind it is very
> very important that the documentation generated ( I think the the
> project site is a good candidate here ) include a very consumable
> tutorial as well as a good outline of the sample packaging and usage
> so that the user can either use the samples on their own or in
> reference to the paper or specification in their hand.
>
> Currently the draft samples have a package that includes the code
> snipets throughout the specification so that the user can read each
> section and run or modify the very simple code snipet as it appears
> in the 2. 0 specification (these are essentially primatives). The
> next package includes working samples from the Examples Section of
> the 2.0 Specification. The code in these sections is as close to
> the code in the specific Example as possible with differences
> highlighted ( the sample you reviewed is one example of this ). The
> third package includes working samples from other sources, such as
> papers, with the intention that a user could read the paper and then
> modify and execute the working sample appropiately.
>
> The current draft samples can simply be executed as a standAlone
> Java application from the command line or from within eclipse.
>
> The following is a sample of the style the Full Examples are
> written. I am going to concentrate comments on this single example,
> then complete the others in the same mann. If people have comments
> or suggestions please let me know :
>
>
>
> thanks,
> Robbie Minshall. [attachment "sample.zip" deleted by Frank
> Budinsky/Toronto/IBM]
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: SDO Samples
Posted by Frank Budinsky <fr...@ca.ibm.com>.
Robbie,
Looks pretty good to me. I wonder if someone from the SCA team can comment
on consistency of approach with other Tuscany and Apache samples. What do
others think about using things like SdoSampleConstants. What about the
shouldUseDataGraph() call to query the user to choose from two ways to run
it?
For this:
// TODO: do you need to do this ?
employees.add(newEmployee);
The answer is no. You would only need to add the newEmployee if you
created it by calling DataFactory.create(). Since you created it by
calling create() on the parent object, it's already attached, so this call
to add will be a NOOP.
Frank.
Robbie J Minshall <rj...@us.ibm.com> wrote on 06/29/2006 02:48:15 PM:
>
> I am working on some samples for the SDO specification. Any
> thoughts or comments on the following would be appreciated.
>
> The first point of contact with SDO may or may not be the
> specification or an introductory paper, regardless it of the first
> point of contact I would hope that the samples are complete and
> usable enough that they can be used in close conjunction with the
> spec, sdo papers, or on their own. With this in mind it is very
> very important that the documentation generated ( I think the the
> project site is a good candidate here ) include a very consumable
> tutorial as well as a good outline of the sample packaging and usage
> so that the user can either use the samples on their own or in
> reference to the paper or specification in their hand.
>
> Currently the draft samples have a package that includes the code
> snipets throughout the specification so that the user can read each
> section and run or modify the very simple code snipet as it appears
> in the 2. 0 specification (these are essentially primatives). The
> next package includes working samples from the Examples Section of
> the 2.0 Specification. The code in these sections is as close to
> the code in the specific Example as possible with differences
> highlighted ( the sample you reviewed is one example of this ). The
> third package includes working samples from other sources, such as
> papers, with the intention that a user could read the paper and then
> modify and execute the working sample appropiately.
>
> The current draft samples can simply be executed as a standAlone
> Java application from the command line or from within eclipse.
>
> The following is a sample of the style the Full Examples are
> written. I am going to concentrate comments on this single example,
> then complete the others in the same mann. If people have comments
> or suggestions please let me know :
>
>
>
> thanks,
> Robbie Minshall. [attachment "sample.zip" deleted by Frank
> Budinsky/Toronto/IBM]
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org