Bug 1144 - Add 'DelegateImplementation', manually impl. may delegate to renamed original

'DelegateImplementation' is a variation of 'ManuallyImplement'.

'ManuallyImplement' emits the interface method, but suppresses
the Java and native-code implementation.
The latter shall be implemented manually by the user.

'DelegateImplementation' emits the interface method,
and the _private_ renamed Java and native-code implementation.
Both can be called from the manual user implementation,
hence delegation.

Configuration:
  DelegateImplementation <ORIG-SYMBOL> <RENAMED-IMPL-SYMBOL>

I.e. delegation model shall apply to <ORIG-SYMBOL>
and the Java and native-code implementation renamed to <RENAMED-IMPL-SYMBOL>.

The user manual implementation of <ORIG-SYMBOL>
may delegate to <RENAMED-IMPL-SYMBOL>.

7 files changed, 124 insertions, 10 deletions

diff --git a/src/java/com/jogamp/gluegen/JavaConfiguration.java b/src/java/com/jogamp/gluegen/JavaConfiguration.java
index 969eaaf..987d27a 100644
--- a/src/java/com/jogamp/gluegen/JavaConfiguration.java
+++ b/src/java/com/jogamp/gluegen/JavaConfiguration.java
@@ -159,6 +159,7 @@ public class JavaConfiguration {
     private boolean forceUseNIODirectOnly4All = false;
     private final Set<String> useNIODirectOnly = new HashSet<String>();
     private final Set<String> manuallyImplement = new HashSet<String>();
+    private final Map<String, String> delegatedImplementation = new HashMap<String, String>();
     private final Set<String> manualStaticInitCall = new HashSet<String>();
     private final Set<String> forceStaticInitCode = new HashSet<String>();
     private final Map<String, List<String>> customJavaCode = new HashMap<String, List<String>>();
@@ -876,6 +877,54 @@ public class JavaConfiguration {
   }
 
   /**
+   * Variant of {@link #getDelegatedImplementation(AliasedSymbol)},
+   * where this method only considers the {@link AliasedSymbol#getName() current-name}
+   * of the given symbol, not the {@link #getJavaSymbolRename(String) renamed-symbol}.
+   */
+  public String getDelegatedImplementation(final String functionName) {
+      final String res = delegatedImplementation.get(functionName);
+      if( null == res ) {
+          return null;
+      }
+      LOG.log(INFO, "DelegatedImplementation: {0}", functionName);
+      return res;
+  }
+
+  /**
+   * Returns the {@code RENAMED-IMPL-SYMBOL} if the implementation of the glue code
+   * of the given function shall be manually delegated by the end user.
+   * <p>
+   * {@code DelegateImplementation <ORIG-SYMBOL> <RENAMED-IMPL-SYMBOL>}
+   * </p>
+   * <p>
+   * The interface is emitted unchanged.
+   * </p>
+   * <p>
+   * The Java and native-code implementation is renamed to {@code RENAMED-IMPL-SYMBOL}.
+   * The user's manual implementation of {@code ORIG-SYMBOL}
+   * may delegate to {@code RENAMED-IMPL-SYMBOL}.
+   * </p>
+   * <p>
+   * If symbol references a struct field or method, see {@link #canonicalStructFieldSymbol(String, String)},
+   * it describes field's array-length or element-count referenced by a pointer.
+   * </p>
+   */
+  public String getDelegatedImplementation(final AliasedSymbol symbol) {
+      final String name = symbol.getName();
+      final Set<String> aliases = symbol.getAliasedNames();
+
+      String res = delegatedImplementation.get(name);
+      if( null == res ) {
+          res = oneInMap(delegatedImplementation, aliases);
+          if( null == res ) {
+              return null;
+          }
+      }
+      LOG.log(INFO, getASTLocusTag(symbol), "DelegatedImplementation: {0}", symbol.getAliasedString());
+      return res;
+  }
+
+  /**
    * Variant of {@link #shouldIgnoreInInterface(AliasedSymbol)},
    * where this method only considers the {@link AliasedSymbol#getName() current-name}
    * of the given symbol, not the {@link #getJavaSymbolRename(String) renamed-symbol}.
@@ -1078,6 +1127,16 @@ public class JavaConfiguration {
     origNames.add(origName);
   }
 
+  /** Programmatically adds a delegate implementation directive for the given symbol. */
+  public void addDelegateImplementation(final String origName, final String renamedImpl) {
+    LOG.log(INFO, "\tDelegateImplementation {0} -> {1}", origName, renamedImpl);
+    final String prevValue = delegatedImplementation.put(origName, renamedImpl);
+    if(null != prevValue && !prevValue.equals(renamedImpl)) {
+        throw new RuntimeException("Rename-Override Attampt: "+origName+" -> "+renamedImpl+
+                                   ", but "+origName+" -> "+prevValue+" already exist. Run in 'debug' mode to analyze!");
+    }
+  }
+
   /** Returns true if the emission style is AllStatic. */
   public boolean allStatic() {
     return emissionStyle == AllStatic;
@@ -1265,6 +1324,8 @@ public class JavaConfiguration {
       readRenameJavaType(tok, filename, lineNo);
     } else if (cmd.equalsIgnoreCase("RenameJavaSymbol")) {
       readRenameJavaSymbol(tok, filename, lineNo);
+    } else if (cmd.equalsIgnoreCase("DelegateImplementation")) {
+      readDelegateImplementation(tok, filename, lineNo);
     } else if (cmd.equalsIgnoreCase("RuntimeExceptionType")) {
       runtimeExceptionType = readString("RuntimeExceptionType", tok, filename, lineNo);
     } else if (cmd.equalsIgnoreCase("UnsupportedExceptionType")) {
@@ -1798,6 +1859,17 @@ public class JavaConfiguration {
     }
   }
 
+  public void readDelegateImplementation(final StringTokenizer tok, final String filename, final int lineNo) {
+    try {
+      final String fromName = tok.nextToken();
+      final String toName   = tok.nextToken();
+      addDelegateImplementation(fromName, toName);
+    } catch (final NoSuchElementException e) {
+      throw new RuntimeException("Error parsing \"DelegateImplementation\" command at line " + lineNo +
+        " in file \"" + filename + "\": missing expected parameter", e);
+    }
+  }
+
   protected void readJavaPrologueOrEpilogue(final StringTokenizer tok, final String filename, final int lineNo, final boolean prologue) {
     try {
       String methodName = tok.nextToken();
diff --git a/src/java/com/jogamp/gluegen/JavaEmitter.java b/src/java/com/jogamp/gluegen/JavaEmitter.java
index fa4ecab..2601929 100644
--- a/src/java/com/jogamp/gluegen/JavaEmitter.java
+++ b/src/java/com/jogamp/gluegen/JavaEmitter.java
@@ -568,12 +568,6 @@ public class JavaEmitter implements GlueEmitter {
           return;
       }
 
-      final MethodAccess accessControl = cfg.accessControl(binding.getName());
-      // We should not emit anything except public APIs into interfaces
-      if (signatureOnly && (accessControl != PUBLIC)) {
-          return;
-      }
-
       // It's possible we may not need a body even if signatureOnly is
       // set to false; for example, if the routine doesn't take any
       // arrays or buffers as arguments
@@ -596,6 +590,20 @@ public class JavaEmitter implements GlueEmitter {
       final boolean emitBody = !signatureOnly && needsBody;
       final boolean isNativeMethod = !isUnimplemented && !needsBody && !signatureOnly;
 
+      final MethodAccess accessControl;
+
+      if ( !signatureOnly && null != binding.getDelegationImplName() ) {
+          // private access for delegation implementation methods
+          accessControl = PRIVATE;
+      } else {
+          accessControl = cfg.accessControl(binding.getName());
+      }
+
+      // We should not emit anything except public APIs into interfaces
+      if ( signatureOnly && PUBLIC != accessControl ) {
+          return;
+      }
+
       final PrintWriter writer = ((signatureOnly || cfg.allStatic()) ? javaWriter() : javaImplWriter());
 
       final JavaMethodBindingEmitter emitter =
@@ -2801,8 +2809,9 @@ public class JavaEmitter implements GlueEmitter {
       javaArgumentTypes.add(mappedType);
       //System.out.println("During binding of [" + sym + "], added mapping from C type: " + cArgType + " to Java type: " + mappedType);
     }
+    final String delegationImplName = null == containingType && null == containingCType ?
+                                      cfg.getDelegatedImplementation(sym) : null;
     final MethodBinding mb = new MethodBinding(sym, delegationImplName,
-    final MethodBinding mb = new MethodBinding(sym, 
                                                javaReturnType, javaArgumentTypes,
                                                containingType, containingCType);
     mangleBinding(mb);
diff --git a/src/java/com/jogamp/gluegen/MethodBinding.java b/src/java/com/jogamp/gluegen/MethodBinding.java
index 5b0290a..278fea0 100644
--- a/src/java/com/jogamp/gluegen/MethodBinding.java
+++ b/src/java/com/jogamp/gluegen/MethodBinding.java
@@ -52,6 +52,7 @@ import java.util.List;
 public class MethodBinding {
 
   private final FunctionSymbol sym;
+  private final String   delegationImplName;
   private final JavaType containingType;
   private final Type     containingCType;
   private String         nativeName;
@@ -77,6 +78,7 @@ public class MethodBinding {
    */
   public MethodBinding(final MethodBinding bindingToCopy) {
     this.sym                              = bindingToCopy.sym;
+    this.delegationImplName               = bindingToCopy.delegationImplName;
     this.containingType                   = bindingToCopy.containingType;
     this.containingCType                  = bindingToCopy.containingCType;
 
@@ -105,11 +107,13 @@ public class MethodBinding {
    * </p>
    */
   public MethodBinding(final FunctionSymbol sym,
+                       final String delegationImplName,
                        final JavaType javaReturnType,
                        final List<JavaType> javaArgumentTypes,
                        final JavaType containingType,
                        final Type containingCType) {
     this.sym = sym;
+    this.delegationImplName = delegationImplName;
     this.containingType = containingType;
     this.containingCType = containingCType;
 
@@ -173,16 +177,28 @@ public class MethodBinding {
     public String getName() {
         return sym.getName();
     }
+    /**
+     * The
+     * {@link JavaConfiguration#getDelegatedImplementation(com.jogamp.gluegen.cgram.types.AliasedSymbol) implementation delegation}
+     * name, or {@code null} for no delegation.
+     * @see #getImplName()
+     */
+    public String getDelegationImplName() {
+        return delegationImplName;
+    }
+
     /** Returns the {@link FunctionSymbol}'s current {@link FunctionSymbol#getName() aliased} API name for the interface. */
     public String getInterfaceName() {
         return sym.getName();
     }
     /**
      * Returns the {@link FunctionSymbol}'s name for the implementation,
-     * which is the current {@link FunctionSymbol#getName() aliased} API name per default.
+     * which is the current {@link FunctionSymbol#getName() aliased} API name per default,
+     * or the {@link #getDelegationImplName() delegation} name.
+     * @see #getDelegationImplName()
      */
     public String getImplName() {
-        return sym.getName();
+        return null != delegationImplName ? delegationImplName : sym.getName();
     }
     /**
      * Returns the {@link FunctionSymbol}'s name for the native function
diff --git a/src/junit/com/jogamp/gluegen/test/junit/generation/BaseClass.java b/src/junit/com/jogamp/gluegen/test/junit/generation/BaseClass.java
index 92015dd..75ef808 100644
--- a/src/junit/com/jogamp/gluegen/test/junit/generation/BaseClass.java
+++ b/src/junit/com/jogamp/gluegen/test/junit/generation/BaseClass.java
@@ -77,7 +77,7 @@ public class BaseClass extends SingletonJunitCase {
      * ie a compilation only coverage test without functional tests.
      */
     public void chapter__TestCoverageSignature(final Bindingtest1 binding) throws Exception {
-          int i;
+          int i = 0;
           final long context = 0;
           LongBuffer lb=null;
           ByteBuffer bb=null;
@@ -119,6 +119,8 @@ public class BaseClass extends SingletonJunitCase {
 
               lb = binding.testFooPtr(larray, 0);
               lb = binding.testFooPtr(lb);
+
+              i = binding.testDelegate(i);
           }
 
           {
@@ -712,6 +714,11 @@ public class BaseClass extends SingletonJunitCase {
               Assert.assertEquals(fooLB, foo2Out);
           }
 
+          {
+              i=41;
+              final int iRes = binding.testDelegate(i);
+              Assert.assertEquals(i+1, iRes);
+          }
     }
 
     public void chapter04TestPointerBuffer(final Bindingtest1 binding) throws Exception {
diff --git a/src/junit/com/jogamp/gluegen/test/junit/generation/test1-common.cfg b/src/junit/com/jogamp/gluegen/test/junit/generation/test1-common.cfg
index 29c13fa..6c516c2 100644
--- a/src/junit/com/jogamp/gluegen/test/junit/generation/test1-common.cfg
+++ b/src/junit/com/jogamp/gluegen/test/junit/generation/test1-common.cfg
@@ -46,6 +46,10 @@ Opaque long TK_Context
 RenameJavaSymbol DEFINE_01_EXT DEFINE_01
 RenameJavaSymbol testXID_EXT testXID
 
+DelegateImplementation testDelegate testDelegateOrigImpl
+IncludeAs CustomJavaCode Bindingtest1p1Impl test1-CustomJavaCode.cfg
+IncludeAs CustomJavaCode Bindingtest1p2Impl test1-CustomJavaCode.cfg
+
 StructPackage TK_Dimension com.jogamp.gluegen.test.junit.generation
 EmitStruct TK_Dimension
 StructPackage TK_DimensionPair com.jogamp.gluegen.test.junit.generation
diff --git a/src/junit/com/jogamp/gluegen/test/junit/generation/test1.c b/src/junit/com/jogamp/gluegen/test/junit/generation/test1.c
index 316603b..0683600 100644
--- a/src/junit/com/jogamp/gluegen/test/junit/generation/test1.c
+++ b/src/junit/com/jogamp/gluegen/test/junit/generation/test1.c
@@ -65,6 +65,10 @@ MYAPI foo MYAPIENTRY nopTest() {
     return 42;
 }
 
+MYAPI int32_t MYAPIENTRY testDelegate(int32_t v) {
+   return v; 
+}
+
 /**
  * new blob sizeof(void*) filled w/ 0xDEADBEEF
  */
diff --git a/src/junit/com/jogamp/gluegen/test/junit/generation/test1.h b/src/junit/com/jogamp/gluegen/test/junit/generation/test1.h
index b176f3a..6e826c5 100644
--- a/src/junit/com/jogamp/gluegen/test/junit/generation/test1.h
+++ b/src/junit/com/jogamp/gluegen/test/junit/generation/test1.h
@@ -111,6 +111,8 @@ MYAPI foo_ptr MYAPIENTRY testFooPtr(foo_ptr v);
 /** Returns 42 */
 MYAPI foo MYAPIENTRY nopTest();
 
+MYAPI int32_t MYAPIENTRY testDelegate(int32_t v);
+
 //
 // Different pointer type tests ..
 //