Thank you David. One question, do we need to comment on the interface or concrete class? For example, Assembler interface in org.apache.openejb.spi package? I think commenting on the interface is better and then for extra comments in concrete class. Regards. Gurkan
On Sat, Jan 5, 2019 at 10:59 PM David Blevins <david.blev...@gmail.com> wrote: > Javadoc is now online! I still have more ideas for hacking on it, but > it's good enough to open up for more people to start filling in > documentation. > > Some important classes.... > > When you deploy an application, all annotations and xml are merged into > one single meta-data tree by this class. After this point, annotations and > xml are no longer read or referenced. It outputs an AppModule which is a > mutable object and a little bit "fancy." > > - > http://tomee.apache.org/tomee-8.0/javadoc/org/apache/openejb/config/AnnotationDeployer.html > - > http://tomee.apache.org/tomee-8.0/javadoc/org/apache/openejb/config/AppModule.html > > The next major step is this class which will take this data and analyze > it, figuring out what corresponding container parts would need to be built > in order to run the app as described. It outputs an AppInfo which is an > immutable data object that can have no methods or logic whatsoever. After > this point, the complexity of roughly 100k lines of deployment code is > erased and all that remains is the AppInfo tree. This tree can be thought > of as an AST (abstract syntax tree) using compiler terms. > > - > http://tomee.apache.org/tomee-8.0/javadoc/org/apache/openejb/config/ConfigurationFactory.html > - > http://tomee.apache.org/tomee-8.0/javadoc/org/apache/openejb/assembler/classic/AppInfo.html > > The AppInfo is blindly built by the Assembler. The Assembler does no > validation. It should have been done in the steps leading to the creation > of the AppInfo. The objects built by the Assembler are the true, > thread-safe, runtime objects that make your apps actually work (aka the > "runtime"). The Assembler is the only bit of code allowed to see both the > AppInfo and the runtime classes. The runtime classes themselves are not > allowed to see the AppInfo tree or the Assembler. After this point the > AppInfo tree and Assembler itself are gone. > > - > http://tomee.apache.org/tomee-8.0/javadoc/org/apache/openejb/assembler/classic/Assembler.html > > Now you have a working and running container wrapped around your code and > ready to serve requests. This runtime is completely unaware of what came > before it or built it and therefore it's most simple self. This runtime is > as immutable as possible and thread-safe. > > This process is a major part of why TomEE is so light at runtime. The > deployment process is a bit like launching a space shuttle where heavy bits > keep falling away until only a tiny part remains. > > The best way to understand that code is to study the Assembler is it is > the last "heavy bit" that builds the actual runtime, before falling away > itself. > > > > Contribution Opportunity: > > - Take this email and try and fill out the Javadoc of the referenced > classes > > > > -- > David Blevins > http://twitter.com/dblevins > http://www.tomitribe.com > >
