You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mina.apache.org by ng...@apache.org on 2009/07/20 23:28:05 UTC

svn commit: r796025 - in /mina/sandbox/vysper/trunk/speccompliance/src/main/java/org: ./ apache/ apache/vysper/ apache/vysper/compliance/ apache/vysper/compliance/reporting/

Author: ngn
Date: Mon Jul 20 21:28:05 2009
New Revision: 796025

URL: http://svn.apache.org/viewvc?rev=796025&view=rev
Log:
Moving spec compliance code into its own module

Added:
    mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/
    mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/
    mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/
    mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/
    mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliance.java
    mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliant.java
    mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/reporting/
    mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/reporting/DocumentSpecCompliantAnnotationFactory.java

Added: mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliance.java
URL: http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliance.java?rev=796025&view=auto
==============================================================================
--- mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliance.java (added)
+++ mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliance.java Mon Jul 20 21:28:05 2009
@@ -0,0 +1,43 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ *
+ */
+
+package org.apache.vysper.compliance;
+
+import java.lang.annotation.*;
+
+/**
+ * collects more than one spec compliant annotation on the same entity.
+ * usage:
+ * <code>
+ * &#64;SpecCompliance(compliant = {
+ *      &#64;SpecCompliant(spec = "RFC3921", section = "7.7.7."),
+ *      &#64;SpecCompliant(spec = "RFC3921bis-06", section = "9.8.4")
+ *      &#64;SpecCompliant(spec = "RFC3921bis-06", section = "9.8.6", coverage = SpecCompliant.ComplianceCoverage.PARTIAL)
+ * })
+ * </code>
+ * 
+ * @author The Apache MINA Project (dev@mina.apache.org)
+ */
+@Documented
+@Retention(RetentionPolicy.SOURCE)
+@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD  })
+public @interface SpecCompliance {
+    SpecCompliant[] compliant();
+}

