SPI naming conventions (was Re: Interfaces for implementation/binding extensions to provide runtime behaviors)

[Simon Nash <na...@hursley.ibm.com>]

Jean-Sebastien Delfino wrote:

> [snip]
> 
>> 5. The org.apache.tuscany.assembly.xml package seems to contain
>>    implementation classes that aren't in an "impl" subpackage.
> 
> 
> I'm not sure that we want all non spi packages to be *.impl. In general 
> I think we should avoid extremes, like:
> - have all spis in *.spi.* packages
> - or have all non spi in *.impl packages
> 
> Looking at other Apache projects, many seem to follow a more reasonable 
> and balanced approach, which I hope we can do as well.
 >
I think the key requirement is to

1. Make it clear to extension developers what classes/interfaces are
    public SPIs or APIs that they are intended to use directly.  These
    should be sufficient to do all the things they would normally need
    to do.

2. Make it clear to base runtime developers what classes/interfaces
    they are exposing to extension developers as SPIs and APIs.  The
    contracts exposed by these APIs and SPIs should not change from
    one release to the next without going through a deprecation and
    migration process.

Ths can be done either with a clear naming convention or in some other
way, e.g., by writing Javadoc comments, or by maintaining a documented
list of all the APIs and SPIs.  My preference is a clear naming convention
because the other mechanisms tend not to be sufficiently robust.

I don't have strong views on what the convention should be, but I
think it should be clear and consistent so that people always know
whether or not the class or interface that they are using or
developing is intended to be an API/SPI or an internal part of
the implementation.

   Simon


---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org