EISTI Oracle Toplink Manuel d installation et d utilisation VILLETTE Charles, BEQUET Pierre, DE SAINT MARTIN Cédric, CALAY-ROCHE Vincent, NAUTRE Francois 20/05/2010
Ce manuel d installation et d utilisation est une reprise (en français) de la présentation Oracle officielle, ce manuel y inclus de nombreuses corrections de bugs. Logiciels Prérequis : 1. Oracle XE (version utilisée ici : 11g) 2. Oracle TopLink Workbench 11.1.1.0 3. Eclipse 4. TcpView (en cas de soucis avec Oracle XE, nous y reviendrons) Fichiers utilisés par/dans le tutorial : http://www.oracle.com/technology/products/ias/toplink/doc/11110/tutorial/in tro/intro_tutorial.zip Dans ce zip, vous trouverez : Src contient toutes les sources java. Mw est vide (pour mettre le projet TopLink Workbench). SQL contient les données SQL de l application de test. Notions importantes (bugs corrigés) - Chez certaines personnes, Oracle XE change de port à chaque démarrage malgré lui avoir spécifié le port de fonctionnement, utilisez dans ce cas là le logiciel TcpView pour connaitre tous les ports ouvert sur votre machine, et ainsi trouver les ports utilisés par Oracle (l un d entre eux sera le bon, a part quelques fois ou il faut redémarrer Oracle XE ) - Oracle XE est à utiliser avec Internet Explorer : les sources SQL présent dans le zip tutorial ne marchent pas à partir de Firefox/Chrome (caractère non valide), alors que sous Internet Explorer il n y a pas de problèmes, ceci est nécessaire que lorsqu il est question de se connecter à l interface d administration de Oracle XE. - Il est fortement conseillé (obligatoire) de créer un utilisateur sur la base Oracle, dont le mot de passe et le login sont commun à toutes les personnes travaillant sur le projet, ceci pour des raisons de données stockées dans les XML créés par TopLink. Pour ce faire, connectezvous dans l interface d administration d Oracle à l aide de l utilisateur «root» SYSTEM (le mot de passe seul vous le connaissez!), puis aller dans Administration -> database Users -> Create
Partie Oracle XE : Installez les scripts fournis dans le zip (en se connectant à partir du nouvel utilisateur créé), ils contiennent de quoi créer la base de données, et de quoi la supprimer (vous pouvez utiliser votre propre script, pensez à avoir une table SEQUENCE (voir plus bas/script disponible dans le zip). Pensez pour réaliser cela à utiliser l interface d administration de Oracle XE sous Internet Explorer pour éviter tout bug liés au navigateur (pour une raison inconnue l interface de Oracle XE ne fonctionnait bien que sous Internet Explorer ) Partie Eclipse (1): Cette partie nous servira pour la suite du projet (la configuration de TopLink ne se faisant pas dans Eclipse), nous parlons ici d Eclipse mais cela peut être n importe quel IDE. Un simple projet JEE est ici nécessaire, ensuite il faut rajouter les bibliothèques suivantes (sous eclipse : clic droit sur le projet > properties -> Java Build Path et sélectionner le tab Librairies) Voici les jar à importer : - Toplink.jar (disponible dans le zip ci-dessus) - Ojdbc14.jar (connecteur Oracle XE version java 1.4 (pas besoin d une version plus récente), disponible sur le site d oracle) - Xmlparserv2.jar (utilisé par TopLink pour scanner les XML générés avec TopLink Workbench) - JUnit.jar : junit permet de réaliser des tests unitaires sur un fichier au hasard, nous l utiliserons ici pour tester une fois toute la partie TopLink réalisée. Celui-ci est aisément trouvable sur http://www.junit.org/ La configuration du projet Eclipse s arrête là pour le moment, le reste se faisant principalement sous TopLink Workbench.
Partie TopLink Workbench : TopLink Workbench est un programme Java disponible dans le zip ci-dessus, il est réalisé en java, et permet de créer des XML à utiliser dans le projet Eclipse. Pour le lancer, il faut aller (dans le zip), dans toplink\bin\workbench.cmd Etape 1 : nouveau projet TopLink : Pour cela : Fichier -> nouveau -> projet Peu importe le nom, pensez simplement à sélectionner le Oracle 10g ou supérieur (10g marche très bien pour la version 11g) Etape 2 : indiquer la base de données : Cliquer dans le menu de gauche sur Database, dans le panneau cliquer sur Ajouter, là encore le nom importe peu. Une fois la connexion créée, voila les paramètres standards à utiliser : - Classe pilote : oracle.jdbc.oracledriver - URL : jdbc:oracle:thin:@localhost:1521:xe Attention, après le @ il est question de : 1. Localhost (endroit ou l on accède à Oracle XE), ici notre propre machine 2. 1521 : le port par défaut de Oracle XE, si Oracle XE change de port, pensez à utiliser TcpView pour trouver le bon 3. XE : pour Oracle XE le SID est XE, pour Oracle standard il faut mettre ORCL - Nom d utilisateur : le nom créé dans Oracle XE au tout début du tutoriel - Mot De Passe : le nom créé dans Oracle XE au tout début du tutoriel - Enregistrez le mot de passe -> au choix. Connexion de développement/ déploiement, ici nous sommes dans une situation confondue, si ce n est pas le cas répétez cette Etape, avec cette fois les informations pour la base de données de déploiement, pensez à linker correctement. Etape 3 : test de connexion Voir ci-dessous pour les erreurs classiques Clic droit sur la Database -> se connecter à la base de données.
Erreurs classiques : Erreur de driver : «Classe oracle.jdbc.oracledriver introuvable» Dans ce cas, on sauvegarde notre projet TopLink Workbench, on ferme TopLink Workbench, on va dans toplink\bin\. On édite le fichier workbench.cmd avec un éditeur de texte, on rajoute après «set CLASSPATH=%CLASSPATH%;%THIS%..\jlib» Ceci : set CLASSPATH=%CLASSPATH%;le chemin du jar ojdbc14.jar Sauvegarder le fichier puis relancer workbench.cmd. La manipulation est identique sous linux. Erreur de port : «Exception d E/S : The Network Adapter could not establish the connection» Si vos mots de passes/utilisateur sont bon, et le SID correct, alors il est ici question d un problème de port sous Oracle (ou alors Oracle XE n est pas lancé), utilisez TcpView pour trouver le bon port... Etape 4 : Importer la base Une fois votre connexion réussie, clic droit sur Database -> Ajouter ou mettre à jour des tables existantes Modèle de schéma : sélectionner le nom d utilisateur définit au début. Cliquer sur Obtenir les noms de tables Importez alors toutes les tables créées avec le script précédent. Cliquez sur OK une fois ceci fait.
Etape 5 : Sequence : Sous Oracle XE, les séquences permettent de créer une sorte de AUTO_INCREMENT sur les IDs permettant de ne pas les manipuler les ids uniques (et ainsi éviter les erreurs d ids unique déjà présent en Base de données). Clic sur le projet, puis sélectionner le tab Séquencement Cocher Table de séquence personnalisée : Nom : SEQUENCE Champ Nom : SEQUENCE.SEQ_NAME : VARCHAR2 Champ Nombre : SEQUENCE.SEQ_COUNT : NUMBER NOTE : cette partie ne semble pas marcher malgré que TopLink Workbench n indique pas d erreur. Etape 6 : Classe Java Nous allons ici créer les relations entre notre base de données importées sous TopLink Workbench et des classes java. Pour cela, développer le menu Database, et prennez une table (peu importe), clic droit dessus -> Générer des classes et des descripteurs à partir de -> Toutes les tables Indiquez un package (celui de votre choix), ce package sera utilisé tel quel dans eclipse. Puis valider, votre projet comporte maintenant les classes Java correspondant à chaque tables importées dans TopLink Workbench. Si dans la partie problème (en bas), il existe une erreur de marquée, vous devez alors la corriger : si cette erreur est simplement liées à un mapping raté entre les tables et les classes java, vous pouvez développer le package dans le menu, et changer manuellement les classes et leur contenu. Etape 7 : création du premier XML Nous allons créer le premier XML liés à notre projet, celui-ci ne contient rien de gênant (vous pouvez le passer sans soucis à un camarade), ce ne sera pas le case du deuxième Pour cela, rien de plus simple : clic droit sur le projet dans le menu de gauche, puis export -> fichier XML de déploiement du projet.
Celui-ci est à mettre dans le projet Eclipse dès maintenant. Il n y a pas de place indiquée pour cela, nous l avons mis dans le dossier WebContent/META-INF sous Eclipse Etape 8 : Sessions.xml Ce XML, comparé au précédent, n est pas générique : il DOIT porter ce nom (sessions.xml), et comporte de nombreuses informations (toujours les mêmes), pour Toplink.jar sous Eclipse. Cependant ce XML est générique en termes d informations que l on peut y trouver (toujours la même structure), mais différente presque pour chaque pc Créer une session Pour ce faire, dans notre projet toujours ouvert, faire Fichier -> nouveau -> session Ensuite : clic droit sur sessions qui vient d apparaitre : nouveau -> session Ensuite : clic sur session qui vient d apparaitre : à droite dans le tab Projet, allez chercher le XML créé à l instant à l étape 7. Dans le tab connexion, ré indiquez les informations de connexions à Oracle (voir etape 2). Dans le tab Journalisation, sélectionnez standard, puis niveau de journalisation à fine. Sauvegardez le tout sous sessions.xml (clic sur sessions -> clic droit -> Enregistrer sous ) Ce fichier doit aussi être placé dans Eclipse, je vous conseille au même endroit que le précédent XML. Ce fichier n est pas vraiment interchangeable, il faut pour cela le modifier en conséquence : <primary-project xsi:type="xml"> -> il faut modifier ici le chemin d accès (le nouveau), pour notre XML de l étape 7, ce chemin peut être relatif (je vous le conseille vivement) <connection-url> -> si vous avez des soucis avec Oracle XE au niveau des ports, il faudra à chaque redémarrage de la BDD modifier en conséquence cette ligne. Cette opération est d ailleurs aussi à faire dans le XML généré à l étape 7! Etape 9 : dernière vérification Dans TopLink Workbench, sélectionnez le menu Outils -> problèmes Si rien ne s affiche, tout est bon, sinon prenez le temps de revoir ou il y a un soucis!
Partie Eclipse (2): Nous revenons maintenant sous Eclipse, veuillez ajouter les fichiers java présents dans zip, ensuite sélectionnez ModelTest.java (dans le zip), et sélectionnez : Run AS -> JUNIT Test Si JUnit Test ne met pas d erreur, TopLink est donc maintenant fonctionnel, regardez du côté de ModelTest.java pour apprendre à le manipuler. Dernièrement, le passage de JUnit à une application réelle n est pas aisée avec le projet en l état, voici donc une classe de connexion TopLink permettant de réaliser cela sans JUnit : Pensez à modifier getsessionsxmlpath et getsessionname avec les configurations de vos XMLs.
package bdd; import oracle.toplink.sessions.databasesession; import oracle.toplink.sessions.project; import oracle.toplink.sessions.session; import oracle.toplink.tools.sessionconfiguration.xmlsessionconfigloader; import oracle.toplink.tools.sessionmanagement.sessionmanager; import oracle.toplink.tools.workbench.xmlprojectreader; public class TopLinkManager { private static DatabaseSession session = null; public TopLinkManager() { Project myproject = XMLProjectReader.read(getSessionsXmlPath()); session = myproject.createdatabasesession(); public static String getsessionsxmlpath() { return "META-INF/sessions.xml"; public static String getsessionname() { return "Session"; public static Session getsession() {
if (session == null) { XMLSessionConfigLoader loader = new XMLSessionConfigLoader(getSessionsXmlPath()); SessionManager mgr = oracle.toplink.tools.sessionmanagement.sessionmanager.getmanager(); session = (DatabaseSession) mgr.getsession(loader,getsessionname(), Thread.currentThread().getContextClassLoader(), true, true); return session; Normalement en l état vous avez tout ce qu il faut pour utiliser toplink sans erreur sous Eclipse avec Oracle XE database.