Création d'un bean Java d'appel de programme IBM i et d'un fichier PCML

Limitations du bean d'appel de programme

  1. Les définitions d'appel de programme permettant d'appeler un programme proprement dit peuvent comporter au maximum 35 paramètres.
  2. Les définitions d'appel de programme permettant d'appeler une procédure peuvent comporter au maximum 7 paramètres.
  3. Les attributs PCML Version minimale et Version maximale sont valides uniquement pour les beans d'appel de programme dont l'option Utiliser PCML est activée.

Classes de support d'exécution

L'assistant Appel de programme génère une fois par projet les fichiers de classe de support d'exécution suivants.
Exemple
AbstractProgramCallBean

Classe parent de tous les beans d'appel de programme. Elle contient les méthodes et propriétés communes de tous les beans d'appel de programme.

LogonSpec

Contient le nom d'hôte, l'ID utilisateur et le mot de passe utilisés pour la connexion au système distant. Si votre application doit s'exécuter sur le système distant, vous pouvez attribuer au nom d'hôte, à l'ID utilisateur et au mot de passe les valeurs spéciales suivantes : "localhost", "*CURRENT", "*CURRENT". Le profil utilisateur en cours permet d'effectuer des appels de programme.

IConnection
Interface de connexion permettant au bean d'appel de programme de se connecter au système distant. Un objet IConnection est associé à chaque bean d'appel de programme. IConnection permet de définir les méthodes suivantes :
  1. getAS400() - Cette méthode renvoie un objet AS400 qui permet au bean d'appel de programme d'établir une connexion avec le système distant pour l'appel de programme.
  2. releaseAS400() - Cette méthode permet au bean d'appel de programme de libérer la connexion une fois le programme appelé.
Le bean d'appel de programme utilise la méthode getAS400() pour obtenir un objet AS400 avant d'essayer d'appeler le programme. Une fois le programme appelé, il utilise la méthode releaseAS400() pour libérer la connexion. Le flux de l'appel de programme est le suivant : getAS400() -> appel du programme distant -> releaseAS400()

L'assistant Appel de programme génère 3 classes qui implémentent cette interface : AS400Connection, PooledAS400Connection et JcaAS400Connection.

AS400Connection

La classe AS400Connection est un encapsuleur simple autour d'un objet AS400. Vous aurez besoin d'associer ce type de connexion à ce bean d'appel de programme si votre application gère toutes les connexions au système distant.

Les instances RuntimeContext contiennent toutes les informations définies dans le fichier de configuration d'exécution, ainsi que d'autres informations générales partagées par plusieurs beans d'appel de programme. Il existe une instance RuntimeContext par fichier de configuration défini dans votre projet.

Exemple 1 :

TestProgram pgm = new TestProgram(); 
AS400Connection myConnection = new AS400Connection(myAS400);
pgm.initConnection(myConnection);
PooledAS400Connection

Par définition, les connexions PooledAS400Connection font partie d'un pool de connexions. La méthode getAS400() renvoie un objet AS400 du pool. A l'aide du nom d'hôte, de l'ID utilisateur et du mot de passe indiqué dans l'objet LogonSpec, la méthode recherche un objet AS400 existant dans le pool. Si un tel objet est disponible, il est renvoyé. Dans le cas contraire, le programme en crée un. Une fois le programme appelé, la méthode releaseAS400() remet l'objet AS400 dans le pool de connexions.

Les informations de l'objet LogonSpec sur la liste des bibliothèques et sur la commande initiale ne servent pas à la recherche d'un objet AS400 existant dans le pool. Ces informations ne sont utilisées que lors de la création d'une connexion. Les informations sur la liste des bibliothèques permettent de configurer la liste initiale. De même, la commande initiale n'est exécutée qu'une fois. Si votre application manipule la liste des bibliothèques lors de l'exécution, n'oubliez pas que toutes les modifications apportées à cette liste seront conservées lors de la prochaine réutilisation de la connexion. En outre, vous ne devez pas définir deux connexions avec un nom d'hôte, un ID utilisateur et un mot de passe identiques, mais des informations différentes sur la liste des bibliothèques et sur la commande initiale. Dans le cas contraire, votre programme risque d'obtenir une connexion avec une liste des bibliothèques incorrecte. Par exemple, imaginons que le programme A définisse une connexion indiquant que la bibliothèque BIBA doit se trouver dans la liste des bibliothèques. Le programme B définit une connexion avec le même nom d'hôte, le même ID utilisateur et le même mot de passe mais indique que la bibliothèque BIBB doit se trouver dans la liste des bibliothèques. Au moment de l'exécution, le programme B risque, pour finir, d'utiliser la connexion définie par le programme A.

