14 Replies Latest reply on Nov 20, 2007 11:33 AM by alrubinger

    New Build Artifact - EJB3 External API

    alrubinger

      I've added a new artifact to the EJB3 build script, producing:

      jboss-ejb3-ext-api.jar

      ...whose intent is to expose any classes needed by a bean provider for development (compilation) of EJB3 and JBoss-specific extensions. To develop EJB3 applications on JBoss, all that should be required on the build CP is this library and jboss-javaee.jar

      Currently the external API is limited to all annotations (minus the Impls), Stateful Cache support, and RemoteProxyFactory (as is currently required for compilation).

      The key here is ensuring that we don't expose any implementation internals to the bean provider, externalizing out as interfaces whenever possible but providing enough support for custom implementations.

      Testing the validity of this JAR is proving difficult; the test suite itself tests many internals and cannot compile against the external API alone.

      How can we ensure that we're providing everything necessary for an external API in this JAR? Separate source tree of test EJBs compiled against the Ext API and jboss-javaee.jar alone?

      The alternative is the status quo I used to employ as a bean provider - grabbing internals from JARs under ejb3.deployer and using those for compilation.

      This must be completed for Beta 3.

      http://jira.jboss.com/jira/browse/EJBTHREE-1099

      S,
      ALR

        • 1. Re: New Build Artifact - EJB3 External API
          wolfc

          The jboss-ejb3-ext-api.jar artifact must come from projects/ejb3, not from AS trunk. This ensures isolation from the other code and a separate release cycle (so we can freeze it).

          • 2. Re: New Build Artifact - EJB3 External API
            alrubinger

            I've started a new artifact under projects:

            jboss-ejb3-ext-api

            ...which currently will not compile due to a series of API leaks detailed in this thread:

            http://www.jboss.com/index.html?module=bb&op=viewtopic&p=4101977#4101977

            S,
            ALR

            • 3. Re: New Build Artifact - EJB3 External API
              alrubinger

              The problem with extracting the external API into its own project is that we introduce cyclic compile dependencies all over the place: EJB3 Core Depends on ext-api, and it's very difficult to ensure that ext-api doesn't depend on Core without losing compile-time constraints.

              An example we've been discussing over the past couple weeks is @Cache, which historically took a value of a cache implementation, and now accepts a factory. But either way, eventually one of the classes in ext-api must extend from or implement Cache in core.

              One benefit of the monolithic layout to EJB3 in AS is that the entire source is available in one tree, compiled simultaneously, and we can pluck out individual classes and manually JAR them to make the ext-api.

              Proposed solutions using separate modules have included using a registered factory like:

              @CacheFactory(type="NoPassivationCache")


              ...where the "type" String is configured in an MC Bean and bound to an actual cache impl or factory. But here the bean provider loses compile-time constraints.

              So I'm going to draw up some rules.

              1) Core depends on ext-api to compile
              2) ext-api cannot depend on Core; must compile on its own

              Given both 1) and 2), something has to give, either:

              A) We ditch some compile-time constraints to get around the circular dependencies
              B) We keep ext-api as a build artifact in EJB3 Core, produced by the build script
              C) We undergo some surgery to clear up and redesign how @Cache and @Pool are used and try to separate out concerns in StatefulContainer and StatelessContainer

              Thoughts? I'm in circles.

              S,
              ALR

              • 4. Re: New Build Artifact - EJB3 External API
                starksm64

                Referencing a cache configuration does not need a type-safe construct. Its a lookup into a map, and its the bean providing that map that would enforce type safety using a Cache interface. There is no point to a @Cache annotation carrying implementation details.

                Nothing needs to implement the @Cache annotation in core, the Cache interface implementation is needed, and this is outside of an ejb provider class. The same applies to @Pool. Its a separate question as to whether you still want these type of annotations as part of the container implementation spi. I don't think they are that useful as its just as easy to configure aspects via xml.

                • 5. Re: New Build Artifact - EJB3 External API
                  brian.stansberry

                  TBH, I don't see why @Cache needs to be in an ext-api jar at all. It's a specification of what impl of an SPI to use, which is probably not the sort of thing we should be encouraging, and definitely isn't something that we need to make totally painless.

                  The only reason a user would need to use this annotation is if they write a custom Cache impl. And if they do that they are going to have to have the full ejb-core jar on their classpath anyway.

                  • 6. Re: New Build Artifact - EJB3 External API
                    alrubinger

                     

                    "scott.stark@jboss.org" wrote:
                    Referencing a cache configuration does not need a type-safe construct.


                    That satisfies my concession A) :)

                    "bstansberry@jboss.com" wrote:
                    TBH, I don't see why @Cache needs to be in an ext-api jar at all


                    Maybe, but it makes room for new Cache implementations we might derive in the future. And I'd like to keep the existing pattern where most metadata can be either XML- or annotation-based.

                    If we don't need compile-time constraints on these annotations, I should be able to pull this together. Will update - thanks, all.

                    S,
                    ALR

                    • 7. Re: New Build Artifact - EJB3 External API
                      wolfc

                      The current @Cache should not be in ext-api. Maybe we'll keep the construct in core.

                      So for a bean developer we get either:

                      @Cache("NoPassivationCache")

                      or
                      @CacheFactory("NoPassivationCache")


                      By making the CacheFactoryRegistry a generic interface:
                      interface CacheFactoryRegistry<T> {
                       CacheFactory<T> getFactory(String name);
                      }

                      We can have typesafety in the core.

                      On a related note: we still need something to pass in the cache configuration.
                      interface CacheFactory<T> {
                       Cache<T> createCache(AnnotedElement element);
                      }


                      I don't like it that we have two different @CacheConfig annotations.

                      • 8. Re: New Build Artifact - EJB3 External API
                        brian.stansberry

                         

                        I don't like it that we have two different @CacheConfig annotations.[url]

                        Me neither. There's a JIRA related to this: http://jira.jboss.com/jira/browse/EJBTHREE-930 but the discussed solution is silly.

                        The only attribute that isn't common between these annotations is "replicationIsPassivation" which can just be ignored by a non-clustered cache. So why not just replace the two with a common version?


                        • 9. Re: New Build Artifact - EJB3 External API
                          alrubinger

                          I have:

                          * Centralized @CacheConfig
                          * Restructured to @Cache("RegisteredCacheType")
                          * Restructured to @Pool("RegisteredPoolType")
                          * Moved @Clustered to "cluster" project
                          * Moved the External API from JBoss AS EJB3 Core to projects/ejb3 and included in classpath as thirdparty library.

                          S,
                          ALR

                          • 10. Re: New Build Artifact - EJB3 External API
                            brian.stansberry

                            Re: @Clustered:

                            1) When moved to cluster module, it was repackaged into org.jboss.annotation.ha. I want to put it back in org.jboss.annotation.ejb. Leaving it in cluster module is fine with me.

                            Reason is newly discovered EJBTHREE-1109 and EJBTHREE-1110 imply that this annotation should have a homeLoadBalancePolicy attribute. That makes the annotation ejb-specific. So, if its ejb specific, might as well keep the old package name and not cause issues for pre-existing applications.

                            2) Please take back ClusteredImpl. That class is an internal ejb3 implementation detail of how you guys consume xml metadata by turning it into a class annotation.

                            • 11. Re: New Build Artifact - EJB3 External API
                              alrubinger

                               

                              "bstansberry@jboss.com" wrote:
                              1) When moved to cluster module, it was repackaged into org.jboss.annotation.ha. I want to put it back in org.jboss.annotation.ejb. Leaving it in cluster module is fine with me.


                              Done.

                              "bstansberry@jboss.com" wrote:
                              2) Please take back ClusteredImpl. That class is an internal ejb3 implementation detail of how you guys consume xml metadata by turning it into a class annotation.


                              And done.

                              S,
                              ALR

                              • 12. Re: New Build Artifact - EJB3 External API
                                alrubinger

                                With the introduction of the ext-api module, we can now be sure that there are no further API leaks into internals.

                                How can we test to be sure that ext-api is complete, however? We can't build EJB3 Unit Tests against ext-api alone; many of them test internals.

                                S,
                                ALR

                                • 13. Re: New Build Artifact - EJB3 External API
                                  wolfc

                                  I don't like the Impls of annotations to still be in trunk. They must always be a one on one match with the actual annotation.
                                  The question is should they be in ext-api?

                                  • 14. Re: New Build Artifact - EJB3 External API
                                    alrubinger

                                     

                                    "wolfc" wrote:
                                    I don't like the Impls of annotations to still be in trunk. They must always be a one on one match with the actual annotation.
                                    The question is should they be in ext-api?


                                    I know we're trying to break everything off from jbossas/trunk into their own components within projects/ejb3, but I'm not jumping at the chance to move implementation code like this into ext-api and a bean developer's visibility. :)

                                    Yet another separate Maven project, annotation-impl, with release cycle to mirror that of ext-api?

                                    S,
                                    ALR