Skip to main content
Jump to: navigation, search

EclipseLink/Examples/JPA/JBoss Web Tutorial

< EclipseLink‎ | Examples‎ | JPA
Revision as of 23:28, 17 February 2010 by (Talk | contribs) (EclipseLink JPA Deployed on JBoss 6.0.0 M1 using Eclipse 3.5 EE edition)

EclipseLink JPA Deployed on JBoss 6.0.0 M1 using Eclipse 3.5 EE edition

20100217: Update for results of EclipseLink 2.0 on JBoss 6.0.0M1 in progress

If you want to get a small web application running quickly on JBoss 6 use the services provided by the Web Tools Project project as part of the EE edition of the Eclipse IDE to take care of deployment details for you.

This basic example details how to use Eclipse to run/debug a minimum J2EE web application servlet using EclipseLink JPA as the persistence provider. The goal of this example is to detail the minimum steps needed to run EclipseLink inside JBoss using the Eclipse IDE - at this point no presentation/controller layer such as JSF, Spring or Struts will be used beyond a basic HttpServlet so we can concentrate on the the integration layer JPA setup.

Tutorial Source

The EAR, EJB and WEB Eclipse project source for this EclipseLink JBoss (JPA) tutorial is available online at the following locations. These 3 projects must be imported along with the jpa core eclipselink project or jar.

  • Checkout the following 3 projects together from $trunk/examples.
    • org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEAR
    • org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEJB
    • org.eclipse.persistence.example.jpa.server.jboss.EnterpriseWeb
  • EclipseLink source via SVN committer access


  • EclipseLink source via SVN anonymous access


The following link will put you at the root of the SVN tree using the online version of subclipse.

  • As an alternative if you do not wish to use SVN or the direct html links into SVN - I have attached a version of the EAR including source to enhancement bug # 250477 in versions for JBoss 5.1.0' (JPA 1.0) and JBoss 6.0.0M1 (JPA 2.0) - except that these may not be in sync with the latest SVN repository changes.

Development Environment

Hardware: Windows 7 64-bit, Core i7 920 Quad Core, 2.7Ghz, 12Gb Ram

Software: Eclipse IDE for Java EE 3.5 Galilleo (Nov 2009), Java JDK 1.6.0_17, JBoss 6.0.0M1 including the HSQL database.

This example will run fine with an older version of Eclipse to version 3.4 and any Database that EclipseLink supports.


  • Install Eclipse
    • I installed a clean version of Eclipse 3.5 Galileo SR1 EE edition with all of WTP 3.0
      • Note: The 64-bit edition currently has issues with EE server plugins - stick to the 32 bit version for now.
    • Eclipse arrives standard with JBoss 5.0 support - you may use the 5.0 version to deploy to 6.0 servers.
  • Install a Database
    • In this example I am using the HSQL database shipped with JBoss - therefore no database installation is required for this tutorial.

JBoss Server Configuration Changes

  • Launch the JBoss AS Administration console to view the configuration at
    • Username/password is admin/admin
  • You don't need to change anything if you use the default HSQL database - otherwise you must add your own datasource.

HSQL Hypersonic Default Datasource

  • The included DefaultDS datasource resolved to the URL jdbc:hsqldb:C:\opt\jboss600m1\server\default\data\hypersonic\localDB - replace "C:\opt\jboss600m1" with your $JBOSS_INSTALL_DIR.

Custom Datasource Configuration Details

JNDI JTA/non-JTA Server DataSource Setup
  • Copy $JBOSS_HOME\docs\examples\jca\oracle-*ds.xml to $JBOSS_HOME\server\default\deploy
  • Edit oracle-ds.xml
  • Enter the following into $JBOSS_HOME\server\default\deploy\oracle-ds.xml
  • Edit oracle-xa-ds.xml
  • Enter the following into $JBOSS_HOME\server\default\deploy\oracle-xa-ds.xml
    <xa-datasource-property name="URL">jdbc:oracle:thin:@localhost:1521:orcl</xa-datasource-property>
    <xa-datasource-property name="User">username</xa-datasource-property>
    <xa-datasource-property name="Password">password</xa-datasource-property>
  • Enter the following into $JBOSS_HOME\server\default\conf\login-config.xml
