Remote proxy REST methods

Goals

• Simplify how remoteable interface proxies are exposed in the server and used in the clients.

User interaction and design

The goal on the server side is to simply map a method URL to a method using the existing @RestMethod annotation.  A new "PROXY" method name is used in place of the usual GET/PUT/POST/DELETE... 

/** 
 * Return a proxy interface to IAddressBook. 
 */ 
@RestMethod(name="PROXY", path="/proxy/*") 
public IAddressBook getProxy() { 
   return addressBookImpl; 
}

// or a new @RestProxy annotation?

@RestProxy(path="/proxy/*") 
public IAddressBook getProxy() { 
   return addressBookImpl; 
}

// or reuse the @Remoteable annotation?

@Remoteable(path="/proxy/*") 
public IAddressBook getProxy() { 
   return addressBookImpl; 
}

• A GET request against /proxy returns the method signatures that can be called on the interface.
• POST requests are used to invoke methods.  The signature for a method request with a String and boolean parameter would be...
• POST /resource-uri/proxy/callMyMethod(java.lang.String,boolean)
• The parameters are passed in the HTTP request body as an array of object (e.g. ["foo",true]).
• The response is serialized and sent back in the HTTP response body.
  
  

On the client side, the proxy is retrieved using the RestClient class:

IAddressBook ab = 
   new RestClientBuilder()
      .rootUrl(microserviceURI)
      .getRemoteableProxy(IAddressBook.class, "/addressBook/proxy");

Optionally, the @Remoteable annotation can be used to specify the URL on the client side....

@Remoteable(path="/addressBook/proxy")
public interface IAddressBook {
 ...
} 

@RestMethod(name="PROXY")  // Path not needed? 
public IAddressBook getProxy() { 
   ...
}

// or a new @RestProxy annotation with no path?

@RestProxy 
public IAddressBook getProxy() { 
   ... 
}
 

IAddressBook ab = 
   new RestClientBuilder()
      .rootUrl(microserviceURI)
      .getRemoteableProxy(IAddressBook.class);

Questions...

• Can the path on the @Remoteable annotation be used in leu of the path attribute in the @RestMethod annotation?  I'm not sure how that would work with the path defined on the servlet class.  Would we cause an error if @RestResource(path="/addressBook") is defined and the @Remoteable path does not start with /addressBook?
• Would the @Remoteable path be used by the RemoteableServlet as well?
• Can/should the @Remoteable path allow for absolute URLs as well?
• Can all of the necessary annotation and classes to treat a third-party end-point as a java interface be in the rest-client module?
• Can we support GET calls with parameters as well?  And differentiate which method should be used with an annotation on the interface?