Introduction au connecteur mobile Java BlackBerry DataSnap
Remonter à Connecteurs DataSnap pour les périphériques mobiles
Cette rubrique est un guide d'introduction à la génération et à l'utilisation du proxy Java BlackBerry DataSnap, pour un usage avec le développement mobile BlackBerry. Le proxy Java supporte les mêmes types de données que DataSnap. Des classes Java spéciales ont été créées pour encapsuler ces types DBX et Delphi, et leur usage est similaire à celui dans Delphi.
A la demande, le serveur DataSnap REST génère et répartit la classe proxy utilisée pour invoquer les méthodes sur le serveur. C'est très similaire à la génération de proxy que vous connaissez déjà, mais vous avez en plus le processus de compression du proxy et de toutes les dépendances, et l'envoi du fichier zip au demandeur. Pour de plus amples informations sur ce processus, voir Introduction aux connecteurs mobiles DataSnap.
La classe DSProxy et tous les fichiers d'exécution sont contenus dans le package com.embarcadero.javablackberry. Voici la structure de ce package :
Remarque : La version 6 (ou supérieure) du système d'exploitation BlackBerry est requise.
Sommaire
Comment télécharger les fichiers proxy BlackBerry à partir d'un serveur DataSnap REST
Vous devez d'abord obtenir une copie de Win32ProxyDownloader.exe (disponible dans le répertoire \bin de votre installation de produit). Pour de plus amples informations, voir Introduction aux connecteurs mobiles DataSnap. Le téléchargeur est un utilitaire simple qui vous aide à demander au serveur le proxy et les autres fichiers nécessaires à la communication avec le serveur.
Pour utiliser le téléchargeur de proxy, vous devez fournir les paramètres suivants :
- -language (obligatoire) : Spécifie la plate-forme/le langage mobile du proxy requis. Pour le développement BlackBerry, utilisez java_blackberry.
- -protocol : Spécifie le protocole de connexion à utiliser, http ou https. La valeur par défaut est http.
- -host : Spécifie le port, et l'adresse IP ou le nom de l'hôte sur lequel se connecter. La valeur par défaut est localhost avec le port 80. Si un port ou un nom différent est nécessaire, le nom doit être entièrement qualifié avec le numéro de port inclus, séparé par un deux-points (":").
- -output : Spécifie le dossier dans lequel télécharger les fichiers proxy. S'il n'est pas spécifié, le dossier en cours est utilisé.
L'exemple suivant utilise la plupart des paramètres mentionnés ci-dessus :
C:\Win32ProxyDownloader.exe -language java_blackberry -host 127.0.0.1:8080 -output C:\test
Après l'exécution du téléchargeur, les fichiers proxy BlackBerry sont copiés dans le dossier de sortie spécifié. Voici ces fichiers :
- La bibliothèque JSON
- Les fichiers source Java statiques requis par le proxy
- DSProxy.java, le proxy généré
Le fichier principal, DSProxy.java, déclare la classe qui contient toutes les méthodes définies sur le serveur.
Après l'importation des fichiers dans votre projet, votre configuration ressemble à ceci :
Comment utiliser la classe DSProxy
Le code ci-dessous montre le fichier DSProxy.java généré par le serveur. Il contient une classe TServerMethods1, qui encapsule les méthodes serveur. Le serveur a seulement une méthode (EchoString), et la classe Java TServerMethods1 l'implémente en conséquence. Le générateur de proxy a automatiquement généré le code pour la connexion au serveur et l'exécution des méthodes. Voir le code pour la méthode EchoString ci-dessous :
public class DSProxy {
public static class TServerMethods1 extends DSAdmin {
public TServerMethods1(DSRESTConnection Connection) {
super(Connection);
}
private DSRESTParameterMetaData[] TServerMethods1_EchoString_Metadata;
private DSRESTParameterMetaData[] get_TServerMethods1_EchoString_Metadata() {
if (TServerMethods1_EchoString_Metadata == null) {
TServerMethods1_EchoString_Metadata = new DSRESTParameterMetaData[]{
new DSRESTParameterMetaData("Value", DSRESTParamDirection.Input,
DBXDataTypes.WideStringType, "string"),
new DSRESTParameterMetaData("", DSRESTParamDirection.ReturnValue,
DBXDataTypes.WideStringType, "string"),
};
}
return TServerMethods1_EchoString_Metadata;
}
/**
* @param Value [in] - Type on server: string
* @return result - Type on server: string
*/
public String EchoString(String Value) throws DBXException {
DSRESTCommand cmd = getConnection().CreateCommand();
cmd.setRequestType(DSHTTPRequestType.GET);
cmd.setText("TServerMethods1.EchoString");
cmd.prepare(get_TServerMethods1_EchoString_Metadata());
cmd.getParameter(0).getValue().SetAsString(Value);
getConnection().execute(cmd);
return cmd.getParameter(1).getValue().GetAsString();
}
private DSRESTParameterMetaData[] TServerMethods1_ReverseString_Metadata;
private DSRESTParameterMetaData[] get_TServerMethods1_ReverseString_Metadata() {
if (TServerMethods1_ReverseString_Metadata == null) {
TServerMethods1_ReverseString_Metadata = new DSRESTParameterMetaData[]{
new DSRESTParameterMetaData("Value", DSRESTParamDirection.Input,
DBXDataTypes.WideStringType, "string"),
new DSRESTParameterMetaData("", DSRESTParamDirection.ReturnValue,
DBXDataTypes.WideStringType, "string"),
};
}
return TServerMethods1_ReverseString_Metadata;
}
}
La première étape de l'utilisation de la classe proxy consiste à créer et à configurer une connexion au serveur. La classe DSRESTConnection encapsule toutes les propriétés et méthodes nécessaires à la connexion au serveur. Créez simplement la connexion et configurez les propriétés, comme illustré ci-dessous :
import com.embarcadero.javablackberry.DSRESTConnection;
// ...
DSRESTConnection conn = new DSRESTConnection();
conn.setHost("host");
conn.setPort(port);
conn.setProtocol("http");
- La propriété host spécifie le nom de l'hôte ou l'adresse IP.
- La propriété port spécifie le port sur lequel le serveur écoute.
- La propriété protocol spécifie le protocole à utiliser pour la connexion. Spécifiquement : http ou https.
Pour invoquer à distance les méthodes serveur, créez simplement la classe proxy, en passant la connexion, puis appelez la méthode :
DSRESTConnection conn = new DSRESTConnection();
conn.setHost("10.40.30.24");
conn.setPort(8080);
TServerMethods1 proxy = new TServerMethods1(conn);
String Result = proxy.EchoString("Hello, World!");
Exemple d'une méthode serveur avec un paramètre var
L'exemple suivant est le code généré quand votre méthode serveur contient un paramètre var ou renvoie plusieurs résultats.
Voici le code Delphi pour la méthode serveur :
function TServerMethods1.VarParamTest(var Value: string): string;
begin
Value := StrUtils.ReverseString(Value);
Result := Value;
end;
Et voici le code proxy généré pour invoquer cette méthode serveur :
private DSRESTParameterMetaData[] TServerMethods1_VarParamTest_Metadata;
private DSRESTParameterMetaData[] get_TServerMethods1_VarParamTest_Metadata() {
if (TServerMethods1_VarParamTest_Metadata == null) {
TServerMethods1_VarParamTest_Metadata = new DSRESTParameterMetaData[]{
new DSRESTParameterMetaData("Value", DSRESTParamDirection.InputOutput,
DBXDataTypes.WideStringType, "string"),
new DSRESTParameterMetaData("", DSRESTParamDirection.ReturnValue,
DBXDataTypes.WideStringType, "string"),
};
}
return TServerMethods1_VarParamTest_Metadata;
}
/**
* @param Value [in/out] - Type on server: string
* @return result - Type on server: string
*/
public static class VarParamTestReturns {
public String Value;
public String returnValue;
}
public VarParamTestReturns VarParamTest(String Value) throws DBXException {
DSRESTCommand cmd = getConnection().CreateCommand();
cmd.setRequestType(DSHTTPRequestType.GET);
cmd.setText("TServerMethods1.VarParamTest");
cmd.prepare(get_TServerMethods1_VarParamTest_Metadata());
cmd.getParameter(0).getValue().SetAsString(Value);
getConnection().execute(cmd);
VarParamTestReturns ret = new VarParamTestReturns();
ret.Value = cmd.getParameter(0).getValue().GetAsString();
ret.returnValue = cmd.getParameter(1).getValue().GetAsString();
return ret;
}
Notez que la méthode renvoie une instance de VarParamTestReturns. Cette classe spéciale contient les informations sur les paramètres var (in/out), ainsi que le résultat. L'exemple ci-dessous montre comment invoquer la méthode et lire les valeurs résultantes.
TServerMethods1 proxy = new TServerMethods1(conn);
VarParamTestReturns Result = proxy.VarParamTest("Hello, World!");
System.out.println(Result.Value);
System.out.println(Result.returnValue);
La valeur du résultat et la nouvelle valeur du paramètre transmis sont contenues dans l'instance de Result. La valeur de Result.Value est "!dlroW ,olleH", et la valeur de Result.returnValue est "Hello, World!".
Comment utiliser les rappels avancés
Les rappels avancés fournissent un moyen, aux serveurs DataSnap, d'envoyer des notifications presque instantanées aux clients REST. Un client peut recenser un rappel pour une rubrique spécifique du serveur qui l'intéresse. Ainsi, à chaque fois que cette rubrique est mise à jour, le client reçoit une notification. C'est, bien entendu, une description très simplifiée de ce que les rappels avancés accomplissent, mais qui est suffisante pour les besoins de cette tâche.
La première étape lors de l'utilisation des rappels dans votre application consiste à créer une classe de rappel personnalisé qui hérite de la classe abstraite DBXCallback et à redéfinir la méthode abstraite "Execute". Un exemple d'implémentation de cette classe est présenté ci-dessous :
public class MyCallback extends DBXCallback {
public TJSONValue execute(TJSONArray params) {
System.out.println(params.toString());
return new TJSONTrue();
}
}
La classe DSClientCallbackChannelManager gère les rappels du client. Elle fournit les méthodes pour le recensement et le dérecensement des rappels, et la fermeture d'un rappel ou de tous les rappels. Son constructeur accepte trois paramètres :
- Un DSRESTConnection qui spécifie les informations de connexion au serveur
- Une chaîne contenant le nom du canal serveur avec lequel recenser
- Une chaîne contenant l'ID du gestionnaire (unique au serveur)
Voici le code qui crée le gestionnaire :
DSCallbackChannelManager manager =
new DSCallbackChannelManager(conn,"chname",DSCallbackChannelManager.getNewManagerID());
Voici un exemple de recensement d'un rappel puis de la diffusion sur le canal où le rappel a été recensé :
manager.registerCallback("mycb01", new MyCallback());
L'exemple ci-dessus recense le rappel avec le nom "mycb01". Le premier paramètre de la méthode 'registerCallback' est un ID de rappel (unique au canal client). Le deuxième paramètre est l'instance de rappel réelle à recenser. S'il s'agit du premier rappel recensé, vous n'êtes pas garanti au retour de l'appel de registerCallback que le gestionnaire de rappels soit prêt, puisque le recensement initial a été effectué de façon asynchrone. Toutefois, après l'appel initial de registerCallback, aucun retour des appels suivants ne s'effectue tant que le recensement n'est pas achevé. La connexion reste ouverte tant que vous ne la fermez pas, ou qu'elle n'est pas fermée par le serveur. Pour arrêter la connexion, vous pouvez dérecenser le rappel et fermer le canal, comme présenté ci-dessous :
manager.unregisterCallback("mycb01");
manager.closeClientChannel();