Getting Started with DataSnap Mobile Connectors
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.
The following mobile platforms are currently supported by the various DataSnap Connectors:
- Android 2.x, 3.x, or 4.x (Java)
- BlackBerry Java SDK 5 and 6 (Java)
- Windows Phone 7 (C#Silverlight--all devices compatible with the platform)
- iOS 4.x, 5.x, 6.x (Objective-C)
- iOS 4.2 (Free Pascal)
- iOS 5.0 (Free Pascal)
Tip: Free Pascal Compiler is supported only in XE2.
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.
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:
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.
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\en\dsrest\connectors. The folder structure is shown in the following screenshot:
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:
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:
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\Embarcadero\RAD Studio\9.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_ios42 -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.
- Getting Started with iOS Objective-C DataSnap Mobile Connector
- Getting Started with iOS Free Pascal DataSnap Connectors
- Getting Started with CSharp Silverlight DataSnap Mobile Connector
- Getting Started with Java Android DataSnap Mobile Connector
- Getting Started with Java BlackBerry DataSnap Mobile Connector