Getting Started with DataSnap Mobile Connectors

From RAD Studio
Jump to: navigation, search

Go Up to DataSnap Connectors for Mobile Devices


DataSnap Mobile Connectors are a framework that you can use to access the services on a DataSnap REST Server, enabling the invocation of server methods in much the same way that the other DataSnap proxy generators do.

Supported Platforms

The following mobile platforms are currently supported by the various DataSnap Connectors:

  • iOS 4.x, 5.x, 6.x, 7.x (Objective-C)
  • Android 2.x, 3.x, or 4.x (Java)
  • Windows Phone 7 (C#Silverlight--all devices compatible with the platform)
  • BlackBerry Java SDK 5 and 6 (Java)

How the DataSnap Connectors Work

DataSnap Connectors provide a new Proxy Dispatcher that works together with the pre-existing proxy generator, metadata provider, and server class components. This proxy dispatcher provides functionality that allows for developers on remote machines to generate a proxy on the server and download it onto the developer's machine. This new proxy dispatching service is introduced because this mobile development will not be done within RAD Studio.

To begin mobile development with DataSnap, the first step is to properly set up your DataSnap Server for proxy dispatching, so that you can generate the mobile platform's proxy. For example, when developing an Android application, you need the DSProxy.java file, which contains the code generated by the server. You also need the com.embarcadero.javaandroid package, which contains the additional static files required by the proxy. These static files are mostly the data types, such as TStream, that correspond to Delphi data types supported by DataSnap.

How the IDE Assists You with DataSnap Mobile Connectors

The DataSnap wizards have a Mobile Connectors check box. If you enable the Mobile Connectors check box, the wizard does the following automatically:

  • Sets up the "proxy" directory and the Connector components (proxy generator, metadata provider, and proxy dispatcher) for you.
  • Generates a post-build event that copies the static file directories (proxy, js, templates, css, images) into your project's output location. (If you manually set the project's output location to "." or to any relative or absolute path that resolves to the project's root directory, the copy is skipped.) The same post-build event is created for a project that includes the JavaScript REST file (DataSnap REST Application Wizard).

How to Generate a Proxy

To configure your DataSnap server for proxy dispatching, you first need to make sure it is properly configured for proxy generation.

The following screenshot shows the components needed to enable a DataSnap REST server to generate the proxies:

DScomponents.png

The following list displays the required components and a brief description of the task each accomplishes:

  • TDSProxyGenerator does the proxy generation.
  • TDSServerMetaDataProvider exposes the REST server metadata (server methods) to the proxy generator.
  • TDSProxyDispatcher / TDSHTTPServiceProxyDispatcher (WebBroker/Indy) handles the HTTP requests that require a specific proxy, and handles a default virtual path named proxy.

So if your server is reachable on http://www.myserver.com/ , the proxy must be requested to http://www.myserver.com/proxy/....

To simplify the proxy downloading process, there are two proxy downloaders (a Win32 console application and a Java command-line application).

Also, you must add to your uses clause each proxy generator unit for which you want to have proxies dispatched (that is, DSProxyJavaAndroid, DSProxyJavaBlackBerry, DSProxyCsharpSilverlight, DSProxyObjectiveCiOS). If you do not add these units to your uses clause, then client requests to dispatch the corresponding proxy might fail.

Each proxy requires a set of other files that must be deployed with the main generated proxy file. These are dependencies such as DBX data types and JSON parsing libraries. All the required files are located in the folder: \ObjRepos\<language>\dsrest\connectors of your product installation.

Note that each proxy requires all of the files contained in the related folder. This folder must be copied and redistributed with the server executable. A typical deployment of a server application is shown in the following screenshot:

Sampleserver.png

When the server has to generate a proxy for a specific language/platform, it generates inside the proper folder, then the server compresses the folder and creates a "language".zip file (java_android.zip when generating an Android proxy) to be downloaded by the client. This process is entirely managed by the TDSProxyDispatcher (or TDSHTTPServiceProxyDispatcher) component.

How to Receive a Dispatched Proxy

Requests to generate and dispatch a proxy come in as HTTP requests to the server, with a URL such as the following: http://serveraddress:port/proxy/mobile_client.zip , where "serveraddress", "port", and "mobile_client" are replaced by the actual values. The values currently accepted for "mobile_client" can be seen as the directory names (under "proxy") in the directory structure:

  • csharp_silverlight
  • objective_ios71
  • java_blackberry
  • java_android

You can open a Web browser and browse directly to the URL. There you should be prompted to download a .zip file that contains all the source code required for your mobile platform to invoke the exposed server methods of the DataSnap server.

For convenience, you could instead obtain the proxy by using the JAR or EXE proxy downloader, which you can find at C:\Program Files (x86)\Embarcadero\Studio\18.0\bin. Both JAR and EXE proxy downloaders take the same parameters, and allow for the automatic downloading and unzipping of the mobile proxy you want.

You can use the proxy downloader command-help to see the available parameters and usage examples:

 WIN32 DATASNAP PROXY DOWNLOADER HELP
 COMMAND:
   Win32ProxyDownloader.exe [-protocol protocol] -language language_platform
    [-output output_folder] [-host hostname]
 OPTIONS:
   -language <language> (required) The language_platform identifier.
    e.g. java_android or objectivec_ios71
   -host <hostname:port> (optional) Hostname and port where the server is
    running. Default is localhost:80
   -protocol <http|https> (optional) protocol can be http or https. Default http
   -output <local_proxy_path> (optional) is the full path where the proxy must
    be downloaded. Default current_folder
 EXAMPLES:
   Win32ProxyDownloader.exe -language java_android
   Win32ProxyDownloader.exe -host localhost:8080 -language java_android
    -output c:\
   Win32ProxyDownloader.exe -protocol http -language java_android -output folder

More information on how to use these proxy downloads can be found in the Getting Started documents for each individual mobile platform.

Topics

See Also