commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ryan Heaton (JIRA)" <commons-...@jakarta.apache.org>
Subject [jira] Updated: (JELLY-225) apt jelly tag library
Date Thu, 22 Dec 2005 18:41:31 GMT
     [ http://issues.apache.org/jira/browse/JELLY-225?page=all ]

Ryan Heaton updated JELLY-225:
------------------------------

    Attachment: testBasicExample.jelly
                testForAllTypesIncludeInterfaces.jelly

I've attached some basic examples:

testBasicExample.jelly: An example script that runs through all source files and outputs as
properties each type's various members, annotations, docs, etc.
testForAllTypesIncludeInterfaces.jelly: An example script that iterates through all types,
including interfaces, that have a certain annotation

> apt jelly tag library
> ---------------------
>
>          Key: JELLY-225
>          URL: http://issues.apache.org/jira/browse/JELLY-225
>      Project: jelly
>         Type: New Feature
>   Components: submissions
>     Reporter: Ryan Heaton
>  Attachments: testBasicExample.jelly, testForAllTypesIncludeInterfaces.jelly
>
> This is a proposal for a new jelly tag library that provides an interface to the new
Java 5 Annotation Processing Tool (apt) and its associated Mirror API (see http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html).
> From the official apt documentation: "apt is a command-line utility for annotation processing.
It includes a set of reflective APIs and supporting infrastructure to process program annotations
(JSR 175). These reflective APIs provide a build-time, source-based, read-only view of program
structure. They are designed to cleanly model the Java programming language's type system
after the addition of generics (JSR 14)."
> Developers who which to process Java source code are presently limited to working with
the Mirror API directly.  If, for example, a developer wished to generate an artifact such
as an xml config file or another Java class must do so by writing to an instance of java.io.PrintWriter.
> As an admittedly impotent example, to generate a simple class that will print out all
methods of all classes in a given source base, the developer would implement instances of
com.sun.mirror.apt.AnnotationProcessorFactory and com.sun.mirror.apt.AnnotationProcessor that
look something like this:
>     package org.apache.commons.jelly.examples;
>     import java.util.Collection;
>     import java.util.Set;
>     import java.util.Collections;
>     import java.io.IOException;
>     import java.io.PrintWriter;
>     import com.sun.mirror.apt.AnnotationProcessorFactory;
>     import com.sun.mirror.apt.AnnotationProcessor;
>     import com.sun.mirror.apt.AnnotationProcessorEnvironment;
>     import com.sun.mirror.declaration.AnnotationTypeDeclaration;
>     import com.sun.mirror.declaration.TypeDeclaration;
>     import com.sun.mirror.declaration.MethodDeclaration;
>     public class ClassAndMethodPrinterAnnotationProcessorFactory implements AnnotationProcessorFactory
{
>       public Collection<String> supportedOptions() {
>         return Collections.EMPTY_LIST;
>       }
>       public Collection<String> supportedAnnotationTypes() {
>         return Collections.EMPTY_LIST;
>       }
>       public AnnotationProcessor getProcessorFor(Set<AnnotationTypeDeclaration>
atds, AnnotationProcessorEnvironment env) {
>         return new ClassAndMethodPrinterAnnotationProcessor(env);
>       }
>       private class ClassAndMethodPrinterAnnotationProcessor implements AnnotationProcessor
{
>         AnnotationProcessorEnvironment env;
>         public ClassAndMethodPrinterAnnotationProcessor(AnnotationProcessorEnvironment
env) {
>           this.env = env;
>         }
>         public void process() {
>           try {
>             PrintWriter writer = env.getFiler().createSourceFile("org.apache.commons.jelly.examples.ClassAndMethodPrinter");
>             writer.println("package org.apache.commons.jelly.examples;");
>             writer.println();
>             writer.println("public class ClassAndMethodPrinter {");
>             writer.println();
>             writer.println("  public static void main(String[] args) {");
>             for (TypeDeclaration typeDeclaration : env.getTypeDeclarations()) {
>               writer.println(String.format("    System.out.println(\"Class: %s\");",
typeDeclaration.getQualifiedName()));
>               for (MethodDeclaration methodDeclaration : typeDeclaration.getMethods())
{
>                 writer.println(String.format("    System.out.println(\"Method: %s.%s\");",
typeDeclaration.getQualifiedName(), methodDeclaration.getSimpleName()));
>               }
>             }
>             writer.println("  }");
>             writer.println();
>             writer.println("}");
>           }
>           catch (IOException e) {
>             throw new RuntimeException(e);
>           }
>         }
>       }
>     }
> Any Java programmer with a little bit of experience could testify that using a PrintWriter
for large and complex output is significantly heavy and burdensome.  To use a familiar paradigm
in J2EE, nobody wants to use a Servlet's PrintWriter for outputting many large and complex
html documents.  For this reason, Java Server Pages (JSP) were created to ease development
of complex output.
> An apt tag library would be to the Mirror API what JSPs are to the Servlet API.  Instead
of writing implementations of AnnotationProcessorFactory and AnnotationProcessor, why not
just use Jelly to manage your output, like so:
>     <j:jelly xmlns:j="jelly:core" xmlns:apt="jelly:apt">
>       <apt:javaSource name="org.apache.commons.jelly.examples.ClassAndMethodPrinter">
>     package org.apache.commons.jelly.examples;
>     public class ClassAndMethodPrinter {
>       public static void main(String[] args) {
>         <apt:forAllTypes var="type">
>         System.out.println("<j:out value="${type.qualifiedName}"/>");
>           <apt:forAllMethods var="method">
>         System.out.println("<j:out value="${type.qualifiedName}"/>.<j:out value="${method.simpleName}"/>");
>           </apt:forAllMethods>
>         </apt:forAllTypes>
>       }
>     }
>       </apt:javaSource>
>     </j:jelly>
>     
> Not only is the requirement to implement Mirror API classes lifted from the developer,
but it's easy to see how easily Jelly provides a much cleaner and easier-to-read abstraction
on top of the Mirror API.  Developers could also take advantage of the rich set of jelly tag
libararies for managing output.
> The new apt tag library would be a replacement for the popular tool XDoclet (see http://xdoclet.sourceforge.net).
 Not only would it provide everything that XDoclet currently provides, but it would have many
significant advantages over XDoclet, including:
> -No tight coupling to Ant
> -Availability of a rich set of tag libraries, including all the current jelly tag libararies
like jelly core and xml taglibs.
> -Complete support for full Java 5 syntax, including generics, annotations, static imports,
enums, etc.
> -A richer (and significantly cleaner) template language (i.e. Jelly)
> -A more complete set of tags for traversing source code classes, including tags like
forAllPackages, forAllImportedTypes, forAllNestedTypes, forAllThrownTypes, etc.
> I already have everything implemented and integrated into the current maven jelly build.
 Attached are a few examples that show what this new library can do.  All examples output
properties files (these are examples I use for unit testing).

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
   http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
   http://www.atlassian.com/software/jira


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message