Envoyer des requêtes au serveur et actions personnalisées

 

En plus d'exécuter du code dans le navigateur de l'utilisateur, une extension JMap Web peut également définir des actions qui peuvent tirer parti de l'API de JMap Serveur. Ces actions peuvent être enregistrées auprès du service AJAX Dispatcher de votre déploiement et être interpellées par des requêtes HTTP.

Une extension JMap Web peut contenir plusieurs actions. Vous pouvez également créer des classes additionnelles (qui ne sont pas des actions) qui peuvent être référencées depuis vos actions.

Créer une action

Créez une classe qui hérite de AbstractHttpRequestAction. Afin de suivre cet exemple, le nom de votre classe devrait être MyFirstAction.

package myextension;
import java.io.IOException;
import java.io.PrintWriter;
 
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
 
import jmap.http.AJAX.servlets.AbstractHttpRequestAction;
 
 
public class MyFirstAction extends AbstractHttpRequestAction
{
  @Override
  public void execute(HttpServletRequest request, HttpServletResponse response) throws IOException
  {
 
  }
}

 

Comme vous avez pu le remarquer, une action nécessite les classes HttpServletRequest et HttpServletResponse afin d'être compilée. Ajoutez le le JAR servlet-api de Tomcat Server à votre chemin de compilation (build path). Ce JAR peut être récupéré dans le répertoire $JMAP_HOME$/tomcat/lib.

Une action doit posséder une méthode execute. Cette méthode sera appelée lorsqu'une requête HTTP spécifiant votre action sera reçue par l'AJAX Dispatcher.

Pour les besoins de cet exemple, voici une action Hello World! typique.

package myextension;
import java.io.IOException;
import java.io.PrintWriter;
 
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
 
import jmap.http.AJAX.servlets.AbstractHttpRequestAction;
 
 
public class MyFirstAction extends AbstractHttpRequestAction
{
  @Override
  public void execute(HttpServletRequest request, HttpServletResponse response) throws IOException
  {
    final PrintWriter writer = response.getWriter();
    String name = request.getParameter("name");
 
    if (name != null && name.trim() != "")
      writer.print("Hello, " + name);
    else
      throw new IllegalArgumentException("Invalid argument. Must specify a `name` parameter.");
  }
}

 

Produire un fichier JAR pour votre action

Afin d'être inclut dans une extension JMap Web, votre code serveur Java doit être contenu dans un seul fichier JAR.

En utilisant Ant

En utilisant l'outil webextensionbuilder du SDK de JMap 6.5 (décrit dans la section Programmer des extensions JMap Web) afin de produire le code de base de l'extension, une action SampleAction est fournie comme point de départ. Un fichier build.xml est également inclut. Vous pouvez utiliser ce fichier avec Ant afin de compiler et produire le fichier JAR de votre extension.

Copiez le fichier MyFirstAction.java au répertoire actions/src de votre extension. Puisque la classe MyFirstAction est définie à l'intérieur du package myextension, créez un répertoire myextension sous actions/src et collez-y votre fichier MyFirstAction.java. À ce stade, vous devriez avoir les items suivant dans votre répertoire actions:

actions/
├── build.xml
├── readme.markdown
└── src
    ├── Example
    │   └── SampleAction.java
    └── myextension
        └── MyFirstAction.java
 
3 directories, 4 files

 

En utilisant la ligne de commande/un terminal, naviguez vers le répertoire actions de votre extension et exécutez la commande suivante:

ant -f build.xml

Lorsque vous aurez votre fichier JAR, copiez le au répertoire actions de votre extension.

En utilisant Ant depuis Eclipse

Comme c'était le cas lors de l'utilisation de l'outil webextensionbuilder, vous pouvez utiliser Ant depuis Eclipse afin de produire le fichier jar serveur de votre extension. Ceci nécessite qu'un JDK soit configuré comme étant le JRE par défaut d'Eclipse et que le fichier tools.jar du JDK soit ajouté au classpath de la configuration du runtime de Ant. Ces étapes furent précédemment décrites ici.

1.Ouvrez le fichier actions/build.xml de votre extension dans Eclipse.

2.Exécutez la cible ant nommée «package».

Exécutez la cible «package».

Exécutez la cible «package».

Lorsque vous aurez votre fichier JAR, copiez le au répertoire actions de votre extension.

Identifier les actions de votre extension

Le fichier extension.json de votre extension informe JMap Serveur à propos de lui-même. Vous devez maintenant y indiquer que votre extension comporte des actions.tains actions. Ouvrez ce fichier dans un éditeur de texte.

La propriété actions est un tableau qui peut contenir plusieurs littéraux objets. Chacun de ces objets décrivent une action.

Les littéraux objets du tableau actions doivent avoir les clefs de propriétés suivantes:

Clefs de propriétés des actions

Description

name

{String} Ceci est le nom de l'action tel qu'elle sera enregistrée auprès du AJAX Dispatcher. Cette valeur doit être unique au sein de votre déploiement JMap Web. Les requêtes HTTP doivent spécifier cette valeur au niveau du paramètre action de celles-ci. Ne fait pas nécessairement référence au nom du fichier source de votre classe.

classname

{String} Le nom complet de votre classe. Doit inclure les packages.

version

{String} Identifie une version. Principalement utile pour fins de débogage.

 

Cet extrait démontre comment représenter l'action MyFirstAction dans l'extension web_sdk_documentation_example qui fût crée plus tôt:

{

  "actions": [

    {

      "name": "hello",

      "className": "myextension.MyFirstAction",

      "version": "1.0.0"

    }

  ],

  "fullname": "Web SDK Documentation Example",

  "namespace": "Example",

  "shortname": "web_sdk_documentation_example",

  "version": "1.0"

}

 

Votre extension peut inclure autant d'actions que vous le voulez. Il suffit simplement de les identifier auprès du fichier extension.json de votre extension.

Après avoir modifié votre fichier extension.json, confirmez qu'il contient du JSON valide. JSONLint est un validateur JSON en ligne qui peut être utilisé à cette fin.

Appeler votre action depuis votre extension JMap Web

Tel que mentionné précédemment, la méthode execute de votre action sera appelée lorsque l'AJAX Dispatcher recevra une requête HTTP qui indique le nom de votre action au niveau de son paramètre action.

L'exemple suivant illustre comment vous pouvez envoyer une requête HTTP auprès de votre action en utilisant jQuery.ajax(). Pour tester ceci, vous pouvez soit inclure cet extrait dans la méthode init de votre extension ou bien le copier et le coller dans la console JavaScript de votre navigateur qui inspecte présentement votre déploiement.

$.ajax(JMap.app.ajaxDispatcher, {
  data: {
    "action": "hello", // The action name as defined in the extension.json file.
    "name": "Developer" // The `name` parameter as expected by the action.
  }
}).error(function(jqXHR, textStatus, errorThrown) {
  alert(textStatus);
}).success(function(data, textStatus, jqXHR) {
  alert(data);
});