[jboss-svn-commits] JBoss Common SVN: r4170 - invokablecontainer/trunk/api/src/main/java/org/jboss/invokable.

[jboss-svn-commits at lists.jboss.org]

Author: david.lloyd at jboss.com
Date: 2010-03-11 11:46:23 -0500 (Thu, 11 Mar 2010)
New Revision: 4170

Modified:
   invokablecontainer/trunk/api/src/main/java/org/jboss/invokable/Invocation.java
   invokablecontainer/trunk/api/src/main/java/org/jboss/invokable/InvocationContext.java
Log:
More javadocs

Modified: invokablecontainer/trunk/api/src/main/java/org/jboss/invokable/Invocation.java
===================================================================
--- invokablecontainer/trunk/api/src/main/java/org/jboss/invokable/Invocation.java	2010-03-11 14:42:01 UTC (rev 4169)
+++ invokablecontainer/trunk/api/src/main/java/org/jboss/invokable/Invocation.java	2010-03-11 16:46:23 UTC (rev 4170)
@@ -25,6 +25,7 @@
 import java.io.InvalidObjectException;
 import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
+import java.io.ObjectStreamField;
 import java.io.Serializable;
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
@@ -45,10 +46,40 @@
     private static final long serialVersionUID = 2691631710015102611L;
     private static final Field targetMethodField;
 
+    /**
+     * Serialization of an {@code Invocation} is handled specially.  The {@code args} and {@code context} fields are
+     * serialized normally, but because {@link Method} is not serializable, the {@code targetMethod} field is not directly
+     * serialized.  Instead, it is written (after the two aforementioned fields) as three distinct objects:
+     * <ol>
+     * <li><b>Declaring Class</b> - this is the result of {@code targetMethod.getDeclaringClass()}.</li>
+     * <li><b>Method Name</b> - this is the string name, as returned by {@code targetMethod.getName()}.</li>
+     * <li><b>Parameter Types</b> - this is an array of {@code Class} objects which represents the method's parameter
+     * types, as returned by {@code targetMethod.getParameterTypes()}.
+     * </ol>
+     * On deserialization, the method is then looked up on the declaring class.  If no valid, matching public method
+     * is found, an {@link java.io.InvalidObjectException} is thrown and deserialization fails.
+     */
+    private static final ObjectStreamField[] serialPersistentFields = {
+            new ObjectStreamField("args", Object[].class),
+            new ObjectStreamField("context", InvocationContext.class),
+    };
+
+    /**
+     * This field contains the method-call arguments.
+     *
+     * @serial
+     */
     private final Object[] args;
 
     @SuppressWarnings({ "InstanceVariableMayNotBeInitializedByReadObject" })
     private transient final Method targetMethod;
+
+    /**
+     * This field contains the invocation context.  As a special case, if the context is empty at serialization
+     * time, it is written as {@code null} to conserve bandwidth.
+     *
+     * @serial
+     */
     private volatile InvocationContext context;
 
     /**

Modified: invokablecontainer/trunk/api/src/main/java/org/jboss/invokable/InvocationContext.java
===================================================================
--- invokablecontainer/trunk/api/src/main/java/org/jboss/invokable/InvocationContext.java	2010-03-11 14:42:01 UTC (rev 4169)
+++ invokablecontainer/trunk/api/src/main/java/org/jboss/invokable/InvocationContext.java	2010-03-11 16:46:23 UTC (rev 4170)
@@ -21,9 +21,11 @@
  */
 package org.jboss.invokable;
 
+import java.io.Externalizable;
 import java.io.IOException;
-import java.io.ObjectInputStream;
-import java.io.ObjectOutputStream;
+import java.io.ObjectInput;
+import java.io.ObjectOutput;
+import java.io.ObjectStreamField;
 import java.io.Serializable;
 import java.util.Collections;
 import java.util.Map;
@@ -41,6 +43,12 @@
 
     private static final long serialVersionUID = -8786118177256759054L;
 
+    /**
+     * An {@code InvocationContext} is written by way of an {@code Externalizable} proxy object.  Thus, no fields
+     * are ever serialized for this object.
+     */
+    private static final ObjectStreamField[] serialPersistentFields = new ObjectStreamField[0];
+
     private transient final Map<Object, Object> backingMap;
 
     private InvocationContext(final Map<Object, Object> backingMap) {
@@ -186,35 +194,36 @@
         }
     }
 
-    static final class Serialized implements Serializable {
+    static final class Serialized implements Externalizable {
 
         private static final long serialVersionUID = -2451954101448516318L;
 
-        private transient Map<Object, Object> values;
+        private Map<Object, Object> values;
 
-        Serialized(final Map<Object, Object> values) {
+        public Serialized(final Map<Object, Object> values) {
             this.values = values;
         }
 
-        private void writeObject(ObjectOutputStream oos) throws IOException {
-            oos.defaultWriteObject();
-            oos.writeInt(values.size());
+        public Serialized() {
+        }
+
+        public void writeExternal(final ObjectOutput objectOutput) throws IOException {
+            objectOutput.writeInt(values.size());
             for (Map.Entry<Object, Object> entry : values.entrySet()) {
-                oos.writeObject(entry.getKey());
-                oos.writeObject(entry.getValue());
+                objectOutput.writeObject(entry.getKey());
+                objectOutput.writeObject(entry.getValue());
             }
         }
 
-        private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IOException {
-            ois.defaultReadObject();
-            final int len = ois.readInt();
+        public void readExternal(final ObjectInput objectInput) throws IOException, ClassNotFoundException {
+            final int len = objectInput.readInt();
             switch (len) {
                 case 0: values = Collections.emptyMap(); return;
-                case 1: values = Collections.singletonMap(ois.readObject(), ois.readObject()); return;
+                case 1: values = Collections.singletonMap(objectInput.readObject(), objectInput.readObject()); return;
             }
             values = new FastCopyHashMap<Object, Object>(len);
             for (int i = 0; i < len; i++) {
-                values.put(ois.readObject(), ois.readObject());
+                values.put(objectInput.readObject(), objectInput.readObject());
             }
         }