Changes in a49dc88: Described the development use case "Add a GWT RPC service"

				wiki/typical-development-scenarios.md
			
          @@ -21,6 +21,24 @@ Add a New Library which can not be found in any SAP Repository

           *	Select the features of the p2 repository you want to use in the project

           *	Reload the target platform

          +## Adding a GWT RPC Service

          +

          +We use a few GWT RPC services which offer easy serialization and asynchronous callback across the wire in a type-safe way. Historically, there was a single service covering a lot of ground: the SailingService. Over time, this service was split into several, including UserManagementService and MediaService.

          +

          +One challenge we faced was that the default URL under which a client-side service would expect the servlet is simply constructed by appending the relative service URL provided in the `@RemoteServiceRelativePath` annotation to the URL that hosts the current .html document that loaded the entry point. This, however, does not work for servlets exposed by OSGi web bundles such as the `com.sap.sailing.gwt.ui` bundle. Web bundles define in their MANIFEST.MF a Web-ContextRoot which is used as a prefix to all servlet URLs. In the case of the `com.sap.sailing.gwt.ui` bundle this is `/gwt`.

          +

          +To change the URL that a client-side service uses to construct the requests to the servlet, a dirty trick is required. The implementation of the service proxy generated by using something like `GWT.create(SailingService.class)` also implements the `com.google.gwt.user.client.rpc.ServiceDefTarget` interface. Casting the service proxy returned by the `GWT.create(...)` call to this interface allows us to set the service's entry point. Here is an excerpt of the method `AbstractEntryPoint.doOnModuleLoad()`:

          +

          +<pre>

          +        ServiceDefTarget sailingServiceDef = (ServiceDefTarget) sailingService;

          +        ...

          +        String moduleBaseURL = GWT.getModuleBaseURL();

          +        String baseURL = moduleBaseURL.substring(0, moduleBaseURL.lastIndexOf('/', moduleBaseURL.length()-2)+1);

          +        sailingServiceDef.setServiceEntryPoint(baseURL + "sailing");

          +</pre>

          +

          +Whenever you add another GWT RPC service, make sure to add it to the list of services whose service entry point URL is adjusted in `AbstractEntryPoint.doOnModuleLoad()`.

          +

           ## Adding a GWT Library to the com.sap.sailing.gwt.ui Project

           *	Copy the library (the jar file) to the folder /WEB-INF/lib

           *	Add the library to the bundle classpath (in the META-INF/manifest.mf file)

...	...	@@ -21,6 +21,24 @@ Add a New Library which can not be found in any SAP Repository
21	21	* Select the features of the p2 repository you want to use in the project
22	22	* Reload the target platform
23	23
	24	+## Adding a GWT RPC Service
	25	+
	26	+We use a few GWT RPC services which offer easy serialization and asynchronous callback across the wire in a type-safe way. Historically, there was a single service covering a lot of ground: the SailingService. Over time, this service was split into several, including UserManagementService and MediaService.
	27	+
	28	+One challenge we faced was that the default URL under which a client-side service would expect the servlet is simply constructed by appending the relative service URL provided in the `@RemoteServiceRelativePath` annotation to the URL that hosts the current .html document that loaded the entry point. This, however, does not work for servlets exposed by OSGi web bundles such as the `com.sap.sailing.gwt.ui` bundle. Web bundles define in their MANIFEST.MF a Web-ContextRoot which is used as a prefix to all servlet URLs. In the case of the `com.sap.sailing.gwt.ui` bundle this is `/gwt`.
	29	+
	30	+To change the URL that a client-side service uses to construct the requests to the servlet, a dirty trick is required. The implementation of the service proxy generated by using something like `GWT.create(SailingService.class)` also implements the `com.google.gwt.user.client.rpc.ServiceDefTarget` interface. Casting the service proxy returned by the `GWT.create(...)` call to this interface allows us to set the service's entry point. Here is an excerpt of the method `AbstractEntryPoint.doOnModuleLoad()`:
	31	+
	32	+<pre>
	33	+ ServiceDefTarget sailingServiceDef = (ServiceDefTarget) sailingService;
	34	+ ...
	35	+ String moduleBaseURL = GWT.getModuleBaseURL();
	36	+ String baseURL = moduleBaseURL.substring(0, moduleBaseURL.lastIndexOf('/', moduleBaseURL.length()-2)+1);
	37	+ sailingServiceDef.setServiceEntryPoint(baseURL + "sailing");
	38	+</pre>
	39	+
	40	+Whenever you add another GWT RPC service, make sure to add it to the list of services whose service entry point URL is adjusted in `AbstractEntryPoint.doOnModuleLoad()`.
	41	+
24	42	## Adding a GWT Library to the com.sap.sailing.gwt.ui Project
25	43	* Copy the library (the jar file) to the folder /WEB-INF/lib
26	44	* Add the library to the bundle classpath (in the META-INF/manifest.mf file)