More progress on the invocation services.

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

src/java/com/threerings/presents/server/InvocationProvider.java

@@ -0,0 +1,73 @@
+//
+// $Id: InvocationProvider.java,v 1.1 2001/07/19 18:08:20 mdb Exp $
+
+package com.threerings.cocktail.cher.server;
+
+/**
+ * Invocation providers should extend this class when implementing
+ * invocation services. Because the service procedures are identified by
+ * strings and the methods that are invoked are looked up via reflection,
+ * the derived class doesn't override or implement any particular method.
+ * However, the procedure names are still restricted. For example, a
+ * procedure identified by the name <code>Tell</code> would result in the
+ * invocation of a method named <code>handleTellRequest</code>. The
+ * arguments to that method would be defined by the arguments that
+ * accompanied the <code>Tell</code> invocation request. If the arguments
+ * do not match, a reflection error will happen when trying to invoke the
+ * method and the whole request will fail.
+ *
+ * <p> Invocation procedures must also package up their response in a
+ * particular way which is through the use of the
+ * <code>createResponse</code> methods. These take a response identifier
+ * (which determines the name of the method that will be invoked on the
+ * response target object provided in the client) and a variable number of
+ * arguments. If a response was created with the identifier
+ * <code>TellFailed</code>, that would result in the method
+ * <code>handleTellFailed</code> being invoked on the response target
+ * object in the client. Again the arguments much match exactly and follow
+ * the reflection rules for automatic conversion of primitive types
+ * (supply an <code>Integer</code> object for <code>int</code> params,
+ * etc.).
+ */
+public class InvocationProvider
+{
+    /**
+     * Creates a response array properly configured with the supplied name
+     * and single argument.
+     */
+    protected Object[] createResponse (String name, Object arg)
+    {
+        return new Object[] { name, null, arg };
+    }
+
+    /**
+     * Creates a response array properly configured with the supplied name
+     * and two arguments.
+     */
+    protected Object[] createResponse (String name, Object arg1, Object arg2)
+    {
+        return new Object[] { name, null, arg1, arg2 };
+    }
+
+    /**
+     * Creates a response array properly configured with the supplied name
+     * and three arguments.
+     */
+    protected Object[] createResponse (String name, Object arg1, Object arg2,
+                                       Object arg3)
+    {
+        return new Object[] { name, null, arg1, arg2, arg3 };
+    }
+
+    /**
+     * Creates a response array properly configured with the supplied name
+     * and varying number of arguments.
+     */
+    protected Object[] createResponse (String name, Object[] args)
+    {
+        Object[] rsp = new Object[args.length+2];
+        rsp[0] = name;
+        System.arraycopy(args, 0, rsp, 2, args.length);
+        return rsp;
+    }
+}