Le pool de connexions est une instance de la classe AS400ConnectionPool de Toolbox. Il reste ouvert jusqu'à la fin de l'exécution de votre application. Cependant, celle-ci peut fermer explicitement le pool en utilisant la méthode getPoolInstance() pour obtenir un descripteur du pool. Grâce à un descripteur du pool, vous pouvez également configurer d'autres paramètres comme le nombre minimal et le nombre maximal de connexions autorisées.

Les connexions sont créées en fonction des besoins. Une fois créées, elle restent dans le pool jusqu'à sa fermeture.

Les exemples ci-après indiquent comment utiliser PooledAS400Connection.

Exemple 1 :

TestProgram pgm = new TestProgram();
LogonSpec logonInfo = new LogonSpec();
logonInfo.setHostName("mySystem");
logonInfo.setUserName("user");
logonInfo.setUserPw("password");
PooledAS400Connection pooledConn = new PooledAS400Connection(TestProgram.getRuntimeContext().getAS400ConnectionPool(), logonInfo);
initConnection(pooledConn);
JcaAS400Connection

Une connexion JcaAS400Connection correspond à une connexion JCA ISeriesPgmCallConnection. La méthode getAS400() effectue une recherche en utilisant le nom JNDI indiqué pour la connexion JCA. Cette connexion doit être une instance d'ISeriesPgmCallConnection. L'objet AS400 renvoyé correspond à celui situé à l'intérieur de la connexion JCA ISeriesPgmCallConnection.

La méthode releaseAS400() permet de fermer la connexion JCA.

Afin d'utiliser la connexion JcaAS400Connection, vous devez définir un projet de connecteur séparé. Pour plus d'informations, voir Configuration du connecteur J2C d'appel de programme IBM i pour l'environnement de test WebSphere.

Exemple 1 : Dans cet exemple, une connexion JCA est créée avec les informations d'ouverture de session par défaut du projet de connecteur JCA.

String jndiName = "my.jca";
JcaAS400Connection jcaConn = new JcaAS400Connection(jndiName);
initConnection(jcaConn);

Exemple 2 : Dans cet exemple, une spécification est fournie pour remplacer les informations d'ouverture de session par défaut du projet de connecteur.

String jndiName = "my.jca";
JcaAS400Connection jcaConn = new JcaAS400Connection(jndiName);
LogonSpec logonInfo = new LogonSpec();
logonInfo.setHostName("mySystem");
logonInfo.setUserName("user");
logonInfo.setUserPw("password");
initConnection(logonSpec, jndiName);
IConnectionFactory

Cette interface correspond à une fabrique de connexions. Elle permet de fournir des connexions personnalisées aux beans d'appel de programme. Si vous l'utilisez, nous vous conseillons de mettre à jour la variable WDT_CONNECTIONFACTORY dans le fichier de configuration d'exécution pour qu'elle désigne votre classe de fabrique de connexions.

ConnectionFactory

Cette classe implémente l'interface IConnectionFactory. En fonction des valeurs indiquées dans le fichier de configuration d'exécution, elle crée les types de connexion IConnection suivants : JcaAS400Connection et PooledAS400Connection.

Messages

Les messages émis par les beans d'appel de programme sont définis dans cette classe. Un fichier Messages.properties correspondant stocke les textes des messages.

Constantes

Les constantes émises par les beans d'appel de programme sont définies dans cette classe.

Indication de l'emplacement du bean Java et du fichier PCML

