In the end I went for both approaches [1]. In order to get the external documentation I instrumented each of the samples with some data about what it does, and then wrote a DocumentSamples java utility that extracts this data from the programs. This has allowed me to produce an HTML document that has two indices, one that shows what each sample does, and the other that shows which samples cover particular areas. I checked in a version of this file in the commit [1].
Regards, Kelvin. [1] http://svn.apache.org/viewvc?view=rev&rev=553460 On 04/07/07, Mike Edwards <[EMAIL PROTECTED]> wrote:
Folks, Having a central place with detailed descriptions of the samples in an organized fashion is a great idea. But this has nothing to do with the structuring on disk, in my opinion. Some folks will read the detailed docs. Others will simply get the code and start playing. For the latter folk, the simple / intermediate / advanced split is a crude guide, but useful for all that. It will also help sample writers think about the kind of sample that they are building - just how much prior knowledge and experience is required in order to tackle the sample? Thinking about samples in terms of graded steps is a very good idea. Cover the basics in one, add features in another and get into the rocket science in yet a third. Yours, Mike. haleh mahbod 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] >> >> > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
