Add the @Generated annotation to Marshaller/Receiver classes

and various dobj bits. The @Generated annotation is "@Documented" and
retained at source only.


git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@6049 542714f4-19e9-0310-aa3c-eee0fc999fb1

src/java/com/threerings/presents/tools/GenDObjectTask.java

@@ -171,6 +171,7 @@ public class GenDObjectTask extends Task
             // create our velocity context
             VelocityContext ctx = new VelocityContext();
             ctx.put("field", fname);
+            ctx.put("generated", GenUtil.getGeneratedAnnotation(getClass(), 4));
             ctx.put("type", GenUtil.simpleName(f));
             ctx.put("wrapfield", GenUtil.boxArgument(ftype, "value"));
             ctx.put("wrapofield", GenUtil.boxArgument(ftype, "ovalue"));

src/java/com/threerings/presents/tools/GenServiceTask.java

@@ -265,6 +265,7 @@ public class GenServiceTask extends InvocationTask
 
         VelocityContext ctx = new VelocityContext();
         ctx.put("name", name);
+        ctx.put("generated", getGeneratedAnnotation());
         ctx.put("package", mpackage);
         ctx.put("methods", sdesc.methods);
         ctx.put("listeners", sdesc.listeners);
@@ -536,6 +537,7 @@ public class GenServiceTask extends InvocationTask
 
         VelocityContext ctx = new VelocityContext();
         ctx.put("name", name);
+        ctx.put("generated", getGeneratedAnnotation());
         ctx.put("package", dpackage);
         ctx.put("methods", sdesc.methods);
         ctx.put("imports", imports.toList());
@@ -594,6 +596,7 @@ public class GenServiceTask extends InvocationTask
 
         VelocityContext ctx = new VelocityContext();
         ctx.put("name", name);
+        ctx.put("generated", getGeneratedAnnotation());
         ctx.put("package", mpackage);
         ctx.put("methods", sdesc.methods);
         ctx.put("listeners", sdesc.listeners);
@@ -610,6 +613,15 @@ public class GenServiceTask extends InvocationTask
         writeFile(mpath, sw.toString());
     }
 
+    /**
+     * Helper to get the appropriate "@Generated" annotation for service classes.
+     */
+    protected String getGeneratedAnnotation ()
+    {
+        return GenUtil.getGeneratedAnnotation(getClass(), 0,
+            "Derived from the Service class java source.");
+    }
+
     /** Rolls up everything needed for the generate* methods. */
     protected class ServiceDescription
     {

src/java/com/threerings/presents/tools/GenUtil.java

@@ -24,6 +24,9 @@ package com.threerings.presents.tools;
 import java.lang.reflect.Field;
 import java.lang.reflect.Type;
 
+import java.text.SimpleDateFormat;
+
+import java.util.Date;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
@@ -237,4 +240,34 @@ public class GenUtil extends com.samskivert.util.GenUtil
 
         return name;
     }
+
+    /**
+     * Return an "@Generated" annotation.
+     *
+     * @param clazz the class doing the code generation, NOT the generation target.
+     * @param indent the number of spaces that the annotation is indented.
+     * @param comments joined by a space and used as explanatory comments.
+     */
+    public static String getGeneratedAnnotation (Class<?> clazz, int indent, String... comments)
+    {
+        final int LINE_LENGTH = 100;
+        String comm = StringUtil.join(comments, " ");
+        boolean hasComment = !StringUtil.isBlank(comm);
+        String anno = "@Generated(value={\"" + clazz.getName() + "\"},";
+        // ISO 8601 date
+        String date = " date=\"" +
+            new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ").format(new Date()) + "\"";
+        // wrap the date onto a new line if it's going to be too long, or if we're
+        // adding a comment (which is also on a new line)
+        if (hasComment || anno.length() + date.length() + 1 + indent > LINE_LENGTH) {
+            // put the date on a new line, space it right
+            date = "\n" + StringUtil.fill(' ', indent + 10) + date;
+        }
+        anno += date;
+        if (hasComment) {
+            anno += ",\n" + StringUtil.fill(' ', indent + 11) + "comments=\"" + comm + "\"";
+        }
+        anno += ")";
+        return anno;
+    }
 }

src/java/com/threerings/presents/tools/SourceFile.java

@@ -53,6 +53,7 @@ public class SourceFile
         while ((line = bin.readLine()) != null) {
             llist.add(line);
         }
+        maybeAddGeneratedImport(llist);
         _lines = llist.toArray(new String[llist.size()]);
         bin.close();
 
@@ -214,6 +215,45 @@ public class SourceFile
         bout.newLine();
     }
 
