Documentation

[Jean-Sebastien Delfino <js...@apache.org>]

With all the recent changes that went into our code base the last few 
weeks, some of our documentation is getting a little out of date / not 
in sync anymore with the code. I started to look at the readmes of the 
samples and I'm going to adjust them.

In addition, I think we need some more documentation of some of the key 
aspects of Tuscany, to help people get involved, extend or use the 
Tuscany runtime. We could use our Wiki for that, here's a first pass at 
what I think we need:

Documentation for Tuscan developers:
- describe how to get the code and build Tuscany, update our 
Building.txt (and I suggest we also put in on the Wiki, it's only in SVN 
now)
- add a section on how to generate IDE specific files with Maven (let's 
start with Eclipse and IDEA)
- Jim, you have some docs describing some of the internals of the 
runtime, do they need to be updated after the recent code changes?
- our coding guidelines, we had a doc describing them in the sandbox at 
some point

For people who want to extend or integrate Tuscany:
- finalize our Tomcat integration doc (already on the Wiki thanks to Jeremy)
- an overview of how to bootstrap the Tuscany runtime
- how to add a new component type to Tuscany
- how to add a new binding

For people who want to use Tuscany, run our samples, develop SCA apps 
with Tuscany
- A high level list of what works and what doesn't work (just a high 
level list, the details are/should be in JIRA)
- how to package Tuscany for running on Tomcat
- how to package Tuscany for running in a J2SE environment
- how to package Axis to support Web Service external services and entry 
points (in a Tomcat environment)
- how to run the samples (I'm starting to update that part)

This is just a first list. Could people in the group add anything I may 
have missed? and also volunteer to help write these docs? Also, I'm only 
covering the SCA Java implementation here, what kind of docs do we want 
to add for SDO and DAS?

-- 

Jean-Sebastien

Re: Documentation

[Jim Marino <jm...@myroma.net>]

I'll update that early next week and post it to the wiki.  On the  
coding guidelines, I can dig that out of the sandbox and post it as  
well (it was in docs at some point too).

On that subject, I've noticed some of the code still is throwing non- 
Tuscany derived exceptions.  In summary, we have two base exceptions  
TuscanyRuntimeException and TuscanyException that all exceptions  
thrown by the runtime should generally extend. We should not throw  
any osoa exceptions except by the top-most level and we should avoid  
throwing exceptions which do not extend from one of those two types  
unless it makes sense to (e.g. IllegalStateException). The pattern we  
have generally been following is to have base checked and unchecked  
exceptions at a package level that other exceptions in that package  
or sub-package extend (some sub-packages may not have a "base"  
exception if there are only a few contained exception types). These  
base types are abstract. Calling code can then chose to catch and  
deal with exceptions at whatever level of granularity they chose.

Also, TuscanyRuntimeException and TuscanyException contain the  
following methods to help build up context:

   public List<String> returnContextNames(String name)

     /**
      * Pushes a context name where an error occured onto the call stack
      */
     public void addContextName(String name)

     /**
      * Returns a string representing additional error information  
referred to in the error message
      */
     public String getIdentifier()

     /**
      * Sets an additional error information referred to in the error  
message
      */
     public void setIdentifier(String identifier)

So, if I throw an exception I could do:

TuscanyException e = new TuscanyFooException("Some error occurred in  
this thing",originalError);
e.setIdentifier(theThingName);
throw e;

Later, in calling code, I could catch and add context information,  
such as the component name:

e.addContextName(componentName);


Both exceptions implement getMessage() which prints a context trace.   
I'll update the coding conventions to include this but unless there  
are any objections, could people make sure that code follows this  
pattern?

Thanks,
Jim





On Mar 2, 2006, at 2:26 PM, Jean-Sebastien Delfino wrote:

> With all the recent changes that went into our code base the last  
> few weeks, some of our documentation is getting a little out of  
> date / not in sync anymore with the code. I started to look at the  
> readmes of the samples and I'm going to adjust them.
>
> In addition, I think we need some more documentation of some of the  
> key aspects of Tuscany, to help people get involved, extend or use  
> the Tuscany runtime. We could use our Wiki for that, here's a first  
> pass at what I think we need:
>
> Documentation for Tuscan developers:
> - describe how to get the code and build Tuscany, update our  
> Building.txt (and I suggest we also put in on the Wiki, it's only  
> in SVN now)
> - add a section on how to generate IDE specific files with Maven  
> (let's start with Eclipse and IDEA)
> - Jim, you have some docs describing some of the internals of the  
> runtime, do they need to be updated after the recent code changes?
> - our coding guidelines, we had a doc describing them in the  
> sandbox at some point
>
> For people who want to extend or integrate Tuscany:
> - finalize our Tomcat integration doc (already on the Wiki thanks  
> to Jeremy)
> - an overview of how to bootstrap the Tuscany runtime
> - how to add a new component type to Tuscany
> - how to add a new binding
>
> For people who want to use Tuscany, run our samples, develop SCA  
> apps with Tuscany
> - A high level list of what works and what doesn't work (just a  
> high level list, the details are/should be in JIRA)
> - how to package Tuscany for running on Tomcat
> - how to package Tuscany for running in a J2SE environment
> - how to package Axis to support Web Service external services and  
> entry points (in a Tomcat environment)
> - how to run the samples (I'm starting to update that part)
>
> This is just a first list. Could people in the group add anything I  
> may have missed? and also volunteer to help write these docs? Also,  
> I'm only covering the SCA Java implementation here, what kind of  
> docs do we want to add for SDO and DAS?
>
> -- 
>
> Jean-Sebastien
>

Re: Documentation

[Jean-Sebastien Delfino <js...@apache.org>]

Kevin Williams wrote:
> I'll be updating the DAS sample readme (java/samples/das) this 
> evening.  The DAS white paper needs more detail but it is still 
> accurate.  I'll be beefing it up soon.
>
>
>
> Jean-Sebastien Delfino wrote:
>
>> With all the recent changes that went into our code base the last few 
>> weeks, some of our documentation is getting a little out of date / 
>> not in sync anymore with the code. I started to look at the readmes 
>> of the samples and I'm going to adjust them.
>>
>> In addition, I think we need some more documentation of some of the 
>> key aspects of Tuscany, to help people get involved, extend or use 
>> the Tuscany runtime. We could use our Wiki for that, here's a first 
>> pass at what I think we need:
>>
>> Documentation for Tuscan developers:
>> - describe how to get the code and build Tuscany, update our 
>> Building.txt (and I suggest we also put in on the Wiki, it's only in 
>> SVN now)
>> - add a section on how to generate IDE specific files with Maven 
>> (let's start with Eclipse and IDEA)
>> - Jim, you have some docs describing some of the internals of the 
>> runtime, do they need to be updated after the recent code changes?
>> - our coding guidelines, we had a doc describing them in the sandbox 
>> at some point
>>
>> For people who want to extend or integrate Tuscany:
>> - finalize our Tomcat integration doc (already on the Wiki thanks to 
>> Jeremy)
>> - an overview of how to bootstrap the Tuscany runtime
>> - how to add a new component type to Tuscany
>> - how to add a new binding
>>
>> For people who want to use Tuscany, run our samples, develop SCA apps 
>> with Tuscany
>> - A high level list of what works and what doesn't work (just a high 
>> level list, the details are/should be in JIRA)
>> - how to package Tuscany for running on Tomcat
>> - how to package Tuscany for running in a J2SE environment
>> - how to package Axis to support Web Service external services and 
>> entry points (in a Tomcat environment)
>> - how to run the samples (I'm starting to update that part)
>>
>> This is just a first list. Could people in the group add anything I 
>> may have missed? and also volunteer to help write these docs? Also, 
>> I'm only covering the SCA Java implementation here, what kind of docs 
>> do we want to add for SDO and DAS?
>>
>
>
>
Just thought about more docs that I think will be useful:
- how to use the SDO tools and codegen plugin
- how to use the WSDL2Java tools and codegen plugin (I'll take care of 
this one).

-- 
Jean-Sebastien

Re: Documentation

[Kevin Williams <ke...@qwest.net>]

I'll be updating the DAS sample readme (java/samples/das) this evening.  
The DAS white paper needs more detail but it is still accurate.  I'll be 
beefing it up soon.



Jean-Sebastien Delfino wrote:

> With all the recent changes that went into our code base the last few 
> weeks, some of our documentation is getting a little out of date / not 
> in sync anymore with the code. I started to look at the readmes of the 
> samples and I'm going to adjust them.
>
> In addition, I think we need some more documentation of some of the 
> key aspects of Tuscany, to help people get involved, extend or use the 
> Tuscany runtime. We could use our Wiki for that, here's a first pass 
> at what I think we need:
>
> Documentation for Tuscan developers:
> - describe how to get the code and build Tuscany, update our 
> Building.txt (and I suggest we also put in on the Wiki, it's only in 
> SVN now)
> - add a section on how to generate IDE specific files with Maven 
> (let's start with Eclipse and IDEA)
> - Jim, you have some docs describing some of the internals of the 
> runtime, do they need to be updated after the recent code changes?
> - our coding guidelines, we had a doc describing them in the sandbox 
> at some point
>
> For people who want to extend or integrate Tuscany:
> - finalize our Tomcat integration doc (already on the Wiki thanks to 
> Jeremy)
> - an overview of how to bootstrap the Tuscany runtime
> - how to add a new component type to Tuscany
> - how to add a new binding
>
> For people who want to use Tuscany, run our samples, develop SCA apps 
> with Tuscany
> - A high level list of what works and what doesn't work (just a high 
> level list, the details are/should be in JIRA)
> - how to package Tuscany for running on Tomcat
> - how to package Tuscany for running in a J2SE environment
> - how to package Axis to support Web Service external services and 
> entry points (in a Tomcat environment)
> - how to run the samples (I'm starting to update that part)
>
> This is just a first list. Could people in the group add anything I 
> may have missed? and also volunteer to help write these docs? Also, 
> I'm only covering the SCA Java implementation here, what kind of docs 
> do we want to add for SDO and DAS?
>

SDO for PHP

[Caroline Maynard <ca...@uk.ibm.com>]

Readers of this list may be interested to know that the first "stable" 
release of SDO for PHP recently shipped on the PHP Extension Community 
Library: http://pecl.php.net/package/sdo

This project uses the Tuscany SDO for C++ library internally, but presents 
a native PHP interface. 
--
Caroline Maynard