L'utilisateur peut intégrer un ensemble de méthodes de services POJO (Plain Old Java Object) à une liste blanche ou une liste noire. Ce type d'opération s'effectue à l'aide de l'attribut de filtre de l'élément de méthode présent dans l'élément POJO. Le filtre peut prendre les valeurs whitelisting et blacklisting. Si le filtre n'est pas spécifié, la totalité des méthodes apparaissent dans la liste. La méthode getAddress de la classe AddressLookup peut être ajoutée à la liste blanche ; pour cela, il suffit de spécifier le service POJO comme dans l'exemple qui suit.
L'exemple montre que l'adaptateur RPC permet uniquement d'accéder à la méthode getAddress de la classe AddressLookup. Vous pouvez également intégrer cette méthode à une liste noire en procédant comme dans l'exemple suivant.
L'exemple précédent montre que l'adaptateur RPC permet d'accéder à toutes les méthodes de la classe AddressLookup, à l'exception de getAddress. Par défaut, toutes les méthodes sont intégrées à la liste blanche si l'élément de méthode du service POJO ou son attribut de filtre n'est pas spécifié.
Lorsque vous appelez une méthode à partir de JavaScript, vous avez, dans la plupart des cas, besoin d'accéder à l'objet HtttpServletRequest. Pour ce faire, avec un adaptateur RPC, vous devez définir HttpServletRequest en tant que premier paramètre lors de l'appel à la méthode. La SMD (description simple de méthode) qui est retournée ne comporte pas l'objet HttpServletRequest comme paramètre et vous pouvez appeler la méthode à partir de JavaScript sans transmettre ce paramètre. Prenons l'exemple de la méthode putNameInSession(HttpServletRequest req, String name). Le fichier XML correspondant s'affiche :
Les valideurs sont définis à l'aide des éléments de valideurs figurant dans le fichier de configuration de l'adaptateur RPC. Vous pouvez définir un ensemble de valideurs pour chaque service POJO. Avant l'appel d'une méthode, la méthode validate du valideur spécifié est appelée sur les paramètres de la méthode. Vous pouvez spécifier des valideurs distincts pour chacun des paramètres de la méthode. Tous les valideurs étendent la classe abstraite com.ibm.websphere.rpcadapter.Validator. La validation peut également s'effectuer à l'aide d'expressions régulières. Vous pouvez utiliser l'élément validation-regex pour spécifier des expressions régulières correspondant aux valeurs de paramètres. Si celles-ci ne correspondent pas à l'expression régulière, une erreur de validation est générée.
En cas d'erreurs de validation, un objet Error est renvoyé au format JSON. Les informations qu'elles contiennent peuvent servir à la gestion des erreurs. Les champs sont décrits ci-après.
L'adaptateur RPC permet maintenant de définir des portées pour les objets qu'il expose. Trois différentes portées, Request, Session et Application, sont prises en charge par l'adaptateur RPC. Si la portée est définie sur Application ou Session, cela constitue un avantage supplémentaire. En effet, l'objet n'est pas recréé à chaque fois mais est recherché à partir de la portée Session ou Application. La clé utilisée est au format suivant : "com.ibm.websphere.rpcadapter:ServiceName" (où ServiceName correspond au nom de l'objet exposé). Afin que vous puissiez spécifier cette clé, chaque objet reçoit la balise scope, qui peut contenir les valeurs suivantes : Session, Request et Application. Voir l'exemple qui suit.
L'adaptateur RPC prend désormais l'ajout de valeurs de retour à la session. Pour activer cette possibilité d'ajouter des valeurs, ajoutez la balise <add-to-session> (voir ci-après).
L'adaptateur RPC prend désormais en charge les objets complexes comme, par exemple, les objets pouvant contenir d'autres objets. Les objets complexes sont pris en charge aussi bien en tant que types de retour que paramètres de méthode. En outre, l'adaptateur RPC rend possible la sérialisation d'un type quelconque d'objet complexe. Maps et Collections ne sont pas pris en charge comme paramètres des appels de méthode. Cela est dû à ce que la la classe des objets de Map ou de Collection ne peut être identifiée uniquement à partir de son contenu. La prise en charge nécessiterait l'optimisation de la classe ou la paramétrisation des types, toutes fonctionnalités non encore prises en charge. Il n'est pas possible non plus d'appeler via HTTP-RPC des méthodes avec des paramètres complexes même si les types complexes de retour sont pris en charge.
Ce type de prise en charge d'objet complexe est particulier. Par exemple : A -> B -> A, autrement dit, A contient B qui contient A. Le composant RPC Adapter du produit gère ce cas en remplaçant les occurrences en double des objets par des marques de réservation $jref (sérialisation JSON) ou par $xref (sérialisation XML). Ces marques de réservation contiennent des informations permettant de rechercher l'objet d'origine, c'est-à-dire une expression XPath dans le cas de XML ou une expression JavaScript dans le cas de JSON. Pour activer la prise en charge de la gestion d'objets récursifs, définissez la balise <recursive-object-support> sur true. Procédez comme dans l'exemple suivant :
Les objets à exposer contiennent fréquemment des champs que le développeur d'applications ne souhaite pas exposer via le service Web JSON ou XML. L'adaptateur RPC donne la possibilité de supprimer des champs de l'objet renvoyé. Cette suppression de champs peut être activée au moyen de la balise <serialized-params>. Pour supprimer le champ postalCode de la classe com.ibm.Address, utilisez la configuration ci-dessous. Si vous choisissez cette configuration, le champ postalCode de la classe com.ibm.Address ne sera pas sérialisé.
L'utilisateur peut spécifier des alias de classe. L'alias spécifié sert de nom de noeud lors de la sérialisation XML. L'exemple suivant illustre la configuration d'un alias d'adresse.
L'utilisateur peut spécifier des convertisseurs pour la classe JSON/XML. Si un convertisseur est spécifié pour une classe, ce convertisseur sera utilisé pour la sérialisation JSON/XML
de cette classe. Toutes les classes de conversion doivent implémenter l'interface com.ibm.websphere.rpcadapter.converters.IConverter
. Par défaut, l'adaptateur RPC est livré avec les convertisseurs suivants.
Convertisseur | Utilisation |
com.ibm.websphere.rpcadapter.converters.sql.Date
|
Pour convertir java.sql.Date en chaîne de date et d'heure. |
com.ibm.websphere.rpcadapter.converters.sql.Time
|
Pour convertir java.sql.Time en chaîne de date et d'heure. |
com.ibm.websphere.rpcadapter.converters.sql.TimeStamp
|
Pour convertir java.sql.TimeStamp en chaîne de date et d'heure. |
com.ibm.websphere.rpcadapter.converters.util.Date
|
Pour convertir java.util.Date en chaîne de date et d'heure. |
Vous pouvez spécifier des convertisseurs dans RpcAdapterConfig.xml comme dans l'exemple suivant. La balise <subclass-support> peut être utilisée pour indiquer que même les sous-classes de la classe de bean indiquée doivent être converties par la classe de convertisseur en définissant la valeur entre les balises sur true. Par défaut, cette valeur est définie sur false.
Pour des raisons de sécurité, l'adaptateur RPC peut être configuré de manière à produire du JSON comment filtered lorsqu'il est utilisé pour exposer des méthodes en tant que services Web JSON, en utilisant par exemple des données JSON encapsulées entre '/*' et '*/'. Dojo possède une fonctionnalité lui permettant de traiter le format JSON comment filtered au niveau du client. Par défaut, cette fonctionnalité est désactivée dans l'adaptateur RPC. Pour l'activer, vous devez définir la balise filtered comme true dans le fichier RPCAdapterConfig.xml, comme l'illustre l'exemple suivant.
La sécurité de l'adaptateur RPC est assurée par le système de sécurité Web Java EE. Tous les services qui ont été configurés pour être exposés au client auront des URL uniques. Vous pouvez restreindre l'accès à ces URL à l'aide du système de sécurité Web Java EE. Pour ce faire, créez un domaine de sécurité sur le serveur d'applications, définissez ensuite dans le fichier de descripteur du déploiement un accès à base de rôles, et enfin mappez ces rôles avec des utilisateurs ou des groupes du domaine de sécurité en utilisant une configuration spécifique au serveur. Cette fonction ne peut pas être utilisée isolément des appels par lots.
En plus de la sécurité Web Java EE, le RPCAdapter peut aussi être configuré pour exécuter des contrôles d'autorisation des services exposés, et peut par conséquent autoriser un accès uniquement à certains rôles définis dans le fichier web.xml ou geronimo-web.xml. Pour utiliser cette fonction, l'url-pattern de "/RPCAdapter/*" doit être sécurisé via le fichier web.xml. L'étape suivante consiste à utiliser la balise <role> pour indiquer si seul un utilisateur ayant un rôle particulier sera autorisé à accéder au service correspondant. Il convient d'observer que si RPCAdapter effectue l'autorisation de service, il incombe à l'application d'authentifier l'utilisateur avant que le service sécurisé soit appelé. Si l'authentification n'est pas effectuée avant l'appel au service sécurisé, RPCAdapter ne permet pas d'accéder au service correspondant. Ceci n'est valable que pour les méthodes du service qui sont déjà sur liste blanche. L'accès à un service peut être contrôlé comme indiqué ci-dessous.
L'API BatchService permet aux utilisateurs de traiter par lots un ensemble d'appels. Une nouvelle fabrique de service de lots peut être créée, initialisée puis soumise comme suit :
Il est possible d'exposer des méthodes surchargées en spécifiant dans le fichier RpcAdapterConfig.xml un nom unique pour une méthode surchargée donnée et les types des paramètres correspondants.
Il est possible d'attribuer aux méthodes d'autres noms que ceux utilisés dans l'implémentation Java. Pour ce faire, il suffit d'utiliser les balises <alias> et <name> comme on l'a vu pour la surcharge de méthodes. La seule exception est que les types de paramètres n'ont pas à être spécifiés si la méthode n'est pas surchargée.
Pour pouvoir accéder aux beans enterprise via l'adaptateur RPC, il faut spécifier in RPCAdapterConfig.xml les informations nécessaires du module EJB. Les méthodes du module EJB sont exposées et vous pouvez appeler une méthode directement à partir de JavaScript.
Pour pouvoir accéder aux beans session via l'adaptateur RPC, vous devez spécifier les interfaces distante et locale, le jndi-name pour la recherche des modules EJB, et les méthodes qui sont implémentées. Dans le cas d'EJB 3.0, les interfaces locale et distante sont remplacées par une seule et même interface habituellement appelée business-interface ou interface métier. Donc, vous spécifierez cette interface métier à l'aide de la balise <business-interface>. La balise <ejb-name> sert à associer un nom logique à un module EJB. La balise <jndi-name> sert à rechercher des modules EJB. Le jndi-name spécifié par l'utilisateur dans le fichier RPCAdapterConfig.xml doit correspondre au jndi-name spécifié dans le fichier web.xml. Dans le cas d'EJB 3.0, le jndi-name doit être préfixé avec java:comp/env/ si c'est WebSphere® Application Server Community Edition qui est utilisé comme serveur d'applications. Si c'est WebSphere Application Server, et qu'EJB3.0 est utilisé, le jndi-name dans la balise
<jndi-name> doit être préfixé avec le mot clé "ejblocal:". Vous devez indiquer avec la balise <session-type> le type du bean session : sans état ou avec état.
Exemple d'entrée de bean session sans état dans le fichier RPCAdapterConfig.xml :
Dans les beans session avec état, l'interface home peut contenir plus d'une fonction create. Si tel est le cas, vous devez spécifier la fonction create qui doit être appelée. La balise <create> permet de déclarer la fonction create dans le fichier RPCAdapterConfig.xml. Fragment de code de bean session avec état pour EJB 2.1 :
La prise en charge des annotations permet d'exposer directement les services à partir du code, plutôt que de devoir les configurer dans le fichier RPCAdapterConfig.xml. Pour permettre d'activer cette fonctionnalité, le fichier RPCAdapter-annotation.jar est fourni avec cette version du produit. Placez ce fichier jar dans le répertoire WEB-INF/lib de l'application Web utilisant cette fonctionnalité. Vous devez annoter avec @Pojo la classe qui contient les méthodes à exposer et vous utiliserez les annotations @Method et @Params pour les méthodes correspondantes. Une classe annotée est rendue visible à l'adaptateur RPC via le fichier web.xml. Spécifiez à l'adaptateur RPC le nom canonique de la classe annotée sous forme de valeur "init-param". Mentionnez le nom "init-param" correspondant sous la forme Classn où n est n'importe quel nombre. Exemple de fragment de code :
Dans l'adaptateur RPC, le format de sortie est soit JSON, soit XML.
Les diverses sorties XML qui sont générés dans des scénarios différents sont répertoriées ci-dessous.
Si le type renvoyé est void, le format de sortie XML généré est une balise vide de résultat :
Si la méthode dans le bean JavaBeans est public int getSalary()
, vous obtenez un résultat de ce genre :
public String getMessage()
, vous obtenez un résultat de ce genre :
public Boolean isLeapYear()
, vous obtenez un résultat de ce genre :
Pour le type de retour Collection, le résultat est un ensemble d'éléments représentant chacun une entrée de la collection. Si la collection contient une quelconque instance de type d'objet supprimé, cette entrée sera ignorée.
public Collection getEmployees()
et que le type de collection renvoyé contient des instances d'Employee, les données produites ressembleront à ceci :
Pour le type de retour Array, les données générées correspondent à un ensemble d'éléments représentant chacun une entrée du tableau (array).
public Employee[] getEmployees()
et que le type Array renvoyé se compose d'instances d'Employee, vous obtenez un résultat de ce genre :
Pour les types de mappage renvoyés, les données générées sont un ensemble d'éléments représentant chacun une paire clé-valeur dans le mappage. Le nom de noeud correspond à la clé.
Si la méthode figurant dans le bean est public Map getDepartments()
et que le mappage renvoyé correspond à une paire clé-valeur du code Department mappée avec les détails relatifs au département, vous obtenez un résultat de ce genre :
Pour les types de retour beans JavaBeans, toutes les méthodes read et tous les champs public sans méthode read sont concernés par la sérialisation XML. Les JavaBeans sont représentés par un élément. Le nom nodal de cet élément sera le type de JavaBeans qu'il représente. Si vous spécifiez un alias pour le bean, c'est cet alias qui est utilisé comme nom nodal.
Si la méthode dans le bean JavaBeans est public Employee getEmployee()
, vous obtenez un résultat de ce genre :
Les différentes sorties JSON générées dans différents scénarios sont expliquées ci-après.
Si le type de retour est void, les données JSON générées sont un objet de résultat JSON.
public int getSalary()
, vous obtenez un résultat de ce genre :
public String getMessage()
, vous obtenez un résultat de ce genre :
public Boolean isLeapYear(int year)
, vous obtenez un résultat de ce genre :
Pour le type de retour Collection, le résultat est un ensemble d'éléments représentant chacun une entrée de la collection. Si la collection contient une quelconque instance de type d'objet supprimé, cette entrée sera ignorée.
public Collection getEmployees()
et que le type Collection renvoyé contient des instances d'Employee, vous obtenez un résultat de ce genre :
Pour le type de retour Array, les données générées correspondent à un ensemble d'éléments représentant chacun une entrée du tableau (array).
public Employee[] getEmployees()
et que le type Array renvoyé se compose d'instances d'Employee, vous obtenez un résultat de ce genre :
Pour les types de mappage renvoyés, les données générées sont un ensemble de paires clé-valeur.
Si la méthode dans le bean JavaBeans est public Map getDepartments()
et que le mappage renvoyé correspond à une paire clé-valeur du code Départment mappée avec les détails relatifs au département, vous obtenez un résultat de ce genre :
Le bean JavaBeans est représenté sous forme de paires clé-valeur dans lesquelles la clé correspond au nom du champ et la valeur à la valeur de ce dernier. Les champs public et ceux contenant des méthodes d'accès get sont les seuls à être sérialisés.
Si la méthode dans le bean JavaBeans est public Employee getEmployee()
, vous obtenez un résultat de ce genre :
Il est possible de configurer l'adaptateur RPC (1) pour qu'il instancie un nouveau bean Java par demande ou (2) pour qu'il réutilise des instances par utilisateur. (Par exemple, un objet de panier électronique doit être configuré comme instance réutilisée par utilisateur.) Le comportement par défaut est d'instancier un nouveau bean JavaBeans par demande. La réutilisation est configurée à l'aide des informations du descripteur de bean. Pour les détails, voir la documentation de l'API SampleBeanInfo.
Certaines commandes sont développées sans être exposées directement en tant que services. Dans de tels cas, vous pouvez développer un programme d'accès à un bean Java qui contienne la logique impliquée. Par exemple, l'EJB ShoppingCart de l'exemple de PlantsByWebSphere inclut une méthode addItem(StoreItem item). L'objet StoreItem incluant le prix de l'article, la conception présuppose que seules des sources de confiance invoqueront la méthode, comme le montre l'exemple suivant dans le servlet ShoppingServlet :