Hi Mike, Although the metadata is written like a javadoc comment, it is not processed by the javadoc tool. The qdox (qdox.codehaus.org) library is a full java parser that builds a datastructure representing everything in the java files you feed it - except the method bodies. This includes analysing the javadoc for tags. The plugin applies this parser to the java source in the "generate-sources" phase, ie before any java code is compiled by javac.
When actually writing the meta-data, the "auto-complete" ability that is available for an xml file (due to a schema) *is* better than the doc-annotation approach (which has no IDE help). However on the plus side, there is much less to write as much of the data is actually derived from analysing the real class hierarchy, method signature, etc. Error-reporting for malformed metadata is automatic for xml with a schema at the "syntax" level. With the doc-annotation approach, the plugin needs to specifically check that the right annotations are there (but that's not too hard). In both cases, the error-reporting will occur before any code compilation. I believe that at the "semantic" level the doc-annotation approach is better checked because you cannot get inconsistent declaration of properties vs code for example; the property metadata is *derived* from the actual code declaration. With the xml approach, the class hierarchy and property types are effectively typed in once in java and once in xml, and there will be problems if the two don't match.. Regards, Simon On Fri, 2008-03-21 at 14:40 -0400, Mike Kienenberger wrote: > I've been following this thread on and off, so my apologies if you > already covered it, > but how different will syntax checking be with the javadoc annotations > vs xml? Xml editors automatically validate with schemas or dtds. Is > something similar available for javadoc annotations in the standard > IDEs? Or will errors not be checked until the javadocs are processed, > which seems like it may be several minutes into the build process? > > Not saying it's a showstopper, just pointing out another area to consider. > > On 3/19/08, Leonardo Uribe <[EMAIL PROTECTED]> wrote: > > > > On Wed, Mar 19, 2008 at 3:39 AM, [EMAIL PROTECTED] > > <[EMAIL PROTECTED]> wrote: > > > > > > > > > > > > > Leonardo Uribe schrieb: > > > > > > > > > > > > Thanks Simon for make more clear this on the wiki page. I have > > also > > > > > added comments about how > > > > > should work isSetFieldMethod and isGetLocalMethod attributes for > > > > > @mfp.property. > > > > > > > > > > > > And thanks for your additions. > > > > > > > > Is the "setLocalMethod" stuff specifically something that trinidad > > > > needs? I have not seen this anywhere in core or tomahawk that I > > > > remember. If so, then perhaps the wiki could say (trinidad only) or > > > > similar next to those props. > > > > > > > > setLocalMethod and isSetProperty stuff is necessary only for tomahawk > > (trinidad does not require this because it use > > a FacesBean to manage the data). > > > > > > > > > > > > > > > > > > > > On Tue, Mar 18, 2008 at 12:44 PM, Andrew Robinson > > > > > > > > > <[EMAIL PROTECTED] > > > > <mailto:[EMAIL PROTECTED]> > > > > <mailto:[EMAIL PROTECTED] > > > > <mailto:[EMAIL PROTECTED]>>> > > > > > > > > > wrote: > > > > > > > > > > On Tue, Mar 18, 2008 at 9:54 AM, [EMAIL PROTECTED] > > > > <mailto:[EMAIL PROTECTED]> > > > > > > > > > > > > <mailto:[EMAIL PROTECTED] > > > > <mailto:[EMAIL PROTECTED]>> > > > > > > > > > <[EMAIL PROTECTED] <mailto:[EMAIL PROTECTED]> > > > > <mailto:[EMAIL PROTECTED] > > > > > > > > > > > > > <mailto:[EMAIL PROTECTED]>>> wrote: > > > > > > Hi Andrew, > > > > > > > > > > > > Andrew Robinson schrieb: > > > > > > > > > > > > > One major drawback to the javadoc annotation approach > > > > has been > > > > > left > > > > > > > out and that is attribute reuse. The maven-faces-plugin > > > > > allows you to > > > > > > > import XML fragments using XPath. So in Trinidad, > > onclick, > > > > > > > onmouseover, onmouseout, etc. you can import one XML > > > > file and > > > > > not have > > > > > > > to re-define all these. But with the javadoc approach, > > you > > > > > have to > > > > > > > either one, try to hack the code to extend other > > > > classes, two > > > > > have > > > > > > > some weird interface usage to import these. Either way, > > the > > > > > object > > > > > > > hierarchy has to be hacked to get it to work. > > > > > > > > > > > > > > > > > > > Hmm..interesting. So trinidad has cases where a class X > > > > is not > > > > > related > > > > > > to A by inheritance, but does want to provide the same > > > > > properties as A? > > > > > > > > > > > > Java currently defines "implements" and "extends"; sounds > > > > like > > > > > Trinidad > > > > > > has invented a new OO concept, "emulates" :-). > > > > > > > > > > No, it only imports certain attributes, not all of them. > > > > Take some > > > > > time to look at the trinidad-build project and how it works. > > > > It is > > > > > better to see than explain. > > > > > > > > > > > > > > > In tomahawk, there are interfaces like > > > > > org.apache.myfaces.component.UserRoleAware that > > define getter and > > > > > setter methods for a particular group of related properties. > > > > Maybe we > > > > > can do something like this: > > > > > > > > > > /** > > > > > * @mfp.interface //or propertiesinterface or setofproperties or > > > > > anything related > > > > > **/ > > > > > public interface UserRoleAware > > > > > { > > > > > static final String ENABLED_ON_USER_ROLE_ATTR = > > > > "enabledOnUserRole"; > > > > > static final String VISIBLE_ON_USER_ROLE_ATTR = > > > > "visibleOnUserRole"; > > > > > > > > > > /** > > > > > * @mfp.property > > > > > **/ > > > > > String getEnabledOnUserRole(); > > > > > > > > > > void setEnabledOnUserRole(String userRole); > > > > > > > > > > /** > > > > > * @mfp.property > > > > > **/ > > > > > String getVisibleOnUserRole(); > > > > > > > > > > void setVisibleOnUserRole(String userRole); > > > > > } > > > > > > > > > > Then the abstract component class can implements this interface > > and > > > > > finally the generated class must implement the methods. In this > > > > way we > > > > > make clearer the API, and eliminate in a clean way the advantage > > of > > > > > using xml files. > > > > > > > > > > > > I see. Yes, where is a group of properties to be shared between two > > > > classes, the OO way would be to declare a common interface. > > > > > > > > I guess another example is the set of "html passthrough > > > > attributes" that > > > > is attached to many components. > > > > > > > > The myfaces-builder-plugin code already walks interfaces looking for > > > > property definitions. Currently the normal "@mfp.component" > > annotation > > > > is looked for even on interfaces (the plugin already knows that > > > > this is > > > > an interface) but a different annotation could also be introduced. > > > > > > > > An alternative might be to have > > > > @mfp.property group="userRole" > > > > and > > > > @mfp.component usePropertyGroups="userRole, htmlAttributes" > > > > but I prefer the interface approach. Does trinidad pull subsets of > > > > properties from the myfaces-api classes? If so, then the > > > > usePropertyGroups would be necessary as we cannot factor out > > > > interfaces > > > > for the javax.faces classes. > > > > > > > > > > > > The point you made about overriding documentation appears to be the > > > > ugliest part of the doc-annotation based approach. In the wiki page > > I > > > > have a "delegating method" just to override the comment, which is > > > > really > > > > not nice. Any suggestions for a better answer to this would be > > > > welcome... > > > > > > > > On trinidad there is 12 files that are on the include dirs. Some files just > > represents > > a bag of properties to be added like this: > > > > CommonAttrs.xml > > inlineStyle > > styleClass > > shortDesc > > partialTriggers > > > > > > Other files just have one property like: > > > > DisclosedRowKeys.xml > > disclosedRowKeys > > > > But other files has related properties: > > > > CoreJSEvents.xml > > onclick > > ondblclick > > ........ > > > > No properties are pulled from myfaces-api classes. > > > > On myfaces 1.2 the most common case is groups of 1 property referenced on > > several components. (Example: TabindexProperty.xml). The advantage of doing > > this is that one change on the property just be done on one site (How we can > > do this using annotations?). > > > > regards > > > > Leonardo Uribe > > > >
