Sounds good, we could do that in the package.html of the javadoc. What
about a matrix of samples versus features exercised? E.g. Columns of
"Sample1", "Sample2" etc and Rows of "Open Content", "Access via Sequence"
etc. That would help us develop the samples too, by highlighting the gaps.
We could do both, as this would be orthogonal to the java packaging. I think
the advantage of some kind of categorization at the packaging level is to
the user who is exploring a distribution by examining the file system.
I know there's no well defined measure of complexity, but this would be a
crude instrument that may prove useful; a novice could use it as a guide
of where to start and how to progress, and an experienced user would, I
imagine, fairly readily calibrate the sample's contents with the complexity
label. Whatever happens, I don't think the current packaging categorization
of where the material originally came from is very helpful, so I would
prefer to flatten the package structure rather than leave it as it is.
Another reason for wanting to remove the existing categorization is because
snippets from the SDO spec, and the examples in the SDO spec are not always
what we want to show to the user. They may make good sense in the context of
having read the surrounding spec material in depth, but I think our samples
need to strike a chord with the SDO user without the need to absorb chunks
of the spec. Some of my recent changes to samples have meant that code in
say the specCodeSnippets package bears a looser relationship to the spec
than it did before. I don't want to be constrained by the spec when I see
code that could be presented in a better way. We have also ended up with
samples in the different sections which demonstrate the same facets of SDO
in slightly different ways, and I think that that is confusing.
If there is strong feeling that basic, intermediate and advanced packages
are a bad way to go then I propose to flatten the package structure, and
then between us (any offers?) we'll create the kind of index that Haleh
suggested.
Regards, Kelvin.
On 02/07/07, haleh mahbod <[EMAIL PROTECTED]> wrote:
Kelvin,
As a user, I would like to see a general ample index file that briefly
explains what each sample does rather than the categorization that is
mentioned here since the terms basic, intermediate, etc. are not well
defined and are open to interpretation. Instead I would like to go to a
central location that I can get enough information to decide which sample
fits my requirements or decide for myself if I am ready to look at a
sample. For example,
1. 'sample name' demonstrates the following
a) create data object, update, retrieve
b) How to use change history
2. 'sample name' demonstrates the following
a)
b)
my 2 cents.. What do other users think?
Haleh
On 7/2/07, Mike Edwards <[EMAIL PROTECTED]> wrote:
>
> Kelvin,
>
> I think "basic" may read better than "novice", but otherwise this is a
> good idea.
>
> Yours, Mike.
>
> kelvin goodson wrote:
> > I just checked in another sample which I'd be happy to take feedback
on
> --
> > [1] (output appended as in my previous posts)
> >
> > I would like to rearrange the packages of the samples, as I think the
> > current arrangement is not very helpful to someone trying to explore
SDO
> > (specCodeSnippets, specExampleSecstion andotherSources). I have
> > recently been categorizing the samples with a flag to say whether they
> are
> > at the novice, intermediate or advanced level. I think perhaps this
> would
> > be a better way to package the samples too. So I propose to create the
> > packages
> >
> > org.apache.tuscany.samples.sdo.novice
> > org.apache.tuscany.samples.sdo.intermediate
> > org.apache.tuscany.samples.sdo.advanced
> >
> > and move all sample programs out of the current packages into one of
> these
> > new packages.
> >
> > The javadoc for the samples would still reference the original source
> > material where appropriate, so that information wouldn't be lost.
> > Comments?
> >
> > Regards,Kelvin.
> >
> > [1]
> >
>
http://svn.apache.org/viewvc/incubator/tuscany/java/sdo/sample/src/main/java/org/apache/tuscany/samples/sdo/MedicalScenario.java?view=markup
> >
> >
> >
> >
> > --------------------------------------------------------------
> > - Running with commentary level for a novice user -
> > - Edit the sample program's constructor argument to one from -
> > - COMMENTARY_FOR_NOVICE -
> > - COMMENTARY_FOR_INTERMEDIATE or -
> > - COMMENTARY_FOR_ADVANCED -
> > - in order to alter the level of commentary you are seeing -
> > --------------------------------------------------------------
> >
> >
>
-----------------------------------------------------------------------------------------------
> >
> > - Tuscany SDO Java Sample
> > org.apache.tuscany.samples.sdo.intermediate.MedicalScenario -
> > - This sample is aimed at a intermediate
> > user -
> >
>
-----------------------------------------------------------------------------------------------
> >
> >
> > --------------------------------------------------------
> > - In this execution of the sample we use Types created -
> > - using the SDO API -
> > --------------------------------------------------------
> >
> >
>
--------------------------------------------------------------------------------
> >
> > - The DataFactory associated with the scope that the types were
created
> > within -
> > - can be used to create an instance of the Person
> > Type -
> > -
> > -
> > - DataFactory dataFactory = scope.getDataFactory();
> > -
> > - DataObject person1 = dataFactory.create("www.example.org/people ",
> > "Person"); -
> >
>
--------------------------------------------------------------------------------
> >
> >
> >
>
-----------------------------------------------------------------------------
> >
> > - The setString() of dataObject method is used to set the properties
of
> the
> > -
> > - new Person DataObject, including a unique identifier reference value
> > -
> > - for the Person instance.
> > -
> > -
> > -
> > - person1.setString("id", "1");
> > -
> > - person1.setString("name", "Joe Johnson Snr.");
> > -
> > - person1.setString("gender", "male"););
> > -
> >
>
-----------------------------------------------------------------------------
> >
> >
> >
>
-----------------------------------------------------------------------------------------
> >
> > - An alternative approach to using the DataFactory directly to
> > create -
> > - all DataObjects is to use a top-down approach, where we create
> > the -
> > - root object for a data graph, and then use the
> createDataObject(String
> > propertyName) -
> > - method to create the contained DataObjects. Here we create the
> > overall -
> > - medical test DataObject, and then create the contained "referrals"
> > DataObject -
> > -
> > -
> > - DataObject test = dataFactory.create("www.example.org/MedicalTest",
> > "Test"); -
> > - DataObject referrals = test.createDataObject("referrals");
> > -
> >
>
-----------------------------------------------------------------------------------------
> >
> >
> >
>
--------------------------------------------------------------------------------
> >
> > - Now we can add the person we created earlier into the set of people
> who
> > have -
> > - been referred for this medical
> > test. -
> > -
> > -
> > - test.set("referrals",
> > referrals); -
> > - referrals.getList("person").add(person1);
> > -
> >
>
--------------------------------------------------------------------------------
> >
> >
> >
>
--------------------------------------------------------------------------------------
> >
> > - Let's take a look at how the current state of the datagraph is
> > rendered in
> > XML ... -
> >
>
--------------------------------------------------------------------------------------
> >
> >
> > <?xml version="1.0" encoding="ASCII"?>
> > <MedicalTest:test xmlns:MedicalTest="www.example.org/MedicalTest ">
> > <referrals>
> > <person name="Joe Johnson Snr." id="1" gender="male"/>
> > </referrals>
> > </MedicalTest:test>
> > -------------------------------------------------------------------
> > - The scenario unfolds and the Joe Johnson Snr. becomes a patient -
> > - -
> > - DataObject patients = test.createDataObject("patients"); -
> > - patients.getList("person").add(person1); -
> > -------------------------------------------------------------------
> >
> >
>
------------------------------------------------------------------------------
> >
> > - Having added Joe Johnson Snr. to the set of patients we can see
> > -
> > - the way that SDO preserves a single containment hierarchy within a
> > -
> > - datagraph. If we look at the XML rendering of the graph again, we
> will
> > -
> > - see that by adding him to the set of patients he has been removed
from
> > the
> > -
> > - containment property associated with the referrals set ...
> > -
> >
>
------------------------------------------------------------------------------
> >
> >
> > <?xml version="1.0" encoding="ASCII"?>
> > <MedicalTest:test xmlns:MedicalTest="www.example.org/MedicalTest ">
> > <referrals/>
> > <patients>
> > <person name="Joe Johnson Snr." id="1" gender="male"/>
> > </patients>
> > </MedicalTest:test>
> >
>
------------------------------------------------------------------------------
> >
> > - The 'Person' Type we are making use of here has been designed to be
> > -
> > - multi-purpose, in that the type has been declared to be 'Open'.
> > -
> > - That means that we can make use of 'Open Content' Properties
> > -
> > - (If the type system has been defined using an XML schema
> > -
> > - then these properties will derive from global elements)
> > -
> > - We can look up open content Properties using the TypeHelper
> > -
> > -
> > -
> > - Property conditionProperty =
> > scope.getTypeHelper().getOpenContentProperty(
> > -
> > - " www.example.org/MedicalTest", "condition");
> > -
> >
>
------------------------------------------------------------------------------
> >
> >
> >
>
---------------------------------------------------------------------------
> > - We can create a value of the appropriate Type for this
> open -
> > - content
> Property -
> >
>
- -
> > - DataObject condition = dataFactory.create(conditionProperty.getType
());
> -
> > - condition.setString("name", "Panar
> Syndrome"); -
> >
>
---------------------------------------------------------------------------
> >
> >
-----------------------------------------------------------------------
> > - If you ask a DataObject that has an 'Open' Type for its list of
-
> > - values associated with an open content Property, and the DataObject
-
> > - doesn't currently have any values for the Property, it will return
-
> > - an empty list. We can use the list to add values for the Property
-
> > -
-
> > - List conditions = person1.getList(conditionProperty);
-
> > - conditions.add(condition); -
> >
-----------------------------------------------------------------------
> >
> > ----------------------------------------------------------
> > - A further look at the data graph in XML form shows -
> > - the presence of the new condition Property's value ... -
> > ----------------------------------------------------------
> >
> > <?xml version="1.0" encoding="ASCII"?>
> > <MedicalTest:test xmlns:MedicalTest="www.example.org/MedicalTest">
> > <referrals/>
> > <patients>
> > <person name="Joe Johnson Snr." id="1" gender="male">
> > <MedicalTest:condition name="Panar Syndrome"/>
> > </person>
> > </patients>
> > </MedicalTest:test>
> > -----------------------------------------------------------------
> > - Having looked at the way SDO handles Open content -
> > - We now turn our attention to 'non-containment' relationships. -
> > - To do this we first create the set of people in the test that -
> > - constitute the blood relatives of patients -- 'relatives' -
> > - and define a new person to be Joe Johnson Snr's child. -
> > - -
> > - DataObject relatives = test.createDataObject("relatives"); -
> > - DataObject person2 = relatives.createDataObject("person"); -
> > - person2.setString("id", "2"); -
> > - person2.setString("name", "Joe Johnson Jnr."); -
> > - person2.setString("gender", "male"); -
> > -----------------------------------------------------------------
> >
> >
>
-------------------------------------------------------------------------
> > - Another quick look at the XML rendering of the graph confirms
> that -
> > - the set of relatives now includes Joe Johnson Jnr, but we haven't
yet
> -
> > - defined who he is related to, or how.
> -
> >
>
-------------------------------------------------------------------------
> >
> > <?xml version="1.0 " encoding="ASCII"?>
> > <MedicalTest:test xmlns:MedicalTest="www.example.org/MedicalTest">
> > <referrals/>
> > <patients>
> > <person name="Joe Johnson Snr." id="1" gender="male">
> > <MedicalTest:condition name="Panar Syndrome"/>
> > </person>
> > </patients>
> > <relatives>
> > <person name="Joe Johnson Jnr." id="2" gender="male"/>
> > </relatives>
> > </MedicalTest:test>
> > ---------------------------------------------------------------
> > - The Person type has a Property 'relative' -
> > - so we create a relative for Joe Johnson Snr. -
> > - -
> > - DataObject relation = person1.createDataObject("relative"); -
> > - relation.set("target", person2); -
> > - relation.set("relationship", "child"); -
> > ---------------------------------------------------------------
> >
> > ---------------------------------------------------------------------
> > - Now when we look at the XML rendering of the data graph -
> > - we can see that the action of setting the 'target' of the -
> > - relationship to Joe Johnson Jnr didn't displace him from the -
> > - set of 'relatives', because the 'target' Property is a -
> > - non-containment Property. This non-containment relationship -
> > - is reflected in the XML by the reference to the unique identifier -
> > - for Joe Johnson Jnr, "2" ... -
> > - -
> > - ... -
> > - <relative target="2" relationship="child"/> -
> > - ... -
> > ---------------------------------------------------------------------
> >
> > <?xml version="1.0" encoding="ASCII"?>
> > <MedicalTest:test xmlns:MedicalTest="www.example.org/MedicalTest ">
> > <referrals/>
> > <patients>
> > <person name="Joe Johnson Snr." id="1" gender="male">
> > <relative relationship="child" target="//@ test/@relatives/@
person.0
> "/>
> > <MedicalTest:condition name="Panar Syndrome"/>
> > </person>
> > </patients>
> > <relatives>
> > <person name="Joe Johnson Jnr." id="2" gender="male"/>
> > </relatives>
> > </MedicalTest:test>
> >
>
-------------------------------------------------------------------------------
> >
> > - Now that the graph is complete we can use the PrintDataGraph sample
> > utility -
> > - to reveal the full SDO nature of the final data
> > graph -
> >
>
-------------------------------------------------------------------------------
> >
> >
> >
> > DataObject: Type: www.example.org/MedicalTest#Test
> > Property referrals: -
> > DataObject: Type: www.example.org/people#PersonSet
> > Property person: - is not set
> >
> > Property patients: -
> > DataObject: Type: www.example.org/people#PersonSet
> > Property person: -
> > [
> > DataObject: Type: www.example.org/people#Person
> > Sequence: {
> > Property: condition:
> > DataObject: Type: www.example.org/MedicalTest#Condition
> > Property diagnosed: - is not set
> > Property name: - Panar Syndrome
> > Property: name: Joe Johnson Snr.
> > Property: id: 1
> > Property: gender: male
> > Property: relative:
> > DataObject: Type: www.example.org/people#Relative
> > Property relationship: - child
> > Property genetic: - is not set
> > Property target: - reference to:
/relatives/person[1]
> > }
> > ]
> >
> > Property relatives: -
> > DataObject: Type: www.example.org/people#PersonSet
> > Property person: -
> > [
> > DataObject: Type: www.example.org/people#Person
> > Sequence: {
> > Property: name: Joe Johnson Jnr.
> > Property: id: 2
> > Property: gender: male
> > }
> > ]
> >
> >
> >
>
-------------------------------------------------------------------------------------
> >
> > - End of sample
> > org.apache.tuscany.samples.sdo.intermediate.MedicalScenario -
> >
>
-------------------------------------------------------------------------------------
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
>
