Re: [platform-releng-dev] improved checking for internal references

[Steven Wasleski <wasleski@xxxxxxxxxx>]

First let me say that I think we need to find a way to make a good start on this now and continue to evolve towards a well maintained and complete api definition over time.

However, I share the concern about the potential for component.xml files to get out of date and I agree that annotations in the source would stand a better chance of staying in sync with the api intentions of the component team. Note that not every class needs to be documented in the component.xml file. If you add a class to an "internal" package you do not need to do anything. If you add a class or interface that does not have any api restrictions to an "api" package you also do not need to do anything.

An idea that has been bouncing around in my head for a little while is that we could start with the component.xml because that is what we have the tools for now. At a later date when we start targeting Java 5 VMs instead of Java 1.4 VMs, we could create the annotation types we need and write a tool to do a one time injection from the component.xml files into the source. If needed we could write a build time script that would do the reverse operation.

I tend to lean toward Java 5 annotations for the source annotations rather than Javadoc because I believe it would be more readily exploited by the JDT to enforce the rules as code is being written rather than just doing a batch build time check. I could be off the mark on this point.

Thanks,
Steve Wasleski

IES Technical Lead

Peter Manahan <manahan@xxxxxxxxxx>

Peter Manahan <manahan@xxxxxxxxxx>
Sent by: platform-releng-dev-admin@xxxxxxxxxxx

02/17/2005 11:49 AM

Please respond to
platform-releng-dev

To	platform-releng-dev@xxxxxxxxxxx
cc
Subject	Re: [platform-releng-dev] improved checking for internal references

I think the idea of the component.xml is great and something that has been needed for a long time. But the potential for it to get out of date is very likely. 

Perhaps if the component.xml was generated at build time.  I assume the javadoc is built that way and since normally API is defined in javadoc perhaps something could be added as a tag that allowed the generation of the component.xml. Keeping all the information with the java files where hopefully the API javadoc is kept up to date. 

Thanks,

-----------------------------------
Peter Manahan
IBM Rational Tools
Common Install
------------------------------------
manahan@xxxxxxxxxx 

platform-releng-dev-admin@xxxxxxxxxxx wrote on 17/02/2005 11:35:51 AM:

> I have some concerns about what this tool will mean in terms of process.
> 
> It seems that every team will be expected to update this file as public 
> classes are added to their plug-ins.  They will also need to update the file 
> if private internal classes are added.  If they fail to do so, there also 
> doesn't seem to be any real way for them to realize that they have forgotten 
> to do something.  As such, I am concerned that this will eventually lead to 
> "component.xml" files that are significantly out-of-date.
> 
> Also, the creation of this file is not an insubstantial task.  For example, 
> Platform/UI maintains about 2400 classes.
> 
> I would like to recommend that the use of this tool be put on hold until it 
> can address some of these issues.  Ideally, the "component.xml" file should 
> be optional.  Sane defaults should be obtainable by: parsing the package 
> name, parsing javadoc comments, and make some assumptions about the nature of 
> fragments.
> 
> 
> On Tuesday February 8 2005 05:52 pm, Jim des Rivieres wrote:
> > The tool takes as input a set of component definition files
> > (component.xml) that provides the following information for each
> > component:
> >
> > - what plug-ins are to be treated as a unit for the purposes of drawing an
> > API boundary; all references between the plug-ins are considered a private
> > matter (even if to internal packages)
> > - a list of packages that are to be considered API packages
> > - a list of classes and interfaces within the API package that have
> > additional constraints on them (e.g., clients are not supposed to
> > implement an API interface, instantiate an API class, or instantiate an
> > API class)
> _______________________________________________
> platform-releng-dev mailing list
> platform-releng-dev@xxxxxxxxxxx
> http://dev.eclipse.org/mailman/listinfo/platform-releng-dev