+    /**
+     * Add an import for "@Generated", if needed.
+     */
+    protected void maybeAddGeneratedImport (ArrayList<String> lines)
+    {
+        final String IMPORT = "import javax.annotation.Generated;";
+
+        int packageLine = -1;
+        int lastJavaImport = -1;
+        int firstNonJavaImport = -1;
+        for (int ii = 0, nn = lines.size(); ii < nn; ii++) {
+            String line = lines.get(ii).trim();
+            if (line.equals(IMPORT)) {
+                return; // we already got one!
+
+            } else if (line.startsWith("package ")) {
+                packageLine = ii;
+
+            } else if (line.startsWith("import java")) {
+                lastJavaImport = ii;
+
+            } else if (firstNonJavaImport == -1 && line.startsWith("import ")) {
+                firstNonJavaImport = ii;
+            }
+        }
+
+        int insertPoint;
+        if (lastJavaImport != -1) {
+            insertPoint = lastJavaImport + 1;
+
+        } else if (firstNonJavaImport != -1) {
+            insertPoint = firstNonJavaImport;
+
+        } else {
+            insertPoint = packageLine + 1;
+        }
+        lines.add(insertPoint, IMPORT);
+    }
+
     protected String[] _lines;
 
     protected int _nstart = -1, _nend = -1;

src/java/com/threerings/presents/tools/dispatcher.tmpl

@@ -1,5 +1,7 @@
 package $package;
 
+import javax.annotation.Generated;
+
 #foreach ($import in $imports)
 import $import;
 #end
@@ -7,6 +9,7 @@ import $import;
 /**
  * Dispatches requests to the {@link ${name}Provider}.
  */
+${generated}
 public class ${name}Dispatcher extends InvocationDispatcher<${name}Marshaller>
 {
     /**

src/java/com/threerings/presents/tools/dobject_field.tmpl

@@ -6,6 +6,7 @@
      * clients) will apply the value change when they received the
      * attribute changed notification.
      */
+    ${generated}
     public void set$upfield ($type value)
     {
         $type ovalue = this.$field;
@@ -24,6 +25,7 @@
      * will apply the value change when they received the attribute
      * changed notification.
      */
+    ${generated}
     public void set${upfield}At ($elemtype value, int index)
     {
         $elemtype ovalue = this.$field[index];

src/java/com/threerings/presents/tools/dobject_name.tmpl

@@ -1,2 +1,3 @@
     /** The field name of the <code>$field</code> field. */
+    ${generated}
     public static final String $capfield = "$field";

src/java/com/threerings/presents/tools/dobject_oidlist.tmpl

@@ -3,6 +3,7 @@
      * oid list. The list will not change until the event is actually
      * propagated through the system.
      */
+    ${generated}
     public void addTo$upfield (int oid)
     {
         requestOidAdd($capfield, oid);
@@ -13,6 +14,7 @@
      * <code>$field</code> oid list. The list will not change until the
      * event is actually propagated through the system.
      */
+    ${generated}
     public void removeFrom$upfield (int oid)
     {
         requestOidRemove($capfield, oid);

src/java/com/threerings/presents/tools/dobject_set.tmpl

@@ -3,6 +3,7 @@
      * <code>$field</code> set. The set will not change until the event is
      * actually propagated through the system.
      */
+    ${generated}
     public void addTo$upfield ($etype elem)
     {
         requestEntryAdd($capfield, $field, elem);
@@ -13,6 +14,7 @@
      * the <code>$field</code> set. The set will not change until the
      * event is actually propagated through the system.
      */
+    ${generated}
     public void removeFrom$upfield (Comparable<?> key)
     {
         requestEntryRemove($capfield, $field, key);
@@ -23,6 +25,7 @@
      * <code>$field</code> set. The set will not change until the event is
      * actually propagated through the system.
      */
+    ${generated}
     public void update$upfield ($etype elem)
     {
         requestEntryUpdate($capfield, $field, elem$transport);
@@ -38,6 +41,7 @@
      * change. Proxied copies of this object (on clients) will apply the
      * value change when they received the attribute changed notification.
      */
+    ${generated}
     public void set$upfield ($type value)
     {
         requestAttributeChange($capfield, value, this.$field);

src/java/com/threerings/presents/tools/marshaller.tmpl

@@ -1,5 +1,7 @@
 package $package;
 
+import javax.annotation.Generated;
+
 #foreach ($import in $imports)
 import $import;
 #end
@@ -11,6 +13,7 @@ import $import;
  * interfaces that marshall the response arguments and deliver them back
  * to the requesting client.
  */
+${generated}
 public class ${name}Marshaller extends InvocationMarshaller
     implements ${name}Service
 {

src/java/com/threerings/presents/tools/provider.tmpl

@@ -1,5 +1,7 @@
 package $package;
 
+import javax.annotation.Generated;
+
 #foreach ($import in $imports)
 import $import;
 #end
@@ -7,6 +9,7 @@ import $import;
 /**
  * Defines the server-side of the {@link ${name}Service}.
  */
+${generated}
 public interface ${name}Provider extends InvocationProvider
 {
 #foreach ($m in $methods)