Re: [Java SDO] Sample re-arrangement
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=revrev=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); -
Re: [Java SDO] Sample re-arrangement
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
Re: [Java SDO] Sample re-arrangement
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