Added: mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliant.java
URL: http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliant.java?rev=796025&view=auto
==============================================================================
--- mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliant.java (added)
+++ mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/SpecCompliant.java Mon Jul 20 21:28:05 2009
@@ -0,0 +1,86 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ *
+ */
+
+package org.apache.vysper.compliance;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation is used to mark methods, types or packages that implement a
+ * specific RFC or a section of an RFC. Use the <code>status</code> parameter
+ * to specify the compliance level.
+ * 
+ * @author The Apache MINA Project (dev@mina.apache.org)
+ * 
+ */
+@Documented
+@Target( { ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
+@Retention(RetentionPolicy.SOURCE)
+public @interface SpecCompliant {
+	public enum ComplianceStatus {
+		NOT_STARTED, IN_PROGRESS, FINISHED
+	}
+
+	public enum ComplianceCoverage {
+		UNKNOWN,
+        UNSUPPORTED, // the spec is not supported
+        PARTIAL, // spec is partially covered 
+        COMPLETE // spec is completely covered
+	}
+
+	/**
+	 * References a RFC or XEP specification document.
+	 * 
+	 * @return the RFC or XEP 
+	 */
+	String spec();
+	
+	/**
+	 * References the section in the specificiation document the target implements.
+	 * 
+	 * @return the section/appendix number or an empty {@link String} in case
+	 *         the entire RFC is implemented by the target
+	 */
+	String section() default "";
+
+	/**
+	 * Specifies the status of the RFC compliance.
+	 * 
+	 * @return the compliance status
+	 */
+	ComplianceStatus status() default ComplianceStatus.IN_PROGRESS;
+
+    /**
+     * Specifies the level of coverage for the referenced spec/section. If known, the referenced spec extract
+     * can be covered fully or partially. In the latter case, other code might reference other parts of the the
+     * same extract. 
+     * @return coverage level
+     */
+	ComplianceCoverage coverage() default ComplianceCoverage.UNKNOWN;
+
+    /**
+     * short text being more specific on coverage and other implementational aspects 
+     */
+    String comment() default "";
+}

Added: mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/reporting/DocumentSpecCompliantAnnotationFactory.java
URL: http://svn.apache.org/viewvc/mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/reporting/DocumentSpecCompliantAnnotationFactory.java?rev=796025&view=auto
==============================================================================
--- mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/reporting/DocumentSpecCompliantAnnotationFactory.java (added)
+++ mina/sandbox/vysper/trunk/speccompliance/src/main/java/org/apache/vysper/compliance/reporting/DocumentSpecCompliantAnnotationFactory.java Mon Jul 20 21:28:05 2009
@@ -0,0 +1,323 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ *
+ */
+package org.apache.vysper.compliance.reporting;
+
+import com.sun.mirror.apt.AnnotationProcessor;
+import com.sun.mirror.apt.AnnotationProcessorEnvironment;
+import com.sun.mirror.apt.AnnotationProcessorFactory;
+import com.sun.mirror.apt.Filer;
+import com.sun.mirror.declaration.*;
+import org.apache.vysper.compliance.SpecCompliant;
+import org.apache.vysper.compliance.SpecCompliance;
+
+import static java.util.Collections.emptySet;
+import static java.util.Collections.unmodifiableCollection;
+import java.util.*;
+import java.io.PrintWriter;
+import java.io.IOException;
+import java.io.File;
+
+/**
+ * this generates from all SpecCompliant annotations a HTML doc to show what parts of the spec are covered.
+ * The table is sorted by implemented spec section and links out to the spec and the apidocs.
+ *
+ * apt can be invoked like this (tools.jar must be on the classpath)
+ * apt -cp build/ant/classes;lib/* -s src/main/java  -factory org.apache.vysper.compliance.reporting.DocumentSpecCompliantAnnotationFactory
+ * it generates a file spec_compliance.html in src/main/java
+ * 
+ * @author The Apache MINA Project (dev@mina.apache.org)
+ */
+public class DocumentSpecCompliantAnnotationFactory implements AnnotationProcessorFactory {
+    // Process any set of annotations
+    private static final Collection<String> supportedAnnotations
+        = unmodifiableCollection(Arrays.asList("org.apache.vysper.compliance.*"));
+
+    // No supported options
+    private static final Collection<String> supportedOptions = emptySet();
+
+    public Collection<String> supportedAnnotationTypes() {
+        return supportedAnnotations;
+    }
+
+    public Collection<String> supportedOptions() {
+        return supportedOptions;
+    }
+
+    public AnnotationProcessor getProcessorFor(
+            Set<AnnotationTypeDeclaration> atds,
+            AnnotationProcessorEnvironment env) {
+        return new SpecCompliantClassAP(env);
+    }
+
+    private static class SpecCompliantClassAP implements AnnotationProcessor {
+
+        protected final AnnotationProcessorEnvironment env;
+        protected AnnotationTypeDeclaration specCompliantAnnotation;
+        protected AnnotationTypeDeclaration specCompliantCollectionAnnotation;
+
+        protected Map<String, SpecDoc> map = new TreeMap<String, SpecDoc>();
+        protected PrintWriter fileWriter;
+
+        SpecCompliantClassAP(AnnotationProcessorEnvironment env) {
+            this.env = env;
+            specCompliantAnnotation = (AnnotationTypeDeclaration) env.getTypeDeclaration("org.apache.vysper.compliance.SpecCompliant");
+            specCompliantCollectionAnnotation = (AnnotationTypeDeclaration) env.getTypeDeclaration("org.apache.vysper.compliance.SpecCompliance");
+
+            try {
+                fileWriter = env.getFiler().createTextFile(Filer.Location.SOURCE_TREE, "", new File("spec_compliance.html"), null);
+            } catch (IOException e) {
+                throw new RuntimeException("could not write to output file", e);
+            }
+        }
+
+        public void process() {
+
+            // Retrieve all declarations with SpecCompliant annotations
+            Collection<Declaration> declarations = env.getDeclarationsAnnotatedWith(specCompliantAnnotation);
+            System.out.println("number of solitairy @SpecCompliant: " + declarations.size());
+            for (Declaration declaration : declarations) {
+                final SpecDoc doc = new SpecDoc(declaration, declaration.getAnnotation(SpecCompliant.class));
+                map.put(doc.getKey(), doc);
+            }
+
+            // Retrieve all SpecCompliance-typed declarations and extract SpecCompliant annotations 
+            Collection<Declaration> moreDeclarations = env.getDeclarationsAnnotatedWith(specCompliantCollectionAnnotation);
+            System.out.println("number of @SpecCompliance: " + moreDeclarations.size());
+            for (Declaration declaration : moreDeclarations) {
+                final SpecCompliance compliance = declaration.getAnnotation(SpecCompliance.class);
+                final SpecCompliant[] specCompliants = compliance.compliant();
+                for (SpecCompliant specCompliant : specCompliants) {
+                    if (specCompliant == null) continue;
+
+                    final SpecDoc doc = new SpecDoc(declaration, specCompliant);
+                    map.put(doc.getKey(), doc);
+                }
+            }
+
+            // visit every annotation fromt the now sorted map
+
+            // write the HTML file
+            fileWriter.println("<html><head>" +
+                    "<link rel='stylesheet' type='text/css' href='http://yui.yahooapis.com/2.7.0/build/reset-fonts-grids/reset-fonts-grids.css'>\n" +
+                    "<link rel='stylesheet' type='text/css' href='http://yui.yahooapis.com/2.7.0/build/base/base-min.css'>\n" + 
+                    "</head><body><table><thead><th>spec</th><th>section</th><th>package</th><th>class</th><th>field/method/etc.</th><th>coverage</th><th>implementation</th><th>comment</th></thead>");
+            for (String key : map.keySet()) {
+                fileWriter.print("<tr>");
+                System.out.println(key);
+                final SpecDoc doc = map.get(key);
+
+                // spec
+                fileWriter.print("<td>");
+                final String specURL = doc.getSpecDocURL();
+                if (specURL != null) fileWriter.print("<a href='" + specURL + "'>");
+                final String specDoc = doc.getSpecDoc();
+                if (specDoc != null) fileWriter.print(specDoc);
+                if (specURL != null) fileWriter.print("</a>"); 
+                fileWriter.print("</td>");
+
+
+                // spec section
+                fileWriter.print("<td>");
+                String specSection = doc.getSpecSection();
+                if (specSection != null && specSection.length() > 0) {
+                    if (specSection.endsWith(".")) specSection = specSection.substring(0, specSection.length() - 1);
+                    String anchorLink = Character.isDigit(specSection.charAt(0)) ? "#section-" : "#appendix-";  
+                    if (specURL != null) fileWriter.print("<a href='" + specURL + anchorLink + specSection + "'>");
+                    fileWriter.print(specSection);
+                    if (specURL != null) fileWriter.print("</a>");
+                }
+                fileWriter.print("</td>");
+
+
+                // package
+                fileWriter.print("<td>");
+                final String packageName = doc.getPackage();
+                if (packageName != null) {
+                    fileWriter.print(o_a_v_shortened(packageName));
+                }
+                fileWriter.print("</td>");
+
+                // class
+                fileWriter.print("<td>");
+                final String className = doc.getClassName();
+                if (className != null) {
+                    fileWriter.print("<a href='" + doc.getFQClassName().replace(".", "/") + ".html'>");
+                    fileWriter.print(o_a_v_cut(packageName, className));
+                    fileWriter.print("</a>");
+                }
+                fileWriter.print("</td>");
+
+
+                // class element
+                fileWriter.print("<td>");
+                final String member = doc.getMember();
+                if (member != null) {
+                    if (className != null) {
+                        fileWriter.print("<a href='" + className.replace(".", "/") + ".html#" + doc.getMemberAnchor().replace(",", ",%20") + "'>");
+                    }
+                    fileWriter.print(o_a_v_cut(packageName, member));
+                    if (className != null) {
+                        fileWriter.print("</a>");
+                    }
+                }
+                fileWriter.print("</td>");
+
+
+                // coverage
+                fileWriter.print("<td>");
+                final SpecCompliant.ComplianceCoverage coverage = doc.getCoverageLevel();
+                if (coverage != null) fileWriter.print(coverage.toString().toLowerCase());
+                fileWriter.print("</td>");
+
+
+                // status
+                fileWriter.print("<td>");
+                final SpecCompliant.ComplianceStatus complianceStatus = doc.getComplianceStatus();
+                if (complianceStatus != null) fileWriter.print(complianceStatus.toString().toLowerCase());
+                fileWriter.print("</td>");
+
+
+                // comment
+                fileWriter.print("<td>");
+                final String comment = doc.getComment();
+                if (comment != null) fileWriter.print(comment);
+                fileWriter.print("</td>");
+
+                fileWriter.println("</tr>");
+
+            }
+            fileWriter.println("</table></body>");
+        }
+
+        private String o_a_v_shortened(String packageString) {
+            if (packageString != null && packageString.contains("org.apache.vysper.")) return packageString.replace("org.apache.vysper.", "o.a.v.");
+            return packageString;
+        }
+
+        private String o_a_v_cut(String packageString, String memberString) {
+            if (memberString != null && memberString.contains(packageString + ".")) return memberString.replace(packageString + ".", "");
+            return memberString;
+        }
+
+    }
+
+    static class SpecDoc {
+
+        Declaration declaration;
+        SpecCompliant specCompliant;
+
+        SpecDoc(Declaration declaration, SpecCompliant specCompliant) {
+            this.declaration = declaration;
+            this.specCompliant = specCompliant;
+        }
+
+        public String getClassName() {
+            if (declaration instanceof FieldDeclaration || declaration instanceof MethodDeclaration) {
+                MemberDeclaration memberDeclaration = (MemberDeclaration) declaration;
+                return memberDeclaration.getDeclaringType().getQualifiedName();
+            } else {
+                return declaration.getSimpleName();
+            }
+        }
+
+        public String getFQClassName() {
+            if (declaration instanceof FieldDeclaration || declaration instanceof MethodDeclaration) {
+                MemberDeclaration memberDeclaration = (MemberDeclaration) declaration;
+                return memberDeclaration.getDeclaringType().getQualifiedName();
+            } else if(declaration instanceof ClassDeclaration) {
+                ClassDeclaration classDeclaration = (ClassDeclaration) declaration;
+                return classDeclaration.getPackage() + "." + classDeclaration.getSimpleName();
+            } else {
+                return declaration.getSimpleName();
+            }
+        }
+
+        public String getPackage() {
+            if (declaration instanceof TypeDeclaration ) {
+                TypeDeclaration typeDeclaration = (TypeDeclaration) declaration;
+                return typeDeclaration.getPackage().getQualifiedName(); 
+            } else if (declaration instanceof FieldDeclaration || declaration instanceof MethodDeclaration) {
+                MemberDeclaration memberDeclaration = (MemberDeclaration) declaration;
+                return memberDeclaration.getDeclaringType().getPackage().getQualifiedName();
+            } else {
+                return null;
+            }
+        }
+
+        public String getMember() {
+            if (declaration instanceof FieldDeclaration || declaration instanceof MethodDeclaration) {
+                MemberDeclaration memberDeclaration = (MemberDeclaration) declaration;
+                return declaration.getSimpleName();
+            } else {
+                return null;
+            }
+        }
+
+        public String getMemberAnchor() {
+            if (declaration instanceof FieldDeclaration || declaration instanceof MethodDeclaration) {
+                MemberDeclaration memberDeclaration = (MemberDeclaration) declaration;
+                return declaration.toString();
+            } else {
+                return null;
+            }
+        }
+
+        public String getKey() {
+            return getSpecDoc() + " " + getSpecSection() + " " + getClassName() + " " + getMember() + " " + getCoverageLevel() + " " + getComplianceStatus();
+        }
+
+        public String getSpecSection() {
+            return specCompliant.section();
+        }
+
+        public String getSpecDoc() {
+            final String specRaw = specCompliant.spec();
+            if (specRaw == null) return null;
+            return specRaw.toLowerCase();
+        }
+
+        public String getSpecDocURL() {
+            final String spec = getSpecDoc();
+            if (spec == null) return null;
+
+            if (spec.startsWith("xep")) return "http://xmpp.org/extensions/" + spec + ".html";
+            if (spec.startsWith("rfc")) {
+                if (!spec.contains("bis")) {
+                    return "http://tools.ietf.org/html/" + spec;
+                } else {
+                    return "http://tools.ietf.org/html/draft-saintandre-" + spec;
+                }
+            }
+            return null;
+        }
+
+        public SpecCompliant.ComplianceCoverage getCoverageLevel() {
+            return specCompliant.coverage();
+        }
+
+        public SpecCompliant.ComplianceStatus getComplianceStatus() {
+            return specCompliant.status();
+        }
+
+        public String getComment() {
+            return specCompliant.comment();
+        }
+    }
+}