API discussion

[Patrick Linskey <pl...@gmail.com>]

Hi,

In the meeting today, we discussed API and SPI compatibility. We
covered a lot of ground, and I expect that we'll see a few email
threads coming out of the discussion.

To get started, I'd like to go over what we discussed about APIs first:

- OpenJPA has a set of published developer-centric interfaces.

- These interfaces are relatively loosely-defined

- Our users would benefit from a more rigorously-defined set of APIs

- It is possible to traverse past the "published interface" set pretty
easily, since some of the published interfaces return types that are
not themselves published, or require arguments from classes that are
not published

During the meeting, we discussed the following options for addressing
the above points:

1. Review which classes are marked as @published, and change the build
process to build an API jar based on scanning source for @published
tags. This would have minimal impact on current users, but would be
less-rigorous and would not allow OSGi enforcement of API boundaries.

2. Break the openjpa-persistence and openjpa-persistence-jdbc modules
into separate modules for API and SPI. This would require repackaging
the current impl classes (EntityManagerImpl etc.) into a new
sub-package, in order to work with the OSGi model (it is my
understanding that OSGi does not allow multiple bundles (jars) to
contribute to the same package), but would provide strong compile-time
guarantees and a more formal contract.

Let's discuss which route we want to take to improve our API definitions.

-Patrick

-- 
Patrick Linskey
202 669 5907

Re: API discussion

[Marc Prud'hommeaux <mp...@apache.org>]

-0. I very much like the idea of separating out our published APIs  
into maven modules (both because we would then have the  
infrastructure to enforce that incompatible changes don't get  
introduces in minor releases, as well as having the ability to easily  
publish an API jar should we so desire).

However, I am concerned with the refactoring. In my experience with  
changing package names, while trivial to implement, always leads to  
problems. Since we don't currently support OSGi (I don't think we  
have even discussed OSGi plans in the lists), I don't see why we need  
to bind goal A (separating of the API/SPI into separate packages)  
with goal B (moving the implementations into different sub-packages).  
We underwent a fair amount of effort to ship only a single aggregate  
jar of all of OpenJPA, rather than jars for each of the individual  
modules, so this wouldn't even affect anyone currently using OpenJPA  
in any context other than having a Maven dependency on the separate  
module jars.

That being said, I'll just vote a -0, and will happily accede to the  
sentiment of the community should it differ with mine.


On Aug 8, 2007, at 11:47 AM, Michael Dick wrote:

> <snip>
>
> 2. Break the openjpa-persistence and openjpa-persistence-jdbc modules
>> into separate modules for API and SPI. This would require repackaging
>> the current impl classes (EntityManagerImpl etc.) into a new
>> sub-package, in order to work with the OSGi model (it is my
>> understanding that OSGi does not allow multiple bundles (jars) to
>> contribute to the same package), but would provide strong compile- 
>> time
>> guarantees and a more formal contract.
>
>
> +1
>
> Having a separate maven module for the APIs should be easier to  
> consume for
> other maven users. Also this approach seems easier to maintain once  
> we're
> done. If we invent a build procedure we'll have to ensure that it's
> compatible with maven version.next.
>
> The impact to current users should be minimal if we only change the  
> packages
> on implementation classes and shouldn't raise too many red flags  
> since we
> haven't shipped v1.0 yet.
>
> -Mike

Re: API discussion

[Michael Dick <mi...@apache.org>]

<snip>

2. Break the openjpa-persistence and openjpa-persistence-jdbc modules
> into separate modules for API and SPI. This would require repackaging
> the current impl classes (EntityManagerImpl etc.) into a new
> sub-package, in order to work with the OSGi model (it is my
> understanding that OSGi does not allow multiple bundles (jars) to
> contribute to the same package), but would provide strong compile-time
> guarantees and a more formal contract.


+1

Having a separate maven module for the APIs should be easier to consume for
other maven users. Also this approach seems easier to maintain once we're
done. If we invent a build procedure we'll have to ensure that it's
compatible with maven version.next.

The impact to current users should be minimal if we only change the packages
on implementation classes and shouldn't raise too many red flags since we
haven't shipped v1.0 yet.

-Mike