Mailing-List: contact tuscany-dev-help@ws.apache.org; run by ezmlm
Precedence: bulk
Reply-To: tuscany-dev@ws.apache.org
Received-SPF: pass (asf.osuosl.org: local policy)
Mime-Version: 1.0 (Apple Message framework v733)
In-Reply-To: <4407710A.1000901@apache.org>
References: <4407710A.1000901@apache.org>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
Message-Id: <3E39708B-A18B-4CB1-B64C-6E2B969006AE@myroma.net>
Content-Transfer-Encoding: 7bit
From: Jim Marino <jmarino@myroma.net>
Subject: Re: Documentation
Date: Fri, 3 Mar 2006 12:49:56 -0800
To: tuscany-dev@ws.apache.org

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
>