Avant de commencer
La deuxième page de l'assistant Appel de programme vous permet d'indiquer le dossier dans lequel vous souhaitez générer le bean Java™ et le fichier PCML.
  1. Cliquez sur Parcourir en regard de la zone Dossier pour sélectionner un dossier existant dans lequel vous souhaitez générer le bean Java et le fichier PCML.
  2. Cliquez sur Parcourir en regard de la zone Package pour sélectionner un module existant. Si vous tapez un nom du module qui n'existe pas, l'assistant Appel de programme le crée. Par défaut, il s'agit du module sélectionné à partir de l'espace de travail lorsque vous avez lancé l'assistant Appel de programme.
  3. Indiquez ou sélectionnez le nom à attribuer au fichier PCML généré par l'assistant dans Nom de fichier PCML. Le nom par défaut est le nom du bean Java du premier programme que vous avez défini.
  4. La case Application Java est sélectionnée par défaut.
    • Si vous souhaitez générer un bean Java, ne décochez pas la case Application Java. Les beans Java générés peuvent être utilisés dans du code Java quelconque. Cela comprend toute application Java autonome ou les composants Java d'applications Web tels que des servlets et des pages JSP. L'assistant génère un bean Java pour chaque programme défini.
    • Si vous souhaitez générer un bean Services Web, cochez la case Services Web. Les beans Java permettent alors à l'assistant de création de services Web de créer un service Web.
    • Si vous souhaitez que les appels de programmes soient exécutés avec la classe ProgramCallDocument de Toolbox, cochez la case Utiliser PCML. Vous devez sélectionner cette option si des paramètres ou des zones de votre programme définissent une version minimale ou une version maximale.
  5. Cliquez sur Suivant pour passer à la page suivante de l'assistant Appel de programme, puis précisez si vous souhaitez générer un fichier de configuration d'exécution.
Résultats

L'assistant Appel de programme génère des classes pour chaque programme que vous définissez avec des classes représentant des structures de données. Si vous avez sélectionné l'option permettant de générer un service Web, trois classes supplémentaires seront générées pour chaque programme. L'une est un bean Java dont le nom se termine par Services. Le nom des deux autres classes se termine par Input ou Result. Les deux classes sont requises par la classe du bean Java de services Web. Si vous souhaitez créer un service Web via l'assistant de services Web, vous devez utiliser la classe dont le nom se termine par Services dans l'assistant.

En plus des classes mentionnées ci-dessus, l'assistant génère également des fichiers de classe de support d'exécution pour chaque projet. Pour plus d'informations, voir Classes de support d'exécution.

L'assistant crée un fichier PCML et un fichier .mpcml. Vous n'avez pas besoin du fichier .mpcml pour déployer votre application ou vos services ; il est uniquement utilisé par l'espace de travail au stade de la conception. Par ailleurs, le programme crée également un fichier .config si vous précisez que vous souhaitez enregistrer les paramètres à la troisième page de l'assistant.

Si le dossier indiqué appartient à un projet Java, le chemin d'accès aux classes du projet est mis à jour pour inclure les fichiers JAR suivants. Lorsque vous déployez votre application Java, vérifiez que ces fichiers JAR sont définis dans le chemin d'accès aux classes de l'application. N'oubliez pas que le fichier jar iseriespgmcallclient est ajouté uniquement si votre projet est conforme à l'architecture J2EE.

  • RACINE_WDSC\plugins\com.ibm.etools.iseries.toolbox_numéro_de_version\runtime\jt400.jar
  • RACINE_WDSC\plugins\com.ibm.etools.iseries.javatools_numéro_de_version\lib\confighelper.jar
  • RACINE_WDSC\plugins\com.ibm.etools.iseries.javatools_numéro_de_version\lib\iseriespgmcallclient.jar

Si le dossier indiqué appartient à un projet Web, le programme copie ces fichiers jar dans le dossier lib du projet Web. N'oubliez pas que le fichier jar iseriespgmcallclient est ajouté uniquement si votre projet est orienté vers un serveur conforme à l'architecture J2EE.

Que faire ensuite

Commentaires en retour