Richard mentioned some examples were broken after a recent library upgrade and I promised to start a thread on the topic as we have system issues there.
One of the things that's aways bugged me and was on the "some day" list is that
in our examples we are encouraging people to have to know how to put together
the right dependencies to get a working container for plain unit testing.
Some examples show `openejb-core` and `javaee-api`, some show `openejb-cxf-rs`,
some show just `openejb-cxf`, some show `tomee-jaxrs`, some also pull in
specific dependencies like `cxf-rt-rs-client`, some add a specific MicroProfile
API.
None of this documented anywhere, you just have to "know". And any time we
upgrade our dependencies, users must upgrade theirs. Any time we change our
excludes or mark things provided, users need to add dependencies they weren't
informed they now need. We're setting people up for failure and frustration.
Side note, this is one of the reasons I really like having the examples in the
main codebase as it helps to keep us honest -- we experience the same things in
our build users experience in theirs.
Some months back I wrote some code that will inspect a TomEE server zip and
generate a pom from it. The poms have zero transitive dependencies, every
dependency is explicitly listed and it is therefore library to library
identical to the zip, but usable as a plain maven dependency. There is one for
each of our servers:
<dependency>
<groupId>org.apache.tomee.bom</groupId>
<artifactId>tomee-webprofile</artifactId>
<version>8.0.7-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.apache.tomee.bom</groupId>
<artifactId>tomee-microprofile</artifactId>
<version>8.0.7-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.apache.tomee.bom</groupId>
<artifactId>tomee-plus</artifactId>
<version>8.0.7-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.apache.tomee.bom</groupId>
<artifactId>tomee-plume</artifactId>
<version>8.0.7-SNAPSHOT</version>
</dependency>
I recommend we take this opportunity to go through all the examples and replace
the use of individual TomEE dependencies in favor of one of the dependencies
above. Once we've done that, the odds of our users or our examples being
affected by library changes drops significantly.
In writing this, the one gap I see is that we probably want an equivalent API
pom for each server dist. Our examples tend to have javaee-api marked as scope
`provided` and the server jars marked with scope `test` so code in
`src/main/java` isn't depending on our internals. We could have an additional
"api" pom that contains the javaee-api jar, all microprofile-*.jar api jars and
any API jars we provide ourselves (at the moment that's just openejb-api.jar).
That might give us examples that look like this in practice:
<dependency>
<groupId>org.apache.tomee.bom</groupId>
<artifactId>tomee-microprofile-api</artifactId>
<version>8.0.7-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.tomee.bom</groupId>
<artifactId>tomee-microprofile</artifactId>
<version>8.0.7-SNAPSHOT</version>
<scope>test</scope>
</dependency>
It's tempting to think, "maybe the second dependency should have an 'impl'
suffix?" I asked myself, thought through it and came out on the "no" side.
There will be people who just want the one dependency that has everything.
Specifically anyone using TomEE in an embedded fashion, as plain libraries, or
aiming to create an uber jar. It's only people who intend to deploy to a TomEE
zip who need/want the two differently scoped dependencies. I also think to
when I'm using Arquillian and there is an "api" and "impl" jar for literally
everything and I forget to add one or the other, things fail, and I think
"seriously, I'm never going to chose a different implementation, why are you
making me do this?" It's all the more frustrating as you know darn well the
impl dep needs a very specific version of that api dep -- you can't just use an
older or newer api version and expect things to work. Therefore I think having
an "everything" dep and an "apis-only" dep is just fine.
Thoughts?
--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com
smime.p7s
Description: S/MIME cryptographic signature