<application-policy name = "OracleDbRealm"> 
      <login-module code =  
  "" flag = "required"> 
         <module-option name = "principal">sa</module-option> 
         <module-option name = "userName">sa</module-option> 
         <module-option name = "password"></module-option> 
         <module-option name = "managedConnectionFactoryName">jboss.jca:service=LocalTxCM,name=OracleDS</module-option> 
JNDI/JNP Port Conflict Workarounds

You may get the following port 1099 conflict if you are also running an Oracle Database.

14:56:41,597 ERROR [Naming] Could not start on port 1099 Address already in use: JVM_Bind at Method)

Try changing the following jboss:service=Naming port to any available port, keep the RmiPort at 1098. Use [netstat -a] to check free ports - in my case 1099 is taken by the 1521 orcl listener.

  TCP    yourpc:1099  ESTABLISHED


   <mbean code="org.jboss.naming.NamingService"
      <attribute name="Port">1199</attribute>
      <attribute name="Port">1099</attribute>
  • Eclipse WTP Server configuration

Open the server configuration on the [servers] view and change [Server Properties/JNDI Port] to 1199

  • <app>/

You will also need to sync this port change in your file (mine is off my web application under src/ just above META-INF.


Downloading EclipseLink Libraries

Download EclipseLink using HTTP - recommended

Download EclipseLink using Maven

See the repository on

Download EclipseLink using SVN - developers only

EclipseLink JAR location

All Servers

The eclipselink.jar should be placed next to the ejb3-persistence.jar (JBoss 5.1.0) off of $JBOSS_HOME/common/lib

Specific Server

The eclipselink.jar should be placed off of $JBOSS_HOME/server/default/lib

JDBC JAR location

Copy your jdbc driver jar to $JBOSS_HOME/common/lib

Create server in Eclipse

Open the servers view New | Server | JBoss | JBoss v5.0 - ok for 6.0 use.

Create J2EE application

Check out the 3 example projects in the trunk '(TBD) or create your own J2EE Enterprise Application as below. File | new | project | J2EE | Enterprise Application Project Select server, use 5.0 Ear version

Create a new Web and an optional EJB project

Select generate deployment descriptor if you want to change the context-root

UML Data Model

The following single entity Cell has a @ManyToMany bidirectional relationship to itself.

Eclipselink server jee jpa examples datamodel.gif

Tutorial Design

The goal of the tutorial is to demonstrate a quick start end-to-end deployment on a specific application server of an EclipseLink JPA application. To accomplish this...

  • The web framework is a simple servlet so we avoid container specific issues around a JSF implementation.
  • The data model is very simple (@ManyToMany) - as the other tutorials get into more advanced JPA entity concepts and annoations
  • The entityManager is container managed where possible by injection
  • The schema is generated by DDL generation in a separate common application managed SE app for an Oracle DB (because of an implicit auto-commit on create table) or directly when using HSQL.
  • The application context name is standard across servers
  • The datasource is globally defined (by the user) on the server - with the only configuration setting being the jta-data-source element in persistence.xml

DDL/Schema Generation

Reference EclipseLink and JPA - Path changes

  • Either link to the 2 SVN projects below or link to an external eclipselink.jar and javax-persistence.jar.
	<classpathentry combineaccessrules="false" kind="src" path="/eclipselink.core"/>
	<classpathentry combineaccessrules="false" kind="src" path="/eclipselink.jpa"/>
  • After EAR project creation - reference eclipselink.core and eclipselink.jpa or include a reference to eclipselink.jar in your WAR project.
  • If you don't reference the eclipselink.* projects then include a classpath reference to persistence.jar and an Oracle JDBC driver jar for your DB - You will need to put this JDBC driver jar in your JBoss /server/default/lib directory as well.

@EJB Injection is not available to Servlets - use a JNDI lookup

In JBoss the JEE @EJB annotation has no effect when trying to inject you session bean that holds the entityManager.

  @EJB(beanName="ApplicationService") // No effect in JBoss

Use the following JNDI name and lookup in your Servlet where org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEAR is the name of your EAR project and ApplicationService is the name of your @Local @Stateless session bean.

public class FrontController extends HttpServlet implements Servlet {
public static final String APPLICATION_SERVICE_JNDI_NAME = "org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEAR/ApplicationService/local";
  @EJB(beanName="ApplicationService") // No effect in JBoss
  public ApplicationServiceLocal applicationService;
  public ApplicationServiceLocal getApplicationService() {
    if(null == applicationService) {
      try {
        Hashtable env = new Hashtable();      
        env.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory");     
        env.put(Context.PROVIDER_URL, "localhost");      
        env.put(Context.URL_PKG_PREFIXES, "org.jboss.naming:org.jnp.interfaces" );     
        InitialContext ctx = new InitialContext(env);
        return (ApplicationServiceLocal) ctx.lookup(APPLICATION_SERVICE_JNDI_NAME);            
      } catch (Exception e) {
        throw new RuntimeException("Datasource not available - lookukp failed: ", e);
    } else {
      return applicationService;


  • JTA is the default transaction-type when deployed in an EE container.
  • JTA : Put persistence.xml beside your JPA entities in yourProjectEJB/ejbModule/META-INF
  • Note: Your <jta-data-source> or <non-jta-data-source> element in persistence.xml must match the JNDI Name: on the server admin page.
<persistence version="2.0" xmlns="" xmlns:xsi="" xsi:schemaLocation="">
    <persistence-unit name="example" transaction-type="JTA">
            <!-- Application managed datasource -->
            <property name="" value="JBoss"/>
            <property name="" value="HSQL"/>
            <!-- remove for production -->
            <property name="eclipselink.ddl-generation" value="drop-and-create-tables"/>
            <property name="eclipselink.ddl-generation.output-mode" value="database"/>
            <property name="eclipselink.logging.level" value="FINEST"/>

Start Server

  • Steps: Select the EAR and [Run on Server].
  • The first "Run on Server" may not start the server, in this case you "Start Server" and then "Run on Server".

Publish EAR

  • Publishing to JBoss 6 is very simple, once the server is setup you can just drop/remove an EAR in the deploy directory to deploy/undeploy an application. Or use Eclipse to debug via the 5005 port if the server is managed through WTP.
  • Eclipse WTP will take care of copying the EAR file to the live deploy directory when you either [re-publish] or modify any files while the server is running.
  • You may also use any combination of running the JBoss server yourself in run or debug mode and using eclipse to publish EAR changes.
  • Dynamic weaving is disabled for now because of [JIRA-572] - Use static weaving workaround before deploying if required. This affects change tracking and lazy loading only.
  • Depending on your application you will see the following after running [start server]
    • In your console window you will see one process both for the server and the deploy target.
2010-02-17 22:17:26,316 INFO  [org.jboss.resource.connectionmanager.ConnectionFactoryBindingService] (Thread-2) Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=DefaultDS' to JNDI name 'java:DefaultDS'
2010-02-17 22:17:33,217 INFO  [org.jboss.ejb3.deployers.JBossASKernel] (Thread-2) Created KernelDeployment for: org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEJB.jar
2010-02-17 22:17:33,217 INFO  [org.jboss.ejb3.deployers.JBossASKernel] (Thread-2) installing bean: jboss.j2ee:ear=org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEAR.ear,jar=org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEJB.jar,name=ApplicationService,service=EJB3
2010-02-17 22:17:35,637 INFO  [STDOUT] (Thread-2) [EL Finest]: 2010-02-17 22:17:35.637--ServerSession(7054061)--Thread(Thread[Thread-2,5,jboss])--End predeploying Persistence Unit example; session vfszip:/C:/opt/jboss600m1/server/default/deploy/org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEAR.ear/org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEJB.jar/_example; state Predeployed; factoryCount 1
2010-02-17 22:17:35,730 INFO  [org.jboss.ejb3.session.SessionSpecContainer] (Thread-2) Starting jboss.j2ee:ear=org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEAR.ear,jar=org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEJB.jar,name=ApplicationService,service=EJB3
2010-02-17 22:17:35,746 INFO  [org.jboss.ejb3.EJBContainer] (Thread-2) STARTED EJB: ejbName: ApplicationService
2010-02-17 22:17:36,199 INFO  [org.jboss.bootstrap.impl.base.server.AbstractServer] (Thread-2) JBossAS [6.0.0.M1 (build: SVNTag=JBoss_6_0_0_M1 date=200912040958)] Started in 43s:528ms

Perform a JPQL query

  • At this time you can initialize your application in a browser - notice the use of the non-jta datasource
public class ApplicationService implements ApplicationServiceLocal  {
	private EntityManager entityManager;

Console Output

2010-02-17 22:23:14,955 INFO  [STDOUT] (http- [EL Info]: 2010-02-17 22:23:14.955--ServerSession(7054061)--Thread(Thread[http-,5,jboss])--EclipseLink, version: Eclipse Persistence Services - 2.1.0.qualifier
2010-02-17 22:23:14,986 INFO  [STDOUT] (http- [EL Config]: 2010-02-17 22:23:14.986--ServerSession(7054061)--Connection(18421505)--Thread(Thread[http-,5,jboss])--Connected: jdbc:hsqldb:C:\opt\jboss600m1\server\default\data\hypersonic\localDB
	User: SA
	Database: HSQL Database Engine  Version: 1.8.0
	Driver: HSQL Database Engine Driver  Version: 1.8.0
2010-02-17 22:23:15,204 INFO  [STDOUT] (http- [EL Fine]: 2010-02-17 22:23:15.204--ServerSession(7054061)--Connection(32007964)--Thread(Thread[http-,5,jboss])--DROP TABLE EL_CELL
2010-02-17 22:23:15,204 INFO  [STDOUT] (http- [EL Finest]: 2010-02-17 22:23:15.204--ServerSession(7054061)--Thread(Thread[http-,5,jboss])--Execute query DataModifyQuery(sql="CREATE TABLE EL_CELL (ID BIGINT NOT NULL, STATE VARCHAR(255), TSEQ VARCHAR(255), RIGHT_ID BIGINT, ACELLATTRIBUTE_ID INTEGER, PRIMARY KEY (ID))")
2010-02-17 22:23:15,204 INFO  [STDOUT] (http- [EL Finest]: 2010-02-17 22:23:15.204--ServerSession(7054061)--Thread(Thread[http-,5,jboss])--reconnecting to external connection pool
2010-02-17 22:23:15,204 INFO  [STDOUT] (http- [EL Fine]: 2010-02-17 22:23:15.204--ServerSession(7054061)--Connection(12574077)--Thread(Thread[http-,5,jboss])--CREATE TABLE EL_CELL (ID BIGINT NOT NULL, STATE VARCHAR(255), TSEQ VARCHAR(255), RIGHT_ID BIGINT, ACELLATTRIBUTE_ID INTEGER, PRIMARY KEY (ID))
2010-02-17 22:23:16,282 INFO  [STDOUT] (http- [EL Finest]: 2010-02-17 22:23:16.282--UnitOfWork(1394419)--Thread(Thread[http-,5,jboss])--Execute query InsertObjectQuery( id: 2 state: null left: null right: null parent: HashSet@54753502 references: HashSet@54753502))
2010-02-17 22:23:16,297 INFO  [STDOUT] (http- [EL Finest]: 2010-02-17 22:23:16.297--ClientSession(15006870)--Thread(Thread[http-,5,jboss])--reconnecting to external connection pool
2010-02-17 22:23:16,297 INFO  [STDOUT] (http- [EL Fine]: 2010-02-17 22:23:16.297--ClientSession(15006870)--Connection(15718095)--Thread(Thread[http-,5,jboss])--INSERT INTO EL_CELL (ID, STATE, TSEQ, RIGHT_ID, ACELLATTRIBUTE_ID) VALUES (?, ?, ?, ?, ?)
	bind => [2, null, null, null, null]
2010-02-17 22:23:16,329 INFO  [STDOUT] (http- [EL Finer]: 2010-02-17 22:23:16.329--UnitOfWork(1394419)--Thread(Thread[http-,5,jboss])--TX afterCompletion callback, status=COMMITTED
2010-02-17 22:23:16,329 INFO  [STDOUT] (http- [EL Finer]: 2010-02-17 22:23:16.329--UnitOfWork(1394419)--Thread(Thread[http-,5,jboss])--end unit of work commit
2010-02-17 22:23:16,375 INFO  [STDOUT] (http- FrontController.getApplicationService() JNDI lookup of org.eclipse.persistence.example.jpa.server.jboss.EnterpriseEAR/ApplicationService/local
2010-02-17 22:23:16,734 INFO  [STDOUT] (http- _Test: JPA 2.0 Metamodel: MetamodelImpl@31657000 [ 5 Types: , 2 ManagedTypes: , 2 EntityTypes: , 0 MappedSuperclassTypes: , 0 EmbeddableTypes: ]
2010-02-17 22:23:16,734 INFO  [STDOUT] (http- [EL Finest]: 2010-02-17 22:23:16.734--UnitOfWork(20126243)--Thread(Thread[http-,5,jboss])--Execute query ReadAllQuery(referenceClass=Cell sql="SELECT ID, STATE, TSEQ, RIGHT_ID, ACELLATTRIBUTE_ID FROM EL_CELL")

2010-02-17 22:23:16,765 INFO  [STDOUT] (http- [EL Finest]: 2010-02-17 22:23:16.765--UnitOfWork(20126243)--Thread(Thread[http-,5,jboss])--Execute query ReadObjectQuery(name="left" referenceClass=Cell sql="SELECT ID, STATE, TSEQ, RIGHT_ID, ACELLATTRIBUTE_ID FROM EL_CELL WHERE (RIGHT_ID = ?)")
2010-02-17 22:23:16,765 INFO  [STDOUT] (http- [EL Finest]: 2010-02-17 22:23:16.765--ServerSession(7054061)--Thread(Thread[http-,5,jboss])--reconnecting to external connection pool
2010-02-17 22:23:16,765 INFO  [STDOUT] (http- [EL Fine]: 2010-02-17 22:23:16.765--ServerSession(7054061)--Connection(4514793)--Thread(Thread[http-,5,jboss])--SELECT ID, STATE, TSEQ, RIGHT_ID, ACELLATTRIBUTE_ID FROM EL_CELL WHERE (RIGHT_ID = ?)
	bind => [1]
2010-02-17 22:23:16,765 INFO  [STDOUT] (http- [EL Finer]: 2010-02-17 22:23:16.765--UnitOfWork(20126243)--Thread(Thread[http-,5,jboss])--TX beforeCompletion callback, status=STATUS_ACTIVE
2010-02-17 22:23:16,765 INFO  [STDOUT] (http- [EL Example]: enterprise: Object: id: 1 state: null left: null right: null parent: HashSet@13182744 references: HashSet@13182744)

Browser Output

Eclipselink example jpa jboss web jpql action cap.jpg


  • 20090329 - last edit for JBoss 4.2
  • 20091115 - Updating site for JBoss 5.1.0
    • Notes (to be integrated into main page)
      • Disable JBossPlatform public JPAClassLoaderHolder getNewTempClassLoader(PersistenceUnitInfo puInfo) workaround
      • Increase server start timeout past 50 sec (60+) for a slower T4200 2.2GHz Core2 Win7-64 machine
  • 20090217 - Update for JBoss 6.0.0M1


Back to the top