Skip to content
This repository

User documentation for DirectRestService. #105

Merged
merged 1 commit into from over 1 year ago

3 participants

bmustiata Christian Meier Constantino Cronemberger
bmustiata

This addresses this pull request:
#99

I apologize for the delay.

Christian Meier mkristian merged commit b9b1d4c into from September 20, 2012
Christian Meier mkristian closed this September 20, 2012
Christian Meier
Owner

thanx

Constantino Cronemberger

Isn't it easier to have an async interface, just like GWT-RPC, and have the generator checking if they are consistent with the server interface? The async interface can even be automatically generated.

I believe no.

Because then you need the tooling to integrate with your IDE, or your build process, and also you get one extra interface for no reason, that has a different signature than the serverside-one.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 1 unique commit by 1 author.

Sep 20, 2012
bmustiata Documented DirectRestService usage in the user documentation. 1cd0a6e
This page is out of date. Refresh to see the latest.
83  restygwt-website/src/documentation/restygwt-user-guide.md 100644 → 100755
Source Rendered
@@ -29,6 +29,15 @@ interface methods MUST return void.  Each method must declare at least one callb
29 29
 Methods can optionally declare one method argument before the callback to pass via the request
30 30
 body.
31 31
 
  32
+or if using REST.withCallback(..).call(..), you can reuse the same interface on the serverside as well:
  33
+
  34
+    import javax.ws.rs.POST;
  35
+    ...
  36
+    public interface PizzaService extends DirectRestService {
  37
+        @POST
  38
+        public OrderConfirmation order(PizzaOrder request);
  39
+    }
  40
+
32 41
 ### JAX/RS Subresource locators
33 42
 
34 43
 RestyGWT supports JAX/RS subresource locator methods as synchronous methods on service interfaces.  For instance:
@@ -537,4 +546,76 @@ and then implement `AnimalRestyTypeIdResolver` as follows:
537 546
 'AnimalRestyTypeIdResolver will be instantiated and interrogated at GWT compile time (deferred binding time, actually).  This code will not be compiled itself into
538 547
 javascript - just used to generate javascript classes that will be used to serialize your Jackson annotated pojos.
539 548
 
540  
-You can optionally implement RestyJsonTypeIdResolver on your TypeIdResolver class, in which case you do not need to include the configuration property setting.
  549
+You can optionally implement RestyJsonTypeIdResolver on your TypeIdResolver class, in which case you do not need to include the configuration property setting.
  550
+
  551
+### Reusing server interfaces.
  552
+
  553
+If you're using JAX-RS on the server-side as well, you might notice that you're repeating yourself in the client and
  554
+server interfaces, with only a minor change for the client interface (since the callback must be asynchronously). So if
  555
+you would have a JAX-RS service that just lists files, implemented like this:
  556
+
  557
+    public class ListFilesService
  558
+    {
  559
+        @Path("/files/list")
  560
+        @POST
  561
+        public List<FileVO> listFiles(@QueryParam("path") String path)
  562
+        {
  563
+            // actual logic to fetch the files.
  564
+        }
  565
+    }
  566
+
  567
+Your corresponding resty-gwt interface would be:
  568
+
  569
+    public interface ListFilesService extends RestService
  570
+    {
  571
+        @Path("/files/list")
  572
+        @POST
  573
+        public void listFiles(@QueryParam("path") String path, MethodCallback<List<FileVO>> callback);
  574
+    }
  575
+
  576
+Now if on the server the interface would change, let's assume a new "filter" parameter would be added, your service call
  577
+will fail at runtime, without giving you a chance to know this API contract is now invalidated at compile time.
  578
+
  579
+Using the new REST.withCallback().call() API this issue is addressed. How does it work?
  580
+
  581
+First you need now an interface that will extend the marker interface DirectRestService (not simply RestService):
  582
+
  583
+    public interface ListFilesService extends DirectRestService
  584
+    {
  585
+        @Path("/files/list")
  586
+        @POST
  587
+        public List<FileVO> listFiles(@QueryParam("path") String path);
  588
+    }
  589
+
  590
+Secondly, your server will just implement it:
  591
+
  592
+    public class ListFilesServiceImpl implements ListFilesService
  593
+    {
  594
+        @Override
  595
+        public List<FileVO> listFiles(String path)
  596
+        {
  597
+            // Logic to fetch the files. Annotations are being used from the interface, so there's no need to duplicate them here
  598
+        }
  599
+    }
  600
+
  601
+And third, clientside you will just declare it it:
  602
+
  603
+        ListFilesService listFilesService = GWT.create(ListFilesService.class);
  604
+
  605
+...and use it; since the calls are still async, you still need to provide a callback, and call it:
  606
+
  607
+        List<FileVO> noop = REST.withCallback(new MethodCallback<List<FileVO>>() {
  608
+            // callback implementation.
  609
+        }).call(listFilesService).listFiles("/mypath");
  610
+
  611
+Because the service is called asynchronously, the response returned by the listFiles method - from
  612
+call(listFilesService).listFiles("/mypath") - will always be null, and in this example
  613
+is being assigned just to enforce the check by the compiler of the return type as well.
  614
+
  615
+The parameters are the actual parameters sent to the service, and the response will be received by the callback.
  616
+
  617
+Since the same interface is reused, this is extremely well fit to changes, including service path,
  618
+response type or parameters changes. In case the API changes, the compilation will break.
  619
+
  620
+Thus you basically have now statically typed JSON services, with JAX-RS/Jackson on the serverside, and resty-gwt on the
  621
+clientside.
Commit_comment_tip

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.