How to use the XDocletJ2EETest project.doc
Upcoming SlideShare
Loading in...5
×
 

Like this? Share it with your network

Share

How to use the XDocletJ2EETest project.doc

on

  • 360 views

 

Statistics

Views

Total Views
360
Views on SlideShare
360
Embed Views
0

Actions

Likes
0
Downloads
2
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Microsoft Word

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

How to use the XDocletJ2EETest project.doc Document Transcript

  • 1. How to use the XDocletJ2EE Test – project This document describes how to use the XDocletJ2EETest – project to verify that a J2EE-server specific XDoclet - module works as expected. Currently the following XDoclet - modules are covered: 1. JBoss (v3.2) 2. IBM WebSphere (v5.1) Content: HOW TO USE THE XDOCLETJ2EE TEST – PROJECT....................................1 1 INTRODUCTION.....................................................................................................2 2 PROJECT AND FILE STRUCTURE.....................................................................3 3 INSTALLING REQUIRED SOFTWARE.............................................................4 3.1 POST INSTALLATION STEPS..........................................................................................4 4 CONFIGURATION..................................................................................................5 4.1 CONFIGURING J2EE ENVIRONMENT VARIABLES............................................................5 4.2 CONFIGURE JBOSS....................................................................................................5 4.3 CONFIGURE WEBSPHERE...........................................................................................5 5 BUILDING THE EAR-FILES.................................................................................7 6 DEPLOYMENT .......................................................................................................7 6.1 DEPLOYMENT ON JBOSS............................................................................................7 6.2 DEPLOYMENT ON WEBSPHERE....................................................................................8 6.2.1 Post-deployment actions on WebSphere.......................................................8 7 TEST...........................................................................................................................8 7.1 TEST ON JBOSS........................................................................................................8 7.2 TEST ON WEBSPHERE...............................................................................................8 7.3 SAMPLE EXPECTED TEST RESULT..................................................................................8
  • 2. 1 Introduction This document id divided in the following chapters: • Project and file structure Describes the subprojects and their main content • Installing required software Describes what software that is required • Configuration Describes how to prepare the J2EE server before deployment (mostly regarding how to define J2EE resources required by the EAR-files) • Building the EAR-files How to use the supplied Ant-scripts for creation of the EAR-files • Deployment How to deploy the EAR-files on the J2EE-servers • Test Finally, but most important… How to run the tests to verify that the XDoclet modules works as expected!
  • 3. 2 Project and file structure The project is divided in the following Eclipse-projects: • CommonAnt Contains common files, such as Ant-scripts • Doc Contains documentation such as this document. • XDocletJ2eeTestEar Contains the specific Ant-scripts for the main J2EE EAR-application. The Ant-script place the ear-file under the folder XDocletJ2eeTestEar/build/deploy. It also contains JBoss specific configuration-files for J2EE resources that the application requires. • XDocletJ2eeTestEjb Contains the most of the EJB’s “under test” • XDocletJ2eeTestWeb Contains the Web-components “under test” (i.e. servlets) but most important all the JUnitEE based TestCases! • XDocletJ2eeTestUtil Contain some common code that is shared between two or more other project. • XDocletJ2eeTestExternalEar Contains the specific Ant-scripts for a small J2EE EAR-application that is used to test external EJB-calls, i.e. calls to EJB’s that lives in another EAR - application. • XDocletJ2eeTestExternalEjb Contains a single EJB to be used to test external EJB-calls
  • 4. • XDocletJ2eeTestExternalWeb Actually not used, just there to make the “not so bright” Ant-scripts happy… 3 Installing required software The following software needs to be installed to be able to build and run the XDocletJ2EE Test – project (all version numbers point out the version being used during development of the project) • Java SDK v1.4.2 • Eclipse v3.0.0 • Ant v1.6.2 • XDoclet v1.2 • JUnitEE v1.10 NOTE: Log4J is also used but its jar-file is placed in the Ear-projects so no separate installation is required. The following is also required for testing JBoss: • JBoss v2.3.2 The JDBC DataSource used in the tests is based on the embedded Hypersonic database engine so no extra database software is required to install. The following is also required for testing IBM WebSphere: • IBM WebSphere v5.1 (base server is sufficient) • IBM Db2 v8.1 3.1 Post installation steps Some of the installation – directories of the required software must be specified in the file CommonAnt/enviroment.properties under the section “Environment settings”. The following properties must be updated: java.home=... ant.home=... xdoclet.home=... junitee.home=... jboss.home=... Also update the property xdoclet.jarFileToValidate to reflect what version of XDoclet you are using. The property is expected to point out the xdoclet-n.n.jar file under ${xdoclet.home}/lib. For example if XDoclet v1.2 is used: xdoclet.jarFileToValidate=xdoclet-1.2.jar
  • 5. 4 Configuration 4.1 Configuring J2EE Environment Variables The XDocletJ2EETest – project uses J2EE Environment Variables to enable an easy way to configure parts of the source code. The value for each J2EE Environment Variable is configured in the file CommonAnt/enviroment.properties under the section “J2EE environment variables”. The following environment variables are used: 1. email.adress: Specifies the email-address that tests on the mail-api uses to send test mails to. 4.2 Configure JBoss Configuration of JBoss specific J2EE resources (JDBC datasource, JMS factories and destinations and so on…) is very simple. Copy the files under XDocletJ2eeTestEar/ src/jboss3.2.3/deploy to ${jboss.home}/server/default/deploy. You must however modify the property mail.smtp.host for the mail-service defined in the file …/deploy/XDocletJ2eeTest-service.xml – file. This property must point out an smtp-server that you have access to. Otherwise the tests on J2EE-mail- resources will fail. Under XDocletJ2eeTestEar/src/jboss3.2.3/conf you can also find a configuration file for log4j that has been modified to set up log4j to log events in the XDocletJ2eeTest – code. You may copy it to {jboss.home}/server/default/conf if you are interested in XDocletJ2eeTest log-messages. 4.3 Configure WebSphere This version of the XDocletJ2eeTest – project does not provide any support for automatic configuration of J2EE resources in WebSphere (under CommonAnt/websphere you can however find some “work under progress” material). Instead you have to use the Admin Console (http://localhost:9090/admin) to configure the resources manually . However, if you are used to the Admin Console you will be able to perform the configuration manually in some 10 minutes . The following J2EE resource has to be defined (see section “XDocletJ2eeTest jndi-names” in CommonAnt/enviroment.properties): 1. A non-XA enabled JMS Queue Connection Factory a. JNDI-name: queue/xdocletj2eetest/QueueConnectionFactoryNoXA NOTE: To simplify configuration of JMS use the Built-in “WebSphere JMS Provider” and not the “WebSphere MQ JMS Provider”. 2. A XA enabled JMS Queue Connection Factory
  • 6. a. JNDI-name: queue/xdocletj2eetest/QueueConnectionFactoryXA 3. Two queues a. JNDI-names: queue/xdocletj2eetest/MDBQueueIn and queue/xdocletj2eetest/MDBQueueOut b. Don’t forget to add the queues to the JMS Server! • In a “base server” configuration you will find the JMS Server under “Servers Application Servers server1 Server Components  JMS Server” • Add the Queue-names (not the JNDI-names!) of the two queues in the property “Queue names”, one queue-name per line. 4. A Queue Listener Port a. Name: XDocletJ2eeTestQueueListenerPort b. Queue Connection Factory: queue/xdocletj2eetest/QueueConnectionFactoryXA c. Queue: queue/xdocletj2eetest/MDBQueueIn 5. A non-XA enabled JMS Topic Connection Factory a. JNDI-name: topic/xdocletj2eetest/TopicConnectionFactoryNoXA b. Set Port to “QUEUED” 6. A XA enabled JMS Topic Connection Factory a. JNDI-name: topic/xdocletj2eetest/TopicConnectionFactoryXA b. Set Port to “QUEUED” 7. Two topics a. JNDI-names: topic/xdocletj2eetest/MDBTopicIn and topic/xdocletj2eetest/MDBTopicOut b. Also set the Topic-property to MDBTopicIn and MDBTopicOut 8. A Topic Listener Port a. Name: XDocletJ2eeTestTopicListenerPort b. Topic Connection Factory: topic/xdocletj2eetest/TopicConnectionFactoryXA c. Topic: topic/xdocletj2eetest/MDBTopicIn 9. A JDBC Data Source (must no be XA enabled) a. JNDI-name: jdbc/xdocletj2eetest/Database NOTE: If your are not familiar with configuration of a DataSource for Db2 v8.1 you might find it easiest to define a non-XA enabled DataSource (using the “DB2 Universal JDBC Driver Provider“) based on Db2’s Type 4 JDBC Driver (i.e. pure Java on the client side). Remember to pay extra attention to: • Select “Use this Data Source in container managed persistence (CMP)” • Setting “Custom Properties”
  • 7. o Set the “driverType” to 4. o Set the “serverName” to the name of the server that runs Db2. o Set the “portNumber” used by the Db2 DRDA-listener (by default it is set by the first Db2-instance on a server to 50000). • Create a Authentication Alias under “J2C Authentication Data Entries” and specify it on the property named “Container-managed Authentication Alias” • Also point out for WebSphere where you have installed Db2 o Under “Environment  Manage WebSphere Variables” point out the folder for the Db2 v8.1 JDBC Driver, db2jcc.jar in the variable DB2UNIVERSAL_JDBC_DRIVER_PATH.  On Windows it is typically C:Program FilesIBMSQLLIBjava  On Linux it is typically /opt/IBM/db2/V8.1/java 10. A mail session a. JNDI-name: mail/xdocletj2eetest/MailSession b. Mail Transport Host for SMTP: A valid smtp-host that you can use to sent test-mails from… c. Mail From: A proper id, e.g. XDocletJ2eeTest.WebSphere@callista.se 11. A URL-resource a. JNDI-name: url/xdocletj2eetest/TestUrl b. URL: Any accessible web-page of your choice (the test only verifies that it can access the page. It does not check its content) Finally, due to some unresolved classloader - problem, you need to set the classloader of the server to single: 1. Select the server from “Servers  Application Servers  server1” 2. Set the property “Application classloader policy” to “Single”. 5 Building the EAR-files To build the ear-files run the ant-scripts for each EAR-project: 1. XDocletJ2eeTestEar/build.xml 2. XDocletJ2eeTestExternalEar/build.xml To remove all generated code and binary files run the Ant-scripts above with the target “cleanAll”. 6 Deployment 6.1 Deployment on JBoss Done automatically by the build script, no extra work required. The two EAR-files are copied to the folder ${jboss.home}serverdefaultdeploy and JBoss will hot-deploy the ear-files if JBoss already is running.
  • 8. 6.2 Deployment on WebSphere Must be done manually using the Admin Console (http://localhost:9090/admin) for now… If the J2EE resources were defined correctly in the step above it just takes a few minutes . 6.2.1 Post-deployment actions on WebSphere WebSphere does not automatically create database tables for CMP Entity Beans during the deployment of an EAR-file. Instead WebSphere creates a SQL DDL file that it stores in the deployed ejb-module that contains the corresponding CMP Entity Beans. Therefore we need to do the following after deployment: 1. Extract sql-ddl from the deployed ejb-jar and create the tables manually in Db2: a. Extract the file /meta-info/Table.ddl from the jar-file $ {WEBSPHERE_HOME}AppServerinstalledApps$ {YOUR_NODE}XDocletJ2eeTestEar.earXDocletJ2eeTestEjb.jar . 2. Run the commands in the DDL-file in the Db2 - “Command Center” to create the database tables for the “CMP Entity Beans”. 7 Test 7.1 Test on JBoss Try the URL: http://localhost:8080/XDocletJ2eeTest/test.html and hit the button. NOTE: Assuming that JBoss listens for HTTP-requests on its default port 8080 . If everything worked as expected you will get a test result similar to the one below! 7.2 Test on WebSphere Try the URL: http://localhost:9080/XDocletJ2eeTest/test.html and hit the button. NOTE: Assuming that WebSphere listens for HTTP-requests on its default port 9080 . If everything worked as expected you will get a test result similar to the one below! 7.3 Sample expected test result JUnit Test Results Summary of test results xdoclet.j2eetest.web.TestSessionBeans 1,202 sec
  • 9. xdoclet.j2eetest.web.TestMessageDrivenBeans 2,133 sec xdoclet.j2eetest.web.TestCMPBeans 0,711 sec xdoclet.j2eetest.web.TestResources 0,851 sec List of executed tests xdoclet.j2eetest.web.TestSessionBeans testJndi(xdoclet.j2eetest.web.TestSessionBeans) 0,691 sec testLocalSLSB(xdoclet.j2eetest.web.TestSessionBeans) 0,040 sec testRemoteSLSB(xdoclet.j2eetest.web.TestSessionBeans) 0,020 sec testLocalSFSB(xdoclet.j2eetest.web.TestSessionBeans) 0,241 sec testRemoteSFSB(xdoclet.j2eetest.web.TestSessionBeans) 0,140 sec testInvalidSFSB(xdoclet.j2eetest.web.TestSessionBeans) 0,020 sec testEJBLocalSLSBCall(xdoclet.j2eetest.web.TestSessionBeans) 0,010 sec testEJBLocalSFSBCall(xdoclet.j2eetest.web.TestSessionBeans) 0,000 sec testEJBRemoteSLSBCall(xdoclet.j2eetest.web.TestSessionBeans) 0,000 sec testEJBRemoteSFSBCall(xdoclet.j2eetest.web.TestSessionBeans) 0,020 sec testExternalRemoteCall(xdoclet.j2eetest.web.TestSessionBeans) 0,010 sec testEJBExternalRemoteCall(xdoclet.j2eetest.web.TestSessionBeans) 0,010 sec xdoclet.j2eetest.web.TestMessageDrivenBeans testQueueMDBfromWeb(xdoclet.j2eetest.web.TestMessageDrivenBeans) 0,441 sec testQueueMDBfromEjb(xdoclet.j2eetest.web.TestMessageDrivenBeans) 0,100 sec testTopicMDBfromWeb(xdoclet.j2eetest.web.TestMessageDrivenBeans) 0,921 sec testTopicMDBfromEjb(xdoclet.j2eetest.web.TestMessageDrivenBeans) 0,671 sec xdoclet.j2eetest.web.TestCMPBeans testParentCMP(xdoclet.j2eetest.web.TestCMPBeans) 0,701 sec testChildCMP(xdoclet.j2eetest.web.TestCMPBeans) 0,010 sec xdoclet.j2eetest.web.TestResources testDataSourceFromWeb(xdoclet.j2eetest.web.TestResources) 0,120 sec testDataSourceFromEjb(xdoclet.j2eetest.web.TestResources) 0,010 sec testURLFromWeb(xdoclet.j2eetest.web.TestResources) 0,181 sec testURLFromEjb(xdoclet.j2eetest.web.TestResources) 0,200 sec testMailSessionFromWeb(xdoclet.j2eetest.web.TestResources) 0,220 sec testMailSessionFromEjb(xdoclet.j2eetest.web.TestResources) 0,120 sec