myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Myfaces Wiki] Update of "Code Generation" by SimonKitching
Date Sat, 02 Feb 2008 23:11:29 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Myfaces Wiki" for change notification.

The following page has been changed by SimonKitching:
http://wiki.apache.org/myfaces/Code_Generation

------------------------------------------------------------------------------
  
  A question was raised about why state isn't retrieved from the attributes map - this cannot
be used, however, cause it would use reflection internally and call the getter of the method,
if a value is not directly stored in the attributes map. As soon as the getter is called,
after the check for the local value returns null, you will get back the value from a value-expression,
and you do not want to save this value in the state, as the value-expression itself is already
stored!
  
+ === Annotation approaches ===
+ 
+ Note that the word "annotation" above is being meant in the general sense of storing metadata
in the source file (as the first paragraph in the section points out). Using Java's built-in
Annotation language feature is just one option, as discussed below.
+ 
+ The options are:
+  * Use real Java Annotations, with retention=Class
+  * Use real Java Annotations, with retention=Source
+  * Use markers embedded within comments
+ 
+ ==== General comments on real Java Annotations ====
+ 
- Another critiscism regarding this approach was the problem that all metadata of the component
would need to be expressed with annotations - this will be pretty tedious, especially as some
of the artifacts (e.g. faces-config description, tld-description and faces-config meta-data
for tool-support) can contain or are written in XML syntax; this would need to be converted
to an annotation based syntax. Additionally, there are peculiarities with annotations which
do not make it easy to use them as a full replacement for a complex XML configuration. One,
they do not allow for a null-value as a default-value, two, if you want to build a complex
structure with them, the syntax is not very intuitive.
+ Some criticism of this was that expressing all the necessary metadata will be pretty tedious,
especially as some of the artifacts (e.g. faces-config description, tld-description and faces-config
meta-data for tool-support) can contain or are written in XML syntax; this would need to be
converted to an annotation based syntax. Additionally, there are peculiarities with annotations
which do not make it easy to use them as a full replacement for a complex XML configuration.
One, they do not allow for a null-value as a default-value, two, if you want to build a complex
structure with them, the syntax is not very intuitive.
+ 
+ I would argue that the meta-data information itself is abstract; it is then made concrete
as xml files in some cases, but as java code in others. So it isn't right to think about "how
do we write a faces-config file in annotations", but instead simply how to represent the complete
set of necessary information. Yes annotations are somewhat less flexible than xml, but the
data to be represented isn't that complex. Some experimenting would be necessary to determine
whether a reasonable syntax could be found or not.
+ 
+ ==== Using real Java Annotations, retention=Class ====
+ 
+ In this approach, the java compiler would include information in the generated .class file
about the annotations in the source. A tool could then post-process these class files to find
this information.
+ 
+ 
+ IDEs have code-completion support for annotations, so working with them could be quite pleasant
for users of these types.
+ There is no runtime penalty, because the annotation information is not loaded into Class
objects at runtime.
+ 
+ However the code would have to be compiled with java 1.5 or later, and the bytecode output
would only be compatible with java 1.5 or later JVMs. Possibly something like RetroWeaver
could be used to make the code 1.4-compatible (throwing away the annotation info after it
has been used is fine) but this is a little clumsy.
+ 
+ It would not be possible for checked-in code to depend on generated code, as the checked-in
code must be compiled first before its .class files can be post-processed.
+ We would also be generating source after the first compile pass has finished, meaning compilation
needs to be done in two passes. Not sure how easy this would be to set up with maven.
+ 
+ Javadoc attached to annotated entities would not be available, as that is not present in
the generated .class files. That means that taglib entries etc. cannot include documentation
taken from javadoc in the source files. It is possible to define documentation using String-typed
annotation attributes, but that would be pretty clumsy in practice.
+ 
+ ==== Using real Java Annotations, retention=Source ====
+ 
+ In this approach, the java compiler would simply ignore the annotations it finds in the
source. However other tools can be used to inspect the source code for these annotations.
+ 
+ IDEs have code-completion support for annotations, so working with them could be quite pleasant
for users of these types.
+ There is no runtime penalty, because the annotation information is not even present in the
.class files.
+ 
+ However the code would have to be compiled with java 1.5 or later. And unfortunately, the
"-target 1.4" option cannot be used with "-source 1.5", so the bytecode output would only
be compatible with java 1.5 or later JVMs.
+ 
+ The code then needs to be processed with some kind of source-code analyser. Sun's JDK comes
with a tool called "APT" for this purpose, but it looks pretty ugly and non-portable. Possibly
Eclipse provides something; plugins do a lot of source-code scanning. As noted in another
section here, there are other source-code parsers available too.
+ 
+ There is no problem with checked-in code depending on generated code, as the code-generation
phase can run before the compilation phase (scanning runs against the source, not the binary
output).
+ 
+ Javadoc attached to annotated entities would probably be available, depending on how the
selected source-code scanner works. So taglib entries etc. can include documentation taken
from javadoc in the source files; this would seem quite convenient for development.
+ 
+ ==== Using real Java Annotations, retention=Class ====
+ 
+ In this approach, specially-formatted comments, eg /** @jsf:component */ are used in the
code.
+ 
+ This has a long history; xdoclet has worked this way for ages, and the Plexus framework
that Maven is built on also does this.
+ 
+ There are a couple of well-known java source code parsing libraries. They are open-source,
and pure java so entirely portable.
+ It should be easy to get access to the rest of the javadoc block, so mapping javadoc comments
on classes or properties into taglib doc is simple.
+ 
+ However it is a new format for users to learn. And there would be no IDE auto-complete help
for comment formats
  
  === Going back to the old Myfaces Core generation approach ===
  

Mime
View raw message