Javadoc is online / How deployment works

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Javadoc is online / How deployment works

David Blevins-2
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

Reply | Threaded
Open this post in threaded view
|

Re: Javadoc is online / How deployment works

Gurkan Erdogdu-5
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 <[hidden email]>
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
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Javadoc is online / How deployment works

David Blevins-2
> On Jan 6, 2019, at 1:23 PM, Gurkan Erdogdu <[hidden email]> wrote:
>
> 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.

I think that's a good approach; interface where possible, concrete class where there are implementation specific details.  The goals are definitely interface worthy.  All the information about AnnotationDeployer and AppModule is specific to the concrete class, also known as the ClassicAssembler.

Here's some old docs on it.

 - http://tomee.apache.org/dev/design-assembler.html

Likely we should move that info into the classes themselves, then delete those pages so we don't have repetitive (and therefore hard to maintain) sources of truth.


-David


Reply | Threaded
Open this post in threaded view
|

Re: Javadoc is online / How deployment works

César Hernández Mendoza
In reply to this post by David Blevins-2
nice improvement to the website.
I'm getting more familiar with the site-generator, today I'll rebase my PR
and try to finish the languages pr.

One question, why do you mean by "referenced classes"?

El sáb., 5 ene. 2019 a las 13:59, David Blevins (<[hidden email]>)
escribió:

> 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
>
>

--
Atentamente:
César Hernández Mendoza.
Reply | Threaded
Open this post in threaded view
|

Re: Javadoc is online / How deployment works

Gurkan Erdogdu-5
In reply to this post by David Blevins-2
Hello team
I have just opened an issue,
https://issues.apache.org/jira/browse/TOMEE-2450 to track all Java source
code comments. This will be the parent issue to track all sub-tasks. If you
want to work on Java Source file to update with comments, please open a
sub-task under this issue. I have already opened for me,
https://issues.apache.org/jira/browse/TOMEE-2451
I am not able to assign this to me, because I have no authorization.
Regards
Gurkan

On Mon, Jan 7, 2019 at 6:04 AM David Blevins <[hidden email]>
wrote:

> > On Jan 6, 2019, at 1:23 PM, Gurkan Erdogdu <[hidden email]> wrote:
> >
> > 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.
>
> I think that's a good approach; interface where possible, concrete class
> where there are implementation specific details.  The goals are definitely
> interface worthy.  All the information about AnnotationDeployer and
> AppModule is specific to the concrete class, also known as the
> ClassicAssembler.
>
> Here's some old docs on it.
>
>  - http://tomee.apache.org/dev/design-assembler.html
>
> Likely we should move that info into the classes themselves, then delete
> those pages so we don't have repetitive (and therefore hard to maintain)
> sources of truth.
>
>
> -David
>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Javadoc is online / How deployment works

jgallimore
Hi Gurkan

I'll assign those to you. I also saw a PR come in with some documentation.
I'll review and merge shortly.

Thanks

Jon

On Tue, Jan 8, 2019 at 3:14 PM Gurkan Erdogdu <[hidden email]> wrote:

> Hello team
> I have just opened an issue,
> https://issues.apache.org/jira/browse/TOMEE-2450 to track all Java source
> code comments. This will be the parent issue to track all sub-tasks. If you
> want to work on Java Source file to update with comments, please open a
> sub-task under this issue. I have already opened for me,
> https://issues.apache.org/jira/browse/TOMEE-2451
> I am not able to assign this to me, because I have no authorization.
> Regards
> Gurkan
>
> On Mon, Jan 7, 2019 at 6:04 AM David Blevins <[hidden email]>
> wrote:
>
> > > On Jan 6, 2019, at 1:23 PM, Gurkan Erdogdu <[hidden email]>
> wrote:
> > >
> > > 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.
> >
> > I think that's a good approach; interface where possible, concrete class
> > where there are implementation specific details.  The goals are
> definitely
> > interface worthy.  All the information about AnnotationDeployer and
> > AppModule is specific to the concrete class, also known as the
> > ClassicAssembler.
> >
> > Here's some old docs on it.
> >
> >  - http://tomee.apache.org/dev/design-assembler.html
> >
> > Likely we should move that info into the classes themselves, then delete
> > those pages so we don't have repetitive (and therefore hard to maintain)
> > sources of truth.
> >
> >
> > -David
> >
> >
> >
>