You are on page 1of 617

WildFly 8

Developer Guide

Exported from JBoss Community Documentation Editor at 2016-04-14 09:38:41 EDT
Copyright 2016 JBoss Community contributors.

JBoss Community Documentation

Page 1 of 617

WildFly 8

Table of Contents
1 WildFly 8 Developer Guide ___________________________________________________________ 22
1.1 Target Audience _______________________________________________________________ 22
1.2 Prerequisites __________________________________________________________________ 22
2 Class loading in WildFly 8 ____________________________________________________________ 23
2.1 Deployment Module Names ______________________________________________________ 23
2.2 Automatic Dependencies ________________________________________________________ 23
2.3 Class Loading Precedence _______________________________________________________ 24
2.4 WAR Class Loading ____________________________________________________________ 24
2.5 EAR Class Loading _____________________________________________________________ 24
2.5.1 Class Path Entries ________________________________________________________ 27
2.6 Global Modules ________________________________________________________________ 27
2.7 JBoss Deployment Structure File __________________________________________________ 27
2.8 Accessing JDK classes __________________________________________________________ 29
3 Implicit module dependencies for deployments ____________________________________________ 30
3.1 What's an implicit module dependency? _____________________________________________ 30
3.2 How and when is an implicit module dependency added? _______________________________ 31
3.3 Which are the implicit module dependencies? ________________________________________ 31
4 How do I migrate my application from JBoss AS 5 or AS 6 to WildFly 8? ________________________ 34
4.1 Migration Overview _____________________________________________________________ 34
4.2 Update Application Dependencies Due to Class Loading Changes ________________________ 34
4.2.1 Modular class loading overview ______________________________________________ 35
4.2.2 Understand module dependencies ___________________________________________ 36
4.2.3 Create or modify files that control class loading in WildFly _________________________ 36
4.2.4 Change ResourceBundle location ____________________________________________ 40
4.2.5 Where to Find Additional Information __________________________________________ 40
4.3 Update the DataSource Configuration ______________________________________________ 40
4.3.1 Overview _______________________________________________________________ 41
4.3.2 Define the datasource _____________________________________________________ 41
4.3.3 Install the JDBC driver _____________________________________________________ 42
4.3.4 Configure the datasource for Hibernate or JPA __________________________________ 44
4.3.5 Where to Find Additional Information __________________________________________ 45
4.4 Update the Resource Adapter Configuration _________________________________________ 45
4.4.1 Overview _______________________________________________________________ 45
4.4.2 Define the resource adapter _________________________________________________ 46
4.5 Update application JNDI namespace names _________________________________________ 46
4.5.1 Overview _______________________________________________________________ 47
4.5.2 Review the JNDI Namespace Rules __________________________________________ 47
4.5.3 Modify your application code to follow the new JNDI namespace rules _______________ 48
4.5.4 Examples of JNDI mappings in previous releases and how they might look now ________ 49
4.5.5 Where to Find Additional Information __________________________________________ 49
4.6 Migrate remote EJB clients to the WildFly 8 client API __________________________________ 49
4.7 Migrate EAP 5 Deployed Applications That Make Remote Invocations to WildFly 8 ___________ 49

JBoss Community Documentation

Page 2 of 617

WildFly 8
4.7.1 Overview _______________________________________________________________ 50
4.7.2 Update the Client Code ____________________________________________________ 50
4.8 Modify logging dependencies _____________________________________________________ 53
4.8.1 Overview _______________________________________________________________ 53
4.8.2 Update your application code for third-party logging frameworks ____________________ 53
4.8.3 Modify code to use the New JBoss Logging Framework ___________________________ 53
4.8.4 Where to Find Additional Information __________________________________________ 53
4.9 Configure changes for applications that use Hibernate and JPA __________________________ 53
4.9.1 Overview _______________________________________________________________ 54
4.9.2 Update your Hibernate 3 application to use Hibernate 4 ___________________________ 54
4.9.3 Changes in JPA container managed behaviour __________________________________ 57
4.9.4 Infinispan as Second Level Cache ____________________________________________ 57
4.9.5 Migrate to Hibernate 4 Validator _____________________________________________ 58
4.10 Changes you need to make for Security _____________________________________________ 61
4.10.1 Configure Security for Basic Authentication _____________________________________ 61
4.10.2 Modify security domain names _______________________________________________ 61
4.11 Configure JAX-RS / Resteasy changes _____________________________________________ 61
4.12 Configure LDAP security realm changes ____________________________________________ 63
4.13 Migrate from JBoss Messaging to HornetQ __________________________________________ 64
4.13.1 Before you start __________________________________________________________ 64
4.13.2 Transfer configurations ____________________________________________________ 65
4.13.3 Modify application code ____________________________________________________ 65
4.13.4 Migrate existing messages __________________________________________________ 65
4.14 Changes you need to make for Clustering ___________________________________________ 65
4.14.1 Starting WildFly 8 with clustering enabled ______________________________________ 66
4.14.2 Specifying the bind address _________________________________________________ 67
4.14.3 Configure jvmRoute to support mod_jk and mod_proxy ___________________________ 67
4.14.4 Specifying multicast address/port ____________________________________________ 68
4.14.5 Using an alternate protocol stack _____________________________________________ 69
4.15 HA Singleton Deployment ________________________________________________________ 69
4.16 Additional changes you may need to make ___________________________________________ 69
4.16.1 Change Maven plugin name ________________________________________________ 69
4.16.2 Update Applications That Use Service-style Deployments _________________________ 69
4.17 Debug and Resolve Migration Issues _______________________________________________ 69
4.17.1 Debug and resolve ClassNotFoundExceptions and NoCLassDefFoundErrors __________ 70
4.17.2 Debug and resolve ClassCastExceptions ______________________________________ 72
4.17.3 Debug and resolve class loading issues _______________________________________ 73
4.17.4 Debug and resolve NoSuchMethodExceptions __________________________________ 73
4.17.5 Debug and resolve DuplicateServiceExceptions _________________________________ 74
4.17.6 Debug and resolve JBoss Seam debug page errors. _____________________________ 74
4.18 EJB 2.x Support _______________________________________________________________ 75
4.18.1 Modify the Code to Use the New JNDI Namespace Rules _________________________ 75
4.18.2 Replace JBoss AOP Interceptors _____________________________________________ 75
4.18.3 Modify the jboss-web.xml File Descriptor _______________________________________ 75
4.18.4 Replace the jboss.xml deployment descriptor file ________________________________ 75
4.18.5 Start the Server with the Full Profiles __________________________________________ 75

JBoss Community Documentation

Page 3 of 617

WildFly 8
4.19 Migration required for other components ____________________________________________ 76
4.20 How to migrate Seam 2 archives to WildFly 8 _________________________________________ 76
4.20.1 Overview _______________________________________________________________ 76
4.20.2 Update the datasource configuration __________________________________________ 76
4.20.3 Add any required dependencies _____________________________________________ 77
4.20.4 Copy dependent archives from outside frameworks or other locations ________________ 77
4.20.5 Seam 2 JPA example deployment on WildFly ___________________________________ 78
4.20.6 How to debug and resolve Seam 2 JNDI errors __________________________________ 79
4.21 Running Seam 3 archives on WildFly _______________________________________________ 79
4.22 Migrating Spring applications _____________________________________________________ 80
4.23 Tools That Can Assist with Migration _______________________________________________ 80
4.23.1 Use Tattletale to find application dependencies __________________________________ 80
4.23.2 IronJacamar Datasource and Resource Adapter Migration Tool _____________________ 81
5 EJB invocations from a remote standalone client using JNDI _________________________________ 88
5.1 Deploying your EJBs on the server side: ____________________________________________ 88
5.2 Writing a remote client application for accessing and invoking the EJBs deployed on the server _ 90
5.3 Setting up EJB client context properties _____________________________________________ 96
5.4 Using a different file for setting up EJB client context ___________________________________ 99
5.5 Setting up the client classpath with the jars that are required to run the client application _______ 99
5.6 Summary ____________________________________________________________________ 100
6 EJB invocations from a remote server _________________________________________________ 101
6.1 Application packaging __________________________________________________________ 101
6.2 Beans ______________________________________________________________________ 102
6.3 Security _____________________________________________________________________ 102
6.4 Configuring a user on the "Destination Server" _______________________________________ 103
6.5 Start the "Destination Server" ____________________________________________________ 104
6.6 Deploying the application _______________________________________________________ 104
6.7 Configuring the "Client Server" to point to the EJB remoting connector on the "Destination Server" _
104
6.8 Start the "Client Server" ________________________________________________________ 105
6.9 Create a security realm on the client server _________________________________________ 105
6.10 Create a outbound-socket-binding on the "Client Server" _______________________________ 107
6.11 Create a "remote-outbound-connection" which uses this newly created "outbound-socket-binding" _
107
6.12 Packaging the client application on the "Client Server" _________________________________ 109
6.13 Contents on jboss-ejb-client.xml __________________________________________________ 110
6.14 Deploy the client application _____________________________________________________ 110
6.15 Client code invoking the bean ____________________________________________________ 111
7 Remote EJB invocations via JNDI - Which approach to use? ________________________________ 112
8 JBoss EJB 3 reference guide ________________________________________________________ 113
8.1 Resource Adapter for Message Driven Beans _______________________________________ 113
8.1.1 Specification of Resource Adapter using Metadata Annotations ____________________ 113
8.2 Run-as Principal ______________________________________________________________ 114
8.2.1 Specification of Run-as Principal using Metadata Annotations _____________________ 114
8.3 Security Domain ______________________________________________________________ 114
8.3.1 Specification of Security Domain using Metadata Annotations _____________________ 114

JBoss Community Documentation

Page 4 of 617

WildFly 8
8.4 Transaction Timeout ___________________________________________________________ 114
8.4.1 Specification of Transaction Timeout with Metadata Annotations ___________________ 115
8.4.2 Specification of Transaction Timeout in the Deployment Descriptor _________________ 116
8.5 Timer service _________________________________________________________________ 116
8.5.1 Single event timer _______________________________________________________ 117
8.5.2 Recurring timer __________________________________________________________ 117
8.5.3 Calendar timer __________________________________________________________ 118
9 JPA reference guide _______________________________________________________________ 119
9.1 Introduction __________________________________________________________________ 120
9.2 Update your Persistence.xml for Hibernate 4.3.0 _____________________________________ 120
9.3 Entity manager _______________________________________________________________ 120
9.4 Application-managed entity manager ______________________________________________ 121
9.5 Container-managed entity manager _______________________________________________ 121
9.6 Persistence Context ___________________________________________________________ 121
9.7 Transaction-scoped Persistence Context ___________________________________________ 122
9.8 Extended Persistence Context ___________________________________________________ 122
9.8.1 Extended Persistence Context Inheritance ____________________________________ 122
9.9 Entities ______________________________________________________________________ 124
9.10 Deployment __________________________________________________________________ 125
9.11 Troubleshooting _______________________________________________________________ 125
9.12 Background on the Jipijapa project ________________________________________________ 127
9.13 Packaging persistence providers with your application and which Jipijapa artifacts to include __ 128
9.14 Using the Hibernate 4.3.x JPA persistence provider ___________________________________ 128
9.15 Using the Infinispan second level cache ____________________________________________ 129
9.16 Replacing the current Hibernate 4.3.x jars with a newer version _________________________ 130
9.17 Packaging the Hibernate 3.5 or greater 3.x JPA persistence provider with your application ____ 130
9.18 Sharing the Hibernate 3.5 or greater JPA persistence provider between multiple applications __ 130
9.19 Using OpenJPA _______________________________________________________________ 132
9.20 Using EclipseLink _____________________________________________________________ 132
9.21 Using DataNucleus ____________________________________________________________ 134
9.22 Using Hibernate OGM __________________________________________________________ 134
9.23 Native Hibernate use ___________________________________________________________ 136
9.24 Injection of Hibernate Session and SessionFactoryInjection of Hibernate Session and
SessionFactory ____________________________________________________________________ 136
9.25 Hibernate properties ___________________________________________________________ 136
9.26 Persistence unit properties ______________________________________________________ 137
9.27 Determine the persistence provider module _________________________________________ 140
9.28 Binding EntityManagerFactory/EntityManager to JNDI _________________________________ 141
9.29 Community __________________________________________________________________ 142
9.29.1 People who have contributed to the WildFly JPA layer: ___________________________ 142
10 OSGi developer guide ______________________________________________________________ 143
11 JNDI reference guide ______________________________________________________________ 144
11.1 Overview ____________________________________________________________________ 144
11.2 Local JNDI ___________________________________________________________________ 144
11.2.1 Binding entries to JNDI ___________________________________________________ 145
11.2.2 Retrieving entries from JNDI _______________________________________________ 147

JBoss Community Documentation

Page 5 of 617

WildFly 8
11.3 Remote JNDI _________________________________________________________________ 149
11.3.1 remote: ________________________________________________________________ 149
11.3.2 ejb: ___________________________________________________________________ 150
12 Spring applications development and migration guide _____________________________________ 151
12.1 Dependencies and Modularity ____________________________________________________ 151
12.2 Persistence usage guide ________________________________________________________ 151
12.3 Native Spring/Hibernate applications ______________________________________________ 151
12.4 JPA-based applications _________________________________________________________ 151
12.4.1 Using server-deployed persistence units ______________________________________ 152
12.4.2 Using Spring-managed persistence units _____________________________________ 153
12.4.3 Managing dependencies __________________________________________________ 154
13 All WildFly 8 documentation _________________________________________________________ 155
14 All JBoss AS 7 documentation _______________________________________________________ 156
15 Application Client Reference _________________________________________________________ 157
15.1 Getting Started _______________________________________________________________ 157
15.2 Connecting to more than one host ________________________________________________ 157
15.3 Example ____________________________________________________________________ 158
16 CDI Reference ____________________________________________________________________ 159
16.1 Using CDI Beans from outside the deployment ______________________________________ 159
16.2 Suppressing implicit bean archives ________________________________________________ 160
16.2.1 Per-deployment configuration ______________________________________________ 160
16.2.2 Global configuration ______________________________________________________ 160
16.3 Non-portable mode ____________________________________________________________ 161
16.3.1 Per-deployment configuration ______________________________________________ 161
16.3.2 Global configuration ______________________________________________________ 161
17 Class Loading in WildFly ____________________________________________________________ 162
17.1 Deployment Module Names _____________________________________________________ 162
17.2 Automatic Dependencies _______________________________________________________ 162
17.3 Class Loading Precedence ______________________________________________________ 163
17.4 WAR Class Loading ___________________________________________________________ 163
17.5 EAR Class Loading ____________________________________________________________ 163
17.5.1 Class Path Entries _______________________________________________________ 166
17.6 Global Modules _______________________________________________________________ 166
17.7 JBoss Deployment Structure File _________________________________________________ 166
17.8 Accessing JDK classes _________________________________________________________ 168
18 Deployment Descriptors used In WildFly _______________________________________________ 169
19 Development Guidelines and Recommended Practices ____________________________________ 173
20 EE Concurrency Utilities ____________________________________________________________ 174
20.1 Overview ____________________________________________________________________ 174
20.2 Context Service _______________________________________________________________ 175
20.3 Managed Thread Factory _______________________________________________________ 175
20.4 Managed Executor Service ______________________________________________________ 177
20.5 Managed Scheduled Executor Service _____________________________________________ 177
21 EJB 3 Reference Guide _____________________________________________________________ 180
21.1 Resource Adapter for Message Driven Beans _______________________________________ 180
21.1.1 Specification of Resource Adapter using Metadata Annotations ____________________ 180

JBoss Community Documentation

Page 6 of 617

WildFly 8
21.2 Run-as Principal ______________________________________________________________ 181
21.2.1 Specification of Run-as Principal using Metadata Annotations _____________________ 181
21.3 Security Domain ______________________________________________________________ 181
21.3.1 Specification of Security Domain using Metadata Annotations _____________________ 181
21.4 Transaction Timeout ___________________________________________________________ 181
21.4.1 Specification of Transaction Timeout with Metadata Annotations ___________________ 182
21.4.2 Specification of Transaction Timeout in the Deployment Descriptor _________________ 183
21.5 Timer service _________________________________________________________________ 183
21.5.1 Single event timer _______________________________________________________ 184
21.5.2 Recurring timer __________________________________________________________ 184
21.5.3 Calendar timer __________________________________________________________ 185
21.6 Container interceptors __________________________________________________________ 185
21.6.1 Overview ______________________________________________________________ 185
21.6.2 Typical EJB invocation call path on the server __________________________________ 186
21.6.3 Feature request for WildFly ________________________________________________ 186
21.6.4 Configuring container interceptors ___________________________________________ 186
21.6.5 Container interceptor positioning in the interceptor chain _________________________ 189
21.6.6 Semantic difference between container interceptor(s) and Java EE interceptor(s) API __ 189
21.6.7 Testcase _______________________________________________________________ 189
21.7 EJB3 subsystem configuration guide ______________________________________________ 189
21.7.1 <session-bean> _________________________________________________________ 192
21.7.2 <mdb> ________________________________________________________________ 192
21.7.3 <entity-bean> ___________________________________________________________ 193
21.7.4 ______________________________________________________________________ 193
21.7.5 <pools> _______________________________________________________________ 193
21.7.6 <caches> ______________________________________________________________ 193
21.7.7 <passivation-stores> _____________________________________________________ 193
21.7.8 <async> _______________________________________________________________ 193
21.7.9 <timer-service> _________________________________________________________ 193
21.7.10<remote> ______________________________________________________________ 194
21.7.11<thread-pools> _________________________________________________________ 194
21.7.12<iiop> _________________________________________________________________ 194
21.7.13<in-vm-remote-interface-invocation> _________________________________________ 195
21.8 EJB IIOP Guide _______________________________________________________________ 196
21.8.1 Enabling IIOP ___________________________________________________________ 196
21.8.2 Enabling JTS ___________________________________________________________ 196
21.8.3 Dynamic Stub's _________________________________________________________ 196
21.8.4 Configuring EJB IIOP settings via jboss-ejb3.xml _______________________________ 196
21.9 jboss-ejb3.xml Reference _______________________________________________________ 196
21.9.1 Example File ___________________________________________________________ 196
21.10JBoss remoting transaction propagation ___________________________________________ 199
21.10.1Propagation example ____________________________________________________ 199
21.10.2What happens when something goes wrong? _________________________________ 203
21.10.3Responisibities of an administrator __________________________________________ 204
21.10.4Cyclic transaction invocation, branch merging _________________________________ 204
21.11Securing EJBs _______________________________________________________________ 204

JBoss Community Documentation

Page 7 of 617

WildFly 8
Securing EJBs ______________________________________________________________ 204
21.11.1Overview ______________________________________________________________ 205
21.11.2Security Domain ________________________________________________________ 205
21.11.3Absence of security domain configuration but presence of other security metadata ____ 207
21.11.4Access to methods without explicit security metadata, on a secured bean ___________ 207
22 EJB invocations from a remote client using JNDI _________________________________________ 209
22.1 Deploying your EJBs on the server side: ___________________________________________ 209
22.2 Writing a remote client application for accessing and invoking the EJBs deployed on the server 211
22.3 Setting up EJB client context properties ____________________________________________ 217
22.4 Using a different file for setting up EJB client context __________________________________ 220
22.5 Setting up the client classpath with the jars that are required to run the client application ______ 220
22.6 Summary ____________________________________________________________________ 221
23 EJB invocations from a remote server instance __________________________________________ 222
23.1 Application packaging __________________________________________________________ 222
23.2 Beans ______________________________________________________________________ 223
23.3 Security _____________________________________________________________________ 223
23.4 Configuring a user on the "Destination Server" _______________________________________ 224
23.5 Start the "Destination Server" ____________________________________________________ 225
23.6 Deploying the application _______________________________________________________ 225
23.7 Configuring the "Client Server" to point to the EJB remoting connector on the "Destination Server" _
225
23.8 Start the "Client Server" ________________________________________________________ 226
23.9 Create a security realm on the client server _________________________________________ 226
23.10Create a outbound-socket-binding on the "Client Server" ______________________________ 228
23.11Create a "remote-outbound-connection" which uses this newly created "outbound-socket-binding" _
228
23.12Packaging the client application on the "Client Server" ________________________________ 230
23.13Contents on jboss-ejb-client.xml _________________________________________________ 231
23.14Deploy the client application _____________________________________________________ 231
23.15Client code invoking the bean ___________________________________________________ 232
24 Example Applications - Migrated to WildFly _____________________________________________ 233
24.1 Example Applications Migrated from Previous Releases _______________________________ 233
24.1.1 Seam 2 JPA example _____________________________________________________ 233
24.1.2 Seam 2 DVD Store example _______________________________________________ 233
24.1.3 Seam 2 Booking example _________________________________________________ 233
24.1.4 Seam 2 Booking - step-by-step migration of binaries ____________________________ 233
24.1.5 jBPM-Console application _________________________________________________ 233
24.1.6 Order application used for performance testing _________________________________ 234
24.1.7 Migrate example application _______________________________________________ 234
24.2 Example Applications Based on EE6 ______________________________________________ 234
24.3 Porting the Order Application from EAP 5.1 to WildFly 8 _______________________________ 234
24.3.1 Overview of the application ________________________________________________ 234
24.3.2 Summary of changes _____________________________________________________ 234
24.4 Seam 2 Booking Application - Migration of Binaries from EAP5.1 to WildFly ________________ 240
24.4.1 Step 1: Build and deploy the EAP5.1 version of the Seam Booking application ________ 241
24.4.2 Step 2: Debug and resolve deployment errors and exceptions _____________________ 241
24.4.3 Step 3: Debug and resolve runtime errors and exceptions ________________________ 256

JBoss Community Documentation

Page 8 of 617

WildFly 8
24.4.4 Step 4: Access the application ______________________________________________ 260
24.4.5 Summary of Changes ____________________________________________________ 260
25 How do I migrate my application from AS5 or AS6 to WildFly _______________________________ 262
25.1 Migration Overview ____________________________________________________________ 262
25.2 Update Application Dependencies Due to Class Loading Changes _______________________ 262
25.2.1 Modular class loading overview _____________________________________________ 263
25.2.2 Understand module dependencies __________________________________________ 264
25.2.3 Create or modify files that control class loading in WildFly ________________________ 264
25.2.4 Change ResourceBundle location ___________________________________________ 268
25.2.5 Where to Find Additional Information _________________________________________ 268
25.3 Update the DataSource Configuration _____________________________________________ 268
25.3.1 Overview ______________________________________________________________ 269
25.3.2 Define the datasource ____________________________________________________ 269
25.3.3 Install the JDBC driver ____________________________________________________ 270
25.3.4 Configure the datasource for Hibernate or JPA _________________________________ 272
25.3.5 Where to Find Additional Information _________________________________________ 273
25.4 Update the Resource Adapter Configuration ________________________________________ 273
25.4.1 Overview ______________________________________________________________ 273
25.4.2 Define the resource adapter ________________________________________________ 274
25.5 Update application JNDI namespace names ________________________________________ 274
25.5.1 Overview ______________________________________________________________ 275
25.5.2 Review the JNDI Namespace Rules _________________________________________ 275
25.5.3 Modify your application code to follow the new JNDI namespace rules ______________ 276
25.5.4 Examples of JNDI mappings in previous releases and how they might look now _______ 277
25.5.5 Where to Find Additional Information _________________________________________ 277
25.6 Migrate remote EJB clients to the WildFly 8 client API _________________________________ 277
25.7 Migrate EAP 5 Deployed Applications That Make Remote Invocations to WildFly 8 __________ 277
25.7.1 Overview ______________________________________________________________ 278
25.7.2 Update the Client Code ___________________________________________________ 278
25.8 Modify logging dependencies ____________________________________________________ 281
25.8.1 Overview ______________________________________________________________ 281
25.8.2 Update your application code for third-party logging frameworks ___________________ 281
25.8.3 Modify code to use the New JBoss Logging Framework __________________________ 281
25.8.4 Where to Find Additional Information _________________________________________ 281
25.9 Configure changes for applications that use Hibernate and JPA _________________________ 281
25.9.1 Overview ______________________________________________________________ 282
25.9.2 Update your Hibernate 3 application to use Hibernate 4 __________________________ 282
25.9.3 Changes in JPA container managed behaviour _________________________________ 285
25.9.4 Infinispan as Second Level Cache ___________________________________________ 285
25.9.5 Migrate to Hibernate 4 Validator ____________________________________________ 286
25.10Changes you need to make for Security ___________________________________________ 289
25.10.1Configure Security for Basic Authentication ___________________________________ 289
25.10.2Modify security domain names _____________________________________________ 289
25.11Configure JAX-RS / Resteasy changes ____________________________________________ 289
25.12Configure LDAP security realm changes ___________________________________________ 291
25.13Migrate from JBoss Messaging to HornetQ _________________________________________ 292

JBoss Community Documentation

Page 9 of 617

WildFly 8
Migrate from JBoss Messaging to HornetQ ________________________________________ 292
25.13.1Before you start _________________________________________________________ 292
25.13.2Transfer configurations ___________________________________________________ 293
25.13.3Modify application code ___________________________________________________ 293
25.13.4Migrate existing messages ________________________________________________ 293
25.14Changes you need to make for Clustering __________________________________________ 293
25.14.1Starting WildFly 8 with clustering enabled ____________________________________ 294
25.14.2Specifying the bind address _______________________________________________ 295
25.14.3Configure jvmRoute to support mod_jk and mod_proxy __________________________ 295
25.14.4Specifying multicast address/port ___________________________________________ 296
25.14.5Using an alternate protocol stack ___________________________________________ 297
25.15HA Singleton Deployment ______________________________________________________ 297
25.16Additional changes you may need to make _________________________________________ 297
25.16.1Change Maven plugin name _______________________________________________ 297
25.16.2Update Applications That Use Service-style Deployments ________________________ 297
25.17Debug and Resolve Migration Issues ______________________________________________ 297
25.17.1Debug and resolve ClassNotFoundExceptions and NoCLassDefFoundErrors ________ 298
25.17.2Debug and resolve ClassCastExceptions _____________________________________ 300
25.17.3Debug and resolve class loading issues ______________________________________ 301
25.17.4Debug and resolve NoSuchMethodExceptions _________________________________ 301
25.17.5Debug and resolve DuplicateServiceExceptions ________________________________ 302
25.17.6Debug and resolve JBoss Seam debug page errors. ____________________________ 302
25.18EJB 2.x Support ______________________________________________________________ 303
25.18.1Modify the Code to Use the New JNDI Namespace Rules ________________________ 303
25.18.2Replace JBoss AOP Interceptors ___________________________________________ 303
25.18.3Modify the jboss-web.xml File Descriptor _____________________________________ 303
25.18.4Replace the jboss.xml deployment descriptor file _______________________________ 303
25.18.5Start the Server with the Full Profiles ________________________________________ 303
25.19Migration required for other components ___________________________________________ 304
25.20How to migrate Seam 2 archives to WildFly 8 _______________________________________ 304
25.20.1Overview ______________________________________________________________ 304
25.20.2Update the datasource configuration ________________________________________ 304
25.20.3Add any required dependencies ____________________________________________ 305
25.20.4Copy dependent archives from outside frameworks or other locations ______________ 305
25.20.5Seam 2 JPA example deployment on WildFly _________________________________ 306
25.20.6How to debug and resolve Seam 2 JNDI errors ________________________________ 307
25.21Running Seam 3 archives on WildFly _____________________________________________ 307
25.22Migrating Spring applications ____________________________________________________ 308
25.23Tools That Can Assist with Migration ______________________________________________ 308
25.23.1Use Tattletale to find application dependencies ________________________________ 308
25.23.2IronJacamar Datasource and Resource Adapter Migration Tool ___________________ 309
26 How do I migrate my application to WildFly from other application servers _____________________ 316
26.1 Choose from the list below: ______________________________________________________ 316
26.2 How do I migrate my application from WebLogic to WildFly _____________________________ 316
26.2.1 Introduction ____________________________________________________________ 318
26.2.2 Prepare for Migration _____________________________________________________ 326
26.2.3 Server Configuration and Deployment Descriptor Files ___________________________ 328

JBoss Community Documentation

Page 10 of 617

WildFly 8
26.2.4 Security _______________________________________________________________ 337
26.2.5 Understand Differences Between WebLogic and JBoss Implementations ____________ 337
26.2.6 Replace WebLogic Proprietary Features ______________________________________ 349
26.2.7 Evaluate the WebLogic Application __________________________________________ 357
26.2.8 Configure the Environment for the Migrated Applications _________________________ 360
26.2.9 Migrate the Application ____________________________________________________ 360
26.2.10Tools and Tips __________________________________________________________ 360
26.3 How do I migrate my application from WebSphere to WildFly ___________________________ 360
26.3.1 Introduction ____________________________________________________________ 363
26.3.2 Prepare for Migration _____________________________________________________ 371
26.3.3 Server Configuration and Deployment Descriptor Files ___________________________ 373
26.3.4 Security _______________________________________________________________ 382
26.3.5 Understand Differences Between WebLogic and JBoss Implementations ____________ 382
26.3.6 Replace WebLogic Proprietary Features ______________________________________ 394
26.3.7 Evaluate the WebLogic Application __________________________________________ 402
26.3.8 Configure the Environment for the Migrated Applications _________________________ 405
26.3.9 Migrate the Application ____________________________________________________ 405
26.3.10Tools and Tips __________________________________________________________ 405
27 Implicit module dependencies for deployments ___________________________________________ 406
27.1 What's an implicit module dependency? ____________________________________________ 406
27.2 How and when is an implicit module dependency added? ______________________________ 407
27.3 Which are the implicit module dependencies? _______________________________________ 407
28 JAX-RS Reference Guide ___________________________________________________________ 410
28.1 Subclassing javax.ws.rs.core.Application and using @ApplicationPath ____________________ 410
28.2 Subclassing javax.ws.rs.core.Application and using web.xml ____________________________ 411
28.3 Using web.xml ________________________________________________________________ 411
29 JNDI Reference ___________________________________________________________________ 412
29.1 Overview ____________________________________________________________________ 412
29.2 Local JNDI ___________________________________________________________________ 412
29.2.1 Binding entries to JNDI ___________________________________________________ 413
29.2.2 Retrieving entries from JNDI _______________________________________________ 415
29.3 Remote JNDI _________________________________________________________________ 417
29.3.1 remote: ________________________________________________________________ 417
29.3.2 ejb: ___________________________________________________________________ 418
29.4 Local JNDI ___________________________________________________________________ 418
29.4.1 Binding entries to JNDI ___________________________________________________ 419
29.4.2 Retrieving entries from JNDI _______________________________________________ 421
29.5 Remote JNDI Reference ________________________________________________________ 423
29.5.1 Remote JNDI ___________________________________________________________ 423
29.5.2 Remote JNDI Access _____________________________________________________ 424
30 JPA Reference Guide ______________________________________________________________ 427
30.1 Introduction __________________________________________________________________ 428
30.2 Update your Persistence.xml for Hibernate 4.3.0 _____________________________________ 428
30.3 Entity manager _______________________________________________________________ 428
30.4 Application-managed entity manager ______________________________________________ 429
30.5 Container-managed entity manager _______________________________________________ 429

JBoss Community Documentation

Page 11 of 617

WildFly 8
30.6 Persistence Context ___________________________________________________________ 429
30.7 Transaction-scoped Persistence Context ___________________________________________ 430
30.8 Extended Persistence Context ___________________________________________________ 430
30.8.1 Extended Persistence Context Inheritance ____________________________________ 430
30.9 Entities ______________________________________________________________________ 432
30.10Deployment _________________________________________________________________ 433
30.11Troubleshooting ______________________________________________________________ 433
30.12Background on the Jipijapa project _______________________________________________ 435
30.13Packaging persistence providers with your application and which Jipijapa artifacts to include __ 436
30.14Using the Hibernate 4.3.x JPA persistence provider __________________________________ 436
30.15Using the Infinispan second level cache ___________________________________________ 437
30.16Replacing the current Hibernate 4.3.x jars with a newer version _________________________ 438
30.17Packaging the Hibernate 3.5 or greater 3.x JPA persistence provider with your application ____ 438
30.18Sharing the Hibernate 3.5 or greater JPA persistence provider between multiple applications __ 438
30.19Using OpenJPA ______________________________________________________________ 440
30.20Using EclipseLink _____________________________________________________________ 440
30.21Using DataNucleus ____________________________________________________________ 442
30.22Using Hibernate OGM _________________________________________________________ 442
30.23Native Hibernate use __________________________________________________________ 444
30.24Injection of Hibernate Session and SessionFactoryInjection of Hibernate Session and
SessionFactory ____________________________________________________________________ 444
30.25Hibernate properties ___________________________________________________________ 444
30.26Persistence unit properties ______________________________________________________ 445
30.27Determine the persistence provider module _________________________________________ 448
30.28Binding EntityManagerFactory/EntityManager to JNDI ________________________________ 449
30.29Community __________________________________________________________________ 450
30.29.1People who have contributed to the WildFly JPA layer: __________________________ 450
31 OSGi ___________________________________________________________________________ 451
32 Remote EJB invocations via JNDI - EJB client API or remote-naming project ___________________ 452
32.1 Purpose _____________________________________________________________________ 452
32.2 History ______________________________________________________________________ 452
32.3 Overview ____________________________________________________________________ 452
32.3.1 Client code relying on jndi.properties in classpath _______________________________ 452
32.3.2 How does remoting naming work ____________________________________________ 454
32.3.3 JNDI operations allowed using remote-naming project ___________________________ 455
32.3.4 Pre-requisites of remotely accessible JNDI objects ______________________________ 456
32.3.5 JNDI lookup strings for remote clients backed by the remote-naming project __________ 456
32.3.6 How does remote-naming project implementation transfer the JNDI objects to the clients ___
457
32.4 Summary ____________________________________________________________________ 457
32.5 Remote EJB invocations backed by the remote-naming project __________________________ 457
32.6 Why use the EJB client API approach then? _________________________________________ 460
32.6.1 Is the lookup optimization applicable for all bean types? __________________________ 462
32.6.2 Restrictions for EJB's _____________________________________________________ 463
33 Scoped EJB client contexts __________________________________________________________ 464
33.1 Overview ____________________________________________________________________ 464

JBoss Community Documentation

Page 12 of 617

1 How to close EJB client contexts? ___________________________________________ 468 33.4 JBoss Modules and WS applications ______________________________________________ 613 JBoss Community Documentation Page 13 of 617 .16WS-Discovery __________________________________________________________ 608 35.2 How to close scoped EJB client contexts? _____________________________________ 468 33.3.1 Dependencies and Modularity ____________________________________________________ 473 34.1 JAX-WS User Guide ___________________________________________________________ 477 35.3.2 Potential shortcomings of a single EJB client context __________________________________ 464 33.2 Client Side _____________________________________________________________ 497 35.6 JAXB Introductions _______________________________________________________ 520 35.15HTTP Proxy ____________________________________________________________ 605 35.1.3.4.5 JSR-181 Annotations _____________________________________________________ 491 35.2.3.4.1.4 Lifecycle management of scoped EJB client contexts _________________________________ 467 33.3 Managing dependencies __________________________________________________ 476 35 Webservices reference guide ________________________________________________________ 477 35.1.11WS-Security ___________________________________________________________ 543 35.3 Can't the scoped EJB client context be automatically closed by the EJB client API when the JNDI context is no longer in scope (i.3.4.2 JAX-WS Tools ________________________________________________________________ 492 35.13WS-Reliable Messaging __________________________________________________ 588 35.5 Schema validation of SOAP messages _______________________________________ 519 35.3 Scoped EJB client contexts ______________________________________________________ 465 33.4.2 Using Spring-managed persistence units _____________________________________ 475 34.17WS-Policy _____________________________________________________________ 608 35.3.3.3.7 Predefined client and endpoint configurations __________________________________ 520 35.4.3 Advanced User Guide __________________________________________________________ 512 35. on GC)? _______________________________________ 472 34 Spring applications development and migration guide _____________________________________ 473 34.2.3.1 Web Service Endpoints ___________________________________________________ 477 35.1.1 Logging _______________________________________________________________ 513 35.3.2.12WS-Trust and STS ______________________________________________________ 568 35.1 Server side _____________________________________________________________ 492 35.3 Address rewrite _________________________________________________________ 515 35.14SOAP over JMS ________________________________________________________ 594 35.2.3.3.3 Native Spring/Hibernate applications ______________________________________________ 473 34.9 Apache CXF integration ___________________________________________________ 529 35.4 JAX-WS Annotations _____________________________________________________ 489 35.2 Persistence usage guide ________________________________________________________ 473 34.3.3.WildFly 8 33.2 Web Service Clients ______________________________________________________ 480 35.e.3.8 Authentication __________________________________________________________ 527 35.4.1 Using server-deployed persistence units ______________________________________ 474 34.4 JPA-based applications _________________________________________________________ 473 34.3 Common API ___________________________________________________________ 486 35.4 wsprovide ______________________________________________________________ 507 35.3.3.4 Configuration through deployment descriptor __________________________________ 515 35.10WS-Addressing _________________________________________________________ 540 35.3 wsconsume ____________________________________________________________ 500 35.2 WS-* support ___________________________________________________________ 514 35.1.

4.1 Setting module dependencies ______________________________________________ 614 JBoss Community Documentation Page 14 of 617 .WildFly 8 35.

xml MANIFEST.MF file dependencies if you use Maven jboss-deployment-structure.MF file Manually edited MANIFEST files How to define MANIFEST.WildFly 8 WildFly 8 Developer Guide Target Audience Prerequisites Class loading in WildFly 8 Deployment Module Names Automatic Dependencies Class Loading Precedence WAR Class Loading EAR Class Loading Class Path Entries Global Modules JBoss Deployment Structure File Accessing JDK classes Implicit module dependencies for deployments What's an implicit module dependency? How and when is an implicit module dependency added? Which are the implicit module dependencies? How do I migrate my application from JBoss AS 5 or AS 6 to WildFly 8? Migration Overview Update Application Dependencies Due to Class Loading Changes Modular class loading overview Understand module dependencies How to Package EARs and WARs Create or modify files that control class loading in WildFly jboss-web.xml application.xml Change ResourceBundle location Where to Find Additional Information Update the DataSource Configuration Overview Define the datasource Install the JDBC driver Install the JDBC driver as a deployment Install the JDBC driver as a core module Configure the datasource for Hibernate or JPA Where to Find Additional Information Update the Resource Adapter Configuration Overview Define the resource adapter JBoss Community Documentation Page 15 of 617 .

3 applications Changes for Hibernate 3.WildFly 8 Update application JNDI namespace names Overview Review the JNDI Namespace Rules Modify your application code to follow the new JNDI namespace rules Examples of JNDI mappings in previous releases and how they might look now Migrate remote EJB clients to the WildFly 8 client API Migrate EAP 5 Deployed Applications That Make Remote Invocations to WildFly 8 Overview Update the Client Code Modify logging dependencies Overview Update your application code for third-party logging frameworks Modify code to use the New JBoss Logging Framework Where to Find Additional Information Configure changes for applications that use Hibernate and JPA Overview Update your Hibernate 3 application to use Hibernate 4 Changes for Hibernate 3.5 applications General Changes when migrating to Hibernate 4 Changes in JPA container managed behaviour Infinispan as Second Level Cache Overview Infinispan second-level cache settings Migrate to Hibernate 4 Validator Accessing the default ValidatorFactory Life cycle triggered validation Manual validation Using the new Bean Validation constraints Custom constraints Where to Find Additional Information Changes you need to make for Security Configure Security for Basic Authentication Modify security domain names Configure JAX-RS / Resteasy changes Configure LDAP security realm changes Migrate from JBoss Messaging to HornetQ Before you start Transfer configurations Modify application code Migrate existing messages JBoss Community Documentation Page 16 of 617 .

xml deployment descriptor file Start the Server with the Full Profiles Migration required for other components How to migrate Seam 2 archives to WildFly 8 Overview Update the datasource configuration Add any required dependencies Copy dependent archives from outside frameworks or other locations Seam 2 JPA example deployment on WildFly How to debug and resolve Seam 2 JNDI errors Running Seam 3 archives on WildFly Migrating Spring applications JBoss Community Documentation Page 17 of 617 .WildFly 8 Changes you need to make for Clustering Starting WildFly 8 with clustering enabled Specifying the bind address Configure jvmRoute to support mod_jk and mod_proxy Specifying multicast address/port Using an alternate protocol stack HA Singleton Deployment Additional changes you may need to make Change Maven plugin name Update Applications That Use Service-style Deployments Debug and Resolve Migration Issues Debug and resolve ClassNotFoundExceptions and NoCLassDefFoundErrors Change the application structure to find classes within the application How to find the JBoss module dependency How to find the JAR in previous install Debug and resolve ClassCastExceptions Remove any unnecessary JARs from the Application archive Exclude any conflicting dependencies using the jboss-deployment-structure.xml File Descriptor Replace the jboss. EJB 2.x Support Modify the Code to Use the New JNDI Namespace Rules Replace JBoss AOP Interceptors Modify the jboss-web.xml file Debug and resolve class loading issues Debug and resolve NoSuchMethodExceptions Debug and resolve DuplicateServiceExceptions Debug and resolve JBoss Seam debug page errors.

EJB invocations from a remote standalone client using JNDI Deploying your EJBs on the server side: Writing a remote client application for accessing and invoking the EJBs deployed on the server Setting up EJB client context properties Using a different file for setting up EJB client context Setting up the client classpath with the jars that are required to run the client application Summary EJB invocations from a remote server Application packaging Beans Security Configuring a user on the "Destination Server" Start the "Destination Server" Deploying the application Configuring the "Client Server" to point to the EJB remoting connector on the "Destination Server" Start the "Client Server" Create a security realm on the client server Create a outbound-socket-binding on the "Client Server" Create a "remote-outbound-connection" which uses this newly created "outbound-socket-binding" Packaging the client application on the "Client Server" Contents on jboss-ejb-client.xml Deploy the client application Client code invoking the bean Remote EJB invocations via JNDI . Use the IronJacamar Migration Tool to convert a resource adapter configuration file.WildFly 8 Tools That Can Assist with Migration Use Tattletale to find application dependencies Install Tattletale Create and review the Tattletale report IronJacamar Datasource and Resource Adapter Migration Tool Summary Download and install IronJacamar Use the IronJacamar Migration Tool to convert a datasource configuration file.Which approach to use? JBoss Community Documentation Page 18 of 617 .

WildFly 8 JBoss EJB 3 reference guide Resource Adapter for Message Driven Beans Specification of Resource Adapter using Metadata Annotations Run-as Principal Specification of Run-as Principal using Metadata Annotations Security Domain Specification of Security Domain using Metadata Annotations Transaction Timeout Specification of Transaction Timeout with Metadata Annotations Specification of Transaction Timeout in the Deployment Descriptor Example of trans-timeout Timer service Single event timer Recurring timer Calendar timer Programmatic calendar timer Annotated calendar timer JBoss Community Documentation Page 19 of 617 .

3.5 or greater JPA persistence provider between multiple applications Using OpenJPA Using EclipseLink Using DataNucleus Using Hibernate OGM Native Hibernate use Injection of Hibernate Session and SessionFactoryInjection of Hibernate Session and SessionFactory Hibernate properties Persistence unit properties Determine the persistence provider module Binding EntityManagerFactory/EntityManager to JNDI Community People who have contributed to the WildFly JPA layer: OSGi developer guide JBoss Community Documentation Page 20 of 617 .x jars with a newer version Packaging the Hibernate 3.xml for Hibernate 4.5 or greater 3.x JPA persistence provider Using the Infinispan second level cache Replacing the current Hibernate 4.WildFly 8 JPA reference guide Introduction Update your Persistence.x JPA persistence provider with your application Sharing the Hibernate 3.3.3.0 Entity manager Application-managed entity manager Container-managed entity manager Persistence Context Transaction-scoped Persistence Context Extended Persistence Context Extended Persistence Context Inheritance Entities Deployment Troubleshooting Background on the Jipijapa project Packaging persistence providers with your application and which Jipijapa artifacts to include Using the Hibernate 4.

WildFly 8 JNDI reference guide Overview Local JNDI Binding entries to JNDI Using a deployment descriptor Programatically Java EE Applications WildFly Modules and Extensions Naming Subsystem Configuration Retrieving entries from JNDI Resource Injection Standard Java SE JNDI API Remote JNDI remote: ejb: Spring applications development and migration guide Dependencies and Modularity Persistence usage guide Native Spring/Hibernate applications JPA-based applications Using server-deployed persistence units Using Spring-managed persistence units Placement of the persistence unit definitions Managing dependencies All WildFly 8 documentation JBoss Community Documentation Page 21 of 617 .

WildFly 8 1 WildFly 8 Developer Guide 1.1 Target Audience Java Developers 1.2 Prerequisites JBoss Community Documentation Page 22 of 617 .

2. if you are deploying a Java EE application a dependency on the Java EE API's will be added to your module automatically.war while sub deployments are named like deployment. This means that it is possible for a deployment to import classes from another deployment using the other deployments module name.myarchive. WildFly's class loading is based on modules that have to define explicit dependencies on other modules. Class loading is considerably different to previous versions of JBoss AS. For a complete list of the automatic dependencies that are added. the details of how to add an explicit module dependency are explained below. Deployments in WildFly are also modules.xml. as part of the deployment process some dependencies on modules defined by the application server are set up for you automatically.1 Deployment Module Names Module names for top level deployments follow the format deployment. 2. and do not have access to classes that are defined in jars in the application server unless an explicit dependency on those classes is defined. For instance.myear. Class loading is based on the JBoss Modules project. JBoss Community Documentation Page 23 of 617 . along with any supporting modules that weld needs to operate.war. Automatic dependencies can be excluded through the use of jboss-deployment-structure.WildFly 8 2 Class loading in WildFly 8 Since JBoss AS7.mywar. Similarly if your module contains a beans.ear. please see Implicit module dependencies for deployments. Instead of the more familiar hierarchical class loading environment.xml file a dependency on Weld will be added automatically.2 Automatic Dependencies Even though in WildFly modules are isolated by default.

2.4 WAR Class Loading The war is considered to be a single module. which gives them access to classes in EAR/lib.These are dependencies that are added to the module automatically by the container. All classes packaged in the war will be loaded with the same class loader. 4. This means that not all classes inside an ear will necessarily have access to all other classes in the ear. e.5 EAR Class Loading Ear deployments are multi-module deployments. 3.0" > <ear-subdeployments-isolated>false</ear-subdeployments-isolated> </subsystem> By default this is set to false. 2. This can include classes in an ear's lib directory. System Dependencies .WildFly 8 2.These are dependencies on other deployments in an ear deployment. Local Resource . unless explicit dependencies have been defined. User Dependencies . or classes defined in other ejb jars. and every WAR or EJB jar deployment is also a separate module.xml or through the Dependencies: manifest entry.3 Class Loading Precedence A common source of errors in Java applications is including API classes in a deployment that are also provided by the container.g. however they do not always have an automatic dependency on each other. For example. class files from WEB-INF/classes or WEB-INF/lib of a war.Class files packaged up inside the deployment itself. consider the following . This behaviour is controlled via the ear-subdeployments-isolated setting in the ee subsystem configuration: <subsystem xmlns="urn:jboss:domain:ee:1. module dependencies are added in a specific order that should prevent this situation from occurring.These are dependencies that are added through jboss-deployment-structure.ear. which allows the sub-deployments to see classes belonging to other sub-deployments within the .ear deployment: JBoss Community Documentation Page 24 of 617 . To prevent this in WildFly. Sub deployments (wars and ejb-jars) always have a dependency on the parent module. so classes defined in WEB-INF/lib are treated the same as classes in WEB-INF/classes. 2. By default the EAR/lib directory is a single module. Inter deployment dependencies . This can result in multiple versions of the class being created and the deployment failing to deploy properly. In order of highest priority to lowest priority 1. including the Java EE api's.

war.javassist export.web.apache. Similarly.jar | |--.velocity export services.war | |--.ear | |--.WildFly 8 myapp.jar and ejb2. User must manually setup the dependency with Class-Path entries.ejb1. irrespective of whether this flag is set to true or false.jar If the ear-subdeployments-isolated is set to false. The available modules can be seen under the modules directory in the application server distribution. then the classes in web.war file(s).xml below. This entry consists of a comma separated list of module names that the deployment requires. For example to add a dependency on javassist and apache velocity you can add a manifest entry as follows: Dependencies: org.org. See the section on jboss-deployment-structure. Dependencies: Manifest Entries Deployments (or more correctly modules within a deployment) may set up dependencies on other modules by adding a Dependencies: manifest entry. It is also possible to override the ear-subdeployments-isolated element value at a per deployment level.ear will have a isolated classloader and other sub-deployments within that . If the ear-subdeployments-isolated is set to true then no automatic module dependencies between the sub-deployments are set up.jar.war within a .antlr Each dependency entry may also specify some of the following parameters by adding them after the module name: JBoss Community Documentation Page 25 of 617 . or by setting up explicit module dependencies. Portability The Java EE specification says that portable applications should not rely on sub deployments having access to other sub deployments unless an explicit Class-Path entry is set in the MANIFEST.org. the .MF.ejb2. This is as per spec.ear will not be able to access classes from that . So portable applications should always use Class-Path entry to explicitly state their dependencies. The ear-subdeployments-isolated element value has no effect on the isolated classloader of the . classes from ejb1.war can access classes belonging to ejb1. i.jar can access classes from ejb2.jar (and vice-versa).e.

annotations If a jandex index has be created for the module these annotations will be merged into the deployments annotation index. this makes items from META-INF/services accessible so services in the modules can be loaded.MF entry when using maven put the following in your pom. and must be named META-INF/jandex. services By default items in META-INF of a dependency are not accessible.slf4j</Dependencies> </manifestEntries> </archive> </configuration> </plugin> </plugins> </build> If your deployment is a jar you must use the maven-jar-plugin rather than the maven-war-plugin.xml file. and adding it as an additional resource root in the module.. optional If this is specified the deployment will not fail if the module is not available. meta-inf This will make the contents of the META-INF directory available (unlike services. To generate a MANIFEST.xml.apache. Adding a dependency to all modules in an EAR Using the export parameter it is possible to add a dependency to all sub deployments in an ear. with the exception of beans. If a module is exported from a Dependencies: entry in the top level of the ear (or by a jar in the ear/lib directory) it will be available to all sub deployments as well. so any module that depends on this module will also get access to the dependency. JBoss Community Documentation Page 26 of 617 . <plugins> <plugin> <groupId>org.xml file is present this module will be scanned by Weld and any resulting beans will be available to the application.maven.plugins</groupId> <artifactId>maven-war-plugin</artifactId> <configuration> <archive> <manifestEntries> <Dependencies>org.xml <build> .idx. a better approach is to create a jar containing just this index..xml: pom. If a beans. The Jandex index can be generated using the Jandex ant task . In general this will not cause any deployment descriptors in META-INF to be processed.WildFly 8 export This means that the dependencies will be exported. which just makes META-INF/services available). Note that it is not necessary to break open the jar being indexed to add this to the modules class path.

WildFly 8

2.5.1 Class Path Entries
It is also possible to add module dependencies on other modules inside the deployment using the
Class-Path manifest entry. This can be used within an ear to set up dependencies between sub
deployments, and also to allow modules access to additional jars deployed in an ear that are not sub
deployments and are not in the EAR/lib directory. If a jar in the EAR/lib directory references a jar via
Class-Path: then this additional jar is merged into the parent ear's module, and is accessible to all sub
deployments in the ear.

2.6 Global Modules
It is also possible to set up global modules, that are accessible to all deployments. This is done by modifying
the configuration file (standalone/domain.xml).
For example, to add javassist to all deployments you can use the following XML:
standalone.xml/domain.xml
<subsystem xmlns="urn:jboss:domain:ee:1.0" >
<global-modules>
<module name="org.javassist" slot="main" />
</global-modules>
</subsystem>

Note that the slot field is optional and defaults to main.

2.7 JBoss Deployment Structure File
jboss-deployment-structure.xml is a JBoss specific deployment descriptor that can be used to
control class loading in a fine grained manner. It should be placed in the top level deployment, in META-INF
(or WEB-INF for web deployments). It can do the following:
Prevent automatic dependencies from being added
Add additional dependencies
Define additional modules
Change an EAR deployments isolated class loading behaviour
Add additional resource roots to a module
An example of a complete jboss-deployment-structure.xml file for an ear deployment is as follows:
jboss-deployment-structure.xml
<jboss-deployment-structure>
<!-- Make sub deployments isolated by default, so they cannot see each others classes without
a Class-Path entry -->

JBoss Community Documentation

Page 27 of 617

WildFly 8
<ear-subdeployments-isolated>true</ear-subdeployments-isolated>
<!-- This corresponds to the top level deployment. For a war this is the war's module, for an
ear -->
<!-- This is the top level ear module, which contains all the classes in the EAR's lib folder
-->
<deployment>
<!-- exclude-subsystem prevents a subsystems deployment unit processors running on a
deployment -->
<!-- which gives basically the same effect as removing the subsystem, but it only affects
single deployment -->
<exclude-subsystems>
<subsystem name="resteasy" />
</exclude-subsystems>
<!-- Exclusions allow you to prevent the server from automatically adding some dependencies
-->
<exclusions>
<module name="org.javassist" />
</exclusions>
<!-- This allows you to define additional dependencies, it is the same as using the
Dependencies: manifest attribute -->
<dependencies>
<module name="deployment.javassist.proxy" />
<module name="deployment.myjavassist" />
<!-- Import META-INF/services for ServiceLoader impls as well -->
<module name="myservicemodule" services="import"/>
</dependencies>
<!-- These add additional classes to the module. In this case it is the same as including
the jar in the EAR's lib directory -->
<resources>
<resource-root path="my-library.jar" />
</resources>
</deployment>
<sub-deployment name="myapp.war">
<!-- This corresponds to the module for a web deployment -->
<!-- it can use all the same tags as the <deployment> entry above -->
<dependencies>
<!-- Adds a dependency on a ejb jar. This could also be done with a Class-Path entry -->
<module name="deployment.myear.ear.myejbjar.jar" />
</dependencies>
<!-- Set's local resources to have the lowest priority -->
<!-- If the same class is both in the sub deployment and in another sub deployment that -->
<!-- is visible to the war, then the Class from the other deployment will be loaded, -->
<!-- rather than the class actually packaged in the war. -->
<!-- This can be used to resolve ClassCastExceptions if the same class is in multiple sub
deployments-->
<local-last value="true" />
</sub-deployment>
<!-- Now we are going to define two additional modules -->
<!-- This one is a different version of javassist that we have packaged -->
<module name="deployment.myjavassist" >
<resources>
<resource-root path="javassist.jar" >
<!-- We want to use the servers version of javassist.util.proxy.* so we filter it out-->
<filter>
<exclude path="javassist/util/proxy" />
</filter>
</resource-root>
</resources>

JBoss Community Documentation

Page 28 of 617

WildFly 8
</module>
<!-- This is a module that re-exports the containers version of javassist.util.proxy -->
<!-- This means that there is only one version of the Proxy classes defined
-->
<module name="deployment.javassist.proxy" >
<dependencies>
<module name="org.javassist" >
<imports>
<include path="javassist/util/proxy" />
<exclude path="/**" />
</imports>
</module>
</dependencies>
</module>
</jboss-deployment-structure>

The xsd for jboss-deployment-structure.xml is available at

https://github.com/wildfly/wildfly-core/blob/master/server/src/main/resources/schema/jboss-deployment-structure-1_
.

2.8 Accessing JDK classes
Not all JDK classes are exposed to a deployment by default. If your deployment uses JDK classes that are
not exposed you can get access to them using jboss-deployment-structure.xml with system dependencies:
Using jboss-deployment-structure.xml to access JDK classes
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.1">
<deployment>
<dependencies>
<system export="true">
<paths>
<path name="com/sun/corba/se/spi/legacy/connection"/>
</paths>
</system>
</dependencies>
</deployment>
</jboss-deployment-structure>

JBoss Community Documentation

Page 29 of 617

WildFly 8

3 Implicit module dependencies for deployments
As explained in the Class Loading in WildFly article, WildFly 8 is based on module classloading. A class
within a module B isn't visible to a class within a module A, unless module B adds a dependency on module
A. Module dependencies can be explicitly (as explained in that classloading article) or can be "implicit". This
article will explain what implicit module dependencies mean and how, when and which modules are added
as implicit dependencies.

3.1 What's an implicit module dependency?
Consider an application deployment which contains EJBs. EJBs typically need access to classes from the
javax.ejb.* package and other Java EE API packages. The jars containing these packages are already
shipped in WildFly and are available as "modules". The module which contains the javax.ejb.* classes has a
specific name and so does the module which contains all the Java EE API classes. For an application to be
able to use these classes, it has to add a dependency on the relevant modules. Forcing the application
developers to add module dependencies like these (i.e. dependencies which can be "inferred") isn't a
productive approach. Hence, whenever an application is being deployed, the deployers within the server,
which are processing this deployment "implicitly" add these module dependencies to the deployment so that
these classes are visible to the deployment at runtime. This way the application developer doesn't have to
worry about adding them explicitly. How and when these implicit dependencies are added is explained in the
next section.

JBoss Community Documentation

Page 30 of 617

WildFly 8

3.2 How and when is an implicit module dependency
added?
When a deployment is being processed by the server, it goes through a chain of "deployment processors".
Each of these processors will have a way to check if the deployment meets a certain criteria and if it does,
the deployment processor adds a implicit module dependency to that deployment. Let's take an example Consider (again) an EJB3 deployment which has the following class:
MySuperDuperBean.java
@Stateless
public class MySuperDuperBean {
...
}

As can be seen, we have a simple @Stateless EJB. When the deployment containing this class is being
processed, the EJB deployment processor will see that the deployment contains a class with the @Stateless
annotation and thus identifies this as a EJB deployment. This is just one of the several ways, various
deployment processors can identify a deployment of some specific type. The EJB deployment
processor will then add an implicit dependency on the Java EE API module, so that all the Java EE API
classes are visible to the deployment.
Some subsystems will always add a API classes, even if the trigger condition is not met. These are
listed separately below.
In the next section, we'll list down the implicit module dependencies that are added to a deployment, by
various deployers within WildFly.

3.3 Which are the implicit module dependencies?
Subsystem

Dependencies that are always

Dependencies that are added if a trigger

responsible

added

condition is met

for adding
the implicit
dependency
Core Server
javax.api
sun.jdk
org.jboss.vfs

JBoss Community Documentation

Page 31 of 617

WildFly 8

EE
Subsystem

javaee.api

EJB3
javaee.api

subsystem

JAX-RS
(Resteasy)

javax.xml.bind.api

org.jboss.resteasy.resteasy-atom-provider
org.jboss.resteasy.resteasy-cdi

subsystem

org.jboss.resteasy.resteasy-jaxrs
org.jboss.resteasy.resteasy-jaxb-provider
org.jboss.resteasy.resteasy-jackson-provider
org.jboss.resteasy.resteasy-jsapi
org.jboss.resteasy.resteasy-multipart-provider
org.jboss.resteasy.async-http-servlet-30

JCA
sub-system

javax.resource.api

javax.jms.api
javax.validation.api
org.jboss.logging
org.jboss.ironjacamar.api
org.jboss.ironjacamar.impl
org.hibernate.validator

JPA
(Hibernate)

javax.persistence.api

subsystem

javaee.api
org.jboss.as.jpa
org.hibernate

JBoss Community Documentation

Page 32 of 617

WildFly 8

Logging
Subsystem

org.jboss.logging
org.apache.commons.logging
org.apache.log4j
org.slf4j
org.jboss.logging.jul-to-slf4j-stub

SAR
org.jboss.logging

Subsystem

org.jboss.modules

Security
Subsystem

org.picketbox

Web
javaee.api

Subsystem

com.sun.jsf-impl
org.hibernate.validator
org.jboss.as.web
org.jboss.logging

Web
Services

org.jboss.ws.api

Subsystem

org.jboss.ws.spi

Weld (CDI)
Subsystem

javax.persistence.api
javaee.api
org.javassist
org.jboss.interceptor
org.jboss.as.weld
org.jboss.logging
org.jboss.weld.core
org.jboss.weld.api
org.jboss.weld.spi

JBoss Community Documentation

Page 33 of 617

WildFly 8

4 How do I migrate my application from JBoss AS
5 or AS 6 to WildFly 8?
The purpose of this guide is to document only those changes that are needed to successfully run and deploy
AS 5 applications on WildFly 8.It provides information on to resolve deployment and runtime problems and
how to prevent changes in application behaviour. This is the first step in moving to the new platform. Once
the application is successfully deployed and running on the new platform, plans can be made to upgrade
individual components to use the new functions and features of WildFly.

4.1 Migration Overview
WildFly 8 is structured differently from previous versions of JBoss AS, so you may want do a little research
before you attempt to migrate your application. Getting Started with WildFly in the Getting Started Guide has
a lot of useful information, including a table that lists the Java Enterprise Edition 6 Web Profile features that
are supported in WildFly. If your application uses features that go beyond the Web Profile specification, you
must use release WildFly 8 or later as it supports the EE6 Full Profile. You should also read Getting started
with WildFly for helpful information about how to install and run the application server.
The rest of this document describes some of the changes you might need to make to your application to
successfully deploy and run it on WildFly.

Reminder
Before making any modifications to your application, make sure to create a backup copy.

JBoss Community Documentation

Page 34 of 617

WildFly 8

4.2 Update Application Dependencies Due to Class
Loading Changes
4.2.1 Modular class loading overview
Class loading in WildFly is considerably different than in previous versions of JBoss AS. Class loading is
now based on the JBoss Modules project. Instead of the more familiar hierarchical class loading
environment, WildFly's class loading is based on modules that have to define explicit dependencies on other
modules. Deployments in WildFly are also modules, and do not have access to classes that are defined in
jars in the application server unless an explicit dependency on those classes is defined.
While WildFly modules are isolated by default, as part of the deployment process some dependencies on
modules defined by the application server are set up for you automatically. For instance, if you are deploying
a Java EE application, a dependency on the Java EE API's will be added to your module automatically.
Similarly if your module contains a beans.xml file, a dependency on Weld will be added automatically,
along with any supporting modules that weld needs to operate. For a complete list of the automatic
dependencies that are added see Implicit module dependencies for deployments.

JBoss Community Documentation

Page 35 of 617

WildFly 8

4.2.2 Understand module dependencies
The deployers within the server "implicitly" add some commonly used module dependencies, like the
javax.api and sun.jdk, to the deployment so that the classes are visible to the deployment at runtime. This
way the application developer doesn't have to worry about adding them explicitly. How and when these
implicit dependencies are added is explained in Implicit module dependencies for deployments.
For some classes, the modules must be specified explicitly in the MANIFEST.MF as Dependencies: or
"Class-Path:" entries or in the jboss-deployment-structure.xml. Otherwise you may see
ClassNotFoundExceptions, NoClassDefFoundErrors, or ClassCastExceptions. Tattletale is an excellent tool
that can help you identify module dependencies in your application. Tattletale is described later in this
document here: Use Tattletale to find application dependencies.
You may also see runtime errors and page redirects to the JBoss Seam Debug Page. Manifest entries are
explained in more detail here: Class Loading in WildFly.

How to Package EARs and WARs
When you migrate your application, you may have to change the packaging structure of your EAR or WAR
due to the class loading changes.
A WAR is a single module and all classes in the WAR are loaded with the same class loader. This means
classes packaged in the WEB-INF/lib are treated the same as classes in WEB-INF/classes.
An EAR is different in that it consists of multiple modules. The EAR/lib directory is a single module, and
every WAR or EJB jar deployment is also a separate module. Classes will not necessarily have access to
other classes in the EAR unless explicit dependencies have been defined.
For more information on EAR and WAR packaging, see "WAR Class Loading" and "EAR Class Loading" in
Class Loading in WildFly.

Reminder
If you are using maven configure defaultLibBundleDir property to lib directory:

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-ear-plugin</artifactId>
<configuration>
<!-- Tell maven to package in ear/lib for WildFly -->
<defaultLibBundleDir>lib</defaultLibBundleDir>
...

JBoss Community Documentation

Page 36 of 617

WildFly 8

4.2.3 Create or modify files that control class loading
in WildFly
jboss-web.xml
If you have defined a class-loading element, you need to remove it. The behaviour that this provokes in
EAP 5 is now the default class-loading behaviour in WildFly, so it is no longer necessary. If you do not
remove this element, you will see a ParseError and XMLStreamException in your server log:

javax.xml.stream.XMLStreamException: ParseError at [row,col]:[5,5]
Message: Unexpected element 'class-loading' encountered
at
org.jboss.metadata.parser.util.MetaDataElementParser.unexpectedElement(MetaDataElementParser.java:109)
at
org.jboss.metadata.parser.jbossweb.JBossWebMetaDataParser.parse(JBossWebMetaDataParser.java:182)
at
org.jboss.as.web.deployment.JBossWebParsingDeploymentProcessor.deploy(JBossWebParsingDeploymentProcessor.java:
... 5 more

MANIFEST.MF file
Manually edited MANIFEST files
Depending on which components your application uses, you may need to add one or more dependencies to
this file. There is more information about these dependencies in the following paragraphs.
The following is an example of MANIFEST.MF file that has been modified to contain dependencies and
classpath entries:

Manifest-Version: 1.0
Dependencies: org.jboss.logmanager
Class-Path: OrderManagerEJB.jar

If you modify the MANIFEST.MF file, make sure to include a newline character at the end of the file.

JBoss Community Documentation

Page 37 of 617

WildFly 8

How to define MANIFEST.MF file dependencies if you use Maven
If you use Maven, you may need to modify your pom.xml file to generate the dependencies for the
MANIFEST.MF file.
If your application uses EJB 3.0, you may have a section in the pom.xml file that looks like the following:

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-ejb-plugin</artifactId>
<configuration>
<ejbVersion>3.0</ejbVersion>
</configuration>
</plugin>

If the EJB 3.0 code uses org.apache.commons.log, you will need to add that dependency to the
MANIFEST.MF file. To do that, you will need to modify the plugin element in the pom.xml file as follows:

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-ejb-plugin</artifactId>
<configuration>
<ejbVersion>3.0</ejbVersion>
<archive>
<manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>
</archive>
</configuration>
</plugin>

In the above example, the src/main/resources/MANIFEST.MF file only needs to contain the
dependency entry:

Dependencies: org.apache.commons.logging

Maven will generate the complete MANIFEST.MF file:

Manifest-Version: 1.0
Dependencies: org.apache.commons.logging

JBoss Community Documentation

Page 38 of 617

init() { Context ctx = new InitialContext().war modules in the application.jar and a myApp. application.jar.jar are initialized and started before the components in myApp.jar and you need to enforce that the components in the myBeans.jar and myApp. you controlled the order of deployments within an EAR through the use of the jboss-app. If can also prevent automatic dependencies from being added. For additional information. ctx.xml file.ear.xml which allows control of the order in which the Java EE modules within an EAR are deployed. The Java EE6 spec provides the <initialize-in-order> element in the application. The myBeans. the application server has the appropriate knowledge to make sure that the EJB component is available before the servlet is started and you do not have to use the <initialize-in-order> element. you set the <initialize-in-order> element to true and specify the order of the myBeans.xml This file is a JBoss specific deployment descriptor that can be used to control class loading in a fine grained manner.xml file. define additional modules.MF. } In this case. To do this. the server is not able to determine that that EJB component is in the myBeans. if that servlet uses legacy JNDI lookup style remote references like the following to access the bean.war.war within a myApp. In this case. see jboss-deployment-structure. you may need to specify module order.war @EJB injects a bean from myBeans. If your application uses dependency injections and resource-refs to refer to components in external modules. The following is an example that uses the <initialize-in-order> element to control deployment order.war. Assume you have an application that contains a myBeans. and add additional resource roots to a module. JBoss Community Documentation Page 39 of 617 . change an EAR deployment's isolated class loading behaviour. A servlet in the myApp. In most cases you do not need to specify deployment order. Like the MANIFEST. However.xml In previous versions of JBoss AS.WildFly 8 jboss-deployment-structure.jar is deployed before the myApp.lookup("TheBeanInMyBeansModule"). this file can be used to add dependencies.xml. in most cases the <initialize-in-order> element is not required because the application server is able to implicitly determine the correct and optimal way of ordering the components. This is no longer the case.

the JBOSS_HOME/server/<servername>/conf/ was available in the classpath. For information about deployment module dependencies. Hence the properties files in that location were available in the classpath of the application. JBoss Community Documentation Page 40 of 617 . to get those properties available in the classpath.2.com/xml/ns/javaee" xmlns:xsi="http://www. package them within your application. then package them at the root of some .org/2001/XMLSchema-instance" version="6" xsi:schemaLocation="http://java. If you want those properties accessible to all components in a . if you are deploying a .war</web-uri> <context-root>myApp</context-root> </web> </module> </application> The schema for the application.sun.sun. 4.jar</ejb> </module> <module> <web> <web-uri>myApp.2. It is preferable to define proper dependencies using dependency injections or resource-refs since it allows the container more flexibility in optimizing deployments.com/xml/ns/javaee/application_6.com/xml/ns/javaee http://java.com/xml/ns/javaee/application_6.5 Where to Find Additional Information For more information about the class loading changes in WildFly 8. see Class Loading in WildFly 8.sun.xml file can be found here at http://java. You should be aware that setting <initialize-in-order> to true slows down deployment. see the Module Compatible Classloading Guide.xsd.w3.4 Change ResourceBundle location In previous versions of AS. see Deployment Module Dependencies.WildFly 8 <application xmlns="http://java.sun. In WildFly 8. For more information about modular class loading. 4.xsd"> <application-name>jboss-as-ejb-in-ear</application-name> <initialize-in-order>true</initialize-in-order> <module> <ejb>myBeans.war then package those properties in WAR WEB-INF/classes/ folder. For example.ear.jar and place that jar in EAR lib/ folder.

You will no longer package the JDBC driver with the application or in the server/lib directory. this has all changed. This file was then deployed in the server's deploy directory. In AS7. If you are running in standalone mode.3.xml. A JDBC 4-compliant driver can be installed as a deployment or as a core module. The following is an example of a MySQL datasource element: JBoss Community Documentation Page 41 of 617 . A driver that is JDBC 4-compliant contains a META-INF/services/java. 4. the configuration file is the domain/configuration/domain. Schema reference information.WildFly 8 4.xml file. the JCA data source configuration was defined in a file with a suffix of *-ds.xml file.3. The IronJacamar distribution features a migration tool that can help you convert your previous datasource configuration file into the new format. The JDBC driver was copied to the server lib/ directory or packaged in the application's WEB-INF/lib/ directory. You can find more information about the tool here: IronJacamar Datasource and Resource Adapter Migration Tool . A driver that is not JDBC 4-compliant requires additional steps.1 Overview In previous versions of the application server. you will configure the datasource in the standalone/configuration/standalone.xml file. a datasource is configured in the server configuration file. can be found here: Datasource Descriptors. you will need to create a datasource element and a driver element for your JDBC driver and datasource information in the standalone. If you are running in domain mode.xml file is now obsolete and the datasource configuration information is now defined in the standalone/configuration/standalone.3 Update the DataSource Configuration 4.Driver file that specifies the driver class name. which is the same for both modes.xml or in the domain/configuration/domain. First. The *-ds.2 Define the datasource In WildFly 8. as noted below.xml file.xml or domain.sql. You will use some of the same information that was previously defined in the *-ds.xml file.

see Adding a MySQL datasource to JBoss AS 7.1. please refer to the DataSources chapter of the Admin Guide.3 Install the JDBC driver The JDBC driver can be installed into the container in one of two ways: either as a deployment or as a core module. which will be outlined below.15.sql.15. This is an example of the driver element for a JDBC 4-compliant MySQL driver.sql. For a detailed explanation how to deploy JDBC 4-compliant driver jar.jar </driver> <transaction-isolation> TRANSACTION_READ_COMMITTED </transaction-isolation> <pool> <min-pool-size>100</min-pool-size> <max-pool-size>200</max-pool-size> </pool> <security> <user-name> USERID </user-name> <password> PASSWORD</password> </security> <statement> <prepared-statement-cache-size>100</prepared-statement-cache-size> <share-prepared-statements/> </statement> </datasource> A JAR that is JDBC 4-compliant contains a META-INF/services/java. JBoss Community Documentation Page 42 of 617 .WildFly 8 <datasource jndi-name="java:/YourDatasourceName" pool-name="YourDatasourceName"> <connection-url>jdbc:mysql://localhost:3306/YourApplicationURL</connection-url> <driver> mysql-connector-java-5.Driver</driver-class> </driver> For more information on how to add a MySQL driver.jar" module="com.15.jdbc. <driver name="mysql-connector-java-5. <driver name="mysql-connector-java-5. This is used by the server to find name of the class(es) of the Drivers which exist in that JAR.mysql.jar" module="com.Driver file that specifies the driver class name.mysql"/> This is an example of the driver element for driver that is not JDBC 4-compliant.3.mysql"> <driver-class>com.Driver file that specifies the driver class name.1. The driver-class must be specified since it there is no META-INF/services/java. 4. There are pros and cons to each approach.1.

it is deployed as a regular JAR. This is the recommended way to install the driver. More information on that topic can be found here: Installing a JDBC Driver as a Deployment. Any JDBC 4-compliant driver will automatically be recognized and installed into the system by name and version.xml file to define the module. In WildFly 8 standalone mode. for example a JAR with the driver and a dependent license JAR. using the MySQL JDBC driver above.sql. you will need to create a directory structure under the modules folder.WildFly 8 Install the JDBC driver as a deployment When you install the JDBC driver as a deployment. You must install the JDBC driver as a core module. you can not install the driver as a deployment. deployments are automatically propagated to all servers to which the deployment applies. you simply copy the JDBC 4-compliant JAR into the AS7_HOME/standalone/deployments directory. Install the JDBC driver as a core module To install the driver as a module.Driver".sql. A JDBC 4-compliant JAR is identified using the Java service provider mechanism. For example. When you run your application server in domain mode. If your JDBC driver JAR is not JDBC 4-compliant.jar If the JDBC driver consists of more than one JAR. you then create the following module.xml file: JBoss Community Documentation Page 43 of 617 .15.1.Driver file to the JAR or by deploying the JAR with an overlay. Here is an example of a MySQL JDBC driver installed as a deployment: JBOSS_HOME/standalone/deployments/mysql-connector-java-5. which contains the name of the class(es) of the Drivers which exist in that JAR. you would create a directory structure as follows: JBOSS_HOME/modules/com/mysql/main In the main directory. it can be made deployable by adding the java. This structure will contain the driver and a module. It contains a text a file named "META-INF/services/java. thus distribution of the driver JAR is one less thing for administrators to worry about.

it is dependent on the Java JDBC APIs which are defined in another module named javax. Make sure you do NOT have a space at the beginning of module. ~ Copyright 2010. or see the FSF site: http://www. Under dependencies.transaction. You should also remove the "hibernate. You should remove the Hibernate jars from your application. and individual contributors as indicated by the @author tags. ~ ~ This is free software. JBoss Community Documentation Page 44 of 617 .15. Red Hat. either version 2. write to the Free ~ Software Foundation. See the copyright.1 of the License.0" encoding="UTF-8"?> <!-~ JBoss.org.4 Configure the datasource for Hibernate or JPA If your application uses JPA and currently bundles the Hibernate JARs.manager_lookup_class" property from your persistence. you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as ~ published by the Free Software Foundation. Home of Professional Open Source. Boston. if not. ~ ~ This software is distributed in the hope that it will be useful.jar"/> </resources> <dependencies> <module name="javax.api"/> </dependencies> </module> The module name. without even the implied warranty of ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. as the case with all JDBC data sources. or (at your option) any later version. "com.0" name="com.WildFly 8 <?xml version="1. Inc. MA 02110-1301 USA. In this case.txt file in the ~ distribution for a full listing of individual contributors. Fifth Floor. you may want to use the Hibernate that is included with WildFly 8. 51 Franklin St.1. See the GNU Lesser General Public License for more details.xml file or you will get a "New missing/unsatisfied dependencies" error for this driver..3. but WITHOUT ANY WARRANTY. Inc..xml as this is not needed. --> <module xmlns="urn:jboss:module:1. matches the directory structure for this module. 4. ~ ~ You should have received a copy of the GNU Lesser General Public License along with this software. you specify the module's dependencies on other modules.fsf.mysql".api that is located under modules/javax/api/main.mysql"> <resources> <resource-root path="mysql-connector-java-5.

which is the same for both modes. If you are running in standalone mode.xml file.5 Where to Find Additional Information DataSource Configuration in WildFly 8 DataSource Descriptors Admin Guide .4 Update the Resource Adapter Configuration TODO: The following section on Resource adapters needs to be reviewed 4.DataSource Configuration How to create and manage datasources in WildFly 8 Adding a MySQL datasource to WildFly 8.4. In WildFly 8. JBoss Community Documentation Page 45 of 617 . you will configure the resource adapter in the standalone/configuration/standalone.1 Overview In previous versions of the application server. the configuration file is the domain/configuration/domain. a resource adapter is configured in the server configuration file. You can find more information about the tool here: IronJacamar Datasource and Resource Adapter Migration Tool . If you are running in domain mode. Schema reference information.xml file.3.xml. 4.WildFly 8 4. The IronJacamar distribution features a migration tool that can help you convert your previous datasource configuration file into the new format. can be found here: Resource adapter descriptors. the resource adapter configuration was defined in a file with a suffix of *-ds.

WildFly 8

4.4.2 Define the resource adapter
The resource adapter descriptor information is defined under the <subsystem
xmlns="urn:jboss:domain:resource-adapters:1.0"/> element in the server configuration file.
You will use some of the same information that was previously defined in the *-ds.xml file.
The following is an example of a resource adapter element in the server configuration file:

<resource-adapters>
<resource-adapter>
<archive>multiple-full.rar</archive>
<config-property name="Name">ResourceAdapterValue</config-property>
<transaction-support>NoTransaction</transaction-support>
<connection-definitions>
<connection-definition
class-name="org.jboss.jca.test.deployers.spec.rars.multiple.MultipleManagedConnectionFactory1"
enabled="true" jndi-name="java:/eis/MultipleConnectionFactory1"
pool-name="MultipleConnectionFactory1">
<config-property name="Name">MultipleConnectionFactory1Value</config-property>
</connection-definition>
<connection-definition
class-name="org.jboss.jca.test.deployers.spec.rars.multiple.MultipleManagedConnectionFactory2"
enabled="true" jndi-name="java:/eis/MultipleConnectionFactory2"
pool-name="MultipleConnectionFactory2">
<config-property name="Name">MultipleConnectionFactory2Value</config-property>
</connection-definition>
</connection-definitions>
<admin-objects>
<admin-object
class-name="org.jboss.jca.test.deployers.spec.rars.multiple.MultipleAdminObject1Impl"
jndi-name="java:/eis/MultipleAdminObject1">
<config-property name="Name">MultipleAdminObject1Value</config-property>
</admin-object>
<admin-object
class-name="org.jboss.jca.test.deployers.spec.rars.multiple.MultipleAdminObject2Impl"
jndi-name="java:/eis/MultipleAdminObject2">
<config-property name="Name">MultipleAdminObject2Value</config-property>
</admin-object>
</admin-objects>
</resource-adapter>
</resource-adapters>

TODO: The above section on Resource adapters needs to be reviewed

JBoss Community Documentation

Page 46 of 617

WildFly 8

4.5 Update application JNDI namespace names
4.5.1 Overview
EJB 3.1 introduced a standardized global JNDI namespace and a series of related namespaces that map to
the various scopes of a Java EE application. The three JNDI namespaces used for portable JNDI lookups
are java:global, java:module, and java:app. If you use JNDI lookups in your application, you will need to
change them to follow the new standardized JNDI namespace convention.
To conform to the new portable JNDI namespace rules, you will need to review the JNDI namespace rules
and modify the application code to follow these rules.

4.5.2 Review the JNDI Namespace Rules
WildFly 8 has tightened up on JNDI namespace names to provide predictable and consistent rules for every
name bound in the application server and to prevent future compatibility issues. This means you might run
into issues with the current namespaces in your application if they don't follow the new rules.
Namespaces should follow these rules:
1. Unqualified relative names like "ExampleDS" or "jdbc/ExampleDS"
should be qualified relative to "java:comp/env", "java:module/env", or
"java:jboss/env", depending on the context.
2. Unqualified "absolute" names like "/jdbc/ExampleDS" should be
qualified relative to a "java:jboss/root" name.
3. Qualified "absolute" names like "java:/jdbc/ExampleDS" should be
qualified the same way as #2.
4. The special "java:jboss" namespace is shared across the entire AS
server instance.
5. Any "relative" name with a "java:" lead-in must be in one of the five
namespaces: "comp", "module", "app", "global", or our proprietary
"jboss". Any name starting with "java:xxx" where "xxx" is a name which
is not equal to one of the above five would result in an invalid name error.

JBoss Community Documentation

Page 47 of 617

WildFly 8

4.5.3 Modify your application code to follow the new JNDI
namespace rules
Here's an example of a JNDI lookup in EAP 5.1. This code is usually found in an initialization method. Note
the lookup name is: "OrderManagerApp/ProductManagerBean/local".
Old - EAP 5.1
private ProductManager productManager;
try {
context = new InitialContext();
productManager = (ProductManager)
context.lookup("OrderManagerApp/ProductManagerBean/local");
}
catch(Exception lookupError) {
throw new ServletException("Unable to find the ProductManager bean", lookupError);
}

Here is an example of how the same lookup would be coded in WildFly 8. This code is defined as member
variables. The lookup name now uses the new portable java:app JNDI namespace:
"java:app/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager"
New - AS 7
@EJB(lookup="java:app/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager")
private ProductManager productManager;

JBoss Community Documentation

Page 48 of 617

WildFly 8

4.5.4 Examples of JNDI mappings in previous releases and
how they might look now
(This needs input!)
Previous Namespace

New Namespaces

OrderManagerApp/ProductManagerBean/local java:module/ProductManagerBean!services.ejb.ProductManager (EE6 st
accessible within the same module)

OrderManagerApp/ProductManagerBean/local java:app/OrderManagerEJB/ProductManagerBean!services.ejb.ProductM
binding, only accessible within the same application)

OrderManagerApp/ProductManagerBean/local java:global/OrderManagerApp/OrderManagerEJB/ProductManagerBean
(EE6 standard binding, globally accessible)
java:comp/UserTransaction

java:comp/UserTransaction (This will not be accessible for non EE thread
application directly creates)

java:comp/UserTransaction

java:jboss/UserTransaction (Globally accessible, use this if java:comp/Us
available)

java:/TransactionManager

java:jboss/TransactionManager

java:/TransactionSynchronizationRegistry

java:jboss/TransactionSynchronizationRegistry

4.5.5 Where to Find Additional Information
Java EE6 Tutorial - Portable JNDI Syntax
Application-specified Portable JNDI Names

4.6 Migrate remote EJB clients to the WildFly 8 client
API
TODO: complete this section

JBoss Community Documentation

Page 49 of 617

WildFly 8

4.7 Migrate EAP 5 Deployed Applications That Make
Remote Invocations to WildFly 8
4.7.1 Overview
In WildFly 8, there are two ways to make remote invocations to the server:
1. You can use the new JBoss specific EJB client API to do the invocation.
2. You can use JNDI to lookup a proxy for your bean and invoke on that returned proxy.
This section covers option 2: coding changes required for clients that use JNDI.
In EAP 5, the EJB remote interface was bound in JNDI, by default, under the name "ejbName/local" for local
interfaces, and "ejbName/remote" for the remote interfaces. The client application then looked up the stateful
bean using "ejbName/remote".
In AS 7, you use the ejb: namespace for remote access to EJBs with the following syntax:
For stateless beans:

ejb:<app-name>/<module-name>/<distinct-name>/<bean-name>!<fully-qualified-classname-of-the-remote-interface>

For stateful beans:

ejb:<app-name>/<module-name>/<distinct-name>/<bean-name>!<fully-qualified-classname-of-the-remote-interface>?s

The values to be substituted in the above syntax are:
<app-name> - the application name of the deployed EJBs. This is typically the ear name without the
.ear suffix, however, the name can be overridden in the application.xml file. If the application is not
deployed as a .ear, this value is an empty string. Assume this example was not deployed as an EAR.
<module-name> - the module name of the deployed EJBs on the server. This is typically the jar name
of the EJB deployment, without the .jar suffix, but can be overridden via the ejb-jar.xml. In this
example, assume the EJBs were deployed in a jboss-as-ejb-remote-app.jar, so the module name is
jboss-as-ejb-remote-app.
<distinct-name> - an optional distinct name for the EJB. This example doesn't use a distinct name, so
it uses an empty string.
<bean-name> - by default, is the simple class name of the bean implementation class.
<fully-qualified-classname-of-the-remote-interface> - the remote view fully qualified class name.

JBoss Community Documentation

Page 50 of 617

WildFly 8

4.7.2 Update the Client Code
Assume you have deployed the following stateless EJB to an AS 7 server. Note that it exposes a remote
view for the bean.

@Stateless
@Remote(RemoteCalculator.class)
public class CalculatorBean implements RemoteCalculator {
@Override
public int add(int a, int b) {
return a + b;
}
@Override
public int subtract(int a, int b) {
return a - b;
}
}

In EAP 5, the client EJB lookup and invocation was coded something like this:

InitialContext ctx = new InitialContext();
RemoteCalculator calculator = (RemoteCalculator)
ctx.lookup("CalculatorBean/remote");
int a = 204;
int b = 340;
int sum = calculator.add(a, b));

In AS 7, using the information described above, the client lookup and invocation is coded like this:

final Hashtable jndiProperties = new Hashtable();
jndiProperties.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
final Context context = new InitialContext(jndiProperties);
final String appName = "";
final String moduleName = "jboss-as-ejb-remote-app";
final String distinctName = "";
final String beanName = CalculatorBean.class.getSimpleName();
final String viewClassName = RemoteCalculator.class.getName();
final RemoteCalculator statelessRemoteCalculator = RemoteCalculator) context.lookup("ejb:" +
appName + "/" + moduleName + "/" + distinctName + "/" + beanName + "!" + viewClassName);
int a = 204;
int b = 340;
int sum = statelessRemoteCalculator.add(a, b);

If your client is accessing a stateful EJB, you must append “?stateful” to the end of the context lookup like
this:

JBoss Community Documentation

Page 51 of 617

WildFly 8

final RemoteCalculator statelessRemoteCalculator = RemoteCalculator) context.lookup("ejb:" +
appName + "/" + moduleName + "/" + distinctName + "/" + beanName + "!" + viewClassName +
"?stateful");

A complete working example, including both server and client code, can be found at the github repo here
https://github.com/jbossas/quickstart/tree/master/ejb-remote.
For more information on remote invocations using JNDI, see EJB invocations from a remote client using
JNDI.

JBoss Community Documentation

Page 52 of 617

WildFly 8

4.8 Modify logging dependencies
4.8.1 Overview
JBoss LogManager supports front ends for all logging frameworks, so you can keep your current logging
code or move to the new JBoss logging infrastructure. Regardless of your decision, because of the modular
class loading changes, you will probably need to modify your application to add the required dependencies.

4.8.2 Update your application code for third-party logging
frameworks
As of WildFly 8, logging dependencies are added by default. There is one caveat to this. If you're using log4j
and you don't want to use the logging subsystem to configure your handlers (appenders), then you need to
exclude the server copy of log4j. See the logging documentation

4.8.3 Modify code to use the New JBoss Logging Framework
To use the new framework, you will need the change your imports and code as follows to achieve the same
results as above:

import org.jboss.logging.Level;
import org.jboss.logging.Logger;
private static final Logger logger = Logger.getLogger(MyClass.class.toString());
if(logger.isTraceEnabled()) {
logger.tracef("Starting...", subsystem);
}

The JAR containing the JBoss Logging classes is located in the module named "org.jboss.logging". Your
MANIFEST-MF file will look like this:

Dependencies: org.jboss.logging

For more information on how to find the module dependency, please see “How to Resolve
ClassNotFoundExceptions” under the “Modular Class Loading” above.

4.8.4 Where to Find Additional Information
WildFly 8 Logging
JBoss Logging Tooling

JBoss Community Documentation

Page 53 of 617

WildFly 8

4.9 Configure changes for applications that use
Hibernate and JPA
4.9.1 Overview
If your application contains a persistence.xml file or the code uses @PersistenceContext or
@PersistenceUnit, WildFly 8 will detect this during deployment and assume the application uses JPA. It will
implicitly add Hibernate 4 and a few other dependencies to your application classpath.
If your application currently uses Hibernate 3 libraries, in most cases, this will not be a problem. You will be
able to deploy and run successfully using Hibernate 4. However, if you see a ClassNotFoundExceptions
when deploying your application you can try one of two following approaches:
1. You may be able to resolve the issue by copying the specific Hibernate 3 JARs containing those
classes into the application "/lib" directory or by adding them to the classpath using some other
method. In some cases this may result in ClassCastExceptions or other class loading issues due to
the mixed use of the Hibernate versions, so you will need to use the second approach.
2. You need to tell the server to use only the Hibernate 3 libraries and you will need to add exclusions
for the Hibernate 4 libraries. Details on how to do this are described here: JPA Reference Guide.
For more information on Hibernate and JPA, see JPA Reference Guide.

JBoss Community Documentation

Page 54 of 617

WildFly 8

4.9.2 Update your Hibernate 3 application to use Hibernate 4
Changes for Hibernate 3.3 applications
1. Hibernate "text" type now maps to JDBC LONGVARCHAR
In pre-3.5 versions of Hibernate, text type were mapped to JDBC CLOB. A new Hibernate type,
"materialized_clob", was added to map Java String properties to JDBC CLOB. If an application has
properties configured as type="text" that are intended to be mapped to JDBC CLOB, they should be
changed to type="materialized_clob" in hbm mapping files, or, if using annotations, @Type(type =
"text") should be replaced by @Lob.
2. Numeric aggregate Criteria projections now return the same value type as their HQL counterparts. As
a result, the return type from the following projections in org.hibernate.criterion have changed:
1. "count" and "count distinct" projections now return a Long value (due to changes in
CountProjection, Projections.rowCount(), Projections.count( propertyName ), and
Projections.countDistinct( propertyName )).
2. "sum" projections return a value type that depends on the property type due to changes in
Projections.sum( propertyName ). Failure to modify your application code may result in a
java.lang.ClassCastException.
1. for properties mapped as Long, Short, Integer, or primitive integer types, a Long value is
returned;
2. for properties mapped as Float, Double, or primitive floating point types, a Double value
is returned.

JBoss Community Documentation

Page 55 of 617

WildFly 8

Changes for Hibernate 3.5 applications
1. AnnotationConfigration must be merged into Configuration
Aside from the fact that AnnotationConfiguration is now deprecated, this usually is not of concern.
However, if you are still using an hbm.xml file, you should be aware that WildFly 8 now uses the
org.hibernate.cfg.EJB3NamingStrategy in AnnotationConfigration instead of the older
org.hibernate.cfg.DefaultNamingStrategy that was previously used in Configuration. This can result in
naming mismatches. If you rely on the naming strategy to default the name of a association
(many-to-many and collections of elements) table, you may see this issue. To resolve it, you can tell
Hibernate to use the the legacy org.hibernate.cfg.DefaultNamingStrategy by calling
Configuration#setNamingStrategy and passing it
org.hibernate.cfg.DefaultNamingStrategy#INSTANCE
2. The namespaces for the Hibernate DTD files have changed.
Previous DTD Namespace

New DTD Namespaces

http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd http://www.hibernate.org/dtd/hibernate-configurati
http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd

http://www.hibernate.org/dtd/hibernate-mapping-3

3. If you are using Oracle, the global environment variable "hibernate.jdbc.use_streams_for_binary"
must be set to true if you are using "materialized_clob" or "materialized_blob" properties.
4. If you are using PostgreSQL, the global environment variable
"hibernate.jdbc.use_streams_for_binary" must be set to false if you are using CLOB or BLOB
properties.

General Changes when migrating to Hibernate 4
In Hibernate 4.0 there is a new IdentifierGenerator implementations.
Hibernate 4.0 supplies a property that is called hibernate.id.new_generator_mappings and hibernate
documentation states that it defaults to false for backward compatibility reasons - however in AS 7.1 this
value defaults to true.
consider setting the value to false in persistence.xml in case you don't see the behaviour you had in your
app in previous versions.
for more information - read about 5.1.2 Identifiers in general and about 5.1.2.2. Identifier generator
more specifically* *here

JBoss Community Documentation

Page 56 of 617

WildFly 8

4.9.3 Changes in JPA container managed behaviour
To comply with the JPA 2.0 specification section 7.6.3.1 requirements for persistence context propagation,
jira AS7-1663 (An extended persistence context should not be propagated if there is no JTA transaction)
was fixed in WildFly 8. If a SFSB with an extended persistence context, invokes another bean (not in an
active JTA transaction) and the other bean uses a transactional entity manager. The extended persistence
context will not be propagated to the transactional entity manager (propagation will occur if invoked with an
active JTA transaction). If your application expects the extended persistence context to be propagated to
the bean with the transactional entity manager, you need to change your app to do the invocation with an
active JTA transaction.

4.9.4 Infinispan as Second Level Cache
Overview
JBoss Cache has been replaced by Infinispan for 2nd level cache (even for non-clustered use). This requires
a change to the persistence.xml file. The syntax is slightly different, depending on if you're using JPA or
Hibernate APIs. These examples assume you are using JPA.

JBoss Community Documentation

Page 57 of 617

infinispan.cache.JndiInfinispanRegionFactory"/> <property name="hibernate.transaction.cachefactory" value="java:CacheManager"/> <property name="hibernate.factory_class property.region.cache. Select the correct Hibernate transaction manager lookup class using the hibernate.use_minimal_puts" value="true"/> <property name="hibernate.manager_lookup_class" value="org.use_second_level_cache" value="true"/> <property name="hibernate.cache.cache.cache.use_second_level_cache" value="true"/> <property name="hibernate.cfg.jbc2.use_second_level_cache" value="true"/> <property name="hibernate.hibernate.region.region. select InfinispanRegionFactory as the cache region factory JBoss Community Documentation Page 58 of 617 .region. select JndiInfinispanRegionFactory as the cache region factory and add the cache manager’s JNDI name If running JPA/Hibernate and Infinispan standalone or within third party application server. Configure the Infinispan cache region factory using one of the two options below: If the Infinispan CacheManager is bound to JNDI.use_minimal_puts" value="true"/> Since JPA applications use Infinispan by default.cache.jbc2.cache.factory_class" value="org.WildFly 8 Infinispan second-level cache settings Here's an example of the persistence.infinispan.cache.cache.transaction.manager_lookup_class property.hibernate.JBossTransactionManagerLookup"/> <property name="hibernate.cache.1: <property name="hibernate. For native Hibernate applications you need to: Select the correct Hibernate transaction factory using the hibernate.hibernate.region_prefix" value="services"/> Here is what is needed to configure the same thing for a JPA application using Infinispan with WildFly 8: <property name="hibernate.jbc2.cache.use_minimal_puts" value="true"/> Here is what is needed to configure the same thing for a native Hibernate application using Infinispan with WildFly 8: <property name="hibernate.xml file in EAP 5.cachemanager" value="java:jboss/infinispan/hibernate"/> <property name="hibernate.cache.factory_class" value="org.cache.entity" value="mvcc-entity"/> <property name="hibernate.transaction.transaction. fewer properties are needed to be specified.JndiMultiplexedJBossCacheRegionFactory"/> <property name="hibernate.cache.

persistence.mode to none.validator.persistence.9.persistence. You can also disable life-cycle based validation by setting the javax. you can ignore groups as Hibernate Validator 3 did not have such a feature.group. A call to any validate method will return a set of ConstraintViolation instances (in contrast to an array of InvalidValue instances in Validator 3). You just need to import the right class and in some cases change the name and/or type of a constraint parameter.constraints and org. The values of these properties are the comma-separated. You can customize your Validator instance by using a fluent API starting with ValidatorFactory. CDI bean or any other Java EE injectable resource.usingContext. Let's have a look at the different parts which needs updating.validation. Other values are auto.x means switching to a completely new code base and new API the JSR 303 (Bean Validation). The former contains the standardized Bean Validation constraints whereas the latter contains some Hibernate Validator specific constraints. javax. The validation groups feature is part of the Bean Validation specification and it is recommended you get familiar with this new functionality. JBoss Community Documentation Page 59 of 617 . For a pure migration however. TraverableResolver and ConstraintValidatorFactory.pre-persist. and javax. To upgrade to Hibernate Validator 4 you have to use the constraints in the javax. Using this API you can configure a custom MessageInterpolator. fully specified class names of the groups to validate. All constraints which existed in Validator 3 are available in Validator 4.validation. you need to create a Validator instance from the ValidatorFactory via ValidatorFactory.hibernate. You can configure the groups to be validated per event type using the properties javax. An empty set indicates a successful validation without any constraint violations.constraints packages. All these interfaces are new to Hibernate Validator and are specified in the Bean Validation specification.x to 4.validation. Life cycle triggered validation When used in combination with Hibernate 4 life-cycle based validation will be automatically enabled by Hibernate Core.validation. callback and ddl. The good news is that this migration should be straight forward. Using the new Bean Validation constraints This is the most visible change fro Hibernate Validator 3 constraints in your code base.persistence.getValidator. Accessing the default ValidatorFactory WildFly 8 binds a default ValidatorFactory to the JNDI context under the name java:comp/ValidatorFactory.validation. use the validate methods to either validate your whole entity or just a single property. Once you have your Validator instance.group.5 Migrate to Hibernate 4 Validator Migrating from Hibernate Validator 3. Validation will occur on entity INSERT.WildFly 8 4.pre-remove. or get Validator injected in your EJB. Manual validation In case you want to manually validate. UPDATE and DELETE operations.group.pre-update. where auto is the default.

hibernate. In Validator 4 the interface to implement is javax. Only the method signature is slightly different.RelationalPersistence for Idiomatic Java JBoss Community Documentation Page 60 of 617 . namely initialize and isValid.WildFly 8 Custom constraints In Validator 3 a custom constraint needed to implement org.ConstraintValidator which contains the same methods as the old interface. Note that support for DDL alteration is no longer part of Hibernate Validator 4 but very few users made use of this feature.Validator. Where to Find Additional Information Infinispan Using Infinspan as JPA/Hibernate Second Level Cache Provider HIBERNATE .validator.validation.

4.10 Changes you need to make for Security 4.WildFly 8 4.properties"/> </login-module> </authentication> </security-domain> If you are running in standalone mode.dir}/example-roles.xml for enterprise applications. ${jboss.config.config. Remove this prefix from the security domain configurations in jboss-web.dir}/example-users.10. You should remove all of the resteasy configuration from your web.1 Configure Security for Basic Authentication The UsersRolesLoginModule has always looked for the properties files in the classpath.server.server.xml and replace it with one of the following three options: JBoss Community Documentation Page 61 of 617 .11 Configure JAX-RS / Resteasy changes WildFly 8 sets up Resteasy for you. In previous versions of AS.dir} refers to JBOSS_HOME/standalone/configuration/ A list of available login modules can be found in the admin guide. 4.properties"/> <module-option name="rolesProperties" value="${jboss. so there is no need to set it up yourself.2 Modify security domain names In WildFly 8 security domains no longer use the prefix java:/jaas/ in their names.xml configuration file : <security-domain name="example"> <authentication> <login-module code="UsersRoles" flag="required"> <module-option name="usersProperties" value="${jboss. so you need to package the properties within the application to make them available in the classpath.server.10. files in the JBOSS_HOME/server/SERVER_NAME/conf directory were on classpath so you could put your properties files there. To configure security for basic authentication. In WildFly 8 the directory structure has changed.xml for web applications and jboss. add a new security domain under security-domains to your standalone.config.

Application in your application.xml If you do not wish to use @ApplicationPath but still need to subclass Application you can set up the JAX-RS mapping in web.Application and use @ApplicationPath This is the easiest way and does not require any xml configuration.acme.rs.core.MyApplication</servlet-name> <url-pattern>/hello/*</url-pattern> </servlet-mapping> This will make your JAX-RS resources available under /mywebappcontext/hello.rs. Simply include a subclass of javax.ws.core.ws.xml: public class MyApplication extends Application { } <servlet-mapping> <servlet-name>com.core.ws. Note that that the path is /mypath not /mypath/* Subclass javax. For example: @ApplicationPath("/mypath") public class MyApplication extends Application { } This will make your JAX-RS resources available under /mywebappcontext/mypath.WildFly 8 Subclass javax.Application and use web. and annotate it with the path that you want your JAX-RS classes to be available.rs. JBoss Community Documentation Page 62 of 617 . You can also use this approach to override an application path set with the @ApplicationPath annotation.

auth.sun.12 Configure LDAP security realm changes In previous releases of JBoss AS. the LDAP realm was configured as an application-policy in the login-config.initial">com.LdapCtxFactory</module-option> <module-option name="java.LdapExtLoginModule" flag="required"> <module-option name="java.jndi.Application</servlet-name> <url-pattern>/hello/*</url-pattern> </servlet-mapping> This will make your JAX-RS resources available under /mywebappcontext/hello.factory.xml as follows: <servlet-mapping> <servlet-name>javax. Note that you only have to add the mapping..xml file if you are running your server in a managed domain. The server is responsible for adding the corresponding servlet automatically.ws..security.xml If you don't want to subclass Application you can set the JAX-RS mapping in web. the LDAP realm is configured as a security-domain in the standalone/configuration/standalone. </login-module> </authentication> </application-policy> In WildFly 8.WildFly 8 Modify web.jboss.spi.core. not the corresponding servlet.authentication">simple</module-option> . For more information.rs.security.naming.xml file.xml file if you are running a standalone server or in the domain/configuration/domain. 4.ldap.naming. see the JAX-RS Reference Guide. The following is an example of configuration in a previous release: <application-policy name="mcp_ldap_domain"> <authentication> <login-module code="org.. The following is an example of configuration in WildFly 8: JBoss Community Documentation Page 63 of 617 .

. In previous releases.13.initial" value="com. the module options must be specified as element attributes with "value=" as follows: <module-option name="java.LdapLoginModule" flag="required"> <module-option name="java.LdapCtxFactory"/> 4.sun.LdapCtxFactory</module-option> In WildFly 8. </module-option> </module-option> </login-module> </authentication> </security-domain> </security-domains> </subsystem> The XML parser has also changed in WildFly 8.jndi.auth.factory. If your application uses JBoss Messaging as the messaging provider. Backup these tables as necessary. 2.initial">com.authentication" value="simple"> .ldap. Make a backup of any JBoss Messaging data. you specified the module options as element content like this: <module-option name="java.jndi.security. JBoss Community Documentation Page 64 of 617 .sun.naming.naming.0"> <security-domains> <security-domain name="mcp_ldap_domain" type="default"> <authentication> <login-module code="org. you will need to make changes to your application to use HornetQ. and the tables are prefixed with "JBM_". Message data is stored in a database.13 Migrate from JBoss Messaging to HornetQ JBoss Messaging will no longer be included in EAP 6.ldap.sun.factory.factory. Shut down the client and server.jndi.LdapCtxFactory"> <module-option name="java.naming.1 Before you start 1.spi.jboss.naming.security..initial" value="com.WildFly 8 <subsystem xmlns="urn:jboss:domain:security:1.ldap. 4.

Instructions for this are available here. no code changes are required. For more information on HornetQ. so the name of the deployment file will vary. These configurations are located in deployment descriptors on the server running JBoss Messaging. see HornetQ Project Documentation and the HornetQ homepage. depending on your JBoss Messaging installation.13. 4. No bridges are deployed by default. JBoss Messaging stores these files in a file called connection-factories-service. if the application will be connecting to a cluster (which is outside the scope of the JMS specification) please carefully review the HornetQ documentation on clustering semantics as HornetQ and JBoss Messaging have taken substantially different approaches in their respective implementations of clustering functionality.these files contain bridge services deployed with JBoss Messaging.13. However.xml. By default. modify the code to use equivalent features available in HornetQ (if available). Refer to Messaging configuration for details on HornetQ configurations.WildFly 8 4. Note: WildFly 8 doesn't currently support JMS bridges configured in standalone*. This will change in a future version. 4.2 Transfer configurations Transfer the existing JBoss Messaging configurations to the WildFly 8 configuration. If the application code uses features specific to JBoss Messaging. This includes the following configurations: Connection Factory service configuration files .13. Message bridge service configurations .4 Migrate existing messages Move any messages in the JBoss Messaging database to the HornetQ journal via a JMS bridge.xml in the deploy/messaging directory of your application server.xml in the deploy/messaging directory of your application server.these files contain JMS queues and topics deployed with JBoss Messaging. these are stored in a destinations-service.3 Modify application code If the application code uses standard JMS. JBoss Community Documentation Page 65 of 617 .these files contain JMS connection factories deployed with JBoss Messaging. Destination service configurations .

start the server using the appropriate configuration file: $ .14.14 Changes you need to make for Clustering 4. or as standalone servers.1 Starting WildFly 8 with clustering enabled To enable clustering in AS5 and AS6. update your domain.xml and designate a server group to use the "ha" profile and "ha-sockets" socket binding group: e.sh -c all In WildFly 8. the method of enabling clustering depends on whether your servers are started via the domain controller./bin/run.name=UNIQUE_NODE_NAME JBoss Community Documentation Page 66 of 617 . you needed to start your server instances using the "all" profile (or some derivation of it).sh --server-config=standalone-ha. <server-groups> <server-group name="main-server-group" profile="ha"> <jvm name="default"> <heap size="64m" max-size="512m"/> </jvm> <socket-binding-group ref="ha-sockets"/> </server-group> </server-group> To enable clustering for standalone servers. To enable clustering for servers started via the domain controller.WildFly 8 4.xml -Djboss. e. $ .g.node.g./bin/standalone.

14.. --> </socket-binding-group> </socket-binding-groups> In the example above.0.xml file. the jvmRoute attribute is configured in the web subsystem of the server configuration file using the instance-id attribute as follows: subsystem xmlns="urn:jboss:domain:web:1.g.2"/> </interface> <interface name="public"> <inet-address value="192.0. For servers started via the domain controller. bind addresses are specified within the standalone-ha.3 Configure jvmRoute to support mod_jk and mod_proxy In previous releases.2"/> </interface> </interfaces> <socket-binding-groups> <socket-binding-group name="ha-sockets" default-interface="public"> <!-./bin/run. 4.168. bind addresses are explicitly defined by the relevant socket bindings within the WildFly 8 configuration files. e. the "public" interface is specified as the default interface for all sockets within the "ha-sockets" socket binding group.xml.0.2 Specifying the bind address In AS5 and AS6.xml: e. <interfaces> <interface name="management"> <inet-address value="192.1" default-virtual-server="default-host" native="false" instance-id="{JVM_ROUTE_SERVER}"> The JVM_ROUTE_SERVER above should be replaced by the jvmRoute server ID.168. JBoss Community Documentation Page 67 of 617 . the web server jvmRoute was configured using a property in the server.2 In WildFly 8.168. bind addresses are specified within domain/configuration/host.WildFly 8 4. In AS 7. For standalone servers.sh -c all -b 192.. you would typically indicate the bind address used for clustering via the "-b" command line argument.g.14.. $ .

you could specify the multicast address and port used for intra-cluster communication using the command line arguments "-u" and "-m". "jboss.14.0..WildFly 8 4.4}" multicast-port="${jboss...11.4 Specifying multicast address/port In AS5 and AS6.11.addr" is the variable for the multicast address and "jboss. <socket-binding name="jgroups-udp" port="55200" multicast-address="${jboss.11" multicast-port="45688"/> <!-.g.11.../bin/domain.addr:230.mcast.mcast.sh -c all -u 228. e.mcast. --> <socket-binding name="jgroups-udp" port="55200" multicast-address="228.11.11 -Djboss. In the following example.11. the multicast address and port used for intra-cluster communication are defined by the socket-binding referenced by the relevant JGroups protocol stack. respectively.0. --> </socket-binding-group> </socket-binding-groups> If you prefer to specify the multicast address and port in the command line.addr=228../bin/run.mcast.mcast.mcast.0" default-stack="udp"> <stack name="udp"> <transport type="UDP" socket-binding="jgroups-udp"/> <!-..11 -m 45688 In WildFly 8..11.port:45688}"/> You can then start your server using the following command line arguments: $ .sh -Djboss. <subsystem xmlns="urn:jboss:domain:jgroups:1. --> </stack> </subsystem> <socket-binding-groups> <socket-binding-group name="ha-sockets" default-interface="public"> <!-.g.port" is the variable for the port.port=45688 JBoss Community Documentation Page 68 of 617 . .. e. you can define the multicast address and ports as system properties and then use those properties on the command line when you start the server.

2 Update Applications That Use Service-style Deployments Although AS 7 no longer uses service-style descriptors. If you are running a standalone server. the container supports these service-style deployments without change where possible.xml deployment descriptors in your AS5/AS6 application.xml or jboss-beans.5 Using an alternate protocol stack In AS5 & AS6. e.stack" system property. You must use org.14. the deployments directory is located here: JBOSS_HOME/standalone/deployments/.g.jgroups. This means that if you used jboss-service. You can continue to package the files in the EAR or SAR.jboss..16.1 Change Maven plugin name The jboss-maven-plugin has not been updated and does not work In WildFly 8. .stack=tcp In WildFly 8. <subsystem xmlns="urn:jboss:domain:jgroups:1./bin/run. you could manipulate the default protocol stack used for all clustering services via the "jboss. or you can place the files directly in the deployments directory.g.16 Additional changes you may need to make 4.jgroups. 4. --> </stack> </subsystem> 4.WildFly 8 4.default. e.as.sh -c all -Djboss.xml.0" default-stack="udp"> <stack name="udp"> <!-. the default protocol stack is defined by the JGroups subsystem within domain.default.xml or standalone-ha.16. JBoss Community Documentation Page 69 of 617 ... they should run with little or no modification in AS 7.plugins:jboss-as-maven-plugin to deploy to the correct directory.15 HA Singleton Deployment TODO: This topic needs content 4.

you may need to move JARs to a different location within the application archive or modify class-path information so classes can be found.17. JBoss Community Documentation Page 70 of 617 . a business class. or missing archives. you may need to explicitly define the dependencies on other modules or possibly copy an archive from a previous framework. For more information on EAR and WAR packaging. you may need to change the packaging of the application. If the class specified is a class you have created in your application. for example. Change the application structure to find classes within the application If the class specified in the exception is a class written specifically for the application. your application may no longer be able to find classes within the EAR or WAR. unresolved dependencies. see "WAR Class Loading" and "EAR Class Loading" in Class Loading in AS7. If the class is is external to your project. Due to modular class loading changes.17 Debug and Resolve Migration Issues 4. In his case. the problem is mostly likely a packaging issue.1 Debug and resolve ClassNotFoundExceptions and NoCLassDefFoundErrors ClassNotFoundExceptions can occur due to application packaging issues.WildFly 8 4.

findClass(ModuleClassLoader.apache. Find the module containing the JAR in the JBOSS_HOME/modules directory and determine the module name. Open the JBOSS_HOME/modules/org/apache/commons/logging/main/module.slf4j.war:main" from Service Module Loader] at org.apache. Navigate to the JBOSS_HOME/modules directory and look for the module path. The module name to the Dependencies in the MANIFEST.commons. If you find a module for the class.jcl-over-slf4j JBoss Community Documentation Page 71 of 617 .logging 2. You can manually find the module dependencies.org. there is org/apache/commons/logging 3. 2.MF file: Dependencies: org. 2.MF file Dependencies: org. 2.jboss. to resolve the dependency you will find the JAR that contains the class specified by the ClassNotFoundException by looking in the JBoss WildFly 8 modules directory. 1. You can use Tattletale to find the JBoss module name. 4. Add the module name to the Dependencies in the MANIFEST. First determine if there is an obvious module for the class 1.xml file and find the module name.modules. you must add a dependency to the manifest entry.lang. Determine which JAR contains the class. 3.Log from [Module "deployment. See the section: Use Tattletale to find application dependencies.WildFly 8 How to find the JBoss module dependency For other classes. If there is no obvious module path for the class 1.java:188) Find the JBoss module containing this class by doing one of the following: 1. under modules.TopicIndex.logging.ClassNotFoundException: org.ModuleClassLoader.dom4j. if you see this ClassNotFoundException trace in the log: Caused by: java. in this case.commons. For example.

ClassValidator r' `find . 2.javassist" /> </exclusions> JBoss Community Documentation Page 72 of 617 . It can also be a result of the same class existing in multiple JARs. you may see ClassCastExceptions and need to exclude the conflicting module dependencies. This will prevent the server from adding the dependencies. If the newer JARs are loaded as automatic dependencies in WildFly 8.WildFly 8 How to find the JAR in previous install If the class is not found in a JAR packaged in a module defined by the WildFly 8 server. Open a terminal and navigate to the EAP5_HOME/ directory. and explicitly define the dependency in the MANIFEST.1.xml file There are cases where you will need to copy in older JARs for your applcation.jar'` 3.1/seam/lib/hibernate-validator.x install or your prior server's lib directory and copy it to your application's lib/ directory.MF file. Often you need to find and remove the JAR from the application's WAR or EAR.jar matches 4. Exclude any conflicting dependencies using the jboss-deployment-structure. when you migrate the Seam Booking application from EAP 5.xml file: <exclusions> <module name="org.validator.2 Debug and resolve ClassCastExceptions This usually happens because the class is being loaded by a different class loader than the class it extends.hibernate.lang.NoClassDefFoundError: org/hibernate/validator/ClassValidator at java. You should see this (one of many) for the result: Binary file .lang.6. This is an example of the exclusions element in the jboss-deployment-structure. 5./jboss-eap-5. For example. \-name '*. Issue the command: grep 'org. you see this ClassNotFoundException in the log: Caused by: java. Then you must find the dependent JBoss module containing the class. find the JAR in your EAP 5.0_25] 1. Copy this JAR to the application's lib/ directory. Rebuild and redeploy the application 4. Remove any unnecessary JARs from the Application archive First find the JAR that contains the class and determine how it is being loaded.Class.17.getDeclaredMethods0(Native Method) [:1.

3 Debug and resolve class loading issues If you are not able to figure out how the classes are loaded. you can often resolve the problem by printing class loader information to the log. add any dependencies as described above.17.lang.Foo2 In your code.xml file or excluding dependencies in the jboss-deployment-structure.toString()). 4. based on your application.4 Debug and resolve NoSuchMethodExceptions A NoSuchMethodException indicates a class version mismatch between JAR files. You might have to remove or move a conflicting JARs. logger.xml file.example2.getClass().WildFly 8 4. JBoss Community Documentation Page 73 of 617 .example2.example1. add dependencies through the MANIFEST.17.MF or jboss-deployment-structure.info("Class loader for foo1: " + com.Foo1. you will need to determine the best approach to resolve the issue. It indicates your application's calling class was compiled using a different version of the JAR than the one used by the application server runtime.getClassLoader().ClassCastException: com. This can occur when you package different versions of common libraries your application. The ModuleClassLoader information in the log will show which modules are loading the classes and. This can also happen if you migrate between versions of JBoss EAP and do not recompile your application against the updated EAP jars.info("Class loader for foo2: " + com.example1.getClassLoader().toString()). print the class loader information by logging logger.getClass(). remove any common JARs from your application archive. for example Hibernate. if you see the following ClassCastException in the log: java. To resolve this problem.Foo1 cannot be cast to com. For example.Foo2. recompile and deploy your application.

it may be due to the way JBoss WS handles the deployment. for example.6 Debug and resolve JBoss Seam debug page errors. Use the same technique above under “How to Resolve ClassNotFoundExceptions or NoCLassDefFoundErrors” to resolve the dependencies. under the Component org. JBossWS introduced a Context Root Mapping Algorithm or rules for servlet based endpoints to allow it to become seamlessly compatible with TCK6. This means that if you have a WAR and a JAR with the same name within an EAR.5 Debug and resolve DuplicateServiceExceptions If you get a DuplicateServiceException for a subdeployment of a JAR or a message that the WAR application has already been installed when you deploy your EAR in WildFly 8.17. Provide a <context-root> element in the in jboss-web.jboss.xml file. Customize the <context-root> for the WAR in the application. JBoss Community Documentation Page 74 of 617 . Provide a <context-root> element in the in jboss-webservices. 4.xml file.seam.caughtException.WildFly 8 4. it may create a web context with the same name as the JAR which will conflict with the WAR context. In AS6. You can resolve this issue in one of the following ways: Rename the JAR file to a name that is different than the WAR. Usually the root cause of the exception can be found in one of the links on this page.xml file.17.

JBoss Community Documentation Page 75 of 617 .xml file. If your application uses JBoss AOP. In previous releases.xml file are now done in the server configuration file. 4. see the section 'Update application JNDI namespace names' above.2 Replace JBoss AOP Interceptors JBoss AOP (Aspect Oriented Programming) is no longer included in WildFly. this is the domain/configuration/domain. For a standalone server.xml deployment descriptor replaces the jboss.xml file. 4. however.3 Modify the jboss-web. The new file is incompatible with jboss. but there is no client side interceptor in AS 7.18. you must use the full JNDI prefix with EJB 2.1. JBoss AOP was used by the EJB container.xml.18 EJB 2.1 Modify the Code to Use the New JNDI Namespace Rules Like EJB 3. 4.xml deployment descriptor to override and add to the features provided by the Java Enterprise Edition (EE) defined ejb3-jar.x Support As 7. To start AS 7 with the full profile.4 Replace the jboss. If you are running your server in a managed domain. this is the standalone/configuration/standalone. Applications that integrate AOP interceptors into the EJB layer must be redesigned to use EJB3 interceptors and CDI. Server side interceptors can be changed to EJB3 interceptors.WildFly 8 4.1. However.0. and the jboss. you need to make a few code modifications and must start the server with the full profile.18. 4. Standard EJB3 configurations that were made in the ejb3-interceptors-aop. 4.1 requires the Java Enterprise Edition 6 Full Profile.xml deployment descriptor.18.xml is now ignored in deployments.18. For more information on the new JNDI namespace rules and code examples.xml" on the command line when you start the server.xml File Descriptor Modify the <jndi-name> for each <ejb-ref> to use the new JNDI fully qualified lookup format.18. you need modify your application code as follows. pass the argument "-c standalone-full.1 provides support for EJB 2. in AS 7.xml deployment descriptor file The jboss-ejb3. the EJB container uses a new mechanism.5 Start the Server with the Full Profiles EJB 2.

you will follow the steps outlined in the migration guide.DB_CLOSE_DELAY=-1 --driver-name=h2 --user-name=sa --password=sa JBoss Community Documentation Page 76 of 617 .DB_CLOSE_DELAY=-1</connection-url> <driver>h2</driver> <security> <user-name>sa</user-name> <password>sa</password> </security> </datasource> This definition is a copy of the default HSQL datasource defined in WildFly.20 How to migrate Seam 2 archives to WildFly 8 4. The easiest way is to define this datasource is to add the following datasource definition to the JBOSS_HOME/standalone/configuration/standalone. You can also add the datasource using the jboss-cli command line interface: $ JBOSS_HOME/bin/jboss-cli.20.1 Overview When you migrate a Seam 2 application.xml file the : <datasource name="ExampleDS" jndi-name="java:/ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true"> <connection-url>jdbc:h2:mem:test. You will need to configure the datasource as noted above.19 Migration required for other components ToDo: Conplete this section 4.20. 4. You will need to specify any module dependencies.sh --connect [standalone@localhost:9999 /] data-source add --name=ExampleDS --jndi-name=java:/ExampleDS --connection-url=jdbc:h2:mem:test. You will also need to determine if the application has any dependencies on archives that do not ship with AS7 and copy any dependent JARs into the application lib/ directory.2 Update the datasource configuration Some Seam 2 examples use a default JDBC datasource named java:/ExampleDS.WildFly 8 4.

jsf-impl" slot="main"/> </exclusions> <dependencies> <module name="javax.WildFly 8 4.xml file in the EAR META-INF/ directory that contains the following data: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0"> <deployment> <exclusions> <module name="org.api" slot="1.0 modules.hibernate"/> </exclusions> <deployment> </jboss-deployment-structure> JBoss Community Documentation Page 77 of 617 .3 Add any required dependencies Since Seam 2 applications use JSF 1.faces.faces.2. Some hibernate classes are no longer available and you may need to copy one or more of the older hibernate JARs into the /lib directory.sun.jsf-impl" slot="1. You will need to create a jboss-deployment-structure.2"/> <module name="com.2 modules and exclude the JSF 2.4 Copy dependent archives from outside frameworks or other locations Even if your Seam 2 application uses Hibernate 3.2"/> </dependencies> </sub-deployment> </jboss-deployment-structure> If your application uses any third-party logging frameworks you will need add dependencies as described in that section of the migration guide.faces. you may still be able to run with the Hibernate 4 module packaged in WildFly. you may have to exclude the hibernate module in the deployments section of the META-INF/jboss-deployment-structure.sun.api" slot="main"/> <module name="com.0"> <deployment> <dependencies> <module name="javax.2" export="true"/> </dependencies> </deployment> <sub-deployment name="jboss-seam-booking.20.war"> <exclusions> <module name="javax. 4.20.xml <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1. If you end up with ClassNotFoundExceptions or ClassCastExceptions involving hibernate classes.2" export="true"/> <module name="com.sun.api" slot="1.jsf-impl" slot="1. you will need to add dependencies for the JSF 1.

apache.jar hibernate-annotations.jar hibernate-validator.sun.faces.jar slf4j-log4j12.log4j" /> <module name="org. Add jboss-deployment-structure. which were in JBoss AS 5/6 and are upgraded in WildFly to higher major version: slf4j-api.apache. Add the following dependencies from seam distribution (seam/lib directory) into jboss-seam-jpa.jar 4.HashtableCacheProvider"/> --> 3.faces.2"/> <module name="com.cache.20.provider_class" value="org.api" slot="1.5 Seam 2 JPA example deployment on WildFly 1.2"/> </dependencies> </deployment> </jboss-deployment-structure> Name Size Creator Creation Comment Date XML File 0.xml to jboss-seam-jpa. Novotny 2011 jboss-deployment-structure.commons.6 jboss-deployment-structure. 2.war/WEB-INF/classes/META-INF/persistence. Remove the jboss-web.war/WEB-INF/ with the following content in it: <jboss-deployment-structure> <deployment> <exclusions> <module name="javax.xml file from the jboss-seam-jpa.<property name="hibernate.jsf-impl" slot="main"/> </exclusions> <dependencies> <module name="org.war/WEB-INF/lib directory.dom4j" /> <module name="org.Defined class loading in jboss-web.api" slot="main"/> <module name="com.commons.logging" /> <module name="org.xml: <!-.xml is now default behaviour.hibernate.war/WEB-INF/ directory .cache. Comment or remove hibernate property in jboss-seam-jpa.xml for Seam 2 JPA example migration 04:50 JBoss Community Documentation Page 78 of 617 .apache.jsf-impl" slot="1.jar hibernate-core.jar hibernate-commons-annotations.collections" /> <module name="javax.sun.WildFly 8 4.jar hibernate-entitymanager.xml kB Marek Jul 18.

21 Running Seam 3 archives on WildFly ToDo: Complete this section JBoss Community Documentation Page 79 of 617 .WildFly 8 4.jboss.example.jar/AuthenticatorAction!org.jboss.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-1) JNDI bindings for session bean named AuthenticatorAction in deployment unit subdeployment "jboss-seam-booking.NameNotFoundException: Name 'jboss-seam-booking' not found in context '' If you don't want to modify JNDI lookups throughout the code.jar" of deployment "jboss-seam-booking.processors. add a matching component element to the components. The JNDI binding messages should look similar to this: 15:01:16.jboss.jar/AuthenticatorAction!org.seam.jboss.seam.jar/AuthenticatorAction java:module/AuthenticatorAction 3.<core:init jndi-pattern="jboss-seam-booking/#{ejbName}/local" debug="true" distributable="false"/> --> <core:init debug="true" distributable="false"/> 2.booking.NameNotFoundException errors in the log like the following: javax. 1.20.booking.ear" are as follows: java:global/jboss-seam-booking/jboss-seam-booking.example.seam.AuthenticatorAction" jndi-name="java:app/jboss-seam-booking. you may see javax.booking.xml file.jar/AuthenticatorAction java:app/jboss-seam-booking.ejb3.Authenticator java:module/AuthenticatorAction!org.as.6 How to debug and resolve Seam 2 JNDI errors When you migrate a Seam 2 application. First.naming.example.jar/AuthenticatorAction" /> 4.example.deployment.Authe java:app/jboss-seam-booking.seam.138 INFO [org. find the JNDI binding INFO messages that are printed in the server log when the application is deployed. you can modify the application's components.jboss.booking. Next.xml file: <component class="org. For each JNDI binding INFO message in the log. you will need to replace the existing core-init element as follows: <!-.Authenticator java:global/jboss-seam-booking/jboss-seam-booking.naming.

you might run into ClassNotFoundExceptions or ClassCastExceptions when you migrate your application. profiles=java5.xml file.2. jbossas7 4. see details at the Spring applications development and migration guide. Uncomment scan and reports in the properties file. Unzip the file into the directory of your choice. Install Tattletale 1.Beta2 or newer from http://sourceforge.properties file by adding jbossas7 to the "profiles" property. To resolve these dependencies.WildFly 8 4.net/projects/jboss/files/JBoss%20Tattletale/. Modify the TATTLETALE_HOME/jboss-tattletale.Beta2 or later contains additional support to help with the new JBoss Modules class loading used in WildFly. java6. you will need to find the JARs that contain the classes specified by the exceptions. ee6.1 Use Tattletale to find application dependencies Due to the modular class loading changes.0.0.23.23 Tools That Can Assist with Migration 4. JBoss Community Documentation Page 80 of 617 .22 Migrating Spring applications For information on how to migrate Spring applications. Download Tattletale version 1.2. 2. Tattletale is an excellent tool that recursively scans your application and provides detailed reports about its contents. 3. Tattletale's "jbossas7" report can be used to to automatically identify and specify dependent module names in your application's jboss-deployment-structure. 4. Tattletale 1.

The jboss-deployment-structure. then creates and writes an XML snippet in the appropriate format that can be copied and pasted under the correct subsystem in the server configuration file. Click on the ARCHIVE_NAME link to view details about the archive. The IronJacamar 1. 1.xml.2 IronJacamar Datasource and Resource Adapter Migration Tool Summary In previous versions of the application server.WildFly 8 Create and review the Tattletale report 1.1 distribution contains a migration tool that can be used to convert the datasource and resource adapter configuration files from previous releases into the configuration format expected by the WildFly server.ear output-results/ 2.0. Create the Tattletale report by issuing the command: java -jar TATTLETALE_HOME/tattletale. Tattletale will only find dependencies on the application classes.Beta1/tattletale. datasources and resource adapters were configured and deployed using a file with a suffix of *-ds. 2. you will need to look at the "Depends On" report. such as its location. In a browser. It will not find dependencies that may be required by classes your application calls or by classes in other JARs included under your application's WEB-INF/lib directory. Click on this link to see how to define the deployment dependency module information for this archive.2.jar applications/jboss-seam-booking.23. open the OUTPUT_DIRECTORY/index. The column on the left lists the archives used by the application.xml link in the column on the right shows how to specify the module dependency for the archive in the left column.jar APPLICATION_ARCHIVE OUTPUT_DIRECTORY For example: java -jar ~/tattletale-1. The tool parses the source configuration file from the previous release. and classes it contains. To identify external dependencies. manifest information.html file and click on "JBoss A7" under the "Reports" section. JBoss Community Documentation Page 81 of 617 . 4.

1 from here: http://www. you need to copy the XML snippet into the standalone/configuration/standalone. 2. type: converter -ds FULLY_QUALIFIED_SOURCE_FILE_NAME FULLY_QUALIFIED_TARGET_FILE_NAME 3. 2.bat The tool will do a best effort to convert all old attributes and elements to the new format. The tool generates the datasources and datasource element.xml file. If you are running in domain mode. we will need to make a few changes to the resulting XML.x: JBoss Community Documentation Page 82 of 617 . Use the IronJacamar Migration Tool to convert a datasource configuration file.sh 2. Copy the XML snippet from the target file into the server configuration file under the subsystem xmlns="urn:jboss:domain:datasources:1. In the following examples. Here is an example of the datasource configuration file for the Seam Booking example that shipped with EAP 5.org/ironjacamar/downloads/ . Windows batch file: IRONJACAMAR_HOME/doc/as/converter.jboss. 2. Linux script: IRONJACAMAR_HOME/doc/as/converter. consult this documentation for additional information. Please. 3. 1. It will be necessary to make additional changes to the generated file. you need to copy the XML snippet into the domain/configuration/domain. you need only copy the datasource element into the configuration file. The converter script can be found in the IRONJACAMAR distribution in the following locations: 1./converter. Open a terminal or command prompt and CD to the IRONJACAMAR_HOME/docs/as/ directory. 1.0" datasources element. For Linux. Unzip the file into a directory of your choice.xml file. If you are running in standalone mode.sh -ds FULLY_QUALIFIED_SOURCE_FILE_NAME FULLY_QUALIFIED_TARGET_FILE_NAME For Windows. If you have existing datasources. run the converter script by typing the following command in the terminal: .WildFly 8 Download and install IronJacamar 1. Download IronJacamar 1.

--> <drivers> <driver name="h2" module="com.hsqldb.JdbcDataSource</xa-datasource-class> </driver> </drivers> </datasources> </subsystem> JBoss Community Documentation Page 83 of 617 . The preferred way to define the driver class is using a drivers element.h2"> <xa-datasource-class>org.0"> <datasources> <datasource enabled="true" jndi-name="java:jboss/datasources/bookingDatasource" jta="true" pool-name="bookingDatasource" use-ccm="true" use-java-context="true"> <connection-url>jdbc:hsqldb:.0" encoding="UTF-8"?> <datasources> <local-tx-datasource> <jndi-name>bookingDatasource</jndi-name> <connection-url>jdbc:hsqldb:.The following drivers element was not in the generated XML snippet. -<driver-class>org.hsqldb.We commented out the following driver-class element since it is not the preferred way to define this.jdbcx.h2database.jdbcDriver</driver-class> <user-name>sa</user-name> <password></password> </local-tx-datasource> </datasources> The generated file will contain a driver-class element.</connection-url> <!-.</connection-url> <driver-class>org.h2.jdbcDriver</driver-class>--> <transaction-isolation>TRANSACTION_NONE</transaction-isolation> <pool> <prefill>false</prefill> <use-strict-min>false</use-strict-min> <flush-strategy>FailingConnectionOnly</flush-strategy> </pool> <security> <user-name>sa</user-name> <password/> </security> <validation> <validate-on-match>false</validate-on-match> <background-validation>false</background-validation> <use-fast-fail>false</use-fast-fail> </validation> <timeout/> <statement> <track-statements>false</track-statements> </statement> </datasource> <!-.WildFly 8 <?xml version="1. Here is the converted XML with the driver-class and drivers modifications as configured in the WildFly configuration file: <subsystem xmlns="urn:jboss:domain:datasources:1. We added this manually.

For Linux./converter. 1. 1. If you are running in domain mode.xml file. If you have existing resource-adapters. Here is an example of the mttestadapter-ds.: JBoss Community Documentation Page 84 of 617 .x TestSuite.xml resource-adapter configuration file from the EAP-5.0" element. Copy the XML snippet from the target file into the server configuration file under the subsystem xmlns="urn:jboss:domain:resource-adapters:1. 2. If you are running in standalone mode. you need to copy the XML snippet into the standalone/configuration/standalone. run the converter script by typing the following command in the terminal: . type: .sh -ra FULLY_QUALIFIED_SOURCE_FILE_NAME FULLY_QUALIFIED_TARGET_FILE_NAME For Windows. you need to copy the XML snippet into the domain/configuration/domain.sh -ra FULLY_QUALIFIED_SOURCE_FILE_NAME FULLY_QUALIFIED_TARGET_FILE_NAME 3. you need to copy only the resource-adapter element into the configuration file.WildFly 8 Use the IronJacamar Migration Tool to convert a resource adapter configuration file. Open a terminal or command prompt and CD to the IRONJACAMAR_HOME/docs/as/ directory. The tool generates the resource-adapters and resource-adapter element. 2./converter.xml file.

Boolean">false</config-property> <config-property name="DoubleProperty" type="java.5</config-property> <config-property name="UrlProperty" type="java.lang.org</config-property> <config-property name="sleepInStart" type="long">200</config-property> <config-property name="sleepInStop" type="long">200</config-property> </tx-connection-factory> </connection-factories> You will need to replace the class-name attribute "FIXME_MCF_CLASS_NAME" in the generated XML snippet with the class name of the managed connection factory.resource.ConnectionManager setup for jboss test adapter --> <!-.jboss.lang.test.Integer">2</config-property> <config-property name="BooleanProperty" type="java.URL">http://www.lang.jca.jboss.==================================================================== --> <connection-factories> <tx-connection-factory> <jndi-name>JBossTestCF</jndi-name> <xa-transaction/> <rar-name>jbosstestadapter.TestManagedConnectionFactory".lang.5</config-property> <config-property name="UrlProperty" type="java.5</config-property> <config-property name="UrlProperty" type="java.net.Build jmx-api (build/build. Here is the server configuration file with the newly generated and edited configuration data: JBoss Community Documentation Page 85 of 617 .lang.Integer">2</config-property> <config-property name="BooleanProperty" type="java.URL">http://www.resource. "org.net.Boolean">false</config-property> <config-property name="DoubleProperty" type="java.lang.jboss.cci.Boolean">false</config-property> <config-property name="DoubleProperty" type="java.lang.Double">5.sh all) and view for config documentation --> <!-.net.rar</rar-name> <connection-definition>javax.org</config-property> <config-property name="sleepInStart" type="long">200</config-property> <config-property name="sleepInStop" type="long">200</config-property> </tx-connection-factory> <tx-connection-factory> <jndi-name>JBossTestCF2</jndi-name> <xa-transaction/> <rar-name>jbosstestadapter.rar</rar-name> <connection-definition>javax.==================================================================== --> <!-.Double">5.lang.org</config-property> <config-property name="sleepInStart" type="long">200</config-property> <config-property name="sleepInStop" type="long">200</config-property> </tx-connection-factory> <tx-connection-factory> <jndi-name>JBossTestCFByTx</jndi-name> <xa-transaction/> <track-connection-by-tx>true</track-connection-by-tx> <rar-name>jbosstestadapter.Double">5.jboss.rar</rar-name> <connection-definition>javax.ConnectionFactory</connection-definition> <config-property name="IntegerProperty" type="java.Integer">2</config-property> <config-property name="BooleanProperty" type="java.lang.ConnectionFactory</connection-definition> <config-property name="IntegerProperty" type="java.cci. in this case.0" encoding="UTF-8"?> <!-.ConnectionFactory</connection-definition> <config-property name="IntegerProperty" type="java.adapter.resource.URL">http://www.WildFly 8 <?xml version="1.cci.

jca.5</config-property> <pool> <prefill>false</prefill> <use-strict-min>false</use-strict-min> <flush-strategy>FailingConnectionOnly</flush-strategy> </pool> <security> <application/> </security> <timeout/> <validation> <background-validation>false</background-validation> <use-fast-fail>false</use-fast-fail> </validation> </connection-definition> </connection-definitions> </resource-adapter> <resource-adapter> <archive>jbosstestadapter.We replaced the following "FIXME_MCF_CLASS_NAME" class-name value with the correct class name <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true" jndi-name="java:jboss/JBossTestCF2" pool-name="JBossTestCF2" use-ccm="true" use-java-context="true"> --> <connection-definition class-name="org.adapter.We replaced the following "FIXME_MCF_CLASS_NAME" class-name value with the correct class name <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true" jndi-name="java:jboss/JBossTestCF" pool-name="JBossTestCF" use-ccm="true" use-java-context="true"> --> <connection-definition class-name="org.5</config-property> <pool> <prefill>false</prefill> JBoss Community Documentation Page 86 of 617 .jca.TestManagedConnectionFactory" enabled="true" jndi-name="java:jboss/JBossTestCF" pool-name="JBossTestCF" use-ccm="true" use-java-context="true"> <config-property name="IntegerProperty">2</config-property> <config-property name="sleepInStart">200</config-property> <config-property name="sleepInStop">200</config-property> <config-property name="BooleanProperty">false</config-property> <config-property name="UrlProperty">http://www.org</config-property> <config-property name="DoubleProperty">5.WildFly 8 <subsystem xmlns="urn:jboss:domain:resource-adapters:1.test.adapter.jboss.rar</archive> <transaction-support>XATransaction</transaction-support> <connection-definitions> <!-.org</config-property> <config-property name="DoubleProperty">5.test.rar</archive> <transaction-support>XATransaction</transaction-support> <connection-definitions> <!-.jboss.0"> <resource-adapters> <resource-adapter> <archive>jbosstestadapter.TestManagedConnectionFactory" enabled="true" jndi-name="java:jboss/JBossTestCF2" pool-name="JBossTestCF2" use-ccm="true" use-java-context="true"> <config-property name="IntegerProperty">2</config-property> <config-property name="sleepInStart">200</config-property> <config-property name="sleepInStop">200</config-property> <config-property name="BooleanProperty">false</config-property> <config-property name="UrlProperty">http://www.jboss.jboss.

We replaced the following "FIXME_MCF_CLASS_NAME" class-name value with the correct class name <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true" jndi-name="java:jboss/JBossTestCFByTx" pool-name="JBossTestCFByTx" use-ccm="true" use-java-context="true"> --> <connection-definition class-name="org.jboss. go to IronJacamar Migration Tool .jboss. JBoss Community Documentation Page 87 of 617 .5</config-property> <pool> <prefill>false</prefill> <use-strict-min>false</use-strict-min> <flush-strategy>FailingConnectionOnly</flush-strategy> </pool> <security> <application/> </security> <timeout/> <validation> <background-validation>false</background-validation> <use-fast-fail>false</use-fast-fail> </validation> </connection-definition> </connection-definitions> </resource-adapter> </resource-adapters></subsystem> For more information about this migration tool.org</config-property> <config-property name="DoubleProperty">5.adapter.jca.TestManagedConnectionFactory" enabled="true" jndi-name="java:jboss/JBossTestCFByTx" pool-name="JBossTestCFByTx" use-ccm="true" use-java-context="true"> <config-property name="IntegerProperty">2</config-property> <config-property name="sleepInStart">200</config-property> <config-property name="sleepInStop">200</config-property> <config-property name="BooleanProperty">false</config-property> <config-property name="UrlProperty">http://www.rar</archive> <transaction-support>XATransaction</transaction-support> <connection-definitions> <!-.WildFly 8 <use-strict-min>false</use-strict-min> <flush-strategy>FailingConnectionOnly</flush-strategy> </pool> <security> <application/> </security> <timeout/> <validation> <background-validation>false</background-validation> <use-fast-fail>false</use-fast-fail> </validation> </connection-definition> </connection-definitions> </resource-adapter> <resource-adapter> <archive>jbosstestadapter.test.

you can refer to the javadocs of the EJB client project at http://docs. As a first step. we would like the users to know that we have introduced a new EJB client API.org/ejbclient/.1 Deploying your EJBs on the server side: Users who already have EJBs deployed on the server side can just skip to the next section. This client API isn't based on JNDI.jboss. int subtract(int a. } JBoss Community Documentation Page 88 of 617 .remote.quickstarts.WildFly 8 5 EJB invocations from a remote standalone client using JNDI This chapter explains how to invoke EJBs from a remote client by using the JNDI API to first lookup the bean proxy and then invoke on that proxy. So let's get started: 5. int b).stateless. In this document. In this example.jboss. Here's the code: package org. For now. /** * @author Jaikiran Pai */ public interface RemoteCalculator { int add(int a. So remote clients need not rely on JNDI API to invoke on EJBs. do remember to take a look at Remote EJB invocations via JNDI EJB client API or remote-naming project Before getting into the details. A separate document covering the EJB remote client API will be made available. After you have read this article. we'll just concentrate on the traditional JNDI based invocation on EJBs. then you'll have to expose atleast one remote view for that bean. let's consider a simple Calculator stateless bean which exposes a RemoteCalculator remote business interface. We'll also have a simple stateful CounterBean which exposes a RemoteCounter remote business interface. int b). which is a WildFly-specific API and allows invocation on remote EJBs.as. you'll have to deploy your application containing the EJBs on the AS7 server. If you want those EJBs to be remotely invocable.ejb.

ejb.remote.ejb.jboss.class) public class CalculatorBean implements RemoteCalculator { @Override public int add(int a.stateful. void decrement().quickstarts. import javax.Stateless. } } package org. /** * @author Jaikiran Pai */ public interface RemoteCounter { void increment().as.stateless. import javax.b. int getCount(). int b) { return a + b.ejb. int b) { return a .ejb.Remote.WildFly 8 package org. } @Override public int subtract(int a.as.remote. /** * @author Jaikiran Pai */ @Stateless @Remote(RemoteCalculator.jboss. } JBoss Community Documentation Page 89 of 617 .quickstarts.

count++. 5. In this chapter we will concentrate on the JNDI lookup and invocation and will leave the EJB client API for a separate chapter. } @Override public int getCount() { return this.WildFly 8 package org.quickstarts.class) public class CounterBean implements RemoteCounter { private int count = 0. import javax.stateful. So let's take a look at what the client code looks like for looking up the JNDI proxy and invoking on it. JBoss Community Documentation Page 90 of 617 .count--.jar" and deploy it to the server. Here's the entire client code which invokes on a stateless bean: package org.Context.jboss.ejb. you can either choose to use the WildFly 8 specific EJB client API to do the invocation or use JNDI to lookup a proxy for your bean and invoke on that returned proxy.as. } @Override public void decrement() { this.as.Remote.ejb.client. @Override public void increment() { this. import javax.2 Writing a remote client application for accessing and invoking the EJBs deployed on the server The next step is to write an application which will invoke the EJBs that you deployed on the server.quickstarts.InitialContext.naming.Stateful.count.remote. import javax. In WildFly.ejb.remote.jboss. Make sure that your deployment has been processed successfully and there aren't any errors. } } Let's package this in a jar (how you package it in a jar is out of scope of this chapter) named "jboss-as-ejb-remote-app.naming. /** * @author Jaikiran Pai */ @Stateful @Remote(RemoteCounter. import javax.ejb.

remote.out. // Invoke a stateful bean invokeStatefulBean().println("Adding " + a + " and " + b + " via the remote stateless calculator deployed on the server").jboss.sasl. int sum = statelessRemoteCalculator.subtract(num1.stateful.RemoteCounter.println("Remote calculator returned difference = " + difference).ejb.println("Subtracting " + num2 + " from " + num1 + " via the remote stateless calculator deployed on the server").out.out.println("Remote calculator returned sum = " + sum).ejb.jboss.remote.WildFly 8 import javax.quickstarts. int difference = statelessRemoteCalculator.JBossSaslProvider. /** * A sample program which acts a remote client for a EJB deployed on AS7 server.as. System.quickstarts. if (difference != num1 .println("Obtained a remote stateless calculator for invocation").jboss.naming. System.security. * This program shows how to lookup stateful and stateless beans via JNDI and then invoke on them * * @author Jaikiran Pai */ public class RemoteEJBClient { public static void main(String[] args) throws Exception { // Invoke a stateless bean invokeStatelessBean().as.CounterBean.Hashtable. System.stateless. org. int num2 = 2332. if (sum != a + b) { throw new RuntimeException("Remote stateless calculator returned an incorrect sum " + sum + " .util.as.quickstarts.out.add(a.stateful. org.as.remote.expected sum was " + (a + b)). import import import import import org. } // try one more invocation. org. import java.num2) { throw new RuntimeException("Remote stateless calculator returned an incorrect difference " + difference + " .Security.quickstarts. this time for subtraction int num1 = 3434.remote.NamingException. System.num2)).expected difference was " + (num1 .out. num2).stateless.jboss. } JBoss Community Documentation Page 91 of 617 . int b = 340.CalculatorBean. // invoke on the remote calculator int a = 204.jboss. b).RemoteCalculator.ejb. System.ejb. import java. } /** * Looks up a stateless bean and invokes on it * * @throws NamingException */ private static void invokeStatelessBean() throws NamingException { // Let's lookup the remote stateless calculator final RemoteCalculator statelessRemoteCalculator = lookupRemoteStatelessCalculator(). org.

"org. jndiProperties. i--) { System.xml of the // EJB deployment on the server.println("Obtained a remote stateful counter for invocation"). // This is the module name of the deployed EJBs on the server. // AS7 allows each deployment to have an (optional) distinct name.URL_PKG_PREFIXES. for (int i = 0. This is typically the ear name // without the .naming").WildFly 8 } /** * Looks up a stateful bean and invokes on it * * @throws NamingException */ private static void invokeStatefulBean() throws NamingException { // Let's lookup the remote stateful counter final RemoteCounter statefulRemoteCounter = lookupRemoteStatefulCounter().jar suffix.decrement().getCount()).println("Decrementing counter"). // Since we haven't deployed the application as a .ear suffix. // invoke on the remote counter bean final int NUM_TIMES = 20. System. we have deployed the EJBs in a jboss-as-ejb-remote-app.client.println("Incrementing counter"). but can be overridden via the ejb-jar. the application name could be overridden in the application.println("Count after increment is " + statefulRemoteCounter. System. } // now decrementing System.out. so the module name is // jboss-as-ejb-remote-app final String moduleName = "jboss-as-ejb-remote-app".ejb.out. final Context context = new InitialContext(jndiProperties). // The app name is the application name of the deployed EJBs.println("Counter will now be incremented " + NUM_TIMES + " times"). System.out.out. without the . statefulRemoteCounter. for (int i = NUM_TIMES. However.ear. the app name for us will be an empty string final String appName = "".println("Counter will now be decremented " + NUM_TIMES + " times").getCount()).out. so this is an empty string final String distinctName = "".put(Context. i < NUM_TIMES.jboss.increment(). System.out.out. We haven't specified a distinct name for // our EJB deployment. // The EJB name which by default is the simple class name of the bean implementation JBoss Community Documentation Page 92 of 617 .xml // In this example.println("Count after decrement is " + statefulRemoteCounter. i++) { System. } } /** * Looks up and returns the proxy to remote stateless calculator bean * * @return * @throws NamingException */ private static RemoteCalculator lookupRemoteStatelessCalculator() throws NamingException { final Hashtable jndiProperties = new Hashtable(). statefulRemoteCounter. This is typically the jar name of the // EJB deployment. i > 0.jar.

// AS7 allows each deployment to have an (optional) distinct name.getName().xml // In this example.ejb.WildFly 8 class final String beanName = CalculatorBean. the application name could be overridden in the application. jndiProperties. so this is an empty string final String distinctName = "".URL_PKG_PREFIXES.lookup("ejb:" + appName + "/" + moduleName + "/" + distinctName + "/" + beanName + "!" + viewClassName).getSimpleName().jar suffix. // The EJB name which by default is the simple class name of the bean implementation class final String beanName = CounterBean.client. so the module name is // jboss-as-ejb-remote-app final String moduleName = "jboss-as-ejb-remote-app".xml of the // EJB deployment on the server. without the .getName(). However.jar.class. the app name for us will be an empty string final String appName = "". we have deployed the EJBs in a jboss-as-ejb-remote-app. but can be overridden via the ejb-jar. This is typically the jar name of the // EJB deployment.class. } /** * Looks up and returns the proxy to remote stateful counter bean * * @return * @throws NamingException */ private static RemoteCounter lookupRemoteStatefulCounter() throws NamingException { final Hashtable jndiProperties = new Hashtable().ear.class. // let's do the lookup (notice the ?stateful string as the last part of the jndi name for stateful bean lookup) return (RemoteCounter) context. } } The entire server side and client side code is hosted at the github repo here ejb-remote JBoss Community Documentation Page 93 of 617 .jboss. // the remote view fully qualified class name final String viewClassName = RemoteCalculator. // The app name is the application name of the deployed EJBs. "org.put(Context.getSimpleName(). // This is the module name of the deployed EJBs on the server. // the remote view fully qualified class name final String viewClassName = RemoteCounter. // Since we haven't deployed the application as a .class. // let's do the lookup return (RemoteCalculator) context.ear suffix. We haven't specified a distinct name for // our EJB deployment.lookup("ejb:" + appName + "/" + moduleName + "/" + distinctName + "/" + beanName + "!" + viewClassName + "?stateful"). This is typically the ear name // without the . final Context context = new InitialContext(jndiProperties).naming").

jar suffix) that you have deployed on the server and the contains your EJBs. EJBs can also be deployed in a .WildFly 8 The code has some comments which will help you understand each of those lines. for distinct-name bean-name : This is the name of the bean for which you are doing the lookup. The bean name part cannot be an empty string in the JNDI name.xml of your deployment. As a first step in the client code. we'll do a lookup of the EJB using a JNDI name.jar (like we did in step 1). by setting it in the ejb-jar. If the deployment uses uses such an override then the app-name used in the JNDI name should match that name. JBoss Community Documentation Page 94 of 617 . to a name of your choice by setting it in the application. If the deployment uses such an override then the module-name used in the JNDI name should match that name. while doing the lookup.xml or via annotations. but can be overriden through either ejb-jar.ear suffix) that you have deployed on the server and contains your EJBs. The bean name is typically the unqualified classname of the bean implementation class. Java EE 6 allows you to override the application name. In such cases where the deployment isn't an .e. doesn't change) for doing EJB lookups.xml.war then the module name is the . fully-qualified-classname-of-the-remote-interface : This is the fully qualified class name of the interface for which you are doing the lookup. The fully qualified class name part cannot be an empty string in the JNDI name. for remote access to EJBs. If a deployment doesn't use distinct-name then. The rest of the parts in the jndi name are as follows: app-name : This is the name of the . More about the purpose and usage of this will be explained in a separate chapter.ear file.ear (without the . In AS7. then the app-name must be an empty string. Module name part cannot be an empty string in the JNDI name distinct-name : This is a WildFly-specific name which can be optionally assigned to the deployments that are deployed on the server. The interface should be one of the remote interfaces exposed by the bean on the server.xml/web. But we'll explain here in more detail what the code does.war name (without the . module-name : This is the name of the .war or a plain . If the EJBs are deployed in a .war suffix). Java EE 6 allows you to override the module name. you use the ejb: namespace with the following syntax: For stateless beans: ejb:<app-name>/<module-name>/<distinct-name>/<bean-name>!<fully-qualified-classname-of-the-remote-interface> For stateful beans: ejb:<app-name>/<module-name>/<distinct-name>/<bean-name>!<fully-qualified-classname-of-the-remote-interface>?s The ejb: namespace identifies it as a EJB lookup and is a constant (i.jar (without the . use an empty string in the JNDI name.

stateless.quickstarts.stateless.naming So at this point. a new session gets created on JNDI lookup and the EJB client API implementation doesn't contact the server during the JNDI lookup to know what kind of a bean the JNDI name represents (we'll come to this in a while). The Context.jar and which exposes the org.pkgs=org.remote.jboss. "org. which (atleast) contains the following property: java.jboss.remote. for your deployed EJBs. final Context context = new InitialContext(jndiProperties).jar (without any ear) and since we are looking up the org.URL_PKG_PREFIXES is set to org.RemoteCalculator That's what the lookupRemoteStatelessCalculator() method in the above client code uses.client.put(Context.url.jboss.as. You can either pass these properties to the constructor of the InitialContext class or have a jndi.ejb.remote.naming"). our JNDI name will be: ejb:/jboss-as-ejb-remote-app//CalculatorBean!org.RemoteCounter.RemoteCalculator remote interface. For the stateful EJB named CounterBean which is deployed in hte same jboss-as-ejb-remote-app.as.client.stateful.jboss.jboss.stateful. The answer is in AS7.quickstarts.ejb. Here we are creating a JNDI InitialContext object by passing it some JNDI properties.URL_PKG_PREFIXES.ejb.naming. You can now do the lookup and the appropriate proxy which will be castable to the remote interface that you used as the fully qualified class name in the JNDI name.ejb.client.as. the proxies returned via JNDI name lookup for ejb: namespace do not connect to the server unless an invocation on those proxies is done.properites file in the classpath of the client application. So the JNDI name itself is expected to indicate that the client is looking up a stateful bean. JBoss Community Documentation Page 95 of 617 .naming. The "org. we have setup the InitialContext and also have the JNDI name ready to do the lookup. how the JNDI implementation knew which server address to look. Since our stateless EJB named CalculatorBean is deployed in a jboss-as-ejb-remote-app.remote.client. will be returned. let's take a look at the following piece of code in the lookupRemoteStatelessCalculator(): final Hashtable jndiProperties = new Hashtable().RemoteCounter?stateful That's what the lookupRemoteStatefulCounter() method in the above client code uses.ejb. let's see our code and check what JNDI name it uses. Now that we know the syntax.jboss.factory.as. the JNDI name will be: ejb:/jboss-as-ejb-remote-app//CounterBean!org.WildFly 8 For stateful beans. so that an appropriate session can be created.ejb.naming" has a URLContextFactory implementation which will be used by the JNDI APIs to parse and return an object for ejb: namespace lookups.quickstarts. This is because for stateful beans. Now that we know of the JNDI name. Some of you might be wondering. the JNDI name expects an additional "?stateful" to be appended after the fully qualified interface name part. This is necessary because we should let the JNDI API know what handles the ejb: namespace that we use in our JNDI names for lookup.jboss.ejb.quickstarts.ejb. jndiProperties.jboss.

int sum = statelessRemoteCalculator. System.30.out. So let's now get to the important part of setting up the EJB client context properties. For example. let's see how we can setup a client context with 1 EJB receiver which can connect to 10. int b = 340. Now that we know what a EJB client context is and what a EJB receiver is.println("Adding " + a + " and " + b + " via the remote stateless calculator deployed on the server"). // invoke on the remote calculator int a = 204.properties can contain the following properties: JBoss Community Documentation Page 96 of 617 . b). then you can setup a EJB receiver which knows its target address is 10. System. This is a WildFly-specific API.40 IP address which has its remoting port opened at 4447 and if that's the server on which you deployed that CalculatorBean.20.20..) method of the bean.30.3 Setting up EJB client context properties A EJB client context is a context which contains contextual information for carrying out remote invocations on EJBs.. The EJB client context can be associated with multiple EJB receivers.40:4447. if you have a AS7 server at 10. The jboss-ejb-client.println("Obtained a remote stateless calculator for invocation"). For example. That EJB client context will then be used (internally) by the JNDI implementation to handle invocations on the bean proxy.out.properties file in the classpath of the application. The client will have to place a jboss-ejb-client. Each EJB receiver is capable of handling invocations on different EJBs.WildFly 8 Now let's get to the point where we invoke on this returned proxy: // Let's lookup the remote stateless calculator final RemoteCalculator statelessRemoteCalculator = lookupRemoteStatelessCalculator(). Each such EJB receiver knows about what set of EJBs it can handle and each of the EJB receiver knows which server target to use for handling the invocations on the bean. Such an EJB receiver will be capable enough to communicate to the server via the JBoss specific EJB remote client protocol (details of which will be explained in-depth in a separate chapter). It's at this point that the JNDI implementation (which is backed by the EJB client API) needs to know the server details. We can see here that the proxy returned after the lookup is used to invoke the add(. 5. whereas a EJB receiver named "Blah" might be able to handle invocation on a bean identified by app-B/module-B/distinctName-B/BeanB!RemoteBean.40 IP address at port 4447.20.add(a. an EJB receiver "Foo" might be able to handle invocation on a bean identified by app-A/module-A/distinctinctName-A/Bar!RemoteBar.30.

There can be more than one connections that are configured.default.xnio.default.connectionprovider.> properties: remote.<. For example: JBoss Community Documentation Page 97 of 617 .username=appuser remote.. The connection names are just logical and are used grouping together the connection configuration properties later on in the properties file. it will default to "config-based-ejb-client-endpoint" name.create. just append it to the "remote.Options. Similarly other properties can be passed too.connection..create.create.org.name property represents the name that will be used to create the client side of the enpdoint. The endpoint.options.org.Options.connectionprovider. Next is the remote.connections" property uses a comma separated value of connection "names"." prefix Next we'll see: remote.password=apppassword The above properties file is just an example. We mentioned earlier that the EJB receivers will communicate with the server for EJB invocations.name property.xnio.SASL_POLICY_NOANONYMOUS=false remote.30.options.default.SSL_ENABLED" property value as false.WildFly 8 endpoint. In this example we use the "remote.create. they use JBoss Remoting project to carry out the communication.options.options. The "remote.40 remote.create.connection.Options..xnio.connectionprovider.create.name property is optional and if not specified in the jboss-ejb-client. Internally.connect. That property will then be used during the connection provider creation." property prefix can be used to pass the options that will be used while create the connection provider which will handle the "remote:" protocol." property prefix to pass the "org.connections=default remote. The example above sets up a single remote connection named "default".connectionprovider.options.connection.org.connection. The endpoint.connection. The actual file that was used for this sample program is available here for reference jboss-ejb-client.Options.options. First the endpoint.default.default.connections=default This is where you define the connections that you want to setup for communication with the remote server.properties file.20.name=client-endpoint remote.properties We'll see what each of it means.connectionprovider.options.host=10.connectionprovider.xnio.SSL_ENABLED=false The "remote.port = 8080 remote.SSL_ENABLED=false remote.

default.username=appuser remote.options.bat).20. that will setup 2 EJB receivers that will be added to the EJB client context.xml or domain. so that's the port we use in our client programs (unless the server is configured for some other http port) remote.host=10." prefix for specifying the connection specific property.<connection-name>.connection. The connection name here is "default" and we are setting the "host" property of that connection to point to 10.connections=one.xnio.connect.30.port = 8080 remote.40 remote.connection. By default WildFly uses 8080 as the remoting port. security-realm is enabled by default.default.org. Each of these connections will be configured with the connection specific properties as follows: remote." property prefix to setup options that will be used during the connection creation.sh (or.password=apppassword The given user/password must be set by using the command bin/add-user. for communicating with the server for remote invocations.SASL_POLICY_NOANONYMOUS=false As you can see we are using the "remote. two Here we are listing 2 connections named "one" and "two". The EJB client API uses the http port. The user and password must be set because the security-realm is enabled for the subsystem remoting (see standalone*.connection.<connection-name>. If you do not need the security for remoting you might remove the attribute security-realm in the configuration.Options. Here's an example of setting up multiple connections with different properties for each of those: JBoss Community Documentation Page 98 of 617 .default.20. Ultimately.WildFly 8 remote. each of the connections will map to a EJB receiver. with the http-upgrade functionality.connect. We then use the "remote. So if you have 2 connections.xml) by default.connection. Similarly we set the "port" for that connection to 4447.40.default.connection.30.default.options.connection.connection.

properties file can be setup and placed in the classpath. containing the client context configurations.port=7999 remote.properties.options.connection. It's available at WILDFLY_HOME/bin/client/jboss-client.WildFly 8 remote.4 Using a different file for setting up EJB client context The EJB client code will by default look for jboss-ejb-client.SASL_POLICY_NOANONYMOUS=false As you can see we setup 2 connections "one" and "two" which both point to "localhost" as the "host" but different ports. If you are using Maven to build the client application.xnio.org. then please follow the instructions in the WILDFLY_HOME/bin/client/README.connection.connection.one.path" system property which points to a properties file on your filesystem.client. JBoss Community Documentation Page 99 of 617 . 5.two. So that's how the jboss-ejb-client.connectionprovider.connection.options.org.Options.host=localhost remote.properties" 5. Place this jar in the classpath of your client application.client.5 Setting up the client classpath with the jars that are required to run the client application A jboss-client jar is shipped in the distribution.xnio.connect.ejb.one.two. An example for that would be "-Djboss. Each of these connections will internally be used to create the EJB receivers in the EJB client context.one.SASL_POLICY_NOANONYMOUS=false remote. two remote.port=6999 remote.create.host=localhost remote.options.org.Options.path=/home/me/my-client/custom-jboss-ejb-client.connection.jar.file.connect. However.txt to add this jar as a Maven dependency.connection. you can specify a different file of your choice by setting the "jboss.ejb.Options.two.SSL_ENABLED=false remote.properties.xnio.properties in the classpath.file.connections=one.

You'll also need to have your application's bean interface jars and other jars that are required by your application.naming. To summarize: On the server side you need to deploy EJBs which expose the remote views.properties in its classpath to setup the server connection information Either has a jndi. in the client classpath JBoss Community Documentation Page 100 of 617 . On the client side you need a client program which: Has a jboss-ejb-client.WildFly 8 5.factory. we saw what it takes to invoke a EJB from a remote client.pkgs property or passes that as a property to the InitialContext constructor Setup the client classpath to include the jboss-client jar that's required for remote invocation of the EJBs.6 Summary In the above examples. The location of the jar is mentioned above.url.properties to specify the java.

ear. This is different from invoking the EJBs from a remote standalone client Let's call the server. .ear | |---. Note that this chapter deals with the case where the bean is deployed on the "Destination Server" but not on the "Client Server".<org. Here's how it would look like: myapp.myapp.myejb.jar which is within a myapp.ear. You can deploy the EJBs in any standard way (. from which the invocation happens to the EJB. 6.1 Application packaging In this example.ejb. we'll consider a EJB which is packaged in a myejb.*> // EJB classes Note that packaging itself isn't really important in the context of this article.war or . JBoss Community Documentation Page 101 of 617 .jar | | | |---.WildFly 8 6 EJB invocations from a remote server The purpose of this chapter is to demonstrate how to lookup and invoke on EJBs deployed on an WildFly server instance from another WildFly server instance.jar). as "Client Server" and the server on which the bean is deployed as the "Destination Server".

ejb.myapp. JBoss Community Documentation Page 102 of 617 .ejb. @Stateless @Remote (Greeter. What this means is that no communication can happen with an WildFly instance from a remote client (irrespective of whether it is a standalone client or another server instance) without passing the appropriate credentials.Remote.2 Beans In our example. import javax. Remember that in this example. have a pleasant day!". So in order to allow this communication to happen successfully.ejb. import javax. } } 6. we'll have to configure user credentials which we will be using during this communication.Stateless.class) public class GreeterBean implements Greeter { @Override public String greet(String user) { return "Hello " + user + ".3 Security WildFly 8 is secure by default.myapp. we'll consider a simple stateless session bean which is as follows: package org.WildFly 8 6. } package org. public interface Greeter { String greet(String user).ejb. our "client server" will be communicating with the "destination server". So let's start with the necessary configurations for this.

properties' Added user 'ejb' to file '/jboss-as-7. You do not require the server to be started to add a user using the add-user script.WildFly 8 6.b) Application User (application-users. We create the user using the add-user script that's available in the JBOSS_HOME/bin folder.1.a) Management User (mgmt-users.Final/standalone/configuration/application-users.1.Final/domain/configuration/application-roles.1.sh What type of user do you wish to add? &nbsp.4 Configuring a user on the "Destination Server" As a first step we'll configure a user on the destination server who will be allowed to access the destination server. \]: About to add user 'ejb' for realm 'ApplicationRealm' Is this correct yes/no? yes Added user 'ejb' to file '/jboss-as-7.1. Realm (ApplicationRealm) : Username : ejb Password : Re-enter Password : What roles do you want this user to belong to? (Please enter a comma separated list. We'll use this user credentials later on in the client server for communicating with this server. Note that you can use any username and password combination you want to. Running the add-user script is an interactive process and you will see questions/output as follows: add-user jpai@jpai-laptop:bin$ ./add-user.1.1.properties) &nbsp. The important bits to remember are the user we have created in this example is ejb and the password is test. or leave blank for none)\[&nbsp.properties' Added user 'ejb' with roles to file '/jboss-as-7.1.Final/domain/configuration/application-users. In this example. JBoss Community Documentation Page 103 of 617 . we'll be configuring a Application User named ejb and with a password test in the ApplicationRealm.properties' As you can see in the output above we have now configured a user on the destination server who'll be allowed to access this server.properties) (a): b Enter the details of the new user to add.Final/standalone/configuration/application-roles.1.properties' Added user 'ejb' with roles to file '/jboss-as-7.

name system property.6 Deploying the application The application (myapp./standalone. over which it can communicate during the EJB invocations. You can do that by passing an appropriate value for -Djboss.node. The " remote-outbound-connection" configuration indicates that a outbound connection will be created to a remote server instance from that server. It's very important to note that if you are starting both the server instances on the same machine. then each of those server instances must have a unique jboss. The process of deploying the application is out of scope of this chapter. we need to let the server know about the "Destination Server"'s EJB remoting connector.name system property to the startup script: .name=<add appropriate value here> 6. JBoss Community Documentation Page 104 of 617 . To do that.xml -Djboss.node.5 Start the "Destination Server" As a next step towards running this example. So let's see how we create these configurations.WildFly 8 6. You can either use the Command Line Interface or the Admin console or any IDE or manually copy it to JBOSS_HOME/standalone/deployments folder (for standalone server).xml configuration. In this example. we'll use the standalone server and use the standalone-full. So far. Just ensure that the application has been deployed successfully. 6. Now let's move to the "Client Server" which acts as the client for the deployed EJBs on the "Destination Server"./standalone.xml Ensure that the server has started without any errors. The startup command will look like: .node. we have built a EJB application and deployed it on the "Destination Server".sh -server-config=standalone-full. we'll have to add a "remote-outbound-connection" to the remoting subsystem on the "Client Server". The "remote-outbound-connection" will be backed by a " outbound-socket-binding" which will point to a remote host and a remote port (of the "Destination Server").7 Configuring the "Client Server" to point to the EJB remoting connector on the "Destination Server" As a first step on the "Client Server".ear in our case) will be deployed to "Destination Server". we'll start the "Destination Server".sh -server-config=standalone-full.

9 Create a security realm on the client server Remember that we need to communicate with a secure destination server.binding.sh -server-config=standalone-full. So for the test password.socket. So our first task here would be to create the base64 encoded version of the password test. That can lead to incorrect encoded versions being generated.port-offset=100 6. I used this online site which generates the base64 encoded string. let's use in the in the security realm that we are going to configure on the "client server". In this example we'll use a security realm which stores a Base64 encoded password and then passes on that credentials when asked for.xml file to add the following in the <management> section Now let's create a "security-realm" for the base64 encoded password.WildFly 8 6. the base64 encoded version is dGVzdA== While generating the base64 encoded string make sure that you don't have any trailing or leading spaces for the original password./standalone. We have copied the entire server installation to a different folder and while starting the "Client Server" we'll use a port-offset (of 100 in this example) to avoid port conflicts: .8 Start the "Client Server" In this example. I'll first shutdown the client server and edit the standlaone-full. You can use any utility which generates you a base64 version for a string. slave domain controller? Now that we have generated that base64 encoded password. Earlier we created a user on the destination server who'll be allowed to communicate with that server. Now on the "client server" we'll create a security-realm which will be used to pass the user information. /core-service=management/security-realm=ejb-security-realm:add() /core-service=management/security-realm=ejb-security-realm/server-identity=secret:add(value=dGVzdA==) JBoss Community Documentation Page 105 of 617 . In order to do that the client server has to pass the user credentials to the destination server. we'll start the "Client Server" on the same machine as the "Destination Server". With new versions the add-user script will show the base64 password if you type 'y' if you've been ask Is this new user going to be used for one AS process to connect to another AS process e. Earlier we created a user named ejb and password test.xml -Djboss.g.

.WildFly 8 Notice that the CLI show the message "process-state" => "reload-required". So that completes the security realm configuration for the client server. the following configuration will be created in the management section: standalone-full. JBoss Community Documentation Page 106 of 617 . <security-realm name="ejb-security-realm"> <server-identities> <secret value="dGVzdA=="/> </server-identities> </security-realm> </security-realms> ... As you can see I have created a security realm named "ejb-security-realm" (you can name it anything) with the base64 encoded password. Now let's move on to the next step.. so you have to restart the server before you can use this change.xml <management> <security-realms> . upon successful invocation of this command.

We'll continue to use the CLI to create this configuration: /subsystem=remoting/remote-outbound-connection=remote-ejb-connection:add(outbound-socket-binding-ref=remote-ej protocol=http-remoting. security-realm=ejb-security-realm. Furthermore.WildFly 8 6. <outbound-socket-binding name="remote-ejb"> <remote-destination host="localhost" port="8080"/> </outbound-socket-binding> </socket-binding-group> 6. we also set the security-realm attribute to point to the security-realm that we created in the previous step. Also notice that we have set the username attribute to use the user name who is allowed to communicate with the destination server.binding. Note that the host information should match the host/IP of the "Destination Server" (in this example we are running on the same machine so we use "localhost") and the port information should match the http-remoting connector port used by the EJB subsystem (by default it's 8080). We'll use the CLI to create this configuration: /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-ejb:add(host=localhos port=8080) The above command will create a outbound-socket-binding named "remote-ejb" (we can name it anything) which points to "localhost" as the host and port 8080 as the destination port.port-offset:0}"> . JBoss Community Documentation Page 107 of 617 . When this command is run successfully. username=ejb) The above command creates a remote-outbound-connection.socket. in the remoting subsystem and uses the previously created "remote-ejb" outbound-socket-binding (notice the outbound-socket-binding-ref in that command) with the http-remoting protocol..10 Create a outbound-socket-binding on the "Client Server" Let's first create a outbound-socket-binding which points the "Destination Server"'s host and port. named "remote-ejb-connection" (we can name it anything). we'll see that the standalone-full.xml (the file which we used to start the server) was updated with the following outbound-socket-binding in the socket-binding-group: <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.11 Create a "remote-outbound-connection" which uses this newly created "outbound-socket-binding" Now let's create a "remote-outbound-connection" which will use the newly created outbound-socket-binding (pointing to the EJB remoting connector of the "Destination Server")..

Now let's run the following two operations to set some default connection creation options for the outbound connection: /subsystem=remoting/remote-outbound-connection=remote-ejb-connection/property=SASL_POLICY_NOANONYMOUS:add(valu /subsystem=remoting/remote-outbound-connection=remote-ejb-connection/property=SSL_ENABLED:add(value=false) Ultimately.1"> . on the client server. that's all we need on the "Client Server"... <outbound-connections> <remote-outbound-connection name="remote-ejb-connection" outbound-socket-binding-ref="remote-ejb" protocol="http-remoting" security-realm="ejb-security-realm" username="ejb"> <properties> <property name="SASL_POLICY_NOANONYMOUS" value="false"/> <property name="SSL_ENABLED" value="false"/> </properties> </remote-outbound-connection> </outbound-connections> </subsystem> From a server configuration point of view. it creates a outbound connection. upon successful invocation of this command. to the remote destination server and sets up the username to the user who allowed to communicate with that destination server and also sets up the security-realm to a pre-configured security-realm capable of passing along the user credentials (in this case the password). JBoss Community Documentation Page 108 of 617 . Our next step is to deploy an application on the "Client Server" which will invoke on the bean deployed on the "Destination Server". the connection creation logic will have the necessary security credentials to pass along and setup a successful secured connection. This way when a connection has to be established from the client server to the destination server. the following configuration will be created in the remoting subsystem: <subsystem xmlns="urn:jboss:domain:remoting:1..WildFly 8 What this step does is.

myapp.jar deployments. Here's how our client application packaging will look like: client-app.xml are explained next.12 Packaging the client application on the "Client Server" Like on the "Destination Server".web.FooServlet> // classes in the web app In the client application we'll use a servlet which invokes on the bean deployed on the "Destination Server". that's not mandatory. we'll use . followed by invocation on the proxy).<org. JBoss Community Documentation Page 109 of 617 .e. If your application is deployed as a top level .WEB-INF/classes | | | | | |---.WildFly 8 6.war deployment.ear | |--. You can even use a .ear).jboss-ejb-client. the same location where you place any web. This jboss-ejb-client. then the jboss-ejb-client.xml is expected to be placed in .xml which is packaged in the META-INF folder of a top level deployment (in this case our client-app. EJB receivers).ear packaging for the client application too.xml file). The code remains the same (JNDI lookup.xml contains the EJB client configurations which will be used during the EJB invocations for finding the appropriate destinations (also known as. We can even invoke the bean on the "Destination Server" from a EJB on the "Client Server".war | | | |--. The important part to notice in this client application is the file jboss-ejb-client. The contents of the jboss-ejb-client.META-INF | | | |--. But like previously mentioned.war or .xml | |--.war/WEB-INF/ folder (i.

WildFly 8 6.xml will look like: <jboss-ejb-client xmlns="urn:jboss:ejb-client:1. 6. Just ensure that the application is deployed successfully.xml The jboss-ejb-client.13 Contents on jboss-ejb-client. This links the EJB client context to use the "remote-ejb-connection" which ultimately points to the EJB remoting connector on the "Destination Server". of this chapter. You can use either the CLI or the admin console or a IDE or deploy manually to JBOSS_HOME/standalone/deployments folder. JBoss Community Documentation Page 110 of 617 . The process of deploying the application is out of scope.0"> <client-context> <ejb-receivers> <remoting-ejb-receiver outbound-connection-ref="remote-ejb-connection"/> </ejb-receivers> </client-context> </jboss-ejb-client> You'll notice that we have configured the EJB client context (for this application) to use a remoting-ejb-receiver which points to our earlier created "remote-outbound-connection" named " remote-ejb-connection".14 Deploy the client application Let's deploy the client application on the "Client Server".

but the code to invoke the bean isn't servlet specific and can be used in other components (like EJB) too. So let's see how it looks like: import javax.. // setup the ejb: namespace URL factory props.WildFly 8 6.Hashtable. JBoss Community Documentation Page 111 of 617 . } } That's it! The above code will invoke on the bean deployed on the "Destination Server" and return the result.InitialContext(props).lookup("ejb:" + "myapp" + "/" + "myejb" + "/" + "" + "/" + "GreeterBean" + "!" + org.myapp.ejb.client.put(Context.class.println("Received greeting: " + greeting).naming").getName()).out.URL_PKG_PREFIXES.naming.jboss. } catch (Exception e) { throw new RuntimeException(e).naming.15 Client code invoking the bean We mentioned that we'll be using a servlet to invoke on the bean.InitialContext. import java. System.util.greet("Tom").jboss. import javax. public void invokeOnBean() { try { final Hashtable props = new Hashtable().org/author/display/AS71/EJB+invocations+from+a+remote+client+using+JNDI final Greeter bean = (Greeter) context.Greeter..Context.ejb. // Lookup the Greeter bean using the ejb: namespace syntax which is explained here https://docs. // create the InitialContext final Context context = new javax. "org. . // invoke on the bean final String greeting = bean.naming.

EJB client API or remote-naming project? JBoss Community Documentation Page 112 of 617 .WildFly 8 7 Remote EJB invocations via JNDI .Which approach to use? Couldn't find a page to include called: Remote EJB invocations via JNDI .

WildFly 8 8 JBoss EJB 3 reference guide This chapter details the extensions that are available when developing Enterprise Java Beans tm on WildFly 8.1 Resource Adapter for Message Driven Beans Each Message Driven Bean must be connected to a resource adapter. For example: @MessageDriven(messageListenerInterface = PostmanPat.rar. 8. 8. The value of the annotation is the name of the deployment unit containing the resource adapter. For example jms-ra. Currently there is no support for configuring the extensions using an implementation specific descriptor file.1.rar") JBoss Community Documentation Page 113 of 617 .class) @ResourceAdapter("ejb3-rar.1 Specification of Resource Adapter using Metadata Annotations The ResourceAdapter annotation is used to specify the resource adapter with which the MDB should connect.

Using this annotation without specifying a run-as role is considered an error. The actual type of the principal is undefined and should not be relied upon.1 Specification of Run-as Principal using Metadata Annotations The RunAsPrincipal annotation is used to specify the run-as principal to use for a given method invocation. 8.2 as Principal Whenever a run-as role is specified for a given method invocation the default anonymous principal is used as the caller principal.1 Specification of Security Domain using Metadata Annotations The SecurityDomain annotation is used to specify the security domain to associate with the EJB.3 Security Domain Each Enterprise Java Bean tm can be associated with a security domain. Only when an EJB is associated with a security domain will authentication and authorization be enforced. This principal can be overridden by specifying a run-as principal.3.2. JBoss Community Documentation Page 114 of 617 .4 Transaction Timeout For any newly started transaction a transaction timeout can be specified in seconds. The value of the annotation specifies the name of the principal to use.WildFly 8 8. 8. For example: @SecurityDomain("other") 8. The value of the annotation is the name of the security domain to be used. For example: @RunAs("admin") @RunAsPrincipal("MyBean") 8.

WildFly 8 When a transaction timeout of 0 is used. For example:@TransactionTimeout(value = 10. then the actual transaction timeout will default to the domain configured default. TODO: add link to tx subsystem Although this is only applicable when using transaction attribute REQUIRED or REQUIRES_NEW the application server will not detect invalid setups. unit = TimeUnit. the timeout will only be applicable if a new transaction is started. It must be a positive integer or 0.1 Specification of Transaction Timeout with Metadata Annotations The TransactionTimeout annotation is used to specify the transaction timeout for a given method. Specifying a granularity lower than SECONDS is considered an error. The value of the annotation is the timeout used in the given unit granularity. Whenever 0 is specified the default domain configured timeout is used. The unit specifies the granularity of the value.SECONDS) JBoss Community Documentation Page 115 of 617 . New Transactions Take care that even when transaction attribute REQUIRED is specified.4. The actual value used is converted to seconds. even when the computed value will result in an even amount of seconds. 8.

The trans-timeout element resides in the urn:trans-timeout namespace and is part of the standard container-transaction element as defined in the jboss namespace.com/xml/ns/javaee" xmlns:tx="urn:trans-timeout" xmlns:xsi="http://www. For the rules when a container-transaction is applicable please refer to EJB 3.com/xml/ns/javaee/ejb-jar_3_1.jboss.xsd urn:trans-timeout http://www. and message-listener interface methods.jboss.3. home.0"> <assembly-descriptor> <container-transaction> <method> <ejb-name>BeanWithTimeoutValue</ejb-name> <method-name>*</method-name> <method-intf>Local</method-intf> </method> <tx:trans-timeout> <tx:timeout>10</tx:timeout> <tx:unit>Seconds</tx:unit> </tx:trans-timeout> </container-transaction> </assembly-descriptor> </jboss:ejb-jar> 8.sun. and timeout callback methods. Example of trans-timeout jboss-ejb3.sun.xsd" version="3.com/xml/ns/javaee http://www.WildFly 8 8.7.com/xml/ns/javaee" xmlns="http://java. JBoss Community Documentation Page 116 of 617 .com/xml/ns/javaee http://java.2.org/j2ee/schema/trans-timeout-1_0.1 FR 13.xsd http://java.4. web service endpoint methods.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.5 Timer service The service is responsible to call the registered timeout methods of the different session beans.sun.xml <jboss:ejb-jar xmlns:jboss="http://www. component.org/j2ee/schema/jboss-ejb3-2_0. no-interface view methods.1.2 Specification of Transaction Timeout in the Deployment Descriptor The trans-timeout element is used to define the transaction timeout for business.w3.1" impl-version="2.jboss.jboss.

3) it will not longer be active after the server is restarted or the application is redeployed. In case of a server restart the timeout method of a persistent timer will only be called directly if the specified time is elapsed. the name of the sub-deployment JAR and the Bean's name. In case of server downtime for a persistent timer.1 Single event timer The timer is will be started once at the specified time.2.1 see 18.5.3) it will be not longer available if JBoss is restarted or the application is redeployed. or more than one. If the timer is not persistent (since EJB3.1 see 18.g.2. 8.2 Recurring timer The timer will be started at the specified first occurrence and after that point at each time if the interval is elapsed.WildFly 8 A persistent timer will be identified by the name of the EAR. JBoss Community Documentation Page 117 of 617 . EAR name contain a version) the timer entry became orphaned and the timer event will not longer be fired. If the timer is not persistent (since EJB3.5. interval is elapsed. 8. If the timer will be started during the last execution is not finished the execution will be suppressed with a warning to avoid concurrent execution. the timeout method will be called only once if one. If one of those names are changed (e.

year="2012") // start once at 01-01-2012 00:00:00 Programmatic calendar timer If the timer is persistent it will be fetched at server start and the missed timeouts are called concurrent. Also a retry will be suppressed if the timeout method throw an Exception. If you set a specific year. It will be automatically deactivated and removed if there will be no next expiration possible. In case of such expired timer access to the given Timer object might throw a NoMoreTimeoutExcption or NoSuchObjectException. month="1". TODO: clarify whether this should happen concurrently/blocked or even fired only once like a recurring timer! JBoss Community Documentation Page 118 of 617 .WildFly 8 8. If a persistent timer contains an end date it will be executed once nevertheless how many times the execution was missed. If the timer is persistent (default if not deactivated by annotation) all missed events are fetched at server start and the annotated timeout method is called concurrent.3 Calendar timer The timer will be started if the schedule expression match. In case of server start the timer is scheduled based on the @Schedule annotation. dayOfMonth="1".. For example: @Schedule( ..e. TODO: clarify whether this should happen concurrently/blocked or even fired only once like a recurring timer! Annotated calendar timer If the timer is non persistent it will not activated for missed events during the server is down.5. i. If the timer is non persistent it will not longer be active after the server is restarted or the application is redeployed.

x JPA persistence provider with your application Sharing the Hibernate 3.x JPA persistence provider Using the Infinispan second level cache Replacing the current Hibernate 4.3.x jars with a newer version Packaging the Hibernate 3.3.5 or greater JPA persistence provider between multiple applications Using OpenJPA Using EclipseLink Using DataNucleus Using Hibernate OGM Native Hibernate use Injection of Hibernate Session and SessionFactoryInjection of Hibernate Session and SessionFactory Hibernate properties Persistence unit properties Determine the persistence provider module Binding EntityManagerFactory/EntityManager to JNDI Community People who have contributed to the WildFly JPA layer: JBoss Community Documentation Page 119 of 617 .3.WildFly 8 9 JPA reference guide Introduction Update your Persistence.0 Entity manager Application-managed entity manager Container-managed entity manager Persistence Context Transaction-scoped Persistence Context Extended Persistence Context Extended Persistence Context Inheritance Entities Deployment Troubleshooting Background on the Jipijapa project Packaging persistence providers with your application and which Jipijapa artifacts to include Using the Hibernate 4.xml for Hibernate 4.5 or greater 3.

0 persistence provider.xml or @PersistenceContext/Unit annotations) and injects Hibernate dependencies into the application deployment.PersistenceProvider) to access the Hibernate persistence provider and some additional extensions as well.persistence.jpa.3 Entity manager The entity manager is similar to the Hibernate Session class. 9. ”entity manager” refers to an instance of the javax. During application deployment. Deploys the persistence unit definitions.0 is org.hibernate.0 specification. Instead of specifying: <provider>org.html and JPA 2.g.3.com/javaee/6/api/javax/persistence/package-summary.0 container-managed requirements.hibernate.spi. 9.3.hibernate. the persistence unit/context annotations and persistence unit/context references in the deployment descriptor.persistence. Javadoc for the JPA interfaces http://download. The JPA subsystem uses the standard SPI (javax.HibernatePersistence</provider> Switch to*:* <provider>org.1 Introduction The WildFly 8 JPA subsystem implements the JPA 2.2 Update your Persistence. persistence. JPA Applications use the Hibernate (core) 4.EntityManager class. This makes it easy to deploy JPA applications.0 The persistence provider class name in Hibernate 4. applications use it to create/read/update/delete data (and related operations). In the remainder of this documentation.HibernatePersistenceProvider</provider> Or remove the persistence provider class name from your persistence. Applications can use application-managed or container-managed entity managers.oracle. Keep in mind that the entity manager is not expected to be thread safe (don't inject it into a servlet class variable which is visible to multiple threads). that is included with WildFly.xml for Hibernate 4. JPA use is detected (e.xml (so the default provider will be used). JBoss Community Documentation Page 120 of 617 .jpa.ejb.HibernatePersistenceProvider. The index of Hibernate documentationis here.WildFly 8 9.

4 Application-managed entity manager Application-managed entity managers provide direct access to the underlying persistence provider (org. Entities changes are also placed into the persistence context (to be saved in the database when the transaction commits).persistence. Every time that a new underlying persistence provider ( org.hibernate. Use the @PersistenceUnit annotation to inject a persistence unit into a javax.ejb.HibernatePersistence). a new persistence context is also created (as an implementation detail of the underlying persistence provider). The EntityManagerFactory can return an application-managed entity manager.HibernatePersistence) instance is created.WildFly 8 9. The persistence context acts like a first level (transactional) cache for interacting with the datasource. The container-managed entity manager will create instances of the underlying persistence provider as needed.5 Container-managed entity manager Container-managed entity managers auto-magically manage the underlying persistence provider for the application.hibernate.ejb. Container-managed entity managers may use transaction-scoped persistence contexts or extended persistence contexts. 9. Loaded entities are placed into the persistence context before being returned to the application.EntityManagerFactory.6 Persistence Context The JPA persistence context contains the entities managed by the persistence provider. 9. JBoss Community Documentation Page 121 of 617 . The scope of the application-managed entity manager is from when the application creates it and lasts until the app closes it.

unitName = "inventoryPU") EntityManager em. @PersistenceContext(type = PersistenceContextType.persist(customer). Look for existing "customerPU" persistence context in active JTA transaction and use if found. instance of org. Entities read outside of a transaction will be detached when the entity manager invocation completes. the persistence context is flushed to the datasource (entity objects are detached but may still be referenced by application code).hibernate. must be made during a transaction. // internally: // 1.8 Extended Persistence Context The (ee container managed) extended persistence context can span multiple transactions and allows data modifications to be queued up (like a shopping cart). address).ejb. String address) { Customer customer = new Customer(name. // persist new Customer when JTA transaction completes (when method ends). Customer entity will be persisted to the database and "customerPU" persistence context closed 9.TRANSACTION EntityManager em. without an active JTA transaction (to be applied during the next JTA TX). public customer createCustomer(String name. @Stateful // will use container managed transactions public class CustomerManager { @PersistenceContext(unitName = "customerPU") // default type is PersistenceContextType.commit will be called.g. em.WildFly 8 9. Example transaction-scoped persistence context is below. When the transaction commits. JBoss Community Documentation Page 122 of 617 .7 Transaction-scoped Persistence Context The transaction-scoped persistence context coordinates with the (active) JTA transaction. return customer.HibernatePersistence) // and put in current active JTA transaction. All entity changes that are expected to be saved to the datasource. The Container-managed extended persistence context can only be injected into a stateful session bean. // 2.EXTENDED. // return Customer entity (will be detached from the persistence context when caller gets control) } // Transaction. Else create new "customerPU" persistence context (e.

For example. Below is an example of using SHALLOW extended persistence context inheritance: <jboss> <jboss-jpa xmlns="http://www. use shallow inheritance.com/xml/ns/javaee"> <extended-persistence inheritance="DEEP"/> </jboss-jpa> </jboss> JBoss Community Documentation Page 123 of 617 .2. The deep inheritance of extended persistence context includes sibling beans. Some other EE application servers. By default.1 If a stateful session bean instantiates a stateful session bean (executing in the same EJB container instance) which also has such an extended persistence context. Sibling beans do not share the same extended persistence context unless their (common) parent bean also has the same extended persistence context. The AS/docs/schema/jboss-jpa_1_0.1 Extended Persistence Context Inheritance JPA 2. Applications can include a (top-level) jboss-all.xml.xml deployment descriptor that specifies either the (default) DEEP extended persistence context inheritance or SHALLOW.WildFly 8 9.0 specification section 7. the current stateful session bean being created. Even though parentA doesn't have an extended persistence context. beanBwithXPC & beanCwithXPC will share the same extended persistence context. will ( deeply) inherit the extended persistence context from any stateful session bean executing in the current Java thread.com/xml/ns/javaee"> <extended-persistence inheritance="SHALLOW"/> </jboss-jpa> </jboss> Below is an example of using DEEP extended persistence inheritance: <jboss> <jboss-jpa xmlns="http://www.jboss.xsd describes the jboss-jpa deployment descriptor that may be included in the jboss-all.jboss. The deep inheritance of extended persistence context includes walking multiple levels up the stateful bean call stack (inheriting from parent beans). the extended persistence context of the first stateful session bean is inherited by the second stateful session bean and bound to it. where stateful session bean only inherit from the parent stateful session bean (if there is a parent bean). and this rule recursively applies—independently of whether transactions are active or not at the point of the creation of the stateful session beans.6. parentA references child beans beanBwithXPC & beanCwithXPC.8.

@PersistenceContext EntityManager em. // create new entity em. // createdBom is now managed and will be saved to database when the current JTA transaction completes The entity lifecycle is managed by the underlying persistence provider.9 Entities JPA 2.persist(createdBom).find(BillOfMaterials. The following cli commands will read the current JPA settings and enable SHALLOW extended persistence context inheritance for applications that do not include the jboss-jpa deployment descriptor: . Removed: a removed entity instance is an instance with a persistent identity.0 makes it easy to use your (pojo) plain old Java class to represent a database table row.value="SHALLOW") 9. JBoss Community Documentation Page 124 of 617 .class.. Integer bomPk = getIndexKeyValue(). Managed (persistent): a managed entity instance is an instance with a persistent identity that is currently associated with a persistence context. bomPk). but scheduled for removal from the database. It has no persistent representation in the database and no identifier value has been assigned. // read existing table row into BillOfMaterials class BillOfMaterials createdBom = new BillOfMaterials(". Detached: the entity instance is an instance with a persistent identity that is no longer associated with a persistence context."). and it is not associated with a persistence context../jboss-cli. New (transient): an entity is new if it has just been instantiated using the new operator. associated with a persistence context.sh cd subsystem=jpa :read-resource :write-attribute(name=default-extended-persistence-inheritance. usually because the persistence context was closed or the instance was evicted from the context.WildFly 8 The AS console/cli can change the default extended persistence context setting (DEEP or SHALLOW). BillOfMaterials bom = em.

as. the jar file or directory whose META-INF directory contains the persistence. Better to put the persistence. If a datasource is not specified. JBoss Community Documentation Page 125 of 617 .as. so you may have deployment issues for other reasons.0 specification): " an EJB-JAR file the WEB-INF/classes directory of a WAR file a jar file in the WEB-INF/lib directory of a WAR file a jar file in the EAR library directory an application client jar file The persistence. datasource name) and as described in the JPA 2. In Java EE environments. the default-datasource will instead be used (must be configured).xml can specify either a JTA datasource or a non-JTA datasource. application searches for a persistence unit.jboss. This use is no longer supported.shows how long each entity manager operation took in milliseconds. The JTA datasource is expected to be used within the EE environment (even when reading data without an active transaction).jar. Portable applications should use the EAR library directory for this case instead. " Question: Can you have a EAR/META-INF/persistence. starting of persistence unit service (per deployed persistence. parsing of persistence.xml? Answer: No.g.xml file is termed the root of the persistence unit.xml). 9.xml) file.jpa category.0"> and add the org.xml To enable TRACE.11 Troubleshooting The org. open the as/standalone/configuration/standalone. NOTE: Java Persistence 1.0 spec (section 8.xml contains the persistence unit configuration (e. the above may deploy but it could include other archives also in the EAR.jpa logging can be enabled to get the following information: INFO .jboss. Search for <subsystem xmlns="urn:jboss:domain:logging:1.xml has been parsed. the root of a persistence unit must be one of the following (quoted directly from the JPA 2.2).0 supported use of a jar file in the root of the EAR as the root of a persistence unit.WildFly 8 9.when persistence.xml in an EAR/lib/somePuJar.informs about entity managers being injected. stopping of persistence unit service DEBUG . You need to change the console-handler level from INFO to TRACE.xml (or as/domain/configuration/domain. creating/reusing transaction scoped entity manager for active transaction TRACE .10 Deployment The persistence.

cache.jdbc.arjuna"> <level name="WARN" /> </logger> <logger category="org. To see what is going on at the JDBC level.spy TRACE and add spy="true" to the datasource.." enabled="true" spy="true"> <logger category="jboss..infinispan: JBoss Community Documentation Page 126 of 617 .spy"> <level name="TRACE"/> </logger> To troubleshoot issues with the Hibernate second level cache..as." pool-name=".0"> <console-handler name="CONSOLE"> <level name="TRACE" /> ..WildFly 8 <subsystem xmlns="urn:jboss:domain:logging:1. <datasource jndi-name="java:jboss/datasources/..modeler"> <level name="WARN" /> </logger> . enable jboss.jpa"> <level name="TRACE" /> </logger> <logger category="org.hibernate..infinispan + org..jdbc.hibernate..util.tomcat.apache. try enabling trace for org.SQL + org.jboss. </console-handler> </periodic-rotating-file-handler> <logger category="com.

modeler"> <level name="WARN" /> </logger> ..infinispan"> <level name="TRACE" /> </logger> <logger category="org. Jipijapa provides additional integration that makes it easier to use various persistence providers..hibernate.arjuna"> <level name="WARN" /> </logger> <logger category="org.SQL"> <level name="TRACE" /> </logger> <logger category="org.xml) can override most settings.WildFly 8 <subsystem xmlns="urn:jboss:domain:logging:1. 9. Also. </console-handler> </periodic-rotating-file-handler> <logger category="com..12 Background on the Jipijapa project The Jipijapa project goal is to improve application platform integration with JPA persistence providers.tomcat. look here at how the Hibernate environment is setup automatically (so that JPA deployments can just work).0"> <console-handler name="CONSOLE"> <level name="TRACE" /> .apache.util. application persistence unit definitions (persistence. JBoss Community Documentation Page 127 of 617 .hibernate"> <level name="TRACE" /> </logger> <logger category="org.. For example.

JBoss Community Documentation Page 128 of 617 .1.0.x.Final OpenJPA 8.x JPA persistence provider Hibernate 4.1.0.jipijapa jipijapa-openjpa 1.2.1.0. should include one of the following Jipijapa integration jars.Final Hibernate ORM version 3.1.jipijapa jipijapa-hibernate4-3 1.0.0.1. 4.14 Using the Hibernate 4.0.1.Final org.jipijapa jipijapa-eclipselink 1.1.Final org.x 8.0.jipijapa jipijapa-hibernate4-1 1.WildFly 8 9.jipijapa jipijapa-hibernate3 1.x is packaged with WildFly and is the default persistence provider.1. so that WildFly can easily deploy your application.0.0.Final org.1. The alternative to including persistence providers with your application.x 8.Final EclipseLink 8. is to instead use the persistence provider as a static module (each of the below providers already have a placeholder static module that you can copy provider jars into).3.Final 9.0. Persistence Provider WildFly Version Group ID Artifact ID Version Hibernate ORM 4.Final org.1.Final Hibernate ORM 4.Final org.3.x.13 Packaging persistence providers with your application and which Jipijapa artifacts to include Applications that include a copy of a persistence provider.x 8. 4.0.1.3.

use_second_level_cache" value="true"/> </properties> </persistence-unit> </persistence> Here is an example of enabling the second level cache for a Hibernate native API hibernate.WildFly 8 9.cache.infinispan. this property is not mandatory and a default container is already deployed for by the application server to host the second level cache.15 Using the Infinispan second level cache To enable the second level cache with Hibernate 4.manager_lookup_class" value="org.MF: Dependencies: org.cache.InfinispanRegionFactory"/> <property name="hibernate.transaction.infinispan.xml file: <property name="hibernate.transaction.cfg.infinispan.factory_class" value="org.cachemanager" value="java:jboss/infinispan/container/hibernate"/> <property name="hibernate.hibernate4.JBossTransactionManagerLookup"/> <property name="hibernate. are not needed.hibernate Infinispan Hibernate/JPA second level cache provider documentation contains advanced configuration information but you should bear in mind that when Hibernate runs within WildFly 8. so you don't need specify anything on top of that: <?xml version="1.</description> <jta-data-source>java:jboss/datasources/mydatasource</jta-data-source> <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode> <properties> <property name="hibernate.org. such as region factory.cache.jpa.use_second_level_cache property to true.container persistence property. the application server providers you with option of selecting a different cache container for Infinispan via hibernate. as is done in the following example (also set the shared-cache-mode accordingly). Moreover. JBoss Community Documentation Page 129 of 617 .com/xml/ns/persistence" version="1.0" encoding="UTF-8"?><persistence xmlns="http://java.region. By default the application server uses Infinispan as the cache provider for JPA applications.infinispan. To reiterate.cache.jboss. some of those configuration options.use_second_level_cache" value="true"/> The Hibernate native API application will also need a MANIFEST. just set the hibernate.as.0"> <persistence-unit name="2lc_example_pu"> <description>example of enabling the second level cache.cache.sun.cache.hibernate.

jpa.sun.jpa.as.Final jars in the ear lib.xml + wildfly/modules/system/layers/base/org/hibernate/envers/main/module.providerModule needs to be set to hibernate3-bundled.17 Packaging the Hibernate 3.</description> <jta-data-source>java:jboss/datasources/PlannerDS</jta-data-source> <properties> <property name="hibernate. Delete *. 3.show_sql" value="false" /> <property name="jboss. Update the wildfly/modules/system/layers/base/org/hibernate/main/module.0"> <persistence-unit name="plannerdatasource_pu"> <description>Hibernate 3 Persistence Unit. The JPA deployer will detect the presence of a persistence provider in the application and jboss.3.as.index files in wildfly/modules/system/layers/base/org/hibernate/main and wildfly/modules/system/layers/base/org/hibernate/envers/main folders.5 (or greater) persistence provider jars with the application. 1. <?xml version="1.x JPA persistence provider with your application WildFly 8 allows the packaging of Hibernate 3. 2.16 Replacing the current Hibernate 4. Backup the current contents of wildfly/modules/system/layers/base/org/hibernate in case you make a mistake.0" encoding="UTF-8"?> <persistence xmlns="http://java.6.providerModule" value="hibernate3-bundled" /> </properties> </persistence-unit> </persistence> The WildFly testsuite contains a test that packages jars from the Hibernate 3.com/xml/ns/persistence" version="1.x jars with a newer version Just update the current wildfly/modules/system/layers/base/org/hibernate/main folder to contain the newer version (after stopping your WildFly server instance).WildFly 8 9.xml to name the jars that you copied in. Remove the older jars and copy new Hibernate jars into wildfly/modules/system/layers/base/org/hibernate/main + wildfly/modules/system/layers/base/org/hibernate/envers/main. 4. 9.5. JBoss Community Documentation Page 130 of 617 .5 or greater 3.

enterprise.asm"/> <module name="javax.annotation.jar"/> <resource-root path="hibernate3-commons-annotations.jar"/> <resource-root path="hibernate3-entitymanager.api"/> <module name="javax.api"/> <module name="javax.transaction.javassist"/> <module name="org.as.Final.jar"/> </resources> --> <dependencies> <module name="asm.api"/> <module name="javax.jboss.jboss.slf4j"/> <module name="org.5 or greater JPA persistence provider between multiple applications Applications can share the same Hibernate3 (for Hibernate 3.persistence.Represents the Hibernate 3.x module <module xmlns="urn:jboss:module:1.WildFly 8 9.jar.1.collections"/> <module name="org.apache.jpa.api"/> <module name="javax.xml file to name each jar you copied in as a "resource-root": <?xml version="1. you will refer to the Hibernate 3 persistence provider as follows: JBoss Community Documentation Page 131 of 617 .18 Sharing the Hibernate 3.spi"/> <module name="org. Update the module.hibernate:3 module (in the AS/modules folder).5 or greater) persistence provider by manually creating an org.logging"/> <module name="org. 3.0" encoding="UTF-8"?><!-.0.jar"/> <resource-root path="hibernate3-core.jboss.xml.commons.dom4j"/> <module name="org.vfs"/> </dependencies> </module> 1.validation.hibernate" slot="3"> <resources> <resource-root path="jipijapa-hibernate3-1. Copy the Hibernate3 jars into this folder (hibernate3-core.1" name="org. Steps to create the Hibernate3 module: 1.bind.x).xml. hibernate3-commons-annotations.jboss.api"/> <module name="javax. In a command shell. In your persistence. cd WF\modules\modules\system\layers\base\org\hibernate\3 2.jar needed for Hibernate 3.jandex"/> <module name="org. go to the AS installation and change into the modules/org folder.antlr"/> <module name="org. hibernate3-entitymanager.api"/> <module name="javax.jar.api"/> <module name="org.

WildFly 8 <?xml version="1.enterprise.openjpa"> <resources> <resource-root path="jipijapa-openjpa-1.jar serp.logging"/> <module name="org.xml to include the same jar file names that you copied in.apache.jboss.api"/> <module name="javax.commons.hibernate:3" /> </properties> </persistence-unit> </persistence> 9.jar"/> <resource-root path="serp.g. openjpa-all. <module xmlns="urn:jboss:module:1.ejb.xml.jboss.jpa.jar"/> </resources> <dependencies> <module name="javax.0.spi"/> <module name="org.1.api"/> <module name="javax.com/xml/ns/persistence" version="1.jandex"/> </dependencies> </module> JBoss Community Documentation Page 132 of 617 .jboss.collections"/> <module name="org.api"/> <module name="javax.as.commons.jar) into the WildFly modules/system/layers/base/org/apache/openjpa/main folder and update modules/system/layers/base/org/apache/openjpa/main/module.as.19 Using OpenJPA You need to copy the OpenJPA jars (e.transaction.0"> <persistence-unit name="crm_pu"> <description>CRM Persistence Unit.jpa.jboss.hibernate.annotation.api"/> <module name="javax.bind.apache.persistence.validation.apache.0" encoding="UTF-8"?> <persistence xmlns="http://java.api"/> <module name="javax.api"/> <module name="org.providerModule" value="org.sun.lang"/> <module name="org.Final.1" name="org.jar"/> <resource-root path="openjpa-all.</description> <provider>org.vfs"/> <module name="org.HibernatePersistence</provider> <jta-data-source>java:jboss/datasources/CRMDS</jta-data-source> <properties> <property name="jboss.api"/> <module name="javax.

5.archive.commons.eclipselink.sh --connect '/system-property=eclipselink.api"/> <module name="javax.api"/> <module name="javax.jar or eclipselink.archive.WildFly 8 9. <module xmlns="urn:jboss:module:1.antlr"/> <module name="org.1.20 Using EclipseLink You need to copy the EclipseLink jar (e. eclipselink-2.eclipse.1" name="org.api"/> <module name="javax.xml.xml should reflect that.0. set (WildFly) system property "eclipselink.factory" to value "org.javassist"/> <module name="org.as.g.JBossArchiveFactoryImpl" via jboss-cli.validation.jboss.transaction.xml to include the EclipseLink jar (take care to use the jar name that you copied in). the module. If you happen to leave the EclipseLink version number in the jar name.eclipselink.JBossArchiveFactoryImpl)' .enterprise.jar"/> <resource-root path="eclipselink.annotation.jipijapa.factory:add(value=org.1.Final.jar"/> </resources> <dependencies> <module name="asm.spi"/> <module name="org.jipijapa. The following shows what the standalone.apache.bind.jboss.logging"/> <module name="org.jms.persistence.dom4j"/> <module name="org.collections"/> <module name="org.api"/> <module name="org.sh command (WildFly server needs to be running when this command is issued): jboss-cli.xml (or your WildFly configuration you are using) file might look like after updating the system properties: JBoss Community Documentation Page 133 of 617 .api"/> <module name="javax.vfs"/> </dependencies> </module> As a workaround for issueid=414974.jpa.api"/> <module name="javax.api"/> <module name="javax.jboss.api"/> <module name="javax.persistence"> <resources> <resource-root path="jipijapa-eclipselink-1.jar as in the example below) into the WildFly modules/system/layers/base/org/eclipse/persistence/main folder and update modules/system/layers/base/org/eclipse/persistence/main/module.asm"/> <module name="javax.

ext.jboss.archive.xml: <?xml version="1.com/xml/ns/persistence" version="1.. 9.0" encoding="UTF-8"?> <persistence xmlns="http://java.xml: <module name="javax.2): Caused by: java.api"/> 9.0 with EclipseLink 2.ExceptionMapper from [Module "org.eclipselink.as. One may encounter following exception (found on WildFly 8.WildFly 8 <system-properties> .1. <property name="eclipselink. Example persistence.jpa.persistence.5.as..HibernateOgmPersistence</provider> <properties> <property name="jboss.adapterModule" value="org.persistence:main" from local module loader.lang.PersistenceProvider</provider> Also refer to page how to use EclipseLink with WildFly guide here.22 Using Hibernate OGM This section is a work in progress.jpa.jpa.xml that include.jpa.sun.hibernate.hibernate:4"/> </properties> </persistence-unit> </persistence> JBoss Community Documentation Page 134 of 617 .as.ws.21 Using DataNucleus Read the how to use DataNucleus with WildFly guide here.jipijapa.rs..JBossArchiveFactoryImpl"/> </system-properties> You should then be able to deploy applications with persistence.ClassNotFoundException: javax.0"> <persistence-unit name="MINIMAL"> <provider>org.rs. <provider>org..jpa. Problem can be solved by adding missing module dependency into modules/system/layers/base/org/eclipse/persistence/main/module.classtransformer" value="false" /> <property name="jboss.factory" value="org.eclipse.ws.ogm.eclipse.

1" name="org.Insert resources here --> </resources> <dependencies> <module name="javax.dom4j"/> <module name="org.jar"/> <!-.xml: <?xml version="1.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.jar"/> <!-.hibernate.api"/> <module name="org.as.0-SNAPSHOT.jpa.Final.collections"/> <module name="org.jar"/> <resource-root path="hibernate-ogm-infinispan-4.1.antlr"/> <module name="org.javassist"/> <module name="org.asm"/> <module name="javax.commons.api"/> <module name="javax.hibernate.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.Final.jar"/> <resource-root path="hibernate-entitymanager-4.Final.hibernate" slot="ogm"> <resources> <resource-root path="hibernate-ogm-core-4.jpa.jar"/> <resource-root path="hibernate-infinispan-4.validation.WildFly 8 The Hibernate ORM module needs to depend on OGM.6.logging"/> <module name="org.6.apache.validation.hibernate" slot="ogm" services="import"/> <module name="org.jboss.1.xml to: <?xml version="1.1" name="org.api"/> <module name="javax.persistence.hibernate" slot="4" optional="true"/> <module name="org.transaction.api"/> <module name="javax.commons-annotations"/> </dependencies> </module> The AS7/modules/org/hibernate/ogm folder should contain the OGM jars and the following module.jboss.1.hibernate" export="true"/> </dependencies> </module> JBoss Community Documentation Page 135 of 617 .dom4j"/> <module name="org.hibernate. Change AS7/modules/org/hibernate/main/module.logging"/> <module name="org.infinispan" optional="true"/> <module name="org.6.api"/> <module name="org.envers" services="import" optional="true"/> <module name="org.api"/> <module name="javax.as.hibernate" slot="4" optional="true"/> <module name="org.commons-annotations"/> <module name="org.api"/> <module name="javax.0.0-SNAPSHOT.hibernate"> <resources> <resource-root path="hibernate-core-4.api"/> <module name="javax.0.jboss.Insert resources here --> </resources> <dependencies> <module name="asm.persistence.jboss.transaction.infinispan" optional="true"/> <module name="org.

MF entry to add Hibernate dependency: Manifest-Version: 1. Dependencies: org. @PersistenceUnit(unitName="crm") SessionFactory factory..Session and org.hibernate. just as you can do with EntityManagers and EntityManagerFactorys. { @PersistenceContext(unitName="crm") Session session1. you could get surprising results (e.0 .SessionFactory.hibernate If you use the Hibernate native api in your application and also use the JPA api to access the same entities (from the same Hibernate session/EntityManager).merge(entity).g.WildFly 8 9. HibernateSession. are referred to here as native Hibernate applications..x) properties (if not already set in persistence unit definition): JBoss Community Documentation Page 136 of 617 . Each entity should be managed by either Hibernate native API or JPA code.23 Native Hibernate use Applications that use the Hibernate API directly.SessionFactory directly. Meaning that JPA applications.Session. type=EXTENDED) Session extendedpc.hibernate.hibernate. Native Hibernate applications. } 9.hibernate... Example MANIFEST.saveOrUpdate(entity) is different than EntityManager. should expect to use the Hibernate jars included in WildFly. import org. import org. @PersistenceContext(unitName="crm2". @Stateful public class MyStatefulBean . Applications that utilize JPA will automatically have the JBoss AS Hibernate injected onto the application deployment classpath. 9. can choose to use the Hibernate jars included with WildFly 8 or they can package their own copy of the Hibernate jars.25 Hibernate properties WildFly automatically sets the following Hibernate (4.24 Injection of Hibernate Session and SessionFactoryInjection of Hibernate Session and SessionFactory You can inject a org.

id.manager_lookup_class This property is removed if found in the persistence.hibernate. interface hibernate.session_factory_name = qualified Is set to the application name + persistence unit name persistence unit name (application can specify a different value but it needs to be unique across all application deployments on the AS instance).ejb.MultipleHiLoPerTableGenerator @GeneratedValue(SEQUENCE) to Hibernate "seqhilo" JBoss Community Documentation Page 137 of 617 .entitymanager_factory_name Is set to the application name + persistence unit name = qualified persistence unit name (application can specify a different value but it needs to be unique across all application deployments on the AS instance).Scanner interface knows how to use the AS annotation indexer (for faster deployment).enhanced.x. hibernate.WildFly 8 Property Purpose hibernate.ejb. In Hibernate 4.enhanced.JtaPlatform Hibernate via this class.service.id.id.spi.session_factory_name.hibernate.jta.platform= instance The transaction manager.hibernate. hibernate.hibernate.packaging.enhanced.id.transaction.ejb. The application can override this value (in the persistence.SequenceStyleGenerator In Hibernate 4. older applications with existing data might need to set to false (see note below).resource_scanner = instance of Instance of entity scanning class is passed in that org. user transaction and of transaction synchronization registry is passed into org.id.platform.jta. hibernate.SequenceStyleGenerator @GeneratedValue(TABLE) maps to org.session_factory_name_is_jndi = only set if the application didn't specify a value for false hibernate.hibernate.x.xml).xml (could conflict with JtaPlatform) hibernate. It really depends on whether your application uses the @GeneratedValue(AUTO) which will generates new key values for newly created entities.new_generator_mappings =true New applications should let this default to true.hibernate. hibernate.TableGenerator @GeneratedValue(SEQUENCE) maps to org. if new_generator_mappings is false: @GeneratedValue(AUTO) maps to Hibernate "native" @GeneratedValue(TABLE) maps to org. if new_generator_mappings is true: @GeneratedValue(AUTO) maps to org.transaction.

26 Persistence unit properties The following properties are supported in the persistence unit definition (in the persistence.xml file): JBoss Community Documentation Page 138 of 617 .WildFly 8 9.

jboss.HibernatePersistenceProviderAdaptor and org. which improves JPA integration with CDI.providerModule name of the persistence provider module (default is org.as. The default is true.jpa. jboss. See note below about some module names that are built in (based on the provider). Should be application .jpa.jboss.jboss. Current valid values are org. for class enhancing to be enabled. wildfly.twophasebootstrap hint to false.jpa.default-unit set to true to choose the default persistence unit in an application.twophasebootstrap persistence providers (like Hibernate ORM 4.allowdefaultdatasourceuse set to false to prevent persistence unit from using the default data source.managed set to false to disable container managed JPA access to the persistence unit. Should be hibernate3-bundled if Hibernate 3 jars are in the application archive (adapterModule and adapterClass will automatically be set for hibernate3-bundled). Other integration adapter modules are expected to be added.ejb. which allows class enhancing/rewriting.xml.as.jpa. This is useful if you inject a persistence context without specifying the unitName (@PersistenceContext EntityManager em) but have multiple persistence units specified in your persistence.HibernatePersistenceProviderAdaptor . Hibernate also needs persistence unit property hibernate.hibernate3.hibernate:4 (Hibernate 4 integration classes) and org. JBoss Community Documentation Page 139 of 617 .jpa.jpa. wildfly.as.jpa.classtransformer set to false to disable class transformers for the persistence unit.WildFly 8 Property Purpose jboss.hibernate:3 (Hibernate 3 integration classes). disables the two phase bootstrap (for the persistence unit that contains the hint).hibernate).x + Spring applications. jboss. The default is true.jboss.adapterModule name of the integration classes that help WildFly to work with the persistence provider.adapterClass class name of the integration adapter. This is only important for persistence units that do not specify a datasource.jboss. allow a two phase persistence unit bootstrap.as.jpa. Setting the wildfly.jpa. jboss.as. This is typically set to false for Seam 2. which enables container managed JPA access to the persistence unit.jpa. if a persistence provider is packaged with the application.as.jpa.jpa.use_class_enhancer to be true. Defaults to true. wildfly.as.3.as.hibernate4. Current valid values are org.jpa.x via EntityManagerFactoryBuilder).as.

ejb.eclipse.toplink org.HibernatePersistence org.cmp3.datanucleus:appengine org.persistence.hibernate org.PersistenceProviderImpl JBoss Community Documentation org.DatastorePersistenceProvider org.apache.toplink.ejb.eclipse.essentials.persistence org.persistence.openjpa. the provider module name is determined by the provider name specified in the persistence.hibernate.jpa.api.jpa.essentials.datanucleus.xml.as.jpa.hibernate.apache.toplink oracle.PersistenceProvider org.openjpa Page 140 of 617 .providerModule property is not specified.appengine.store.jpa. The mapping is: Provider Name Module name blank org.27 Determine the persistence provider module As mentioned above.hibernate:ogm oracle.toplink.ogm. if the jboss.PersistenceProvider oracle.EntityManagerFactoryProvider oracle.HibernateOgmPersistence org.datanucleus org.PersistenceProviderImpl org.WildFly 8 9.datanucleus.jpa.hibernate org.

EntityManager) context.28 Binding EntityManagerFactory/EntityManager to JNDI By default WildFly does not bind the entity manager factory to JNDI.com/xml/ns/persistence http://java.xml of your application by setting the jboss.sun.manager.sun.jndi. }}via hint jboss.persistence.persistence. add a managed data source.name" value="java:/myEntityManager"/> </properties> </persistence-unit> </persistence> @Stateful public class ExampleSFSB { public void createSomeEntityWithTransactionScopedEM(String name) { Context context = new InitialContext(). you can explicitly configure this in the persistence.entity.com/xml/ns/persistence/persistence_2_0.jndi.entity.name{}{{.manager.jndi.factory.factory.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://java.lookup("java:/myEntityManager"). However.jndi.entity. You can also bind a container managed (transaction scoped) entity manager to JNDI as well.w3. } } JBoss Community Documentation Page 141 of 617 . a transaction scoped entity manager (persistence context).setName(name).entity.name" value="java:jboss/myEntityManagerFactory" /> <property name="jboss.WildFly 8 9.EntityManager entityManager = (javax. acts as a proxy that always gets an unique underlying entity manager (at the persistence provider level). someEntity. The value of that property should be the JNDI name to which the entity manager factory should be bound. Here's an example: persistence. the example data source is just for proofs of concept! --> <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source> <properties> <!-. As a reminder. SomeEntity someEntity = new SomeEntity().sun.If you are running in a production environment.Bind entity manager factory to JNDI at java:jboss/myEntityManagerFactory --> <property name="jboss. javax.persist(name).name hint. entityManager.0" encoding="UTF-8"?> <persistence version="2.xsd"> <persistence-unit name="myPU"> <!-.com/xml/ns/persistence" xmlns:xsi="http://www.xml <?xml version="1.manager.0" xmlns="http://java.manager.

For those of you that haven't downloaded the AS source code and started hacking patches together. solutions and code changes. I would like to thank them for this.29 Community Many thanks to the community. as well as those reporting issues. Also. new for WildFly. is the JipiJapa project that contains additional integration code that makes EE JPA application deployments work better. The following list of contributors should grow over time. I hope to see more of you listed here. 9. for reporting issues.1 People who have contributed to the WildFly JPA layer: Carlo de Wolf (lead of the EJB3 project) Steve Ebersole (lead of the Hibernate ORM project) Stuart Douglas (lead of the Seam Persistence project.29. You will find that it easy very easy to find your way around the WildFly/JPA/* source tree and make changes.WildFly 8 9. WildFly project team member/committer) Jaikiran Pai (Active member of JBoss forums and JBoss EJB3 project team member) Strong Liu (leads the productization effort of Hibernate in the EAP product) Scott Marlow (lead of the WildFly container JPA sub-project) Antti Laisi (OpenJPA integration changes) Galder Zamarreño (Infinispan 2lc documentation) Sanne Grinovero (Infinispan 2lc documentation) Paul Ferraro (Infinispan 2lc integration) JBoss Community Documentation Page 142 of 617 . I would like to encourage you to start by reading Hacking on WildFly. A number of people have been answering Wildfly forum questions related to JPA usage.

WildFly 8 10 OSGi developer guide Couldn't find a page to include called: OSGi Developer Guide JBoss Community Documentation Page 143 of 617 .

This is useful in that it allows applications to only ever reference standard portable Java EE names in both code and deployment descriptors.Scoped to the application server In addition to the standard namespaces. This approach is the most efficient. so that you can take advantage of certain core services such as naming and injection.Scoped to the current module java:app . This centralized directory is. It also allows for the application to be unaware of network topology details/ This can even work with Java SE clients by using the little known EE Application Client feature. In a nutshell. However. it is highly recommended to use Client JNDI over traditional remote JNDI access. it does require that all names follow a strict layout. Applications which share the same WildFly instance can use this namespace to intercommunicate. whereas Client JNDI requires one. and a proxy/stub to the component is serialized as part of the name lookup and returned to the client. a variety of mechanisms exist to access remote components. traditional remote JNDI involves two calls to invoke an EE component. and removes a potential single point of failure. This feature allows you to run an extremely minimal AS server around your application. and for a centralised directory for multiple application servers. EJB) java:module . 11. Every WildFly instance has it's own local JNDI namespace (java:) which is unique per JVM.WildFly 8 11 JNDI reference guide 11.This is a more familiar approach to EE application developers. Traditional Remote JNDI . The layout of this namespace is primarily governed by the Java EE specification.This approach is where local names are bound as an alias to a remote name using one of the above mechanisms. but without network round-trips.The namespace is scoped to the current component (i. Client JNDI . It does however allow for customized names. Currently only access to remote EJBs is supported via the ejb: namespace.2 Local JNDI The Java EE platform specification defines the following JNDI contexts: java:comp . For this reason.This is a mechanism by which remote components can be accessed using the JNDI APIs. where the client performs a remote component name lookup against a server.e. to make this possible. EE Application Client / Server-To-Server Delegation .1 Overview WildFly offers several mechanisms to retrieve components by name. however. so user customizations are not possible. Future revisions will likely add a JMS client JNDI namespace. WildFly also provides the following two global namespaces: JBoss Community Documentation Page 144 of 617 .Scoped to the current application java:global . In addition to local JNDI. The client then invokes a method on the proxy which results in another remote network call to the underlying service. a single point of failure.

org/xml/ns/javaee" xmlns:xsi="http://www.1"> <env-entry> <env-entry-name>java:global/mystring</env-entry-name> <env-entry-type>java.1 Binding entries to JNDI There are several methods that can be used to bind entries into JNDI in WildFly.jcp. For example the following web. 11. see the Java EE Platform Specification.jcp.lang.xml binds the string "Hello World" to java:global/mystring and the string "Hello Module" to java:comp/env/hello (any non absolute JNDI name is relative to java:comp/env context). Using a deployment descriptor For Java EE applications the recommended way is to use a deployment descriptor to create the binding. For web deployments java:comp is aliased to java:module. <web-app xmlns="http://xmlns.org/xml/ns/javaee http://xmlns.String</env-entry-type> <env-entry-value>Hello Module</env-entry-value> </env-entry> </web-app> For more details.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.xsd" version="3.w3.2.lang. so EJB's deployed in a war do not have their own comp namespace. JBoss Community Documentation Page 145 of 617 .String</env-entry-type> <env-entry-value>Hello World</env-entry-value> </env-entry> <env-entry> <env-entry-name>hello</env-entry-name> <env-entry-type>java.jcp.WildFly 8 java:jboss java:/ Only entries within the java:jboss/exported context are accessible over remote JNDI.org/xml/ns/javaee/web-app_3_1.

the bind() invocation needs to be wrapped using WildFly proprietary APIs: InitialContext initialContext = new InitialContext().pushOwner(serviceTarget). } The ServiceTarget removes the bind when uninstalled.popOwner(). } finally { WritableServiceBasedNamingStore.WildFly 8 Programatically Java EE Applications Standard Java EE applications may use the standard JNDI API.bind("java:global/a". included with Java SE. to bind entries in the global namespaces (the standard java:comp. try { initialContext. There is no need to unbind entries created programatically. 100). WritableServiceBasedNamingStore. JBoss Community Documentation Page 146 of 617 . as mandated by the Java EE Platform Specification). and the bindings are automatically removed when the deployment is undeployed. which is executed out of a Java EE application context. using the standard JNDI API may result in a UnsupportedOperationException if the target namespace uses a WritableServiceBasedNamingStore. 100). To work around that. initialContext. thus using one out of the module/extension domain usage should be avoided. unless entries are removed using unbind(). java:module and java:app namespaces are read-only. since WildFly tracks which bindings belong to a deployment. InitialContext initialContext = new InitialContext(). WildFly Modules and Extensions With respect to code in WildFly Modules/Extensions.bind("java:global/a".

net.directory.naming.xml/domain. or through the management API.jndi.principal" value=“uid=admin.This allows to to specify the javax.xml might look like: <subsystem xmlns="urn:jboss:domain:naming:2.spi.net. such as an LDAP Directory Service Lookup .naming.naming.String).ObjectFactory that is used to create the looked up value. As an example: /subsystem=naming/binding=java\:global\/mybinding:add(binding-type=simple. value=1000) WildFly's Administrator Guide includes a section describing in detail the Naming subsystem configuration.security.initial" value=“com.A primitive or java.ldap.naming.factory.lang.acme. type=long.security. JBoss Community Documentation Page 147 of 617 .0" > <bindings> <simple name="java:global/a" value="100" type="int" /> <simple name="java:global/jbossDocs" value="https://docs.xml file directly.example.URL entry (default is java.LdapCtxFactory” /> <property name="java.InitialDirContext" cache="true"> <environment> <property name="java.authentication" value=“simple” /> <property name="java.acme" class="org.provider.naming.url" value=“ldap://ldap.com:389” /> <property name="java.MyObjectFactory" /> <external-context name="java:global/federation/ldap/example” class="javax. An example standalone. when this entry is looked up it will lookup the target and return the result.org" type="java.sun.An external context to federate. This can be done by either editing the standalone.ou=system” /> <property name="java.security. Object Factory .naming. External Context .The allows to create JNDI aliases.naming.WildFly 8 Naming Subsystem Configuration It is also possible to bind to one of the three global namespaces using configuration in the naming subsystem.credentials" value=“secret” /> </environment> </external-context> <lookup name="java:global/c" lookup="java:global/b" /> </bindings> </subsystem> The CLI may also be used to bind an entry. Four different types of bindings are supported: Simple .jboss.URL" /> <object-factory name="java:global/b" module="com.

lang. which value. the @Resource's lookup attribute instructs WildFly to lookup the value in java:global/mystring. With respect to the field named hello. The executor field has no attributes specified.xml previously shown. Note that @Resource is more than a JNDI lookup. similar to when using deployment descriptors to bind JNDI entries. there is no lookup attribute value defined. if unspecified. Considering that the deployment descriptor was the web. then WildFly inject the valued defined in the deployment descriptor into the field. it also binds an entry in the component's JNDI environment. the value in java:comp/DefaultManagedExecutorService.lang. JBoss Community Documentation Page 148 of 617 . depending on the field's Java type.0 Specification (JSR 236). The new bind JNDI name is defined by @Resource's name attribute. which defines an environment entry with same hello name.String/myString.String/myString.enterprise. for instance java. and when that happens it's up to WildFly to provide a default value or null.WildFly 8 11. For instance. bind it in java:comp/env/java. and then inject such value into the field. it is considered relative to java:comp/env.2 Retrieving entries from JNDI Resource Injection For Java EE applications the recommended way to lookup a JNDI entry is to use @Resource injection: @Resource(lookup = "java:global/mystring") private String myString. In this particular case WildFly would inject the default instance of a managed executor service.concurrent.ManagedExecutorService/executor. @Resource(name = "hello") private String hello. with respect to the field named myString above. so the bind's name would default to java:comp/env/javax. unless the name is an absolute JNDI name. but there is no such entry in the deployment descriptor. is the Java type concatenated with / and the field's name. so the responsibility to provide the entry's value is delegated to the deployment descriptor. @Resource ManagedExecutorService executor. More.2. as mandated by the EE Concurrency Utilities 1.

INITIAL_CONTEXT_FACTORY.0. "remote://localhost:4447").x is no longer supported.lookup("java:global/mystring").class. without any additional configuration needed.Final</version> <type>pom</type> <scope>compile</scope> </dependency> If you are not using maven a shaded jar that contains all required classes can be found in the bin/client directory of WildFly's distribution.PROVIDER_URL.3 Remote JNDI WildFly supports two different types of remote JNDI.remote.wildfly</groupId> <artifactId>wildfly-ejb-client-bom</artifactId> <version>8.put(Context. To use it.put(Context. 11.InitialContextFactory. if you are maven user can be done simply by adding the following to your pom. JBoss Community Documentation Page 149 of 617 .3.1 remote: The remote: protocol uses the WildFly remoting protocol to lookup items from the servers local JNDI.0. you must have the appropriate jars on the class path.xml: <dependency> <groupId>org. The old jnp based JNDI implementation used in JBoss AS versions prior to 7. 11.naming. the standard JNDI API to lookup an entry from JNDI: String myString = (String) new InitialContext(). org. or simply String myString = InitialContext.WildFly 8 Standard Java SE JNDI API Java EE applications may use.client.doLookup("java:global/mystring").getName()). remoteContext = new InitialContext(env). env.jboss. env. final Properties env = new Properties().

in this case the JNDI lookup will hit the server.3. ejb name and interface type.MyRemoteInterface ejb:myapp/myejbjar/MyStatefulName!comp. This lookup will not hit the server. The exception to this is stateful session beans. For more details on how the server connections are configured. JBoss Community Documentation Page 150 of 617 .test. module name.x home interface. This is a client side JNDI implementation.2 ejb: The ejb: namespace is provided by the jboss-ejb-client library. The second example is for a stateful session bean. in order to tell the server to create the SFSB session. If the current context does not have a connection to a server with the specified EJB deployed then an error will occur. instead a proxy will be generated for the remote interface specified in the name.MyStatefulRemoteInterface?stateful The first example is a lookup of a singleton.WildFly 8 11. When you invoke a method on this proxy it will use the current EJB client context to perform the invocation. Instead of looking up an EJB on the server the lookup name contains enough information for the client side library to generate a proxy with the EJB information. using their application name. Some examples are: ejb:myapp/myejbjar/MyEjbName!com.test. please see EJB invocations from a remote client using JNDI. and no error will be thrown until the proxy is actually used. stateless or EJB 2. This protocol allows you to look up EJB's. Using this protocol it is possible to look up EJB's that do not actually exist. which need to connect to a server when they are created in order to create the session bean instance on the server.

native JDBC applications.1 Dependencies and Modularity WildFly 8 has a modular class loading strategy. different from previous versions of JBoss AS. This makes it easier for Spring applications that package their own dependencies . using a Spring-managed persistence unit.2 as described in SPR-8096). Some module dependencies are implicit. JPA-based applications. through either one of LocalSessionFactoryBean or AnnotationSessionFactoryBean) may use a version of Hibernate 3 packaged inside the application. Hibernate 4 (which is provided through the 'org.4 based applications Spring applications using JPA may choose between: using a server-deployed persistence unit.e. depending on the type of deployment as shown here.1 (and may be supported by Spring 3. which enforces a better class loading isolation between deployments and the application server itself. this does not mean that duplications and conflicts cannot exist on the classpath.0 and Spring 3. 12.2 Persistence usage guide Depending on the strategy being used. A detailed description can be found in the documentation dedicated to class loading in WildFly 8. 12.such as logging frameworks or persistence providers to run on WildFly 8. Spring applications can be: native Hibernate applications. This reduces significantly the risk of running into a class loading conflict and allows applications to package their own dependencies if they choose to do so.hibernate' module of WildFly 8) is not supported by Spring 3.3 Native Spring/Hibernate applications Applications that use the Hibernate API directly with Spring (i.WildFly 8 12 Spring applications development and migration guide This document details the main points that need to be considered by Spring developers that wish to develop new applications or to migrate existing applications to be run into WildFly 8. 12. 12. JBoss Community Documentation Page 151 of 617 . At the same time. so adding this module as a dependency is not a solution.

1 Using server-deployed persistence units Applications that use a server-deployed persistence unit must observe the typical Java EE rules in what concerns dependency management.4. either the persistence context or the persistence unit need to be registered in JNDI via web. In order to use the server-deployed persistence units from within Spring.xml as follows: <persistence-context-ref> <persistence-context-ref-name>persistence/petclinic-em</persistence-unit-ref-name> <persistence-unit-name>petclinic</persistence-unit-name> </persistence-context-ref> or. JBoss Community Documentation Page 152 of 617 .EntityManager"/> or <jee:jndi-lookup id="entityManagerFactory" jndi-name="java:comp/env/persistence/petclinic-emf" expected-type="javax.xml properties is not supported in WildFly 8.persistence classes and persistence provider (Hibernate) are contained in modules which are added automatically by the application when the persistence unit is deployed. as follows: <jee:jndi-lookup id="entityManager" jndi-name="java:comp/env/persistence/petclinic-em" expected-type="javax.persistence.persistence.EntityManagerFactory"/> JNDI binding JNDI binding via persistence. i. the persistence context or persistence unit are available to be looked up in JNDI.e. respectively: <persistence-unit-ref> <persistence-unit-ref-name>persistence/petclinic-emf</persistence-unit-ref-name> <persistence-unit-name>petclinic</persistence-unit-name> </persistence-unit-ref> When doing so.WildFly 8 12. the javax.

springframework. This is what these applications need to consider: Placement of the persistence unit definitions When the application server encounters a deployment that has a file named META-INF/persistence.4.2 Using Spring-managed persistence units Spring applications running in WildFly 8 may also create persistence units on their own.xml and the location can be indicated through the persistenceXmlLocation property of the factory bean class. the corresponding definition can be: <bean id="entityManagerFactory" class="org. In most cases. which will fail the deployment of the persistence unit. such definition files are not compliant with the Java EE requirements. Persistence unit definition files can exist in other locations than META-INF/persistence. WEB-INF/classes/META-INF/persistence.xml (or.jpa.LocalContainerEntityManagerFactoryBean"> <property name="persistenceXmlLocation" value="classpath*:META-INF/jpa-persistence.xml"/> <!-. it will attempt to create a persistence unit based on what is provided in the file.WildFly 8 12.xml).other definitions --> </bean> JBoss Community Documentation Page 153 of 617 . Spring applications can easily avoid this type of conflict. for that matter. mostly because required elements such as the datasource of the persistence unit are supposed to be provided by the Spring context definitions.orm.xml. using the LocalContainerEntityManagerFactoryBean. and consequently of the entire deployment. Assuming that the persistence unit is in the META-INF/jpa-persistence. by using a feature of the LocalContainerEntityManagerFactoryBean which is designed for this purpose.

the application server will automatically add the 'org. WEB-INF/jboss-deployment-structure. In order to do so.4. This can be avoided by instructing the server to exclude the module from the deployment's list of dependencies. the Hibernate 3 jars must be included in the deployment. due the presence of @PersistenceUnit or @PersistenceContext annotations on the application classes. Therefore.0"> <deployment> <exclusions> <module name="org.hibernate' module as a dependency. it is required to use that version with the application.WildFly 8 12. At the same time.xml or.3 Managing dependencies Since the LocalContainerEntityManagerFactoryBean and the corresponding HibernateJpaVendorAdapter are based on Hibernate 3.xml with the following content: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1. for web applications. include a META-INF/jboss-deployment-structure.hibernate"/> </exclusions> </deployment> </jboss-deployment-structure> JBoss Community Documentation Page 154 of 617 .

WildFly 8 13 All WildFly 8 documentation JBoss Community Documentation Page 155 of 617 .

WildFly 8 14 All JBoss AS 7 documentation JBoss Community Documentation Page 156 of 617 .

Note that the application client is different to the EJB client libraries. An application client is essentially a cut down server instance.1 Getting Started To launch the application client use the appclient. 15. it is perfectly possible to write client application that do not use the application client. such as this one.sh or appclient.properties file rather than a host: .sh --ejb-client-properties=my-jboss-ejb-client. that allow you to use EE features such as injection in a client side program. 15.bat script in the bin directory.ear#appClient.0. There are tutorials available elsewhere that cover application client basics.properties myear./appclient. The next argument is the application client deployment to use. and this deployment must also be deployed on the full server instance that the client is connecting too. For example: ./appclient.ear#appClient. This article is not a tutorial on application client development. Any arguments after the deployment to use are passed directly through to the application clients main function. WildFly 8 contains an application client.0.sh --host=10.jar arg1 JBoss Community Documentation Page 157 of 617 . but instead use the jboss-ejb-client library directly.jar arg1 The --host argument tells the appclient the server to connect to. application clients can only run a single deployment.2 Connecting to more than one host If you want to connect to more than one host or make use of the clustering functionality then you need to specify a jboss-ejb-client.1 myear. rather it covers the specifics of the WildFly application client.WildFly 8 15 Application Client Reference As a Java EE 7 compliant server.

WildFly 8 15. JBoss Community Documentation Page 158 of 617 .3 Example A simple example how to package an application client and use it with WildFly can be within the quickstart appclient which is located on Github .

either using the MANIFEST.my-cdi-module meta-inf. and make sure the META-INF directory of this deployment is imported. This document is not intended to be a CDI tutorial.WildFly 8 16 CDI Reference WildFly 8 uses Weld. In order for this to work you must add a dependency on the external deployment that your beans are coming from.2"> <deployment> <dependencies> <module name="deployment.xml. so that your deployment has visibility to the beans.jar" meta-inf="import"/> </dependencies> </deployment> </jboss-deployment-structure> Note that this can be used to create beans from both modules in the modules directory.MF you need to add a Dependencies entry.g. e. Dependencies: com.1 Using CDI Beans from outside the deployment For WildFly 8 onwards.xml file in any archive in the deployment. For some general information on CDI see the below links: CDI Specification Weld Reference Guide The AS7 Quickstarts 16. and from other deployments. com. with meta-inf specified after the entry. the CDI reference implementation as its CDI provider.xml file). To activate CDI for a deployment simply add a beans. <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1. it only covers CDI usage that is specific to WildFly. Using MANIFEST.d1. it is now possible have classes outside the deployment be picked up as CDI beans. For more information on class loading and adding dependencies to your deployment please see the Class Loading Guide JBoss Community Documentation Page 159 of 617 .xml you need to add a dependency entry with meta-inf="import". e.MF or using jboss-deployment-structure.g.xml file (To import beans from outside the deployment they must be in an archive with a beans.my-other-cdi-module meta-inf Using jboss-deployment-structure. There are two ways to do this.

0"> <weld xmlns="urn:jboss:weld:1. Libraries exist that make use of scope annotation (bean defining annotations) for their own convenience but are not designed to run with CDI support. though. In an implicit bean archive only those classes that are either annotated with bean defining annotations or are session beans are recognized by CDI as beans (other classes cannot be injected).xml file. Fortunately. the beans. An implicit bean archive is any archive that contains one or more classes annotated with a bean defining annotation (scope annotation) or one or more session beans. Guava would be an example of such library. WildFly makes it possible to suppress implicit bean archives and only enable CDI in archives that bundle the beans. As a result.WildFly 8 16. In addition to well-known explicit bean archives (basically any archive containing the beans. If your application bundles such library it will be recognized as a CDI archive and may fail the deployment.2. This has a side-effect.1 deployment configuration You can either set this up for your deployment only by adding the following content to the META-INF/jboss-all. you may configure this for all deployments in your WildFly instance by executing the following command: /subsystem=weld:write-attribute(name=require-bean-descriptor. There are two ways to achieve this: 16.2 Suppressing implicit bean archives CDI 1.2.0" require-bean-descriptor="true"/> </jboss> 16.xml file) the specification introduces implicit bean archives.xml file is no longer required for CDI to work in your application.1 brings new options to packaging of CDI-enabled applications.value=true) JBoss Community Documentation Page 160 of 617 .xml file of your application: <jboss xmlns="urn:jboss:1.2 Global configuration Alternatively.

you may configure this for all deployments in your WildFly instance by executing the following command: /subsystem=weld:write-attribute(name=non-portable-mode.weld.3.3 portable mode CDI 1. The non-portable mode only exists to preserve compatibility with legacy extensions! JBoss Community Documentation Page 161 of 617 . As a result.value=true) Note that new portable extensions should always use the BeanManager API properly and thus never required the non-portable mode.WildFly 8 16.1 clarifies some aspects of how CDI portable extensions work.1.0" non-portable-mode="true" /> </jboss> 16. there are two ways to enable the non-portable mode: 16. some extensions that do not use the API properly (but were tolerated in CDI 1.0 environment) may stop working with CDI 1.IllegalStateException: WELD-001332: BeanManager method getBeans() is not available during application initialization Fortunately.0"> <weld xmlns="urn:jboss:weld:1.xml file of your application: <jboss xmlns="urn:jboss:1.3.jboss.1 deployment configuration You can either set this up for your deployment only by adding the following content to the META-INF/jboss-all. there is a non-portable mode available in WildFly which skips some of the API usage checks and therefore allows the legacy extensions to work as before.exceptions.If this is the case of your application you will see an exception like this: org.2 Global configuration Alternatively. Again.

17.war. Deployments in WildFly are also modules. along with any supporting modules that weld needs to operate. Class loading is based on the JBoss Modules project. For instance. Instead of the more familiar hierarchical class loading environment.2 Automatic Dependencies Even though in WildFly modules are isolated by default.ear. This means that it is possible for a deployment to import classes from another deployment using the other deployments module name. JBoss Community Documentation Page 162 of 617 .myear. WildFly's class loading is based on modules that have to define explicit dependencies on other modules. Automatic dependencies can be excluded through the use of jboss-deployment-structure. Similarly if your module contains a beans.myarchive. if you are deploying a Java EE application a dependency on the Java EE API's will be added to your module automatically. as part of the deployment process some dependencies on modules defined by the application server are set up for you automatically. the details of how to add an explicit module dependency are explained below. please see Implicit module dependencies for deployments. Class loading is considerably different to previous versions of JBoss AS.xml. For a complete list of the automatic dependencies that are added. and do not have access to classes that are defined in jars in the application server unless an explicit dependency on those classes is defined.xml file a dependency on Weld will be added automatically.WildFly 8 17 Class Loading in WildFly Since JBoss AS7.mywar.war while sub deployments are named like deployment.1 Deployment Module Names Module names for top level deployments follow the format deployment. 17.

however they do not always have an automatic dependency on each other.ear deployment: JBoss Community Documentation Page 163 of 617 . 17. Local Resource .xml or through the Dependencies: manifest entry. Inter deployment dependencies .g. This can include classes in an ear's lib directory. 4. By default the EAR/lib directory is a single module.These are dependencies on other deployments in an ear deployment. unless explicit dependencies have been defined. or classes defined in other ejb jars.ear. e. including the Java EE api's. Sub deployments (wars and ejb-jars) always have a dependency on the parent module.These are dependencies that are added through jboss-deployment-structure. 3.Class files packaged up inside the deployment itself. which gives them access to classes in EAR/lib. This means that not all classes inside an ear will necessarily have access to all other classes in the ear.These are dependencies that are added to the module automatically by the container. User Dependencies .0" > <ear-subdeployments-isolated>false</ear-subdeployments-isolated> </subsystem> By default this is set to false.5 EAR Class Loading Ear deployments are multi-module deployments.3 Class Loading Precedence A common source of errors in Java applications is including API classes in a deployment that are also provided by the container. For example. consider the following . This behaviour is controlled via the ear-subdeployments-isolated setting in the ee subsystem configuration: <subsystem xmlns="urn:jboss:domain:ee:1. so classes defined in WEB-INF/lib are treated the same as classes in WEB-INF/classes. class files from WEB-INF/classes or WEB-INF/lib of a war. All classes packaged in the war will be loaded with the same class loader. which allows the sub-deployments to see classes belonging to other sub-deployments within the . In order of highest priority to lowest priority 1. and every WAR or EJB jar deployment is also a separate module. 2. 17. To prevent this in WildFly. module dependencies are added in a specific order that should prevent this situation from occurring.4 WAR Class Loading The war is considered to be a single module. System Dependencies . This can result in multiple versions of the class being created and the deployment failing to deploy properly.WildFly 8 17.

i.ejb2.jar.javassist export. The available modules can be seen under the modules directory in the application server distribution.velocity export services. then the classes in web.apache.antlr Each dependency entry may also specify some of the following parameters by adding them after the module name: JBoss Community Documentation Page 164 of 617 . or by setting up explicit module dependencies. irrespective of whether this flag is set to true or false. Similarly.org.war. Dependencies: Manifest Entries Deployments (or more correctly modules within a deployment) may set up dependencies on other modules by adding a Dependencies: manifest entry. Portability The Java EE specification says that portable applications should not rely on sub deployments having access to other sub deployments unless an explicit Class-Path entry is set in the MANIFEST. It is also possible to override the ear-subdeployments-isolated element value at a per deployment level.ejb1.jar | |--.ear | |--.web. User must manually setup the dependency with Class-Path entries. If the ear-subdeployments-isolated is set to true then no automatic module dependencies between the sub-deployments are set up.jar can access classes from ejb2.xml below. classes from ejb1.ear will have a isolated classloader and other sub-deployments within that . This entry consists of a comma separated list of module names that the deployment requires. So portable applications should always use Class-Path entry to explicitly state their dependencies.jar (and vice-versa).MF.war within a . The ear-subdeployments-isolated element value has no effect on the isolated classloader of the .jar If the ear-subdeployments-isolated is set to false.war file(s). See the section on jboss-deployment-structure.e.WildFly 8 myapp.ear will not be able to access classes from that . This is as per spec.war | |--.org. For example to add a dependency on javassist and apache velocity you can add a manifest entry as follows: Dependencies: org. the .war can access classes belonging to ejb1.jar and ejb2.

MF entry when using maven put the following in your pom. optional If this is specified the deployment will not fail if the module is not available.WildFly 8 export This means that the dependencies will be exported. services By default items in META-INF of a dependency are not accessible.idx. annotations If a jandex index has be created for the module these annotations will be merged into the deployments annotation index. If a module is exported from a Dependencies: entry in the top level of the ear (or by a jar in the ear/lib directory) it will be available to all sub deployments as well. and must be named META-INF/jandex. JBoss Community Documentation Page 165 of 617 . meta-inf This will make the contents of the META-INF directory available (unlike services..plugins</groupId> <artifactId>maven-war-plugin</artifactId> <configuration> <archive> <manifestEntries> <Dependencies>org. To generate a MANIFEST.maven. which just makes META-INF/services available).. so any module that depends on this module will also get access to the dependency. a better approach is to create a jar containing just this index.xml: pom. Adding a dependency to all modules in an EAR Using the export parameter it is possible to add a dependency to all sub deployments in an ear.apache. If a beans. In general this will not cause any deployment descriptors in META-INF to be processed. and adding it as an additional resource root in the module. Note that it is not necessary to break open the jar being indexed to add this to the modules class path. with the exception of beans.xml file.xml <build> .xml file is present this module will be scanned by Weld and any resulting beans will be available to the application. this makes items from META-INF/services accessible so services in the modules can be loaded.xml. <plugins> <plugin> <groupId>org.slf4j</Dependencies> </manifestEntries> </archive> </configuration> </plugin> </plugins> </build> If your deployment is a jar you must use the maven-jar-plugin rather than the maven-war-plugin. The Jandex index can be generated using the Jandex ant task .

xml <jboss-deployment-structure> <!-. to add javassist to all deployments you can use the following XML: standalone.5.1 Class Path Entries It is also possible to add module dependencies on other modules inside the deployment using the Class-Path manifest entry.6 Global Modules It is also possible to set up global modules.xml/domain. This is done by modifying the configuration file (standalone/domain.WildFly 8 17.xml).xml <subsystem xmlns="urn:jboss:domain:ee:1.xml file for an ear deployment is as follows: jboss-deployment-structure. and is accessible to all sub deployments in the ear. This can be used within an ear to set up dependencies between sub deployments. It can do the following: Prevent automatic dependencies from being added Add additional dependencies Define additional modules Change an EAR deployments isolated class loading behaviour Add additional resource roots to a module An example of a complete jboss-deployment-structure.7 JBoss Deployment Structure File jboss-deployment-structure. 17.Make sub deployments isolated by default. that are accessible to all deployments.xml is a JBoss specific deployment descriptor that can be used to control class loading in a fine grained manner. It should be placed in the top level deployment. If a jar in the EAR/lib directory references a jar via Class-Path: then this additional jar is merged into the parent ear's module.0" > <global-modules> <module name="org. so they cannot see each others classes without a Class-Path entry --> JBoss Community Documentation Page 166 of 617 . For example. and also to allow modules access to additional jars deployed in an ear that are not sub deployments and are not in the EAR/lib directory. 17. in META-INF (or WEB-INF for web deployments).javassist" slot="main" /> </global-modules> </subsystem> Note that the slot field is optional and defaults to main.

This could also be done with a Class-Path entry --> <module name="deployment. for an ear --> <!-.This allows you to define additional dependencies.Set's local resources to have the lowest priority --> <!-.exclude-subsystem prevents a subsystems deployment unit processors running on a deployment --> <!-. but it only affects single deployment --> <exclude-subsystems> <subsystem name="resteasy" /> </exclude-subsystems> <!-.util.proxy" /> <module name="deployment.This corresponds to the module for a web deployment --> <!-.Exclusions allow you to prevent the server from automatically adding some dependencies --> <exclusions> <module name="org.WildFly 8 <ear-subdeployments-isolated>true</ear-subdeployments-isolated> <!-. For a war this is the war's module.javassist.Now we are going to define two additional modules --> <!-.myjavassist" /> <!-.These add additional classes to the module.which gives basically the same effect as removing the subsystem.it can use all the same tags as the <deployment> entry above --> <dependencies> <!-.Adds a dependency on a ejb jar.jar" > <!-.javassist" /> </exclusions> <!-.This is the top level ear module.jar" /> </dependencies> <!-.* so we filter it out--> <filter> <exclude path="javassist/util/proxy" /> </filter> </resource-root> </resources> JBoss Community Documentation Page 167 of 617 . --> <!-. then the Class from the other deployment will be loaded.Import META-INF/services for ServiceLoader impls as well --> <module name="myservicemodule" services="import"/> </dependencies> <!-.This one is a different version of javassist that we have packaged --> <module name="deployment.ear.myejbjar.war"> <!-.proxy.We want to use the servers version of javassist.rather than the class actually packaged in the war.jar" /> </resources> </deployment> <sub-deployment name="myapp.myear. it is the same as using the Dependencies: manifest attribute --> <dependencies> <module name="deployment. which contains all the classes in the EAR's lib folder --> <deployment> <!-. --> <!-.This corresponds to the top level deployment.This can be used to resolve ClassCastExceptions if the same class is in multiple sub deployments--> <local-last value="true" /> </sub-deployment> <!-.If the same class is both in the sub deployment and in another sub deployment that --> <!-.is visible to the war. In this case it is the same as including the jar in the EAR's lib directory --> <resources> <resource-root path="my-library.myjavassist" > <resources> <resource-root path="javassist.

com/wildfly/wildfly-core/blob/master/server/src/main/resources/schema/jboss-deployment-structure-1_ .javassist. 17.1"> <deployment> <dependencies> <system export="true"> <paths> <path name="com/sun/corba/se/spi/legacy/connection"/> </paths> </system> </dependencies> </deployment> </jboss-deployment-structure> JBoss Community Documentation Page 168 of 617 .javassist" > <imports> <include path="javassist/util/proxy" /> <exclude path="/**" /> </imports> </module> </dependencies> </module> </jboss-deployment-structure> The xsd for jboss-deployment-structure.This means that there is only one version of the Proxy classes defined --> <module name="deployment.8 Accessing JDK classes Not all JDK classes are exposed to a deployment by default.proxy" > <dependencies> <module name="org. If your deployment uses JDK classes that are not exposed you can get access to them using jboss-deployment-structure.This is a module that re-exports the containers version of javassist.WildFly 8 </module> <!-.util.xml is available at https://github.proxy --> <!-.xml with system dependencies: Using jboss-deployment-structure.xml to access JDK classes <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.

or deployment META-INF of an descriptor ejb-jar.xml WEB-INF of a EJB The EJB spec war.WildFly 8 18 Deployment Descriptors used In WildFly This page gives a list and a description of all the valid deployment descriptors that a WildFly deployment can use. This can be use to override settings from web.xml JBoss Web WEB-INF deployment descriptor.xml META-INF or Info This file can be Class Loading in WEB-INF of the used to control top level class loading deployment for the WildFly deployment beans.xml WEB-INF Servlet Web deployment descriptor jboss-web.xml. This document is a work in progress. Descriptor Location Specification Description jboss-deployment-structure.xml schema EJB jar JBoss Community Documentation Page 169 of 617 . and to set WildFly specific options ejb-jar.xml WEB-INF or CDI META-INF The presence Weld Reference of this Guide descriptor (even if empty) activates CDI web.

WildFly 8 jboss-ejb3.xml META-INF of an Java EE application. and to set WildFly specific settings application. This from a remote META-INF of an file is used to server instance EJB jar setup the EJB client context for a deployment that is used for remote EJB invocations JBoss Community Documentation Page 170 of 617 .xml. this EJB jar can be used to override settings from ejb-jar.xml META-INF of an JBoss EAR application deployment descriptor. or settings. can be used to override settings application.xml WEB-INF of a The JBoss EJB war.xml META-INF JPA JPA descriptor Hibernate Reference used for Guide defining persistence units jboss-ejb-client.xml WEB-INF of a Remote EJB EJB invocations war.xml EAR Platform schema Specification jboss-app. and to set WildFly specific settings persistence. or deployment META-INF of an descriptor.xml.

WildFly 8 jbosscmp-jdbc. The format is largely unchanged from previous versions. Used to map CMP entity beans to a database. used to deploy message destinations with a deployment *-ds. use to bundle datasources with a deployment JBoss Community Documentation Page 171 of 617 .xml META-INF of a Spec IronJacamar rar archive deployment Reference Guide descriptor for Schema resource adaptor deployments ironjacamar. ra.xml META-INF of a JBoss IronJacamar rar archive deployment Reference Guide descriptor for resource adaptor deployments *-jms.xml META-INF or JMS message WEB-INF destination deployment descriptor.xml META-INF or Datasource DataSource WEB-INF deployment Configuration descriptor.xml META-INF of an CMP EJB jar deployment descriptor.

WildFly 8 application-client.xml META-INF of an The application client WildFly specific jar deployment descriptor for application client deployments jboss-webservices.0.xml META-INF of an Java EE6 The spec application-client.xml application client Platform deployment schema jar Specification descriptor for application client deployments jboss-client.x specific deployments or deployment WEB-INF for descriptor for POJO webservice webservice endpoints deployments/EJB webservice endpoints bundled in .war JBoss Community Documentation Page 172 of 617 .xml META-INF for The JBossWS EJB webservice 4.

WildFly 8 19 Development Guidelines and Recommended Practices The purpose of this page is to document tips and techniques that will assist developers in creating fast. JBoss Community Documentation Page 173 of 617 . and reliable applications. secure. It is also a place to note what you should avoid doing when developing applications.

perhaps customised to better serve a specific usage. may be created through WildFly's EE Subsystem Configuration. and such configuration is covered by Default EE Bindings Configuration. The EE Concurrency Utilities support the propagation of the invocation context. JNDI and security contexts. JBoss Community Documentation Page 174 of 617 . as mandated by the specification. the class loading. which adapts well known Java SE concurrency utilities to the Java EE application environment specifics.WildFly 8 20 EE Concurrency Utilities 20. ready to use. but additional instances. WildFly creates a single default instance of each EE Concurrency Utility type in all configurations within the distribution. by default. Additionally. and provide these to the applications. the EE subsystem configuration also includes the configuration of which instance should be considered the default instance mandated by the Java EE specification. The Java EE application server is responsible for the creation (and shutdown) of every instance of the EE Concurrency Utilities. the same way a logged-in user principal is propagated when a servlet invokes an EJB asynchronously. capturing the existent context in the application threads to use in their own threads. To learn how to configure EE Concurrency Utilities please refer to EE Concurrency Utilities Configuration. The propagation of the invocation context includes.1 Overview EE Concurrency Utilities (JSR 236) is a technology introduced with Java EE 7.

WildFly 8 20. } WildFly default configurations creates a single default instance of a Context Service. 20.class).ContextService) is a brand new concurrency utility.enterprise. no matter what's the name attribute value.concurrent. @Resource's lookup attribute needs to specify the JNDI name used in the wanted instance configuration. the default Context Service instance's JNDI name is java:comp/DefaultContextService. JBoss Community Documentation Page 175 of 617 .enterprise.3 Managed Thread Factory The Managed Thread Factory (javax..ThreadFactory) adapted to the Java EE platform specifics.... which applications may use to build contextual proxies from existing objects.concurrent. A contextual proxy is an object that sets a invocation context. Usage example: public void onGet(..ManagedThreadFactory) allows Java EE applications to create Java threads.concurrent. Applications may alternatively use instead the standard JNDI API: ContextService contextService = InitialContext. It is an extension of Java SE's Thread Factory ( java. // . As mandated by the Java EE specification. whenever is invoked. Runnable contextualTask = contextService. before delegating the invocation to the original object. Runnable..2 Context Service The Context Service (javax.createContextualProxy(task. captured when created. which may be retrieved through @Resource injection: @Resource private ContextService contextService.. WildFly will always inject the default instance. To retrieve instead a non default Context Service instance.) { Runnable task = .util.doLookup("java:comp/DefaultContextService"). if the lookup attribute is not defined.

.enterprise.start(). which allows an application to learn about termination status.newThread(task). which may be retrieved through @Resource injection: @Resource private ManagedThreadFactory managedThreadFactory..) { Runnable task = ... Usage example: public void onGet(. } WildFly default configurations creates a single default instance of a Managed Thread Factory. in case the lookup attribute is not defined.concurrent..ManageableThread. and such context is propagated to the thread's Runnable execution. To retrieve instead a non default Managed Thread Factory instance. WildFly will always inject the default instance.WildFly 8 Managed Thread Factory instances are managed by the application server. thread. the application's thread context is captured when a thread creation is requested. thus Java EE applications are forbidden to invoke any lifecycle related method. Managed Thread Factory threads implement javax. Thread thread = managedThreadFactory. @Resource's lookup attribute needs to specify the JNDI name used in the wanted instance configuration.doLookup("java:comp/DefaultManagedThreadFactory"). As mandated by the Java EE specification. In case the Managed Thread Factory is configured to use a Context Service. Applications may alternatively use instead the standard JNDI API: ManagedThreadFactory managedThreadFactory = InitialContext.. no matter what's the name attribute value. // . the default Managed Thread Factory instance's JNDI name is java:comp/DefaultManagedThreadFactory. JBoss Community Documentation Page 176 of 617 ..

.) { Runnable task = . the default Managed Executor Service instance's JNDI name is java:comp/DefaultManagedExecutorService.... Managed Executor Service instances are managed by the application server.4 Managed Executor Service The Managed Executor Service (javax. and propagated to the executor thread responsible for the task execution.ManagedExecutorService) allows Java EE applications to submit tasks for asynchronous execution.. in case the lookup attribute is not defined.doLookup("java:comp/DefaultManagedExecutorService").concurrent.WildFly 8 20. Future future = managedExecutorService.enterprise. no matter what's the name attribute value. To retrieve instead a non default Managed Executor Service instance. which may be retrieved through @Resource injection: @Resource private ManagedExecutorService managedExecutorService. As mandated by the Java EE specification. the application's thread context is captured when the task is submitted. WildFly will always inject the default instance. In case the Managed Executor Service is configured to use a Context Service. @Resource's lookup attribute needs to specify the JNDI name used in the wanted instance configuration. It is an extension of Java SE's Executor Service (java. Usage example: public void onGet(. // .util.submit(task).. } WildFly default configurations creates a single default instance of a Managed Executor Service.. Applications may alternatively use instead the standard JNDI API: ManagedExecutorService managedExecutorService = InitialContext.ExecutorService) adapted to the Java EE platform requirements. JBoss Community Documentation Page 177 of 617 .concurrent. thus Java EE applications are forbidden to invoke any lifecycle related method.

. WildFly will always inject the default instance. ScheduledFuture future = managedScheduledExecutorService. and propagated to the executor thread responsible for the task execution. In case the Managed Scheduled Executor Service is configured to use a Context Service. 60.. the application's thread context is captured when the task is scheduled. @Resource's lookup attribute needs to specify the JNDI name used in the wanted instance configuration. Applications may alternatively use instead the standard JNDI API: ManagedScheduledExecutorService managedScheduledExecutorService = InitialContext.concurrent. thus Java EE applications are forbidden to invoke any lifecycle related method. It is an extension of Java SE's Executor Service ( java.ManagedScheduledExecutorService) allows Java EE applications to schedule tasks for asynchronous execution. which may be retrieved through @Resource injection: @Resource private ManagedScheduledExecutorService managedScheduledExecutorService. } WildFly default configurations creates a single default instance of a Managed Scheduled Executor Service.SECONDS). // . To retrieve instead a non default Managed Scheduled Executor Service instance..concurrent.enterprise.util.5 Managed Scheduled Executor Service The Managed Scheduled Executor Service ( javax. TimeUnit..) { Runnable task = ... JBoss Community Documentation Page 178 of 617 . in case the lookup attribute is not defined.schedule(task. no matter what's the name attribute value.WildFly 8 20. Usage example: public void onGet(. Managed Scheduled Executor Service instances are managed by the application server.doLookup("java:comp/DefaultManagedScheduledExecutorService")..ScheduledExecutorService) adapted to the Java EE platform requirements.

the default Managed Scheduled Executor Service instance's JNDI name is java:comp/DefaultManagedScheduledExecutorService. JBoss Community Documentation Page 179 of 617 .WildFly 8 As mandated by the Java EE specification.

For example: @MessageDriven(messageListenerInterface = PostmanPat.rar. 21. 21. Currently there is no support for configuring the extensions using an implementation specific descriptor file. For example jms-ra.WildFly 8 21 EJB 3 Reference Guide This chapter details the extensions that are available when developing Enterprise Java Beans tm on WildFly 8.class) @ResourceAdapter("ejb3-rar.1.1 Specification of Resource Adapter using Metadata Annotations The ResourceAdapter annotation is used to specify the resource adapter with which the MDB should connect.rar") JBoss Community Documentation Page 180 of 617 . The value of the annotation is the name of the deployment unit containing the resource adapter.1 Resource Adapter for Message Driven Beans Each Message Driven Bean must be connected to a resource adapter.

21. This principal can be overridden by specifying a run-as principal.3.1 Specification of Security Domain using Metadata Annotations The SecurityDomain annotation is used to specify the security domain to associate with the EJB. Only when an EJB is associated with a security domain will authentication and authorization be enforced.3 Security Domain Each Enterprise Java Bean tm can be associated with a security domain. For example: @RunAs("admin") @RunAsPrincipal("MyBean") 21. 21.2 as Principal Whenever a run-as role is specified for a given method invocation the default anonymous principal is used as the caller principal.4 Transaction Timeout For any newly started transaction a transaction timeout can be specified in seconds. Using this annotation without specifying a run-as role is considered an error.2.WildFly 8 21. The value of the annotation is the name of the security domain to be used.1 Specification of Run-as Principal using Metadata Annotations The RunAsPrincipal annotation is used to specify the run-as principal to use for a given method invocation. The value of the annotation specifies the name of the principal to use. The actual type of the principal is undefined and should not be relied upon. For example: @SecurityDomain("other") 21. JBoss Community Documentation Page 181 of 617 .

21. For example:@TransactionTimeout(value = 10. even when the computed value will result in an even amount of seconds. then the actual transaction timeout will default to the domain configured default.4. Whenever 0 is specified the default domain configured timeout is used.WildFly 8 When a transaction timeout of 0 is used. New Transactions Take care that even when transaction attribute REQUIRED is specified. The value of the annotation is the timeout used in the given unit granularity. Specifying a granularity lower than SECONDS is considered an error. The unit specifies the granularity of the value. the timeout will only be applicable if a new transaction is started.1 Specification of Transaction Timeout with Metadata Annotations The TransactionTimeout annotation is used to specify the transaction timeout for a given method.SECONDS) JBoss Community Documentation Page 182 of 617 . It must be a positive integer or 0. unit = TimeUnit. TODO: add link to tx subsystem Although this is only applicable when using transaction attribute REQUIRED or REQUIRES_NEW the application server will not detect invalid setups. The actual value used is converted to seconds.

1. JBoss Community Documentation Page 183 of 617 . and timeout callback methods.xml <jboss:ejb-jar xmlns:jboss="http://www.com/xml/ns/javaee" xmlns:tx="urn:trans-timeout" xmlns:xsi="http://www.com/xml/ns/javaee http://java.1 FR 13.0"> <assembly-descriptor> <container-transaction> <method> <ejb-name>BeanWithTimeoutValue</ejb-name> <method-name>*</method-name> <method-intf>Local</method-intf> </method> <tx:trans-timeout> <tx:timeout>10</tx:timeout> <tx:unit>Seconds</tx:unit> </tx:trans-timeout> </container-transaction> </assembly-descriptor> </jboss:ejb-jar> 21.2 Specification of Transaction Timeout in the Deployment Descriptor The trans-timeout element is used to define the transaction timeout for business. For the rules when a container-transaction is applicable please refer to EJB 3.xsd" version="3.jboss.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.jboss.2.jboss. The trans-timeout element resides in the urn:trans-timeout namespace and is part of the standard container-transaction element as defined in the jboss namespace.com/xml/ns/javaee http://www. home.1" impl-version="2.com/xml/ns/javaee/ejb-jar_3_1.7. Example of trans-timeout jboss-ejb3.com/xml/ns/javaee" xmlns="http://java.w3.org/j2ee/schema/jboss-ejb3-2_0. no-interface view methods.sun. component.org/j2ee/schema/trans-timeout-1_0. web service endpoint methods.xsd urn:trans-timeout http://www.jboss.sun.5 Timer service The service is responsible to call the registered timeout methods of the different session beans.4. and message-listener interface methods.WildFly 8 21.3.sun.xsd http://java.

EAR name contain a version) the timer entry became orphaned and the timer event will not longer be fired. If one of those names are changed (e. or more than one. the name of the sub-deployment JAR and the Bean's name.3) it will be not longer available if JBoss is restarted or the application is redeployed. In case of a server restart the timeout method of a persistent timer will only be called directly if the specified time is elapsed.g. If the timer is not persistent (since EJB3.3) it will not longer be active after the server is restarted or the application is redeployed. interval is elapsed.1 see 18. 21. the timeout method will be called only once if one. JBoss Community Documentation Page 184 of 617 . 21.5.2.1 Single event timer The timer is will be started once at the specified time. In case of server downtime for a persistent timer. If the timer is not persistent (since EJB3.1 see 18.WildFly 8 A persistent timer will be identified by the name of the EAR.2.5.2 Recurring timer The timer will be started at the specified first occurrence and after that point at each time if the interval is elapsed. If the timer will be started during the last execution is not finished the execution will be suppressed with a warning to avoid concurrent execution.

The Java EE interceptors are expected to run after the container has done necessary invocation processing which involves security context propagation. i.5. transaction management and other such duties.6. In case of server start the timer is scheduled based on the @Schedule annotation. TODO: clarify whether this should happen concurrently/blocked or even fired only once like a recurring timer! Annotated calendar timer If the timer is non persistent it will not activated for missed events during the server is down. If the timer is non persistent it will not longer be active after the server is restarted or the application is redeployed. dayOfMonth="1". In case of such expired timer access to the given Timer object might throw a NoMoreTimeoutExcption or NoSuchObjectException. if the user applications have to intercept the call before certain container specific interceptor(s) are run. Such interceptors differed from the typical (portable) spec provided Java EE interceptors.WildFly 8 21. For example: @Schedule( .3 Calendar timer The timer will be started if the schedule expression match. year="2012") // start once at 01-01-2012 00:00:00 Programmatic calendar timer If the timer is persistent it will be fetched at server start and the missed timeouts are called concurrent. JBoss Community Documentation Page 185 of 617 . It will be automatically deactivated and removed if there will be no next expiration possible. Also a retry will be suppressed if the timeout method throw an Exception..1 Overview JBoss AS versions prior to WildFly8 allowed a JBoss specific way to plug-in user application specific interceptors on the server side so that those interceptors get invoked during an EJB invocation. If the timer is persistent (default if not deactivated by annotation) all missed events are fetched at server start and the annotated timeout method is called concurrent. As a result. these Java EE interceptors come too late into the picture.. If you set a specific year. TODO: clarify whether this should happen concurrently/blocked or even fired only once like a recurring timer! 21.e.6 Container interceptors 21. month="1". If a persistent timer contains an end date it will be executed once nevertheless how many times the execution was missed.

For example.doSomething().a container interceptor) N 5.k. The invocation on the bean. Invocation on the EJB instance's method The WildFly specific interceptors include the security context propagation. .. This feature is now implemented. As a result. AS5 allowed the use of JBoss AOP interceptors to do this. WildFly 8 doesn't have such a feature.2 Typical EJB invocation call path on the server A typical EJB invocation looks like this: Client application MyBeanInterface bean = lookupBean(). the "container interceptors" (let's call them that) might even decide break the invocation flow and not let the invocation proceed (for example: due to the invoking caller not being among the allowed user roles who can invoke the method on the bean). WildFly specific interceptor (a. WildFly specific interceptor (a.6.WildFly 8 21. 4. Previous versions of JBoss AS allowed a way to plug-in the user application specific interceptors (which relied on JBoss AS specific libraries) into this invocation flow so that they do run some application specific logic before the control reaches step#5 above. User application specific Java EE interceptor(s) (if any) 6.6..3 Feature request for WildFly There were many community users who requested for this feature to be made available in WildFly.k. WildFly specific interceptor (a.org/browse/AS7-5897 JIRA was raised. https://issues. In some cases.k.a container interceptor) 1 2.doSomething() triggers the following (only relevant portion of the flow shown below): 1. bean. transaction management and other container provided services. JBoss Community Documentation Page 186 of 617 . 21.a container interceptor) 2 3.jboss..

WildFly 8

21.6.4 Configuring container interceptors
As you can see from the JIRA https://issues.jboss.org/browse/AS7-5897, one of the goals of this feature
implementation was to make sure that we don't introduce any new WildFly specific library dependencies for
the container interceptors. So we decided to allow the Java EE interceptors (which are just POJO classes
with lifecycle callback annotations) to be used as container interceptors. As such you won't need any
dependency on any WildFly specific libraries. That will allow us to support this feature for a longer time in
future versions of WildFly.
Furthermore, configuring these container interceptors is similar to configuring the Java EE interceptors for
EJBs. In fact, it uses the same xsd elements that are allowed in ejb-jar.xml for 3.1 version of ejb-jar
deployment descriptor.

Container interceptors can only be configured via deployment descriptors. There's no annotation
based way to configure container interceptors. This was an intentional decision, taken to avoid
introducing any WildFly specific library dependency for the annotation.

Configuring the container interceptors can be done in jboss-ejb3.xml file, which then gets placed under the
META-INF folder of the EJB deployment, just like the ejb-jar.xml. Here's an example of how the container
interceptor(s) can be configured in jboss-ejb3.xml:

JBoss Community Documentation

Page 187 of 617

WildFly 8

jboss-ejb3.xml
<jboss xmlns="http://www.jboss.com/xml/ns/javaee"
xmlns:jee="http://java.sun.com/xml/ns/javaee"
xmlns:ci ="urn:container-interceptors:1.0">
<jee:assembly-descriptor>
<ci:container-interceptors>
<!-- Default interceptor -->
<jee:interceptor-binding>
<ejb-name>*</ejb-name>

<interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ContainerInterceptorOne</intercepto
</jee:interceptor-binding>
<!-- Class level container-interceptor -->
<jee:interceptor-binding>
<ejb-name>AnotherFlowTrackingBean</ejb-name>

<interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ClassLevelContainerInterceptor</int
</jee:interceptor-binding>
<!-- Method specific container-interceptor -->
<jee:interceptor-binding>
<ejb-name>AnotherFlowTrackingBean</ejb-name>

<interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.MethodSpecificContainerInterceptor<
<method>
<method-name>echoWithMethodSpecificContainerInterceptor</method-name>
</method>
</jee:interceptor-binding>
<!-- container interceptors in a specific order -->
<jee:interceptor-binding>
<ejb-name>AnotherFlowTrackingBean</ejb-name>
<interceptor-order>

<interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ClassLevelContainerInterceptor</int
<interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.MethodSpecificContainerInterceptor<
<interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ContainerInterceptorOne</intercepto
</interceptor-order>
<method>
<method-name>echoInSpecificOrderOfContainerInterceptors</method-name>
</method>
</jee:interceptor-binding>
</ci:container-interceptors>
</jee:assembly-descriptor>
</jboss>

The usage of urn:container-interceptors:1.0 namespace which allows the container-interceptors
elements to be configured
The container-interceptors element which contain the interceptor bindings
The interceptor bindings themselves are the same elements as what the EJB3.1 xsd allows for
standard Java EE interceptors
The interceptors can be bound either to all EJBs in the deployment (using the the * wildcard) or
individual bean level (using the specific EJB name) or at specific method level for the EJBs.

JBoss Community Documentation

Page 188 of 617

WildFly 8

The xsd for the urn:container-interceptors:1.0 namespace is available here
https://github.com/jbossas/jboss-as/blob/master/ejb3/src/main/resources/jboss-ejb-container-interceptors_1_0.xsd

The interceptor classes themselves are simple POJOs and use the @javax.annotation.AroundInvoke
to mark the around invoke method which will get invoked during the invocation on the bean. Here's an
example of the interceptor:
Example of container interceptor
public class ClassLevelContainerInterceptor {
@AroundInvoke
private Object iAmAround(final InvocationContext invocationContext) throws Exception {
return this.getClass().getName() + " " + invocationContext.proceed();
}
}

21.6.5 Container interceptor positioning in the interceptor
chain
The container interceptors configured for a EJB are guaranteed to be run before the WildFly provided
security interceptors, transaction management interceptors and other such interceptors thus allowing the
user application specific container interceptors to setup any relevant context data before the invocation
proceeds.

21.6.6 Semantic difference between container interceptor(s)
and Java EE interceptor(s) API
Although the container interceptors are modeled to be similar to the Java EE interceptors, there are some
differences in the API semantics. One such difference is that invoking on
javax.interceptor.InvocationContext.getTarget() method is illegal for container interceptors since these
interceptors are invoked way before the EJB components are setup or instantiated.

21.6.7 Testcase
This testcase in the WildFly codebase can be used for reference for implementing container interceptors in
user applications

https://github.com/jbossas/jboss-as/blob/master/testsuite/integration/basic/src/test/java/org/jboss/as/test/integration/ejb/con

JBoss Community Documentation

Page 189 of 617

WildFly 8

21.7 EJB3 subsystem configuration guide
This page lists the options that are available for configuring the EJB subsystem.
A complete example of the config is shown below, with a full explanation of each

JBoss Community Documentation

Page 190 of 617

WildFly 8

<subsystem xmlns="urn:jboss:domain:ejb3:1.2">
<session-bean>
<stateless>
<bean-instance-pool-ref pool-name="slsb-strict-max-pool"/>
</stateless>
<stateful default-access-timeout="5000" cache-ref="simple" clustered-cache-ref="clustered"/>
<singleton default-access-timeout="5000"/>
</session-bean>
<mdb>
<resource-adapter-ref resource-adapter-name="hornetq-ra"/>
<bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
</mdb>
<entity-bean>
<bean-instance-pool-ref pool-name="entity-strict-max-pool"/>
</entity-bean>
<pools>
<bean-instance-pools>
<strict-max-pool name="slsb-strict-max-pool" max-pool-size="20"
instance-acquisition-timeout="5" instance-acquisition-timeout-unit="MINUTES"/>
<strict-max-pool name="mdb-strict-max-pool" max-pool-size="20"
instance-acquisition-timeout="5" instance-acquisition-timeout-unit="MINUTES"/>
<strict-max-pool name="entity-strict-max-pool" max-pool-size="100"
instance-acquisition-timeout="5" instance-acquisition-timeout-unit="MINUTES"/>
</bean-instance-pools>
</pools>
<caches>
<cache name="simple" aliases="NoPassivationCache"/>
<cache name="passivating" passivation-store-ref="file" aliases="SimpleStatefulCache"/>
<cache name="clustered" passivation-store-ref="infinispan" aliases="StatefulTreeCache"/>
</caches>
<passivation-stores>
<file-passivation-store name="file"/>
<cluster-passivation-store name="infinispan" cache-container="ejb"/>
</passivation-stores>
<async thread-pool-name="default"/>
<timer-service thread-pool-name="default">
<data-store path="timer-service-data" relative-to="jboss.server.data.dir"/>
</timer-service>
<remote connector-ref="remoting-connector" thread-pool-name="default"/>
<thread-pools>
<thread-pool name="default">
<max-threads count="10"/>
<keepalive-time time="100" unit="milliseconds"/>
</thread-pool>
</thread-pools>
<iiop enable-by-default="false" use-qualified-name="false"/>
<in-vm-remote-interface-invocation pass-by-value="false"/> <!-- Warning see notes below about
possible issues -->
</subsystem>

JBoss Community Documentation

Page 191 of 617

WildFly 8

21.7.1 <session-bean>
<stateless>
This element is used to configure the instance pool that is used by default for stateless session beans. If it is
not present stateless session beans are not pooled, but are instead created on demand for every invocation.
The instance pool can be overridden on a per deployment or per bean level using jboss-ejb3.xml or the
org.jboss.ejb3.annotation.Pool annotation. The instance pools themselves are configured in the
<pools> element.

<stateful>
This element is used to configure Stateful Session Beans.
default-access-timeout This attribute specifies the default time concurrent invocations on the
same bean instance will wait to acquire the instance lock. It can be overridden via the deployment
descriptor or via the javax.ejb.AccessTimeout annotation.
cache-ref This attribute is used to set the default cache for non-clustered beans. It can be
overridden by jboss-ejb3.xml, or via the org.jboss.ejb3.annotation.Cache annotation.
clustered-cache-ref This attribute is used to set the default cache for clustered beans.

<singleton>
This element is used to configure Singleton Session Beans.
default-access-timeout This attribute specifies the default time concurrent invocations will wait
to acquire the instance lock. It can be overridden via the deployment descriptor or via the
javax.ejb.AccessTimeout annotation.

21.7.2 <mdb>
<resource-adaptor-ref>
This element sets the default resource adaptor for Message Driven Beans.

<bean-instance-pool-ref>
This element is used to configure the instance pool that is used by default for Message Driven Beans. If it is
not present they are not pooled, but are instead created on demand for every invocation. The instance pool
can be overridden on a per deployment or per bean level using jboss-ejb3.xml or the
org.jboss.ejb3.annotation.Pool annotation. The instance pools themselves are configured in the
<pools> element.

JBoss Community Documentation

Page 192 of 617

WildFly 8

21.7.3 <entity-bean>
This element is used to configure the behavior for EJB2 EntityBeans.

<bean-instance-pool-ref>
This element is used to configure the instance pool that is used by default for Entity Beans. If it is not present
they are not pooled, but are instead created on demand for every invocation. The instance pool can be
overridden on a per deployment or per bean level using jboss-ejb3.xml or the
org.jboss.ejb3.annotation.Pool annotation. The instance pools themselves are configured in the
<pools> element.

21.7.4
21.7.5 <pools>
21.7.6 <caches>
21.7.7 <passivation-stores>
21.7.8 <async>
This element enables async EJB invocations. It is also used to specify the thread pool that these invocations
will use.

21.7.9 <timer-service>
This element enables the EJB timer service. It is also used to specify the thread pool that these invocations
will use.

<data-store>
This is used to configure the directory that persistent timer information is saved to.

JBoss Community Documentation

Page 193 of 617

WildFly 8

21.7.10 <remote>
This is used to enable remote EJB invocations. It specifies the remoting connector to use (as defined in the
remoting subsystem configuration), and the thread pool to use for remote invocations.

21.7.11 <thread-pools>
This is used to configure the thread pools used by async, timer and remote invocations.

21.7.12 <iiop>
This is used to enable IIOP (i.e. CORBA) invocation of EJB's. If this element is present then the JacORB
subsystem must also be installed. It supports the following two attributes:
enable-by-default If this is true then all EJB's with EJB2.x home interfaces are exposed via IIOP,
otherwise they must be explicitly enabled via jboss-ejb3.xml.
use-qualified-name If this is true then EJB's are bound to the corba naming context with a
binding name that contains the application and modules name of the deployment (e.g.
myear/myejbjar/MyBean), if this is false the default binding name is simply the bean name.

JBoss Community Documentation

Page 194 of 617

WildFly 8

21.7.13 <in-vm-remote-interface-invocation>
By default remote interface invocations use pass by value, as required by the EJB spec. This element can
use used to enable pass by reference, which can give you a performance boost. Note WildFly will do a
shallow check to see if the caller and the EJB have access to the same class definitions, which means if you
are passing something such as a List<MyObject>, WildFly only checks the List to see if it is the same class
definition on the call & EJB side. If the top level class definition is the same, JBoss will make the call using
pass by reference, which means that if MyObject or any objects beneath it are loaded from different
classloaders, you would get a ClassCastException. If the top level class definitions are loaded from different
classloaders, JBoss will use pass by value. JBoss cannot do a deep check of all of the classes to ensure no
ClassCastExceptions will occur because doing a deep check would eliminate any performance boost you
would have received by using call by reference. It is recommended that you configure pass by reference
only on callers that you are sure will use the same class definitions and not globally. This can be done via a
configuration in the jboss-ejb-client.xml as shown below.
To configure a caller/client use pass by reference, you configure your top level deployment with a
META-INF/jboss-ejb-client.xml containing:

<jboss-ejb-client xmlns="urn:jboss:ejb-client:1.0">
<client-context>
<ejb-receivers local-receiver-pass-by-value="false"/>
</client-context>
</jboss-ejb-client>

JBoss Community Documentation

Page 195 of 617

WildFly 8

21.8 EJB IIOP Guide
21.8.1 Enabling IIOP
To enable IIOP you must have the JacORB subsystem installed, and the <iiop/> element present in the
ejb3 subsystem configuration. The standalone-full.xml configuration that comes with the distribution
has both of these enabled.
The <iiop/> element takes two attributes that control the default behaviour of the server, for full details see
EJB3 subsystem configuration guide.

21.8.2 Enabling JTS
To enable JTS simply add a <jts/> element to the transactions subsystem configuration.
It is also necessary to enable the JacORB transactions interceptor as shown below.

<subsystem xmlns="urn:jboss:domain:jacorb:1.1">
<orb>
<initializers transactions="on"/>
</orb>
</subsystem>

21.8.3 Dynamic Stub's
Downloading stubs directly from the server is no longer supported. If you do not wish to pre-generate your
stub classes JDK Dynamic stubs can be used instead. The enable JDK dynamic stubs simply set the
com.sun.CORBA.ORBUseDynamicStub system property to true.

21.8.4 Configuring EJB IIOP settings via jboss-ejb3.xml
TODO

21.9 jboss-ejb3.xml Reference
jboss-ejb3.xml is a custom deployment descriptor that can be placed in either ejb-jar or war archives. If
it is placed in an ejb-jar then it must be placed in the META-INF folder, in a web archive it must be placed in
the WEB-INF folder.
The contents of jboss-ejb3.xml are merged with the contents of ejb-jar.xml, with the
jboss-ejb3.xml items taking precedence.

JBoss Community Documentation

Page 196 of 617

WildFly 8

21.9.1 Example File
A simple example is shown below:

<?xml version="1.1" encoding="UTF-8"?>
<jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:s="urn:security:1.1"
xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee
http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd
http://java.sun.com/xml/ns/javaee
http://www.jboss.org/j2ee/schema/jboss-ejb3-spec-2_0.xsd
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
version="3.1" impl-version="2.0">
<enterprise-beans>
<message-driven>
<ejb-name>ReplyingMDB</ejb-name>
<ejb-class>org.jboss.as.test.integration.ejb.mdb.messagedestination.ReplyingMDB</ejb-class>
<activation-config>
<activation-config-property>
<activation-config-property-name>destination</activation-config-property-name>
<activation-config-property-value>java:jboss/mdbtest/messageDestinationQueue
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
</enterprise-beans>
<assembly-descriptor>
<s:security>
<ejb-name>DDMyDomainSFSB</ejb-name>
<s:security-domain>myDomain</s:security-domain>
<s:run-as-principal>myPrincipal</s:run-as-principal>
</s:security>
</assembly-descriptor>
</jboss:ejb-jar>

As you can see the format is largely similar to ejb-jar.xml, in fact they even use the same namespaces,
however jboss-ejb3.xml adds some additional namespaces of its own to allow for configuring non-spec
info. The format of the standard http://java.sun.com/xml/ns/javaee is well documented elsewhere,
this document will cover the non-standard namespaces.

The root namespace http://www.jboss.com/xml/ns/javaee

JBoss Community Documentation

Page 197 of 617

WildFly 8

Assembly descriptor namespaces
The following namespaces can all be used in the <assembly-descriptor> element. They can be used to
apply their configuration to a single bean, or to all beans in the deployment by using * as the ejb-name.

The security namespace urn:security
This allows you to set the security domain and the run-as principal for an EJB.

<s:security>
<ejb-name>*</ejb-name>
<s:security-domain>myDomain</s:security-domain>
<s:run-as-principal>myPrincipal</s:run-as-principal>
</s:security>

The resource adaptor namespace urn:resource-adapter-binding
This allows you to set the resource adaptor for an MDB.

<r:resource-adapter-binding>
<ejb-name>*</ejb-name>
<r:resource-adapter-name>myResourceAdaptor</r:resource-adapter-name>
</r:resource-adapter-binding>

The IIOP namespace urn:iiop
The IIOP namespace is where IIOP settings are configured. As there are quite a large number of options
these are covered in the IIOP guide.

The pool namespace urn:ejb-pool:1.0
This allows you to select the pool that is used by the SLSB or MDB. Pools are defined in the server
configuration (i.e. standalone.xml or domain.xml)

<p:pool>
<ejb-name>*</ejb-name>
<p:bean-instance-pool-ref>my-pool</p:bean-instance-pool-ref>
</p:pool>

The cache namespace urn:ejb-cache:1.0
This allows you to select the cache that is used by the SFSB. Caches are defined in the server configuration
(i.e. standalone.xml or domain.xml)

<c:cache>
<ejb-name>*</ejb-name>
<c:cache-ref>my-cache</c:cache-ref>
</c:cache>

JBoss Community Documentation

Page 198 of 617

0 This namespace is deprecated and as of WildFly 8 its use has no effect. When transaction is propagated from one AS to another then server from which transaction originates enlists the target AS as one of its subordinate XAResources and it uses standard XA two-phase protocol to perform commit/abort operations. describe in detail how transactions are propagated. The clustering behavior of EJBs is determined by the profile in use on the server. Transaction can span many ASs in arbitrary topology. This example consist of two application servers (denoted further as AS) and two database servers. 21.10. Orange squares indicate branches of transaction executing on a given node.10 JBoss remoting transaction propagation In Wildfly transaction can span many instances of application servers. how they are recovered in case of failure and what are the responsibilities of administrator. based on an example. 21. In this article we will.1 Propagation example On pictures below we see example which we will use to describe internals of transaction propagation. On picture 1 one can see flow of transaction before commit.WildFly 8 The clustering namespace urn:clustering:1. JBoss Community Documentation Page 199 of 617 .

After A decided to commit the transaction the two-phase commit starts. B writes data to database d2. It is possible that many branches of the same transaction are executing in the same XAResource. As we noted above in hierarchical transaction propagation architecture some nodes can be both coordinator and subordinate. A executes method of bean located in B. We will see such case in the following part of this article. As a result of this d1 is enlisted as XAResource in t. 5. Each time a XAResource is enlisted in transaction new branch of this transaction is created. Branch t:3. As a result of that d2 is enlisted as XAResource in t:2. We will denote xids in the form g:b where g is global transaction id and b is branch id. A writes data to database d1.WildFly 8 We will describe in more detail individual steps to see what's happening behind the curtain: 1. In this example after d1 is enlisted in t then branch t:1 of transaction t is created in d1. Global transaction id and branch id. XA transaction can have many branches which are part of one global transaction. Each of resources has a right to abort the transaction in prepare phase.in our example coordinator is t. Transaction receives an identifier t. On picture 2 we can see how sucessfull prepare would like in our example: JBoss Community Documentation Page 200 of 617 . Transaction is identified in XAResource by it's xid which is XA compliant transaction identifier. As a result of that B is enlisted in t as another XAResource and branch t:2 which denotes this transaction in B is created. It begins with the prepare phase. When B receives method invocation it learns that this invocation is part of a transaction. It means that during two phase commit this transaction will be coordinated by another transaction . Please note that B is both subordinate to A and a coordinator to d2. Because of that xids consist of two parts. 4. Because of that B makes transaction t:2 a subordinate transaction. A commits the transaction. Resource is prepared to commit the transaction if it can guarantee that it is able to commit or abort the transaction even in case of node failure. prepared resource must have written log entries which enable transaction commit or rollback to permanent store. A starts the transaction. that will denote the transaction t in d2 is created. Such node can declare itself prepared to it's coordinator if all of its subordinates are prepared. Put it another way. 3. Coordinator is responsible for making sure that all of it's subordinates are prepared. We will see how it is done in detail below. 2. If at least one resource return abort message the transaction has to be rolled back. This branch represents part of transaction executing in given XAResource.

A sends COMMIT t:1 message to d1. Note also that after transaction is prepared and commit/rollback decision is being made then this transaction can be executed correctly even in case of failure of one/many of the nodes.WildFly 8 6. 18. 17. On picture 3 we can see commit phase of successfully executed transaction: 13. We will look in the following part of this article how failure recovery works. B sends READY t:2 to A: B now knows that all of it's subordinates are prepared. Coordinator must wait till all of it's subordinates have acknowledge that they have finished processing the transaction. A sends PREPARE t:2 message to B. A makes the the decision to commit the transaction. coordinators which are subordinate to other node can acknowlegde that they finished processing the transaction only if all of their subordinate nodes have finished processing it. More about it in recovery section. If all subordinates were able to prepare transaction correctly then transaction can be committed. 15. d2 replies with READY t:3. 16. 12. Again. A sends PREPARE t:1 message to d1. 14. 7. A as a main transaction coordinator it learns that all of it's subordinates are ready to commit. B sends COMMIT t:3 message to d2: As with PREPARE B will be able to acknowledge correct COMMIT completion only after it receives ACK message from all it's subordinates. 19. so a result of that it can also mark itself as a prepared XAResource to A. Otherwise it must be rolled back. 10. A sends COMMIT t:2 message to B. 8. B sends ACK t:2 to A. A learns that transaction has finished successfully. B sends PREPARE t:3 message to d2: Before B could reply with READY it must make sure that all of it's subordinate branches are prepared. A must keep information of the transaction till all of it's subordinates have commited it. d2 sends ACK t:3 to B. 11. JBoss Community Documentation Page 201 of 617 . d1 replies with ACK t:1: This informs A that branch t:1 has committed successfully. d1 responds with READY t:1. 9. Based on the outcome of prepare phase coordinator on node which created the transaction can decide what to do with it.

Because of that it sends ROLLBACK message to all of them. The ROLLBACK message is propagated in the same way as COMMIT. As a result of that in step 10 it sends ABORT message to B.WildFly 8 What will happen if some of resources is unable to commit? The scenario is very similar. Let's suppose that d2 is unable to commit the transaction. B propagetes ABORT further to A. JBoss Community Documentation Page 202 of 617 . A learns that one of its subordinates is unable to commit.

That means that all locks aquired by t in d1 and d2 cannot be released till A recovers. In such situation there is no guarantee that transaction will be processed correctly. And what happens with d2 node? When node recovers it has to restore all the data to consistent state. Because of that periodically checks if node on which t:3 was running has already been recovered. heuristic outcomes Lets suppose that A fails after it decides to commit the transaction. d1 and d2 doesn't know what the result of commit is they have to keep their branches of t in prepared state. Such case is called heuristic outcomes of a transaction. It is not always the case that node can wait indefinitely for a coordinator to recover. If there are some changes done to d2 by transaction t then they all have to be reverted. It can read from its log that transaction t is in prepared state. A sends the COMMIT message to d1 but it is unable to send COMMIT message to node B. we can assume that failures during PREPARE phase will result in aborting of transaction. Failure of subordinate failure after prepare stage Lets suppose that after all nodes are prepared node B fails. In our example A is able to check that it hasn't committed branch of transaction identified by xid t:3. When node B is recovered A finds out about it and it sends COMMIT message to it. If transaction has not been prepared the node has right to revert it.10. As a result of that ROLLBACK is propagated to all nodes. Failure of coordinator after prepare stage. Because of that B is unable to sent PREPARE message to d2. Please note however that before A is recovered then d1 and d2 must be blocked. A has written in its log that it has committed the transaction t but it must collect ACK from all it's subordinate resources. When obtains this message it commits t and returns ACK.2 What happens when something goes wrong? Node failure during prepare stage Lets suppose that after data has been written to d2 the node on which it runs fails. if those nodes want to be sure that the transaction is executed correctly. In order to recover B must wait for action from A. Because B. In our example A knows that before it can finish processing t I must obtain ACK for all branches that it created. Generally. Please note also that even if the timeout wasn't exceeded before d2 recovers it can also revert the transaction during recovery. That's why some nodes can wait for some specified amount of time and if this time is exceeded they can decided themselves what to do with a transaction. When node B recovers it has to restore database to consistent state. If B sends d2 PREPARE message after recovery and before the timeout is exceeded then B can just reply with ABORT message. B cannot make any decision in this situation because it does not know what decision A made. When it recovers again it will read from it's log that it should send COMMIT to d1 and B. JBoss Community Documentation Page 203 of 617 .WildFly 8 21. d2 knows about it because it can not have record in its log which indicates that transaction has been prepared. A periodically checks if it has some pending transactions that require recovery. In case of heuristic outcomes occurrence it is a responsibility of administrator to check that all nodes that finished the transaction heuristically are in consistent state. B managed to send READY to A before failure so A decides to commit the transaction. It will do it and transaction will be completed. As a result of that in this scenario d2 knows what to do with t immediately after it is recovered. After timeout B decides that it is unable to prepare the transaction and it returns ABORT.

On picture 5 we can see how successfull commit invocation would look like in such scenario. This branch is executed on A. t:4 is prepared and committed as if it was executing on a node without any previous transaction branch.WildFly 8 21. Administrator is responsible for amending failed nodes and checking if any heuristic transaction completion took place.10. B invokes a method of a bean deployed in A and then A again writes data to d1. We can see that although t and t:4 are part of the same transaction they are prepared independent of eachother.3 Responisibities of an administrator Recovery infrastructure is able to perform recovery in all cases except heuristic outcomes. We can see that in such situation there are two branches of t executing on A. JBoss Community Documentation Page 204 of 617 . If there are many nodes which failed they can be restored in any order. branch merging Lets suppose that after step 4. In our example database d1 also has two transaction branches executing. that transactions can be merged by some XAResource if necessary. Another branch t:4 is created. Note however. Because of that any configured outbound-connections that were available during failed transaction execution must be present after recovery. In case some XAResource has completed the transaction heuristcally then administrator must check manually whether commit/rollback decision was consistent with transaction outcome and in case of inconsistencies repair it manually. this two branches can be merged so that they are seen as part of one transaction and they don't block eachother. 21.10.4 Cyclic transaction invocation. Connections to other servers that might have took part in transactions that require recovery are created based on remoting subsystem outbound-connections configuration. As a result transaction is propagated back from B to A. If database engine enables that. Branch t:4 is subordinate of t:3 and it is commited according to two phase protocol.

An alternate way of configuring a security domain.Stateless.xml deployment descriptor. Here's an example of how the configuration will look like: JBoss Community Documentation Page 205 of 617 . 21.jboss. It leaves it to the vendor implementations to allow such configurations.annotation.. instead of using annotation. Like with all other configurations.annotation. is to use jboss-ejb3.. The use of @SecurityDomain annotation lets the developer to point the container to the name of the security domain which is configured in the EJB3 subsystem in the standalone/domain configuration.SecurityDomain annotation allows the developer to configure the security domain for a bean.ejb. Here's an example: import org.11 Securing EJBs 21.. The configuration of the security domain in the EJB3 subsystem is out of the scope of this chapter..jboss.11.. these security related configurations can also be done via the deployment descriptor (ejb-jar. { . @Stateless @SecurityDomain("other") public class MyBean . @DenyAll) which can be used on EJB implementation classes and/or the business method implementations of the beans. the use of @org.2 Security Domain The Java EE spec doesn't mandate a specific way to configure security domain for a bean.xml). In WildFly 8. import javax. @PermitAll.WildFly 8 21.ejb3.1 Overview The Java EE spec specifies certain annotations (like @RolesAllowed. We won't be going into the details of Java EE specific annotations/deployment descriptor configurations in this chapter but instead will be looking at the vendor specific extensions to the security configurations.11.ejb3.SecurityDomain. the way they wish.

org/2001/XMLSchema-instance" xmlns:s="urn:security:1.w3.Name of the security domain which is configured in the EJB3 subsystem --> <s:security-domain>other</s:security-domain> </s:security> </assembly-descriptor> </jboss:ejb-jar> As you can see we use the security-domain element to configure the security domain.jar deployment or .1" version="3.com/xml/ns/javaee" xmlns:xsi="http://www.jboss.1" impl-version="2.war/WEB-INF folder of a . JBoss Community Documentation Page 206 of 617 .0"> <assembly-descriptor> <s:security> <!-.xml is expected to be placed in the .com/xml/ns/javaee" xmlns:jboss="http://www.WildFly 8 <?xml version="1. The jboss-ejb3.war deployment.sun.Even wildcard * is supported --> <ejb-name>MyBean</ejb-name> <!-.0" encoding="UTF-8"?> <jboss:ejb-jar xmlns="http://java.jar/META-INF folder of a .

. makes the bean secure. @RunAs. the absence of an explicitly configured security domain on the bean would leave the bean unsecured. on a secured bean Consider this example bean: @Stateless public class FooBean { @RolesAllowed("bar") public void doSomething() { . which meant that even if the doSomething method was configured with @RolesAllowed("bar") anyone even without the "bar" role could invoke on the bean. Prior to WildFly 8.11. } public void helloWorld() { . the bean isn't configured for any specific security domain. } .WildFly 8 21. However.3 Absence of security domain configuration but presence of other security metadata Let's consider the following example bean: @Stateless public class FooBean { @RolesAllowed("bar") public void doSomething() { . the security domain name is default to "other".4 Access to methods without explicit security metadata. even in the absence of an explicitly configured security domain. @DenyAll. @PermitAll. } } JBoss Community Documentation Page 207 of 617 ... In WildFly 8. @RunAsPrincipal) on the bean or any business method of the bean. } As you can see the doSomething method is configured to be accessible for users with role "bar".. In such cases. the presence of any security metadata (like @RolesAllowed. Users can explicitly configure an security domain for the bean if they want to using either the annotation or deployment descriptor approach explained earlier... 21.11.

WildFly 8 As you can see the doSomething method is marked for access for only users with role "bar". the default-missing-method-permissions-deny-access element accepts either a true or false value.org/2001/XMLSchema-instance" xmlns:s="urn:security:1.e.4"> .xml deployment descriptor at a per bean level or a per deployment level as follows: <?xml version="1. This behaviour can be controlled via the jboss-ejb3.1" version="3. notice that the method helloWorld doesn't have any specific security configurations. such methods which have no explicit security configurations.. as follows: <subsystem xmlns="urn:jboss:domain:ejb3:1. <default-missing-method-permissions-deny-access value="true"/> .0" encoding="UTF-8"?> <jboss:jboss xmlns="http://java. will be treated similar to a method with @DenyAll configuration. What that means is. This behaviour can also be configured at the EJB3 subsystem level so that it applies to all EJB3 deployments on the server. The value for this element can either be true or false.com/xml/ns/javaee" xmlns:jboss="http://www.w3.sun..Even wildcard * is supported where * is equivalent to all EJBs in the deployment --> <ejb-name>FooBean</ejb-name> <s:missing-method-permissions-deny-access>false</s:missing-method-permissions-deny-access> </s:security> </assembly-descriptor> </jboss:jboss> Notice the use of <missing-method-permissions-deny-access> element.0"> <assembly-descriptor> <s:security> <!-.. However. </subsystem> Again. which have no explicit security configurations.e. no one is allowed access to methods. In WildFly 8. If this element isn't configured then it is equivalent to a value of true i. That enables security on the bean (with security domain defaulted to "other"). the behaviour will be switched to be similar to @PermitAll.jboss..com/xml/ns/javaee" xmlns:xsi="http://www. in a secured bean.1" impl-version="2. no one is allowed access to the helloWorld method. A value of true makes the behaviour similar to @DenyAll and a value of false makes it behave like @PermitAll JBoss Community Documentation Page 208 of 617 . Setting this to false allows access to such methods for all users i. on secured beans.

quickstarts. let's consider a simple Calculator stateless bean which exposes a RemoteCalculator remote business interface. So let's get started: 22. int b).ejb. which is a WildFly-specific API and allows invocation on remote EJBs. then you'll have to expose atleast one remote view for that bean. we would like the users to know that we have introduced a new EJB client API. In this document. If you want those EJBs to be remotely invocable. int subtract(int a.jboss.1 Deploying your EJBs on the server side: Users who already have EJBs deployed on the server side can just skip to the next section. do remember to take a look at Remote EJB invocations via JNDI EJB client API or remote-naming project Before getting into the details. After you have read this article. you'll have to deploy your application containing the EJBs on the AS7 server.remote. For now.as. Here's the code: package org. This client API isn't based on JNDI. int b).stateless.org/ejbclient/. In this example. we'll just concentrate on the traditional JNDI based invocation on EJBs. So remote clients need not rely on JNDI API to invoke on EJBs. A separate document covering the EJB remote client API will be made available. /** * @author Jaikiran Pai */ public interface RemoteCalculator { int add(int a.WildFly 8 22 EJB invocations from a remote client using JNDI This chapter explains how to invoke EJBs from a remote client by using the JNDI API to first lookup the bean proxy and then invoke on that proxy. We'll also have a simple stateful CounterBean which exposes a RemoteCounter remote business interface. } JBoss Community Documentation Page 209 of 617 .jboss. As a first step. you can refer to the javadocs of the EJB client project at http://docs.

import javax.remote.stateless.jboss.class) public class CalculatorBean implements RemoteCalculator { @Override public int add(int a.quickstarts.remote.WildFly 8 package org.as. } @Override public int subtract(int a.ejb. int b) { return a + b.b.ejb.jboss. int getCount(). void decrement().stateful. /** * @author Jaikiran Pai */ public interface RemoteCounter { void increment(). } } package org.quickstarts.ejb. } JBoss Community Documentation Page 210 of 617 . int b) { return a .ejb.as.Stateless. /** * @author Jaikiran Pai */ @Stateless @Remote(RemoteCalculator. import javax.Remote.

So let's take a look at what the client code looks like for looking up the JNDI proxy and invoking on it. In WildFly. 22.Stateful.naming.client.quickstarts.ejb.InitialContext.jar" and deploy it to the server. Here's the entire client code which invokes on a stateless bean: package org.remote.ejb.jboss. Make sure that your deployment has been processed successfully and there aren't any errors.count.Context.WildFly 8 package org. import javax. } } Let's package this in a jar (how you package it in a jar is out of scope of this chapter) named "jboss-as-ejb-remote-app.stateful.ejb. import javax. you can either choose to use the WildFly 8 specific EJB client API to do the invocation or use JNDI to lookup a proxy for your bean and invoke on that returned proxy.jboss. In this chapter we will concentrate on the JNDI lookup and invocation and will leave the EJB client API for a separate chapter. } @Override public void decrement() { this.remote.quickstarts.2 Writing a remote client application for accessing and invoking the EJBs deployed on the server The next step is to write an application which will invoke the EJBs that you deployed on the server.ejb.count++. @Override public void increment() { this.count--. import javax.naming.as. /** * @author Jaikiran Pai */ @Stateful @Remote(RemoteCounter. } @Override public int getCount() { return this.class) public class CounterBean implements RemoteCounter { private int count = 0. JBoss Community Documentation Page 211 of 617 .as.Remote. import javax.

num2)). num2).out. } // try one more invocation. } /** * Looks up a stateless bean and invokes on it * * @throws NamingException */ private static void invokeStatelessBean() throws NamingException { // Let's lookup the remote stateless calculator final RemoteCalculator statelessRemoteCalculator = lookupRemoteStatelessCalculator().JBossSaslProvider. import java.RemoteCounter.ejb. System.remote. /** * A sample program which acts a remote client for a EJB deployed on AS7 server.println("Remote calculator returned sum = " + sum).stateless.Hashtable. System. if (sum != a + b) { throw new RuntimeException("Remote stateless calculator returned an incorrect sum " + sum + " .remote.add(a. * This program shows how to lookup stateful and stateless beans via JNDI and then invoke on them * * @author Jaikiran Pai */ public class RemoteEJBClient { public static void main(String[] args) throws Exception { // Invoke a stateless bean invokeStatelessBean(). if (difference != num1 . System.util.stateless.stateful.remote.as.quickstarts. int sum = statelessRemoteCalculator. System.out. int difference = statelessRemoteCalculator. org. System. org.println("Obtained a remote stateless calculator for invocation").WildFly 8 import javax. this time for subtraction int num1 = 3434.jboss.quickstarts.naming. } JBoss Community Documentation Page 212 of 617 .println("Subtracting " + num2 + " from " + num1 + " via the remote stateless calculator deployed on the server"). int num2 = 2332. b).quickstarts.RemoteCalculator.stateful. org. import import import import import org.num2) { throw new RuntimeException("Remote stateless calculator returned an incorrect difference " + difference + " .as.ejb.ejb.jboss.jboss.subtract(num1.NamingException.out.jboss.sasl. // invoke on the remote calculator int a = 204.security.CalculatorBean.as. import java.jboss.remote.as.println("Adding " + a + " and " + b + " via the remote stateless calculator deployed on the server").Security.out.quickstarts.CounterBean.expected sum was " + (a + b)). org.expected difference was " + (num1 . // Invoke a stateful bean invokeStatefulBean().out. int b = 340.println("Remote calculator returned difference = " + difference).ejb.

for (int i = 0. This is typically the jar name of the // EJB deployment.println("Incrementing counter"). // Since we haven't deployed the application as a . i++) { System. i < NUM_TIMES.increment(). System.out. We haven't specified a distinct name for // our EJB deployment.naming"). final Context context = new InitialContext(jndiProperties).println("Counter will now be decremented " + NUM_TIMES + " times"). the app name for us will be an empty string final String appName = "". // The EJB name which by default is the simple class name of the bean implementation JBoss Community Documentation Page 213 of 617 . System.client.out. However. System. but can be overridden via the ejb-jar. System.out.ear suffix. This is typically the ear name // without the . // The app name is the application name of the deployed EJBs.println("Count after increment is " + statefulRemoteCounter. we have deployed the EJBs in a jboss-as-ejb-remote-app. without the .xml // In this example. so the module name is // jboss-as-ejb-remote-app final String moduleName = "jboss-as-ejb-remote-app". the application name could be overridden in the application.jboss.ear.println("Count after decrement is " + statefulRemoteCounter. // This is the module name of the deployed EJBs on the server.decrement(). // invoke on the remote counter bean final int NUM_TIMES = 20.out.jar suffix.out.URL_PKG_PREFIXES. } } /** * Looks up and returns the proxy to remote stateless calculator bean * * @return * @throws NamingException */ private static RemoteCalculator lookupRemoteStatelessCalculator() throws NamingException { final Hashtable jndiProperties = new Hashtable().getCount()). so this is an empty string final String distinctName = "". i--) { System.out. jndiProperties. "org.jar.getCount()). statefulRemoteCounter.println("Obtained a remote stateful counter for invocation"). // AS7 allows each deployment to have an (optional) distinct name.println("Decrementing counter").WildFly 8 } /** * Looks up a stateful bean and invokes on it * * @throws NamingException */ private static void invokeStatefulBean() throws NamingException { // Let's lookup the remote stateful counter final RemoteCounter statefulRemoteCounter = lookupRemoteStatefulCounter().xml of the // EJB deployment on the server. for (int i = NUM_TIMES.ejb.put(Context. i > 0. } // now decrementing System.println("Counter will now be incremented " + NUM_TIMES + " times"). statefulRemoteCounter.out.

lookup("ejb:" + appName + "/" + moduleName + "/" + distinctName + "/" + beanName + "!" + viewClassName + "?stateful").class. // This is the module name of the deployed EJBs on the server.class. without the . the app name for us will be an empty string final String appName = "". the application name could be overridden in the application. // The EJB name which by default is the simple class name of the bean implementation class final String beanName = CounterBean. // the remote view fully qualified class name final String viewClassName = RemoteCalculator. final Context context = new InitialContext(jndiProperties).class.xml // In this example.URL_PKG_PREFIXES. we have deployed the EJBs in a jboss-as-ejb-remote-app.client. // the remote view fully qualified class name final String viewClassName = RemoteCounter. } /** * Looks up and returns the proxy to remote stateful counter bean * * @return * @throws NamingException */ private static RemoteCounter lookupRemoteStatefulCounter() throws NamingException { final Hashtable jndiProperties = new Hashtable().class. // AS7 allows each deployment to have an (optional) distinct name.ejb.getSimpleName().getSimpleName().WildFly 8 class final String beanName = CalculatorBean.jar. However. jndiProperties. We haven't specified a distinct name for // our EJB deployment. "org.naming").jboss. so this is an empty string final String distinctName = "". } } The entire server side and client side code is hosted at the github repo here ejb-remote JBoss Community Documentation Page 214 of 617 .getName().ear suffix.xml of the // EJB deployment on the server.lookup("ejb:" + appName + "/" + moduleName + "/" + distinctName + "/" + beanName + "!" + viewClassName). // The app name is the application name of the deployed EJBs. // let's do the lookup return (RemoteCalculator) context.ear. // Since we haven't deployed the application as a . This is typically the jar name of the // EJB deployment.jar suffix. // let's do the lookup (notice the ?stateful string as the last part of the jndi name for stateful bean lookup) return (RemoteCounter) context. so the module name is // jboss-as-ejb-remote-app final String moduleName = "jboss-as-ejb-remote-app".put(Context. This is typically the ear name // without the . but can be overridden via the ejb-jar.getName().

If a deployment doesn't use distinct-name then.jar suffix) that you have deployed on the server and the contains your EJBs. module-name : This is the name of the . for remote access to EJBs. In AS7.xml. The rest of the parts in the jndi name are as follows: app-name : This is the name of the . More about the purpose and usage of this will be explained in a separate chapter. Java EE 6 allows you to override the module name. while doing the lookup.war or a plain .jar (without the .jar (like we did in step 1).WildFly 8 The code has some comments which will help you understand each of those lines. EJBs can also be deployed in a . we'll do a lookup of the EJB using a JNDI name.ear suffix) that you have deployed on the server and contains your EJBs. The bean name is typically the unqualified classname of the bean implementation class.war then the module name is the . In such cases where the deployment isn't an . you use the ejb: namespace with the following syntax: For stateless beans: ejb:<app-name>/<module-name>/<distinct-name>/<bean-name>!<fully-qualified-classname-of-the-remote-interface> For stateful beans: ejb:<app-name>/<module-name>/<distinct-name>/<bean-name>!<fully-qualified-classname-of-the-remote-interface>?s The ejb: namespace identifies it as a EJB lookup and is a constant (i. but can be overriden through either ejb-jar. Java EE 6 allows you to override the application name. If the EJBs are deployed in a . As a first step in the client code. then the app-name must be an empty string.e. JBoss Community Documentation Page 215 of 617 . for distinct-name bean-name : This is the name of the bean for which you are doing the lookup. to a name of your choice by setting it in the application. The interface should be one of the remote interfaces exposed by the bean on the server. But we'll explain here in more detail what the code does.ear (without the .war suffix).xml of your deployment.ear file. If the deployment uses uses such an override then the app-name used in the JNDI name should match that name. The bean name part cannot be an empty string in the JNDI name. use an empty string in the JNDI name. The fully qualified class name part cannot be an empty string in the JNDI name. by setting it in the ejb-jar.xml/web.war name (without the .xml or via annotations. fully-qualified-classname-of-the-remote-interface : This is the fully qualified class name of the interface for which you are doing the lookup. If the deployment uses such an override then the module-name used in the JNDI name should match that name. Module name part cannot be an empty string in the JNDI name distinct-name : This is a WildFly-specific name which can be optionally assigned to the deployments that are deployed on the server. doesn't change) for doing EJB lookups.

for your deployed EJBs. Some of you might be wondering.client.RemoteCounter.RemoteCounter?stateful That's what the lookupRemoteStatefulCounter() method in the above client code uses. jndiProperties.ejb.stateless.ejb. "org.naming.remote. The answer is in AS7.jboss. so that an appropriate session can be created.ejb.stateful.jboss.client. we have setup the InitialContext and also have the JNDI name ready to do the lookup.naming So at this point.client.naming. The Context. Now that we know of the JNDI name.remote. Now that we know the syntax.stateless.remote. let's see our code and check what JNDI name it uses.as. final Context context = new InitialContext(jndiProperties).quickstarts.RemoteCalculator That's what the lookupRemoteStatelessCalculator() method in the above client code uses. the proxies returned via JNDI name lookup for ejb: namespace do not connect to the server unless an invocation on those proxies is done. So the JNDI name itself is expected to indicate that the client is looking up a stateful bean.factory. a new session gets created on JNDI lookup and the EJB client API implementation doesn't contact the server during the JNDI lookup to know what kind of a bean the JNDI name represents (we'll come to this in a while). which (atleast) contains the following property: java. Here we are creating a JNDI InitialContext object by passing it some JNDI properties.jar (without any ear) and since we are looking up the org. our JNDI name will be: ejb:/jboss-as-ejb-remote-app//CalculatorBean!org.as.jboss.jar and which exposes the org. will be returned.jboss.quickstarts.naming" has a URLContextFactory implementation which will be used by the JNDI APIs to parse and return an object for ejb: namespace lookups.ejb.stateful.ejb.URL_PKG_PREFIXES. This is necessary because we should let the JNDI API know what handles the ejb: namespace that we use in our JNDI names for lookup. Since our stateless EJB named CalculatorBean is deployed in a jboss-as-ejb-remote-app.as.quickstarts. You can either pass these properties to the constructor of the InitialContext class or have a jndi.url.ejb. how the JNDI implementation knew which server address to look. For the stateful EJB named CounterBean which is deployed in hte same jboss-as-ejb-remote-app.put(Context.ejb.URL_PKG_PREFIXES is set to org.jboss.RemoteCalculator remote interface.jboss. JBoss Community Documentation Page 216 of 617 .jboss. The "org.WildFly 8 For stateful beans.properites file in the classpath of the client application. the JNDI name expects an additional "?stateful" to be appended after the fully qualified interface name part. let's take a look at the following piece of code in the lookupRemoteStatelessCalculator(): final Hashtable jndiProperties = new Hashtable(). the JNDI name will be: ejb:/jboss-as-ejb-remote-app//CounterBean!org.client.remote.ejb.naming").as.jboss. This is because for stateful beans.quickstarts. You can now do the lookup and the appropriate proxy which will be castable to the remote interface that you used as the fully qualified class name in the JNDI name.pkgs=org.

if you have a AS7 server at 10. We can see here that the proxy returned after the lookup is used to invoke the add(. int b = 340. Such an EJB receiver will be capable enough to communicate to the server via the JBoss specific EJB remote client protocol (details of which will be explained in-depth in a separate chapter).add(a. Each EJB receiver is capable of handling invocations on different EJBs. The jboss-ejb-client.20.40 IP address at port 4447. That EJB client context will then be used (internally) by the JNDI implementation to handle invocations on the bean proxy. For example.. 22. The EJB client context can be associated with multiple EJB receivers. System.30. The client will have to place a jboss-ejb-client.WildFly 8 Now let's get to the point where we invoke on this returned proxy: // Let's lookup the remote stateless calculator final RemoteCalculator statelessRemoteCalculator = lookupRemoteStatelessCalculator().20. This is a WildFly-specific API. Now that we know what a EJB client context is and what a EJB receiver is. It's at this point that the JNDI implementation (which is backed by the EJB client API) needs to know the server details.out. int sum = statelessRemoteCalculator. whereas a EJB receiver named "Blah" might be able to handle invocation on a bean identified by app-B/module-B/distinctName-B/BeanB!RemoteBean. System.) method of the bean.30.20.30. let's see how we can setup a client context with 1 EJB receiver which can connect to 10.properties file in the classpath of the application. So let's now get to the important part of setting up the EJB client context properties. then you can setup a EJB receiver which knows its target address is 10. an EJB receiver "Foo" might be able to handle invocation on a bean identified by app-A/module-A/distinctinctName-A/Bar!RemoteBar.properties can contain the following properties: JBoss Community Documentation Page 217 of 617 . For example..out.println("Obtained a remote stateless calculator for invocation").40 IP address which has its remoting port opened at 4447 and if that's the server on which you deployed that CalculatorBean.println("Adding " + a + " and " + b + " via the remote stateless calculator deployed on the server"). Each such EJB receiver knows about what set of EJBs it can handle and each of the EJB receiver knows which server target to use for handling the invocations on the bean.3 Setting up EJB client context properties A EJB client context is a context which contains contextual information for carrying out remote invocations on EJBs. // invoke on the remote calculator int a = 204.40:4447. b).

create.Options. Internally.Options.host=10. The connection names are just logical and are used grouping together the connection configuration properties later on in the properties file. There can be more than one connections that are configured..connection.create.> properties: remote.options.connections" property uses a comma separated value of connection "names".name property.options.org.xnio.xnio.options." prefix Next we'll see: remote.20. The endpoint.create.connection. Similarly other properties can be passed too.name=client-endpoint remote.connectionprovider.40 remote.properties file.xnio.properties We'll see what each of it means. The endpoint. Next is the remote. it will default to "config-based-ejb-client-endpoint" name.default.username=appuser remote.options.connections=default This is where you define the connections that you want to setup for communication with the remote server.xnio.default.SSL_ENABLED=false The "remote.connectionprovider.default. For example: JBoss Community Documentation Page 218 of 617 .Options.connectionprovider.connection.create.options.name property represents the name that will be used to create the client side of the enpdoint..connect.password=apppassword The above properties file is just an example.connectionprovider. We mentioned earlier that the EJB receivers will communicate with the server for EJB invocations.30." property prefix can be used to pass the options that will be used while create the connection provider which will handle the "remote:" protocol. First the endpoint..name property is optional and if not specified in the jboss-ejb-client.port = 8080 remote.SSL_ENABLED=false remote.org. The actual file that was used for this sample program is available here for reference jboss-ejb-client. The "remote.default. That property will then be used during the connection provider creation.SSL_ENABLED" property value as false.<.connection. In this example we use the "remote.options.connectionprovider. just append it to the "remote.create.connectionprovider. they use JBoss Remoting project to carry out the communication.SASL_POLICY_NOANONYMOUS=false remote." property prefix to pass the "org.options.connection.Options. The example above sets up a single remote connection named "default".WildFly 8 endpoint.connections=default remote.create.org.default.

xml) by default.default.sh (or. The EJB client API uses the http port.30.xml or domain.org. security-realm is enabled by default.connection.20.password=apppassword The given user/password must be set by using the command bin/add-user.connections=one.default.connect. Similarly we set the "port" for that connection to 4447. The connection name here is "default" and we are setting the "host" property of that connection to point to 10.port = 8080 remote. We then use the "remote. that will setup 2 EJB receivers that will be added to the EJB client context.30. Here's an example of setting up multiple connections with different properties for each of those: JBoss Community Documentation Page 219 of 617 .connect.bat).host=10.username=appuser remote." prefix for specifying the connection specific property. for communicating with the server for remote invocations. The user and password must be set because the security-realm is enabled for the subsystem remoting (see standalone*.default.<connection-name>.connection. Ultimately.connection.options.<connection-name>.connection.SASL_POLICY_NOANONYMOUS=false As you can see we are using the "remote. two Here we are listing 2 connections named "one" and "two".connection. each of the connections will map to a EJB receiver." property prefix to setup options that will be used during the connection creation.connection. Each of these connections will be configured with the connection specific properties as follows: remote.WildFly 8 remote. with the http-upgrade functionality. So if you have 2 connections.connection.40. By default WildFly uses 8080 as the remoting port.40 remote.options.Options.default. If you do not need the security for remoting you might remove the attribute security-realm in the configuration. so that's the port we use in our client programs (unless the server is configured for some other http port) remote.xnio.default.20.

SASL_POLICY_NOANONYMOUS=false remote.connections=one.connection.Options.path=/home/me/my-client/custom-jboss-ejb-client.path" system property which points to a properties file on your filesystem.org.file.connection.file.txt to add this jar as a Maven dependency.jar.properties file can be setup and placed in the classpath.connect.Options.one. Place this jar in the classpath of your client application.two.options.create.one.port=6999 remote. If you are using Maven to build the client application.5 Setting up the client classpath with the jars that are required to run the client application A jboss-client jar is shipped in the distribution. It's available at WILDFLY_HOME/bin/client/jboss-client.properties.WildFly 8 remote.connect.connection. you can specify a different file of your choice by setting the "jboss. then please follow the instructions in the WILDFLY_HOME/bin/client/README.connectionprovider.port=7999 remote.SSL_ENABLED=false remote.properties in the classpath.org.ejb.4 Using a different file for setting up EJB client context The EJB client code will by default look for jboss-ejb-client.ejb.properties.SASL_POLICY_NOANONYMOUS=false As you can see we setup 2 connections "one" and "two" which both point to "localhost" as the "host" but different ports.options.client.xnio. So that's how the jboss-ejb-client.client. Each of these connections will internally be used to create the EJB receivers in the EJB client context.xnio.properties" 22.one.host=localhost remote. However. containing the client context configurations.host=localhost remote.connection.xnio.org. JBoss Community Documentation Page 220 of 617 . An example for that would be "-Djboss.connection.two. 22.two.options.Options.connection. two remote.

You'll also need to have your application's bean interface jars and other jars that are required by your application.factory. in the client classpath JBoss Community Documentation Page 221 of 617 .naming. The location of the jar is mentioned above. To summarize: On the server side you need to deploy EJBs which expose the remote views. On the client side you need a client program which: Has a jboss-ejb-client.pkgs property or passes that as a property to the InitialContext constructor Setup the client classpath to include the jboss-client jar that's required for remote invocation of the EJBs.properties to specify the java.properties in its classpath to setup the server connection information Either has a jndi.url.6 Summary In the above examples. we saw what it takes to invoke a EJB from a remote client.WildFly 8 22.

Note that this chapter deals with the case where the bean is deployed on the "Destination Server" but not on the "Client Server".ear.*> // EJB classes Note that packaging itself isn't really important in the context of this article.jar).ear | |---.myejb. as "Client Server" and the server on which the bean is deployed as the "Destination Server". we'll consider a EJB which is packaged in a myejb. .myapp.war or .jar | | | |---. JBoss Community Documentation Page 222 of 617 . from which the invocation happens to the EJB.1 Application packaging In this example. 23. This is different from invoking the EJBs from a remote standalone client Let's call the server.ear.<org.ejb. Here's how it would look like: myapp. You can deploy the EJBs in any standard way (.jar which is within a myapp.WildFly 8 23 EJB invocations from a remote server instance The purpose of this chapter is to demonstrate how to lookup and invoke on EJBs deployed on an WildFly server instance from another WildFly server instance.

ejb. } package org. have a pleasant day!". JBoss Community Documentation Page 223 of 617 . our "client server" will be communicating with the "destination server".Stateless. So let's start with the necessary configurations for this. we'll consider a simple stateless session bean which is as follows: package org. @Stateless @Remote (Greeter.class) public class GreeterBean implements Greeter { @Override public String greet(String user) { return "Hello " + user + ".ejb. import javax. we'll have to configure user credentials which we will be using during this communication.ejb. So in order to allow this communication to happen successfully. import javax.myapp. } } 23.3 Security WildFly 8 is secure by default. Remember that in this example.2 Beans In our example. public interface Greeter { String greet(String user).WildFly 8 23. What this means is that no communication can happen with an WildFly instance from a remote client (irrespective of whether it is a standalone client or another server instance) without passing the appropriate credentials.myapp.ejb.Remote.

4 Configuring a user on the "Destination Server" As a first step we'll configure a user on the destination server who will be allowed to access the destination server. We create the user using the add-user script that's available in the JBOSS_HOME/bin folder.1.properties' Added user 'ejb' to file '/jboss-as-7.1. The important bits to remember are the user we have created in this example is ejb and the password is test.properties) (a): b Enter the details of the new user to add.b) Application User (application-users. You do not require the server to be started to add a user using the add-user script.properties' Added user 'ejb' with roles to file '/jboss-as-7.Final/standalone/configuration/application-users. Running the add-user script is an interactive process and you will see questions/output as follows: add-user jpai@jpai-laptop:bin$ . or leave blank for none)\[&nbsp.Final/domain/configuration/application-roles.properties' As you can see in the output above we have now configured a user on the destination server who'll be allowed to access this server. we'll be configuring a Application User named ejb and with a password test in the ApplicationRealm.1.a) Management User (mgmt-users.WildFly 8 23. \]: About to add user 'ejb' for realm 'ApplicationRealm' Is this correct yes/no? yes Added user 'ejb' to file '/jboss-as-7. Realm (ApplicationRealm) : Username : ejb Password : Re-enter Password : What roles do you want this user to belong to? (Please enter a comma separated list. Note that you can use any username and password combination you want to.1. JBoss Community Documentation Page 224 of 617 .sh What type of user do you wish to add? &nbsp.1. We'll use this user credentials later on in the client server for communicating with this server.1. In this example.properties' Added user 'ejb' with roles to file '/jboss-as-7.Final/standalone/configuration/application-roles.properties) &nbsp.1.Final/domain/configuration/application-users.1./add-user.

ear in our case) will be deployed to "Destination Server". The startup command will look like: . we have built a EJB application and deployed it on the "Destination Server". The " remote-outbound-connection" configuration indicates that a outbound connection will be created to a remote server instance from that server. It's very important to note that if you are starting both the server instances on the same machine. we need to let the server know about the "Destination Server"'s EJB remoting connector. 23.sh -server-config=standalone-full. we'll use the standalone server and use the standalone-full.name=<add appropriate value here> 23. You can do that by passing an appropriate value for -Djboss. JBoss Community Documentation Page 225 of 617 . You can either use the Command Line Interface or the Admin console or any IDE or manually copy it to JBOSS_HOME/standalone/deployments folder (for standalone server).name system property.7 Configuring the "Client Server" to point to the EJB remoting connector on the "Destination Server" As a first step on the "Client Server".6 Deploying the application The application (myapp.node.xml -Djboss. Now let's move to the "Client Server" which acts as the client for the deployed EJBs on the "Destination Server". The "remote-outbound-connection" will be backed by a " outbound-socket-binding" which will point to a remote host and a remote port (of the "Destination Server").WildFly 8 23.name system property to the startup script: . So far./standalone.sh -server-config=standalone-full. The process of deploying the application is out of scope of this chapter. In this example.5 Start the "Destination Server" As a next step towards running this example.node. we'll start the "Destination Server".xml configuration. So let's see how we create these configurations. then each of those server instances must have a unique jboss.node. Just ensure that the application has been deployed successfully. we'll have to add a "remote-outbound-connection" to the remoting subsystem on the "Client Server"./standalone.xml Ensure that the server has started without any errors. over which it can communicate during the EJB invocations. To do that.

let's use in the in the security realm that we are going to configure on the "client server". I used this online site which generates the base64 encoded string. That can lead to incorrect encoded versions being generated. slave domain controller? Now that we have generated that base64 encoded password.binding. /core-service=management/security-realm=ejb-security-realm:add() /core-service=management/security-realm=ejb-security-realm/server-identity=secret:add(value=dGVzdA==) JBoss Community Documentation Page 226 of 617 . the base64 encoded version is dGVzdA== While generating the base64 encoded string make sure that you don't have any trailing or leading spaces for the original password. So for the test password. So our first task here would be to create the base64 encoded version of the password test.port-offset=100 23.sh -server-config=standalone-full. We have copied the entire server installation to a different folder and while starting the "Client Server" we'll use a port-offset (of 100 in this example) to avoid port conflicts: . I'll first shutdown the client server and edit the standlaone-full.g.xml -Djboss.socket. Now on the "client server" we'll create a security-realm which will be used to pass the user information.xml file to add the following in the <management> section Now let's create a "security-realm" for the base64 encoded password. we'll start the "Client Server" on the same machine as the "Destination Server". Earlier we created a user on the destination server who'll be allowed to communicate with that server. You can use any utility which generates you a base64 version for a string./standalone. With new versions the add-user script will show the base64 password if you type 'y' if you've been ask Is this new user going to be used for one AS process to connect to another AS process e. Earlier we created a user named ejb and password test.9 Create a security realm on the client server Remember that we need to communicate with a secure destination server.WildFly 8 23. In this example we'll use a security realm which stores a Base64 encoded password and then passes on that credentials when asked for. In order to do that the client server has to pass the user credentials to the destination server.8 Start the "Client Server" In this example.

<security-realm name="ejb-security-realm"> <server-identities> <secret value="dGVzdA=="/> </server-identities> </security-realm> </security-realms> . As you can see I have created a security realm named "ejb-security-realm" (you can name it anything) with the base64 encoded password. So that completes the security realm configuration for the client server. so you have to restart the server before you can use this change. upon successful invocation of this command. Now let's move on to the next step.WildFly 8 Notice that the CLI show the message "process-state" => "reload-required". JBoss Community Documentation Page 227 of 617 .xml <management> <security-realms> .. the following configuration will be created in the management section: standalone-full....

binding.WildFly 8 23. in the remoting subsystem and uses the previously created "remote-ejb" outbound-socket-binding (notice the outbound-socket-binding-ref in that command) with the http-remoting protocol. security-realm=ejb-security-realm. we also set the security-realm attribute to point to the security-realm that we created in the previous step.10 Create a outbound-socket-binding on the "Client Server" Let's first create a outbound-socket-binding which points the "Destination Server"'s host and port. JBoss Community Documentation Page 228 of 617 .port-offset:0}"> . named "remote-ejb-connection" (we can name it anything)... Note that the host information should match the host/IP of the "Destination Server" (in this example we are running on the same machine so we use "localhost") and the port information should match the http-remoting connector port used by the EJB subsystem (by default it's 8080). Also notice that we have set the username attribute to use the user name who is allowed to communicate with the destination server.11 Create a "remote-outbound-connection" which uses this newly created "outbound-socket-binding" Now let's create a "remote-outbound-connection" which will use the newly created outbound-socket-binding (pointing to the EJB remoting connector of the "Destination Server"). username=ejb) The above command creates a remote-outbound-connection. Furthermore. We'll continue to use the CLI to create this configuration: /subsystem=remoting/remote-outbound-connection=remote-ejb-connection:add(outbound-socket-binding-ref=remote-ej protocol=http-remoting.xml (the file which we used to start the server) was updated with the following outbound-socket-binding in the socket-binding-group: <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss. When this command is run successfully. <outbound-socket-binding name="remote-ejb"> <remote-destination host="localhost" port="8080"/> </outbound-socket-binding> </socket-binding-group> 23.socket. We'll use the CLI to create this configuration: /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-ejb:add(host=localhos port=8080) The above command will create a outbound-socket-binding named "remote-ejb" (we can name it anything) which points to "localhost" as the host and port 8080 as the destination port. we'll see that the standalone-full.

Our next step is to deploy an application on the "Client Server" which will invoke on the bean deployed on the "Destination Server".1"> .. that's all we need on the "Client Server".WildFly 8 What this step does is. This way when a connection has to be established from the client server to the destination server. on the client server. the following configuration will be created in the remoting subsystem: <subsystem xmlns="urn:jboss:domain:remoting:1. Now let's run the following two operations to set some default connection creation options for the outbound connection: /subsystem=remoting/remote-outbound-connection=remote-ejb-connection/property=SASL_POLICY_NOANONYMOUS:add(valu /subsystem=remoting/remote-outbound-connection=remote-ejb-connection/property=SSL_ENABLED:add(value=false) Ultimately. <outbound-connections> <remote-outbound-connection name="remote-ejb-connection" outbound-socket-binding-ref="remote-ejb" protocol="http-remoting" security-realm="ejb-security-realm" username="ejb"> <properties> <property name="SASL_POLICY_NOANONYMOUS" value="false"/> <property name="SSL_ENABLED" value="false"/> </properties> </remote-outbound-connection> </outbound-connections> </subsystem> From a server configuration point of view... upon successful invocation of this command. it creates a outbound connection. to the remote destination server and sets up the username to the user who allowed to communicate with that destination server and also sets up the security-realm to a pre-configured security-realm capable of passing along the user credentials (in this case the password). JBoss Community Documentation Page 229 of 617 . the connection creation logic will have the necessary security credentials to pass along and setup a successful secured connection.

myapp.ear). followed by invocation on the proxy).e. the same location where you place any web.META-INF | | | |--.war/WEB-INF/ folder (i.xml | |--. You can even use a .xml is expected to be placed in . then the jboss-ejb-client.WEB-INF/classes | | | | | |---.war | | | |--.war deployment.xml are explained next. The code remains the same (JNDI lookup. we'll use . But like previously mentioned. If your application is deployed as a top level . The important part to notice in this client application is the file jboss-ejb-client.ear packaging for the client application too. EJB receivers). This jboss-ejb-client.xml file).xml contains the EJB client configurations which will be used during the EJB invocations for finding the appropriate destinations (also known as.<org.ear | |--.FooServlet> // classes in the web app In the client application we'll use a servlet which invokes on the bean deployed on the "Destination Server".xml which is packaged in the META-INF folder of a top level deployment (in this case our client-app.war or . We can even invoke the bean on the "Destination Server" from a EJB on the "Client Server".jboss-ejb-client. The contents of the jboss-ejb-client. Here's how our client application packaging will look like: client-app.jar deployments.WildFly 8 23. JBoss Community Documentation Page 230 of 617 .12 Packaging the client application on the "Client Server" Like on the "Destination Server". that's not mandatory.web.

xml The jboss-ejb-client.0"> <client-context> <ejb-receivers> <remoting-ejb-receiver outbound-connection-ref="remote-ejb-connection"/> </ejb-receivers> </client-context> </jboss-ejb-client> You'll notice that we have configured the EJB client context (for this application) to use a remoting-ejb-receiver which points to our earlier created "remote-outbound-connection" named " remote-ejb-connection".xml will look like: <jboss-ejb-client xmlns="urn:jboss:ejb-client:1. JBoss Community Documentation Page 231 of 617 . Just ensure that the application is deployed successfully. 23. The process of deploying the application is out of scope.13 Contents on jboss-ejb-client. This links the EJB client context to use the "remote-ejb-connection" which ultimately points to the EJB remoting connector on the "Destination Server".WildFly 8 23.14 Deploy the client application Let's deploy the client application on the "Client Server". You can use either the CLI or the admin console or a IDE or deploy manually to JBOSS_HOME/standalone/deployments folder. of this chapter.

JBoss Community Documentation Page 232 of 617 . public void invokeOnBean() { try { final Hashtable props = new Hashtable().put(Context. So let's see how it looks like: import javax.naming"). import java. // create the InitialContext final Context context = new javax.out.org/author/display/AS71/EJB+invocations+from+a+remote+client+using+JNDI final Greeter bean = (Greeter) context.InitialContext.ejb.greet("Tom").WildFly 8 23.jboss. // Lookup the Greeter bean using the ejb: namespace syntax which is explained here https://docs.class.InitialContext(props).Context. } catch (Exception e) { throw new RuntimeException(e)..util.client. .naming.lookup("ejb:" + "myapp" + "/" + "myejb" + "/" + "" + "/" + "GreeterBean" + "!" + org.myapp.Greeter. // invoke on the bean final String greeting = bean. but the code to invoke the bean isn't servlet specific and can be used in other components (like EJB) too.naming.ejb. import javax. // setup the ejb: namespace URL factory props. } } That's it! The above code will invoke on the bean deployed on the "Destination Server" and return the result..naming.15 Client code invoking the bean We mentioned that we'll be using a servlet to invoke on the bean.getName()).Hashtable. "org.println("Received greeting: " + greeting).jboss.URL_PKG_PREFIXES. System.

1 Seam 2 JPA example To see details on changes required to run this application on WildFly. 24.step-by-step migration of binaries This document takes a somewhat different "brute force" approach. see jBPM5 on WildFly on his Kris's Blog.1. 24. see Seam 2 Booking example on WildFly 8 on Marek Novotny's Blog.Migrated to WildFly 24. JBoss Community Documentation Page 233 of 617 .Step by Step. For details about this migration.1. see Seam 2 DVD Store example on WildFly 8 on Marek Novotny's Blog.WildFly 8 24 Example Applications .3 Seam 2 Booking example For details on how to migrate this demo application.4 Seam 2 Booking .1. 24.2 Seam 2 DVD Store example For details on how to migrate this demo application. see Seam 2 JPA example deployment on WildFly 8. See Seam 2 Booking EAR Migration of Binaries .5 jBPM-Console application Kris Verlaenen migrated this application from AS 5 to WildFly 8.1 Example Applications Migrated from Previous Releases The applications in this section were written for a previous version of the server but have been modified to run on WildFly 8. 24. Changes were made to resolve issues that arose during deployment and runtime or to fix problems with application behaviour. then see what issues you hit and learn how debug and resolve them. Each example below documents the changes that were made to get the application to run successfully on WildFly.1.1. The idea is to deploy the binaries to WildFly. 24.

See the following github project for details. see Get Started Developing Applications 24.3. JBoss Community Documentation Page 234 of 617 . Quickstarts: A number of quickstart applications were written to demonstrate Java EE 6 and a few additional technologies. some stateless session beans. These are the notes he made during the migration process.1.3 Porting the Order Application from EAP 5. 24. modifications were made to the way the EAR was packaged. a stateful session bean. see Order Application Migration from EAP5.1 to WildFly 8 Andy Miller ported an example Order application that was used for performance testing from EAP 5. 24. This is because WildFly removed support of some proprietary features that were available in EAP 5. specific. In addition to application code changes.WildFly 8 24. and their solutions. that might crop up when migrating applications to WildFly 8. 24.6 Order application used for performance testing Andy Miller migrated this application from AS 5 to WildFly. working examples that can be used as a reference for your own project.1. and some entities.2 Example Applications Based on EE6 Applications in this section were designed and written specifically to use the features and functions of EE6. For details about this migration.7 Migrate example application A step by step work through of issues.1 to WildFly. it contains three servlets.1 to WildFly 8. For more information about the quickstarts.1.1 Overview of the application The application is relatively simple. They provide small.

1 version: try { context = new InitialContext().DistributionCenterManager")pr DistributionCenterManager distributionCenterManager. The real difference is in the lookup name. While migrating to WildFly.CustomerManager") private CustomerManager customerManager. } catch(Exception lookupError) { throw new ServletException("Couldn't find CustomerManager bean". lookupError).ProductManager") private ProductManager productManager.lookup("OrderManagerApp/CustomerManagerBean/local"). In addition to the change to injection. the lookup name changed from: JBoss Community Documentation Page 235 of 617 .0. the servlets were using pre-EE 5 methods for looking up stateless and stateful session bean interfaces. which was supported in EAP 5. The JNDI lookup code changed as follows: Example of code in the EAP 5. although this was not a required change.ejb.WildFly 8 24. } Example of how this is now coded in WildFly: @EJB(lookup="java:app/OrderManagerEJB/DistributionCenterManagerBean!services. lookupError). which did not support EJB reference injection. } catch(Exception lookupError) { throw new ServletException("Couldn't find the ProductManager bean".3.ejb. } try { customerManager = (CustomerManager) context.1.ejb. it seemed a good time to change the code to use the @EJB annotation.lookup("OrderManagerApp/DistributionCenterManagerBean/local").2 Summary of changes Code Changes Modify JNDI lookup code Since this application was first written for EAP 4. lookupError). } try { productManager = (ProductManager) context.lookup("OrderManagerApp/ProductManagerBean/local").3. @EJB(lookup="java:app/OrderManagerEJB/ProductManagerBean!services. } catch(Exception lookupError) { throw new ServletException("Couldn't find DistributionCenterManager bean". WildFly only supports the new EE 6 portable JNDI names rather than the old EAR structure based names. distributionCenterManager = (DistributionCenterManager) context. @EJB(lookup="java:app/OrderManagerEJB/CustomerManagerBean!services.2/4.

WildFly 8 OrderManagerApp/DistributionCenterManagerBean/local to: java:app/OrderManagerEJB/DistributionCenterManagerBean!services. JBoss Community Documentation Page 236 of 617 .DistributionCenterManager All the other beans were changed in a similar manner.ejb. They are now based on the portable JNDI names described in EE 6.

class.logmanager JBoss Community Documentation Page 237 of 617 . Rather than bundling third-party logging.class).getLogger(CustomerManagerBean.isTraceEnabled()) { log. } In addition to the code changes made to use the new AS7 JBoss log manager module. The code changes themselves are rather trivial. you must add this dependency to the MANIFEST. as this example illustrates: Old JBoss Commons Logging/Log4J: private static Log log = LogFactory.toString())."). New WildFly Logging private static Logger logger = Logger.TRACE.jboss. Old JBoss Commons Logging/Log4J: if(log. "Total rows flushed is " + (i+1)).log(Level. logger.0 Dependencies: org.isLoggable(Level.trace("Just flushed " + batchSize + " rows to the database.log(Level.trace("Total rows flushed is " + (i+1)). log.WildFly 8 Modify logging code The next major change was to logging within the application.TRACE)) { logger. the application was modified to use the new WildFly Logging infrastructure.TRACE.getLog(CustomerManagerBean. The old version was using the commons logging infrastructure and Log4J that is bundled in the application server.MF file as follows: Manifest-Version: 1. "Just flushed " + batchSize + " rows to the database."). } New WildFly Logging: if(logger.

jbc2.entity" value="mvcc-entity"/> <property name="hibernate.cache.jbc2. See "Using the Infinispan second level cache" for more details.cache.jbc2.use_query_cache" value="false"/> <property name="hibernate.WildFly 8 Modify the code to use Infinispan for 2nd level cache Jboss Cache has been replaced by Infinispan for 2nd level cache.xml file.cache.1: <properties> <property name="hibernate.hibernate.region.use_second_level_cache" value="true"/> <property name="hibernate.use_minimal_puts" value="true"/> <property name="hibernate. This requires modification of the persistence.factory_class" value="org.cache. JBoss Community Documentation Page 238 of 617 .region_prefix" value="services"/> </properties> This is how it was modified to use Infinispan for the same configuration: <properties> <property name="hibernate.cache. That was the extent of the code changes required to migrate the application to AS7.use_second_level_cache" value="true"/> <property name="hibernate.cache.JndiMultiplexedJBossCacheRegionFactory"/> <property name="hibernate.use_minimal_puts" value="true"/> </properties> <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode> Most of the properties are removed since they will default to the correct values for the second level cache.cache.cachefactory" value="java:CacheManager"/> <property name="hibernate.cache.region.region.cache.cache. This is what the file looked like in EAP 5.cfg.

OrderManagerEJB.MF META-INF/application.war OrderManagerEntities. Manifest-Version: 1.0 Dependencies: org.logmanager Class-Path: OrderManagerEJB. Modify the class path in the MANIFEST.ear META-INF/application.jar. The old structure of the EAR was as follows: $ jar tf OrderManagerApp.jar OrderManagerEJB.jboss. The second approach was selected because it simplified the EAR structure: $ jar tf OrderManagerApp.war to resolve another class loading issue resulting from the modification to use EJB reference injection in the servlets.jar META-INF/ Since there is no longer an OrderManagerEntities.xml OrderManagerWeb.war OrderManagerEJB.xml OrderManagerWeb. There are a couple of ways to resolve this issue: 1. This did not work due to modular class loading changes in WildFly.jar META-INF/ In this structure.xml were in one jar file.jar file for the injected beans. OrderManagerEntities.xml file was modified to remove the entry.MF 2.ear META-INF/MANIFEST.jar The Class-Path entry tells the application to look in the OrderManagerEJB.MF file in the OrderManagerWeb. the applcation. Flatten the code and put all the beans in one JAR file. the structure of the existing EAR failed to deploy successfully in WildFly.jar. the entities and the persistence.jar file. An entry was added to the MANIFEST. and the stateless and stateful session beans were in another jar file. JBoss Community Documentation Page 239 of 617 .WildFly 8 EAR Packaging Changes Due to modular class loading changes.

this approach seemed more appealing because it simplified the structure while maintaining the web tier in its own WAR.4 Seam 2 Booking Application .Migration of Binaries from EAP5. the purpose of this document is to show the types of issues you might encounter when migrating an application and how to debug and resolve those issues. For this example.MF file. the application EAR is deployed to the JBOSS_HOME/standalone/deployments directory with no changes other than extracting the archives so we can modify the XML files contained within them.1 to WildFly This is a step-by-step how-to guide on porting the Seam Booking application binaries from EAP5. 24. JBoss Community Documentation Page 240 of 617 .1 to WildFly 8.WildFly 8 Summary Although the existing EAR structure could have worked with additional modifications to the MANIFEST. Although there are better approaches for migrating applications. The source files for both versions is attached so you can view the changes that were made to the application.

Build the EAR cd /EAP5_HOME/jboss-eap5.war" At this point.1/seam/examples/booking/exploded-archives/jboss-seam-booking.4.server.1) Found jboss-seam-booking. you will first encounter your first deployment error. you will now see the following.server.1/seam/examples/booking/exploded-archives/jboss-seam-booking.ear 3.as.jboss. In the next section.jboss.jar" INFO [org.ear.1/seam/examples/booking/exploded-archives/jboss-seam-booking.jar" INFO [org.deployment] (MSC service thread 1-3) Starting deployment of "jboss-seam-booking. You will see: INFO [org.jboss.ear AS7_HOME/standalone/deployments/ cp -r EAP5_HOME/jboss-eap-5.jar AS7_HOME/standalone/deployments/jboss-seam.war AS7_HOME/standalone/deployments/jboss-seam. Copy the EAR to the JBOSS_HOME deployments directory: cp -r EAP5_HOME/jboss-eap-5.dodeploy and copy it into the deployments directory.1/seam/examples/booking ~/tools/apache-ant-1.ear.1 version of the Seam Booking application 1. we will step through each issue and how to debug and resolve it.as. Start the WildFly server and check the log.deployment] (MSC service thread 1-1) Starting deployment of "jboss-seam-booking. JBoss Community Documentation Page 241 of 617 .ear in deployment directory. indicating that it is deploying: INFO [org.server. To trigger deployment create a file called jboss-seam-booking.2/bin/ant explode 2.as.as.deployment] (DeploymentScanner-threads .server.ear cp -r EAP5_HOME/jboss-eap-5.jboss.deployment] (MSC service thread 1-2) Starting deployment of "jboss-seam-booking.jboss.deployment] (MSC service thread 1-6) Starting deployment of "jboss-seam. In the log.dodeploy 4. Create an empty file with the name jboss-seam-booking.WildFly 8 24.8.as.1 Step 1: Build and deploy the EAP5.ear" INFO [org.

faces.faces.."jboss-seam-booking.lang.deployment.WildFly 8 24.modules.StartException in service jboss.faces.war".ModuleClassLoader. it can not find the class javax.FacesException from \[Module "deployment. additional logs removed .java:191) What it means: The ClassNotFoundException indicates a missing dependency.jboss.FacesException and you need to explicitly add the dependency.ClassNotFoundException: javax.2 Step 2: Debug and resolve deployment errors and exceptions First Issue: java.war" of deployment "jboss-seam-booking.ear".msc. JBoss Community Documentation Page 242 of 617 .war".4.ClassNotFoundException: javax.jboss.."jboss-seam-booking.ear" (..jboss-seam-booking.deployment. the log contains the following error: ERROR \[org."jboss-seam-booking. In this case.lang.subunit.POST_MODULE: org.jboss.service.subunit.service.) Caused by: java.FacesException When you deploy the application.msc.POST_MODULE: Failed to process phase POST_MODULE of subdeployment "jboss-seam-booking.ear".fail\] (MSC service thread 1-1) MSC00001: Failed to start service jboss."jboss-seam-booking.findClass(ModuleClassLoader.ear:main" from Service Module Loader\] at org.

2 module in the sub-deployment section for the WAR and exclude the module for JSF 2.logging.2 directory is for JSF 1. so we need to be able to specify one and exclude the other.0 version in main.faces. Next Issue: java.ClassNotFoundException: org.ear. Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.faces. we want to use the JSF 1.dodeploy file in the same directory. we add the dependency for the javax. the log contains the following error: JBoss Community Documentation Page 243 of 617 .faces.0 and the one located in the 1.faces. we create a jboss-deployment-structure.api" slot="1.0"> <deployment> <dependencies> <module name="javax.war"> <exclusions> <module name="javax.commons.failed file and creating a blank jboss-seam-booking.api" slot="1.api for the JSF 1.2.0.2"/> </dependencies> </sub-deployment> </jboss-deployment-structure> In the "deployment" section. We also add the dependency for the JSF 1. If there was only one module available. you will find 2 modules that match: javax/faces/api/main javax/faces/api/1. To do this.apache.ear.api" slot="main"/> </exclusions> <dependencies> <module name="javax.2" export="true"/> </dependencies> </deployment> <sub-deployment name="jboss-seam-booking.2 version and not the 2.2 module. In this case.xml file in the EAR META-INF/ directory that contains the following data: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.WildFly 8 How to resolve it: Find the module name for that class in the AS7_HOME/modules directory by looking for a path that matches the missing class.lang.2 Both modules have the same module name: “javax.Log When you deploy the application.faces.api” but one in the main directory is for JSF 2.MF file and added the module dependency. But in this case. we could simply create a MANIFEST.

faces.INSTALL: org.jboss. <module name="org.ClassNotFoundException: org.Log from [Module "deployment. In this case.) Caused by: java.service. you will find one module that matches the path org/apache/commons/logging/.commons.failed file and creating a blank jboss-seam-booking.ear.2" export="true"/> <module name="org..0"> <deployment> <dependencies> <module name="javax.faces.logging. How to resolve it: Find the module name for that class in the JBOSS_HOME/modules/ directory by looking for a path that matches the missing class.faces.war:main" from Service Module Loader] What it means: The ClassNotFoundException indicates a missing dependency.apache.ear.apache.logging”.apache.xml to add the module dependency to the deployment section of the file.commons.jboss.unit. The module name is “org. JBoss Community Documentation Page 244 of 617 .api" slot="main"/> </exclusions> <dependencies> <module name="javax.unit..xml should now look like this: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1. In this case.logging."jboss-seam-booking.ear" (.logging" export="true"/> The jboss-deployment-structure.WildFly 8 ERROR [org.ear".StartException in service jboss.ear".war"> <exclusions> <module name="javax. additional logs removed .fail] (MSC service thread 1-8) MSC00001: Failed to start service jboss.deployment.jboss-seam-booking.Log and you need to explicitly add the dependency.api" slot="1.dodeploy file in the same directory..lang.jboss-seam-booking. it can not find the class org.api" slot="1.INSTALL: Failed to process phase INSTALL of deployment "jboss-seam-booking.commons.logging" export="true"/> </dependencies> </deployment> <sub-deployment name="jboss-seam-booking.apache.service.apache.commons.2"/> </dependencies> </sub-deployment> </jboss-deployment-structure> Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.commons.ear."jboss-seam-booking.deployment. Modify the jboss-deployment-structure.msc.msc.

servlet.WildFly 8 Next Issue: java..SeamListener: java.ClassNotFoundException: org.NoClassDefFoundError: org/dom4j/DocumentException (.jboss-seam.[default-host].lang. it can not find the class org.lang.seam.[/seam-booking]] (MSC service thread 1-3) Exception sending context initialized event to listener instance of class org.jboss-seam-booking.ClassNotFoundException: org.DocumentException from [Module "deployment..ear.dom4j.[jboss.web]. In this case.lang. the log contains the following error: ERROR [org.) Caused by: java.DocumentException When you deploy the application. additional logs removed .apache..core.jboss.catalina.jar:main" from Service Module Loader] What it means: Again.DocumentException.dom4j.ContainerBase.. JBoss Community Documentation Page 245 of 617 . the ClassNotFoundException indicates a missing dependency.dom4j.

war"> <exclusions> <module name="javax.0"> <deployment> <dependencies> <module name="javax.api" slot="1.WildFly 8 How to resolve it: Find the module name in the JBOSS_HOME/modules/ directory by looking for the org/dom4j/DocumentException.dom4j”.faces.faces.2" export="true"/> <module name="org.logging" export="true"/> <module name="org.api" slot="1.dom4j" export="true"/> The jboss-deployment-structure. Modify the jboss-deployment-structure. The module name is “org.dodeploy file in the same directory. <module name="org.dom4j" export="true"/> </dependencies> </deployment> <sub-deployment name="jboss-seam-booking. JBoss Community Documentation Page 246 of 617 .commons.xml to add the module dependency to the deployment section of the file.ear.ear.xml file should now look like this: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.apache.faces.api" slot="main"/> </exclusions> <dependencies> <module name="javax.2"/> </dependencies> </sub-deployment> </jboss-deployment-structure> Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.failed file and creating a blank jboss-seam-booking.

failed file and creating a blank jboss-seam-booking.1/seam/lib grep 'org.international.jar to the jboss-seam-booking.. the JAR containing the class was part of the EAP 5.ClassNotFoundException: org.InvalidValue When you deploy the application.jboss.validator”.lang.jar matches Binary file . We will look for the JAR that contains the missing class in the EAP5_HOME/jboss-eap-5.lang. additional logs removed .core.hibernate. so adding the module dependency will not resolve this issue./hibernate-validator.jar jboss-seam-booking.catalina.ear.validator.seam. we need to copy the hibernate-validator.. it can not find the class org. -name '*.ClassNotFoundException: org. To do this.hibernate.ear.jar'` The result shows: Binary file . JBoss Community Documentation Page 247 of 617 .statusMessages (.jboss. In this case.hibernate.ear. In this case.SeamListener: java.hibernate.hibernate.hibernate.) Caused by: java.web].InvalidValue.jboss-seam-booking.WildFly 8 Next Issue: java.validator.jar:main" from Service Module Loader] What it means: Again.1/seam/lib/ directory.ContainerBase.[default-host]. the log contains the following error: ERROR [org.InvalidValue from [Module "deployment.RuntimeException: Could not create Component: org.InvalidValue class.ear/lib Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.1/seam/lib/hibernate-validator. open a console and type the following: cd EAP5_HOME/jboss-eap-5.jboss-seam.dodeploy file in the same directory. How to resolve it: There is a module “org.1 deployment.seam.lang.validator.validator.apache.jar matches In this case.validator./test/hibernate-all.[/seam-booking]] (MSC service thread 1-6) Exception sending context initialized event to listener instance of class org.. the ClassNotFoundException indicates a missing dependency..servlet.InvalidValue' `find . but the JAR does not contain the org.ear/lib/ directory: cp EAP5_HOME/jboss-eap-5.[jboss.

faces.4-b09-jbossorg-4] .2_13.2_13-b01-FCS] (.java:294) [jsf-impl-2. 11 more Caused by: java.0_25] at javax. In this case.faces.ConfigurationException: Factory 'javax.verifyFactoriesExist(FactoryConfigProcessor.2_13-b01-FCS] .0.config.newInstance(Class.0.WildFly 8 Next Issue: java.jsf...SeamApplicationFactory at javax.processor.faces.java:308) [:1.jar:1.FactoryFinder.SeamApplicationFactory When you deploy the application.config...lang.0..0.faces.jar:2.application.config] (MSC service thread 1-7) Unsanitized stacktrace from failed start.ApplicationFactory' was not configured properly.6.getImplGivenPreviousImpl(FactoryFinder.jar:2. additional logs removed .verifyFactoriesExist(FactoryConfigProcessor.FactoryFinder..java:604) [jsf-api-1.) Caused by: javax.FactoryConfigProcessor.FacesException: org.java:606) [jsf-api-1.. it is not as obvious..ConfigurationException and java.jboss.enterprise.webcontainer.faces..0_25] at java.config.lang.6.) at com.Class. additional logs removed .4-b09-jbossorg-4.4-b09-jbossorg-4] (.seam.FactoryConfigProcessor.java:340) [:1.newInstance0(Class. the log contains the following error: INFO [javax.4-b09-jbossorg-4.: com.lang. 16 more What it means: The com.faces.faces.getImplGivenPreviousImpl(FactoryFinder.lang.sun.jar:1..SeamApplicationFactory at java.jboss.2_13.sun.jsf.seam.faces..jboss.InstantiationException: org.processor.seam. JBoss Community Documentation Page 248 of 617 ..InstantiationException indicate a dependency issue. at com.config.sun.resource.jsf.Class.sun.InstantiationException: org.java:296) [jsf-impl-2..lang.jsf..

commons.FacesException ClassNotFoundException. As we did with the javax. We also need to add it to the WAR subdeployment and exclude the JSF 2.jar in the 1.lang.2" export="true"/> <module name="com.logging" export="true"/> <module name="org.0"> <deployment> <dependencies> <module name="javax.collections.war"> <exclusions> <module name="javax.faces.api" slot="1.faces classes. We need to modify the jboss-deployment-structure.2"/> <module name="com.faces.0 version in main.2 directory shows it contains the com.2 version and not the JSF 2. Next Issue: java.sun.2"/> </dependencies> </sub-deployment> </jboss-deployment-structure> Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.ear.sun.faces.dom4j" export="true"/> </dependencies> </deployment> <sub-deployment name="jboss-seam-booking.sun.failed file and creating a blank jboss-seam-booking.0 module.ClassNotFoundException: org.faces module.dodeploy file in the same directory.jsf-impl" slot="1. so we need to be able to specify one and exclude the other.apache.2" export="true"/> <module name="org.api" slot="main"/> <module name="com.commons.ear. While there is no com. we want to use the JSF 1.sun.2_13.WildFly 8 How to resolve it: We need to find the module that contains the com.faces. A quick check of the jsf-impl-1.xml to add the module dependency to the deployment section of the file.jsf-impl" slot="main"/> </exclusions> <dependencies> <module name="javax.jsf-impl modules.apache. The file should now look like this: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1. the log contains the following error: JBoss Community Documentation Page 249 of 617 . there are are two com.jsf-impl" slot="1.sun.ArrayStack When you deploy the application.sun.sun.api" slot="1.faces classes.

config..faces.catalina. In this case.config.jboss-seam-booking.ArrayStack.commons..ear:main" from Service Module Loader] (. additional logs removed .web].apache.collections.apache.WildFly 8 ERROR [org.faces..[/seam-booking]] (MSC service thread 1-1) Exception sending context initialized event to listener instance of class com.ear:main" from Service Module Loader] What it means: Again.ArrayStack from [Module "deployment. JBoss Community Documentation Page 250 of 617 .lang.ArrayStack from [Module "deployment.ConfigureListener: java.core.apache. it can not find the class org.collections.collections.RuntimeException: com.ContainerBase.[jboss.commons.[default-host].lang.ClassNotFoundException: org..apache.jboss-seam-booking. the ClassNotFoundException indicates a missing dependency.commons.sun.) Caused by: java.ConfigurationException: CONFIGURATION FAILED! org.sun.

Modify the jboss-deployment-structure. Next Issue: Services with missing/unavailable dependencies When you deploy the application.sun.faces.apache.dodeploy file in the same directory.2"/> </dependencies> </sub-deployment> </jboss-deployment-structure> Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.xml to add the module dependency to the deployment section of the file. <module name="org. The module name is “org.2"/> <module name="com.ear.faces. the log contains the following error: JBoss Community Documentation Page 251 of 617 .faces.war"> <exclusions> <module name="javax.apache.WildFly 8 How to resolve it: Find the module name in the JBOSS_HOME/modules/ directory by looking for the org/apache/commons/collections path.0"> <deployment> <dependencies> <module name="javax.jsf-impl" slot="1.2" export="true"/> <module name="org.sun.collections" export="true"/> </dependencies> </deployment> <sub-deployment name="jboss-seam-booking.jsf-impl" slot="1.apache.collections" export="true"/> The jboss-deployment-structure.api" slot="1.collections”.ear.commons.2" export="true"/> <module name="com.jsf-impl" slot="main"/> </exclusions> <dependencies> <module name="javax.commons.apache.commons.dom4j" export="true"/> <module name="org.failed file and creating a blank jboss-seam-booking.api" slot="1.xml file should now look like this: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.sun.commons.api" slot="main"/> <module name="com.logging" export="true"/> <module name="org.

How to resolve it: In WildFly 8.\"jboss-seam-booking.<jta-data-source>java:/bookingDatasource</jta-data-source> --> <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source> Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.xml file to comment the existing jta-data-source element and replace it as follows: <!-.ear\".dodeploy file in the same directory..jar\".comp.xml file. we will modify the persistence.subunit.comp.jboss-seam-booking.jar/META-INF/persistence.java.jboss-seam-booking.AuthenticatorAction missing [ jboss.component.naming.\"jboss-seam-booking.HotelSearchingAct missing [ jboss.2) {"Composite operation failed and was rolled back.." <.\"env/org.jar#bookingDatabase\" missing [ jboss.jbo ] The “/em” indicates an Entity Manager and datasource issue.\"jboss-seam-booking.BookingListAction. look that the text within the brackets after “missing”.naming.WildFly 8 ERROR [org.jar\".jar\".context.xml file.deployment. Steps that failed:" => {"Operation step-2" => {"Services with missing/unavailable dependencies" => ["jboss.\"jboss-seam-booking.ear\".\"jboss-seam-booking.jar\".ear\".java.component.java.AuthenticatorAction. JBoss Community Documentation Page 252 of 617 .ear.jar\"."jboss.jboss.ear/jboss-seam-booking. Since WildFly ships with an example database that is already defined in the standalone.subunit.ear.jbo ]".ST missing [ jboss.deployment.context.\"jboss-seam-booking.bookingDatasource ]"]}}} What it means: When you get a “Services with missing/unavailable dependencies” error.."jboss.jb ]".jar\".naming.xml file to use that example database.comp.component.\"env/org.\"jboss-seam-booking.\"jboss-seam-booking.context.java..HotelSearchingAction.context.deployment] (DeploymentScanner-threads .jboss-seam-booking. datasource configuration has changed and needs to be defined in the standalone/configuration/standalone.jar\".\"jboss-seam-booking.subunit.deployment.\"env/org.failed file and creating a blank jboss-seam-booking.persistenceunit. you can see that the jndi-name for the example database is "java:jboss/datasources/ExampleDS". Looking in the standalone.context.> "jboss.naming.comp.as.java.jboss ]".\"jboss-seam-booking.jboss-seam-booking.\"jboss-seam-booking.\"env/org.BookingListAction. Modify the jboss-seam-booking. additional logs removed .xml file.AuthenticatorAction.naming. In this case you see: missing [ jboss.

HibernateException: could not instantiate RegionFactory [org..HashtableCacheProvider When you deploy the application.createRegionFactory(SettingsFactory...jar#bookingDatabase": org.SettingsFactory.hibernate.bridge..hibernate.jboss.ear/jboss-seam-booking. 20 more Caused by: java..ejb.PersistenceException: [PersistenceUnit: bookingDatabase] Unable to build EntityManagerFactory at org. In this case.cache.InvocationTargetException at sun.hibernate.jboss.StartException in service jboss.) Caused by: java.ear/jboss-seam-booking.RegionFactoryCacheProviderBridge.6.cache.) Caused by: org.internal.fail] (MSC service thread 1-4) MSC00001: Failed to start service jboss.bridge.reflect.Ejb3Configuration.HashtableCacheProvider.msc.jboss.msc.hibernate.lang...hibernate.. log messages removed .persistence..cfg.newInstance0(Native Method) [:1.HashtableCacheProvider] at org... log messages removed .j . log messages removed .) Caused by: org.cache.findClass(ModuleClassLoader.jboss..lang.) Caused by: javax.ModuleClassLoader..."jboss-seam-booking.ServiceControllerImpl$StartTask..service.WildFly 8 Next Issue: java.internal.cache.service..jar#bookingDatabase": Failed to start service at org.persistenceunit.run(ServiceControllerImpl.ClassNotFoundException: org.) What it means: The ClassNotFoundException indicates a missing dependency.java:191) (.persistenceunit.hibernate.. JBoss Community Documentation Page 253 of 617 .hibernate:main" from local module loader @12a3793 (roots: /home/sgilda/tools/jboss7/modules)] at org.msc.lang.HashtableCacheProvider from [Module "org.buildEntityManagerFactory(Ejb3Configuration. log messages removed .java:903) {.reflect.service. the log contains the following error: ERROR [org.java:355) (.hibernate... it can not find the class org.<init>(RegionFactoryCacheProviderBridge.hibernate.ClassNotFoundException: org.RegionFactoryCacheProviderBridge] at org."jboss-seam-booking..CacheException: could not instantiate CacheProvider [org.hibernate.cache.hibernate.0_25] (.modules.NativeConstructorAccessorImpl.cache.cache. log messages removed .java:1786) (...

jar jboss-seam-booking.InvalidValue' `find . We will look for the JAR that contains the missing class in the EAP5_HOME/jboss-eap-5.ear.failed file and creating a blank jboss-seam-booking.cache.ear/lib/ directory: cp EAP5_HOME/jboss-eap-5. we need to copy the hibernate-core.1/seam/lib/ directory. the log contains the following error: JBoss Community Documentation Page 254 of 617 .dodeploy file in the same directory.validator.HashtableCacheProvider When you deploy the application.WildFly 8 How to resolve it: There is no module for “org. open a console and type the following: cd EAP5_HOME/jboss-eap-5.hibernate. the JAR containing the class was part of the EAP 5.hibernate. Next Issue: java./hibernate-core.hibernate.ClassCastException: org. -name '*.ear/lib Redeploy the application by deleting the standalone/deployments/jboss-seam-booking. To do this.jar'` The result shows: Binary file .1/seam/lib/hibernate-core.lang.ear.1 deployment.jar matches Binary file .cache”. In this case.1/seam/lib grep 'org.jar matches In this case.jar to the jboss-seam-booking./test/hibernate-all.

20 more Caused by: java.SettingsFactory.jar and is implicitly loaded by that module.jboss.hibernate.cache.hibernate.) Caused by: org.jboss...WildFly 8 ERROR [org.cache.msc. org.spi.hibernate.RegionFactoryCacheProviderBridge.InvocationTargetException at sun.cache... The class it extends..CacheException: could not instantiate CacheProvider [org..HashtableCacheProvider cannot be cast to org.RegionFactoryCacheProviderBridge] at org. log messages removed .lang.internal. it will force the Seam application to bundle the old Hibernate libraries.persistenceunit.. it appears the class org.ejb.hibernate.service.ServiceControllerImpl$StartTask.spi.. log messages removed ...0.java:1786) (.ear/jboss-seam-booking..j .bridge.cache.Beta1. 20 more What it means: A ClassCastException can be a result of many problems.hibernate.hibernate..CacheProvider at org.jar and is being loaded by the application class loader. this problem is caused by a backward compatibility issue due moving the HashtableCacheProvider class into another package.cache.hibernate.HashtableCacheProvider class is in in the hibernate-core. resulting in ClassCastExceptions.cfg. This is not obvious.NativeConstructorAccessorImpl.hibernate.RegionFactoryCacheProviderBridge.jar#bookingDatabase": Failed to start service at org.ear/jboss-seam-booking.) Caused by: java.cache.jboss.cache.ClassCastException: org.hibernate.internal.persistenceunit.cache. The org.internal package.hibernate..cache.hibernate.cache.reflect.hibernate.Ejb3Configuration.hibernate.msc.PersistenceException: [PersistenceUnit: bookingDatabase] Unable to build EntityManagerFactory at org. If you look at this exception in the log.lang.xml file.cache.bridge.hibernate.) Caused by: org.bridge. This class was moved from the org.internal.cache package to the org.fail] (MSC service thread 1-2) MSC00001: Failed to start service jboss.CacheProvider and is being loaded by a different class loader than the class it extends.reflect..) Caused by: javax..persistence.StartException in service jboss..service. In WildFly.newInstance0(Native Method) [:1.msc.java:355) (.hibernate.createRegionFactory(SettingsFactory.run(ServiceControllerImpl.java:903) (. is in the org/hibernate/main/hibernate-core-4.j .cache.0. If you don't remove the hibernate.buildEntityManagerFactory(Ejb3Configuration.6.spi. but due to changes in Hibernate 4.hibernate...<init>(RegionFactoryCacheProviderBridge.CacheProvider.HashtableCacheProvider extends org. JBoss Community Documentation Page 255 of 617 . log messages removed .provider_class property from the persistence.HibernateException: could not instantiate RegionFactory [org. log messages removed .<init>(RegionFactoryCacheProviderBridge."jboss-seam-booking.cache.."jboss-seam-booking..jar#bookingDatabase": org. you should move away from using HashtableCacheProvider and use Infinispan instead.0_25] (.service.HashtableCacheProvider] at org.

JBoss Community Documentation Page 256 of 617 . log messages removed .cache..hibernate..jsf.) What it means: A NameNotFoundException indications a JNDI naming issue.NameNotFoundException: Name 'jboss-seam-booking' not found in context '' The application deploys successfully.java:2170) [jboss-seam.0...naming.0. 24.jboss.jar:] (.provider_class" value="org.java:109) (.cache.jar/META-INF persistence.seam.3 Step 3: Debug and resolve runtime errors and exceptions First Issue: javax.InstantiationException: Could not instantiate Seam component: org..cache..HashtableCacheProvider"/> --> Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.naming. No more issues: Deployment errors should be resolved At this point.synchronizations at org..jboss. the application should deploy without errors..seam.xml file as follows: <!-. but when you access the URL “ http://localhost:8080/seam-booking/” in a browser..1-8080-1) swallowing exception: java.newInstance(Component. but when you access the URL “ http://localhost:8080/seam-booking/” in a browser and attempt "Account Login".jboss..Component.jar:] (.jboss.transaction.seam.NameNotFoundException: Name 'jboss-seam-booking' not found in context '' at org.util. In the next section. you need to comment out the hibernate.jboss. you get “The page isn't redirecting properly” and the log contains the following error: SEVERE [org.nameNotFoundException(NamingUtils.failed file and creating a blank jboss-seam-booking.4.SeamPhaseListener] (http--127.begin(SeamPhaseListener.<property name="hibernate.as.jboss.) Caused by: javax.java:598) [jboss-seam.NamingUtils.IllegalStateException: Could not start transaction at org. we will step through each runtime issue and how to debug and resolve it.lang..naming.. you will get a runtime error “The page isn't redirecting properly”. log messages removed .WildFly 8 How to resolve it: In WildFly.ear. JNDI naming rules have changed in WildFly and we need to modify the lookup names to follow the new rules.provider_class property in the jboss-seam-booking.) Caused by: org.SeamPhaseListener. log messages removed .ear.seam.seam.dodeploy file in the same directory.jsf.

Auth java:app/jboss-seam-booking.booking.Register java:global/jboss-seam-booking/jboss-seam-booking.jboss.Register java:module/RegisterAction!org.example.jboss.BookingList java:global/jboss-seam-booking/jboss-seam-booking.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-1) JNDI bindings for session bean named HotelBookingAction in deployment unit subdeployment "jboss-seam-booking.jar/RegisterAction!org.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-1) JNDI bindings for session bean named AuthenticatorAction in deployment unit subdeployment "jboss-seam-booking.ejb3.Bookin java:app/jboss-seam-booking.example.booking.ear" are as follows: java:global/jboss-seam-booking/jboss-seam-booking.138 INFO [org.example.example.example.seam.Authenticator java:global/jboss-seam-booking/jboss-seam-booking.ejb3.HotelBooking java:module/HotelBookingAction!org.jar/HotelBookingAction java:app/jboss-seam-booking.138 INFO [org.jar/RegisterAction java:app/jboss-seam-booking.jar/RegisterAction java:module/RegisterAction 15:01:16.deployment.jboss.example.seam.booking.seam.jar/BookingListAction java:module/BookingListAction 15:01:16.jboss.jboss.as.jboss.seam.ear" are as follows: java:global/jboss-seam-booking/jboss-seam-booking.processors.jar/HotelBookingAction!org. Looking at the server log we see this: 15:01:16.HotelBooking java:global/jboss-seam-booking/jboss-seam-booking.as.booking.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-1) JNDI bindings for session bean named BookingListAction in deployment unit subdeployment "jboss-seam-booking.jboss.example.booking.jar" of deployment "jboss-seam-booking.jar" of deployment "jboss-seam-booking.Authenticator java:module/AuthenticatorAction!org.booking.Register java:app/jboss-seam-booking.booking.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-1) JNDI bindings for session bean named ChangePasswordAction in deployment unit JBoss Community Documentation Page 257 of 617 .processors.example.jar/HotelBookingAction!org.jboss.seam.booking.example.booking.jboss.processors.jar" of deployment "jboss-seam-booking.jar/BookingListAction!org.example.jboss.seam.example.booking.seam.139 INFO [org.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-1) JNDI bindings for session bean named RegisterAction in deployment unit subdeployment "jboss-seam-booking.jar/BookingListAction!org.as.as.as.booking.jar/AuthenticatorAction java:module/AuthenticatorAction 15:01:16.jar/HotelBookingAction java:module/HotelBookingAction 15:01:16.jboss.jboss.deployment.BookingList java:module/BookingListAction!org.jboss.jar/AuthenticatorAction!org.processors.138 INFO [org.jboss.deployment.ejb3.ejb3.Hotel java:app/jboss-seam-booking.jboss.booking. look earlier in the server log trace to what JNDI binding were used.jar/AuthenticatorAction java:app/jboss-seam-booking.ear" are as follows: java:global/jboss-seam-booking/jboss-seam-booking.jar" of deployment "jboss-seam-booking.WildFly 8 How to resolve it: To debug this.seam.seam.seam.jar/AuthenticatorAction!org.processors.deployment.jboss.seam.seam.ejb3.example.138 INFO [org.jboss.jar/RegisterAction!org.ear" are as follows: java:global/jboss-seam-booking/jboss-seam-booking.jar/BookingListAction java:app/jboss-seam-booking.deployment.

deployment.jar/HotelSearchingAction java:app/jboss-seam-booking.LocalTimerServiceDispat java:app/jboss-seam/TimerServiceDispatcher!org.Hot java:app/jboss-seam-booking.139 INFO [org.jboss.example.seam.example.jboss.seam.ear" are as follows: java:global/jboss-seam-booking/jboss-seam/TimerServiceDispatcher!org.HotelSearching java:module/HotelSearchingAction!org.jboss.seam.ejb3.jboss.ear" are as follows: java:global/jboss-seam-booking/jboss-seam-booking.example.jar/HotelSearchingAction java:module/HotelSearchingAction 15:01:16.deployment.jar/#{ejbName}" debug="true" distributable="false"/> JBoss Community Documentation Page 258 of 617 .jboss.example.booking.ChangePassword java:global/jboss-seam-booking/jboss-seam-booking.processors.WildFly 8 subdeployment "jboss-seam-booking.async.processors.as.booking.example.seam.jboss.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-6) JNDI bindings for session bean named TimerServiceDispatcher in deployment unit subdeployment "jboss-seam.seam.jar/ChangePasswordAction!org.booking.booking.ear" are as follows: java:global/jboss-seam-booking/jboss-seam/EjbSynchronizations!org. note the EJB JNDI bindings all start with "java:app/jboss-seam-booking.Cha java:app/jboss-seam-booking.seam.jboss.LocalEjbSynchronizat java:app/jboss-seam/EjbSynchronizations!org.jboss.transaction.ear" are as follows: java:global/jboss-seam-booking/jboss-seam-booking.async.transaction.jar/ChangePasswordAction java:app/jboss-seam-booking.processors.jar" of deployment "jboss-seam-booking.jboss.jar/HotelSearchingAction!org.ejb3.jboss.jar/HotelSearchingAction!org.jar" of deployment "jboss-seam-booking.xml file to use the new JNDI bindings. In the log.LocalTimerServiceDispatcher java:global/jboss-seam-booking/jboss-seam/TimerServiceDispatcher java:app/jboss-seam/TimerServiceDispatcher java:module/TimerServiceDispatcher We need to modify the WAR's lib/components.seam.LocalEjbSynchronizations java:module/EjbSynchronizations!org.example.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-6) JNDI bindings for session bean named EjbSynchronizations in deployment unit subdeployment "jboss-seam.as.jar" Replace the <core:init> element as follows: <!-<core:init jndi-pattern="jboss-seam-booking/#{ejbName}/local" debug="true" distributable="false"/> --> <core:init jndi-pattern="java:app/jboss-seam-booking.as.seam.transaction.LocalEjbSynchronizations java:global/jboss-seam-booking/jboss-seam/EjbSynchronizations java:app/jboss-seam/EjbSynchronizations java:module/EjbSynchronizations 15:01:16.LocalTimerServiceDispatcher java:module/TimerServiceDispatcher!org.jar/ChangePasswordAction java:module/ChangePasswordAction 15:01:16.140 INFO [org.seam.jar" of deployment "jboss-seam-booking.deployment.HotelSearching java:global/jboss-seam-booking/jboss-seam-booking.ChangePassword java:module/ChangePasswordAction!org.jar/ChangePasswordAction!org.ejb3.jboss.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-1) JNDI bindings for session bean named HotelSearchingAction in deployment unit subdeployment "jboss-seam-booking.booking.jboss.jar" of deployment "jboss-seam-booking.jboss.seam.async.140 INFO [org.jboss.seam.seam.jboss.booking.

seam.com/products/seam/components" xmlns:core="http://jboss.2.2.EjbSynchronizations" jndi-name="java:app/jboss-seam/EjbSynchronizations"/> <component class="org.2.seam.async.com/products/seam/core" xmlns:security="http://jboss.ear.jar/#{ejbName}" debug="true" distributable="false"/> <core:manager conversation-timeout="120000" concurrent-request-timeout="500" conversation-id-parameter="cid"/> <transaction:ejb-transaction/> <security:identity authenticate-method="#{authenticator.com/products/seam/security" xmlns:transaction="http://jboss.WildFly 8 Next.com/products/seam/components-2. When you access the URL “ http://localhost:8080/seam-booking/” in a browser.jboss.<core:init jndi-pattern="jboss-seam-booking/#{ejbName}/local" debug="true" distributable="false"/> --> <core:init jndi-pattern="java:app/jboss-seam-booking.ear.com/products/seam/security http://jboss.2. At this point.transaction.TimerServiceDispatcher" jndi-name="java:app/jboss-seam/TimerServiceDispatcher"/> The components. Add the following component elements to the file: <component class="org.xsd"> <!-.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://jboss. the application should deploy and run without error.jboss. you will be able to login successfully.com/products/seam/security-2.seam.com/products/seam/transaction http://jboss.EjbSynchronizations" jndi-name="java:app/jboss-seam/EjbSynchronizations"/> <component class="org.com/products/seam/core http://jboss.dodeploy file in the same directory.TimerServiceDispatcher" jndi-name="java:app/jboss-seam/TimerServiceDispatcher"/> </components> Redeploy the application by deleting the standalone/deployments/jboss-seam-booking.failed file and creating a blank jboss-seam-booking.com/products/seam/transaction-2.jboss.com/products/seam/components http://jboss.transaction.xsd http://jboss. we need to add the EjbSynchronizations and TimerServiceDispatcher JNDI bindings.xsd http://jboss.w3.xsd http://jboss.com/products/seam/core-2.async. JBoss Community Documentation Page 259 of 617 .com/products/seam/transaction" xmlns:xsi="http://www.xml file should now look like this: <?xml version="1.seam.authenticate}"/> <component class="org.jboss.0" encoding="UTF-8"?> <components xmlns="http://jboss.

We created a jboss-deployment-structure.xml file in the EAR's META-INF/ directory.commons.WildFly 8 24.jsf-impl" slot="main"/> </exclusions> <dependencies> <module name="javax.sun.commons.5 Summary of Changes Although it would be much more efficient to determine dependencies in advance and add the implicit dependencies in one step.2" export="true"/> <module name="org.jsf-impl" slot="1. We added "dependencies" and "exclusions" to resolve ClassNotFoundExceptions.dom4j" export="true"/> <module name="org.sun.2" export="true"/> <module name="com.api" slot="1.apache. The following is a summary of changes made to the application when migrating it to WildFly: 1.collections" export="true"/> </dependencies> </deployment> <sub-deployment name="jboss-seam-booking.jsf-impl" slot="1. 24.jar JBoss Community Documentation Page 260 of 617 .4.1/seam/lib/ directory to the jboss-seam-booking.logging" export="true"/> <module name="org. You should the Booking welcome page. We copied the following JARs from the EAP5_HOME/jboss-eap-5.4.apache. this exercise shows how problems appear in the log and provides some information on how to debug and resolve them.war"> <exclusions> <module name="javax.ear/lib/ directory to resolve ClassNotFoundExceptions: hibernate-core.2"/> <module name="com.faces. This file contains the following data: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.4 Step 4: Access the application Access the URL “http://localhost:8080/seam-booking/” in a browser and login with demo/demo.api" slot="main"/> <module name="com.0"> <deployment> <dependencies> <module name="javax.api" slot="1.2"/> </dependencies> </sub-deployment> </jboss-deployment-structure> 2.faces.sun.faces.jar hibernate-validator.

cache. We added component elements for the "EjbSynchronizations" and "TimerServiceDispatcher" JNDI bindings <component class="org.jboss.HashtableCacheProvider"/> --> 4.cache. we commented out the hibernate.async. JBoss Community Documentation Page 261 of 617 .gz) and the EAR as modified to run on AS7 (jboss-seam-booking-as7.ear.tar. 1.seam.WildFly 8 3. we changed the jta-data-source element to use the Example database that ships with AS7: <!-.<core:init jndi-pattern="jboss-seam-booking/#{ejbName}/local" debug="true" distributable="false"/> --> <core:init jndi-pattern="java:app/jboss-seam-booking.TimerServiceDispatcher" jndi-name="java:app/jboss-seam/TimerServiceDispatcher"/> The unmodified EAR from EAP 5.jar/META-INF/persistence.jboss. Next. First.provider_class" value="org.cache.xml file to use the new JNDI bindings 1.xml} file as follows.EjbSynchronizations" jndi-name="java:app/jboss-seam/EjbSynchronizations"/> <component class="org.gz) are attached to this document.hibernate.tar. We modified the {{jboss-seam-booking.provider_class property: <!-.ear.<property name="hibernate.1 (jboss-seam-booking-eap51.transaction.jar/#{ejbName}" debug="true" distributable="false"/> 2. We replaced the <core:init> existing element as follows: <!-. We modified the WAR's lib/components.<jta-data-source>java:/bookingDatasource</jta-data-source> --> <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source> 2.seam.

Once the application is successfully deployed and running on the new platform.WildFly 8 25 How do I migrate my application from AS5 or AS6 to WildFly The purpose of this guide is to document only those changes that are needed to successfully run and deploy AS 5 applications on WildFly 8. 25. you must use release WildFly 8 or later as it supports the EE6 Full Profile. You should also read Getting started with WildFly for helpful information about how to install and run the application server.1 Migration Overview WildFly 8 is structured differently from previous versions of JBoss AS. Getting Started with WildFly in the Getting Started Guide has a lot of useful information. Reminder Before making any modifications to your application. including a table that lists the Java Enterprise Edition 6 Web Profile features that are supported in WildFly. make sure to create a backup copy.It provides information on to resolve deployment and runtime problems and how to prevent changes in application behaviour. so you may want do a little research before you attempt to migrate your application. JBoss Community Documentation Page 262 of 617 . If your application uses features that go beyond the Web Profile specification. plans can be made to upgrade individual components to use the new functions and features of WildFly. The rest of this document describes some of the changes you might need to make to your application to successfully deploy and run it on WildFly. This is the first step in moving to the new platform.

JBoss Community Documentation Page 263 of 617 .WildFly 8 25. WildFly's class loading is based on modules that have to define explicit dependencies on other modules. For a complete list of the automatic dependencies that are added see Implicit module dependencies for deployments.1 Modular class loading overview Class loading in WildFly is considerably different than in previous versions of JBoss AS. Similarly if your module contains a beans. as part of the deployment process some dependencies on modules defined by the application server are set up for you automatically.2.xml file. Instead of the more familiar hierarchical class loading environment. Class loading is now based on the JBoss Modules project. a dependency on Weld will be added automatically. if you are deploying a Java EE application. For instance. Deployments in WildFly are also modules. While WildFly modules are isolated by default.2 Update Application Dependencies Due to Class Loading Changes 25. and do not have access to classes that are defined in jars in the application server unless an explicit dependency on those classes is defined. along with any supporting modules that weld needs to operate. a dependency on the Java EE API's will be added to your module automatically.

Classes will not necessarily have access to other classes in the EAR unless explicit dependencies have been defined. The EAR/lib directory is a single module.2 Understand module dependencies The deployers within the server "implicitly" add some commonly used module dependencies. the modules must be specified explicitly in the MANIFEST. NoClassDefFoundErrors. For more information on EAR and WAR packaging. Tattletale is an excellent tool that can help you identify module dependencies in your application. Manifest entries are explained in more detail here: Class Loading in WildFly. and every WAR or EJB jar deployment is also a separate module.apache. You may also see runtime errors and page redirects to the JBoss Seam Debug Page.MF as Dependencies: or "Class-Path:" entries or in the jboss-deployment-structure.2.WildFly 8 25. For some classes. like the javax.maven. to the deployment so that the classes are visible to the deployment at runtime.. or ClassCastExceptions. How and when these implicit dependencies are added is explained in Implicit module dependencies for deployments. Tattletale is described later in this document here: Use Tattletale to find application dependencies.Tell maven to package in ear/lib for WildFly --> <defaultLibBundleDir>lib</defaultLibBundleDir> . This way the application developer doesn't have to worry about adding them explicitly. Otherwise you may see ClassNotFoundExceptions. How to Package EARs and WARs When you migrate your application. JBoss Community Documentation Page 264 of 617 . Reminder If you are using maven configure defaultLibBundleDir property to lib directory: <build> <plugins> <plugin> <groupId>org.xml. you may have to change the packaging structure of your EAR or WAR due to the class loading changes.plugins</groupId> <artifactId>maven-ear-plugin</artifactId> <configuration> <!-.jdk.. This means classes packaged in the WEB-INF/lib are treated the same as classes in WEB-INF/classes.api and sun. An EAR is different in that it consists of multiple modules. A WAR is a single module and all classes in the WAR are loaded with the same class loader. see "WAR Class Loading" and "EAR Class Loading" in Class Loading in WildFly.

you will see a ParseError and XMLStreamException in your server log: javax. so it is no longer necessary.jar If you modify the MANIFEST.jboss.jboss.MF file that has been modified to contain dependencies and classpath entries: Manifest-Version: 1.parser.col]:[5.util.. There is more information about these dependencies in the following paragraphs. JBoss Community Documentation Page 265 of 617 . you may need to add one or more dependencies to this file.metadata.parse(JBossWebMetaDataParser.XMLStreamException: ParseError at [row.WildFly 8 25.unexpectedElement(MetaDataElementParser.java:182) at org. 5 more MANIFEST.as. The behaviour that this provokes in EAP 5 is now the default class-loading behaviour in WildFly. you need to remove it.2.stream.0 Dependencies: org.5] Message: Unexpected element 'class-loading' encountered at org.java:109) at org.jboss.MF file Manually edited MANIFEST files Depending on which components your application uses.parser.jboss.web.metadata. If you do not remove this element.JBossWebParsingDeploymentProcessor.logmanager Class-Path: OrderManagerEJB.JBossWebMetaDataParser.xml If you have defined a class-loading element.xml. make sure to include a newline character at the end of the file..3 Create or modify files that control class loading in WildFly jboss-web.deployment. The following is an example of MANIFEST.jbossweb.MF file.MetaDataElementParser.java: .deploy(JBossWebParsingDeploymentProcessor.

0</ejbVersion> <archive> <manifestFile>src/main/resources/META-INF/MANIFEST.maven.MF file dependencies if you use Maven If you use Maven. the src/main/resources/MANIFEST.plugins</groupId> <artifactId>maven-ejb-plugin</artifactId> <configuration> <ejbVersion>3. If your application uses EJB 3.0. you may need to modify your pom.MF file.apache.MF</manifestFile> </archive> </configuration> </plugin> In the above example.WildFly 8 How to define MANIFEST.logging JBoss Community Documentation Page 266 of 617 . you will need to add that dependency to the MANIFEST.MF file only needs to contain the dependency entry: Dependencies: org.apache.apache.apache.0 code uses org.MF file.maven.logging Maven will generate the complete MANIFEST.xml file to generate the dependencies for the MANIFEST. To do that.commons. you will need to modify the plugin element in the pom.MF file: Manifest-Version: 1.commons.log.xml file as follows: <plugin> <groupId>org.apache. you may have a section in the pom.plugins</groupId> <artifactId>maven-ejb-plugin</artifactId> <configuration> <ejbVersion>3.0</ejbVersion> </configuration> </plugin> If the EJB 3.xml file that looks like the following: <plugin> <groupId>org.0 Dependencies: org.commons.

application. If your application uses dependency injections and resource-refs to refer to components in external modules. init() { Context ctx = new InitialContext(). in most cases the <initialize-in-order> element is not required because the application server is able to implicitly determine the correct and optimal way of ordering the components.lookup("TheBeanInMyBeansModule").war. ctx. The Java EE6 spec provides the <initialize-in-order> element in the application.xml which allows control of the order in which the Java EE modules within an EAR are deployed. A servlet in the myApp. you set the <initialize-in-order> element to true and specify the order of the myBeans.war. if that servlet uses legacy JNDI lookup style remote references like the following to access the bean.xml This file is a JBoss specific deployment descriptor that can be used to control class loading in a fine grained manner. The following is an example that uses the <initialize-in-order> element to control deployment order. Assume you have an application that contains a myBeans. } In this case. For additional information.xml file.MF. this file can be used to add dependencies. JBoss Community Documentation Page 267 of 617 . you controlled the order of deployments within an EAR through the use of the jboss-app. see jboss-deployment-structure. In this case.xml.jar are initialized and started before the components in myApp.war within a myApp.WildFly 8 jboss-deployment-structure.jar and you need to enforce that the components in the myBeans.ear. In most cases you do not need to specify deployment order.jar and a myApp. the server is not able to determine that that EJB component is in the myBeans.xml file. you may need to specify module order. and add additional resource roots to a module. This is no longer the case. change an EAR deployment's isolated class loading behaviour. To do this. Like the MANIFEST.jar. The myBeans. define additional modules. the application server has the appropriate knowledge to make sure that the EJB component is available before the servlet is started and you do not have to use the <initialize-in-order> element.xml In previous versions of JBoss AS.war @EJB injects a bean from myBeans. If can also prevent automatic dependencies from being added.war modules in the application.jar and myApp. However.jar is deployed before the myApp.

to get those properties available in the classpath.com/xml/ns/javaee/application_6. see Deployment Module Dependencies. if you are deploying a .w3.WildFly 8 <application xmlns="http://java.sun. then package them at the root of some . the JBOSS_HOME/server/<servername>/conf/ was available in the classpath. Hence the properties files in that location were available in the classpath of the application.war</web-uri> <context-root>myApp</context-root> </web> </module> </application> The schema for the application. JBoss Community Documentation Page 268 of 617 . package them within your application. It is preferable to define proper dependencies using dependency injections or resource-refs since it allows the container more flexibility in optimizing deployments. see Class Loading in WildFly 8.2. For more information about modular class loading. For information about deployment module dependencies. 25.sun. For example.xsd.war then package those properties in WAR WEB-INF/classes/ folder.xml file can be found here at http://java. see the Module Compatible Classloading Guide.xsd"> <application-name>jboss-as-ejb-in-ear</application-name> <initialize-in-order>true</initialize-in-order> <module> <ejb>myBeans.ear.com/xml/ns/javaee/application_6.4 Change ResourceBundle location In previous versions of AS.jar</ejb> </module> <module> <web> <web-uri>myApp.5 Where to Find Additional Information For more information about the class loading changes in WildFly 8. 25.sun.org/2001/XMLSchema-instance" version="6" xsi:schemaLocation="http://java.jar and place that jar in EAR lib/ folder. If you want those properties accessible to all components in a .com/xml/ns/javaee http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www. You should be aware that setting <initialize-in-order> to true slows down deployment.2. In WildFly 8.

as noted below.xml file.1 Overview In previous versions of the application server. can be found here: Datasource Descriptors.xml file. You will no longer package the JDBC driver with the application or in the server/lib directory. A driver that is JDBC 4-compliant contains a META-INF/services/java.WildFly 8 25. the JCA data source configuration was defined in a file with a suffix of *-ds. The following is an example of a MySQL datasource element: JBoss Community Documentation Page 269 of 617 . You can find more information about the tool here: IronJacamar Datasource and Resource Adapter Migration Tool .sql.xml. A JDBC 4-compliant driver can be installed as a deployment or as a core module. In AS7.xml file.xml file. The IronJacamar distribution features a migration tool that can help you convert your previous datasource configuration file into the new format. 25.3 Update the DataSource Configuration 25. The JDBC driver was copied to the server lib/ directory or packaged in the application's WEB-INF/lib/ directory. This file was then deployed in the server's deploy directory. If you are running in standalone mode. this has all changed.xml file is now obsolete and the datasource configuration information is now defined in the standalone/configuration/standalone. you will need to create a datasource element and a driver element for your JDBC driver and datasource information in the standalone. If you are running in domain mode. a datasource is configured in the server configuration file. First.xml or domain. you will configure the datasource in the standalone/configuration/standalone.3.Driver file that specifies the driver class name. which is the same for both modes. the configuration file is the domain/configuration/domain. A driver that is not JDBC 4-compliant requires additional steps.3.2 Define the datasource In WildFly 8.xml or in the domain/configuration/domain. Schema reference information. You will use some of the same information that was previously defined in the *-ds.xml file. The *-ds.

This is used by the server to find name of the class(es) of the Drivers which exist in that JAR.1.1.Driver</driver-class> </driver> For more information on how to add a MySQL driver.WildFly 8 <datasource jndi-name="java:/YourDatasourceName" pool-name="YourDatasourceName"> <connection-url>jdbc:mysql://localhost:3306/YourApplicationURL</connection-url> <driver> mysql-connector-java-5.sql.Driver file that specifies the driver class name. please refer to the DataSources chapter of the Admin Guide.3. <driver name="mysql-connector-java-5. JBoss Community Documentation Page 270 of 617 .jdbc.mysql"> <driver-class>com. see Adding a MySQL datasource to JBoss AS 7.sql. 25. There are pros and cons to each approach.15. <driver name="mysql-connector-java-5.mysql. which will be outlined below.jar" module="com.15.15.jar </driver> <transaction-isolation> TRANSACTION_READ_COMMITTED </transaction-isolation> <pool> <min-pool-size>100</min-pool-size> <max-pool-size>200</max-pool-size> </pool> <security> <user-name> USERID </user-name> <password> PASSWORD</password> </security> <statement> <prepared-statement-cache-size>100</prepared-statement-cache-size> <share-prepared-statements/> </statement> </datasource> A JAR that is JDBC 4-compliant contains a META-INF/services/java.Driver file that specifies the driver class name. The driver-class must be specified since it there is no META-INF/services/java. For a detailed explanation how to deploy JDBC 4-compliant driver jar.3 Install the JDBC driver The JDBC driver can be installed into the container in one of two ways: either as a deployment or as a core module.jar" module="com.mysql"/> This is an example of the driver element for driver that is not JDBC 4-compliant.1. This is an example of the driver element for a JDBC 4-compliant MySQL driver.

Any JDBC 4-compliant driver will automatically be recognized and installed into the system by name and version. using the MySQL JDBC driver above.jar If the JDBC driver consists of more than one JAR.1. thus distribution of the driver JAR is one less thing for administrators to worry about. When you run your application server in domain mode. If your JDBC driver JAR is not JDBC 4-compliant.sql.WildFly 8 Install the JDBC driver as a deployment When you install the JDBC driver as a deployment. This structure will contain the driver and a module. you simply copy the JDBC 4-compliant JAR into the AS7_HOME/standalone/deployments directory.xml file: JBoss Community Documentation Page 271 of 617 . which contains the name of the class(es) of the Drivers which exist in that JAR. A JDBC 4-compliant JAR is identified using the Java service provider mechanism. deployments are automatically propagated to all servers to which the deployment applies. You must install the JDBC driver as a core module. you would create a directory structure as follows: JBOSS_HOME/modules/com/mysql/main In the main directory.15. it is deployed as a regular JAR. For example.Driver file to the JAR or by deploying the JAR with an overlay. In WildFly 8 standalone mode.sql. This is the recommended way to install the driver.Driver". It contains a text a file named "META-INF/services/java. it can be made deployable by adding the java. you then create the following module. More information on that topic can be found here: Installing a JDBC Driver as a Deployment. you will need to create a directory structure under the modules folder. you can not install the driver as a deployment. Here is an example of a MySQL JDBC driver installed as a deployment: JBOSS_HOME/standalone/deployments/mysql-connector-java-5.xml file to define the module. for example a JAR with the driver and a dependent license JAR. Install the JDBC driver as a core module To install the driver as a module.

jar"/> </resources> <dependencies> <module name="javax. "com.mysql". You should remove the Hibernate jars from your application.org.. you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as ~ published by the Free Software Foundation. Under dependencies. if not. ~ ~ You should have received a copy of the GNU Lesser General Public License along with this software. Red Hat. Fifth Floor. Home of Professional Open Source. You should also remove the "hibernate.. MA 02110-1301 USA.3. ~ Copyright 2010.WildFly 8 <?xml version="1. Inc. Inc.0" name="com. Make sure you do NOT have a space at the beginning of module. but WITHOUT ANY WARRANTY.api that is located under modules/javax/api/main. without even the implied warranty of ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. it is dependent on the Java JDBC APIs which are defined in another module named javax.api"/> </dependencies> </module> The module name. you specify the module's dependencies on other modules.txt file in the ~ distribution for a full listing of individual contributors. write to the Free ~ Software Foundation.1 of the License.fsf. --> <module xmlns="urn:jboss:module:1.xml as this is not needed.manager_lookup_class" property from your persistence.mysql"> <resources> <resource-root path="mysql-connector-java-5.4 Configure the datasource for Hibernate or JPA If your application uses JPA and currently bundles the Hibernate JARs. 25. JBoss Community Documentation Page 272 of 617 . See the GNU Lesser General Public License for more details. ~ ~ This is free software.transaction.1. 51 Franklin St. See the copyright. you may want to use the Hibernate that is included with WildFly 8. as the case with all JDBC data sources. Boston. ~ ~ This software is distributed in the hope that it will be useful.15. matches the directory structure for this module.0" encoding="UTF-8"?> <!-~ JBoss. or (at your option) any later version. and individual contributors as indicated by the @author tags. either version 2. or see the FSF site: http://www. In this case.xml file or you will get a "New missing/unsatisfied dependencies" error for this driver.

1 Overview In previous versions of the application server. Schema reference information.4. In WildFly 8. which is the same for both modes. you will configure the resource adapter in the standalone/configuration/standalone. 25. The IronJacamar distribution features a migration tool that can help you convert your previous datasource configuration file into the new format.3.xml.4 Update the Resource Adapter Configuration TODO: The following section on Resource adapters needs to be reviewed 25. JBoss Community Documentation Page 273 of 617 . a resource adapter is configured in the server configuration file.xml file.DataSource Configuration How to create and manage datasources in WildFly 8 Adding a MySQL datasource to WildFly 8.5 Where to Find Additional Information DataSource Configuration in WildFly 8 DataSource Descriptors Admin Guide . can be found here: Resource adapter descriptors. You can find more information about the tool here: IronJacamar Datasource and Resource Adapter Migration Tool . the configuration file is the domain/configuration/domain.WildFly 8 25.xml file. the resource adapter configuration was defined in a file with a suffix of *-ds. If you are running in domain mode. If you are running in standalone mode.

spec.deployers.MultipleAdminObject2Impl" jndi-name="java:/eis/MultipleAdminObject2"> <config-property name="Name">MultipleAdminObject2Value</config-property> </admin-object> </admin-objects> </resource-adapter> </resource-adapters> TODO: The above section on Resource adapters needs to be reviewed JBoss Community Documentation Page 274 of 617 .rars.jca.rars.jca.spec.2 Define the resource adapter The resource adapter descriptor information is defined under the <subsystem xmlns="urn:jboss:domain:resource-adapters:1.xml file.deployers.rars.jca.test.test.rars.test.WildFly 8 25.4.jca.deployers.jboss.multiple. The following is an example of a resource adapter element in the server configuration file: <resource-adapters> <resource-adapter> <archive>multiple-full.deployers.MultipleManagedConnectionFactory1" enabled="true" jndi-name="java:/eis/MultipleConnectionFactory1" pool-name="MultipleConnectionFactory1"> <config-property name="Name">MultipleConnectionFactory1Value</config-property> </connection-definition> <connection-definition class-name="org.0"/> element in the server configuration file.jboss.spec.MultipleManagedConnectionFactory2" enabled="true" jndi-name="java:/eis/MultipleConnectionFactory2" pool-name="MultipleConnectionFactory2"> <config-property name="Name">MultipleConnectionFactory2Value</config-property> </connection-definition> </connection-definitions> <admin-objects> <admin-object class-name="org.test.multiple.multiple.multiple.jboss.jboss.MultipleAdminObject1Impl" jndi-name="java:/eis/MultipleAdminObject1"> <config-property name="Name">MultipleAdminObject1Value</config-property> </admin-object> <admin-object class-name="org. You will use some of the same information that was previously defined in the *-ds.spec.rar</archive> <config-property name="Name">ResourceAdapterValue</config-property> <transaction-support>NoTransaction</transaction-support> <connection-definitions> <connection-definition class-name="org.

2.1 introduced a standardized global JNDI namespace and a series of related namespaces that map to the various scopes of a Java EE application. you will need to change them to follow the new standardized JNDI namespace convention. Namespaces should follow these rules: 1. Qualified "absolute" names like "java:/jdbc/ExampleDS" should be qualified the same way as #2.5 Update application JNDI namespace names 25.1 Overview EJB 3. "java:module/env". Unqualified "absolute" names like "/jdbc/ExampleDS" should be qualified relative to a "java:jboss/root" name. This means you might run into issues with the current namespaces in your application if they don't follow the new rules. or "java:jboss/env". If you use JNDI lookups in your application.5. 25. and java:app. Any "relative" name with a "java:" lead-in must be in one of the five namespaces: "comp". 3. Any name starting with "java:xxx" where "xxx" is a name which is not equal to one of the above five would result in an invalid name error. JBoss Community Documentation Page 275 of 617 . The special "java:jboss" namespace is shared across the entire AS server instance. or our proprietary "jboss". Unqualified relative names like "ExampleDS" or "jdbc/ExampleDS" should be qualified relative to "java:comp/env". you will need to review the JNDI namespace rules and modify the application code to follow these rules. "global". 5. depending on the context. "app". To conform to the new portable JNDI namespace rules. 4. "module".5. java:module. The three JNDI namespaces used for portable JNDI lookups are java:global.2 Review the JNDI Namespace Rules WildFly 8 has tightened up on JNDI namespace names to provide predictable and consistent rules for every name bound in the application server and to prevent future compatibility issues.WildFly 8 25.

Note the lookup name is: "OrderManagerApp/ProductManagerBean/local". This code is defined as member variables. This code is usually found in an initialization method. JBoss Community Documentation Page 276 of 617 .EAP 5.ProductManager") private ProductManager productManager. lookupError).lookup("OrderManagerApp/ProductManagerBean/local").AS 7 @EJB(lookup="java:app/OrderManagerEJB/ProductManagerBean!services. Old . } catch(Exception lookupError) { throw new ServletException("Unable to find the ProductManager bean". try { context = new InitialContext(). The lookup name now uses the new portable java:app JNDI namespace: "java:app/OrderManagerEJB/ProductManagerBean!services.5.WildFly 8 25.ProductManager" New .ejb.3 Modify your application code to follow the new JNDI namespace rules Here's an example of a JNDI lookup in EAP 5.ejb.1. productManager = (ProductManager) context. } Here is an example of how the same lookup would be coded in WildFly 8.1 private ProductManager productManager.

only accessible within the same application) OrderManagerApp/ProductManagerBean/local java:global/OrderManagerApp/OrderManagerEJB/ProductManagerBean (EE6 standard binding.Portable JNDI Syntax Application-specified Portable JNDI Names 25.ejb.ProductM binding.5.ProductManager (EE6 st accessible within the same module) OrderManagerApp/ProductManagerBean/local java:app/OrderManagerEJB/ProductManagerBean!services.4 Examples of JNDI mappings in previous releases and how they might look now (This needs input!) Previous Namespace New Namespaces OrderManagerApp/ProductManagerBean/local java:module/ProductManagerBean!services.6 Migrate remote EJB clients to the WildFly 8 client API TODO: complete this section JBoss Community Documentation Page 277 of 617 .5.WildFly 8 25. use this if java:comp/Us available) java:/TransactionManager java:jboss/TransactionManager java:/TransactionSynchronizationRegistry java:jboss/TransactionSynchronizationRegistry 25.ejb. globally accessible) java:comp/UserTransaction java:comp/UserTransaction (This will not be accessible for non EE thread application directly creates) java:comp/UserTransaction java:jboss/UserTransaction (Globally accessible.5 Where to Find Additional Information Java EE6 Tutorial .

This is typically the jar name of the EJB deployment.ear suffix.xml. <bean-name> . 2.7.7 Migrate EAP 5 Deployed Applications That Make Remote Invocations to WildFly 8 25.jar suffix. This is typically the ear name without the . <fully-qualified-classname-of-the-remote-interface> . however. The client application then looked up the stateful bean using "ejbName/remote". is the simple class name of the bean implementation class. In this example.the remote view fully qualified class name. by default. so the module name is jboss-as-ejb-remote-app. <distinct-name> .1 Overview In WildFly 8. <module-name> . JBoss Community Documentation Page 278 of 617 .by default.WildFly 8 25. In EAP 5.an optional distinct name for the EJB.xml file. If the application is not deployed as a . under the name "ejbName/local" for local interfaces.ear.the application name of the deployed EJBs. the name can be overridden in the application. so it uses an empty string. In AS 7.the module name of the deployed EJBs on the server. but can be overridden via the ejb-jar. the EJB remote interface was bound in JNDI. You can use JNDI to lookup a proxy for your bean and invoke on that returned proxy. assume the EJBs were deployed in a jboss-as-ejb-remote-app. without the . This example doesn't use a distinct name. and "ejbName/remote" for the remote interfaces. Assume this example was not deployed as an EAR. this value is an empty string. there are two ways to make remote invocations to the server: 1. You can use the new JBoss specific EJB client API to do the invocation.jar. you use the ejb: namespace for remote access to EJBs with the following syntax: For stateless beans: ejb:<app-name>/<module-name>/<distinct-name>/<bean-name>!<fully-qualified-classname-of-the-remote-interface> For stateful beans: ejb:<app-name>/<module-name>/<distinct-name>/<bean-name>!<fully-qualified-classname-of-the-remote-interface>?s The values to be substituted in the above syntax are: <app-name> . This section covers option 2: coding changes required for clients that use JNDI.

} } In EAP 5. } @Override public int subtract(int a.ejb.add(a. RemoteCalculator calculator = (RemoteCalculator) ctx. Note that it exposes a remote view for the bean. int b = 340.getName(). int b = 340.class.WildFly 8 25.class. final String beanName = CalculatorBean.lookup("ejb:" + appName + "/" + moduleName + "/" + distinctName + "/" + beanName + "!" + viewClassName).URL_PKG_PREFIXES.lookup("CalculatorBean/remote"). int sum = calculator. final Context context = new InitialContext(jndiProperties). final String distinctName = "".2 Update the Client Code Assume you have deployed the following stateless EJB to an AS 7 server. final String viewClassName = RemoteCalculator. int a = 204.put(Context.client.class) public class CalculatorBean implements RemoteCalculator { @Override public int add(int a. b). int sum = statelessRemoteCalculator. jndiProperties. int b) { return a . int a = 204. b)).add(a. using the information described above. final String appName = "".b. the client EJB lookup and invocation was coded something like this: InitialContext ctx = new InitialContext().naming"). final String moduleName = "jboss-as-ejb-remote-app". @Stateless @Remote(RemoteCalculator.7. the client lookup and invocation is coded like this: final Hashtable jndiProperties = new Hashtable().jboss. "org. int b) { return a + b. you must append “?stateful” to the end of the context lookup like this: JBoss Community Documentation Page 279 of 617 . In AS 7. If your client is accessing a stateful EJB. final RemoteCalculator statelessRemoteCalculator = RemoteCalculator) context.getSimpleName().

see EJB invocations from a remote client using JNDI.lookup("ejb:" + appName + "/" + moduleName + "/" + distinctName + "/" + beanName + "!" + viewClassName + "?stateful"). including both server and client code. For more information on remote invocations using JNDI. JBoss Community Documentation Page 280 of 617 . A complete working example. can be found at the github repo here https://github.com/jbossas/quickstart/tree/master/ejb-remote.WildFly 8 final RemoteCalculator statelessRemoteCalculator = RemoteCalculator) context.

Regardless of your decision. because of the modular class loading changes. See the logging documentation 25. you will probably need to modify your application to add the required dependencies. private static final Logger logger = Logger.4 Where to Find Additional Information WildFly 8 Logging JBoss Logging Tooling JBoss Community Documentation Page 281 of 617 . Your MANIFEST-MF file will look like this: Dependencies: org.WildFly 8 25.2 Update your application code for third-party logging frameworks As of WildFly 8.jboss.jboss.8. There is one caveat to this.8.Logger.. 25.logging For more information on how to find the module dependency.logging.toString()).isTraceEnabled()) { logger. If you're using log4j and you don't want to use the logging subsystem to configure your handlers (appenders). import org.logging".1 Overview JBoss LogManager supports front ends for all logging frameworks. subsystem).Level.8. so you can keep your current logging code or move to the new JBoss logging infrastructure.jboss.tracef("Starting. } The JAR containing the JBoss Logging classes is located in the module named "org. you will need the change your imports and code as follows to achieve the same results as above: import org.8.jboss.getLogger(MyClass.8 Modify logging dependencies 25. if(logger.3 Modify code to use the New JBoss Logging Framework To use the new framework. 25.logging. then you need to exclude the server copy of log4j.". logging dependencies are added by default. please see “How to Resolve ClassNotFoundExceptions” under the “Modular Class Loading” above.class..

this will not be a problem. so you will need to use the second approach. Details on how to do this are described here: JPA Reference Guide. For more information on Hibernate and JPA.9 Configure changes for applications that use Hibernate and JPA 25. You will be able to deploy and run successfully using Hibernate 4. if you see a ClassNotFoundExceptions when deploying your application you can try one of two following approaches: 1. in most cases. It will implicitly add Hibernate 4 and a few other dependencies to your application classpath. JBoss Community Documentation Page 282 of 617 .WildFly 8 25. In some cases this may result in ClassCastExceptions or other class loading issues due to the mixed use of the Hibernate versions.9. However. 2. WildFly 8 will detect this during deployment and assume the application uses JPA. You need to tell the server to use only the Hibernate 3 libraries and you will need to add exclusions for the Hibernate 4 libraries. You may be able to resolve the issue by copying the specific Hibernate 3 JARs containing those classes into the application "/lib" directory or by adding them to the classpath using some other method.xml file or the code uses @PersistenceContext or @PersistenceUnit.1 Overview If your application contains a persistence. If your application currently uses Hibernate 3 libraries. see JPA Reference Guide.

countDistinct( propertyName )).sum( propertyName ). As a result.5 versions of Hibernate. or. JBoss Community Documentation Page 283 of 617 . "materialized_clob". text type were mapped to JDBC CLOB. a Long value is returned. "sum" projections return a value type that depends on the property type due to changes in Projections.3 applications 1. the return type from the following projections in org. Failure to modify your application code may result in a java. Numeric aggregate Criteria projections now return the same value type as their HQL counterparts.WildFly 8 25. @Type(type = "text") should be replaced by @Lob. a Double value is returned. was added to map Java String properties to JDBC CLOB.rowCount(). Hibernate "text" type now maps to JDBC LONGVARCHAR In pre-3. for properties mapped as Long. 2. for properties mapped as Float.criterion have changed: 1.ClassCastException. 2. or primitive integer types.count( propertyName ).2 Update your Hibernate 3 application to use Hibernate 4 Changes for Hibernate 3. 1. Short. A new Hibernate type.9. Double. Integer. 2. Projections.lang. If an application has properties configured as type="text" that are intended to be mapped to JDBC CLOB. or primitive floating point types. and Projections. Projections.hibernate. "count" and "count distinct" projections now return a Long value (due to changes in CountProjection. if using annotations. they should be changed to type="materialized_clob" in hbm mapping files.

EJB3NamingStrategy in AnnotationConfigration instead of the older org.2.id.2 Identifiers in general and about 5.org/dtd/hibernate-mapping-3 3.dtd http://www.hibernate. you should be aware that WildFly 8 now uses the org. consider setting the value to false in persistence. General Changes when migrating to Hibernate 4 In Hibernate 4.0.xml in case you don't see the behaviour you had in your app in previous versions. 4.0 there is a new IdentifierGenerator implementations. the global environment variable "hibernate.read about 5. However. This can result in naming mismatches.0 supplies a property that is called hibernate.DefaultNamingStrategy that was previously used in Configuration.use_streams_for_binary" must be set to false if you are using CLOB or BLOB properties.net/hibernate-configuration-3. for more information .jdbc.sourceforge. if you are still using an hbm.1.sourceforge. AnnotationConfigration must be merged into Configuration Aside from the fact that AnnotationConfiguration is now deprecated. If you are using Oracle.WildFly 8 Changes for Hibernate 3. The namespaces for the Hibernate DTD files have changed.DefaultNamingStrategy#INSTANCE 2.2.hibernate.xml file. Identifier generator more specifically* *here JBoss Community Documentation Page 284 of 617 .cfg.use_streams_for_binary" must be set to true if you are using "materialized_clob" or "materialized_blob" properties.hibernate.0.hibernate.DefaultNamingStrategy by calling Configuration#setNamingStrategy and passing it org.5 applications 1.dtd http://www. you may see this issue.hibernate.cfg.org/dtd/hibernate-configurati http://hibernate. you can tell Hibernate to use the the legacy org.1 this value defaults to true. If you are using PostgreSQL. Previous DTD Namespace New DTD Namespaces http://hibernate. the global environment variable "hibernate.1.hibernate.however in AS 7.jdbc.net/hibernate-mapping-3. this usually is not of concern.cfg. Hibernate 4.cfg. If you rely on the naming strategy to default the name of a association (many-to-many and collections of elements) table.new_generator_mappings and hibernate documentation states that it defaults to false for backward compatibility reasons . To resolve it.

jira AS7-1663 (An extended persistence context should not be propagated if there is no JTA transaction) was fixed in WildFly 8. depending on if you're using JPA or Hibernate APIs.0 specification section 7. If a SFSB with an extended persistence context.3 Changes in JPA container managed behaviour To comply with the JPA 2.1 requirements for persistence context propagation. The syntax is slightly different. The extended persistence context will not be propagated to the transactional entity manager (propagation will occur if invoked with an active JTA transaction).9. 25. If your application expects the extended persistence context to be propagated to the bean with the transactional entity manager. This requires a change to the persistence.3.9.4 Infinispan as Second Level Cache Overview JBoss Cache has been replaced by Infinispan for 2nd level cache (even for non-clustered use). These examples assume you are using JPA. JBoss Community Documentation Page 285 of 617 .6.WildFly 8 25.xml file. invokes another bean (not in an active JTA transaction) and the other bean uses a transactional entity manager. you need to change your app to do the invocation with an active JTA transaction.

cache.transaction.cache.WildFly 8 Infinispan second-level cache settings Here's an example of the persistence.factory_class property.cache.factory_class" value="org.hibernate.use_second_level_cache" value="true"/> <property name="hibernate.region.use_minimal_puts" value="true"/> Here is what is needed to configure the same thing for a native Hibernate application using Infinispan with WildFly 8: <property name="hibernate.JBossTransactionManagerLookup"/> <property name="hibernate.region.jbc2.region. For native Hibernate applications you need to: Select the correct Hibernate transaction factory using the hibernate.transaction.manager_lookup_class" value="org.cache.cachefactory" value="java:CacheManager"/> <property name="hibernate. Select the correct Hibernate transaction manager lookup class using the hibernate.jbc2.infinispan.JndiInfinispanRegionFactory"/> <property name="hibernate.cache.region.cachemanager" value="java:jboss/infinispan/hibernate"/> <property name="hibernate. fewer properties are needed to be specified.cfg.entity" value="mvcc-entity"/> <property name="hibernate.factory_class" value="org.manager_lookup_class property.transaction.cache.transaction.xml file in EAP 5. select JndiInfinispanRegionFactory as the cache region factory and add the cache manager’s JNDI name If running JPA/Hibernate and Infinispan standalone or within third party application server.1: <property name="hibernate.infinispan.JndiMultiplexedJBossCacheRegionFactory"/> <property name="hibernate.cache.cache.cache.use_minimal_puts" value="true"/> <property name="hibernate.hibernate.cache.cache.cache.use_minimal_puts" value="true"/> Since JPA applications use Infinispan by default. Configure the Infinispan cache region factory using one of the two options below: If the Infinispan CacheManager is bound to JNDI.cache.use_second_level_cache" value="true"/> <property name="hibernate.cache.region_prefix" value="services"/> Here is what is needed to configure the same thing for a JPA application using Infinispan with WildFly 8: <property name="hibernate.hibernate.use_second_level_cache" value="true"/> <property name="hibernate. select InfinispanRegionFactory as the cache region factory JBoss Community Documentation Page 286 of 617 .jbc2.

Other values are auto. you can ignore groups as Hibernate Validator 3 did not have such a feature.mode to none.hibernate.constraints and org.pre-update.persistence.validation. Life cycle triggered validation When used in combination with Hibernate 4 life-cycle based validation will be automatically enabled by Hibernate Core. You can customize your Validator instance by using a fluent API starting with ValidatorFactory.x to 4.persistence.usingContext. You just need to import the right class and in some cases change the name and/or type of a constraint parameter. callback and ddl. fully specified class names of the groups to validate.group. TraverableResolver and ConstraintValidatorFactory.9.x means switching to a completely new code base and new API the JSR 303 (Bean Validation). Using the new Bean Validation constraints This is the most visible change fro Hibernate Validator 3 constraints in your code base. and javax.persistence. CDI bean or any other Java EE injectable resource. you need to create a Validator instance from the ValidatorFactory via ValidatorFactory. An empty set indicates a successful validation without any constraint violations.validation. Once you have your Validator instance. All constraints which existed in Validator 3 are available in Validator 4. UPDATE and DELETE operations.validation. Accessing the default ValidatorFactory WildFly 8 binds a default ValidatorFactory to the JNDI context under the name java:comp/ValidatorFactory.validation.constraints packages.validation. use the validate methods to either validate your whole entity or just a single property.5 Migrate to Hibernate 4 Validator Migrating from Hibernate Validator 3. Using this API you can configure a custom MessageInterpolator. All these interfaces are new to Hibernate Validator and are specified in the Bean Validation specification. You can configure the groups to be validated per event type using the properties javax.validator.getValidator. where auto is the default.persistence. The good news is that this migration should be straight forward. Manual validation In case you want to manually validate. or get Validator injected in your EJB. The values of these properties are the comma-separated. A call to any validate method will return a set of ConstraintViolation instances (in contrast to an array of InvalidValue instances in Validator 3). Let's have a look at the different parts which needs updating. You can also disable life-cycle based validation by setting the javax.pre-persist. For a pure migration however.group. javax. To upgrade to Hibernate Validator 4 you have to use the constraints in the javax.group.WildFly 8 25. The former contains the standardized Bean Validation constraints whereas the latter contains some Hibernate Validator specific constraints.pre-remove. The validation groups feature is part of the Bean Validation specification and it is recommended you get familiar with this new functionality. Validation will occur on entity INSERT. JBoss Community Documentation Page 287 of 617 .

validator.WildFly 8 Custom constraints In Validator 3 a custom constraint needed to implement org.validation.hibernate. Where to Find Additional Information Infinispan Using Infinspan as JPA/Hibernate Second Level Cache Provider HIBERNATE . Only the method signature is slightly different.Validator.ConstraintValidator which contains the same methods as the old interface. Note that support for DDL alteration is no longer part of Hibernate Validator 4 but very few users made use of this feature.RelationalPersistence for Idiomatic Java JBoss Community Documentation Page 288 of 617 . In Validator 4 the interface to implement is javax. namely initialize and isValid.

You should remove all of the resteasy configuration from your web.properties"/> </login-module> </authentication> </security-domain> If you are running in standalone mode.dir}/example-users.2 Modify security domain names In WildFly 8 security domains no longer use the prefix java:/jaas/ in their names.config.server.WildFly 8 25.11 Configure JAX-RS / Resteasy changes WildFly 8 sets up Resteasy for you.xml for enterprise applications. files in the JBOSS_HOME/server/SERVER_NAME/conf directory were on classpath so you could put your properties files there. In WildFly 8 the directory structure has changed.xml for web applications and jboss. In previous versions of AS. ${jboss.config.1 Configure Security for Basic Authentication The UsersRolesLoginModule has always looked for the properties files in the classpath.server.properties"/> <module-option name="rolesProperties" value="${jboss. To configure security for basic authentication.10 Changes you need to make for Security 25. so there is no need to set it up yourself.dir}/example-roles.xml configuration file : <security-domain name="example"> <authentication> <login-module code="UsersRoles" flag="required"> <module-option name="usersProperties" value="${jboss. add a new security domain under security-domains to your standalone.config.xml and replace it with one of the following three options: JBoss Community Documentation Page 289 of 617 .10. 25. 25. so you need to package the properties within the application to make them available in the classpath.dir} refers to JBOSS_HOME/standalone/configuration/ A list of available login modules can be found in the admin guide.server.10. Remove this prefix from the security domain configurations in jboss-web.

Application in your application.rs. and annotate it with the path that you want your JAX-RS classes to be available.Application and use web.ws.MyApplication</servlet-name> <url-pattern>/hello/*</url-pattern> </servlet-mapping> This will make your JAX-RS resources available under /mywebappcontext/hello.ws.rs. For example: @ApplicationPath("/mypath") public class MyApplication extends Application { } This will make your JAX-RS resources available under /mywebappcontext/mypath.core.ws. JBoss Community Documentation Page 290 of 617 .core.rs.xml If you do not wish to use @ApplicationPath but still need to subclass Application you can set up the JAX-RS mapping in web.Application and use @ApplicationPath This is the easiest way and does not require any xml configuration.acme. You can also use this approach to override an application path set with the @ApplicationPath annotation.WildFly 8 Subclass javax.core.xml: public class MyApplication extends Application { } <servlet-mapping> <servlet-name>com. Simply include a subclass of javax. Note that that the path is /mypath not /mypath/* Subclass javax.

.naming. The following is an example of configuration in WildFly 8: JBoss Community Documentation Page 291 of 617 .security.LdapCtxFactory</module-option> <module-option name="java. not the corresponding servlet. The server is responsible for adding the corresponding servlet automatically.core.WildFly 8 Modify web.security.ws. Note that you only have to add the mapping. 25.factory.initial">com. The following is an example of configuration in a previous release: <application-policy name="mcp_ldap_domain"> <authentication> <login-module code="org.LdapExtLoginModule" flag="required"> <module-option name="java.rs.xml If you don't want to subclass Application you can set the JAX-RS mapping in web.spi. the LDAP realm is configured as a security-domain in the standalone/configuration/standalone.xml as follows: <servlet-mapping> <servlet-name>javax.auth..jndi.ldap.xml file. see the JAX-RS Reference Guide.authentication">simple</module-option> .xml file if you are running a standalone server or in the domain/configuration/domain.sun.xml file if you are running your server in a managed domain. the LDAP realm was configured as an application-policy in the login-config.12 Configure LDAP security realm changes In previous releases of JBoss AS.naming.Application</servlet-name> <url-pattern>/hello/*</url-pattern> </servlet-mapping> This will make your JAX-RS resources available under /mywebappcontext/hello..jboss. </login-module> </authentication> </application-policy> In WildFly 8. For more information.

.initial" value="com.LdapCtxFactory"> <module-option name="java.authentication" value="simple"> .13 Migrate from JBoss Messaging to HornetQ JBoss Messaging will no longer be included in EAP 6.naming.LdapLoginModule" flag="required"> <module-option name="java. the module options must be specified as element attributes with "value=" as follows: <module-option name="java.ldap. you will need to make changes to your application to use HornetQ.naming. Make a backup of any JBoss Messaging data.initial" value="com.auth. Message data is stored in a database. 2. Shut down the client and server.1 Before you start 1.sun.factory. and the tables are prefixed with "JBM_".13. 25.naming.WildFly 8 <subsystem xmlns="urn:jboss:domain:security:1.security.sun..jboss.security. In previous releases.jndi.jndi. </module-option> </module-option> </login-module> </authentication> </security-domain> </security-domains> </subsystem> The XML parser has also changed in WildFly 8.naming.factory.jndi. you specified the module options as element content like this: <module-option name="java.0"> <security-domains> <security-domain name="mcp_ldap_domain" type="default"> <authentication> <login-module code="org.initial">com. Backup these tables as necessary.LdapCtxFactory"/> 25.ldap. JBoss Community Documentation Page 292 of 617 .LdapCtxFactory</module-option> In WildFly 8.ldap.factory.spi. If your application uses JBoss Messaging as the messaging provider.sun.

JBoss Community Documentation Page 293 of 617 .these files contain bridge services deployed with JBoss Messaging.these files contain JMS queues and topics deployed with JBoss Messaging. Destination service configurations . No bridges are deployed by default.13. no code changes are required. depending on your JBoss Messaging installation. 25. Instructions for this are available here.xml. These configurations are located in deployment descriptors on the server running JBoss Messaging. This includes the following configurations: Connection Factory service configuration files .WildFly 8 25. Note: WildFly 8 doesn't currently support JMS bridges configured in standalone*.xml in the deploy/messaging directory of your application server.2 Transfer configurations Transfer the existing JBoss Messaging configurations to the WildFly 8 configuration.13. if the application will be connecting to a cluster (which is outside the scope of the JMS specification) please carefully review the HornetQ documentation on clustering semantics as HornetQ and JBoss Messaging have taken substantially different approaches in their respective implementations of clustering functionality. modify the code to use equivalent features available in HornetQ (if available). these are stored in a destinations-service. Refer to Messaging configuration for details on HornetQ configurations.3 Modify application code If the application code uses standard JMS. so the name of the deployment file will vary.13. JBoss Messaging stores these files in a file called connection-factories-service. For more information on HornetQ. However. see HornetQ Project Documentation and the HornetQ homepage. 25. By default. If the application code uses features specific to JBoss Messaging.these files contain JMS connection factories deployed with JBoss Messaging. This will change in a future version. Message bridge service configurations .4 Migrate existing messages Move any messages in the JBoss Messaging database to the HornetQ journal via a JMS bridge.xml in the deploy/messaging directory of your application server.

$ . start the server using the appropriate configuration file: $ .14.xml -Djboss.g.sh --server-config=standalone-ha.name=UNIQUE_NODE_NAME JBoss Community Documentation Page 294 of 617 . or as standalone servers. the method of enabling clustering depends on whether your servers are started via the domain controller.14 Changes you need to make for Clustering 25.sh -c all In WildFly 8. update your domain.WildFly 8 25.1 Starting WildFly 8 with clustering enabled To enable clustering in AS5 and AS6.xml and designate a server group to use the "ha" profile and "ha-sockets" socket binding group: e.g. you needed to start your server instances using the "all" profile (or some derivation of it)./bin/standalone./bin/run. To enable clustering for servers started via the domain controller. <server-groups> <server-group name="main-server-group" profile="ha"> <jvm name="default"> <heap size="64m" max-size="512m"/> </jvm> <socket-binding-group ref="ha-sockets"/> </server-group> </server-group> To enable clustering for standalone servers.node. e.

0.2 Specifying the bind address In AS5 and AS6. $ . --> </socket-binding-group> </socket-binding-groups> In the example above.14. bind addresses are specified within domain/configuration/host. <interfaces> <interface name="management"> <inet-address value="192..1" default-virtual-server="default-host" native="false" instance-id="{JVM_ROUTE_SERVER}"> The JVM_ROUTE_SERVER above should be replaced by the jvmRoute server ID. bind addresses are explicitly defined by the relevant socket bindings within the WildFly 8 configuration files. In AS 7. For standalone servers.2 In WildFly 8.2"/> </interface> <interface name="public"> <inet-address value="192.sh -c all -b 192.g.. bind addresses are specified within the standalone-ha.2"/> </interface> </interfaces> <socket-binding-groups> <socket-binding-group name="ha-sockets" default-interface="public"> <!-. 25. the web server jvmRoute was configured using a property in the server. the jvmRoute attribute is configured in the web subsystem of the server configuration file using the instance-id attribute as follows: subsystem xmlns="urn:jboss:domain:web:1.14./bin/run.WildFly 8 25.3 Configure jvmRoute to support mod_jk and mod_proxy In previous releases.xml file.0..168. e.168. For servers started via the domain controller.168.xml.g.xml: e. you would typically indicate the bind address used for clustering via the "-b" command line argument. JBoss Community Documentation Page 295 of 617 . the "public" interface is specified as the default interface for all sockets within the "ha-sockets" socket binding group.0.

11.port" is the variable for the port.0" default-stack="udp"> <stack name="udp"> <transport type="UDP" socket-binding="jgroups-udp"/> <!-.14.11.mcast./bin/run.11 -Djboss.addr" is the variable for the multicast address and "jboss.mcast.mcast. <subsystem xmlns="urn:jboss:domain:jgroups:1.sh -Djboss.0...4}" multicast-port="${jboss.11 -m 45688 In WildFly 8..addr=228. . --> <socket-binding name="jgroups-udp" port="55200" multicast-address="228. the multicast address and port used for intra-cluster communication are defined by the socket-binding referenced by the relevant JGroups protocol stack. you could specify the multicast address and port used for intra-cluster communication using the command line arguments "-u" and "-m".mcast.11" multicast-port="45688"/> <!-.. e.11.11.0.11. you can define the multicast address and ports as system properties and then use those properties on the command line when you start the server..4 Specifying multicast address/port In AS5 and AS6..WildFly 8 25. --> </stack> </subsystem> <socket-binding-groups> <socket-binding-group name="ha-sockets" default-interface="public"> <!-.addr:230.port=45688 JBoss Community Documentation Page 296 of 617 . "jboss. In the following example.mcast. e.. <socket-binding name="jgroups-udp" port="55200" multicast-address="${jboss.g. --> </socket-binding-group> </socket-binding-groups> If you prefer to specify the multicast address and port in the command line..11.g.port:45688}"/> You can then start your server using the following command line arguments: $ . respectively./bin/domain.mcast..sh -c all -u 228.

e.stack" system property. .g.xml or jboss-beans.g. or you can place the files directly in the deployments directory. You can continue to package the files in the EAR or SAR.xml. JBoss Community Documentation Page 297 of 617 . the default protocol stack is defined by the JGroups subsystem within domain.stack=tcp In WildFly 8.0" default-stack="udp"> <stack name="udp"> <!-. <subsystem xmlns="urn:jboss:domain:jgroups:1.5 Using an alternate protocol stack In AS5 & AS6. they should run with little or no modification in AS 7.default.WildFly 8 25. This means that if you used jboss-service. --> </stack> </subsystem> 25. you could manipulate the default protocol stack used for all clustering services via the "jboss.sh -c all -Djboss..jgroups.xml deployment descriptors in your AS5/AS6 application.plugins:jboss-as-maven-plugin to deploy to the correct directory.1 Change Maven plugin name The jboss-maven-plugin has not been updated and does not work In WildFly 8.16. the deployments directory is located here: JBOSS_HOME/standalone/deployments/.16 Additional changes you may need to make 25.jboss. If you are running a standalone server. the container supports these service-style deployments without change where possible.as. 25. e.16.14.15 HA Singleton Deployment TODO: This topic needs content 25.. You must use org./bin/run..2 Update Applications That Use Service-style Deployments Although AS 7 no longer uses service-style descriptors.xml or standalone-ha.jgroups.default.

you may need to move JARs to a different location within the application archive or modify class-path information so classes can be found.17 Debug and Resolve Migration Issues 25. Due to modular class loading changes. or missing archives.17.1 Debug and resolve ClassNotFoundExceptions and NoCLassDefFoundErrors ClassNotFoundExceptions can occur due to application packaging issues. a business class. for example. If the class is is external to your project. you may need to explicitly define the dependencies on other modules or possibly copy an archive from a previous framework. For more information on EAR and WAR packaging.WildFly 8 25. unresolved dependencies. your application may no longer be able to find classes within the EAR or WAR. see "WAR Class Loading" and "EAR Class Loading" in Class Loading in AS7. JBoss Community Documentation Page 298 of 617 . In his case. the problem is mostly likely a packaging issue. Change the application structure to find classes within the application If the class specified in the exception is a class written specifically for the application. If the class specified is a class you have created in your application. you may need to change the packaging of the application.

to resolve the dependency you will find the JAR that contains the class specified by the ClassNotFoundException by looking in the JBoss WildFly 8 modules directory. Find the module containing the JAR in the JBOSS_HOME/modules directory and determine the module name. You can use Tattletale to find the JBoss module name.commons. you must add a dependency to the manifest entry. If there is no obvious module path for the class 1.Log from [Module "deployment. 2. there is org/apache/commons/logging 3.ModuleClassLoader.commons.org. Add the module name to the Dependencies in the MANIFEST.logging 2. 2. First determine if there is an obvious module for the class 1.jcl-over-slf4j JBoss Community Documentation Page 299 of 617 .logging.ClassNotFoundException: org. For example.apache. You can manually find the module dependencies.java:188) Find the JBoss module containing this class by doing one of the following: 1. 2. in this case.war:main" from Service Module Loader] at org.jboss. under modules. Navigate to the JBOSS_HOME/modules directory and look for the module path. 1.slf4j. 3. If you find a module for the class.findClass(ModuleClassLoader.apache.TopicIndex. See the section: Use Tattletale to find application dependencies.lang. Open the JBOSS_HOME/modules/org/apache/commons/logging/main/module.dom4j.WildFly 8 How to find the JBoss module dependency For other classes. if you see this ClassNotFoundException trace in the log: Caused by: java.modules.MF file Dependencies: org. The module name to the Dependencies in the MANIFEST. 4.MF file: Dependencies: org.xml file and find the module name. Determine which JAR contains the class.

This will prevent the server from adding the dependencies. For example.MF file. and explicitly define the dependency in the MANIFEST. Copy this JAR to the application's lib/ directory.1. Issue the command: grep 'org.validator. It can also be a result of the same class existing in multiple JARs.ClassValidator r' `find . Exclude any conflicting dependencies using the jboss-deployment-structure.xml file: <exclusions> <module name="org. Then you must find the dependent JBoss module containing the class. Open a terminal and navigate to the EAP5_HOME/ directory. Often you need to find and remove the JAR from the application's WAR or EAR.jar'` 3.xml file There are cases where you will need to copy in older JARs for your applcation.lang.jar matches 4. find the JAR in your EAP 5. you may see ClassCastExceptions and need to exclude the conflicting module dependencies.Class. This is an example of the exclusions element in the jboss-deployment-structure.hibernate.WildFly 8 How to find the JAR in previous install If the class is not found in a JAR packaged in a module defined by the WildFly 8 server.1/seam/lib/hibernate-validator.2 Debug and resolve ClassCastExceptions This usually happens because the class is being loaded by a different class loader than the class it extends. \-name '*. If the newer JARs are loaded as automatic dependencies in WildFly 8./jboss-eap-5.x install or your prior server's lib directory and copy it to your application's lib/ directory.0_25] 1. Remove any unnecessary JARs from the Application archive First find the JAR that contains the class and determine how it is being loaded.17.NoClassDefFoundError: org/hibernate/validator/ClassValidator at java.javassist" /> </exclusions> JBoss Community Documentation Page 300 of 617 . You should see this (one of many) for the result: Binary file . 2.6.lang. you see this ClassNotFoundException in the log: Caused by: java. Rebuild and redeploy the application 25. when you migrate the Seam Booking application from EAP 5.getDeclaredMethods0(Native Method) [:1. 5.

you can often resolve the problem by printing class loader information to the log. add any dependencies as described above.Foo1.17. remove any common JARs from your application archive.Foo2.info("Class loader for foo1: " + com.xml file or excluding dependencies in the jboss-deployment-structure. This can occur when you package different versions of common libraries your application.getClass().Foo2 In your code.toString()). 25. add dependencies through the MANIFEST. You might have to remove or move a conflicting JARs.lang.WildFly 8 25.toString()). if you see the following ClassCastException in the log: java. This can also happen if you migrate between versions of JBoss EAP and do not recompile your application against the updated EAP jars.example1. print the class loader information by logging logger.ClassCastException: com. It indicates your application's calling class was compiled using a different version of the JAR than the one used by the application server runtime. based on your application. JBoss Community Documentation Page 301 of 617 . logger.getClass(). To resolve this problem.getClassLoader().4 Debug and resolve NoSuchMethodExceptions A NoSuchMethodException indicates a class version mismatch between JAR files.info("Class loader for foo2: " + com. you will need to determine the best approach to resolve the issue.17.Foo1 cannot be cast to com. For example.xml file.3 Debug and resolve class loading issues If you are not able to figure out how the classes are loaded. recompile and deploy your application.example2. The ModuleClassLoader information in the log will show which modules are loading the classes and.example2.getClassLoader().example1. for example Hibernate.MF or jboss-deployment-structure.

xml file.jboss.xml file. Use the same technique above under “How to Resolve ClassNotFoundExceptions or NoCLassDefFoundErrors” to resolve the dependencies. In AS6. Provide a <context-root> element in the in jboss-webservices.seam. Usually the root cause of the exception can be found in one of the links on this page. Customize the <context-root> for the WAR in the application.WildFly 8 25.17.17.caughtException. it may be due to the way JBoss WS handles the deployment. under the Component org.6 Debug and resolve JBoss Seam debug page errors. You can resolve this issue in one of the following ways: Rename the JAR file to a name that is different than the WAR. JBoss Community Documentation Page 302 of 617 . for example. This means that if you have a WAR and a JAR with the same name within an EAR.xml file. it may create a web context with the same name as the JAR which will conflict with the WAR context. 25. JBossWS introduced a Context Root Mapping Algorithm or rules for servlet based endpoints to allow it to become seamlessly compatible with TCK6.5 Debug and resolve DuplicateServiceExceptions If you get a DuplicateServiceException for a subdeployment of a JAR or a message that the WAR application has already been installed when you deploy your EAR in WildFly 8. Provide a <context-root> element in the in jboss-web.

25.xml file are now done in the server configuration file.xml is now ignored in deployments.1 requires the Java Enterprise Edition 6 Full Profile. you need modify your application code as follows.3 Modify the jboss-web. JBoss Community Documentation Page 303 of 617 . For a standalone server. and the jboss. 25.1 Modify the Code to Use the New JNDI Namespace Rules Like EJB 3.xml deployment descriptor replaces the jboss. pass the argument "-c standalone-full. If you are running your server in a managed domain. see the section 'Update application JNDI namespace names' above. the EJB container uses a new mechanism. Server side interceptors can be changed to EJB3 interceptors.xml" on the command line when you start the server.xml file. this is the domain/configuration/domain. you need to make a few code modifications and must start the server with the full profile.18.1.xml deployment descriptor.1. 25.18. this is the standalone/configuration/standalone. In previous releases. Standard EJB3 configurations that were made in the ejb3-interceptors-aop. JBoss AOP was used by the EJB container.18 EJB 2.18. The new file is incompatible with jboss. If your application uses JBoss AOP.5 Start the Server with the Full Profiles EJB 2. 25.x Support As 7.18. you must use the full JNDI prefix with EJB 2.xml deployment descriptor file The jboss-ejb3. However.18.xml deployment descriptor to override and add to the features provided by the Java Enterprise Edition (EE) defined ejb3-jar.WildFly 8 25. in AS 7. For more information on the new JNDI namespace rules and code examples.4 Replace the jboss. but there is no client side interceptor in AS 7. however.xml file.xml File Descriptor Modify the <jndi-name> for each <ejb-ref> to use the new JNDI fully qualified lookup format. To start AS 7 with the full profile.2 Replace JBoss AOP Interceptors JBoss AOP (Aspect Oriented Programming) is no longer included in WildFly. Applications that integrate AOP interceptors into the EJB layer must be redesigned to use EJB3 interceptors and CDI. 25.xml.1 provides support for EJB 2.0.

20. you will follow the steps outlined in the migration guide.DB_CLOSE_DELAY=-1 --driver-name=h2 --user-name=sa --password=sa JBoss Community Documentation Page 304 of 617 . You will also need to determine if the application has any dependencies on archives that do not ship with AS7 and copy any dependent JARs into the application lib/ directory.DB_CLOSE_DELAY=-1</connection-url> <driver>h2</driver> <security> <user-name>sa</user-name> <password>sa</password> </security> </datasource> This definition is a copy of the default HSQL datasource defined in WildFly. You will need to specify any module dependencies. The easiest way is to define this datasource is to add the following datasource definition to the JBOSS_HOME/standalone/configuration/standalone.WildFly 8 25.1 Overview When you migrate a Seam 2 application.20.sh --connect [standalone@localhost:9999 /] data-source add --name=ExampleDS --jndi-name=java:/ExampleDS --connection-url=jdbc:h2:mem:test. You can also add the datasource using the jboss-cli command line interface: $ JBOSS_HOME/bin/jboss-cli. 25.19 Migration required for other components ToDo: Conplete this section 25.2 Update the datasource configuration Some Seam 2 examples use a default JDBC datasource named java:/ExampleDS.20 How to migrate Seam 2 archives to WildFly 8 25.xml file the : <datasource name="ExampleDS" jndi-name="java:/ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true"> <connection-url>jdbc:h2:mem:test. You will need to configure the datasource as noted above.

2 modules and exclude the JSF 2.api" slot="1. If you end up with ClassNotFoundExceptions or ClassCastExceptions involving hibernate classes.2" export="true"/> <module name="com. you may still be able to run with the Hibernate 4 module packaged in WildFly. Some hibernate classes are no longer available and you may need to copy one or more of the older hibernate JARs into the /lib directory.2" export="true"/> </dependencies> </deployment> <sub-deployment name="jboss-seam-booking.20.sun.xml <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0"> <deployment> <exclusions> <module name="org.0 modules.faces.api" slot="main"/> <module name="com. You will need to create a jboss-deployment-structure. you will need to add dependencies for the JSF 1.war"> <exclusions> <module name="javax.0"> <deployment> <dependencies> <module name="javax.WildFly 8 25.jsf-impl" slot="1. you may have to exclude the hibernate module in the deployments section of the META-INF/jboss-deployment-structure.sun.4 Copy dependent archives from outside frameworks or other locations Even if your Seam 2 application uses Hibernate 3.faces.sun.3 Add any required dependencies Since Seam 2 applications use JSF 1.hibernate"/> </exclusions> <deployment> </jboss-deployment-structure> JBoss Community Documentation Page 305 of 617 .api" slot="1.2.jsf-impl" slot="1.2"/> </dependencies> </sub-deployment> </jboss-deployment-structure> If your application uses any third-party logging frameworks you will need add dependencies as described in that section of the migration guide. 25.20.faces.2"/> <module name="com.xml file in the EAR META-INF/ directory that contains the following data: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.jsf-impl" slot="main"/> </exclusions> <dependencies> <module name="javax.

xml: <!-. which were in JBoss AS 5/6 and are upgraded in WildFly to higher major version: slf4j-api. 2.20.jar 4.jar hibernate-annotations.apache.xml file from the jboss-seam-jpa.xml to jboss-seam-jpa.jar hibernate-entitymanager.api" slot="1.sun.log4j" /> <module name="org.commons.commons.jsf-impl" slot="main"/> </exclusions> <dependencies> <module name="org. Add jboss-deployment-structure.apache.sun.xml for Seam 2 JPA example migration 04:50 JBoss Community Documentation Page 306 of 617 .api" slot="main"/> <module name="com.Defined class loading in jboss-web.<property name="hibernate. Add the following dependencies from seam distribution (seam/lib directory) into jboss-seam-jpa.HashtableCacheProvider"/> --> 3.collections" /> <module name="javax.5 Seam 2 JPA example deployment on WildFly 1.xml is now default behaviour.cache.dom4j" /> <module name="org.war/WEB-INF/classes/META-INF/persistence.apache.jsf-impl" slot="1.logging" /> <module name="org. Remove the jboss-web.hibernate.war/WEB-INF/ with the following content in it: <jboss-deployment-structure> <deployment> <exclusions> <module name="javax.war/WEB-INF/lib directory.2"/> <module name="com.6 jboss-deployment-structure.jar hibernate-validator.jar hibernate-core.2"/> </dependencies> </deployment> </jboss-deployment-structure> Name Size Creator Creation Comment Date XML File 0.WildFly 8 25.provider_class" value="org. Comment or remove hibernate property in jboss-seam-jpa.jar slf4j-log4j12.cache.xml kB Marek Jul 18.faces. Novotny 2011 jboss-deployment-structure.war/WEB-INF/ directory .jar hibernate-commons-annotations.faces.

20.jboss.NameNotFoundException errors in the log like the following: javax.example.Authe java:app/jboss-seam-booking. 1. The JNDI binding messages should look similar to this: 15:01:16.Authenticator java:global/jboss-seam-booking/jboss-seam-booking.naming. add a matching component element to the components.xml file.booking.21 Running Seam 3 archives on WildFly ToDo: Complete this section JBoss Community Documentation Page 307 of 617 . you can modify the application's components.seam.jboss.as.jboss.EjbJndiBindingsDeploymentUnitProcessor] (MSC service thread 1-1) JNDI bindings for session bean named AuthenticatorAction in deployment unit subdeployment "jboss-seam-booking.deployment.example.jar/AuthenticatorAction!org. you may see javax.6 How to debug and resolve Seam 2 JNDI errors When you migrate a Seam 2 application.ejb3. you will need to replace the existing core-init element as follows: <!-.booking.naming.example. First.xml file: <component class="org. For each JNDI binding INFO message in the log. find the JNDI binding INFO messages that are printed in the server log when the application is deployed.jar/AuthenticatorAction java:module/AuthenticatorAction 3.processors.NameNotFoundException: Name 'jboss-seam-booking' not found in context '' If you don't want to modify JNDI lookups throughout the code.jar/AuthenticatorAction java:app/jboss-seam-booking.jar/AuthenticatorAction!org.booking.jar" of deployment "jboss-seam-booking.seam.WildFly 8 25.jboss.AuthenticatorAction" jndi-name="java:app/jboss-seam-booking.ear" are as follows: java:global/jboss-seam-booking/jboss-seam-booking.Authenticator java:module/AuthenticatorAction!org.138 INFO [org.booking.seam. Next.seam.example.<core:init jndi-pattern="jboss-seam-booking/#{ejbName}/local" debug="true" distributable="false"/> --> <core:init debug="true" distributable="false"/> 2.jboss.jar/AuthenticatorAction" /> 25.

net/projects/jboss/files/JBoss%20Tattletale/. Tattletale 1. Unzip the file into the directory of your choice. Uncomment scan and reports in the properties file.xml file.1 Use Tattletale to find application dependencies Due to the modular class loading changes. jbossas7 4.2.0.23. java6. Download Tattletale version 1. Tattletale's "jbossas7" report can be used to to automatically identify and specify dependent module names in your application's jboss-deployment-structure.0.Beta2 or later contains additional support to help with the new JBoss Modules class loading used in WildFly. 3. see details at the Spring applications development and migration guide. ee6. JBoss Community Documentation Page 308 of 617 .WildFly 8 25. Install Tattletale 1.23 Tools That Can Assist with Migration 25. you might run into ClassNotFoundExceptions or ClassCastExceptions when you migrate your application. Modify the TATTLETALE_HOME/jboss-tattletale.22 Migrating Spring applications For information on how to migrate Spring applications.2. profiles=java5. you will need to find the JARs that contain the classes specified by the exceptions. To resolve these dependencies. 2.Beta2 or newer from http://sourceforge. Tattletale is an excellent tool that recursively scans your application and provides detailed reports about its contents. 25.properties file by adding jbossas7 to the "profiles" property.

0. Click on the ARCHIVE_NAME link to view details about the archive. manifest information. 1. 25.html file and click on "JBoss A7" under the "Reports" section.2.ear output-results/ 2. The IronJacamar 1.2 IronJacamar Datasource and Resource Adapter Migration Tool Summary In previous versions of the application server.1 distribution contains a migration tool that can be used to convert the datasource and resource adapter configuration files from previous releases into the configuration format expected by the WildFly server.Beta1/tattletale. The column on the left lists the archives used by the application. The jboss-deployment-structure. Tattletale will only find dependencies on the application classes.jar applications/jboss-seam-booking. then creates and writes an XML snippet in the appropriate format that can be copied and pasted under the correct subsystem in the server configuration file. you will need to look at the "Depends On" report. To identify external dependencies. such as its location. It will not find dependencies that may be required by classes your application calls or by classes in other JARs included under your application's WEB-INF/lib directory. datasources and resource adapters were configured and deployed using a file with a suffix of *-ds.xml link in the column on the right shows how to specify the module dependency for the archive in the left column. and classes it contains. The tool parses the source configuration file from the previous release. In a browser.WildFly 8 Create and review the Tattletale report 1.xml. Click on this link to see how to define the deployment dependency module information for this archive. JBoss Community Documentation Page 309 of 617 . 2.23. Create the Tattletale report by issuing the command: java -jar TATTLETALE_HOME/tattletale. open the OUTPUT_DIRECTORY/index.jar APPLICATION_ARCHIVE OUTPUT_DIRECTORY For example: java -jar ~/tattletale-1.

1. The tool generates the datasources and datasource element.x: JBoss Community Documentation Page 310 of 617 . we will need to make a few changes to the resulting XML. Please. you need to copy the XML snippet into the standalone/configuration/standalone.1 from here: http://www.bat The tool will do a best effort to convert all old attributes and elements to the new format./converter. you need to copy the XML snippet into the domain/configuration/domain. Download IronJacamar 1. For Linux. 2. Windows batch file: IRONJACAMAR_HOME/doc/as/converter. If you have existing datasources.jboss.sh 2. Use the IronJacamar Migration Tool to convert a datasource configuration file. If you are running in standalone mode. Copy the XML snippet from the target file into the server configuration file under the subsystem xmlns="urn:jboss:domain:datasources:1. type: converter -ds FULLY_QUALIFIED_SOURCE_FILE_NAME FULLY_QUALIFIED_TARGET_FILE_NAME 3. 3. consult this documentation for additional information. 2. Linux script: IRONJACAMAR_HOME/doc/as/converter. It will be necessary to make additional changes to the generated file. you need only copy the datasource element into the configuration file. Open a terminal or command prompt and CD to the IRONJACAMAR_HOME/docs/as/ directory.org/ironjacamar/downloads/ . The converter script can be found in the IRONJACAMAR distribution in the following locations: 1. Here is an example of the datasource configuration file for the Seam Booking example that shipped with EAP 5. 1.sh -ds FULLY_QUALIFIED_SOURCE_FILE_NAME FULLY_QUALIFIED_TARGET_FILE_NAME For Windows. Unzip the file into a directory of your choice. 2. In the following examples.0" datasources element.xml file. run the converter script by typing the following command in the terminal: . If you are running in domain mode.WildFly 8 Download and install IronJacamar 1.xml file.

hsqldb. Here is the converted XML with the driver-class and drivers modifications as configured in the WildFly configuration file: <subsystem xmlns="urn:jboss:domain:datasources:1. -<driver-class>org.jdbcx.h2database.</connection-url> <!-.WildFly 8 <?xml version="1.h2"> <xa-datasource-class>org.0"> <datasources> <datasource enabled="true" jndi-name="java:jboss/datasources/bookingDatasource" jta="true" pool-name="bookingDatasource" use-ccm="true" use-java-context="true"> <connection-url>jdbc:hsqldb:. The preferred way to define the driver class is using a drivers element.We commented out the following driver-class element since it is not the preferred way to define this. --> <drivers> <driver name="h2" module="com.hsqldb.</connection-url> <driver-class>org.jdbcDriver</driver-class>--> <transaction-isolation>TRANSACTION_NONE</transaction-isolation> <pool> <prefill>false</prefill> <use-strict-min>false</use-strict-min> <flush-strategy>FailingConnectionOnly</flush-strategy> </pool> <security> <user-name>sa</user-name> <password/> </security> <validation> <validate-on-match>false</validate-on-match> <background-validation>false</background-validation> <use-fast-fail>false</use-fast-fail> </validation> <timeout/> <statement> <track-statements>false</track-statements> </statement> </datasource> <!-.0" encoding="UTF-8"?> <datasources> <local-tx-datasource> <jndi-name>bookingDatasource</jndi-name> <connection-url>jdbc:hsqldb:. We added this manually.JdbcDataSource</xa-datasource-class> </driver> </drivers> </datasources> </subsystem> JBoss Community Documentation Page 311 of 617 .jdbcDriver</driver-class> <user-name>sa</user-name> <password></password> </local-tx-datasource> </datasources> The generated file will contain a driver-class element.h2.The following drivers element was not in the generated XML snippet.

If you are running in standalone mode.xml file. you need to copy the XML snippet into the standalone/configuration/standalone.xml resource-adapter configuration file from the EAP-5. The tool generates the resource-adapters and resource-adapter element. Copy the XML snippet from the target file into the server configuration file under the subsystem xmlns="urn:jboss:domain:resource-adapters:1.0" element. Here is an example of the mttestadapter-ds.sh -ra FULLY_QUALIFIED_SOURCE_FILE_NAME FULLY_QUALIFIED_TARGET_FILE_NAME For Windows.WildFly 8 Use the IronJacamar Migration Tool to convert a resource adapter configuration file. you need to copy only the resource-adapter element into the configuration file. 2. 1. If you have existing resource-adapters.sh -ra FULLY_QUALIFIED_SOURCE_FILE_NAME FULLY_QUALIFIED_TARGET_FILE_NAME 3.x TestSuite.xml file. type: . For Linux. Open a terminal or command prompt and CD to the IRONJACAMAR_HOME/docs/as/ directory. 1. you need to copy the XML snippet into the domain/configuration/domain.: JBoss Community Documentation Page 312 of 617 . 2. If you are running in domain mode./converter./converter. run the converter script by typing the following command in the terminal: .

lang.resource.adapter.Integer">2</config-property> <config-property name="BooleanProperty" type="java.resource.Double">5.rar</rar-name> <connection-definition>javax.jboss. "org.TestManagedConnectionFactory".Boolean">false</config-property> <config-property name="DoubleProperty" type="java.lang.ConnectionFactory</connection-definition> <config-property name="IntegerProperty" type="java.test.cci.jboss.lang.5</config-property> <config-property name="UrlProperty" type="java.org</config-property> <config-property name="sleepInStart" type="long">200</config-property> <config-property name="sleepInStop" type="long">200</config-property> </tx-connection-factory> </connection-factories> You will need to replace the class-name attribute "FIXME_MCF_CLASS_NAME" in the generated XML snippet with the class name of the managed connection factory. in this case.rar</rar-name> <connection-definition>javax.cci.net.resource.Boolean">false</config-property> <config-property name="DoubleProperty" type="java.net.jboss.jca.URL">http://www.lang.Build jmx-api (build/build.org</config-property> <config-property name="sleepInStart" type="long">200</config-property> <config-property name="sleepInStop" type="long">200</config-property> </tx-connection-factory> <tx-connection-factory> <jndi-name>JBossTestCFByTx</jndi-name> <xa-transaction/> <track-connection-by-tx>true</track-connection-by-tx> <rar-name>jbosstestadapter.rar</rar-name> <connection-definition>javax.==================================================================== --> <connection-factories> <tx-connection-factory> <jndi-name>JBossTestCF</jndi-name> <xa-transaction/> <rar-name>jbosstestadapter.jboss.URL">http://www.WildFly 8 <?xml version="1.0" encoding="UTF-8"?> <!-.5</config-property> <config-property name="UrlProperty" type="java.net.lang.==================================================================== --> <!-.lang.org</config-property> <config-property name="sleepInStart" type="long">200</config-property> <config-property name="sleepInStop" type="long">200</config-property> </tx-connection-factory> <tx-connection-factory> <jndi-name>JBossTestCF2</jndi-name> <xa-transaction/> <rar-name>jbosstestadapter.Double">5.cci.5</config-property> <config-property name="UrlProperty" type="java.Integer">2</config-property> <config-property name="BooleanProperty" type="java.URL">http://www.Double">5.lang.sh all) and view for config documentation --> <!-.lang. Here is the server configuration file with the newly generated and edited configuration data: JBoss Community Documentation Page 313 of 617 .ConnectionManager setup for jboss test adapter --> <!-.ConnectionFactory</connection-definition> <config-property name="IntegerProperty" type="java.Boolean">false</config-property> <config-property name="DoubleProperty" type="java.Integer">2</config-property> <config-property name="BooleanProperty" type="java.lang.ConnectionFactory</connection-definition> <config-property name="IntegerProperty" type="java.

test.rar</archive> <transaction-support>XATransaction</transaction-support> <connection-definitions> <!-.TestManagedConnectionFactory" enabled="true" jndi-name="java:jboss/JBossTestCF2" pool-name="JBossTestCF2" use-ccm="true" use-java-context="true"> <config-property name="IntegerProperty">2</config-property> <config-property name="sleepInStart">200</config-property> <config-property name="sleepInStop">200</config-property> <config-property name="BooleanProperty">false</config-property> <config-property name="UrlProperty">http://www.adapter.5</config-property> <pool> <prefill>false</prefill> JBoss Community Documentation Page 314 of 617 .rar</archive> <transaction-support>XATransaction</transaction-support> <connection-definitions> <!-.adapter.TestManagedConnectionFactory" enabled="true" jndi-name="java:jboss/JBossTestCF" pool-name="JBossTestCF" use-ccm="true" use-java-context="true"> <config-property name="IntegerProperty">2</config-property> <config-property name="sleepInStart">200</config-property> <config-property name="sleepInStop">200</config-property> <config-property name="BooleanProperty">false</config-property> <config-property name="UrlProperty">http://www.jboss.jboss.0"> <resource-adapters> <resource-adapter> <archive>jbosstestadapter.jca.jca.WildFly 8 <subsystem xmlns="urn:jboss:domain:resource-adapters:1.jboss.jboss.test.org</config-property> <config-property name="DoubleProperty">5.org</config-property> <config-property name="DoubleProperty">5.We replaced the following "FIXME_MCF_CLASS_NAME" class-name value with the correct class name <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true" jndi-name="java:jboss/JBossTestCF" pool-name="JBossTestCF" use-ccm="true" use-java-context="true"> --> <connection-definition class-name="org.We replaced the following "FIXME_MCF_CLASS_NAME" class-name value with the correct class name <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true" jndi-name="java:jboss/JBossTestCF2" pool-name="JBossTestCF2" use-ccm="true" use-java-context="true"> --> <connection-definition class-name="org.5</config-property> <pool> <prefill>false</prefill> <use-strict-min>false</use-strict-min> <flush-strategy>FailingConnectionOnly</flush-strategy> </pool> <security> <application/> </security> <timeout/> <validation> <background-validation>false</background-validation> <use-fast-fail>false</use-fast-fail> </validation> </connection-definition> </connection-definitions> </resource-adapter> <resource-adapter> <archive>jbosstestadapter.

go to IronJacamar Migration Tool .jca. JBoss Community Documentation Page 315 of 617 .5</config-property> <pool> <prefill>false</prefill> <use-strict-min>false</use-strict-min> <flush-strategy>FailingConnectionOnly</flush-strategy> </pool> <security> <application/> </security> <timeout/> <validation> <background-validation>false</background-validation> <use-fast-fail>false</use-fast-fail> </validation> </connection-definition> </connection-definitions> </resource-adapter> </resource-adapters></subsystem> For more information about this migration tool.jboss.We replaced the following "FIXME_MCF_CLASS_NAME" class-name value with the correct class name <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true" jndi-name="java:jboss/JBossTestCFByTx" pool-name="JBossTestCFByTx" use-ccm="true" use-java-context="true"> --> <connection-definition class-name="org.jboss.adapter.test.WildFly 8 <use-strict-min>false</use-strict-min> <flush-strategy>FailingConnectionOnly</flush-strategy> </pool> <security> <application/> </security> <timeout/> <validation> <background-validation>false</background-validation> <use-fast-fail>false</use-fast-fail> </validation> </connection-definition> </connection-definitions> </resource-adapter> <resource-adapter> <archive>jbosstestadapter.rar</archive> <transaction-support>XATransaction</transaction-support> <connection-definitions> <!-.TestManagedConnectionFactory" enabled="true" jndi-name="java:jboss/JBossTestCFByTx" pool-name="JBossTestCFByTx" use-ccm="true" use-java-context="true"> <config-property name="IntegerProperty">2</config-property> <config-property name="sleepInStart">200</config-property> <config-property name="sleepInStop">200</config-property> <config-property name="BooleanProperty">false</config-property> <config-property name="UrlProperty">http://www.org</config-property> <config-property name="DoubleProperty">5.

The following is a rough outline of topics to addressed.WildFly 8 26 How do I migrate my application to WildFly from other application servers 26. Introduction About this Guide Introduction to the JBoss AS 7 Server Java Enterprise Edition 6 Overview Overview of Java EE 6 Profiles Java Enterprise Edition 6 Web Profile Java Enterprise Edition 6 Full Profile JBoss AS 7 Architectural Overview Review What's New and Different in JBoss AS 7 Modules and Modular Class Loading Directory Structure of JBoss AS 7 Deployment Administration Tools JBoss Community Documentation Page 316 of 617 . You do not need to follow the template below. This is a work in progress.2 How do I migrate my application from WebLogic to WildFly The purpose of this guide is to document the application changes that are needed to successfully run and deploy WebLogic applications on AS 7.1 Choose from the list below: How do I migrate my application from WebLogic to WildFly How do I migrate my application from WebSphere to WildFly 26. Feel free to add content in any way you prefer.

xml weblogic-ejb-jar.xml Elements to the JBoss Enterprise Application Platform Equivalent Migrate weblogic.xml Elements to the jboss-ejb3.xml Security Replace WebLogic Oracle Wallets WebLogic Certicom-based SSL Implementation WebLogic Security versus JBoss JAAS Security APIs Understand Differences Between WebLogic and JBoss Implementations Overview of JNDI Differences Migrate WebLogic JNDI Lookups to Use Portable JNDI Syntax Replace WebLogic JNDI Lookup Code Portable JNDI Naming Syntax Portable JNDI Naming Syntax Rules Programmatic Login WebLogic Transaction Manager JEE Transaction Manager WebLogic JMX Lookups versus JBoss JMX Lookups Class Loading and Application Packaging Archive Packaging and Assembly Rules Debug and Resolve ClassCastExceptions and ClassNotFoundExceptions Hibernate and JPA Migrate Your Application From Hibernate 3 to Hibernate 4 Configure Your Application to Use the Hibernate 3 Libraries JBoss Community Documentation Page 317 of 617 .xml Descriptor File Configurations Replace the WebLogic plan.xml Descriptor Map Additional weblogic-ejb-jar.WildFly 8 Prepare for Migration Become Familiar with Java EE 6 Become Familiar with JBoss AS 7 Identify the current hardware and operating systems Examine the existing WebLogic application server and platform Examine and understand the existing WebLogic application Review monitoring and administration procedures and tools Review resources available for the migration process Prepare a migration plan Execute the plan Server Configuration and Deployment Descriptor Files WebLogic and JBoss Server Configuration File WebLogic Server Configuration and Deployment Descriptor Files JBoss AS 7 Configuration File Migrate the Server Configuration Map Configuration Files and Descriptors to the JBoss Equivalent Replace the weblogic-ejb-jar.xml Descriptor File Configurations Migrate weblogic-application.xml Deployment Descriptor Map weblogic-ejb-jar.xml *-jms.xml Deployment Descriptor Configuration Use Property Substitution to Specify the Target Deployment Environment WebService.

Failover. Caching Third-party Libraries External Systems WebLogic Proprietary Libraries and APIs Examine the Current Build Process Analyze and Understand the Application Code Services and Components Proprietary WebLogic Features or Libraries Packaging and Deployment Deployment Descriptors and Plans Evaluate the WebLogic Development Tools Eclipse and Plugins NetBeans ADF Data Migration Determine Need for JBoss Modules Configure the Environment for the Migrated Applications Install JBoss Verify the Installation Using the Helloworld Quickstart Migrate the Application Execute the Migration Plan Test Move to Production Tools and Tips Debugging Automated Tools FAQs Consulting Service JBoss Community Documentation Page 318 of 617 .WildFly 8 Replace WebLogic Proprietary Features WebLogic CommonJ Framework or WebLogic Work Manager API Replace WebLogic Virtual Directories Split Directories Replace WebLogic ApplicationLifecycleListener Code Replace Application Start and Stop Events WebLogic Proprietary Annotations Replace the Proprietary WebLogic @WLServlet Annotation Replace the Proprietary WebLogic @WLFilter Annotation Replace the Proprietary WebLogic @WLInitParam Annotation WebLogic Specific Oracle Datasources Evaluate the WebLogic Application Examine the High-level Architecture of the Application JVM Version Frameworks IDE (Eclipse Plugins) Database LDAP Requirements for High-Availablity. Clusting.

and scalable Java EE applications quickly. Red Hat Consulting and Red Hat partners offer a wide variety of workshops. Introduction to the JBoss AS 7 Server JBoss AS 7 is a fast. training. powerful. or ESB frameworks. The Management Console and Management Command Line Interface remove the need to edit XML configuration files by hand. and service offerings designed to help customers migrate more complex applications. secure. EE 6 Web Profile includes a subset of APIs which are useful to web developers. Oracle WebLogic applications that adhere to the Java EE 6 specification should require minimal changes to run on JBoss AS 7. EE 6 Full Profile includes all APIs and specifications included in the EE 6 specification. powerful middleware platform built upon open standards. see Getting Started with JBoss Application Server 7 . it includes APIs and development frameworks that can be used to develop secure.WildFly 8 26. rules engines. The new modular structure allows for services to be enabled only when required. and other technologies to create a stable and scalable platform. workflow systems. For more information about JBoss AS 7.1 Introduction About this Guide The purpose of this document is to guide you through the planning process and migration of fairly simple and standard Oracle WebLogic applications to JBoss AS 7. distributed caching. adding the ability to script and automate tasks. powerful messaging. significantly increasing start up speed. and compliant with the Java Enterprise Edition 6 specification. This document will not cover migration of advanced features such as portal. or subsets of APIs. JBoss AS 7 is a certified implementation of the Java Enterprise Edition 6 Full Profile and Web Profile specifications. In addition. It integrates JBoss Application Server 7 with high-availability clustering. Java Enterprise Edition 6 Overview Overview of Java EE 6 Profiles Java Enterprise Edition 6 (EE 6) includes support for multiple profiles.2. The only two profiles that the EE 6 specification defines are the Full Profile and the Web Profile. JBoss AS 7 is a certified implementation of the Java Enterprise Edition 6 Full Profile and Web Profile specifications. JBoss Community Documentation Page 319 of 617 .

0 (JSR 45) Enterprise Application Technologies Contexts and Dependency Injection (CDI) (JSR 299) Dependency Injection for Java (JSR 330) Enterprise JavaBeans 3.2 and Expression Language (EL) 1.0 (JSR 314) Java Standard Tag Library (JSTL) for JSP 1.1 (JSR 250) Java Transaction API (JTA) 1.1 Lite (JSR 318) Java Persistence API 2. Java EE 6 Web Profile Requirements Java Platform.2 JavaServer Faces (JSF) 2. Enterprise Edition 6 Java Web Technologies Servlet 3. It is designed for web application development.0 (JSR 315) JSP 2.WildFly 8 Java Enterprise Edition 6 Web Profile The Web Profile is one of two profiles defined by the Java Enterprise Edition 6 specification.1 (JSR 907) Bean Validation (JSR 303) JBoss Community Documentation Page 320 of 617 .2 Debugging Support for Other Languages 1.0 (JSR 317) Common Annotations for the Java Platform 1.

class loading is based on JBoss Modules.3 (JSR 115) Java EE Application Deployment 1. Applications written for JBoss Enterprise Application Platform 5 must be modified to specify module dependencies and in some cases.1 (not Lite) (JSR 318) Java EE Connector Architecture 1.WildFly 8 Java Enterprise Edition 6 Full Profile The Java Enterprise Edition 6 (EE 6) specification defines a concept of profiles. and defines two of them as part of the specification.3 (JSR 67) Java API for XML Registries (JAXR) 1. Besides the items supported in the Java Enterprise Edition 6 Web Profile. Items Included in the EE 6 Full Profile EJB 3. the class loading architecture was hierarchical. JBoss Community Documentation Page 321 of 617 . hides server implementation classes.0 (JSR 93) Management and Security Technologies Java Authentication Service Provider Interface for Containers 1. For more information. This offers true application isolation. Module based class loading In previous releases of JBoss AS. the Full Profile supports the following APIs. JBoss AS 7 supports the Full Profile. Review What's New and Different in JBoss AS 7 The following is a list of notable differences in JBoss AS 7 from the previous release. install. For complete information on how to download. and Development Guide located on the Customer Portal .4 (JSR 919) Web Service Technologies Jax-RS RESTful Web Services 1.1 (JSR 311) Implementing Enterprise Web Services 1.2 (JSR 88) J2EE Management 1. Administration and Configuration Guide. configure. Class loading is concurrent for better performance. and develop applications. In JBoss AS 7. and only loads the classes your application needs.3 (JSR 109) JAX-WS Java API for XML-Based Web Services 2.6 (JSR 322) Java Message Service (JMS) API 1. refer to Class Loading and Modules in the Development Guide for JBoss Enterprise Application Platform 6 on the Customer Portal . repackage archives. refer to the Installation Guide.2 (JSR 224) Java Architecture for XML Binding (JAXB) 2.1 (JSR 77) JBoss AS 7 Architectural Overview The following sections highlight some basic information about JBoss Enterprise Application Platform 6.0 (JSR 196) Java Authentication Contract for Containers 1.1 (JSR 914) JavaMail 1.2 (JSR 222) Web Services Metadata for the Java Platform (JSR 181) Java APIs for XML-based RPC 1.1 (JSR 101) Java APIs for XML Messaging 1.

refer to About Managed Domains in the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 on the Customer Portal . The Linux script JBOSS_HOME/bin/domain. While this should not impact applications built for previous releases. For servers running in a managed domain. Configuration files for standalone servers are now located in the JBOSS_HOME/standalone/configuration/ directory and deployments are located in the JBOSS_HOME/standalone/deployments/ directory. These profiles were located in the JBOSS_HOME/server/ directory. Ordering of deployments JBoss AS 7 uses fast. the server is configured using the JBOSS_HOME/domain/configuration/domain.xml file. For servers running in a managed domain.xml file.bat is used to start a managed domain. In JBoss Enterprise Application Platform 6. database. resource adapter. A standalone server is configured using the JBOSS_HOME/standalone/configuration/standalone. you can configure entire groups of servers at once.bat was used to start the server. the application server is able to automatically determine dependencies in advance and choose the most efficient deployment strategy. In JBoss Enterprise Application Platform 5. In a managed domain.sh or Windows script JBOSS_HOME/bin/run. the Linux script JBOSS_HOME/bin/run. The information contained in the multiple JBoss Enterprise Application Platform 5 configuration files must be migrated to the new single configuration file. In JBoss Enterprise Application Platform 6.WildFly 8 Domain Management In JBoss AS 7. In most cases. JBoss Community Documentation Page 322 of 617 . the server start script is dependent on how you run your server. The Linux script JBOSS_HOME/bin/standalone. so there is no JBOSS_HOME/server/ directory. This file is used to configure all the services and subsystems used for the deployment. configuration files can be found in the JBOSS_HOME/domain/configuration/ directory and deployments can be found in the JBOSS_HOME/domain/deployments/ directory. Directory Structure and Scripts As previously mentioned.sh or Windows script JBOSS_HOME/bin/domain. the server can be run as a standalone server or in a managed domain.sh or Windows script JBOSS_HOME/bin/standalone. keeping configurations synchronized across your entire network of servers. deployment configuration is done using one file. However.bat is used to start a standalone server. For more information. JBoss Enterprise Application Platform 5 applications that consist of multiple modules deployed as EARs and use legacy JNDI lookups instead of CDI injection or resource-ref entries may require configuration changes. concurrent initialization for deployment resulting in improved performance and efficiency. Applications often contained multiple configuration files for security. Domain mode is not supported in the following JBoss Enterprise products: JBoss Portal Platform 6 Deployment Configuration Standalone Servers and Managed Domains JBoss AS 7 used profile based deployment configuration. and other configurations. JBoss AS 7 no longer uses profile based deployment configuration. this can simplify management of deployments to multiple servers.

For more information on modular class loading. a module containing these libraries can be created and installed by the JBoss administrator. Creating custom static modules can be useful if many applications are deployed on the same server that use the same third party libraries. All the application server provided APIs are provided as static modules. Because deployments are loaded as modules.15. Modules and Modular Class Loading Class loading in AS 7 is based on the JBoss Modules project. Modules are only loaded when required. they can configure dependencies and be used as dependencies by other deployments.1. com.0" name="com. sometimes called static and dynamic modules. see Class Loading in AS7 . The name of the module is defined in the module.api"/> </dependencies> </module> The module name. including the Java EE APIs as well as other APIs such as JBoss Logging.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.api"/> <module name="javax. This usually only occurs when an application is deployed that has explicit or implicit dependencies. <?xml version="1.xml). Modules A Module is a logical grouping of classes used for class loading and dependency management. Instead of bundling those libraries with each application. or subdeployment in an EAR. The applications can then declare an explicit dependency on the custom static modules. Each sub-directory represents one module and contains one or more JAR files and a configuration file (module. Applications that use other types of JNDI lookups must be changed to follow the new standardized JNDI namespace convention. JBoss Community Documentation Page 323 of 617 .mysql"> <resources> <resource-root path="mysql-connector-java-5. h6.xml file.xml file. should match the directory structure for the module.WildFly 8 JNDI Lookups JBoss AS 7 now uses standardized portable JNDI namespaces. For more information about JNDI naming syntax. All modules provide the same features. However the only difference between the two is how they are packaged. Dynamic Modules Dynamic Modules are created and loaded by the application server for each JAR or WAR deployment. Static Modules Static Modules are predefined in the JBOSS_HOME/modules/ directory of the application server.transaction. JBoss AS 7 identifies two different types of modules. The following is an example module. see the section below on “Portable JNDI Naming Syntax”.mysql. The name of a dynamic module is derived from the name of the deployed archive.jar"/> </resources> <dependencies> <module name="javax.

JBoss Community Documentation Page 324 of 617 . Any subdeployment can be configured with explicit dependencies on another subdeployment as would be done for any other module. Subdeployment class loader isolation can be enabled if strict compatibility is required. Directory Structure of JBoss AS 7 JBoss AS 7 includes a simplified directory structure.MF file of each subdeployment. Each WAR and EJB JAR subdeployment is a module. They are loaded as multiple unique modules.WildFly 8 Modules and Class Loading in Enterprise Archives Enterprise Archives (EAR) are not loaded as a single module like JAR or WAR deployments. The contents of the lib/ directory in the root of the EAR archive is a module. This can be enabled for a single EAR deployment or for all EAR deployments. EJB JAR subdeployments have implicit dependencies on the parent module and any other EJB JAR subdeployments. compared to previous versions. The Java EE 6 specification recommends that portable applications should not rely on subdeployments being able to access each other unless dependencies are explicitly declared as Class-Path entries in the MANIFEST. The implicit dependencies described above occur because JBoss AS 7 has subdeployment class loader isolation disabled by default. These modules have the same behavior as any other module with the following additional implicit dependencies: WAR subdeployments have implicit dependencies on the parent module and any EJB JAR subdeployments. This is called the parent module. It also includes directory structures of the standalone/ and domain/ folders. The following rules determine what modules exist in an EAR. No subdeployment ever gains an implicit dependency on a WAR subdeployment. The following table contains a listing of the directories and a description of what each directory contains.

Services are deployed using the Management Console and Management CLI. data/ Information about deployed services. log/ Contains the run-time log files for the host and process controllers which run on the local instance. do not place files in this directory manually. servers/ Contains the equivalent data/. jboss-modules. and tmp/ directories for each server instance in a domain. and examples. welcome-content/ Contains content used by the Welcome web application which is available on port 8080 of a default installation. These files are modified by the Management Console and Management CLI. standalone/ Configuration files.WildFly 8 level Directories Name Purpose appclient/ Contains configuration details for the application client container. deployment content. Directories within the domain/ directory Name Purpose configuration/ Configuration files for the managed domain. bin/ Contains start-up scripts for JBoss EAP 6 on Red Hat Enterprise Linux and Microsoft Windows. deployment content. Therefore. which contain similar data to the same directories within the top-level domain/ directory. | tmp/ Contains temporary data such as files pertaining to the shared-key mechanism used by the Management CLI to authenticate local users to the managed domain. and are not meant to be edited directly. docs/ License files. rather than by a deployment scanner. domain/ Configuration files. and writable areas used when JBoss EAP 6 runs as a standalone server. modules/ Modules which are dynamically loaded by JBoss EAP 6 when services request them. schemas. bundles/ Contains OSGi bundles which pertain to JBoss EAP 6 internal functionality. JBoss Community Documentation Page 325 of 617 . and writable areas used when JBoss EAP 6 runs as a managed domain. log/.jar The bootstrapping mechanism which loads modules.

and are not meant to be edited directly. 26. with live notifications when any changes require the server instance to be restarted or reloaded. These files are modified by the Management Console and Management CLI. JON TODO: section is not complete. JBoss Community Documentation Page 326 of 617 . In a Managed Domain. lib/ External libraries which pertain to a standalone server mode. The Management Console also has the ability to perform administrative tasks.2. The standalone server does include a deployment scanner. the recommended approach is to manage deployments using the Management Console or Management CLI. tmp/ Contains temporary data such as files pertaining to the shared-key mechanism used by the Management CLI to authenticate local users to the server.2 Prepare for Migration Before you attempt to migrate your WebLogic application to JBoss AS 7. However. Deployment TODO: section is not complete. and make persistent modifications to the server configuration. Administration Tools Management Console The Management Console is a web-based administration tool used to to start and stop servers. it helps to have an understanding of the process. server instances and server groups in the same domain can be centrally managed from the Management Console of the domain controller. Empty by default. so you can place archives in this directory to be deployed. JBoss CLI The Management Command Line Interface (CLI) is a command line administration tool that can perform operations in batch modes.WildFly 8 Directories within the standalone/ directory Name Purpose configuration/ Configuration files for the standalone server. allowing multiple tasks to be run as a group. tune system settings. deploy and undeploy applications. deployments/ Information about deployed services.

You can find Java Enterprise Edition 6 documentation here: http://www. so understanding Java EE 6 is a great place to start. including the operating systems. features and components. functions. JBoss Community Documentation Page 327 of 617 . disk usage and capacity. Prepare a migration plan Develop a migration plan including a detailed roadmap and resources that will be needed. software. and determine the equivalent capabilities in JBoss AS 7. note the proprietary APIs and features and determine the JBoss or Java EE 6 equivalents. lightweight. Identify the current hardware and operating systems This includes the operating systems and versions. Assess the skills of the development team that will be doing the work and plan for training or additional consulting help.com/support/configurations/jboss/. Review resources available for the migration process Resources include people. Examine the existing WebLogic application server and platform Examine the existing application server and platform.WildFly 8 Become Familiar with Java EE 6 JBoss AS 7 is a fast. JVMs. Be totally familiar with its architecture. and hardware. databases. Also be aware that additional hardware and other resources will be required during the migration process until the effort is completed. number of processors. Examine and understand the existing WebLogic application Thoroughly examine the existing WebLogic application.oracle. memory capacity.html and a Java EE 6 tutorial here: http://docs. powerful implementation of the Java Enterprise Edition 6 specification. and web servers.com/technetwork/java/javaee/tech/index.com/javaee/6/tutorial/doc/.oracle.redhat. The supported JBoss configurations can be found on the Customer Portal at https://access. In particular. Become Familiar with JBoss AS 7 See the Admin Guide and Developer Guide for details on how to configure and develop applications with JBoss AS 7. Review monitoring and administration procedures and tools Perform a review of all monitoring and administration procedures and tools in place to identify any that may need modification or replacement to work with the JBoss AS 7.

and service in the domain.xml file. Migrate the Server Configuration Unfortunately.3 Server Configuration and Deployment Descriptor Files WebLogic and JBoss Server Configuration File WebLogic Server Configuration and Deployment Descriptor Files Configuration of the WebLogic Server is centralized in the WEBLOGIC_HOME/domains/DOMAIN_NAME/config/config. the server is configured using the JBOSS_HOME/domain/configuration/domain. You can use the Management Console or Management Command Line Interface (CLI) to configure the server and the changes will be reflected in the server configuration file. Use the Admin Guide to find information about how to perform the same configuration in JBoss. the server can be run as a standalone server or in a managed domain.xml files. In most cases you will not edit these files directly. In most cases you use the Administration Console or one of the other WebLogic tools to modify the domain's configuration and the changes are then reflected in the configuration files. For servers running in a managed domain. JBoss Community Documentation Page 328 of 617 . The best approach is to open the WebLogic configuration file and examine each section.xml file. cluster.WildFly 8 Execute the plan Implement the strategic migration plan and employ implementation support strategies. A standalone server is configured using the JBOSS_HOME/standalone/configuration/standalone. You can find more information about the Management CLI here: CLI Recipes. resource. 26. JBoss AS 7 Configuration File In JBoss AS 7.2. It contains the configuration parameter settings for each server instance.xml and JBOSS_HOME/domain/configuration/host. server configuration is a complex process and there is not an easy mapping from one application server to another.

xml support value-added features that are not included in the standard specifications. *-jdbc.xml or domain. JBoss Community Documentation Page 329 of 617 . this or domain.xml.xml JDBC datasource descriptor file. Replace the weblogic-ejb-jar. In JBoss. jboss-ejb3.xml standalone. Many of these elements map to the jboss-ejb3.xml information is specified in the datasources subsystem of the JBoss configuration file. weblogic-cmp-rdbms-jar.xml standalone. elements that are unique to WebLogic Server.xml file. Deployment descriptor file describes the EJB weblogic-ejb-jar.xml. however. The equivalent file in JBoss AS 7 is the jboss-ejb3.xml file in The equivalent file in JBoss Enterprise Application Platform 6.xml deployment descriptor file describes elements that are specific to the WebLogic Server.xml weblogic.xml. map to other descriptor files.xml. Some elements.WildFly 8 Map Configuration Files and Descriptors to the JBoss Equivalent WebLogic configuration files are fairly complex and it can be difficult to map them to JBoss equivalents. but the following table can be used as a guideline: WebLogic File AS 7 Equivalent Description of the File ejb-jar. or standalone.xml Deployment Descriptor The WebLogic weblogic-ejb-jar.xml Deployment descriptor for web applications to or domain.

For JBoss descriptor elements. replace the variable JBOSS_PREFIX with the following file path prefix depending on the bean type: Entity Bean: /ejb-jar/enterprise-beans/entity Session Bean: /ejb-jar/enterprise-beans/session Message-Driven Bean: /ejb-jar/enterprise-beans/message-driven JBoss Community Documentation Page 330 of 617 .xml Descriptor The following table maps the WebLogic XPath elements to the corresponding JBoss XPath elements for various types of beans.xml XPath Element WEBLOGIC_PREFIX/ejb-name JBOSS_PREFIX/ejb-name WEBLOGIC_PREFIX/resource-description/res-ref-name JBOSS_PREFIX/resource-ref/res-ref-name WEBLOGIC_PREFIX/resource-env-description/res-env-ref-name JBOSS_PREFIX/resource-env-ref/resource-env-re WEBLOGIC_PREFIX/ejb-reference-description/ejb-ref-name JBOSS_PREFIX/ejb-ref/ejb-ref-name WEBLOGIC_PREFIX/service-reference-description/service-ref-name JBOSS_PREFIX/service-ref/service-ref-name WEBLOGIC_PREFIX/service-reference-description/wsdl-file JBOSS_PREFIX/service-ref/wsdl-file For readability.xml XPath Element JBoss jboss-ejb3.xml Elements to the jboss-ejb3. For WebLogic descriptor elements. replace the variable WEBLOGIC_PREFIX with the following path prefix: /weblogic-ejb-jar/weblogic-enterprise-bean for all bean types. the variables WEBLOGIC_PREFIX and JBOSS_PREFIX were used in place of paths in the table.WildFly 8 Map weblogic-ejb-jar. WebLogic weblogic-ejb-jar.

. For more information on how to configure the JBoss server. In JBoss Enterprise Application Platform 6.com/site/documentation/JBoss_Enterprise_Application_Platform/.. many of these features may be configured in the application deployment or JBoss server configuration files. you can achieve the same behavior by specifying the <sync-on-commit-only> in the jbosscmp-jdbc. While there is no direct mapping of these descriptor elements.redhat. The table that follows uses this weblogic.xml deployment descriptor file is used to support value-added features that are not included in the standard specifications for web applications.. which defaults to True. it is available as a patch.xml file. is used for performance reasons to delay updates to the persistent store of all beans until the end of the transaction. updates are sent to the database after each method invocation. delay-updates-until-end-of-tx This element in the webLogic-ejb-jar.1. refer to the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 on https://access. <sync-on-commit-only>true</sync-on-commit-only> <insert-after-ejb-post-create>true</insert-after-ejb-post-create> <call-ejb-store-on-clean>true</call-ejb-store-on-clean> </entity> </jbosscmp-jdbc> This feature is available in JBoss Enterprise Application Platform 6. This allows other processes to access the persisted data while the transaction is waiting to be completed. JBoss Community Documentation Page 331 of 617 . but are not committed until the end of the transaction. <entity> <ejb-name>Student</ejb-name> <create-table>true</create-table> <remove-table>true</remove-table> <table-name>STUDENT</table-name> . The following section provides examples of how to map a few common configurations.xml Descriptor File Configurations he weblogic. For example: <jbosscmp-jdbc> .x.xml file.xml Elements to the JBoss Enterprise Application Platform Equivalent The following list describes how to map addtional elements to the JBoss Enterprise Application Platform Equivalent. When set to False.WildFly 8 Map Additional weblogic-ejb-jar. Migrate weblogic.0..xml file as the example. For JBoss Enterprise Application Platform 6.

WildFly 8 <?xml version="1.xml <context-root>MyAppContextRoot</context-root> JBoss Community Documentation <jboss-web> <context-root>MyAppContextRoot</context-roo </jboss-web> Page 332 of 617 .bea.xml configurations to JBoss weblogic.xml JBoss Equivalent Specify the context root: Add the following to the WEB-INF/jboss-web.//DTD Web Application 7. Inc.0//EN" "http://www.com/servers/wls700/dtd/weblogic700-web-jar.dtd"> <weblogic-web-app> <context-root>MyAppContextRoot</context-root> <security-role-assignment> <role-name>TestRole1</role-name> <principal-name>TestRole1</principal-name> </security-role-assignment> <security-role-assignment> <role-name>TestRole2</role-name> <principal-name>TestRole2</principal-name> </security-role-assignment> <session-descriptor> <session-param> <param-name>TimeoutSecs</param-name> <param-value>3650</param-value> </session-param> </session-descriptor> <container-descriptor> <save-sessions-enabled>true</save-sessions-enabled> <prefer-web-inf-classes>true</prefer-web-inf-classes> </container-descriptor> <jsp-descriptor> <jsp-param> <param-name>keepgenerated</param-name> <param-value>true</param-value> </jsp-param> <jsp-param> <param-name>encoding</param-name> <param-value>ISO8859_1</param-value> </jsp-param> </jsp-descriptor> </weblogic-web-app> The following table maps the some common weblogic.0" encoding="UTF-8"?> <\!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems.

security.WildFly 8 Map roles: <security-role-assignment> <role-name>TestRole1</role-name> <principal-name>TestRole1</principal-name> </security-role-assignment> Use the RoleMappingLoginModule in the server confi <security-domain name="FormBasedAuthWebAppPolic <authentication> \\ <login-module code="org. flag="required"> <module-option name="dsJndiName" va <module-option name="principalsQuer PRINCIPLES where principal_id=?"/> <module-option name="rolesQuery" va ROLES where principal_id=?"/> </login-module> <\!-\. Page 333 of 617 .jboss.jboss. flag="optional"> <module-option name="rolesPropertie value="/home/userone/jboss-eap-6.security.Following is the RoleMappingLogi <login-module code="org.xml: <session-config> <session-timeout>3650</session-timeout>\ </session-config> Since the WAR has its own scoped class loader.xm <jboss-web> <security-domain>java:/jaas/FormBasedAuthWe </jboss-web> Specify Session Timeout: <session-descriptor> <session-param> <param-name>TimeoutSecs</param-name> <param-value>3650</param-value> </session-param> </session-descriptor> Specify class loading precedence: Add the following to the WEB-INF/jboss-web.0-GA/standalon <module-option name="replaceRole" v </login-module> </authentication> </security-domain> Then add the following to the WEB-INF/jboss-web. the WEB-INF/classes directories will always be loaded <container-descriptor> <save-sessions-enabled>true</save-sessions-enabled> <prefer-web-inf-classes>true</prefer-web-inf-classes> </container-descriptor> JBoss Community Documentation known alternative/relative configuration in JBoss.

xml Descriptor File Configurations The weblogic-application. refer to the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 on https://access.xml file and the equivalent in standard Java EE descriptor files. While there is no direct mapping of these descriptor elements.xml deployment descriptor file is used to describe WebLogic EAR archives. The following example shows how to map a few common elements. The table that follows shows an example of elements in a weblogic-application.com/site/documentation/JBoss_Enterprise_Application_Platform/. For more information on how to configure the JBoss server.com"/> </virtual-server> </subsystem> Migrate weblogic-application.1" <virtual-server name="default-host" enable<alias name="localhost"/> <alias name="example.xml <context-param> element: <context-param> <description> Web application default encoding </description> <param-name> webapp.encoding.xml Element JBoss Equivalent <application-param> element: <application-param> <description> Web application default encoding </description> <param-name> webapp. many of these features may be configured in standard Java EE files.default </param-name> <param-value> UTF8 </param-value> </context-param> Page 334 of 617 . WebLogic weblogic-application.default </param-name> <param-value> UTF8 </param-value> </application-param> JBoss Community Documentation Maps to the web.redhat.encoding.WildFly 8 Configure JSPs: Configure JSPs in the web subsystem of the server c <jsp-descriptor> <jsp-param> <param-name>keepgenerated</param-name> <param-value>true</param-value> </jsp-param> <jsp-param> <param-name>encoding</param-name> <param-value>ISO8859_1</param-value> </jsp-param> </jsp-descriptor> <subsystem xmlns="urn:jboss:domain:web:1.1" def native="false"> <configuration> <jsp-configuration development="true" j keep-generated="true"/> </configuration> <connector name="http" protocol="HTTP/1.

development. JBoss Community Documentation Page 335 of 617 . create a <simple> element in the naming subsystem of the server configuration file. Enable Property Substitution in the Server Configuration File The <spec-descriptor-property-replacement> element in the ee subsystem of the server configuration file is used to enable or disable property substitution in the ejb-jar. This topic describes how to change the target deployment environment in JBoss Enterprise Application Platform 6.redhat. you can bind string values into JNDI and them map them into the application.xml.String</resource-env-ref-type> </resource-env-ref> To bind simple strings into JNDI. you pass the new values to the deployment descriptors based on the deployment environment. The following is an example of the naming subsystem element configured for JNDI substitution. This is the default value. The following is an example of the ee subsystem element configured to enable property substitution. quality assurance. The <jboss-descriptor-property-replacement> element in the ee subsystem of the server configuration file is used to enable or disable property substitution in the jboss-ejb3.WildFly 8 Replace the WebLogic plan.xml. for example. To enable property substitution it must be set to true.xml deployment descriptor file provides a way to target the application deployment for a specific environment.xml Deployment Descriptor Configuration The WebLogic plan.xml.com/site/documentation/JBoss_Enterprise_Application_Platform/. integration testing. *-jms.xml file contains the following resource reference: <resource-env-ref> <description>IP address of the destination</description> <resource-env-ref-name>destination/ip-address</resource-env-ref-name> <resource-env-ref-type>java. jboss-app.1"> <spec-descriptor-property-replacement>true</spec-descriptor-property-replacement> <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement> </subsystem> For more information about property substitution. Using this technique.lang. or production. Bind Strings for JNDI Runtime Mapping For values outside deployment descriptors that change depending on the target environment. Assume the application's web. <subsystem xmlns="urn:jboss:domain:ee:1. jboss-web. Use Property Substitution to Specify the Target Deployment Environment 1.xml descriptor files. refer to the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal at https://access. you achieve the same outcome using property substitution.xml descriptor files. In JBoss Enterprise Application Platform 6.xml.xml and persistence. 2. and *-ds.

WebService.xml and the <jndi-name> element must match the <simple> element name in the server configuration file. <jboss-web> <resource-env-ref> <resource-env-ref-name>destination/ip-address</resource-env-ref-name> <jndi-name>java:/my/jndi/key</jndi-name> </resource-env-ref> </jboss-web> Follow the same procedure to implement property substitution for other descriptor files.WildFly 8 <subsystem xmlns="urn:jboss:domain:naming:1.xml WebLogic JMS descriptor file TODO: This section is not complete weblogic-ejb-jar.xml to map the global JNDI entry to the application's java:comp/env/ Environment Naming Context (ENC). The <resource-env-ref-name> element value must match the value specified in the web. refer to the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal at https://access.1"> <bindings> <simple name="java:/my/jndi/key" value="MyJndiValue"/> </bindings> </subsystem> Add an entry to the application's jboss-web.xml WebLogic EJB descriptor JBoss Community Documentation Page 336 of 617 .com/site/documentation/JBoss_Enterprise_Application_Platform/.redhat.xml WebLogic Webservice descriptor files TODO: This section is not complete *-jms. For more information about how to manage the server configuration files.

com/site/documentation/JBoss_Enterprise_Application_Platform/.1.oracle.com/cd/E16340_01/core.3. JSSE is the only SSL implementation that is supported.4 Security Replace WebLogic Oracle Wallets Weblogic administrators use wallets created by Oracle Wallet Manager to manage public key security credentials on application clients and servers. Refer to the Oracle Wallet Manager documentation for details: http://docs. WebLogic Security versus JBoss JAAS Security APIs TODO: This section is not complete.redhat. JBoss Community Documentation Page 337 of 617 . Configure JBoss Enterprise Application Platform 6 to Use the Java KeyStore Java KeyStores are configured in the security subsystem of the server configuration file. WebLogic Certicom-based SSL Implementation Releases prior to WebLogic Server version 11g Release 1 (10.5) defaulted to the Certicom-based SSL (Secure Sockets Layer) implementation. These wallets must first be converted to standard Java KeyStore (JKS) entries that can then be used to configure the credentials in JBoss Enterprise Application Platform 6.xsd file.1111/e10105/walletmgr. The 11g release introduced an SSL implementation based on JSSE (Java Secure Socket Extension) and deprecated the Certicom-based SSL implementation.htm#ASADM10989. JBoss Enterprise Application Platform 6 supports the JSSE implementation. 2. Convert Oracle Wallet to JKS Use the Oracle orapki command-line tool to convert the wallet to standard JKS keystore.2. The schema is defined in the file:///JBOSS_INSTALL_DIRECTORY/docs/schema/jboss-as-config_1_4. For details on how to configure the server to use keystores. refer to Implement SSL Encryption for the JBoss Enterprise Application Platform Web Server in the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal at https://access.com/site/documentation/JBoss_Enterprise_Application_Platform/. For instructions on how to implement SSL in JBoss Enterprise Application Platform 6.redhat.WildFly 8 26. 1. refer to the chapter entitled Securing JBoss Enterprise Application Platform in the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal at https://access. Be sure to replace JBOSS_INSTALL_DIRECTORY in the previous link with the actual path for your install.1. As of WebLogic Server version 12.

you instantiate the InitialContext with no argument and then look up the service using the portable JNDI lookup rules: java:global.class.getSimpleName() ). Migrate WebLogic JNDI Lookups to Use Portable JNDI Syntax Replace WebLogic JNDI Lookup Code In WebLogic. This is an example of what the code would look like in JBoss: Context context = new InitialContext(). Service service = (Service)context. security principal and credentials. "weblogic.jndi. In JBoss. String>(). "t3://localhost:7001" ). context factory.INITIAL_CONTEXT_FACTORY. For more information about portable JNDI naming syntax.SECURITY_PRINCIPAL.put( Context.lookup( "java:app/service/" + ServiceImpl. you create a Hashtable containing environment information such as provider URL. java:module. see the sections below on Portable JNDI Naming Syntax and JNDI Namespace Rules. JBoss Community Documentation Page 338 of 617 .put( Context. java:app. "weblogic" ).5 Understand Differences Between WebLogic and JBoss Implementations Overview of JNDI Differences JBoss Enterprise Application Platform 6 uses standardized portable JNDI namespaces. env.class.Service#" + Service.WLInitialContextFactory" ).put( Context.PROVIDER_URL. Then you lookup the Service using a prefix with the Service class name This is an example of how code may look in WebLogic: Hashtable<String. You pass this table as a parameter when you create the InitialContext. Service service = (Service) context.put( Context. String> env = new Hashtable<String.2. env.lookup( "sample.SECURITY_CREDENTIALS. env. Context context = new InitialContext( env ). "weblogic" ). WebLogic applications must be changed to follow the standardized JNDI namespace convention. env.getName() ).WildFly 8 26.

each with its own scope. Qualified absolute names like java:/jdbc/DefaultDS should be qualified the same way as Unqualified absolute names above.jar/HotelBookingAction java:module Names in this namespace are shared by all components in a module.jboss. Enterprise Edition (Java EE) Specification. Three of the namespaces are used for portable JNDI lookups. You can download the specification from here: http://jcp. module. Unqualified absolute names like /jdbc/DefaultDS should be qualified relative to a java:jboss/root name. Namespaces should follow these rules: 1. For example. a WAR and an EJB jar file in the same EAR file would have access to resources in the java:app namespace.WildFly 8 Portable JNDI Naming Syntax There are four logical namespaces.2. 4.example. The following table details when and how to use each namespace. not only to provide predictable and consistent rules for every name bound in the application server.org/en/jsr/detail?id=316 Portable JNDI Naming Syntax Rules JBoss Enterprise Application Platform 6 has improved upon JNDI namespace names. 2. "Application Component Environment Namespaces" in the "JSR 316: JavaTM Platform. 5. JBoss Community Documentation Page 339 of 617 . global.jar/HotelBookingAction You can find more information about JNDI naming contexts in section EE. Any name starting with java:xxx where xxx does not match any of the above five would result in an invalid name error. java:module/env. or java:jboss/env. app.seam. depending on the context. This means you might run into issues with the current namespaces in your application if they don't follow the new rules. The special java:jboss namespace is shared across the entire AS server instance.5. or the proprietary jboss. for example. Any relative name with a java: prefix must be in one of the five namespaces: comp. all enterprise beans in a single EJB module or all components in a web module. Unqualified relative names like DefaultDS or jdbc/DefaultDS should be qualified relative to java:comp/env. v6". Use names in this namespace to find remote EJBs. 3.2. The following is an example of a java:app namespace: java:app/jboss-seam-booking.booking.HotelBooking java:app Names in this namespace are shared by all components in all modules in a single application. but also to prevent future compatibility issues. The following is an example of a java:module namespace: java:module/HotelBookingAction!org. The following is an example of a java:global namespace: java:global/jboss-seam-booking/jboss-seam-booking. JNDI Description Namespace java:global Names in this namespace are shared by all applications deployed in an application server instance.

annotation. you must replace the WebLogic proprietary code with one of the following: You can add the following annotations to the Servlet class that performs the authentication.xml file with a <security-constraint> element: <login-config> <auth-method>FORM</auth-method> <realm-name>ApplicationRealm</realm-name> <form-login-config> <form-login-page>/login. you can instead add a <security-constraint> element containing a dummy URL pattern to the web.xml file. @WebServlet("/securedUrlPattern") @ServletSecurity(@HttpConstraint(rolesAllowed = { "myRole" })) @DeclareRoles("myRole") public class SecuredServlet extends HttpServlet { //Rest of code } If you prefer not to use the standard servlet.ServletSecurity.HttpConstraint.DeclareRoles.security. In JBoss AS 7. you can use the standard Java EE6 Servlet 3. // Imports for annotations import javax.annotation. import javax.0 HttpServletRequest.annotation. To enable programmatic login.xml file may result in the error message "No authenticator available for programmatic login".jsp</form-login-page> <form-error-page>/loginError.jsp</form-error-page> </form-login-config> </login-config> <security-constraint> <web-resource-collection> <web-resource-name>All resources</web-resource-name> <description>Protects all resources</description> <url-pattern>/dummy/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>myRole</role-name> </auth-constraint> </security-constraint> JBoss Community Documentation Page 340 of 617 .WildFly 8 Programmatic Login WebLogic provides a proprietary ServletAuthentication class to perform programmatic login. Failure to create a <security-constraint> element in the web.servlet.annotation.login() method to perform programmatic login or you can define a <security-constraint> element in the web.WebServlet.xml file. This notifies JBoss to create a default Authenticator. import javax. import javax. The following is an example of a web.servlet.servlet.

getWriter().getParameter( "password" ).getWriter().getWriter().login(userName.getWriter(). } catch(ServletException ex) { // handle the error response. password).println( "<form name=\"FailedLogin\" method=\"post\">" ). String password = request. response.println( "<br/>" ). return.getWriter(). response. } WebLogic Transaction Manager JEE Transaction Manager TODO: This section is not complete WebLogic JMX Lookups versus JBoss JMX Lookups TODO: This section is not complete JBoss Community Documentation Page 341 of 617 .WildFly 8 If the application uses the WebLogic proprietary ServletAuthentication class for programmatic login.println( "Failed to log in " + username + " with the given password<br/>" ).getParameter( "username" ).println( "<input name=\"FailedLogin\" type=\"submit\" value=\"Return\" />" ).println( "</form>" ). try { request. response. you must replace it with the standard HttpServletRequest login as follows: String userName = request. response.

the extension must appear on the extracted directory name. you may see a ClassCastException or a ClassNotFoundException. it is generally better to avoid the use of a web.xml file. Hibernate. For web applications. The JBoss AS 7 installation includes Java EE 6.xml file if possible. Extracted directories may be nested in extracted deployments. The following are general rules for assembly of archives or directories that are deployed to JBoss Enterprise Application Platform 6: Archives may be nested within other archived deployments. for example myEnterpriseApp. In WebLogic. it should be located under the root of the application WEB-INF/ directory. In JBoss.war. that are commonly used by applications. or modules. JBoss Community Documentation Page 342 of 617 . refer to the chapter entitled Class Loading and Modules in the Development Guide for JBoss Enterprise Application Platform 6 on the Customer Portal . If your application needs a version of the classes that is different than the classes located in the JBOSS_HOME/modules/system/layers/base/ directory. or other archive can be deployed without the archive extension in the directory name. You must recreate archives for the nested artifacts. For more information about class loading and modules. This can simplify packaging of archives and eliminate the need to bundle Java EE 6 and other common classes. and other commonly used classes in the server install modules/ directory. an extracted WAR. JBoss Logging. This system provides more flexibility and control than the traditional system of hierarchical class loaders. Archives may be nested in extracted deployments. If your WebLogic application packages a JAR that is also included in the server modules/system/layers/base/ directory. it should be located under the META-INF/ directory in the root of the EAR. If your enterprise application requires an application. JBoss AS ships with a number of classes. you may see a ClassCastException when you deploy or run your application. You can also create custom dynamic modules to make third-party JARs and other resources available to all applications running on the server. Modules are only loaded when a deployment requests them and these JARs or classes should not be bundled within the application archives. or change the packaging structure of your EAR or WAR. A ClassNotFoundException can be a result of missing JARs or a mismatch of API versions. remove JARs. Debug and Resolve ClassCastExceptions and ClassNotFoundExceptions A ClassCastException can occur because a class is being loaded by a different class loader than the class it extends. Extracted directories may NOT be nested in archived deployments. It can also be a result of the same class existing in multiple JARs. as well as other APIs such as JBoss Logging. you may need to modify deployment descriptors. the Java EE APIs. Due to the modular class loading system used by JBoss AS 7. These classes are located in the JBOSS_HOME/modules/system/layers/base/ directory and include all the application server provided APIs.ear or myWebApp. If this file is required.WildFly 8 Class Loading and Application Packaging Archive Packaging and Assembly Rules JBoss Enterprise Application Platform 6 uses a modular classloading system for controlling the class paths of deployed applications. EAR.

Explicitly define the dependency in either the MANIFEST. To resolve this issue: 1.xml file. The following is an example of a jboss-deployment-structure file that defines the module dependency: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.core. JBoss Community Documentation Page 343 of 617 .WildFly 8 Resolve ClassCastExceptions Caused by Duplicate JARs Because JBoss AS 7 ships with a number of classes.api" slot="main" /> </dependencies> </deployment> </jboss-deployment-structure> 3.[/].BundleSupport. Remove the duplicate JAR(s) from the application's packaged WAR or EAR file.apache.jar JARs were packaged in the lib/ folder of the application archive. In this case.[MVCUserInterface]] (http-localhost/127. or modules.0.servlet.2_spec-1.common.standard.fmt.jar and standard.1:8080-2) Servlet.ContainerBase. packaging these common JARs with your application can result in a ClassCastException.web]. that are commonly used by applications.ClassCastException: javax. if you bundle the jstl.0.LocalizationContext cannot be cast to java.jar and standard.0.tag.3. In this case. the jboss-jstl-api_1. 2.service() for servlet MVCUserInterface threw exception: java.java:178)[jbossfollowing is an example of the procedure used to resolve this type issue. Search the application archive to find all JAR(s) that are packaged with the application that contain the class named by the ClassCastException.String at org.apache.catalina.jstl.MF file or in the jboss-deployment-structure. you may see a ClassCastException similar to the following: 08:38:01. the jstl.jsp.2"> <deployment> <dependencies> <module name="javax.jar with the application archive.jar can be found in the EAP_HOME/modules/system/layers/base/javax/servlet/jstl/api/main directory. Find the JBoss module that contains the class named by the ClassCastException.taglibs.fmt. For example.jstl.[jboss.getLocalizationContext(BundleSupport.servlet.Final-redhat-2.[default-host].lang.lang.867 ERROR [org.

jboss. The default module for JSF 2.0 and the application is using JSF 1.ClassNotFoundException: javax. you may see you may see a ClassCastException or ClassNotFoundException like the following: Caused by: java. 2.api" slot="main"/> <module name="com.2 directory.WildFly 8 Resolve ClassCastExceptions and ClassNotFoundExceptions Caused by API Version Differences If your application uses a version of an API other than the default API included in the main/ module of the modules/system/layers/base/ directory.modules.faces.jsf-impl" slot="main"/> </exclusions> <dependencies> <module name="javax.2" export="true"/> <module name="com.faces.2 version in the jboss-deployment-structure.api" slot="1.0 is located in the EAP_HOME/modules/system/layers/base/javax/faces/api/main directory and a module for JSF 1.xml file and exclude the default JSF 2. For example.weblogic-example.0 dependency.2. it cannot find the class javax.faces. Search the application archives and remove any jsf-api JARs from the packaged application.2 dependency and exclude the JSF 2.lang. if your application uses JSF 1.faces. The default JSF module for JBoss AS 7 is version JSF 2. you may see a ClassCastException or a ClassNotFoundException when you run the application. To resolve this issue: 1. Find the JBoss module that contains the class named by the ClassNotFoundException.2 is located in the EAP_HOME/modules/system/layers/base/javax/faces/api/1.FacesException due to a mismatch in API versions.sun. JBoss Community Documentation Page 344 of 617 .2 instead of the default JSF 2. you must explicitly include the JSF 1. there are 2 modules for the javax. To resolve the mismatch. Explicitly define the dependency on the older JSF 1.0"> <deployment> <exclusions> <module name="javax.ear:main" from Service Module Loader\] at org.0 module as follows: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.jsf-impl" slot="1.0.sun.2" export="true"/> </dependencies> </deployment> </jboss-deployment-structure> 3.ModuleClassLoader.java:191) In this case.faces. In this case.api classes.findClass(ModuleClassLoader.FacesException from \[Module "deployment.

If your application has properties configured as type="text" that are intended to be mapped to JDBC "CLOB". a Long value is returned. For properties mapped as Float. Review code to find changes in returned value types Numeric aggregate criteria projections now return the same value type as their HQL counterparts. As a result. the return types from the following projections in org.5. JBoss AS 7 assumes the use of Hibernate 4 with JPA applications and implicitly adds Hibernate 4 plus a few other dependencies to your application classpath. You can create a custom Hibernate 3 module. 2. Due to changes in Projections. you must do one of the following: 1.x libraries. JBoss Community Documentation Page 345 of 617 . was added in Hibernate 4 to map Java String properties to JDBC "CLOB". The following sections describe how to do this. you can configure your application to use Hibernate 3. You can package the Hibernate 3 libraries with your application. Double. If you do not want to update your application to use Hibernate 4. Projections. or primitive integer types.lang.x Application to Hibernate 4. 1. A new Hibernate type. Integer. Other dependencies must be explicitly defined.WildFly 8 Hibernate and JPA Class loading in JBoss AS 7 is based on the JBoss Modules project.x application to use Hibernate 4. change the property to type="materialized_clob". If your application uses annotations. the count and count distinct projections now return a Long value.sum(propertyName). If your application uses hbm mapping files. text type was mapped to JDBC "CLOB".hibernate.criterion have changed.rowCount(). 2. If your application currently uses Hibernate 3. 2.x in one of the following ways: 1.3. Some module dependencies defined by the application server are set up for you automatically. Projections. Failure to modify your application code could result in a java. This is the recommended approach. or primitive floating point types. and Projections. You have 2 choices: 1. "materialized_clob". 2. 2.x 1. Map Hibernate text types to JDBC LONGVARCHAR In versions of Hibernate prior to 3. By default. you should replace @Type(type = "text") with @Lob. You can migrate your Hibernate 3. you may see ClassNotFoundExceptions or other Hibernate exceptions in the server log.count(propertyName). Migrate Your Application From Hibernate 3 to Hibernate 4 Migrate Your Hibernate 3. 2. 1. For properties mapped as Long. Due to changes in CountProjection. a Double value is returned. the sum projections now return a value type that depends on the property type. Short.countDistinct(propertyName).ClassCastException.

the global environment variable "hibernate. Configure Your Application to Use the Hibernate 3 Libraries If you do not want to migrate your appliation to use Hibernate 4.cfg.net/hibernate-configuration-3.sourceforge.hibernate.jdbc. it should not affect your migration. 2.use_streams_for_binary" must be set to false. the global environment variable "hibernate.sourceforge. Modify environment variables 1. JBoss Community Documentation Page 346 of 617 .WildFly 8 Migrate Your Hibernate 3.cfg.DefaultNamingStrategy" that was used in previous releases.dtd http://www.org/dtd/hibernate-configurati http://hibernate. To resolve it.xml file.DefaultNamingStrategy#INSTANCE.cfg.5.hibernate.hibernate. If you rely on the naming strategy to default the name of an association (many-to-many and collections of elements) table.use_streams_for_binary" must be set to true. 2.x 1.org/dtd/hibernate-mapping-3 3.x Application to Hibernate 4. you may see this issue.DefaultNamingStrategy by calling Configuration#setNamingStrategy and passing it org.0. If you are using PostgreSQL and using the "CLOB" or "BLOB" properties. Modify the namespaces to conform to the new Hibernate DTD file names. you should be aware that JBoss AS 7 now uses the "org.hibernate. If you are using Oracle and using the "materialized_clob" or "materialized_blob" properties.0. Merge the AnnotationConfiguration into the Configuration Although AnnotationConfiguration is now deprecated.cfg. If you are still using an hbm.net/hibernate-mapping-3.jdbc.dtd http://www. you can tell Hibernate to use the legacy org. Previous DTD Namespace New DTD Namespace http://hibernate. This can result in naming mismatches.hibernate.hibernate. you can try to resolve any issues using one of the following approaches.EJB3NamingStrategy" in AnnotationConfiguration instead of the "org.

x JARs with the Application 1. Copy the specific Hibernate 3.x JARs into the application's lib/ directory. 2. Create a Custom Module for the Hibernate 3.hibernate"/> </exclusions> <deployment> </jboss-deployment-structure> 3. In some cases this may result in ClassCastExceptions or other class loading issues due to the mixed use of the Hibernate versions.x Libraries JBoss Community Documentation Page 347 of 617 . you need to instruct the server to use only the Hibernate 3 libraries using the following procedure. or in the META-INF/ directory if you are deploying an EAR. Create a jboss-deployment-structure.WildFly 8 Package the Hibernate 3.xml file with the following content to tell the server to exclude the Hibernate 4 classes: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.xml file in either the META-INF/ directory or the WEB-INF/ directory if you are deploying a WAR. If that happens.0"> <deployment> <exclusions> <module name="org. Place the jboss-deployment-structure.

0.1.api"/> <module name="javax. Create a directory structure under the JBOSS_HOME/module directory to contain the Hibernate 3 files and JARs.jpa.apache.as.api"/> <module name="org.GA. 1.transaction. The following is an example of a module.7.jboss.jar"/> <resource-root path="commons-collections.jar"/> <resource-root path="javassist-3. Copy the JARs from the Hibernate distribution to the {{JBOSS_HOME/modules/org/hibernate/3/} folder.ant"/> <module name="org.Insert other Hibernate 3 jars to be used here --> </resources> <dependencies> <module name="org.api"/> <module name="javax.javassist"/> <module name="org. For example: $ cd JBOSS_HOME/modules/ $ mkdir -p org/hibernate/3 2.WildFly 8 1.hibernate" slot="3"/> <module name="asm. 3.jar"/> <resource-root path="dom4j-1.6.validation.6.xml file in the JBOSS_HOME/modules/org/hibernate/3/ directory that describes the JARs and dependencies for the Hibernate 3 libraries.infinispan"/> <module name="org.0" name="org.hibernate" slot="3"> <resources> <resource-root path="hibernate3. Create a custom module for the Hibernate 3 libraries.6: <?xml version="1.xml file for Hibernate 3.persistence. Create a module.api"/> <module name="javax.jar"/> <!-.jar"/> <resource-root path="antlr-2.6.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.asm"/> <module name="javax.slf4j"/> </dependencies> </module> JBoss Community Documentation Page 348 of 617 .12.

providerModule" value="org.as.as.</description> <jta-data-source>java:jboss/datasources/gameDS</jta-data-source> <properties> <property name="jboss.6. or in the META-INF/ directory if you are deploying an EAR.WildFly 8 2. Set the "jboss.0"> <deployment> <dependencies> <module name="org.com/xml/ns/persistence" version="1. Place the jboss-deployment-structure.providerModule" to "org. JBoss Community Documentation Page 349 of 617 .0"> <persistence-unit name="GameOfThrones_pu"> <description>my Hibernate 3 persistence unit.xml file in either the META-INF/ directory or the WEB-INF/ directory if you are deploying a WAR.xml using Hibernate 3.xml to use the custom Hibernate module.jpa.hibernate:3"/> </properties> </persistence-unit> The Java Persistence API (JPA) deployer will detect the presence of a persistence provider in the application and use the Hibernate 3 libraries. 3.hibernate" slot="3"/> </dependencies> <exclusions> <module name="org.6.0" encoding="UTF-8"?> <persistence xmlns="http://java.jpa.hibernate" slot="main"/> </exclusions> <deployment> </jboss-deployment-structure> 4.persistence.xml file with the following content to tell the server to use the Hibernate 3 module and exclude the Hibernate 4 libraries: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1. Create a jboss-deployment-structure.sun.hibernate:3" as follows: <!-.Final --> <?xml version="1. Modify the persistence.

is not an official standard and.6 . you must do one of the following:for JBoss to find the documents. WebLogic uses both directories during deployment to find or generate artifacts. The JCA Resource Adapter specification can be found here: JSR 322: JavaTM EE Connector Architecture 1.ironjacamar. The best approach is to implement a JCA Resource Adapter with the required business interface to replace the CommonJ code. Split Directories WebLogic supports a split development directory environment. you can set up symbolic links (symlinks) for the the documents defined with alternate roots. Replace WebLogic Virtual Directories WebLogic provides the ability to specify an alternate document root for files in a Web application using the <virtual-directory-mapping> element in the weblogic. JBoss AS 7 does not support this feature. This directory layout contains both source and build directories. is not supported in JBoss Application Server. The IronJacamar tool can help you get started writing a Resource Adapter.6 Replace WebLogic Proprietary Features WebLogic CommonJ Framework or WebLogic Work Manager API The WebLogic CommonJ framework. as such. Information about the WorkManager Interface can be found here: http://www. If an application uses this feature. sometimes referred to as the WebLogic Work Manager API. The following table shows the four stages in the application lifecycle available for listener registration in WebLogic: JBoss Community Documentation Page 350 of 617 . You must modify the application packaging structure and move the files to the well-known standard Java EE 6 location.xml proprietary descriptor file.2. For JBoss servers running on Linux.org/doc/api/spec/1.WorkManager). so it should not impact your migration.html.work. IronJacamar provides a WorkManager Resource Adapter in its test suite. Replace WebLogic ApplicationLifecycleListener Code The WebLogic ApplicationLifecycleListener abstract class is used to perform functions or schedule jobs at application server start and stop.WildFly 8 26. WebLogic applications that use the WebLogic version of the framework will need to replace this code.resource. It is not recommended for production. JBoss instead supports the Java EE 6 standard WorkManager API (javax. This model is meant for development purposes only.7/javax/resource/spi/work/WorkManager.

evt) void Provides hooks for listeners after the application ends the postStop(ApplicationLifecycleEvent shutdown process. Since the code must access the context root of the application using the ServletContext. Create a ServletContextListener The ServletContextListener class provides two methods that are analoguous to postStart() and postStop() methods in the WebLogic ApplicationLifecycleListener class. evt) Replace Application Start and Stop Events In JBoss Enterprise Application Platform 6. evt) void Provides hooks for listeners after the application finishes postStart(ApplicationLifecycleEvent initialization. the servlet must be deployed to a WAR file. there is no equivalent to intercept the preStart or preStop processing. but you can use one of the following methods to achieve results similar to the postStart and postStop methods.WildFly 8 WebLogic Method Description void Provides hooks for listeners before the application finishes preStart(ApplicationLifecycleEvent initialization. 1. evt) void Provides hooks for listeners when the application begins the preStop(ApplicationLifecycleEvent shutdown process. The following is an example of code that uses the ServletContextListener to perform tasks after application server start and stop: JBoss Community Documentation Page 351 of 617 .

currentTimeMillis()). System. System.getServletContext().servlet.getServerInfo() + " " + System. } @Override public void contextDestroyed(ServletContextEvent evt) { ServletContext ctx = evt.WebListener. @WebListener public class ContextListener implements ServletContextListener { @Override public void contextInitialized(ServletContextEvent evt) { ServletContext ctx = evt. javax. javax.ServletContextEvent. System.println("contextDestroyed(): ServerInfo: " + ctx.annotation. The following is an example of a stateless session bean: JBoss Community Documentation Page 352 of 617 .ServletContextListener.getServletContext().out.WildFly 8 import import import import javax. System. } } 2.out.currentTimeMillis()).out. javax. Create a Singleton Stateless Session Bean Create a singleton bean using the @Singleton annotation.servlet.currentTimeMillis()).println("contextDestroyed(): ContextPath: " + ctx.currentTimeMillis()).getContextPath() + " " + System.println("contextInitialized(): ServerInfo: " + ctx. Use the @PostConstruct annotation to specify the method to invoke at the start of the application lifecyle and the @PostDestroy annotation to specify the method to invoke at the end of the application life cycle.servlet. Use the @Startup annotation to tell the container to initialize the singleton session bean at application start.getContextPath() + " " + System.getServerInfo() + " " + System.ServletContext.println("contextInitialized(): ContextPath: " + ctx.servlet.out.

annotation.Startup.println("startup()". For more information on the Java EE 6 servlet annotations. Replace the Proprietary WebLogic @WLServlet Annotation You must replace the proprietary WebLogic @WLServlet annotation with the standard Java EE 6 @WebServlet equivalent.servlet.println("shutdown()". @Startup @Singleton public class StartupBean { @PostConstruct void startup() { System. } } WebLogic Proprietary Annotations WebLogic provides its own proprietary servlet and filter annotations for dependency injection. You must also remove the WebLogic imports and JAR. they must be replaced the standard Java EE 6 annotations.WebFilter @WLInitParam @WebInitParam javax. JBoss Community Documentation Page 353 of 617 . If the application uses them.WebServlet @WLFilter @WebFilter javax.out. The following table shows the mapping of the WebLogic @WLServlet annotation attributes to the Java EE 6 @WebServlet equivalents. Details about the attributes are listed below. WebLogic Java EE 6 Equivalent Java EE 6 Import @WLServlet @WebServlet javax. "@PostContruct called").annotation.PreDestroy.annotation javadoc . Before you replace the code.servlet.ejb. see the javax. you must understand how to map the attribute values.WildFly 8 import import import import javax.Singleton.WebParam Be sure to modify the attributes for the annotations to conform to the standard attribute names. "@PreDestroy called"). javax.servlet. } @PreDestroy void shutdown() { System.PostConstruct.annotation.servlet. javax.annotation.ejb.annotation. The following table contains a mapping of the most commonly used WebLogic annotations to the corresponding standard Java EE 6 annotation. javax.out.

2.security. . Here is an example of WebLogic code that uses the @WLServlet annotation: import weblogic. runAs = "SuperEditor" initParams = { @WLInitParam (name="catalog". mapping = {"/catalog/*"} ) public class MyCatalogServlet extends HttpServlet { . } Here is the equivalent code that uses the standard @WebServlet annotation: JBoss Community Documentation Page 354 of 617 . .2. Define the run-as element for the Servlet in the application's web.3 of the Servlet 3. 2.annotation.WLServlet.0 specification for further information about web-fragments. Use the javax.xml file. @WLServlet ( name = "catalog". See sections 8. value="spring").WildFly 8 WebLogic Java EE 6 Equivalent Description / Comments String displayName Display name for the Servlet String description String description Servlet description String icon String smallicon The icon location Attribute Name String displayName -or-String largeicon String name String name The Servlet name WLInitParam[] WebInitParam[] Servlet initialization parameters initParams initParams int loadOnStartup int loadOnStartup Whether the Servlet should load on server start String runAs No equivalent attribute The run-as User for the Servlet.annotation.RunAs annotation in the class file. 3. String[] mapping String[] urlPatterns or The Servlet URL pattern String[] value The following is a list of options for replacement of the runAs attribute: 1.1 through 8. @WLInitParam (name="language". Define the run-as element in a application's {{web-fragments. value="English") }. There are 3 options for replacement detailed below.xml} file.servlet.

Before you replace the code.WebServlet.servlet.RunAs. WebLogic Attribute Java EE 6 Equivalent Description / Comments String displayName String displayName Display name for the Servlet String description String description Servlet description String icon String smallicon -or-String The icon location Name largeicon String name String name The Servlet name WLInitParam[] WebInitParam[] initParams Servlet initialization parameters String[] urlPatterns or String[] The Servlet URL pattern initParams String[] mapping value No equivalent attribute No equivalent attribute DispatcherTypes[] The dispatcher types to which the filter dispatcherTypes applies String[] servletNames The names of the servlets to which the filter applies Here is an example of WebLogic code that uses the @WLFilter annotation: JBoss Community Documentation Page 355 of 617 . urlPatterns = "/catalog/*" ) @RunAs("SuperEditor") public class MyCatalogServlet extends HttpServlet { . @WebServlet ( name = "catalog".WildFly 8 import javax. import javax.security. value="spring"). initParams = { @WebInitParam (name="catalog".annotation. . The following table shows the mapping of the WebLogic @WLFilter annotation attributes to the Java EE 6 @WebFilter equivalents. } Replace the Proprietary WebLogic @WLFilter Annotation You must replace the proprietary WebLogic @WLFilter annotation with the standard Java EE 6 @WebFilter equivalent. @WebInitParam (name="language".annotation. you must understand how to map the attribute values. value="English") }. .

servlet. .annotation.WebFilter. import weblogic.WLInitParam.WildFly 8 import weblogic. .WLFilter. . value="winter") } urlPatterns = {"/catalog/*"} ) public class MyFilter implements Filter { . . } JBoss Community Documentation Page 356 of 617 . value="winter") } mapping = {"/catalog/*"} ) public class MyFilter implements Filter { .annotation.servlet.servlet. initParams = { @WebInitParam(name="catalog".annotation.servlet. } Here is the equivalent code that uses the standard @WebFilter annotation: import javax.WebInitParam.annotation. @WLFilter ( name = "catalogFilter". initParams = { @WLInitParam(name="catalog". @WebFilter ( filterName = "catalogFilter". import javax.

WLInitParam.servlet. .WebFilter. The following table shows the mapping of the WebLogic @WLInitParam annotation attributes to the Java EE 6 @WebInitParam equivalents. @WebFilter ( filterName = "catalogFilter".WildFly 8 Replace the Proprietary WebLogic @WLInitParam Annotation You must replace the proprietary WebLogic @WLInitParam annotation with the standard Java EE 6 @WebInitParam equivalent. @WLFilter ( name = "catalogFilter". JBoss Community Documentation Page 357 of 617 . import avax. . initParams = { @WebInitParam(name="catalog". .servlet.WLFilter. .servlet. value="winter". you must understand how to map the attribute values. Before you replace the code. value="winter") } mapping = {"/catalog/*"} ) public class MyFilter implements Filter { .annotation.servlet.annotation.annotation. import weblogic. } Here is the equivalent code that uses the standard @WebInitParam annotation: import javax.WebInitParam. description="winter catalog") } urlPatterns = {"/catalog/*"} ) public class MyFilter implements Filter { .annotation. initParams = { @WLInitParam(name="catalog". WebLogic Attribute Name Java EE 6 Equivalent Description / Comments String name String name Name of the initialization parameter String value String value Value of the initialization parameter No equivalent attribute String description Optional description of the initialization parameter Here is an example of WebLogic code that uses the @WLInitParam annotation: import weblogic. } WebLogic Specific Oracle Datasources TODO: section is not complete.

WildFly 8 26.2. Caching Third-party Libraries External Systems WebLogic Proprietary Libraries and APIs Examine the Current Build Process Consider conversion to Maven Analyze and Understand the Application Code JBoss Community Documentation Page 358 of 617 . Failover.7 Evaluate the WebLogic Application Examine the High-level Architecture of the Application JVM Version Frameworks Portal Rules Engine Workflow ESB IDE (Eclipse Plugins) Database JDBC compliant drivers Hibernate Persistence frameworks LDAP Requirements for High-Availablity. Clusting.

Encryption Web Services Proprietary WebLogic Features or Libraries jCOM .Bridge to ActiveX JSP tag extensions WebLogic Helper Classes Packaging and Deployment Structure of the Archives Deployment Descriptors and Plans Evaluate the WebLogic Development Tools Eclipse and Plugins NetBeans ADF Data Migration Database LDAP JMS JBoss Community Documentation Page 359 of 617 .JDBC or proprietary EJB JMS . Topics.JAAS. Messages to Migrate JNDI JTA LDAP Logging .Queues.WildFly 8 Services and Components Look for uses of the following components or services.Map WebLogic Debug options to the equivalent Java EE or JBoss classes for logging MDB Resource adapters RMI Security . Cache Clustering Data sources .

WildFly 8 Determine Need for JBoss Modules Third-party libraries Library versions not provided with JBoss 26.2.2.10 Tools and Tips Debugging Automated Tools FAQs Consulting Service 26. The following is a rough outline of topics to addressed.3 How do I migrate my application from WebSphere to WildFly The purpose of this guide is to document the application changes that are needed to successfully run and deploy WebLogic applications on AS 7.2. JBoss Community Documentation Page 360 of 617 .9 Migrate the Application Execute the Migration Plan Test Move to Production 26.8 Configure the Environment for the Migrated Applications Install JBoss Verify the Installation Using the Helloworld Quickstart 26.

xml weblogic-ejb-jar.xml Deployment Descriptor Map weblogic-ejb-jar.WildFly 8 Feel free to add content in any way you prefer.xml Elements to the jboss-ejb3.xml *-jms. This is a work in progress.xml Descriptor File Configurations Migrate weblogic-application. Introduction About this Guide Introduction to the JBoss AS 7 Server Java Enterprise Edition 6 Overview Overview of Java EE 6 Profiles Java Enterprise Edition 6 Web Profile Java Enterprise Edition 6 Full Profile JBoss AS 7 Architectural Overview Review What's New and Different in JBoss AS 7 Modules and Modular Class Loading Directory Structure of JBoss AS 7 Deployment Administration Tools Prepare for Migration Become Familiar with Java EE 6 Become Familiar with JBoss AS 7 Identify the current hardware and operating systems Examine the existing WebLogic application server and platform Examine and understand the existing WebLogic application Review monitoring and administration procedures and tools Review resources available for the migration process Prepare a migration plan Execute the plan Server Configuration and Deployment Descriptor Files WebLogic and JBoss Server Configuration File WebLogic Server Configuration and Deployment Descriptor Files JBoss AS 7 Configuration File Migrate the Server Configuration Map Configuration Files and Descriptors to the JBoss Equivalent Replace the weblogic-ejb-jar.xml Elements to the JBoss Enterprise Application Platform Equivalent Migrate weblogic.xml JBoss Community Documentation Page 361 of 617 .xml Descriptor File Configurations Replace the WebLogic plan.xml Deployment Descriptor Configuration Use Property Substitution to Specify the Target Deployment Environment WebService. You do not need to follow the template below.xml Descriptor Map Additional weblogic-ejb-jar.

WildFly 8 Security Replace WebLogic Oracle Wallets WebLogic Certicom-based SSL Implementation WebLogic Security versus JBoss JAAS Security APIs Understand Differences Between WebLogic and JBoss Implementations Overview of JNDI Differences Migrate WebLogic JNDI Lookups to Use Portable JNDI Syntax Replace WebLogic JNDI Lookup Code Portable JNDI Naming Syntax Portable JNDI Naming Syntax Rules Programmatic Login WebLogic Transaction Manager JEE Transaction Manager WebLogic JMX Lookups versus JBoss JMX Lookups Class Loading and Application Packaging Archive Packaging and Assembly Rules Debug and Resolve ClassCastExceptions and ClassNotFoundExceptions Hibernate and JPA Migrate Your Application From Hibernate 3 to Hibernate 4 Configure Your Application to Use the Hibernate 3 Libraries Replace WebLogic Proprietary Features WebLogic CommonJ Framework or WebLogic Work Manager API Replace WebLogic Virtual Directories Split Directories Replace WebLogic ApplicationLifecycleListener Code Replace Application Start and Stop Events WebLogic Proprietary Annotations Replace the Proprietary WebLogic @WLServlet Annotation Replace the Proprietary WebLogic @WLFilter Annotation Replace the Proprietary WebLogic @WLInitParam Annotation WebLogic Specific Oracle Datasources JBoss Community Documentation Page 362 of 617 .

WildFly 8 Evaluate the WebLogic Application Examine the High-level Architecture of the Application JVM Version Frameworks IDE (Eclipse Plugins) Database LDAP Requirements for High-Availablity. Failover. Caching Third-party Libraries External Systems WebLogic Proprietary Libraries and APIs Examine the Current Build Process Analyze and Understand the Application Code Services and Components Proprietary WebLogic Features or Libraries Packaging and Deployment Deployment Descriptors and Plans Evaluate the WebLogic Development Tools Eclipse and Plugins NetBeans ADF Data Migration Determine Need for JBoss Modules Configure the Environment for the Migrated Applications Install JBoss Verify the Installation Using the Helloworld Quickstart Migrate the Application Execute the Migration Plan Test Move to Production Tools and Tips Debugging Automated Tools FAQs Consulting Service JBoss Community Documentation Page 363 of 617 . Clusting.

powerful middleware platform built upon open standards. and service offerings designed to help customers migrate more complex applications. Introduction to the JBoss AS 7 Server JBoss AS 7 is a fast. or ESB frameworks. powerful messaging. rules engines. EE 6 Web Profile includes a subset of APIs which are useful to web developers. and scalable Java EE applications quickly. It integrates JBoss Application Server 7 with high-availability clustering. training. In addition. Red Hat Consulting and Red Hat partners offer a wide variety of workshops. The Management Console and Management Command Line Interface remove the need to edit XML configuration files by hand. it includes APIs and development frameworks that can be used to develop secure. or subsets of APIs.1 Introduction About this Guide The purpose of this document is to guide you through the planning process and migration of fairly simple and standard Oracle WebLogic applications to JBoss AS 7. JBoss AS 7 is a certified implementation of the Java Enterprise Edition 6 Full Profile and Web Profile specifications. The only two profiles that the EE 6 specification defines are the Full Profile and the Web Profile. significantly increasing start up speed. and compliant with the Java Enterprise Edition 6 specification.3. For more information about JBoss AS 7. EE 6 Full Profile includes all APIs and specifications included in the EE 6 specification. powerful. This document will not cover migration of advanced features such as portal. distributed caching. secure.WildFly 8 26. adding the ability to script and automate tasks. JBoss AS 7 is a certified implementation of the Java Enterprise Edition 6 Full Profile and Web Profile specifications. The new modular structure allows for services to be enabled only when required. and other technologies to create a stable and scalable platform. workflow systems. Java Enterprise Edition 6 Overview Overview of Java EE 6 Profiles Java Enterprise Edition 6 (EE 6) includes support for multiple profiles. see Getting Started with JBoss Application Server 7 . Oracle WebLogic applications that adhere to the Java EE 6 specification should require minimal changes to run on JBoss AS 7. JBoss Community Documentation Page 364 of 617 .

2 JavaServer Faces (JSF) 2. Enterprise Edition 6 Java Web Technologies Servlet 3.1 (JSR 907) Bean Validation (JSR 303) JBoss Community Documentation Page 365 of 617 .1 Lite (JSR 318) Java Persistence API 2.0 (JSR 315) JSP 2.2 Debugging Support for Other Languages 1.WildFly 8 Java Enterprise Edition 6 Web Profile The Web Profile is one of two profiles defined by the Java Enterprise Edition 6 specification. It is designed for web application development. Java EE 6 Web Profile Requirements Java Platform.1 (JSR 250) Java Transaction API (JTA) 1.0 (JSR 314) Java Standard Tag Library (JSTL) for JSP 1.2 and Expression Language (EL) 1.0 (JSR 45) Enterprise Application Technologies Contexts and Dependency Injection (CDI) (JSR 299) Dependency Injection for Java (JSR 330) Enterprise JavaBeans 3.0 (JSR 317) Common Annotations for the Java Platform 1.

4 (JSR 919) Web Service Technologies Jax-RS RESTful Web Services 1.2 (JSR 222) Web Services Metadata for the Java Platform (JSR 181) Java APIs for XML-based RPC 1.0 (JSR 93) Management and Security Technologies Java Authentication Service Provider Interface for Containers 1. class loading is based on JBoss Modules. For complete information on how to download. hides server implementation classes.3 (JSR 109) JAX-WS Java API for XML-Based Web Services 2.1 (not Lite) (JSR 318) Java EE Connector Architecture 1. This offers true application isolation.1 (JSR 914) JavaMail 1.1 (JSR 77) JBoss AS 7 Architectural Overview The following sections highlight some basic information about JBoss Enterprise Application Platform 6. Applications written for JBoss Enterprise Application Platform 5 must be modified to specify module dependencies and in some cases. Besides the items supported in the Java Enterprise Edition 6 Web Profile.WildFly 8 Java Enterprise Edition 6 Full Profile The Java Enterprise Edition 6 (EE 6) specification defines a concept of profiles.1 (JSR 311) Implementing Enterprise Web Services 1. and only loads the classes your application needs. configure. For more information.3 (JSR 67) Java API for XML Registries (JAXR) 1. refer to the Installation Guide.6 (JSR 322) Java Message Service (JMS) API 1. the class loading architecture was hierarchical. repackage archives.2 (JSR 88) J2EE Management 1. and Development Guide located on the Customer Portal . the Full Profile supports the following APIs. Review What's New and Different in JBoss AS 7 The following is a list of notable differences in JBoss AS 7 from the previous release. refer to Class Loading and Modules in the Development Guide for JBoss Enterprise Application Platform 6 on the Customer Portal . Module based class loading In previous releases of JBoss AS.0 (JSR 196) Java Authentication Contract for Containers 1. Administration and Configuration Guide. install. and defines two of them as part of the specification. Class loading is concurrent for better performance.2 (JSR 224) Java Architecture for XML Binding (JAXB) 2.3 (JSR 115) Java EE Application Deployment 1. JBoss Community Documentation Page 366 of 617 . Items Included in the EE 6 Full Profile EJB 3. JBoss AS 7 supports the Full Profile.1 (JSR 101) Java APIs for XML Messaging 1. and develop applications. In JBoss AS 7.

In a managed domain. refer to About Managed Domains in the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 on the Customer Portal . In JBoss Enterprise Application Platform 5.xml file. and other configurations. JBoss Enterprise Application Platform 5 applications that consist of multiple modules deployed as EARs and use legacy JNDI lookups instead of CDI injection or resource-ref entries may require configuration changes. this can simplify management of deployments to multiple servers. the server can be run as a standalone server or in a managed domain. database. In JBoss Enterprise Application Platform 6. resource adapter. These profiles were located in the JBOSS_HOME/server/ directory.bat is used to start a managed domain. In most cases. However. In JBoss Enterprise Application Platform 6. Applications often contained multiple configuration files for security. For servers running in a managed domain. the application server is able to automatically determine dependencies in advance and choose the most efficient deployment strategy. the server is configured using the JBOSS_HOME/domain/configuration/domain.WildFly 8 Domain Management In JBoss AS 7. Domain mode is not supported in the following JBoss Enterprise products: JBoss Portal Platform 6 Deployment Configuration Standalone Servers and Managed Domains JBoss AS 7 used profile based deployment configuration. so there is no JBOSS_HOME/server/ directory. This file is used to configure all the services and subsystems used for the deployment. JBoss AS 7 no longer uses profile based deployment configuration. JBoss Community Documentation Page 367 of 617 .bat was used to start the server.sh or Windows script JBOSS_HOME/bin/domain.sh or Windows script JBOSS_HOME/bin/run.sh or Windows script JBOSS_HOME/bin/standalone. deployment configuration is done using one file. The Linux script JBOSS_HOME/bin/domain.xml file. The information contained in the multiple JBoss Enterprise Application Platform 5 configuration files must be migrated to the new single configuration file. A standalone server is configured using the JBOSS_HOME/standalone/configuration/standalone. Directory Structure and Scripts As previously mentioned. While this should not impact applications built for previous releases. keeping configurations synchronized across your entire network of servers. Configuration files for standalone servers are now located in the JBOSS_HOME/standalone/configuration/ directory and deployments are located in the JBOSS_HOME/standalone/deployments/ directory. Ordering of deployments JBoss AS 7 uses fast. For more information. For servers running in a managed domain. The Linux script JBOSS_HOME/bin/standalone. the Linux script JBOSS_HOME/bin/run. concurrent initialization for deployment resulting in improved performance and efficiency. you can configure entire groups of servers at once.bat is used to start a standalone server. configuration files can be found in the JBOSS_HOME/domain/configuration/ directory and deployments can be found in the JBOSS_HOME/domain/deployments/ directory. the server start script is dependent on how you run your server.

mysql"> <resources> <resource-root path="mysql-connector-java-5.xml file. see Class Loading in AS7 .xml). The following is an example module. JBoss AS 7 identifies two different types of modules. <?xml version="1. The name of the module is defined in the module.1. Modules are only loaded when required.xml file.jar"/> </resources> <dependencies> <module name="javax. they can configure dependencies and be used as dependencies by other deployments. All modules provide the same features. should match the directory structure for the module. Creating custom static modules can be useful if many applications are deployed on the same server that use the same third party libraries.api"/> <module name="javax.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1. Static Modules Static Modules are predefined in the JBOSS_HOME/modules/ directory of the application server. or subdeployment in an EAR. sometimes called static and dynamic modules. a module containing these libraries can be created and installed by the JBoss administrator. including the Java EE APIs as well as other APIs such as JBoss Logging. h6. This usually only occurs when an application is deployed that has explicit or implicit dependencies.15. For more information about JNDI naming syntax.0" name="com.WildFly 8 JNDI Lookups JBoss AS 7 now uses standardized portable JNDI namespaces.api"/> </dependencies> </module> The module name. The applications can then declare an explicit dependency on the custom static modules. Because deployments are loaded as modules. see the section below on “Portable JNDI Naming Syntax”. Dynamic Modules Dynamic Modules are created and loaded by the application server for each JAR or WAR deployment. Applications that use other types of JNDI lookups must be changed to follow the new standardized JNDI namespace convention. Instead of bundling those libraries with each application.mysql. Modules and Modular Class Loading Class loading in AS 7 is based on the JBoss Modules project. However the only difference between the two is how they are packaged. For more information on modular class loading. Each sub-directory represents one module and contains one or more JAR files and a configuration file (module. The name of a dynamic module is derived from the name of the deployed archive.transaction. JBoss Community Documentation Page 368 of 617 . All the application server provided APIs are provided as static modules. Modules A Module is a logical grouping of classes used for class loading and dependency management. com.

They are loaded as multiple unique modules. These modules have the same behavior as any other module with the following additional implicit dependencies: WAR subdeployments have implicit dependencies on the parent module and any EJB JAR subdeployments.WildFly 8 Modules and Class Loading in Enterprise Archives Enterprise Archives (EAR) are not loaded as a single module like JAR or WAR deployments. Each WAR and EJB JAR subdeployment is a module. The implicit dependencies described above occur because JBoss AS 7 has subdeployment class loader isolation disabled by default. The Java EE 6 specification recommends that portable applications should not rely on subdeployments being able to access each other unless dependencies are explicitly declared as Class-Path entries in the MANIFEST. This is called the parent module. Directory Structure of JBoss AS 7 JBoss AS 7 includes a simplified directory structure. JBoss Community Documentation Page 369 of 617 . No subdeployment ever gains an implicit dependency on a WAR subdeployment. Any subdeployment can be configured with explicit dependencies on another subdeployment as would be done for any other module.MF file of each subdeployment. Subdeployment class loader isolation can be enabled if strict compatibility is required. The contents of the lib/ directory in the root of the EAR archive is a module. The following rules determine what modules exist in an EAR. compared to previous versions. It also includes directory structures of the standalone/ and domain/ folders. EJB JAR subdeployments have implicit dependencies on the parent module and any other EJB JAR subdeployments. This can be enabled for a single EAR deployment or for all EAR deployments. The following table contains a listing of the directories and a description of what each directory contains.

WildFly 8 level Directories Name Purpose appclient/ Contains configuration details for the application client container. docs/ License files. JBoss Community Documentation Page 370 of 617 . schemas. and are not meant to be edited directly. data/ Information about deployed services. deployment content. and examples. and writable areas used when JBoss EAP 6 runs as a standalone server. Therefore. jboss-modules. do not place files in this directory manually. Services are deployed using the Management Console and Management CLI. bundles/ Contains OSGi bundles which pertain to JBoss EAP 6 internal functionality. | tmp/ Contains temporary data such as files pertaining to the shared-key mechanism used by the Management CLI to authenticate local users to the managed domain.jar The bootstrapping mechanism which loads modules. modules/ Modules which are dynamically loaded by JBoss EAP 6 when services request them. deployment content. log/ Contains the run-time log files for the host and process controllers which run on the local instance. These files are modified by the Management Console and Management CLI. bin/ Contains start-up scripts for JBoss EAP 6 on Red Hat Enterprise Linux and Microsoft Windows. and writable areas used when JBoss EAP 6 runs as a managed domain. rather than by a deployment scanner. welcome-content/ Contains content used by the Welcome web application which is available on port 8080 of a default installation. servers/ Contains the equivalent data/. domain/ Configuration files. and tmp/ directories for each server instance in a domain. Directories within the domain/ directory Name Purpose configuration/ Configuration files for the managed domain. standalone/ Configuration files. log/. which contain similar data to the same directories within the top-level domain/ directory.

The Management Console also has the ability to perform administrative tasks. deployments/ Information about deployed services. lib/ External libraries which pertain to a standalone server mode. Administration Tools Management Console The Management Console is a web-based administration tool used to to start and stop servers. it helps to have an understanding of the process. the recommended approach is to manage deployments using the Management Console or Management CLI. and make persistent modifications to the server configuration. server instances and server groups in the same domain can be centrally managed from the Management Console of the domain controller. deploy and undeploy applications. However.WildFly 8 Directories within the standalone/ directory Name Purpose configuration/ Configuration files for the standalone server. Deployment TODO: section is not complete. In a Managed Domain.2 Prepare for Migration Before you attempt to migrate your WebLogic application to JBoss AS 7. These files are modified by the Management Console and Management CLI. tmp/ Contains temporary data such as files pertaining to the shared-key mechanism used by the Management CLI to authenticate local users to the server. so you can place archives in this directory to be deployed. JBoss CLI The Management Command Line Interface (CLI) is a command line administration tool that can perform operations in batch modes.3. JBoss Community Documentation Page 371 of 617 . Empty by default. with live notifications when any changes require the server instance to be restarted or reloaded. JON TODO: section is not complete. and are not meant to be edited directly. tune system settings. The standalone server does include a deployment scanner. allowing multiple tasks to be run as a group. 26.

Be totally familiar with its architecture. functions.com/technetwork/java/javaee/tech/index. JBoss Community Documentation Page 372 of 617 . Become Familiar with JBoss AS 7 See the Admin Guide and Developer Guide for details on how to configure and develop applications with JBoss AS 7. Examine and understand the existing WebLogic application Thoroughly examine the existing WebLogic application. and determine the equivalent capabilities in JBoss AS 7.WildFly 8 Become Familiar with Java EE 6 JBoss AS 7 is a fast. powerful implementation of the Java Enterprise Edition 6 specification. databases. JVMs. features and components. Assess the skills of the development team that will be doing the work and plan for training or additional consulting help. and web servers. Prepare a migration plan Develop a migration plan including a detailed roadmap and resources that will be needed. The supported JBoss configurations can be found on the Customer Portal at https://access. number of processors. Review resources available for the migration process Resources include people. disk usage and capacity. Also be aware that additional hardware and other resources will be required during the migration process until the effort is completed.com/support/configurations/jboss/. note the proprietary APIs and features and determine the JBoss or Java EE 6 equivalents. lightweight.oracle.redhat. and hardware. In particular. memory capacity. including the operating systems. software.html and a Java EE 6 tutorial here: http://docs.com/javaee/6/tutorial/doc/. You can find Java Enterprise Edition 6 documentation here: http://www. Review monitoring and administration procedures and tools Perform a review of all monitoring and administration procedures and tools in place to identify any that may need modification or replacement to work with the JBoss AS 7. Identify the current hardware and operating systems This includes the operating systems and versions. so understanding Java EE 6 is a great place to start. Examine the existing WebLogic application server and platform Examine the existing application server and platform.oracle.

WildFly 8 Execute the plan Implement the strategic migration plan and employ implementation support strategies. resource. You can find more information about the Management CLI here: CLI Recipes. the server can be run as a standalone server or in a managed domain.xml file. The best approach is to open the WebLogic configuration file and examine each section.xml and JBOSS_HOME/domain/configuration/host. You can use the Management Console or Management Command Line Interface (CLI) to configure the server and the changes will be reflected in the server configuration file. the server is configured using the JBOSS_HOME/domain/configuration/domain. A standalone server is configured using the JBOSS_HOME/standalone/configuration/standalone. Use the Admin Guide to find information about how to perform the same configuration in JBoss. In most cases you will not edit these files directly.3. cluster. JBoss AS 7 Configuration File In JBoss AS 7. and service in the domain.3 Server Configuration and Deployment Descriptor Files WebLogic and JBoss Server Configuration File WebLogic Server Configuration and Deployment Descriptor Files Configuration of the WebLogic Server is centralized in the WEBLOGIC_HOME/domains/DOMAIN_NAME/config/config. It contains the configuration parameter settings for each server instance. For servers running in a managed domain.xml files. In most cases you use the Administration Console or one of the other WebLogic tools to modify the domain's configuration and the changes are then reflected in the configuration files. Migrate the Server Configuration Unfortunately.xml file. server configuration is a complex process and there is not an easy mapping from one application server to another. 26. JBoss Community Documentation Page 373 of 617 .

xml file.xml weblogic. or standalone.xml or domain.xml Deployment Descriptor The WebLogic weblogic-ejb-jar. weblogic-cmp-rdbms-jar. map to other descriptor files. Some elements. but the following table can be used as a guideline: WebLogic File AS 7 Equivalent Description of the File ejb-jar. Many of these elements map to the jboss-ejb3. JBoss Community Documentation Page 374 of 617 .xml standalone. Replace the weblogic-ejb-jar. Deployment descriptor file describes the EJB weblogic-ejb-jar. however.xml.xml deployment descriptor file describes elements that are specific to the WebLogic Server. this or domain. *-jdbc.WildFly 8 Map Configuration Files and Descriptors to the JBoss Equivalent WebLogic configuration files are fairly complex and it can be difficult to map them to JBoss equivalents. elements that are unique to WebLogic Server.xml.xml standalone.xml JDBC datasource descriptor file.xml file in The equivalent file in JBoss Enterprise Application Platform 6.xml. In JBoss. jboss-ejb3.xml. The equivalent file in JBoss AS 7 is the jboss-ejb3.xml Deployment descriptor for web applications to or domain.xml support value-added features that are not included in the standard specifications.xml information is specified in the datasources subsystem of the JBoss configuration file.

xml XPath Element WEBLOGIC_PREFIX/ejb-name JBOSS_PREFIX/ejb-name WEBLOGIC_PREFIX/resource-description/res-ref-name JBOSS_PREFIX/resource-ref/res-ref-name WEBLOGIC_PREFIX/resource-env-description/res-env-ref-name JBOSS_PREFIX/resource-env-ref/resource-env-re WEBLOGIC_PREFIX/ejb-reference-description/ejb-ref-name JBOSS_PREFIX/ejb-ref/ejb-ref-name WEBLOGIC_PREFIX/service-reference-description/service-ref-name JBOSS_PREFIX/service-ref/service-ref-name WEBLOGIC_PREFIX/service-reference-description/wsdl-file JBOSS_PREFIX/service-ref/wsdl-file For readability.WildFly 8 Map weblogic-ejb-jar. WebLogic weblogic-ejb-jar.xml Descriptor The following table maps the WebLogic XPath elements to the corresponding JBoss XPath elements for various types of beans. replace the variable JBOSS_PREFIX with the following file path prefix depending on the bean type: Entity Bean: /ejb-jar/enterprise-beans/entity Session Bean: /ejb-jar/enterprise-beans/session Message-Driven Bean: /ejb-jar/enterprise-beans/message-driven JBoss Community Documentation Page 375 of 617 . replace the variable WEBLOGIC_PREFIX with the following path prefix: /weblogic-ejb-jar/weblogic-enterprise-bean for all bean types.xml XPath Element JBoss jboss-ejb3. the variables WEBLOGIC_PREFIX and JBOSS_PREFIX were used in place of paths in the table. For WebLogic descriptor elements.xml Elements to the jboss-ejb3. For JBoss descriptor elements.

The table that follows uses this weblogic.xml file. updates are sent to the database after each method invocation.xml file as the example. it is available as a patch.redhat. many of these features may be configured in the application deployment or JBoss server configuration files.. When set to False. but are not committed until the end of the transaction. For more information on how to configure the JBoss server.... <entity> <ejb-name>Student</ejb-name> <create-table>true</create-table> <remove-table>true</remove-table> <table-name>STUDENT</table-name> .xml Elements to the JBoss Enterprise Application Platform Equivalent The following list describes how to map addtional elements to the JBoss Enterprise Application Platform Equivalent. delay-updates-until-end-of-tx This element in the webLogic-ejb-jar. For example: <jbosscmp-jdbc> . Migrate weblogic.xml Descriptor File Configurations he weblogic. you can achieve the same behavior by specifying the <sync-on-commit-only> in the jbosscmp-jdbc. The following section provides examples of how to map a few common configurations. is used for performance reasons to delay updates to the persistent store of all beans until the end of the transaction.xml file.WildFly 8 Map Additional weblogic-ejb-jar. refer to the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 on https://access. which defaults to True. JBoss Community Documentation Page 376 of 617 . While there is no direct mapping of these descriptor elements.xml deployment descriptor file is used to support value-added features that are not included in the standard specifications for web applications.0.1. For JBoss Enterprise Application Platform 6. <sync-on-commit-only>true</sync-on-commit-only> <insert-after-ejb-post-create>true</insert-after-ejb-post-create> <call-ejb-store-on-clean>true</call-ejb-store-on-clean> </entity> </jbosscmp-jdbc> This feature is available in JBoss Enterprise Application Platform 6. This allows other processes to access the persisted data while the transaction is waiting to be completed.x.com/site/documentation/JBoss_Enterprise_Application_Platform/. In JBoss Enterprise Application Platform 6.

//DTD Web Application 7.com/servers/wls700/dtd/weblogic700-web-jar.xml <context-root>MyAppContextRoot</context-root> JBoss Community Documentation <jboss-web> <context-root>MyAppContextRoot</context-roo </jboss-web> Page 377 of 617 . Inc.xml configurations to JBoss weblogic.xml JBoss Equivalent Specify the context root: Add the following to the WEB-INF/jboss-web.0//EN" "http://www.WildFly 8 <?xml version="1.bea.dtd"> <weblogic-web-app> <context-root>MyAppContextRoot</context-root> <security-role-assignment> <role-name>TestRole1</role-name> <principal-name>TestRole1</principal-name> </security-role-assignment> <security-role-assignment> <role-name>TestRole2</role-name> <principal-name>TestRole2</principal-name> </security-role-assignment> <session-descriptor> <session-param> <param-name>TimeoutSecs</param-name> <param-value>3650</param-value> </session-param> </session-descriptor> <container-descriptor> <save-sessions-enabled>true</save-sessions-enabled> <prefer-web-inf-classes>true</prefer-web-inf-classes> </container-descriptor> <jsp-descriptor> <jsp-param> <param-name>keepgenerated</param-name> <param-value>true</param-value> </jsp-param> <jsp-param> <param-name>encoding</param-name> <param-value>ISO8859_1</param-value> </jsp-param> </jsp-descriptor> </weblogic-web-app> The following table maps the some common weblogic.0" encoding="UTF-8"?> <\!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems.

0-GA/standalon <module-option name="replaceRole" v </login-module> </authentication> </security-domain> Then add the following to the WEB-INF/jboss-web.WildFly 8 Map roles: <security-role-assignment> <role-name>TestRole1</role-name> <principal-name>TestRole1</principal-name> </security-role-assignment> Use the RoleMappingLoginModule in the server confi <security-domain name="FormBasedAuthWebAppPolic <authentication> \\ <login-module code="org. the WEB-INF/classes directories will always be loaded <container-descriptor> <save-sessions-enabled>true</save-sessions-enabled> <prefer-web-inf-classes>true</prefer-web-inf-classes> </container-descriptor> JBoss Community Documentation known alternative/relative configuration in JBoss.security. flag="required"> <module-option name="dsJndiName" va <module-option name="principalsQuer PRINCIPLES where principal_id=?"/> <module-option name="rolesQuery" va ROLES where principal_id=?"/> </login-module> <\!-\.security.jboss. flag="optional"> <module-option name="rolesPropertie value="/home/userone/jboss-eap-6.jboss.xm <jboss-web> <security-domain>java:/jaas/FormBasedAuthWe </jboss-web> Specify Session Timeout: <session-descriptor> <session-param> <param-name>TimeoutSecs</param-name> <param-value>3650</param-value> </session-param> </session-descriptor> Specify class loading precedence: Add the following to the WEB-INF/jboss-web.Following is the RoleMappingLogi <login-module code="org.xml: <session-config> <session-timeout>3650</session-timeout>\ </session-config> Since the WAR has its own scoped class loader. Page 378 of 617 .

xml deployment descriptor file is used to describe WebLogic EAR archives. The following example shows how to map a few common elements.default </param-name> <param-value> UTF8 </param-value> </application-param> JBoss Community Documentation Maps to the web.1" <virtual-server name="default-host" enable<alias name="localhost"/> <alias name="example.redhat. WebLogic weblogic-application.xml Descriptor File Configurations The weblogic-application.default </param-name> <param-value> UTF8 </param-value> </context-param> Page 379 of 617 .com/site/documentation/JBoss_Enterprise_Application_Platform/.xml file and the equivalent in standard Java EE descriptor files. The table that follows shows an example of elements in a weblogic-application.encoding. For more information on how to configure the JBoss server.com"/> </virtual-server> </subsystem> Migrate weblogic-application.xml Element JBoss Equivalent <application-param> element: <application-param> <description> Web application default encoding </description> <param-name> webapp. refer to the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 on https://access.WildFly 8 Configure JSPs: Configure JSPs in the web subsystem of the server c <jsp-descriptor> <jsp-param> <param-name>keepgenerated</param-name> <param-value>true</param-value> </jsp-param> <jsp-param> <param-name>encoding</param-name> <param-value>ISO8859_1</param-value> </jsp-param> </jsp-descriptor> <subsystem xmlns="urn:jboss:domain:web:1. While there is no direct mapping of these descriptor elements.1" def native="false"> <configuration> <jsp-configuration development="true" j keep-generated="true"/> </configuration> <connector name="http" protocol="HTTP/1. many of these features may be configured in standard Java EE files.xml <context-param> element: <context-param> <description> Web application default encoding </description> <param-name> webapp.encoding.

xml. The following is an example of the naming subsystem element configured for JNDI substitution. or production. create a <simple> element in the naming subsystem of the server configuration file. Using this technique. jboss-app.1"> <spec-descriptor-property-replacement>true</spec-descriptor-property-replacement> <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement> </subsystem> For more information about property substitution. In JBoss Enterprise Application Platform 6. The following is an example of the ee subsystem element configured to enable property substitution. <subsystem xmlns="urn:jboss:domain:ee:1. This topic describes how to change the target deployment environment in JBoss Enterprise Application Platform 6. JBoss Community Documentation Page 380 of 617 .WildFly 8 Replace the WebLogic plan. Use Property Substitution to Specify the Target Deployment Environment 1. for example. 2. To enable property substitution it must be set to true. and *-ds. jboss-web.xml descriptor files. Assume the application's web. you achieve the same outcome using property substitution.xml descriptor files.xml file contains the following resource reference: <resource-env-ref> <description>IP address of the destination</description> <resource-env-ref-name>destination/ip-address</resource-env-ref-name> <resource-env-ref-type>java. you can bind string values into JNDI and them map them into the application. This is the default value. Enable Property Substitution in the Server Configuration File The <spec-descriptor-property-replacement> element in the ee subsystem of the server configuration file is used to enable or disable property substitution in the ejb-jar. integration testing.lang.com/site/documentation/JBoss_Enterprise_Application_Platform/.xml and persistence.redhat. refer to the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal at https://access.xml.String</resource-env-ref-type> </resource-env-ref> To bind simple strings into JNDI. The <jboss-descriptor-property-replacement> element in the ee subsystem of the server configuration file is used to enable or disable property substitution in the jboss-ejb3.xml deployment descriptor file provides a way to target the application deployment for a specific environment. Bind Strings for JNDI Runtime Mapping For values outside deployment descriptors that change depending on the target environment.xml Deployment Descriptor Configuration The WebLogic plan.xml. quality assurance. you pass the new values to the deployment descriptors based on the deployment environment. *-jms. development.xml.

<jboss-web> <resource-env-ref> <resource-env-ref-name>destination/ip-address</resource-env-ref-name> <jndi-name>java:/my/jndi/key</jndi-name> </resource-env-ref> </jboss-web> Follow the same procedure to implement property substitution for other descriptor files.xml and the <jndi-name> element must match the <simple> element name in the server configuration file. For more information about how to manage the server configuration files.com/site/documentation/JBoss_Enterprise_Application_Platform/.xml WebLogic Webservice descriptor files TODO: This section is not complete *-jms. refer to the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal at https://access.redhat. The <resource-env-ref-name> element value must match the value specified in the web. WebService.1"> <bindings> <simple name="java:/my/jndi/key" value="MyJndiValue"/> </bindings> </subsystem> Add an entry to the application's jboss-web.xml WebLogic JMS descriptor file TODO: This section is not complete weblogic-ejb-jar.WildFly 8 <subsystem xmlns="urn:jboss:domain:naming:1.xml WebLogic EJB descriptor JBoss Community Documentation Page 381 of 617 .xml to map the global JNDI entry to the application's java:comp/env/ Environment Naming Context (ENC).

WildFly 8 26. WebLogic Certicom-based SSL Implementation Releases prior to WebLogic Server version 11g Release 1 (10. Configure JBoss Enterprise Application Platform 6 to Use the Java KeyStore Java KeyStores are configured in the security subsystem of the server configuration file.1111/e10105/walletmgr.3.3.5) defaulted to the Certicom-based SSL (Secure Sockets Layer) implementation.xsd file. Refer to the Oracle Wallet Manager documentation for details: http://docs. JSSE is the only SSL implementation that is supported. JBoss Enterprise Application Platform 6 supports the JSSE implementation.com/site/documentation/JBoss_Enterprise_Application_Platform/. JBoss Community Documentation Page 382 of 617 . 1. Convert Oracle Wallet to JKS Use the Oracle orapki command-line tool to convert the wallet to standard JKS keystore. The schema is defined in the file:///JBOSS_INSTALL_DIRECTORY/docs/schema/jboss-as-config_1_4.oracle.com/site/documentation/JBoss_Enterprise_Application_Platform/.htm#ASADM10989. For details on how to configure the server to use keystores.com/cd/E16340_01/core.4 Security Replace WebLogic Oracle Wallets Weblogic administrators use wallets created by Oracle Wallet Manager to manage public key security credentials on application clients and servers.redhat. For instructions on how to implement SSL in JBoss Enterprise Application Platform 6. Be sure to replace JBOSS_INSTALL_DIRECTORY in the previous link with the actual path for your install. WebLogic Security versus JBoss JAAS Security APIs TODO: This section is not complete.redhat.1. As of WebLogic Server version 12. The 11g release introduced an SSL implementation based on JSSE (Java Secure Socket Extension) and deprecated the Certicom-based SSL implementation. 2. These wallets must first be converted to standard Java KeyStore (JKS) entries that can then be used to configure the credentials in JBoss Enterprise Application Platform 6. refer to Implement SSL Encryption for the JBoss Enterprise Application Platform Web Server in the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal at https://access. refer to the chapter entitled Securing JBoss Enterprise Application Platform in the Administration and Configuration Guide for JBoss Enterprise Application Platform 6 located on the Customer Portal at https://access.1.

5 Understand Differences Between WebLogic and JBoss Implementations Overview of JNDI Differences JBoss Enterprise Application Platform 6 uses standardized portable JNDI namespaces.3.getSimpleName() ). Context context = new InitialContext( env ). "t3://localhost:7001" ). java:module. env. JBoss Community Documentation Page 383 of 617 . Migrate WebLogic JNDI Lookups to Use Portable JNDI Syntax Replace WebLogic JNDI Lookup Code In WebLogic. Then you lookup the Service using a prefix with the Service class name This is an example of how code may look in WebLogic: Hashtable<String.Service#" + Service. WebLogic applications must be changed to follow the standardized JNDI namespace convention. you create a Hashtable containing environment information such as provider URL.class. String>().lookup( "java:app/service/" + ServiceImpl. you instantiate the InitialContext with no argument and then look up the service using the portable JNDI lookup rules: java:global. context factory. You pass this table as a parameter when you create the InitialContext. In JBoss. see the sections below on Portable JNDI Naming Syntax and JNDI Namespace Rules.put( Context.put( Context. env.SECURITY_CREDENTIALS.WildFly 8 26. "weblogic" ). This is an example of what the code would look like in JBoss: Context context = new InitialContext(). String> env = new Hashtable<String. "weblogic" ).WLInitialContextFactory" ). java:app. For more information about portable JNDI naming syntax.jndi.class.PROVIDER_URL. Service service = (Service) context.SECURITY_PRINCIPAL. env.put( Context.put( Context.getName() ).lookup( "sample.INITIAL_CONTEXT_FACTORY. security principal and credentials. Service service = (Service)context. env. "weblogic.

The following table details when and how to use each namespace. Use names in this namespace to find remote EJBs. Unqualified absolute names like /jdbc/DefaultDS should be qualified relative to a java:jboss/root name. but also to prevent future compatibility issues.WildFly 8 Portable JNDI Naming Syntax There are four logical namespaces. Qualified absolute names like java:/jdbc/DefaultDS should be qualified the same way as Unqualified absolute names above. "Application Component Environment Namespaces" in the "JSR 316: JavaTM Platform. depending on the context.5. for example. Any name starting with java:xxx where xxx does not match any of the above five would result in an invalid name error. JNDI Description Namespace java:global Names in this namespace are shared by all applications deployed in an application server instance. 5. or the proprietary jboss. You can download the specification from here: http://jcp. JBoss Community Documentation Page 384 of 617 . Enterprise Edition (Java EE) Specification. each with its own scope. v6". java:module/env. or java:jboss/env.jboss. For example. Unqualified relative names like DefaultDS or jdbc/DefaultDS should be qualified relative to java:comp/env. global.org/en/jsr/detail?id=316 Portable JNDI Naming Syntax Rules JBoss Enterprise Application Platform 6 has improved upon JNDI namespace names.2. 4. This means you might run into issues with the current namespaces in your application if they don't follow the new rules. module. app. a WAR and an EJB jar file in the same EAR file would have access to resources in the java:app namespace.jar/HotelBookingAction You can find more information about JNDI naming contexts in section EE.jar/HotelBookingAction java:module Names in this namespace are shared by all components in a module. 2. Namespaces should follow these rules: 1.seam. The following is an example of a java:module namespace: java:module/HotelBookingAction!org. not only to provide predictable and consistent rules for every name bound in the application server.2. Three of the namespaces are used for portable JNDI lookups.example. Any relative name with a java: prefix must be in one of the five namespaces: comp.HotelBooking java:app Names in this namespace are shared by all components in all modules in a single application. all enterprise beans in a single EJB module or all components in a web module. The following is an example of a java:app namespace: java:app/jboss-seam-booking.booking. 3. The special java:jboss namespace is shared across the entire AS server instance. The following is an example of a java:global namespace: java:global/jboss-seam-booking/jboss-seam-booking.

login() method to perform programmatic login or you can define a <security-constraint> element in the web.annotation. you can use the standard Java EE6 Servlet 3.jsp</form-login-page> <form-error-page>/loginError. @WebServlet("/securedUrlPattern") @ServletSecurity(@HttpConstraint(rolesAllowed = { "myRole" })) @DeclareRoles("myRole") public class SecuredServlet extends HttpServlet { //Rest of code } If you prefer not to use the standard servlet.xml file may result in the error message "No authenticator available for programmatic login".servlet.xml file.xml file with a <security-constraint> element: <login-config> <auth-method>FORM</auth-method> <realm-name>ApplicationRealm</realm-name> <form-login-config> <form-login-page>/login.annotation.HttpConstraint.security.servlet.jsp</form-error-page> </form-login-config> </login-config> <security-constraint> <web-resource-collection> <web-resource-name>All resources</web-resource-name> <description>Protects all resources</description> <url-pattern>/dummy/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>myRole</role-name> </auth-constraint> </security-constraint> JBoss Community Documentation Page 385 of 617 .annotation.0 HttpServletRequest. you must replace the WebLogic proprietary code with one of the following: You can add the following annotations to the Servlet class that performs the authentication. you can instead add a <security-constraint> element containing a dummy URL pattern to the web.servlet. // Imports for annotations import javax.annotation.WildFly 8 Programmatic Login WebLogic provides a proprietary ServletAuthentication class to perform programmatic login. Failure to create a <security-constraint> element in the web. This notifies JBoss to create a default Authenticator. The following is an example of a web. import javax. To enable programmatic login.ServletSecurity. In JBoss AS 7. import javax.xml file.DeclareRoles. import javax.WebServlet.

println( "</form>" ). } catch(ServletException ex) { // handle the error response. response. } WebLogic Transaction Manager JEE Transaction Manager TODO: This section is not complete WebLogic JMX Lookups versus JBoss JMX Lookups TODO: This section is not complete JBoss Community Documentation Page 386 of 617 .getWriter(). password).getWriter().getParameter( "username" ). return.println( "Failed to log in " + username + " with the given password<br/>" ).getWriter().getWriter().getParameter( "password" ). you must replace it with the standard HttpServletRequest login as follows: String userName = request.login(userName.println( "<form name=\"FailedLogin\" method=\"post\">" ). try { request.getWriter(). response.println( "<br/>" ).println( "<input name=\"FailedLogin\" type=\"submit\" value=\"Return\" />" ). response. response. String password = request.WildFly 8 If the application uses the WebLogic proprietary ServletAuthentication class for programmatic login.

that are commonly used by applications. or other archive can be deployed without the archive extension in the directory name. Hibernate. and other commonly used classes in the server install modules/ directory. In JBoss. you may see a ClassCastException or a ClassNotFoundException. EAR. You can also create custom dynamic modules to make third-party JARs and other resources available to all applications running on the server. The following are general rules for assembly of archives or directories that are deployed to JBoss Enterprise Application Platform 6: Archives may be nested within other archived deployments. It can also be a result of the same class existing in multiple JARs. an extracted WAR. it should be located under the META-INF/ directory in the root of the EAR. This can simplify packaging of archives and eliminate the need to bundle Java EE 6 and other common classes. For more information about class loading and modules.xml file. If your application needs a version of the classes that is different than the classes located in the JBOSS_HOME/modules/system/layers/base/ directory. remove JARs. You must recreate archives for the nested artifacts.xml file if possible. Extracted directories may be nested in extracted deployments. for example myEnterpriseApp. In WebLogic. or change the packaging structure of your EAR or WAR. it should be located under the root of the application WEB-INF/ directory. refer to the chapter entitled Class Loading and Modules in the Development Guide for JBoss Enterprise Application Platform 6 on the Customer Portal . it is generally better to avoid the use of a web. Extracted directories may NOT be nested in archived deployments. If your enterprise application requires an application. Archives may be nested in extracted deployments. Modules are only loaded when a deployment requests them and these JARs or classes should not be bundled within the application archives. JBoss AS ships with a number of classes. A ClassNotFoundException can be a result of missing JARs or a mismatch of API versions.WildFly 8 Class Loading and Application Packaging Archive Packaging and Assembly Rules JBoss Enterprise Application Platform 6 uses a modular classloading system for controlling the class paths of deployed applications. the Java EE APIs. you may see a ClassCastException when you deploy or run your application. JBoss Community Documentation Page 387 of 617 .ear or myWebApp. as well as other APIs such as JBoss Logging. Debug and Resolve ClassCastExceptions and ClassNotFoundExceptions A ClassCastException can occur because a class is being loaded by a different class loader than the class it extends.war. This system provides more flexibility and control than the traditional system of hierarchical class loaders. If your WebLogic application packages a JAR that is also included in the server modules/system/layers/base/ directory. the extension must appear on the extracted directory name. The JBoss AS 7 installation includes Java EE 6. If this file is required. These classes are located in the JBOSS_HOME/modules/system/layers/base/ directory and include all the application server provided APIs. JBoss Logging. Due to the modular class loading system used by JBoss AS 7. you may need to modify deployment descriptors. For web applications. or modules.

jstl.[default-host].Final-redhat-2.getLocalizationContext(BundleSupport. the jstl.taglibs. In this case.jsp.jstl.lang. Remove the duplicate JAR(s) from the application's packaged WAR or EAR file.servlet.3. JBoss Community Documentation Page 388 of 617 . if you bundle the jstl.0.jar and standard.core. The following is an example of a jboss-deployment-structure file that defines the module dependency: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.jar can be found in the EAP_HOME/modules/system/layers/base/javax/servlet/jstl/api/main directory.apache. that are commonly used by applications.tag.service() for servlet MVCUserInterface threw exception: java. Explicitly define the dependency in either the MANIFEST.standard.catalina.apache.[jboss. Search the application archive to find all JAR(s) that are packaged with the application that contain the class named by the ClassCastException.web].0.ClassCastException: javax.[MVCUserInterface]] (http-localhost/127.String at org.jar and standard. For example.fmt.api" slot="main" /> </dependencies> </deployment> </jboss-deployment-structure> 3.jar JARs were packaged in the lib/ folder of the application archive. you may see a ClassCastException similar to the following: 08:38:01. Find the JBoss module that contains the class named by the ClassCastException.867 ERROR [org. the jboss-jstl-api_1.[/]. In this case. packaging these common JARs with your application can result in a ClassCastException.0.java:178)[jbossfollowing is an example of the procedure used to resolve this type issue.1:8080-2) Servlet.common.2"> <deployment> <dependencies> <module name="javax. To resolve this issue: 1. 2.ContainerBase. or modules.lang.LocalizationContext cannot be cast to java.xml file.servlet.MF file or in the jboss-deployment-structure.BundleSupport.2_spec-1.fmt.jar with the application archive.WildFly 8 Resolve ClassCastExceptions Caused by Duplicate JARs Because JBoss AS 7 ships with a number of classes.

2. you must explicitly include the JSF 1.api classes.findClass(ModuleClassLoader. The default JSF module for JBoss AS 7 is version JSF 2. Search the application archives and remove any jsf-api JARs from the packaged application.2" export="true"/> </dependencies> </deployment> </jboss-deployment-structure> 3.java:191) In this case.jboss. there are 2 modules for the javax.0"> <deployment> <exclusions> <module name="javax.0.sun.jsf-impl" slot="main"/> </exclusions> <dependencies> <module name="javax.ear:main" from Service Module Loader\] at org.api" slot="1.ClassNotFoundException: javax. you may see a ClassCastException or a ClassNotFoundException when you run the application.modules. In this case.2" export="true"/> <module name="com.2 version in the jboss-deployment-structure.faces.FacesException due to a mismatch in API versions. it cannot find the class javax.xml file and exclude the default JSF 2.0 is located in the EAP_HOME/modules/system/layers/base/javax/faces/api/main directory and a module for JSF 1.WildFly 8 Resolve ClassCastExceptions and ClassNotFoundExceptions Caused by API Version Differences If your application uses a version of an API other than the default API included in the main/ module of the modules/system/layers/base/ directory. Explicitly define the dependency on the older JSF 1.0 dependency.2 dependency and exclude the JSF 2. To resolve the mismatch.api" slot="main"/> <module name="com. To resolve this issue: 1.ModuleClassLoader.weblogic-example. if your application uses JSF 1. Find the JBoss module that contains the class named by the ClassNotFoundException.faces. you may see you may see a ClassCastException or ClassNotFoundException like the following: Caused by: java.2 directory.2 is located in the EAP_HOME/modules/system/layers/base/javax/faces/api/1.lang. The default module for JSF 2.FacesException from \[Module "deployment.sun.faces.2 instead of the default JSF 2.jsf-impl" slot="1.faces. For example.0 and the application is using JSF 1. JBoss Community Documentation Page 389 of 617 .0 module as follows: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.faces. 2.

2.count(propertyName).countDistinct(propertyName). or primitive floating point types. You can package the Hibernate 3 libraries with your application. the return types from the following projections in org.x 1.x in one of the following ways: 1. If your application has properties configured as type="text" that are intended to be mapped to JDBC "CLOB".lang. and Projections. 2. 2. You can migrate your Hibernate 3. or primitive integer types. you must do one of the following: 1. Short. you should replace @Type(type = "text") with @Lob. 2.5.ClassCastException. text type was mapped to JDBC "CLOB". By default. 2. Double. a Long value is returned. A new Hibernate type. JBoss AS 7 assumes the use of Hibernate 4 with JPA applications and implicitly adds Hibernate 4 plus a few other dependencies to your application classpath. you may see ClassNotFoundExceptions or other Hibernate exceptions in the server log.rowCount(). As a result. You can create a custom Hibernate 3 module. Other dependencies must be explicitly defined. was added in Hibernate 4 to map Java String properties to JDBC "CLOB".criterion have changed. change the property to type="materialized_clob". the count and count distinct projections now return a Long value. If your application uses hbm mapping files. 1. For properties mapped as Long. 2. The following sections describe how to do this.WildFly 8 Hibernate and JPA Class loading in JBoss AS 7 is based on the JBoss Modules project. a Double value is returned. For properties mapped as Float. the sum projections now return a value type that depends on the property type. Integer. 1. Projections. Due to changes in Projections. Due to changes in CountProjection.sum(propertyName). Migrate Your Application From Hibernate 3 to Hibernate 4 Migrate Your Hibernate 3.3.x libraries. Review code to find changes in returned value types Numeric aggregate criteria projections now return the same value type as their HQL counterparts. Failure to modify your application code could result in a java. If your application currently uses Hibernate 3. Some module dependencies defined by the application server are set up for you automatically.x Application to Hibernate 4. If you do not want to update your application to use Hibernate 4. Map Hibernate text types to JDBC LONGVARCHAR In versions of Hibernate prior to 3. You have 2 choices: 1. JBoss Community Documentation Page 390 of 617 . you can configure your application to use Hibernate 3. "materialized_clob". This is the recommended approach.x application to use Hibernate 4. If your application uses annotations.hibernate. Projections.

org/dtd/hibernate-mapping-3 3.0.cfg. the global environment variable "hibernate.0. you can try to resolve any issues using one of the following approaches.DefaultNamingStrategy by calling Configuration#setNamingStrategy and passing it org. Previous DTD Namespace New DTD Namespace http://hibernate. To resolve it. the global environment variable "hibernate.WildFly 8 Migrate Your Hibernate 3.hibernate. it should not affect your migration.hibernate.sourceforge.jdbc. If you are using PostgreSQL and using the "CLOB" or "BLOB" properties. Modify environment variables 1.cfg.jdbc.DefaultNamingStrategy" that was used in previous releases.EJB3NamingStrategy" in AnnotationConfiguration instead of the "org.5.hibernate.hibernate. Configure Your Application to Use the Hibernate 3 Libraries If you do not want to migrate your appliation to use Hibernate 4.dtd http://www.org/dtd/hibernate-configurati http://hibernate. JBoss Community Documentation Page 391 of 617 . Modify the namespaces to conform to the new Hibernate DTD file names.sourceforge. 2. Merge the AnnotationConfiguration into the Configuration Although AnnotationConfiguration is now deprecated. you should be aware that JBoss AS 7 now uses the "org. If you are still using an hbm.hibernate.dtd http://www.xml file. you may see this issue. If you rely on the naming strategy to default the name of an association (many-to-many and collections of elements) table.hibernate.net/hibernate-configuration-3. 2.x 1.x Application to Hibernate 4. If you are using Oracle and using the "materialized_clob" or "materialized_blob" properties.use_streams_for_binary" must be set to true.use_streams_for_binary" must be set to false.cfg. This can result in naming mismatches. you can tell Hibernate to use the legacy org.net/hibernate-mapping-3.DefaultNamingStrategy#INSTANCE.cfg.

xml file in either the META-INF/ directory or the WEB-INF/ directory if you are deploying a WAR. 2. Create a Custom Module for the Hibernate 3. Create a jboss-deployment-structure. Copy the specific Hibernate 3.xml file with the following content to tell the server to exclude the Hibernate 4 classes: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1. you need to instruct the server to use only the Hibernate 3 libraries using the following procedure.x JARs into the application's lib/ directory.x Libraries JBoss Community Documentation Page 392 of 617 .x JARs with the Application 1.hibernate"/> </exclusions> <deployment> </jboss-deployment-structure> 3.WildFly 8 Package the Hibernate 3. Place the jboss-deployment-structure. In some cases this may result in ClassCastExceptions or other class loading issues due to the mixed use of the Hibernate versions. or in the META-INF/ directory if you are deploying an EAR.0"> <deployment> <exclusions> <module name="org. If that happens.

7.0" name="org. Copy the JARs from the Hibernate distribution to the {{JBOSS_HOME/modules/org/hibernate/3/} folder.infinispan"/> <module name="org. 3.hibernate" slot="3"/> <module name="asm.jar"/> <!-.jar"/> <resource-root path="commons-collections.jboss.persistence.jar"/> <resource-root path="dom4j-1. Create a custom module for the Hibernate 3 libraries.validation.ant"/> <module name="org. 1.12.asm"/> <module name="javax.6.hibernate" slot="3"> <resources> <resource-root path="hibernate3.jar"/> <resource-root path="antlr-2.Insert other Hibernate 3 jars to be used here --> </resources> <dependencies> <module name="org.1.6.slf4j"/> </dependencies> </module> JBoss Community Documentation Page 393 of 617 .WildFly 8 1.api"/> <module name="org.xml file in the JBOSS_HOME/modules/org/hibernate/3/ directory that describes the JARs and dependencies for the Hibernate 3 libraries.api"/> <module name="javax. For example: $ cd JBOSS_HOME/modules/ $ mkdir -p org/hibernate/3 2.6: <?xml version="1.transaction.xml file for Hibernate 3.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.api"/> <module name="javax.jar"/> <resource-root path="javassist-3.0. The following is an example of a module.apache.javassist"/> <module name="org. Create a module.GA.6.as.jpa.api"/> <module name="javax. Create a directory structure under the JBOSS_HOME/module directory to contain the Hibernate 3 files and JARs.

persistence.0"> <deployment> <dependencies> <module name="org.xml to use the custom Hibernate module. 3.providerModule" to "org.hibernate" slot="3"/> </dependencies> <exclusions> <module name="org.6.providerModule" value="org.0"> <persistence-unit name="GameOfThrones_pu"> <description>my Hibernate 3 persistence unit.xml file in either the META-INF/ directory or the WEB-INF/ directory if you are deploying a WAR.jpa.Final --> <?xml version="1.as.sun.</description> <jta-data-source>java:jboss/datasources/gameDS</jta-data-source> <properties> <property name="jboss.hibernate:3" as follows: <!-.com/xml/ns/persistence" version="1.jpa.as. Modify the persistence.6.xml using Hibernate 3. Set the "jboss. Place the jboss-deployment-structure.hibernate:3"/> </properties> </persistence-unit> The Java Persistence API (JPA) deployer will detect the presence of a persistence provider in the application and use the Hibernate 3 libraries.hibernate" slot="main"/> </exclusions> <deployment> </jboss-deployment-structure> 4. or in the META-INF/ directory if you are deploying an EAR.0" encoding="UTF-8"?> <persistence xmlns="http://java.WildFly 8 2.xml file with the following content to tell the server to use the Hibernate 3 module and exclude the Hibernate 4 libraries: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1. JBoss Community Documentation Page 394 of 617 . Create a jboss-deployment-structure.

6 . It is not recommended for production.7/javax/resource/spi/work/WorkManager. The following table shows the four stages in the application lifecycle available for listener registration in WebLogic: JBoss Community Documentation Page 395 of 617 . Replace WebLogic ApplicationLifecycleListener Code The WebLogic ApplicationLifecycleListener abstract class is used to perform functions or schedule jobs at application server start and stop. Information about the WorkManager Interface can be found here: http://www. The best approach is to implement a JCA Resource Adapter with the required business interface to replace the CommonJ code. You must modify the application packaging structure and move the files to the well-known standard Java EE 6 location. For JBoss servers running on Linux. you can set up symbolic links (symlinks) for the the documents defined with alternate roots. This directory layout contains both source and build directories.3. The JCA Resource Adapter specification can be found here: JSR 322: JavaTM EE Connector Architecture 1. WebLogic applications that use the WebLogic version of the framework will need to replace this code.org/doc/api/spec/1.xml proprietary descriptor file.ironjacamar.html. JBoss instead supports the Java EE 6 standard WorkManager API (javax.WorkManager). The IronJacamar tool can help you get started writing a Resource Adapter. WebLogic uses both directories during deployment to find or generate artifacts.work.resource. IronJacamar provides a WorkManager Resource Adapter in its test suite. JBoss AS 7 does not support this feature. sometimes referred to as the WebLogic Work Manager API. is not an official standard and.WildFly 8 26. is not supported in JBoss Application Server.6 Replace WebLogic Proprietary Features WebLogic CommonJ Framework or WebLogic Work Manager API The WebLogic CommonJ framework. If an application uses this feature. Split Directories WebLogic supports a split development directory environment. you must do one of the following:for JBoss to find the documents. as such. This model is meant for development purposes only. Replace WebLogic Virtual Directories WebLogic provides the ability to specify an alternate document root for files in a Web application using the <virtual-directory-mapping> element in the weblogic. so it should not impact your migration.

Create a ServletContextListener The ServletContextListener class provides two methods that are analoguous to postStart() and postStop() methods in the WebLogic ApplicationLifecycleListener class. evt) Replace Application Start and Stop Events In JBoss Enterprise Application Platform 6. the servlet must be deployed to a WAR file. Since the code must access the context root of the application using the ServletContext.WildFly 8 WebLogic Method Description void Provides hooks for listeners before the application finishes preStart(ApplicationLifecycleEvent initialization. 1. evt) void Provides hooks for listeners after the application ends the postStop(ApplicationLifecycleEvent shutdown process. evt) void Provides hooks for listeners when the application begins the preStop(ApplicationLifecycleEvent shutdown process. but you can use one of the following methods to achieve results similar to the postStart and postStop methods. there is no equivalent to intercept the preStart or preStop processing. evt) void Provides hooks for listeners after the application finishes postStart(ApplicationLifecycleEvent initialization. The following is an example of code that uses the ServletContextListener to perform tasks after application server start and stop: JBoss Community Documentation Page 396 of 617 .

System. System.ServletContextListener.annotation. javax. System.ServletContextEvent.servlet.currentTimeMillis()).getContextPath() + " " + System. Create a Singleton Stateless Session Bean Create a singleton bean using the @Singleton annotation.currentTimeMillis()). } @Override public void contextDestroyed(ServletContextEvent evt) { ServletContext ctx = evt.println("contextDestroyed(): ServerInfo: " + ctx. @WebListener public class ContextListener implements ServletContextListener { @Override public void contextInitialized(ServletContextEvent evt) { ServletContext ctx = evt. The following is an example of a stateless session bean: JBoss Community Documentation Page 397 of 617 .getServletContext().WildFly 8 import import import import javax. javax.currentTimeMillis()).WebListener.ServletContext. Use the @Startup annotation to tell the container to initialize the singleton session bean at application start.out.getServerInfo() + " " + System. Use the @PostConstruct annotation to specify the method to invoke at the start of the application lifecyle and the @PostDestroy annotation to specify the method to invoke at the end of the application life cycle.out.println("contextDestroyed(): ContextPath: " + ctx.getContextPath() + " " + System. System.out.getServletContext(). } } 2.getServerInfo() + " " + System.servlet.currentTimeMillis()).servlet.servlet.out.println("contextInitialized(): ServerInfo: " + ctx.println("contextInitialized(): ContextPath: " + ctx. javax.

The following table contains a mapping of the most commonly used WebLogic annotations to the corresponding standard Java EE 6 annotation. javax.WildFly 8 import import import import javax.Startup.WebParam Be sure to modify the attributes for the annotations to conform to the standard attribute names. You must also remove the WebLogic imports and JAR. Before you replace the code. WebLogic Java EE 6 Equivalent Java EE 6 Import @WLServlet @WebServlet javax.servlet. they must be replaced the standard Java EE 6 annotations. you must understand how to map the attribute values. Replace the Proprietary WebLogic @WLServlet Annotation You must replace the proprietary WebLogic @WLServlet annotation with the standard Java EE 6 @WebServlet equivalent.ejb.annotation. If the application uses them. javax.annotation.annotation. } } WebLogic Proprietary Annotations WebLogic provides its own proprietary servlet and filter annotations for dependency injection.PreDestroy. } @PreDestroy void shutdown() { System.servlet.Singleton.servlet. see the javax.println("shutdown()". For more information on the Java EE 6 servlet annotations. JBoss Community Documentation Page 398 of 617 . "@PreDestroy called").annotation javadoc .annotation.out.out. javax. Details about the attributes are listed below.annotation. The following table shows the mapping of the WebLogic @WLServlet annotation attributes to the Java EE 6 @WebServlet equivalents.WebFilter @WLInitParam @WebInitParam javax.servlet.println("startup()". "@PostContruct called"). @Startup @Singleton public class StartupBean { @PostConstruct void startup() { System.ejb.WebServlet @WLFilter @WebFilter javax.PostConstruct.

See sections 8. 2. Define the run-as element for the Servlet in the application's web.3 of the Servlet 3.1 through 8. 3. @WLServlet ( name = "catalog".WildFly 8 WebLogic Java EE 6 Equivalent Description / Comments String displayName Display name for the Servlet String description String description Servlet description String icon String smallicon The icon location Attribute Name String displayName -or-String largeicon String name String name The Servlet name WLInitParam[] WebInitParam[] Servlet initialization parameters initParams initParams int loadOnStartup int loadOnStartup Whether the Servlet should load on server start String runAs No equivalent attribute The run-as User for the Servlet.xml file.annotation.RunAs annotation in the class file.2. Define the run-as element in a application's {{web-fragments. @WLInitParam (name="language".2.0 specification for further information about web-fragments. .annotation. Here is an example of WebLogic code that uses the @WLServlet annotation: import weblogic. . There are 3 options for replacement detailed below. mapping = {"/catalog/*"} ) public class MyCatalogServlet extends HttpServlet { . value="spring"). value="English") }. String[] mapping String[] urlPatterns or The Servlet URL pattern String[] value The following is a list of options for replacement of the runAs attribute: 1.security. } Here is the equivalent code that uses the standard @WebServlet annotation: JBoss Community Documentation Page 399 of 617 . runAs = "SuperEditor" initParams = { @WLInitParam (name="catalog".xml} file.servlet. Use the javax.WLServlet.

. The following table shows the mapping of the WebLogic @WLFilter annotation attributes to the Java EE 6 @WebFilter equivalents.annotation. urlPatterns = "/catalog/*" ) @RunAs("SuperEditor") public class MyCatalogServlet extends HttpServlet { . .RunAs.servlet. @WLInitParam (name="language". @WebServlet ( name = "catalog". value="English") }. initParams = { @WebInitParam (name="catalog". import javax.WebServlet.security. WebLogic Attribute Java EE 6 Equivalent Description / Comments String displayName String displayName Display name for the Servlet String description String description Servlet description String icon String smallicon -or-String The icon location Name largeicon String name String name The Servlet name WLInitParam[] WebInitParam[] initParams Servlet initialization parameters String[] urlPatterns or String[] The Servlet URL pattern initParams String[] mapping value No equivalent attribute No equivalent attribute DispatcherTypes[] The dispatcher types to which the filter dispatcherTypes applies String[] servletNames The names of the servlets to which the filter applies Here is an example of WebLogic code that uses the @WLFilter annotation: JBoss Community Documentation Page 400 of 617 .WildFly 8 import javax. you must understand how to map the attribute values.annotation. Before you replace the code. } Replace the Proprietary WebLogic @WLFilter Annotation You must replace the proprietary WebLogic @WLFilter annotation with the standard Java EE 6 @WebFilter equivalent. value="spring").

annotation. initParams = { @WLInitParam(name="catalog".annotation. @WebFilter ( filterName = "catalogFilter".annotation.WebInitParam. . value="winter") } urlPatterns = {"/catalog/*"} ) public class MyFilter implements Filter { .servlet.WebFilter. value="winter") } mapping = {"/catalog/*"} ) public class MyFilter implements Filter { .servlet.WildFly 8 import weblogic. @WLFilter ( name = "catalogFilter". . } JBoss Community Documentation Page 401 of 617 .servlet.WLFilter.WLInitParam. .servlet. } Here is the equivalent code that uses the standard @WebFilter annotation: import javax.annotation. initParams = { @WebInitParam(name="catalog". import javax. . import weblogic.

description="winter catalog") } urlPatterns = {"/catalog/*"} ) public class MyFilter implements Filter { . . The following table shows the mapping of the WebLogic @WLInitParam annotation attributes to the Java EE 6 @WebInitParam equivalents. @WebFilter ( filterName = "catalogFilter". initParams = { @WLInitParam(name="catalog". you must understand how to map the attribute values. import weblogic. value="winter") } mapping = {"/catalog/*"} ) public class MyFilter implements Filter { .WLFilter. } WebLogic Specific Oracle Datasources TODO: section is not complete.servlet.servlet. . JBoss Community Documentation Page 402 of 617 .servlet. value="winter".WLInitParam.annotation. initParams = { @WebInitParam(name="catalog". import avax. . @WLFilter ( name = "catalogFilter".WildFly 8 Replace the Proprietary WebLogic @WLInitParam Annotation You must replace the proprietary WebLogic @WLInitParam annotation with the standard Java EE 6 @WebInitParam equivalent.annotation. } Here is the equivalent code that uses the standard @WebInitParam annotation: import javax.annotation.servlet. . Before you replace the code.WebInitParam.WebFilter.annotation. WebLogic Attribute Name Java EE 6 Equivalent Description / Comments String name String name Name of the initialization parameter String value String value Value of the initialization parameter No equivalent attribute String description Optional description of the initialization parameter Here is an example of WebLogic code that uses the @WLInitParam annotation: import weblogic.

3.7 Evaluate the WebLogic Application Examine the High-level Architecture of the Application JVM Version Frameworks Portal Rules Engine Workflow ESB IDE (Eclipse Plugins) Database JDBC compliant drivers Hibernate Persistence frameworks LDAP Requirements for High-Availablity. Failover. Caching Third-party Libraries External Systems WebLogic Proprietary Libraries and APIs Examine the Current Build Process Consider conversion to Maven Analyze and Understand the Application Code JBoss Community Documentation Page 403 of 617 .WildFly 8 26. Clusting.

Messages to Migrate JNDI JTA LDAP Logging .WildFly 8 Services and Components Look for uses of the following components or services.Queues.JDBC or proprietary EJB JMS .Map WebLogic Debug options to the equivalent Java EE or JBoss classes for logging MDB Resource adapters RMI Security .JAAS. Encryption Web Services Proprietary WebLogic Features or Libraries jCOM . Cache Clustering Data sources .Bridge to ActiveX JSP tag extensions WebLogic Helper Classes Packaging and Deployment Structure of the Archives Deployment Descriptors and Plans Evaluate the WebLogic Development Tools Eclipse and Plugins NetBeans ADF Data Migration Database LDAP JMS JBoss Community Documentation Page 404 of 617 . Topics.

10 Tools and Tips Debugging Automated Tools FAQs Consulting Service JBoss Community Documentation Page 405 of 617 .WildFly 8 Determine Need for JBoss Modules Third-party libraries Library versions not provided with JBoss 26.8 Configure the Environment for the Migrated Applications Install JBoss Verify the Installation Using the Helloworld Quickstart 26.3.3.3.9 Migrate the Application Execute the Migration Plan Test Move to Production 26.

27. WildFly 8 is based on module classloading. EJBs typically need access to classes from the javax. when and which modules are added as implicit dependencies. unless module B adds a dependency on module A. the deployers within the server. JBoss Community Documentation Page 406 of 617 .ejb. For an application to be able to use these classes.WildFly 8 27 Implicit module dependencies for deployments As explained in the Class Loading in WildFly article. Forcing the application developers to add module dependencies like these (i. This article will explain what implicit module dependencies mean and how. Hence. whenever an application is being deployed. it has to add a dependency on the relevant modules.1 What's an implicit module dependency? Consider an application deployment which contains EJBs.ejb. This way the application developer doesn't have to worry about adding them explicitly. Module dependencies can be explicitly (as explained in that classloading article) or can be "implicit". which are processing this deployment "implicitly" add these module dependencies to the deployment so that these classes are visible to the deployment at runtime. A class within a module B isn't visible to a class within a module A.* classes has a specific name and so does the module which contains all the Java EE API classes. The jars containing these packages are already shipped in WildFly and are available as "modules".e. How and when these implicit dependencies are added is explained in the next section. dependencies which can be "inferred") isn't a productive approach.* package and other Java EE API packages. The module which contains the javax.

jdk org. even if the trigger condition is not met.WildFly 8 27. it goes through a chain of "deployment processors". so that all the Java EE API classes are visible to the deployment.. When the deployment containing this class is being processed. In the next section.api sun. by various deployers within WildFly. we have a simple @Stateless EJB. we'll list down the implicit module dependencies that are added to a deployment.2 How and when is an implicit module dependency added? When a deployment is being processed by the server.3 Which are the implicit module dependencies? Subsystem Dependencies that are always Dependencies that are added if a trigger responsible added condition is met for adding the implicit dependency Core Server javax.java @Stateless public class MySuperDuperBean { .jboss. The EJB deployment processor will then add an implicit dependency on the Java EE API module. the deployment processor adds a implicit module dependency to that deployment..vfs JBoss Community Documentation Page 407 of 617 . Let's take an example Consider (again) an EJB3 deployment which has the following class: MySuperDuperBean. These are listed separately below. This is just one of the several ways. 27. the EJB deployment processor will see that the deployment contains a class with the @Stateless annotation and thus identifies this as a EJB deployment. } As can be seen. Each of these processors will have a way to check if the deployment meets a certain criteria and if it does. Some subsystems will always add a API classes. various deployment processors can identify a deployment of some specific type.

validation.WildFly 8 EE Subsystem javaee.resteasy.ironjacamar.jboss.resteasy-jaxb-provider org.api org.resteasy.resteasy.jboss.api subsystem javaee.jboss.resteasy-multipart-provider org.jboss.resteasy.validator JPA (Hibernate) javax.resteasy-jackson-provider org.api org.bind.jboss.jboss.jboss.resteasy-atom-provider org.persistence.resteasy-jaxrs org.api subsystem JAX-RS (Resteasy) javax.jpa org.api org.hibernate JBoss Community Documentation Page 408 of 617 .resteasy.api javax.resteasy.api org.resource.resteasy.ironjacamar.api javax.async-http-servlet-30 JCA sub-system javax.as.api EJB3 javaee.jboss.hibernate.jboss.logging org.jboss.jms.jboss.resteasy-jsapi org.impl org.xml.resteasy-cdi subsystem org.jboss.resteasy.

jboss.jboss.api Subsystem org.jboss.logging Subsystem org.log4j org.WildFly 8 Logging Subsystem org.logging Web Services org.jboss.api org.web org.ws.api org.weld org.jboss.validator org.spi Weld (CDI) Subsystem javax.jboss.as.as.logging org.weld.jboss.logging.jsf-impl org.persistence.modules Security Subsystem org.commons.ws.apache.picketbox Web javaee.logging org.javassist org.core org.jboss.weld.hibernate.logging org.weld.jboss.jboss.spi JBoss Community Documentation Page 409 of 617 .jboss.interceptor org.jboss.slf4j org.jboss.api Subsystem com.jul-to-slf4j-stub SAR org.apache.sun.api javaee.jboss.

Simply include a subclass of javax.ws.rs. These three methods are specified in the JAX-RS 1. 28.rs. For example: @ApplicationPath("/mypath") public class MyApplication extends Application { } This will make your JAX-RS resources available under /mywebappcontext/mypath.ws. and annotate it with the path that you want your JAX-RS classes to be available.core.2.1 specification in section 2.WildFly 8 28 RS Reference Guide This page outlines the three options you have for deploying JAX-RS applications in WildFly 8.Application in your application.core.3.Application and using @ApplicationPath This is the easiest way and does not require any xml configuration.1 Subclassing javax. Note that that the path is /mypath not /mypath/* JBoss Community Documentation Page 410 of 617 .

ws.rs.xml as follows: <servlet-mapping> <servlet-name>javax.xml If you don't wan't to subclass Application you can set the JAX-RS mapping in web.MyApplication</servlet-name> <url-pattern>/hello/*</url-pattern> </servlet-mapping> This will make your JAX-RS resources available under /mywebappcontext/hello.core.WildFly 8 28. You can also use this approach to override an application path set with the @ApplicationPath annotation.core.2 Subclassing javax.rs. The server is responsible for adding the corresponding servlet automatically.3 Using web.acme.Application</servlet-name> <url-pattern>/hello/*</url-pattern> </servlet-mapping> This will make your JAX-RS resources available under /mywebappcontext/hello.xml: public class MyApplication extends Application { } <servlet-mapping> <servlet-name>com.Application and using web. JBoss Community Documentation Page 411 of 617 .ws.xml If you do not wish to use @ApplicationPath but still need to subclass Application you can set up the JAX-RS mapping in web. 28. Note that you only have to add the mapping. not the corresponding servlet.

a variety of mechanisms exist to access remote components. This centralized directory is. In a nutshell. whereas Client JNDI requires one. EJB) java:module . This approach is the most efficient.e. However. it is highly recommended to use Client JNDI over traditional remote JNDI access. however. but without network round-trips.Scoped to the application server In addition to the standard namespaces.This is a more familiar approach to EE application developers. This is useful in that it allows applications to only ever reference standard portable Java EE names in both code and deployment descriptors.This is a mechanism by which remote components can be accessed using the JNDI APIs. so user customizations are not possible. Every WildFly instance has it's own local JNDI namespace (java:) which is unique per JVM.1 Overview WildFly offers several mechanisms to retrieve components by name.The namespace is scoped to the current component (i. to make this possible. a single point of failure. so that you can take advantage of certain core services such as naming and injection. and for a centralised directory for multiple application servers. For this reason. EE Application Client / Server-To-Server Delegation .2 Local JNDI The Java EE platform specification defines the following JNDI contexts: java:comp . Traditional Remote JNDI .Scoped to the current application java:global . Future revisions will likely add a JMS client JNDI namespace.WildFly 8 29 JNDI Reference 29. and a proxy/stub to the component is serialized as part of the name lookup and returned to the client. it does require that all names follow a strict layout. Applications which share the same WildFly instance can use this namespace to intercommunicate. This feature allows you to run an extremely minimal AS server around your application.Scoped to the current module java:app . where the client performs a remote component name lookup against a server. WildFly also provides the following two global namespaces: JBoss Community Documentation Page 412 of 617 . In addition to local JNDI. It also allows for the application to be unaware of network topology details/ This can even work with Java SE clients by using the little known EE Application Client feature. Currently only access to remote EJBs is supported via the ejb: namespace. and removes a potential single point of failure. traditional remote JNDI involves two calls to invoke an EE component. The layout of this namespace is primarily governed by the Java EE specification.This approach is where local names are bound as an alias to a remote name using one of the above mechanisms. Client JNDI . The client then invokes a method on the proxy which results in another remote network call to the underlying service. 29. It does however allow for customized names.

<web-app xmlns="http://xmlns.jcp.jcp.org/xml/ns/javaee" xmlns:xsi="http://www.1"> <env-entry> <env-entry-name>java:global/mystring</env-entry-name> <env-entry-type>java.xml binds the string "Hello World" to java:global/mystring and the string "Hello Module" to java:comp/env/hello (any non absolute JNDI name is relative to java:comp/env context).lang.1 Binding entries to JNDI There are several methods that can be used to bind entries into JNDI in WildFly. Using a deployment descriptor For Java EE applications the recommended way is to use a deployment descriptor to create the binding.String</env-entry-type> <env-entry-value>Hello World</env-entry-value> </env-entry> <env-entry> <env-entry-name>hello</env-entry-name> <env-entry-type>java. For web deployments java:comp is aliased to java:module. JBoss Community Documentation Page 413 of 617 . so EJB's deployed in a war do not have their own comp namespace.WildFly 8 java:jboss java:/ Only entries within the java:jboss/exported context are accessible over remote JNDI.xsd" version="3.lang.jcp.org/xml/ns/javaee/web-app_3_1. see the Java EE Platform Specification.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.2.org/xml/ns/javaee http://xmlns.String</env-entry-type> <env-entry-value>Hello Module</env-entry-value> </env-entry> </web-app> For more details. For example the following web. 29.w3.

which is executed out of a Java EE application context. included with Java SE. InitialContext initialContext = new InitialContext().bind("java:global/a". initialContext. WritableServiceBasedNamingStore. thus using one out of the module/extension domain usage should be avoided. java:module and java:app namespaces are read-only. } The ServiceTarget removes the bind when uninstalled.bind("java:global/a". 100). JBoss Community Documentation Page 414 of 617 . the bind() invocation needs to be wrapped using WildFly proprietary APIs: InitialContext initialContext = new InitialContext(). 100). to bind entries in the global namespaces (the standard java:comp. as mandated by the Java EE Platform Specification). using the standard JNDI API may result in a UnsupportedOperationException if the target namespace uses a WritableServiceBasedNamingStore. There is no need to unbind entries created programatically. To work around that.WildFly 8 Programatically Java EE Applications Standard Java EE applications may use the standard JNDI API. try { initialContext.popOwner(). } finally { WritableServiceBasedNamingStore. WildFly Modules and Extensions With respect to code in WildFly Modules/Extensions. since WildFly tracks which bindings belong to a deployment. unless entries are removed using unbind().pushOwner(serviceTarget). and the bindings are automatically removed when the deployment is undeployed.

ldap.credentials" value=“secret” /> </environment> </external-context> <lookup name="java:global/c" lookup="java:global/b" /> </bindings> </subsystem> The CLI may also be used to bind an entry.lang.provider.The allows to create JNDI aliases.URL" /> <object-factory name="java:global/b" module="com. External Context . This can be done by either editing the standalone.example.URL entry (default is java.WildFly 8 Naming Subsystem Configuration It is also possible to bind to one of the three global namespaces using configuration in the naming subsystem.This allows to to specify the javax.acme" class="org. when this entry is looked up it will lookup the target and return the result.naming.acme.MyObjectFactory" /> <external-context name="java:global/federation/ldap/example” class="javax.InitialDirContext" cache="true"> <environment> <property name="java.naming.String).principal" value=“uid=admin.xml file directly.ObjectFactory that is used to create the looked up value.initial" value=“com.A primitive or java. JBoss Community Documentation Page 415 of 617 . As an example: /subsystem=naming/binding=java\:global\/mybinding:add(binding-type=simple. An example standalone.org" type="java.sun.net. or through the management API.naming.com:389” /> <property name="java. value=1000) WildFly's Administrator Guide includes a section describing in detail the Naming subsystem configuration.LdapCtxFactory” /> <property name="java.factory.An external context to federate.net.spi.xml might look like: <subsystem xmlns="urn:jboss:domain:naming:2. Object Factory .security.security.0" > <bindings> <simple name="java:global/a" value="100" type="int" /> <simple name="java:global/jbossDocs" value="https://docs.jboss.naming.naming.xml/domain. Four different types of bindings are supported: Simple .naming.directory.authentication" value=“simple” /> <property name="java.jndi.security.ou=system” /> <property name="java. type=long.naming. such as an LDAP Directory Service Lookup .url" value=“ldap://ldap.

String/myString.lang. with respect to the field named myString above. JBoss Community Documentation Page 416 of 617 . and when that happens it's up to WildFly to provide a default value or null. but there is no such entry in the deployment descriptor. Note that @Resource is more than a JNDI lookup. the @Resource's lookup attribute instructs WildFly to lookup the value in java:global/mystring.2 Retrieving entries from JNDI Resource Injection For Java EE applications the recommended way to lookup a JNDI entry is to use @Resource injection: @Resource(lookup = "java:global/mystring") private String myString. More. it is considered relative to java:comp/env.String/myString. bind it in java:comp/env/java. so the bind's name would default to java:comp/env/javax. depending on the field's Java type. the value in java:comp/DefaultManagedExecutorService.lang. there is no lookup attribute value defined. In this particular case WildFly would inject the default instance of a managed executor service. @Resource ManagedExecutorService executor.0 Specification (JSR 236). so the responsibility to provide the entry's value is delegated to the deployment descriptor. The new bind JNDI name is defined by @Resource's name attribute.ManagedExecutorService/executor. @Resource(name = "hello") private String hello. then WildFly inject the valued defined in the deployment descriptor into the field. With respect to the field named hello.xml previously shown. for instance java.2. and then inject such value into the field. unless the name is an absolute JNDI name. For instance. is the Java type concatenated with / and the field's name.concurrent. similar to when using deployment descriptors to bind JNDI entries.enterprise. if unspecified. Considering that the deployment descriptor was the web. which value.WildFly 8 29. The executor field has no attributes specified. which defines an environment entry with same hello name. as mandated by the EE Concurrency Utilities 1. it also binds an entry in the component's JNDI environment.

final Properties env = new Properties().wildfly</groupId> <artifactId>wildfly-ejb-client-bom</artifactId> <version>8. To use it.INITIAL_CONTEXT_FACTORY.client. org.3 Remote JNDI WildFly supports two different types of remote JNDI. you must have the appropriate jars on the class path. the standard JNDI API to lookup an entry from JNDI: String myString = (String) new InitialContext().jboss.naming. remoteContext = new InitialContext(env).class. or simply String myString = InitialContext.lookup("java:global/mystring").remote. 29.0.getName()).InitialContextFactory.3.doLookup("java:global/mystring"). 29.put(Context. The old jnp based JNDI implementation used in JBoss AS versions prior to 7.x is no longer supported.put(Context.1 remote: The remote: protocol uses the WildFly remoting protocol to lookup items from the servers local JNDI. if you are maven user can be done simply by adding the following to your pom.xml: <dependency> <groupId>org.PROVIDER_URL. JBoss Community Documentation Page 417 of 617 . without any additional configuration needed. env. env.WildFly 8 Standard Java SE JNDI API Java EE applications may use.0.Final</version> <type>pom</type> <scope>compile</scope> </dependency> If you are not using maven a shaded jar that contains all required classes can be found in the bin/client directory of WildFly's distribution. "remote://localhost:4447").

Scoped to the current application java:global . instead a proxy will be generated for the remote interface specified in the name.Scoped to the current module java:app . using their application name.MyRemoteInterface ejb:myapp/myejbjar/MyStatefulName!comp. This protocol allows you to look up EJB's. 29. JBoss Community Documentation Page 418 of 617 . Using this protocol it is possible to look up EJB's that do not actually exist. and no error will be thrown until the proxy is actually used.4 Local JNDI The Java EE platform specification defines the following JNDI contexts: java:comp .test. in order to tell the server to create the SFSB session. This lookup will not hit the server. The second example is for a stateful session bean.Scoped to the application server In addition to the standard namespaces. The exception to this is stateful session beans.The namespace is scoped to the current component (i.WildFly 8 29. When you invoke a method on this proxy it will use the current EJB client context to perform the invocation. Some examples are: ejb:myapp/myejbjar/MyEjbName!com. stateless or EJB 2. EJB) java:module . For more details on how the server connections are configured. module name. in this case the JNDI lookup will hit the server. If the current context does not have a connection to a server with the specified EJB deployed then an error will occur.x home interface. which need to connect to a server when they are created in order to create the session bean instance on the server. ejb name and interface type. please see EJB invocations from a remote client using JNDI. This is a client side JNDI implementation.MyStatefulRemoteInterface?stateful The first example is a lookup of a singleton.e.2 ejb: The ejb: namespace is provided by the jboss-ejb-client library. Instead of looking up an EJB on the server the lookup name contains enough information for the client side library to generate a proxy with the EJB information.test.3. WildFly also provides the following two global namespaces: java:jboss java:/ Only entries within the java:jboss/exported context are accessible over remote JNDI.

29.String</env-entry-type> <env-entry-value>Hello Module</env-entry-value> </env-entry> </web-app> For more details.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.1"> <env-entry> <env-entry-name>java:global/mystring</env-entry-name> <env-entry-type>java.org/xml/ns/javaee http://xmlns.lang. For example the following web.jcp.xml binds the string "Hello World" to java:global/mystring and the string "Hello Module" to java:comp/env/hello (any non absolute JNDI name is relative to java:comp/env context).lang.org/xml/ns/javaee" xmlns:xsi="http://www.WildFly 8 For web deployments java:comp is aliased to java:module. see the Java EE Platform Specification. so EJB's deployed in a war do not have their own comp namespace.org/xml/ns/javaee/web-app_3_1. JBoss Community Documentation Page 419 of 617 . Using a deployment descriptor For Java EE applications the recommended way is to use a deployment descriptor to create the binding.4.jcp.1 Binding entries to JNDI There are several methods that can be used to bind entries into JNDI in WildFly.w3.xsd" version="3. <web-app xmlns="http://xmlns.jcp.String</env-entry-type> <env-entry-value>Hello World</env-entry-value> </env-entry> <env-entry> <env-entry-name>hello</env-entry-name> <env-entry-type>java.

100). To work around that. included with Java SE. initialContext. } The ServiceTarget removes the bind when uninstalled. the bind() invocation needs to be wrapped using WildFly proprietary APIs: InitialContext initialContext = new InitialContext(). try { initialContext. which is executed out of a Java EE application context. 100). WritableServiceBasedNamingStore. using the standard JNDI API may result in a UnsupportedOperationException if the target namespace uses a WritableServiceBasedNamingStore. unless entries are removed using unbind(). to bind entries in the global namespaces (the standard java:comp. and the bindings are automatically removed when the deployment is undeployed. There is no need to unbind entries created programatically. as mandated by the Java EE Platform Specification).bind("java:global/a". } finally { WritableServiceBasedNamingStore. java:module and java:app namespaces are read-only.pushOwner(serviceTarget). InitialContext initialContext = new InitialContext(). JBoss Community Documentation Page 420 of 617 . WildFly Modules and Extensions With respect to code in WildFly Modules/Extensions.popOwner().bind("java:global/a". thus using one out of the module/extension domain usage should be avoided. since WildFly tracks which bindings belong to a deployment.WildFly 8 Programatically Java EE Applications Standard Java EE applications may use the standard JNDI API.

type=long. An example standalone. or through the management API.ldap.principal" value=“uid=admin.MyObjectFactory" /> <external-context name="java:global/federation/ldap/example” class="javax.xml file directly.acme.net.credentials" value=“secret” /> </environment> </external-context> <lookup name="java:global/c" lookup="java:global/b" /> </bindings> </subsystem> The CLI may also be used to bind an entry.The allows to create JNDI aliases.example.URL" /> <object-factory name="java:global/b" module="com.sun.ObjectFactory that is used to create the looked up value.security. value=1000) WildFly's Administrator Guide includes a section describing in detail the Naming subsystem configuration.ou=system” /> <property name="java.jboss. External Context .An external context to federate.A primitive or java.provider.naming.security.LdapCtxFactory” /> <property name="java.naming.naming. Four different types of bindings are supported: Simple .InitialDirContext" cache="true"> <environment> <property name="java. JBoss Community Documentation Page 421 of 617 .naming.initial" value=“com.xml might look like: <subsystem xmlns="urn:jboss:domain:naming:2.jndi.This allows to to specify the javax. such as an LDAP Directory Service Lookup .factory.naming.net.directory.lang.URL entry (default is java.naming.naming.com:389” /> <property name="java.spi. This can be done by either editing the standalone.WildFly 8 Naming Subsystem Configuration It is also possible to bind to one of the three global namespaces using configuration in the naming subsystem.org" type="java.security.url" value=“ldap://ldap. As an example: /subsystem=naming/binding=java\:global\/mybinding:add(binding-type=simple.String).authentication" value=“simple” /> <property name="java. when this entry is looked up it will lookup the target and return the result. Object Factory .acme" class="org.0" > <bindings> <simple name="java:global/a" value="100" type="int" /> <simple name="java:global/jbossDocs" value="https://docs.xml/domain.

and then inject such value into the field. The new bind JNDI name is defined by @Resource's name attribute. but there is no such entry in the deployment descriptor.concurrent. With respect to the field named hello.0 Specification (JSR 236). if unspecified. with respect to the field named myString above.enterprise. as mandated by the EE Concurrency Utilities 1. it is considered relative to java:comp/env.xml previously shown.2 Retrieving entries from JNDI Resource Injection For Java EE applications the recommended way to lookup a JNDI entry is to use @Resource injection: @Resource(lookup = "java:global/mystring") private String myString.ManagedExecutorService/executor. so the bind's name would default to java:comp/env/javax. for instance java.lang. unless the name is an absolute JNDI name. Note that @Resource is more than a JNDI lookup. More.lang. The executor field has no attributes specified. For instance. the @Resource's lookup attribute instructs WildFly to lookup the value in java:global/mystring. depending on the field's Java type.String/myString. is the Java type concatenated with / and the field's name. Considering that the deployment descriptor was the web. and when that happens it's up to WildFly to provide a default value or null. the value in java:comp/DefaultManagedExecutorService. bind it in java:comp/env/java. which defines an environment entry with same hello name. it also binds an entry in the component's JNDI environment. so the responsibility to provide the entry's value is delegated to the deployment descriptor. then WildFly inject the valued defined in the deployment descriptor into the field. @Resource ManagedExecutorService executor.String/myString. which value. JBoss Community Documentation Page 422 of 617 . similar to when using deployment descriptors to bind JNDI entries.WildFly 8 29. In this particular case WildFly would inject the default instance of a managed executor service. there is no lookup attribute value defined.4. @Resource(name = "hello") private String hello.

WildFly 8 Standard Java SE JNDI API Java EE applications may use. JBoss Community Documentation Page 423 of 617 . remote: The remote: protocol uses the WildFly remoting protocol to lookup items from the servers local JNDI.naming.put(Context.0.5 Remote JNDI Reference 29.doLookup("java:global/mystring"). or simply String myString = InitialContext. final Properties env = new Properties(). To use it.xml: <dependency> <groupId>org. env. org.Final</version> <type>pom</type> <scope>compile</scope> </dependency> If you are not using maven a shaded jar that contains all required classes can be found in the bin/client directory of WildFly's distribution.0.getName()).PROVIDER_URL.jboss. The old jnp based JNDI implementation used in JBoss AS versions prior to 7.client. 29. without any additional configuration needed.InitialContextFactory.lookup("java:global/mystring"). "remote://localhost:4447").wildfly</groupId> <artifactId>wildfly-ejb-client-bom</artifactId> <version>8.5.x is no longer supported.remote. if you are maven user can be done simply by adding the following to your pom.1 Remote JNDI WildFly supports two different types of remote JNDI.put(Context.INITIAL_CONTEXT_FACTORY.class. you must have the appropriate jars on the class path. env. the standard JNDI API to lookup an entry from JNDI: String myString = (String) new InitialContext(). remoteContext = new InitialContext(env).

This is a client side JNDI implementation. please see EJB invocations from a remote client using JNDI.MyStatefulRemoteInterface?stateful The first example is a lookup of a singleton. stateless or EJB 2.test. Some examples are: ejb:myapp/myejbjar/MyEjbName!com. For more details on how the server connections are configured. 29. in this case the JNDI lookup will hit the server.test. module name. The exception to this is stateful session beans. If the current context does not have a connection to a server with the specified EJB deployed then an error will occur. which need to connect to a server when they are created in order to create the session bean instance on the server. ejb name and interface type. Using this protocol it is possible to look up EJB's that do not actually exist. The second example is for a stateful session bean. Instead of looking up an EJB on the server the lookup name contains enough information for the client side library to generate a proxy with the EJB information.MyRemoteInterface ejb:myapp/myejbjar/MyStatefulName!comp.WildFly 8 ejb: The ejb: namespace is provided by the jboss-ejb-client library. in order to tell the server to create the SFSB session. JBoss Community Documentation Page 424 of 617 . instead a proxy will be generated for the remote interface specified in the name.x home interface. This protocol allows you to look up EJB's. using their application name.2 Remote JNDI Access WildFly supports two different types of remote JNDI. When you invoke a method on this proxy it will use the current EJB client context to perform the invocation.5. and no error will be thrown until the proxy is actually used. This lookup will not hit the server.

WildFly 8

http-remoting:
The http-remoting: protocol implementation is provided by JBoss Remote Naming project, and uses http
upgrade to lookup items from the servers local JNDI. To use it, you must have the appropriate jars on the
class path, if you are maven user can be done simply by adding the following to your pom.xml
dependencies:

<dependency>
<groupId>org.wildfly</groupId>
<artifactId>wildfly-ejb-client-bom</artifactId>
<version>8.0.0.Final</version>
<type>pom</type>
</dependency>

If you are not using maven a shaded jar that contains all required classes
can be found in the bin/client directory of WildFly's distribution.

final Properties env = new Properties();
env.put(Context.INITIAL_CONTEXT_FACTORY,
"org.jboss.naming.remote.client.InitialContextFactory");
env.put(Context.PROVIDER_URL, "http-remoting://localhost:8080");
// the property below is required ONLY if there is no ejb client configuration loaded (such as a
// jboss-ejb-client.properties in the class path) and the context will be used to lookup EJBs
env.put("jboss.naming.client.ejb.context", true);
InitialContext remoteContext = new InitialContext(env);
RemoteCalculator ejb = (RemoteCalculator)
remoteContext.lookup("wildfly-http-remoting-ejb/CalculatorBean!"
+ RemoteCalculator.class.getName());

The http-remoting client assumes JNDI names in remote lookups are relative to
java:jboss/exported namespace, a lookup of an absolute JNDI name will fail.

JBoss Community Documentation

Page 425 of 617

WildFly 8

ejb:
The ejb: namespace implementation is provided by the jboss-ejb-client library, and allows the lookup of
EJB's using their application name, module name, ejb name and interface type. To use it, you must have the
appropriate jars on the class path, if you are maven user can be done simply by adding the following to your
pom.xml dependencies:

<dependency>
<groupId>org.wildfly</groupId>
<artifactId>wildfly-ejb-client-bom</artifactId>
<version>8.0.0.Final</version>
<type>pom</type>
</dependency>

If you are not using maven a shaded jar that contains all required classes
can be found in the bin/client directory of WildFly's distribution.
This is a client side JNDI implementation. Instead of looking up an EJB on the server the lookup name
contains enough information for the client side library to generate a proxy with the EJB information. When
you invoke a method on this proxy it will use the current EJB client context to perform the invocation. If the
current context does not have a connection to a server with the specified EJB deployed then an error will
occur. Using this protocol it is possible to look up EJB's that do not actually exist, and no error will be thrown
until the proxy is actually used. The exception to this is stateful session beans, which need to connect to a
server when they are created in order to create the session bean instance on the server.

final Properties env = new Properties();
env.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
InitialContext remoteContext = new InitialContext(env);
MyRemoteInterface myRemote = (MyRemoteInterface)
remoteContext.lookup("ejb:myapp/myejbjar/MyEjbName\!com.test.MyRemoteInterface");
MyStatefulRemoteInterface myStatefulRemote = (MyStatefulRemoteInterface)
remoteContext.lookup("ejb:myapp/myejbjar/MyStatefulName\!comp.test.MyStatefulRemoteInterface?stateful");

The first example is a lookup of a singleton, stateless or EJB 2.x home interface. This lookup will not hit the
server, instead a proxy will be generated for the remote interface specified in the name. The second
example is for a stateful session bean, in this case the JNDI lookup will hit the server, in order to tell the
server to create the SFSB session.

For more details on how the server connections are configured, including the required jboss ejb
client setup, please see EJB invocations from a remote client using JNDI.

JBoss Community Documentation

Page 426 of 617

WildFly 8

30 JPA Reference Guide
Introduction
Update your Persistence.xml for Hibernate 4.3.0
Entity manager
Application-managed entity manager
Container-managed entity manager
Persistence Context
Transaction-scoped Persistence Context
Extended Persistence Context
Extended Persistence Context Inheritance
Entities
Deployment
Troubleshooting
Background on the Jipijapa project
Packaging persistence providers with your application and which Jipijapa artifacts to include
Using the Hibernate 4.3.x JPA persistence provider
Using the Infinispan second level cache
Replacing the current Hibernate 4.3.x jars with a newer version
Packaging the Hibernate 3.5 or greater 3.x JPA persistence provider with your application
Sharing the Hibernate 3.5 or greater JPA persistence provider between multiple applications
Using OpenJPA
Using EclipseLink
Using DataNucleus
Using Hibernate OGM
Native Hibernate use
Injection of Hibernate Session and SessionFactoryInjection of Hibernate Session and SessionFactory
Hibernate properties
Persistence unit properties
Determine the persistence provider module
Binding EntityManagerFactory/EntityManager to JNDI
Community
People who have contributed to the WildFly JPA layer:

JBoss Community Documentation

Page 427 of 617

WildFly 8

30.1 Introduction
The WildFly 8 JPA subsystem implements the JPA 2.0 container-managed requirements. Deploys the
persistence unit definitions, the persistence unit/context annotations and persistence unit/context references
in the deployment descriptor. JPA Applications use the Hibernate (core) 4.0 persistence provider, that is
included with WildFly. The JPA subsystem uses the standard SPI
(javax.persistence.spi.PersistenceProvider) to access the Hibernate persistence provider and some
additional extensions as well.
During application deployment, JPA use is detected (e.g. persistence.xml or @PersistenceContext/Unit
annotations) and injects Hibernate dependencies into the application deployment. This makes it easy to
deploy JPA applications.
In the remainder of this documentation, ”entity manager” refers to an instance of the
javax.persistence.EntityManager class. Javadoc for the JPA interfaces
http://download.oracle.com/javaee/6/api/javax/persistence/package-summary.html and JPA 2.0 specification.
The index of Hibernate documentationis here.

30.2 Update your Persistence.xml for Hibernate 4.3.0
The persistence provider class name in Hibernate 4.3.0 is
org.hibernate.jpa.HibernatePersistenceProvider.
Instead of specifying:
<provider>org.hibernate.ejb.HibernatePersistence</provider>
Switch to*:*
<provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
Or remove the persistence provider class name from your persistence.xml (so the default provider will be
used).

30.3 Entity manager
The entity manager is similar to the Hibernate Session class; applications use it to create/read/update/delete
data (and related operations). Applications can use application-managed or container-managed entity
managers. Keep in mind that the entity manager is not expected to be thread safe (don't inject it into a
servlet class variable which is visible to multiple threads).

JBoss Community Documentation

Page 428 of 617

WildFly 8

30.4 Application-managed entity manager
Application-managed entity managers provide direct access to the underlying persistence provider
(org.hibernate.ejb.HibernatePersistence). The scope of the application-managed entity manager is from
when the application creates it and lasts until the app closes it. Use the @PersistenceUnit annotation to
inject a persistence unit into a javax.persistence.EntityManagerFactory. The EntityManagerFactory can
return an application-managed entity manager.

30.5 Container-managed entity manager
Container-managed entity managers auto-magically manage the underlying persistence provider for the
application. Container-managed entity managers may use transaction-scoped persistence contexts or
extended persistence contexts. The container-managed entity manager will create instances of the
underlying persistence provider as needed. Every time that a new underlying persistence provider (
org.hibernate.ejb.HibernatePersistence) instance is created, a new persistence context is also created (as
an implementation detail of the underlying persistence provider).

30.6 Persistence Context
The JPA persistence context contains the entities managed by the persistence provider. The persistence
context acts like a first level (transactional) cache for interacting with the datasource. Loaded entities are
placed into the persistence context before being returned to the application. Entities changes are also placed
into the persistence context (to be saved in the database when the transaction commits).

JBoss Community Documentation

Page 429 of 617

WildFly 8

30.7 Transaction-scoped Persistence Context
The transaction-scoped persistence context coordinates with the (active) JTA transaction. When the
transaction commits, the persistence context is flushed to the datasource (entity objects are detached but
may still be referenced by application code). All entity changes that are expected to be saved to the
datasource, must be made during a transaction. Entities read outside of a transaction will be detached when
the entity manager invocation completes. Example transaction-scoped persistence context is below.

@Stateful // will use container managed transactions
public class CustomerManager {
@PersistenceContext(unitName = "customerPU") // default type is
PersistenceContextType.TRANSACTION
EntityManager em;
public customer createCustomer(String name, String address) {
Customer customer = new Customer(name, address);
em.persist(customer); // persist new Customer when JTA transaction completes (when method
ends).
// internally:
//
1. Look for existing "customerPU" persistence context in active
JTA transaction and use if found.
//
2. Else create new "customerPU" persistence context (e.g.
instance of org.hibernate.ejb.HibernatePersistence)
//
and put in current active JTA transaction.
return customer;
// return Customer entity (will be detached from the persistence
context when caller gets control)
} // Transaction.commit will be called, Customer entity will be persisted to the database and
"customerPU" persistence context closed

30.8 Extended Persistence Context
The (ee container managed) extended persistence context can span multiple transactions and allows data
modifications to be queued up (like a shopping cart), without an active JTA transaction (to be applied during
the next JTA TX). The Container-managed extended persistence context can only be injected into a stateful
session bean.

@PersistenceContext(type = PersistenceContextType.EXTENDED, unitName = "inventoryPU")
EntityManager em;

JBoss Community Documentation

Page 430 of 617

WildFly 8

30.8.1 Extended Persistence Context Inheritance
JPA 2.0 specification section 7.6.2.1
If a stateful session bean instantiates a stateful session bean (executing in the same EJB
container instance) which also has such an extended persistence context, the extended
persistence context of the first stateful session bean is inherited by the second stateful
session bean and bound to it, and this rule recursively applies—independently of whether
transactions are active or not at the point of the creation of the stateful session beans.

By default, the current stateful session bean being created, will ( deeply) inherit the extended persistence
context from any stateful session bean executing in the current Java thread. The deep inheritance of
extended persistence context includes walking multiple levels up the stateful bean call stack (inheriting from
parent beans). The deep inheritance of extended persistence context includes sibling beans. For example,
parentA references child beans beanBwithXPC & beanCwithXPC. Even though parentA doesn't have an
extended persistence context, beanBwithXPC & beanCwithXPC will share the same extended persistence
context.
Some other EE application servers, use shallow inheritance, where stateful session bean only inherit from
the parent stateful session bean (if there is a parent bean). Sibling beans do not share the same extended
persistence context unless their (common) parent bean also has the same extended persistence context.
Applications can include a (top-level) jboss-all.xml deployment descriptor that specifies either the (default)
DEEP extended persistence context inheritance or SHALLOW.
The AS/docs/schema/jboss-jpa_1_0.xsd describes the jboss-jpa deployment descriptor that may be
included in the jboss-all.xml. Below is an example of using SHALLOW extended persistence context
inheritance:
<jboss>
<jboss-jpa xmlns="http://www.jboss.com/xml/ns/javaee">
<extended-persistence inheritance="SHALLOW"/>
</jboss-jpa>
</jboss>
Below is an example of using DEEP extended persistence inheritance:
<jboss>
<jboss-jpa xmlns="http://www.jboss.com/xml/ns/javaee">
<extended-persistence inheritance="DEEP"/>
</jboss-jpa>
</jboss>

JBoss Community Documentation

Page 431 of 617

WildFly 8
The AS console/cli can change the default extended persistence context setting (DEEP or SHALLOW). The
following cli commands will read the current JPA settings and enable SHALLOW extended persistence
context inheritance for applications that do not include the jboss-jpa deployment descriptor:
./jboss-cli.sh
cd subsystem=jpa
:read-resource
:write-attribute(name=default-extended-persistence-inheritance,value="SHALLOW")

30.9 Entities
JPA 2.0 makes it easy to use your (pojo) plain old Java class to represent a database table row.

@PersistenceContext EntityManager em;
Integer bomPk = getIndexKeyValue();
BillOfMaterials bom = em.find(BillOfMaterials.class, bomPk); // read existing table row into
BillOfMaterials class
BillOfMaterials createdBom = new BillOfMaterials("...");
// create new entity
em.persist(createdBom); // createdBom is now managed and will be saved to database when the
current JTA transaction completes

The entity lifecycle is managed by the underlying persistence provider.
New (transient): an entity is new if it has just been instantiated using the new operator, and it is not
associated with a persistence context. It has no persistent representation in the database and no
identifier value has been assigned.
Managed (persistent): a managed entity instance is an instance with a persistent identity that is
currently associated with a persistence context.
Detached: the entity instance is an instance with a persistent identity that is no longer associated with
a persistence context, usually because the persistence context was closed or the instance was
evicted from the context.
Removed: a removed entity instance is an instance with a persistent identity, associated with a
persistence context, but scheduled for removal from the database.

JBoss Community Documentation

Page 432 of 617

WildFly 8

30.10 Deployment
The persistence.xml contains the persistence unit configuration (e.g. datasource name) and as described in
the JPA 2.0 spec (section 8.2), the jar file or directory whose META-INF directory contains the
persistence.xml file is termed the root of the persistence unit. In Java EE environments, the root of a
persistence unit must be one of the following (quoted directly from the JPA 2.0 specification):
"
an EJB-JAR file
the WEB-INF/classes directory of a WAR file
a jar file in the WEB-INF/lib directory of a WAR file
a jar file in the EAR library directory
an application client jar file
The persistence.xml can specify either a JTA datasource or a non-JTA datasource. The JTA datasource is
expected to be used within the EE environment (even when reading data without an active transaction). If a
datasource is not specified, the default-datasource will instead be used (must be configured).
NOTE: Java Persistence 1.0 supported use of a jar file in the root of the EAR as the root of a persistence
unit. This use is no longer supported. Portable applications should use the EAR library directory for this case
instead.
"
Question: Can you have a EAR/META-INF/persistence.xml?
Answer: No, the above may deploy but it could include other archives also in the EAR, so you may have
deployment issues for other reasons. Better to put the persistence.xml in an EAR/lib/somePuJar.jar.

30.11 Troubleshooting
The org.jboss.as.jpa logging can be enabled to get the following information:
INFO - when persistence.xml has been parsed, starting of persistence unit service (per deployed
persistence.xml), stopping of persistence unit service
DEBUG - informs about entity managers being injected, creating/reusing transaction scoped entity
manager for active transaction
TRACE - shows how long each entity manager operation took in milliseconds, application searches
for a persistence unit, parsing of persistence.xml
To enable TRACE, open the as/standalone/configuration/standalone.xml (or
as/domain/configuration/domain.xml) file. Search for <subsystem
xmlns="urn:jboss:domain:logging:1.0"> and add the org.jboss.as.jpa category. You need to change
the console-handler level from INFO to TRACE.

JBoss Community Documentation

Page 433 of 617

WildFly 8

<subsystem xmlns="urn:jboss:domain:logging:1.0">
<console-handler name="CONSOLE">
<level name="TRACE" />
...
</console-handler>
</periodic-rotating-file-handler>
<logger category="com.arjuna">
<level name="WARN" />
</logger>
<logger category="org.jboss.as.jpa">
<level name="TRACE" />
</logger>
<logger category="org.apache.tomcat.util.modeler">
<level name="WARN" />
</logger>
...

To see what is going on at the JDBC level, enable jboss.jdbc.spy TRACE and add spy="true" to the
datasource.

<datasource jndi-name="java:jboss/datasources/..." pool-name="..." enabled="true" spy="true">
<logger category="jboss.jdbc.spy">
<level name="TRACE"/>
</logger>

To troubleshoot issues with the Hibernate second level cache, try enabling trace for org.hibernate.SQL +
org.hibernate.cache.infinispan + org.infinispan:

JBoss Community Documentation

Page 434 of 617

WildFly 8

<subsystem xmlns="urn:jboss:domain:logging:1.0">
<console-handler name="CONSOLE">
<level name="TRACE" />
...
</console-handler>
</periodic-rotating-file-handler>
<logger category="com.arjuna">
<level name="WARN" />
</logger>
<logger category="org.hibernate.SQL">
<level name="TRACE" />
</logger>
<logger category="org.hibernate">
<level name="TRACE" />
</logger>
<logger category="org.infinispan">
<level name="TRACE" />
</logger>
<logger category="org.apache.tomcat.util.modeler">
<level name="WARN" />
</logger>
...

30.12 Background on the Jipijapa project
The Jipijapa project goal is to improve application platform integration with JPA persistence providers.
Jipijapa provides additional integration that makes it easier to use various persistence providers. For
example, look here at how the Hibernate environment is setup automatically (so that JPA deployments can
just work). Also, application persistence unit definitions (persistence.xml) can override most settings.

JBoss Community Documentation

Page 435 of 617

WildFly 8

30.13 Packaging persistence providers with your
application and which Jipijapa artifacts to include
Applications that include a copy of a persistence provider, should include one of the following Jipijapa
integration jars, so that WildFly can easily deploy your application. The alternative to including persistence
providers with your application, is to instead use the persistence provider as a static module (each of the
below providers already have a placeholder static module that you can copy provider jars into).
Persistence Provider

WildFly Version Group ID

Artifact ID

Version

Hibernate ORM 4.3.x

8.1.0.Final

org.jipijapa jipijapa-hibernate4-3 1.1.0.Final

Hibernate ORM 4.0.x, 4.1.x, 4.2.x 8.1.0.Final

org.jipijapa jipijapa-hibernate4-1 1.1.0.Final

Hibernate ORM version 3.x

8.1.0.Final

org.jipijapa jipijapa-hibernate3

1.1.0.Final

EclipseLink

8.1.0.Final

org.jipijapa jipijapa-eclipselink

1.1.0.Final

OpenJPA

8.1.0.Final

org.jipijapa jipijapa-openjpa

1.1.0.Final

30.14 Using the Hibernate 4.3.x JPA persistence
provider
Hibernate 4.3.x is packaged with WildFly and is the default persistence provider.

JBoss Community Documentation

Page 436 of 617

manager_lookup_class" value="org. just set the hibernate.container persistence property.use_second_level_cache" value="true"/> </properties> </persistence-unit> </persistence> Here is an example of enabling the second level cache for a Hibernate native API hibernate.cache.hibernate Infinispan Hibernate/JPA second level cache provider documentation contains advanced configuration information but you should bear in mind that when Hibernate runs within WildFly 8.region. JBoss Community Documentation Page 437 of 617 .jpa.sun.infinispan.MF: Dependencies: org. some of those configuration options.hibernate. are not needed.cache.JBossTransactionManagerLookup"/> <property name="hibernate.transaction.cfg. By default the application server uses Infinispan as the cache provider for JPA applications.hibernate4.cache. this property is not mandatory and a default container is already deployed for by the application server to host the second level cache.0" encoding="UTF-8"?><persistence xmlns="http://java.factory_class" value="org.use_second_level_cache property to true.infinispan. so you don't need specify anything on top of that: <?xml version="1.jboss. Moreover. as is done in the following example (also set the shared-cache-mode accordingly).as. such as region factory.transaction.infinispan. To reiterate.InfinispanRegionFactory"/> <property name="hibernate.org. the application server providers you with option of selecting a different cache container for Infinispan via hibernate.cachemanager" value="java:jboss/infinispan/container/hibernate"/> <property name="hibernate.xml file: <property name="hibernate.cache.cache.0"> <persistence-unit name="2lc_example_pu"> <description>example of enabling the second level cache.</description> <jta-data-source>java:jboss/datasources/mydatasource</jta-data-source> <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode> <properties> <property name="hibernate.15 Using the Infinispan second level cache To enable the second level cache with Hibernate 4.WildFly 8 30.com/xml/ns/persistence" version="1.use_second_level_cache" value="true"/> The Hibernate native API application will also need a MANIFEST.cache.infinispan.

providerModule needs to be set to hibernate3-bundled. Remove the older jars and copy new Hibernate jars into wildfly/modules/system/layers/base/org/hibernate/main + wildfly/modules/system/layers/base/org/hibernate/envers/main.3.jpa. 3.6. JBoss Community Documentation Page 438 of 617 . Update the wildfly/modules/system/layers/base/org/hibernate/main/module.x JPA persistence provider with your application WildFly 8 allows the packaging of Hibernate 3. 4. <?xml version="1. Backup the current contents of wildfly/modules/system/layers/base/org/hibernate in case you make a mistake. 2.17 Packaging the Hibernate 3.</description> <jta-data-source>java:jboss/datasources/PlannerDS</jta-data-source> <properties> <property name="hibernate.jpa.0"> <persistence-unit name="plannerdatasource_pu"> <description>Hibernate 3 Persistence Unit.0" encoding="UTF-8"?> <persistence xmlns="http://java.WildFly 8 30.5 (or greater) persistence provider jars with the application.xml to name the jars that you copied in. 1.16 Replacing the current Hibernate 4. 30.index files in wildfly/modules/system/layers/base/org/hibernate/main and wildfly/modules/system/layers/base/org/hibernate/envers/main folders.5. The JPA deployer will detect the presence of a persistence provider in the application and jboss.xml + wildfly/modules/system/layers/base/org/hibernate/envers/main/module.show_sql" value="false" /> <property name="jboss.com/xml/ns/persistence" version="1.5 or greater 3.Final jars in the ear lib.as. Delete *.sun.x jars with a newer version Just update the current wildfly/modules/system/layers/base/org/hibernate/main folder to contain the newer version (after stopping your WildFly server instance).as.providerModule" value="hibernate3-bundled" /> </properties> </persistence-unit> </persistence> The WildFly testsuite contains a test that packages jars from the Hibernate 3.

1" name="org.jboss. hibernate3-entitymanager.1.api"/> <module name="javax.jboss.annotation.slf4j"/> <module name="org.api"/> <module name="javax.logging"/> <module name="org. cd WF\modules\modules\system\layers\base\org\hibernate\3 2. In a command shell.collections"/> <module name="org. Copy the Hibernate3 jars into this folder (hibernate3-core.jar needed for Hibernate 3.antlr"/> <module name="org. go to the AS installation and change into the modules/org folder.Final.xml. you will refer to the Hibernate 3 persistence provider as follows: JBoss Community Documentation Page 439 of 617 .xml.jar"/> <resource-root path="hibernate3-entitymanager.api"/> <module name="org.Represents the Hibernate 3.18 Sharing the Hibernate 3.jar"/> <resource-root path="hibernate3-commons-annotations.jar. hibernate3-commons-annotations.enterprise. In your persistence. Update the module.persistence. Steps to create the Hibernate3 module: 1.spi"/> <module name="org.as.bind. 3.api"/> <module name="javax.apache.jar"/> </resources> --> <dependencies> <module name="asm.dom4j"/> <module name="org.jar.5 or greater) persistence provider by manually creating an org.javassist"/> <module name="org.jpa.WildFly 8 30.transaction.hibernate:3 module (in the AS/modules folder).commons.api"/> <module name="javax.jar"/> <resource-root path="hibernate3-core.jandex"/> <module name="org.jboss.asm"/> <module name="javax.jboss.0.x).validation.api"/> <module name="javax.xml file to name each jar you copied in as a "resource-root": <?xml version="1.vfs"/> </dependencies> </module> 1.0" encoding="UTF-8"?><!-.hibernate" slot="3"> <resources> <resource-root path="jipijapa-hibernate3-1.x module <module xmlns="urn:jboss:module:1.5 or greater JPA persistence provider between multiple applications Applications can share the same Hibernate3 (for Hibernate 3.api"/> <module name="javax.

WildFly 8 <?xml version="1.0" encoding="UTF-8"?> <persistence xmlns="http://java.commons.jar serp.1" name="org.collections"/> <module name="org.enterprise.bind.ejb.jboss.api"/> <module name="javax.19 Using OpenJPA You need to copy the OpenJPA jars (e.apache.api"/> <module name="javax.apache.validation.api"/> <module name="javax.jandex"/> </dependencies> </module> JBoss Community Documentation Page 440 of 617 .g.hibernate.api"/> <module name="javax.logging"/> <module name="org.jar"/> <resource-root path="serp.as. openjpa-all.jar"/> <resource-root path="openjpa-all.lang"/> <module name="org.openjpa"> <resources> <resource-root path="jipijapa-openjpa-1.jboss.sun.api"/> <module name="javax.xml to include the same jar file names that you copied in.as.jpa.0.</description> <provider>org.jpa.HibernatePersistence</provider> <jta-data-source>java:jboss/datasources/CRMDS</jta-data-source> <properties> <property name="jboss.jar"/> </resources> <dependencies> <module name="javax.1.api"/> <module name="org.commons.xml.0"> <persistence-unit name="crm_pu"> <description>CRM Persistence Unit.transaction.vfs"/> <module name="org.com/xml/ns/persistence" version="1.hibernate:3" /> </properties> </persistence-unit> </persistence> 30.jar) into the WildFly modules/system/layers/base/org/apache/openjpa/main folder and update modules/system/layers/base/org/apache/openjpa/main/module.spi"/> <module name="org.apache.jboss.jboss.Final.annotation. <module xmlns="urn:jboss:module:1.persistence.providerModule" value="org.api"/> <module name="javax.

api"/> <module name="javax.jar"/> </resources> <dependencies> <module name="asm. eclipselink-2.api"/> <module name="javax.factory" to value "org.xml (or your WildFly configuration you are using) file might look like after updating the system properties: JBoss Community Documentation Page 441 of 617 .1. the module.sh --connect '/system-property=eclipselink.eclipselink. If you happen to leave the EclipseLink version number in the jar name.jar as in the example below) into the WildFly modules/system/layers/base/org/eclipse/persistence/main folder and update modules/system/layers/base/org/eclipse/persistence/main/module.eclipselink.xml.jboss.persistence.api"/> <module name="javax.as. The following shows what the standalone.jar"/> <resource-root path="eclipselink.1.bind.logging"/> <module name="org.enterprise.jboss.xml to include the EclipseLink jar (take care to use the jar name that you copied in).eclipse.jboss.api"/> <module name="javax.api"/> <module name="javax.transaction.1" name="org.jar or eclipselink.api"/> <module name="org.jipijapa.collections"/> <module name="org.jpa.archive.commons.api"/> <module name="javax.sh command (WildFly server needs to be running when this command is issued): jboss-cli.antlr"/> <module name="org.WildFly 8 30.dom4j"/> <module name="org. <module xmlns="urn:jboss:module:1.validation.JBossArchiveFactoryImpl)' .factory:add(value=org.annotation.apache.5.20 Using EclipseLink You need to copy the EclipseLink jar (e. set (WildFly) system property "eclipselink.javassist"/> <module name="org.persistence"> <resources> <resource-root path="jipijapa-eclipselink-1.jipijapa.Final.spi"/> <module name="org.jms.g.xml should reflect that.asm"/> <module name="javax.0.JBossArchiveFactoryImpl" via jboss-cli.vfs"/> </dependencies> </module> As a workaround for issueid=414974.api"/> <module name="javax.archive.

archive. Example persistence.hibernate.lang. One may encounter following exception (found on WildFly 8. 30.xml: <module name="javax.jboss.JBossArchiveFactoryImpl"/> </system-properties> You should then be able to deploy applications with persistence.jipijapa...classtransformer" value="false" /> <property name="jboss.ext.as. <provider>org.xml: <?xml version="1.rs.as.rs.1.api"/> 30.jpa.ws.0" encoding="UTF-8"?> <persistence xmlns="http://java.jpa.adapterModule" value="org.PersistenceProvider</provider> Also refer to page how to use EclipseLink with WildFly guide here.eclipse.eclipselink.ogm.jpa.hibernate:4"/> </properties> </persistence-unit> </persistence> JBoss Community Documentation Page 442 of 617 .as.persistence:main" from local module loader.22 Using Hibernate OGM This section is a work in progress.persistence.factory" value="org.WildFly 8 <system-properties> .xml that include.jpa.ExceptionMapper from [Module "org.sun. Problem can be solved by adding missing module dependency into modules/system/layers/base/org/eclipse/persistence/main/module.. <property name="eclipselink.ClassNotFoundException: javax.eclipse.jpa.2): Caused by: java.0 with EclipseLink 2.HibernateOgmPersistence</provider> <properties> <property name="jboss..0"> <persistence-unit name="MINIMAL"> <provider>org.com/xml/ns/persistence" version="1.ws.5.21 Using DataNucleus Read the how to use DataNucleus with WildFly guide here.

commons-annotations"/> </dependencies> </module> The AS7/modules/org/hibernate/ogm folder should contain the OGM jars and the following module.hibernate" slot="4" optional="true"/> <module name="org.jpa.6.api"/> <module name="javax.validation.dom4j"/> <module name="org.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.Insert resources here --> </resources> <dependencies> <module name="javax.as.0-SNAPSHOT.jboss.persistence.persistence.commons-annotations"/> <module name="org.jboss.Insert resources here --> </resources> <dependencies> <module name="asm.hibernate.Final.api"/> <module name="org. Change AS7/modules/org/hibernate/main/module.javassist"/> <module name="org.jboss.hibernate" slot="4" optional="true"/> <module name="org.infinispan" optional="true"/> <module name="org.api"/> <module name="javax.api"/> <module name="org.jar"/> <!-.1.api"/> <module name="javax.envers" services="import" optional="true"/> <module name="org.hibernate" slot="ogm"> <resources> <resource-root path="hibernate-ogm-core-4.jar"/> <resource-root path="hibernate-entitymanager-4.asm"/> <module name="javax.validation.jar"/> <!-.commons.collections"/> <module name="org.1" name="org.as.jar"/> <resource-root path="hibernate-infinispan-4.api"/> <module name="javax.hibernate.jboss.Final.1.1.hibernate" export="true"/> </dependencies> </module> JBoss Community Documentation Page 443 of 617 .xml to: <?xml version="1.api"/> <module name="javax.0.logging"/> <module name="org.apache.hibernate.WildFly 8 The Hibernate ORM module needs to depend on OGM.0-SNAPSHOT.1" name="org.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.transaction.api"/> <module name="javax.jpa.dom4j"/> <module name="org.antlr"/> <module name="org.hibernate"> <resources> <resource-root path="hibernate-core-4.xml: <?xml version="1.hibernate" slot="ogm" services="import"/> <module name="org.transaction.6.6.Final.infinispan" optional="true"/> <module name="org.0.logging"/> <module name="org.jar"/> <resource-root path="hibernate-ogm-infinispan-4.

Meaning that JPA applications. @Stateful public class MyStatefulBean . Example MANIFEST. Native Hibernate applications. Dependencies: org.0 .. import org..SessionFactory directly.x) properties (if not already set in persistence unit definition): JBoss Community Documentation Page 444 of 617 .WildFly 8 30. just as you can do with EntityManagers and EntityManagerFactorys. type=EXTENDED) Session extendedpc.Session and org.SessionFactory.g.hibernate. are referred to here as native Hibernate applications.saveOrUpdate(entity) is different than EntityManager..25 Hibernate properties WildFly automatically sets the following Hibernate (4. @PersistenceUnit(unitName="crm") SessionFactory factory. import org.MF entry to add Hibernate dependency: Manifest-Version: 1.merge(entity). @PersistenceContext(unitName="crm2".24 Injection of Hibernate Session and SessionFactoryInjection of Hibernate Session and SessionFactory You can inject a org. Applications that utilize JPA will automatically have the JBoss AS Hibernate injected onto the application deployment classpath. you could get surprising results (e. 30. } 30.hibernate.hibernate. { @PersistenceContext(unitName="crm") Session session1. HibernateSession.hibernate If you use the Hibernate native api in your application and also use the JPA api to access the same entities (from the same Hibernate session/EntityManager).23 Native Hibernate use Applications that use the Hibernate API directly. can choose to use the Hibernate jars included with WildFly 8 or they can package their own copy of the Hibernate jars. should expect to use the Hibernate jars included in WildFly. Each entity should be managed by either Hibernate native API or JPA code..Session.hibernate.

entitymanager_factory_name Is set to the application name + persistence unit name = qualified persistence unit name (application can specify a different value but it needs to be unique across all application deployments on the AS instance).hibernate.SequenceStyleGenerator In Hibernate 4.id.spi.x.transaction.hibernate. hibernate.ejb.service.x.SequenceStyleGenerator @GeneratedValue(TABLE) maps to org.platform= instance The transaction manager.xml (could conflict with JtaPlatform) hibernate.ejb.id.xml).enhanced.session_factory_name_is_jndi = only set if the application didn't specify a value for false hibernate.hibernate. if new_generator_mappings is false: @GeneratedValue(AUTO) maps to Hibernate "native" @GeneratedValue(TABLE) maps to org.WildFly 8 Property Purpose hibernate. hibernate.enhanced.jta.manager_lookup_class This property is removed if found in the persistence.hibernate.jta.Scanner interface knows how to use the AS annotation indexer (for faster deployment).platform.ejb. The application can override this value (in the persistence.new_generator_mappings =true New applications should let this default to true.hibernate. In Hibernate 4. user transaction and of transaction synchronization registry is passed into org.session_factory_name = qualified Is set to the application name + persistence unit name persistence unit name (application can specify a different value but it needs to be unique across all application deployments on the AS instance). if new_generator_mappings is true: @GeneratedValue(AUTO) maps to org. hibernate.enhanced.TableGenerator @GeneratedValue(SEQUENCE) maps to org.id. hibernate.resource_scanner = instance of Instance of entity scanning class is passed in that org.transaction. older applications with existing data might need to set to false (see note below). It really depends on whether your application uses the @GeneratedValue(AUTO) which will generates new key values for newly created entities.id.MultipleHiLoPerTableGenerator @GeneratedValue(SEQUENCE) to Hibernate "seqhilo" JBoss Community Documentation Page 445 of 617 .hibernate.JtaPlatform Hibernate via this class.id. interface hibernate.session_factory_name.packaging.

xml file): JBoss Community Documentation Page 446 of 617 .WildFly 8 30.26 Persistence unit properties The following properties are supported in the persistence unit definition (in the persistence.

jpa. allow a two phase persistence unit bootstrap.twophasebootstrap hint to false.jboss.as.hibernate:4 (Hibernate 4 integration classes) and org.as. wildfly.twophasebootstrap persistence providers (like Hibernate ORM 4.hibernate).jpa. Hibernate also needs persistence unit property hibernate. This is useful if you inject a persistence context without specifying the unitName (@PersistenceContext EntityManager em) but have multiple persistence units specified in your persistence.as.hibernate4. This is only important for persistence units that do not specify a datasource.jpa.as. jboss. Current valid values are org.as. if a persistence provider is packaged with the application.classtransformer set to false to disable class transformers for the persistence unit.x via EntityManagerFactoryBuilder).allowdefaultdatasourceuse set to false to prevent persistence unit from using the default data source. JBoss Community Documentation Page 447 of 617 . The default is true. The default is true.jpa.ejb.hibernate:3 (Hibernate 3 integration classes).jpa. disables the two phase bootstrap (for the persistence unit that contains the hint).providerModule name of the persistence provider module (default is org.xml.jboss.x + Spring applications. wildfly. Other integration adapter modules are expected to be added. Current valid values are org.jboss.jpa.adapterClass class name of the integration adapter.hibernate3. This is typically set to false for Seam 2. Setting the wildfly. which allows class enhancing/rewriting.jpa. wildfly. jboss.adapterModule name of the integration classes that help WildFly to work with the persistence provider.jpa.as.default-unit set to true to choose the default persistence unit in an application.as. Should be hibernate3-bundled if Hibernate 3 jars are in the application archive (adapterModule and adapterClass will automatically be set for hibernate3-bundled).jpa.use_class_enhancer to be true.WildFly 8 Property Purpose jboss.jpa.HibernatePersistenceProviderAdaptor . Should be application . jboss. jboss.jpa. See note below about some module names that are built in (based on the provider). which enables container managed JPA access to the persistence unit.jpa. for class enhancing to be enabled.managed set to false to disable container managed JPA access to the persistence unit.as. Defaults to true.as. which improves JPA integration with CDI.jpa.HibernatePersistenceProviderAdaptor and org.jboss.3.

DatastorePersistenceProvider org.persistence.essentials.providerModule property is not specified.xml.openjpa.api.as.HibernatePersistence org. the provider module name is determined by the provider name specified in the persistence.ejb.persistence.persistence org. The mapping is: Provider Name Module name blank org.ogm.toplink oracle.appengine.PersistenceProviderImpl JBoss Community Documentation org.eclipse.EntityManagerFactoryProvider oracle.datanucleus org.eclipse.WildFly 8 30.PersistenceProvider org.jpa.store.27 Determine the persistence provider module As mentioned above.ejb.jpa.HibernateOgmPersistence org.hibernate org.openjpa Page 448 of 617 .apache.hibernate.cmp3.hibernate:ogm oracle.datanucleus:appengine org.jpa.hibernate org.PersistenceProviderImpl org.PersistenceProvider oracle.toplink.apache.toplink org.datanucleus.toplink.essentials. if the jboss.jpa.jpa.datanucleus.hibernate.

you can explicitly configure this in the persistence.jndi.WildFly 8 30.entity.entity.0" xmlns="http://java.setName(name).name{}{{.sun.com/xml/ns/persistence" xmlns:xsi="http://www.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://java. } } JBoss Community Documentation Page 449 of 617 . entityManager.0" encoding="UTF-8"?> <persistence version="2.sun.EntityManager entityManager = (javax.sun.manager.Bind entity manager factory to JNDI at java:jboss/myEntityManagerFactory --> <property name="jboss.jndi. You can also bind a container managed (transaction scoped) entity manager to JNDI as well.manager.name" value="java:/myEntityManager"/> </properties> </persistence-unit> </persistence> @Stateful public class ExampleSFSB { public void createSomeEntityWithTransactionScopedEM(String name) { Context context = new InitialContext().28 Binding EntityManagerFactory/EntityManager to JNDI By default WildFly does not bind the entity manager factory to JNDI.persistence. }}via hint jboss.w3. add a managed data source.xml <?xml version="1.name" value="java:jboss/myEntityManagerFactory" /> <property name="jboss.factory.jndi. someEntity.If you are running in a production environment.manager.entity.factory.jndi. acts as a proxy that always gets an unique underlying entity manager (at the persistence provider level).persist(name). SomeEntity someEntity = new SomeEntity(). The value of that property should be the JNDI name to which the entity manager factory should be bound.entity.name hint. However.EntityManager) context. As a reminder.persistence.com/xml/ns/persistence http://java.xsd"> <persistence-unit name="myPU"> <!-.xml of your application by setting the jboss. a transaction scoped entity manager (persistence context). the example data source is just for proofs of concept! --> <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source> <properties> <!-.manager.com/xml/ns/persistence/persistence_2_0. Here's an example: persistence.lookup("java:/myEntityManager"). javax.

For those of you that haven't downloaded the AS source code and started hacking patches together. I would like to encourage you to start by reading Hacking on WildFly. The following list of contributors should grow over time. for reporting issues. Also. I hope to see more of you listed here. is the JipiJapa project that contains additional integration code that makes EE JPA application deployments work better.29.29 Community Many thanks to the community. You will find that it easy very easy to find your way around the WildFly/JPA/* source tree and make changes.1 People who have contributed to the WildFly JPA layer: Carlo de Wolf (lead of the EJB3 project) Steve Ebersole (lead of the Hibernate ORM project) Stuart Douglas (lead of the Seam Persistence project. WildFly project team member/committer) Jaikiran Pai (Active member of JBoss forums and JBoss EJB3 project team member) Strong Liu (leads the productization effort of Hibernate in the EAP product) Scott Marlow (lead of the WildFly container JPA sub-project) Antti Laisi (OpenJPA integration changes) Galder Zamarreño (Infinispan 2lc documentation) Sanne Grinovero (Infinispan 2lc documentation) Paul Ferraro (Infinispan 2lc integration) JBoss Community Documentation Page 450 of 617 . solutions and code changes.WildFly 8 30. I would like to thank them for this. new for WildFly. 30. as well as those reporting issues. A number of people have been answering Wildfly forum questions related to JPA usage.

WildFly 8 31 OSGi WildFly does not include support for OSGi. JBoss Community Documentation Page 451 of 617 . such functionality is now responsibility of JBoss OSGi project.

} JBoss Community Documentation Page 452 of 617 . the JNP project is not used.WildFly 8 32 Remote EJB invocations via JNDI ..2 History Previous versions of JBoss AS (versions < WildFly 8) used JNP project ( http://anonsvn. 32. . There were various reasons why the JNP client was replaced by jboss-remote-naming project.3.EJB client API or remote-naming project 32. Starting WildFly 8. Developers of client applications of previous versions of JBoss AS will be familiar with the jnp:// PROVIDER_URL URL they used to use in their applications for communicating with the JNDI server on the JBoss server.lookup("foo/bar"). One of them was the JNP project did not allow fine grained security configurations while communicating with the JNDI server.org/repos/jbossas/projects/naming/) as the JNDI naming implementation. Neither on the server side nor on the client side. 32. The jboss-remote-naming project is backed by the jboss-remoting project (https://github.naming.properties in classpath void doLookup() { // Create an InitialContext using the javax.1 Client code relying on jndi. 32. The client side of the JNP project has now been replaced by jboss-remote-naming project ( https://github.jboss.* API Context ctx = new InitialContext().com/jbossas/jboss-remote-naming).com/jboss-remoting/jboss-remoting) which allows much more and better control over security. This article explains which approach to use when and what the differences and scope of each of these projects is. let's quickly see what the code looks like. ctx.1 Purpose WildFly provides EJB client API project as well as remote-naming project for invoking on remote objects exposed via JNDI..3 Overview Now that we know that for remote client JNDI communication with WildFly 8 requires jboss-remote-naming project.

"org.InitialContextFactory java.put(Context. We'll see what our jndi.provider. We'll come back to the details of this lookup string in a while. the URI protocol scheme for jboss-remote-naming project is remote://. JNP client project in previous AS versions allowed a comma separated list for PROVIDER_URL value. WildFly 8 can use the PROVIDER_URL like: java.jboss.client. Once the InitialContext is created.url=http-remoting://server1:8080. The other property is the PROVIDER_URL.properties file. // lookup ctx.PROVIDER_URL. so that if one of the server isn't accessible then the JNDI API would use the next available server.INITIAL_CONTEXT_FACTORY.client."http-remoting://localhost:8080"). we just use it to do a lookup on a JNDI name which we know is bound on the server side. The rest of the PROVIDER_URL part is the server hostname or IP and the port on which the remoting connector is exposed on the server side.factory.com/javase/6/docs/api/javax/naming/InitialContext. In WildFly. later. there's not much here in terms of code. . Let's now see what the jndi. The jboss-remote-naming project has similar support starting 1.naming.lookup("foo/bar"). We first create a InitialContext ( http://download.. jndiProps.properties in our client classpath looks like: java.html) which as per the API will look for a jndi. jndiProps.1.naming.. } JBoss Community Documentation Page 453 of 617 .remote.oracle.InitialContextFactory"). Developers familiar with previous JBoss AS versions would remember that they used jnp://localhost:1099 (just an example).Final version of that project (which is available in a WildFly release after 7.put(Context.1.3.WildFly 8 As you can see.0. The first property tells the JNDI API which initial context factory to use. That's what we have used in our example.Final).http-remoting://server2:8080 So we saw how to setup the JNDI properties in the jndi. The JNDI API also allows you to pass these properties to the constructor of the InitialContext class (please check the javadoc of that class for more details).initial=org. By default the http-remoting connector port in WildFly 8 is 8080.naming.url=http-remoting://localhost:8080 Those 2 properties are important for jboss-remote-naming project to be used for communicating with the WildFly server. // create a context passing these properties Context ctx = new InitialContext(jndiProps).provider. In this case we are pointing it to the InitailContextFactory class supplied by the jboss-remote-naming project. The hostname we have used is localhost but that should point to the server IP or hostname where the server is running.naming.properties in the classpath of the application.remote.jboss.properties looks like.naming. Let's quickly see what the code would look like: void doLookup() { Properties jndiProps = new Properties().

2 How does remoting naming work We have so far had an overview of how the client code looks like when using the jboss-remote-naming (henceforth referred to as remote-naming .3.remote. is out of the scope of this documentation. the org.properties. Starting WildFly 8. remote-naming internally uses jboss-remoting project. is secured (see https://community.InitialContextFactory internally looks for the PROVIDER_URL (and other) properties that are applicable for that context ( doesn't matter whether it comes from the jndi. 32. Note: The server side configurations for the remoting connector to allow "peter" to access the connector. the remote-naming project internally sets up a connection using the jboss-remoting APIs with the remoting connector which is exposed on that port.InitialContextFactory class.naming.client. backed by jboss-remoting project.WildFly 8 That's it! You can see that the values that we pass to those properties are the same as what we did via the jndi.jboss. It's upto the client application to decide which approach they want to follow. We previously mentioned that remote-naming. the client has to pass appropriate user credentials. every service including the http remoting connector (which listens by default on port 8080). The WildFly 8 documentation already has chapters on how to set that up. Let's now have a brief look at how the remote-naming project internally establishes the communication with the server and allows JNDI operations from the client side. Like previously mentioned. This means that when trying to do JNDI operations like a lookup.naming. has increased support for security configurations.client. That was just to keep the examples simple. JBoss Community Documentation Page 454 of 617 .jboss. When the client code creates an InitialContext backed by the org.org/wiki/AS710Beta1-SecurityEnabledByDefault for details). Once it identifies the server and port to connect to. But let's now take the code a step further and see one of the ways how we pass the user credentials.jboss. In our examples so far we haven't passed any username/pass or any other credentials while creating the InitialContext.remote.properties file or whether passed explicitly to the constructor of the InitialContext). Let's at the moment just assume that the remoting connector on port 8080 is accessible to a user named "peter" whose password is expected to be "lois".too tired of typing jboss-remote-naming everytime ) project.

// username jndiProps. Let's now take this one step further and see what kind of operations are allowed for a JNDI context backed by the remote-naming project.properties). except that we now have added 2 additional properties that are passed to the InitialContext constructor.oracle. // create a context passing these properties Context ctx = new InitialContext(jndiProps). One.naming.oracle. The client applications are expected to use the remote-naming project mainly for lookups of JNDI objects.WildFly 8 void doLookup() { Properties jndiProps = new Properties(). There are some other ways to do this too.html#SECURITY_CREDENTIALS which passes the password (lois in this case).naming.PROVIDER_URL.. As such.com/javase/6/docs/api/javax/naming/Context. "org.put(Context.3 JNDI operations allowed using remote-naming project So far we have mainly concentrated on how the naming context is created and what it internally does when an instance is created.INITIAL_CONTEXT_FACTORY. Of course the same properties can be configured in the jndi. it's outside the scope of this article and two (which is kind of the real reason) I haven't looked fully at the remote-naming implementation details to see what other ways are allowed. "lois"). This is one way of passing the security credentials for JNDI communication with WildFly. jndiProps.client. One important thing to note in case of remote-naming project is that.html that are exposed for JNDI operations.properties file (read the javadoc of the Context class for appropriate properties to be used in the jndi.Context class.. But we won't go into those details here for two reasons.jboss. Neither WildFly 8 nor remote-naming project allows writing/binding to the JNDI server from a remote application.SECURITY_CREDENTIALS. // lookup ctx. the remote-naming project does not support many of the methods that are exposed by the javax.lookup("foo/bar")."http-remoting://localhost:8080").3. .put(Context. // password jndiProps. the project's scope is to allow a client to communicate with the JNDI backend exposed by the server. JBoss Community Documentation Page 455 of 617 .html#SECURITY_PRINCIPAL which passes the username (peter in this case) and the second is http://docs.com/javase/6/docs/api/javax/naming/Context.InitialContextFactory").oracle.SECURITY_PRINCIPAL. 32.put(Context.remote. The first is http://docs.com/javase/6/docs/api/javax/naming/Context. The remote-naming project only supports the read-only kind of methods (like the lookup() method) and does not support any write kind of methods (like the bind() method). jndiProps.put(Context. } The code is similar to our previous example. "peter"). The JNDI Context has various methods http://docs.

However. you shouldn't be prefixing the java:jboss/exported/ string to the JNDI name. the remote-naming project will lookup for "foo/bar" JNDI name under the "java:jboss/exported/" namespace of the server. The remote-naming implementation perhaps should be smart enough to strip off the java:jboss/exported/ namespace prefix if supplied. 32. But let's not go into that here. JBoss Community Documentation Page 456 of 617 . java:jboss/exported/foo/bar 2) Objects bound to the java:jboss/exported/ namespace are expected to be serializable.WildFly 8 32.5 JNDI lookup strings for remote clients backed by the remote-naming project In our examples. the JNDI names used while using the remote-naming project are always relative to the java:jboss/exported/ namespace. For example. we are using "foo/bar" JNDI name for the lookup. then remote-naming will translate it to ctx. that actually is (internally) "java:jboss/exported/foo/bar". if you use the following JNDI name: ctx. There's a bit more to understand about the JNDI name and how it maps to the JNDI name that's bound on the server side. and as a result.lookup("java:jboss/exported/java:jboss/exported/helloworld"). This allows the objects to be sent over the wire to the remote clients Both these conditions are important and are required for the objects to be remotely accessible via JNDI.3. to be remotely accessible are: 1) Such objects should be bound under the java:jboss/exported/ namespace. so far. we have been consistently using " foo/bar" as the JNDI name to lookup from a remote client using the remote-naming project. Note: Since the JNDI name that you use on the client side is always relative to java:jboss/exported namespace. will fail during lookup. The remote-naming project expects it to always be relative to the "java:jboss/exported/" namespace. First of all. Once connected with the server side. The two conditions that are to be satisfied by the objects bound to JNDI. not all of those are exposed remotely. the JNDI can contain numerous objects that are bound to it.4 requisites of remotely accessible JNDI objects On the server side. So in our examples.lookup("java:jboss/exported/helloworld").3. For example.

the remote-naming implementation then passes over the object bound at that address to the client. Assuming that the JNDI name is available.3. So assuming your server side application has the following stateless bean: JBoss Community Documentation Page 457 of 617 .4 Summary That pretty much covers whatever is important to know. In fact. This is very important to remember. This is where the requirement about the JNDI object being serializable comes into picture.WildFly 8 32. in the remote-naming project. Some of you might already have started thinking about exposing remote views of EJBs under that namespace. On the client side the remote-naming implementation then unmarshalles the object and returns it to the client application. So literally. remote-naming project internally uses jboss-marshalling project to marshal the JNDI object over to the client.5 Remote EJB invocations backed by the remote-naming project In previous sections of this article we saw that whatever is exposed in the java:jboss/exported/ namespace is accessible remotely to the client applications under the relative JNDI name. 32. since we haven't yet come to the part of EJB invocations from a remote client using the remote-naming project. can just skip the rest of this article if you aren't interested in those details. each lookup backed by the remote-naming project entails a server side communication/interaction and then marshalling/unmarshalling of the object graph. On the server side.6 How does remote-naming project implementation transfer the JNDI objects to the clients When a lookup is done on a JNDI string. Those of you who don't have client applications doing remote EJB invocations. the motivation behind writing this article was to explain why not to use remote-naming project (in most cases) for doing EJB invocations against WildFly server. We'll come back to this later. Don't close the browser yet though. It's important to note that WildFly server side already by default exposes the remote views of a EJB under the java:jboss/exported/ namespace (although it isn't logged in the server logs). the implementation then looks for the JNDI name under the java:jboss/exported/ namespace. to see why this is important when it comes to using EJB client API project for doing EJB lookups (EJB invocations from a remote client using JNDI) as against using remote-naming project for doing the same thing. under that namespace. 32. the remote-naming implementation internally uses the connection to the remoting connector (which it has established based on the properties that were passed to the InitialContext) to communicate with the server. for a typical client application.

WildFly 8 package org. app-name = the name of the .ear (without the .jar/.xml of the deployment. JBoss Community Documentation Page 458 of 617 . So the JNDI name for the Foo remote view under the java:jboss/exported/ namespace would be: java:jboss/exported/myapp/myejbmodule/FooBean!org.jar or . The answer is yes! Let's quickly see the client code for invoking our FooBean. let's assume the bean is packaged in a myejbmodule.. bean-name = the name of the bean which by default is the simple name of the bean implementation class.ear.ear suffix) or the application name configured via application.. So the next logical question would be. } } Then the "Foo" remote view is exposed under the java:jboss/exported/ namespace under the following JNDI name scheme (which is similar to that mandated by EJB3. public String sayBar() { return "Baaaaaaaar".myapp.jar which is within a myapp. Note that only the java:jboss/exported/ namespace is available to remote clients. Again.myapp.war suffix) in which the bean is deployed or the module-name configured in web. @Stateless @Remote(Foo.1 spec for java:global/ namespace):[app-name] app-name/module-name/bean-name!bean-interface where.ear then there will be no app-name part to the JNDI string.xml deployment descriptor. So in our example above.class) public class FooBean implements Foo { .ejb. in addition to the java:global/ java:app/ java:module/ namespaces mandated by the EJB 3. module-name = the name of the .ejb. Of course it can be overridden either by using the "name" attribute of the bean definining annotation (@Stateless(name="blah") in this case) or even the ejb-jar. The module name is mandatory part in the JNDI string. let's just use "peter" and "lois" as username/pass for connecting to the remoting connector.xml/ejb-jar. If the application isn't packaged in a .Foo That's where WildFly will automatically expose the remote views of the EJBs under the java:jboss/exported/ namespace.war (without the . are these remote views of EJBs accessible and invokable using the remote-naming project on the client application. bean-interface = the fully qualified class name of the interface being exposed by the bean.xml deployment descriptor.1 spec.

In this case too.jboss. "lois").SECURITY_PRINCIPAL.PROVIDER_URL.context". But in the example above. The EJBReceiver is responsible for handling the EJB invocations. From a EJB client API project perspective.ejb. security credentials and other similar parameters. // after this point the beanRemoteInterface is not longer valid! } As you can see. then you would have configured all these properties via the jboss-ejb-client. Let's see what the "jboss.put(Context. such a EJBReceiver would have to know the server address.println("Remote Foo bean returned " + bar).client.client.ejb.com/jbossas/jboss-ejb-client.naming.put("jboss. One type of a EJBReceiver is a RemotingConnectionEJBReceiver which internally uses jboss-remoting project to communicate with the remote server to handle the EJB invocations. most of the code is similar to what we have been seeing so far for setting up a JNDI context backed by the remote-naming project.INITIAL_CONTEXT_FACTORY.remote. JBoss Community Documentation Page 459 of 617 . // This is an important property to set if you want to do EJB invocations via the remote-naming project jndiProps. jndiProps. for successful communication with the server. So no matter. ctx.close().client. the project expects a EJBClientContext backed by (atleast one) EJBReceiver(s). System.myapp.InitialContextFactory"). remote access/invocations on EJBs is facilitated by the JBoss specific EJB client API.properties or via programatic API usage as explained here EJB invocations from a remote client using JNDI. // password jndiProps..Foo"). Of course to be able to connect to the server.naming. port. If you were using the core EJB client API. // username jndiProps. what mechanism you use (remote-naming or core EJB client API).naming. true)."http-remoting://localhost:8080"). Properties jndiProps = new Properties(). 2) The JNDI name used for the lookup 3) And subsequently the invocation on the bean interface returned by the lookup.out.put(Context. In WildFly.put(Context..ejb. Such a EJBReceiver expects a connection backed by the jboss-remoting project.ejb. jndiProps.SECURITY_CREDENTIALS. we are using remote-naming project and are not directly interacting with the EJB client API project. // create a context passing these properties Context ctx = new InitialContext(jndiProps). The only parts that change are: 1) An additional "jboss.client. the remote-naming internally uses EJB client API to handle EJB invocations. the invocations are ultimately routed through the EJB client API project. "org.put(Context. // lookup the bean Foo beanRemoteInterface = (Foo) ctx.WildFly 8 void doBeanLookup() { . "peter").lookup("myapp/myejbmodule/FooBean!org. which is a project on its own https://github.naming. String bar = beanRemoteInterface.context" does.context" property that is added to the properties passed to the InitialContext constructor.sayBar().

WildFly 8 If you look closely at what's being passed. Now since the remote-naming implementation has done the necessary setup for the EJBClientContext (due to the presence of " jboss.client.context" property and its usage. In fact.client. When this is set to true and passed to the InitialContext creation (either via jndi.naming. via the JNDI properties. Now this is where the "jboss. the JNDI name. let's understand a bit about the EJB client project. the rest is straightforward. Long story short.client.ejb. you'll realize that these properties are indeed the same as what the RemotingConnectionEJBReceiver would expect to be able to establish the connection to the server.properties or via the constructor of that class).6 Why use the EJB client API approach then? I can guess that some of you might already question why/when would one use the EJB client API style lookups as explained in the EJB invocations from a remote client using JNDI article instead of just using (what appears to be a simpler) remote-naming style lookups. marshalling/unmarshalling etc. using the remote-naming project for doing remote EJB invocations against WildFly is possible! 32. Remember that we earlier explained how each lookup via remote-naming triggers a server side communication and a marshalling/unmarshalling process. Before we answer that.context" property). we cast the returned object back to the Foo interface. We won't go into the details of how the EJB client API handles the communication/invocation. The easiest place where this optimization can be applied.. So we now know the importance of the "jboss.naming. containing a RemotingConnectionEJBReceiver which is created using the same remoting connection that is created by and being used by remote-naming project for its own JNDI communication usage. Once the unmarshalled object is returned (which actually is a proxy to the bean). The EJB client project was implemented keeping in mind various optimizations and features that would be possible for handling remote invocations. Let's move on the next part in that code. to the remote-naming project and if you remember the details that we explained in a previous section about how the remote-naming project establishes a connection to the remote server. we just invoke on that returned object. the remote-naming project has no clue (since that's not in the scope of that project to know) whether it's an EJB or some random object. Notice that we have used the JNDI name relative to the java:jboss/exported/ namespace while doing the lookup. One such optimization was to avoid doing unnecessary server side communication(s) which would typically involve network calls.context" property comes into picture.naming. So effectively. This applies for EJB views too. the InitialContext creation via the remote-naming project has now internally triggered the creation of a EJBClientContext containing a EJBReceiver capable of handling the EJB invocations (remember. the remote-naming project internally will do whatever is necessary to setup a EJBClientContext.. no remote EJB invocations are possible without the presence of a EJBClientContext containing a EJBReceiver which can handle the EJB).ejb. the invocation on that proxy will internally use the EJBClientContext (the proxy is smart enough to do that) to interact with the server and return back the result. And since we know that the Foo view is exposed on that JNDI name.ejb. is to the EJB lookup. Consider the following code (let's ignore how the context is created): JBoss Community Documentation Page 460 of 617 .

More details about such code can be found here EJB invocations from a remote client using JNDI When a client application looks up anything under the "ejb:" namespace. "org.client. it expects the client application to let it know that a EJB is being looked up.ejb.lookup("foo/bar"). it is a clear indication (for the EJB client API project) to know that the client is looking up an EJB. we'll come to that later).lookup("ejb:myapp/myejbmodule//FooBean!org. when the invocation on the proxy happens. So unlike.URL_PKG_PREFIXES. marshalling/unmarshalling step but it also means that you can create an EJB proxy even when the server isn't up yet. Instead. in the case of remote-naming project (which has no clue about the semantics of the object being looked up). the EJB client API project does not trigger a server side communication or a marshal/unmarshal process when you do lookup for a remote view of a stateless bean (it's important to note that we have specifically mentioned stateless bean here. Now foo/bar JNDI name could potentially point to any type of object on the server side.Proxy instance of the remote view type that's being looked up.jboss. This not just saves a network call. String bar = beanProxy.URL_PKG_PREFIXES property. That's where it steps in to do the necessary optimizations that might be applicable.lang.jboss.ejb. In order to do so. we explained this earlier). the EJB client API just returns a java.myapp. by expecting the client application to use the JNDI name of the format "ejb:" namespace and also expecting the client application to setup the JNDI context by passing the "org.sayBar().WildFly 8 ctx. the EJB client API does communicate with the server to carry out the invocation.Foo"). jndiProperties. If the context was setup using the remote-naming project (like we have seen earlier in our examples). Later on. Example: final Properties jndiProperties = new Properties().naming" value for the Context. It does this. And that's exactly what it does (remember.reflect. // lookup Foo beanProxy = context. // create the context final Context context = new InitialContext(jndiProperties).ejb. then the only way for remote-naming to return an object for that lookup operation is to communicate with the server and marshal/unmarshal the object bound on the server side. JBoss Community Documentation Page 461 of 617 .naming").put(Context. The EJB client API project on the other hand optimizes this lookup. The jndi name itself won't have the type/semantic information of the object bound to that name on the server side.client.

Notice the use of "?stateful" in that JNDI name.6. Note that if you want to use remote-naming for looking up and invoking on non-EJB remote objects then you are free to do so. we have managed to optimize certain operations by using the EJB client API for EJB lookup/invocation as against using the remote-naming project.1 Is the lookup optimization applicable for all bean types? In the previous section we (intentionally) mentioned that the lookup optimization by the EJB client API project happens for stateless beans. So as you can see. That's why the remote-naming project for remote EJB invocations is considered "deprecated". See EJB invocations from a remote client using JNDI for more details about such lookup.lookup("ejb:myapp/myejbmodule//StatefulBean!org. that's why that project has been provided.ejb. In fact. You can even use the remote-naming project for EJB invocations (like we just saw). That's exactly why the EJB client API project expects the JNDI name lookup string for stateful beans to include the "?stateful" string at the end of the JNDI name: context.myapp. a lookup is expected to create a session for that stateful bean and for session creation we do have to communicate with the server since the server is responsible for creating that session. if you are fine with not wanting the optimizations that the EJB client API can do for you or if you have other restrictions that force you to use that project. The presence of "?stateful" in the JNDI name lookup string is a directive to the EJB client API to let it know that a stateful bean is being looked up and it's necessary to communicate with the server and create a session during that lookup.WildFly 8 32. There are other EJB client API implementation details (and probably more might be added) which are superior when it is used for remote EJB invocations in client applications as against remote-naming project which doesn't have the intelligence to carry out such optimizations for EJB invocations.Counter?stateful"). This kind of optimization is not possible for stateful beans because in case of stateful beans. JBoss Community Documentation Page 462 of 617 .

In this case the underlying EJBContext is destroyed and the conections are closed. the first available server will be used and only in case it is not longer available there will be a failover to the next available one. or the InitialContext is not longer referenced and gets garbage-collected.6. No cluster support.2 Restrictions for EJB's If the remote-naming is used there are some restrictions as there is no full support of the ejb-client features.WildFly 8 32.close() for the related Initalcontext is invoked.getCurrent() can not be used and it is not possible to add a client interceptor No UserTransaction support All proxies become invalid if . No loadbalancing. It is not possible to use remote-naming if the client is an application deployed on another JBoss instance JBoss Community Documentation Page 463 of 617 . As a cluster needs to be defined in the jboss-ejb-client. The EJBContext.properties this feature can not be used and there is no cluster node added No client side interceptor. if the URL conatains multiple "remote://" servers there is no loadbalancing.

In case of remote clients which run within another WildFly 8 instance.naming. the corresponding EJB client context will be used for finding the right EJB receiver and letting it handle the invocation. each deployed application will have a corresponding EJB client context... Whenever that application invokes on another EJB. Typically EJB remote applications can be classified into: A remote client which runs as a standalone Java application A remote client which runs within another WildFly 8 instance Depending on the kind of remote client.Context ctxOne = new javax. Let's focus on the standalone remote clients (the ones that don't run within another WildFly 8 instance) for some of the next sections. An EJB receiver is a component which knows how to communicate with a server which is capable of handling the EJB invocation.WildFly 8 33 Scoped EJB client contexts 33. from an EJB client API point of view. there can potentially be more than 1 EJBClientContext(s) within a JVM. typically a remote standalone client has just one EJB client context backed by any number of EJB receivers.InitialContext(). Like mentioned earlier.lookup("ejb:app/module/distinct/bean!interface"). In case of standalone applications. .naming. beanOne. Consider this example: public class MyApplication { public static void main(String args[]) { final javax. Certain standalone applications can potentially have more than one EJBClientContext(s) and a EJB client context selector will be responsible for returning the appropriate context. 33.doSomething(). final MyBeanInterface beanOne = ctxOne. typically a single EJBClientContext (backed by any number of EJB receivers) exists.1 Overview WildFly 8 introduced the EJB client API for managing remote EJB invocations. However this isn't mandatory. The EJB client API works off EJBClientContext(s).2 Potential shortcomings of a single EJB client context In the Overview section we briefly looked at the different types of remote clients. An EJBClientContext can potentially contain any number of EJB receivers. } } JBoss Community Documentation Page 464 of 617 .

final MyBeanInterface beanTwo = ctxTwo. } } So we have the same application.WildFly 8 Now.. but wants to use two different credentials while connecting to the server. Let's take a look at the following code: public class MyApplication { public static void main(String args[]) { // let's say we want to use "foo" security credential while connecting to the AS7 server for invoking on this bean instance final javax. beanTwo.doSomething(). where you can have more control over the EJB client contexts and their association with JNDI contexts which are typically used for EJB invocations.. Since we just have a single EJB client context.doSomething().. Now let's consider a case where the user application wants to invoke on the bean more than once.jboss.naming. That was one of the use cases which prompted the https://issues.properties file which is used to setup the EJB client context and the EJB receivers. but wants to connect to the WildFly 8 server using different security credentials.lookup("ejb:app/module/distinct/bean!interface"). which wants to connect to the same server instance for invoking the EJB(s) hosted on that server.InitialContext().naming.Context ctxOne = new javax. Which effectively means that the above code will end up using just one credential to connect to the server. JBoss Community Documentation Page 465 of 617 . beanOne.lookup("ejb:app/module/distinct/bean!interface"). final MyBeanInterface beanOne = ctxOne.naming. These configurations include the security credentials that will be used to create a EJB receiver which connects to the AS7 server. The proposal was to introduce a way.Context ctxTwo = new javax. . .naming. the EJB client API looks for the EJB client context to pick a EJB receiver. Now when the above code is invoked. the client application has a single EJB client context which can have atmost 1 EJB recevier for each server instance. we have seen in this other chapter EJB invocations from a remote client using JNDI that the JNDI lookups are (typically) backed by jboss-ejb-client. Let's assume we have a jboss-ejb-client. that context is used by the above code to invoke the bean. Remember.InitialContext().org/browse/EJBCLIENT-34 feature request.properties with the relevant receivers configurations. to pass on the EJB invocation request.. // let's say we want to use "bar" security credential while connecting to the AS7 server for invoking on this bean instance final javax. So there was no easy way to have the above code working.

closeContext(ctxTwo).. except for one additional property which is required to scope the EJB client context to the JNDI context.naming. That way any invocation done on EJB proxies looked up using that JNDI context. you would typically create a JNDI context passing it the PROVIDER_URL which would point to the target server.ejb.org/browse/EJBCLIENT-34..properties file. beanTwo.org/browse/EJBCLIENT-34 we now allow the EJB client contexts to be scoped with the JNDI contexts.Context ctxTwo = new javax.doSomething().Context ctxOne = new javax. final MyBeanInterface beanOne = ctxOne.. The name of the property is: org. . Before we introduced https://issues.context JBoss Community Documentation Page 466 of 617 . If we look back at the example above. beanOne.3 Scoped EJB client contexts Developers familiar with earlier versions of JBoss AS would remember that for invoking an EJB. would end up on that server. .naming. We want the user applications to have more control over which EJB receiver gets used for a specific invocation.scoped.. Consider the following example: public class MyApplication { public static void main(String args[]) { // let's say we want to use "foo" security credential while connecting to the AS7 server for invoking on this bean instance final Properties ejbClientContextPropsOne = getPropsForEJBClientContextOne(): final javax.jboss.lookup("ejb:app/module/distinct/bean!interface").jboss. we'll realize that. // read on the entire article to understand more about closing scoped EJB client contexts // let's say we want to use "bar" security credential while connecting to the AS7 server for invoking on this bean instance final Properties ejbClientContextPropsTwo = getPropsForEJBClientContextTwo(): final javax. closeContext(ctxOne). final MyBeanInterface beanTwo = ctxTwo.InitialContext(ejbClientContextPropsTwo).doSomething().client.org/browse/EJBCLIENT-34 feature. As part of https://issues. So what do the EJB client context properties look like? The properties are the same that you would pass through the jboss-ejb-client.naming.naming. the EJB client context was typically scoped to the client application.WildFly 8 33.jboss. // read on the entire article to understand more about closing scoped EJB client contexts } } Notice any difference between this code and the earlier one? We now create and pass EJB client context specific properties to the JNDI context.lookup("ejb:app/module/distinct/bean!interface").jboss.InitialContext(ejbClientContextPropsOne). we are ultimately aiming for a similar functionality through https://issues.

IMPORTANT: It is very important to remember that scoped EJB client contexts which are scoped to the JNDI contexts are NOT fire and forget kind of contexts.jboss. JBoss Community Documentation Page 467 of 617 . What that means is the application program which is using these contexts is solely responsible for managing their lifecycle and the application itself is responsible for closing the context at the right moment.4 Lifecycle management of scoped EJB client contexts Like you saw in the previous sections. Not closing the context will end in resource problems as the underlying physical connection will stay open. Not managing the EJB client context lifecycle correctly can lead to connection leaks in some cases. It's very important to understand how the lifecycle of the EJB client context works in such cases. This property lets the EJB client API know that it has to created a EJB client context (backed by EJB receiver(s)) and that created context is then scoped/visible to only that JNDI context which created it. An internal implementation detail of this logic includes the ability of the EJB client context to cache connections based on certain internal algorithm it uses.context property) will fallback to the default behaviour of using the "current" EJB client context which typically is the one tied to the entire application. JNDI contexts which aren't scoped to a EJB client context (for example.ejb. This allows the EJB client context to be usable for EJB invocations. the EJB client context is tied to the JNDI context. This effectively means that the other JNDI contexts which the application uses to lookup and invoke on EJBs will not know about the other scoped EJB client contexts at all.WildFly 8 which is expected to have a value true. the EJB client context connects to the server(s) listed in the JNDI properties.scoped. The connections thus created for a EJB client context are kept open as long as the EJB client context is open. The connections associated with the EJB client context are closed when the EJB client context itself is closed. Especially since any EJB client context is almost always backed by connections to the server. Read the rest of the sections in this article to understand more about the lifecycle management of such scoped contexts. This gives the user applications the flexibility that was associated with the JNP based JNDI invocations prior to WildFly 8 versions. Lookup and invocation on any EJB proxies looked up using this JNDI context will only know of the EJB client context associated with this JNDI context. When you create a scoped EJB client context. After closing the context the proxies which are bound to this context are no longer valid and any invocation will throw an Exception. 33. This scoping of the EJB client context helps the user applications to have more control over which JNDI context "talks to" which server and connects to that server in "what way". in case of scoped EJB client contexts. The algorithm itself isn't publicly documented (yet) since the chances of it changing or even removal shouldn't really affect the client application and instead it's supposed to be transparent to the client application.client. not passing the org.

33. The JNDI API provided by Java language allows "URL context factory" to be registered in the JNDI framework (see this for details http://docs.naming.e. What's actually happening when you lookup that string is that a separate javax. But the real question is how do you get the relevant scoped EJB client context which is associated with a JNDI context. Internally.WildFly 8 The connections that were manually added by the application to the EJB client context are not managed by the EJB client context.oracle.4. The ejb: URL string is backed by a URL context factory. when a lookup happens for a ejb: URL string.com/javase/jndi/tutorial/provider/url/factory. i. Let's see some code for better understanding: // JNDI context "A" Context jndiCtx = new InitialContext(props).lookup("ejb:app/module/distinct/bean!interface"). is just one statement. // Use the returned EJB naming context to lookup the rest of the JNDI string for EJB final MyBean bean = ejbNamingContext. // Now let's lookup a EJB MyBean bean = jndiCtx.Context is created for that ejb: lookup. That's what the ejb: prefix is when you do a remote EJB lookup.2 How to close scoped EJB client contexts? The answer is the same. the URL context factory can be used to resolve URL strings during JNDI lookup.lookup("app/module/distinct/bean!interface"). it's important to understand how the ejb: JNDI namespace that's used for EJB lookups and how the JNDI context (typically the InitialContext that you see in the client code) are related. a relevant javax. the ejb: is backed by a URL context factory which returns a Context for the ejb: URL (that's why it's called a context factory) final Context ejbNamingContext = (Context) jndiCtx. This new javax. JBoss Community Documentation Page 468 of 617 .html).1 How to close EJB client contexts? The answer to that is simple. Like that documentation states. Use the close() method on the appropriate EJB client context. Before we get to that. involves a few more things under the hood. although. Let's break up that one line into multiple statements to understand better: // Remember. So we first create a JNDI context and then use it to lookup an EJB.naming.4. use the close() method on the EJB client context.Context gets created for the ejb: URL string.naming. The bean lookup using the ejb: JNDI name. they won't be opened (obviously) nor closed by the EJB client API when the EJB client context is closed.lookup("ejb:"). 33.Context is then used to lookup the rest of the string in that JNDI name.

an instance of javax. i.naming. } finally { jndiCtx. So as you can see when the ejb: URL string is parsed in a JNDI name.ejb..Context.Context that backs the ejb: URL string is still not closed. the code works the same. bean.close(). We know that the ejb: URL string lookup returns us a javax.Context backing the ejb: URL string is a different instance than the one the code is closing.naming. .Context gets created for the ejb: URL string. which then returns the EJB proxy. This instance is different from the one which was used to do the lookup (jndiCtx in this example).put("org.. So here's how it's going to look: JBoss Community Documentation Page 469 of 617 .naming. So why am I explaining all this when the section is titled "How to close scoped EJB client contexts"? The reason is because client applications dealing with scoped EJB client contexts which are associated with a JNDI context would expect the following code to close the associated EJB client context.client.doSomething().naming. All we have to do is keep a reference to this instance and close it when we are done with the EJB invocations. That doesn't happen because as explained previously. // mark it for scoped EJB client context props."true").WildFly 8 As you see above. Context jndiCtx = new InitialContext(props). As a result. we split up that single statement into a couple of statements for explaining the details better. it gets hold of a javax. which effectively means that the scoped EJB client context is not closed too which then ultimately means that the connection to the server(s) in the EJB client context are not closed too. the javax. the other javax..scoped.. } Applications expect that the call to jndiCtx. Irrespective of whether the lookup is done in a single statement or multiple parts. // add other properties props. So now let's see how this can be done properly.jboss.e. Now this returned instance is used to lookup the rest of the JNDI string ("app/module/distinct/bean!interface"). The JNDI implementation in Java.context".close() will effectively close the EJB client context associated with the JNDI context.naming. but will be surprised that it won't: final Properties props = new Properties().put(. try { final MyBean bean = jndiCtx. only just closes the context on which the close was called.lookup("ejb:app/module/distinct/bean!interface")..Context instance. This is an important detail to understand (for reasons explained later).).

JBoss Community Documentation Page 470 of 617 .put("org.lookup("app/module/distinct/bean!interface").close(). Effectively. we closed the ejbRootNamingContext (as well as the other JNDI context).ejb.. we changed the code to first do a lookup on just the "ejb:" string to get hold of the EJB naming context and then used that ejbRootNamingContext instance to lookup the rest of the EJB JNDI name to get hold of the EJB proxy.put(. } catch (Throwable t) { // log and ignore } } As you see.).context".doSomething().scoped. // the rest of the EJB jndi string bean. } catch (Throwable t) { // log and ignore } try { // also close our other JNDI context since we are done with it too jndiCtx.. Context ejbRootNamingContext = (Context) jndiCtx. Closing the ejbRootNamingContext ensures that the scoped EJB client context associated with that JNDI context is closed too..jboss.. // add other properties props. Context jndiCtx = new InitialContext(props).close()."true"). } finally { try { // close the EJB naming JNDI context ejbRootNamingContext.. this closes the connection(s) to the server(s) within that EJB client context. Then when it was time to close the context.WildFly 8 final Properties props = new Properties().lookup("ejb:"). // mark it for scoped EJB client context props. . try { final MyBean bean = ejbRootNamingContext.client.

JBoss Community Documentation Page 471 of 617 . // the rest of the EJB jndi string bean. } catch (Throwable t) { // log and ignore } } Notice that we no longer hold a reference to 2 JNDI contexts and instead just keep track of the ejbRootNamingContext which is actually the root JNDI context for our "ejb:" URL string.lookup("app/module/distinct/bean!interface"). then yes you can get rid of some instances and code from the above code. try { final MyBean bean = ejbRootNamingContext."true"). ..).. // add other properties props.scoped.put(.close().doSomething(). So it depends on your application and how it's coded.context".put("org.jboss.ejb. You can change that code to: final Properties props = new Properties()...client. Context ejbRootNamingContext = (Context) new InitialContext(props). Of course. } finally { try { // close the EJB naming JNDI context ejbRootNamingContext. this means that you can only use this context for EJB lookups or any other EJB related JNDI lookups..WildFly 8 Can that code be simplified a bit? If you are using that JNDI context only for EJB invocations. // mark it for scoped EJB client context props.lookup("ejb:").

WildFly 8 33.scoped.put(.. the EJB client API can't take that decision.e. bean.4. bean. JBoss Community Documentation Page 472 of 617 . .lookup("ejb:"). No. } MyBean lookupEJB() { final Properties props = new Properties()..3 Can't the scoped EJB client context be automatically closed by the EJB client API when the JNDI context is no longer in scope (i.. If the EJB client API had closed the scoped EJB client context associated with that JNDI context. on GC)? That's one of the common questions that gets asked..e.client."true"). // rest of the EJB jndi string return bean.lookup("app/module/distinct/bean!interface").jboss.. // add other properties props. the JNDI context that was used for lookup (i. i.context".doSomeOtherThing()..keepDoingSomething().ejb. . The doEJBInvocation() then uses that returned proxy and keeps doing the invocations on the bean. it cannot automatically go ahead and close the scoped EJB client context by itself when the associated JNDI context is eligible for GC. when that JNDI context was garbage collected. } As you can see. the doEJBInvocation() method first calls a lookupEJB() method which does a lookup of the bean using a JNDI context and then returns the bean (proxy).).e. The reason is simple as illustrated by the following code: void doEJBInvocation() { final MyBean bean = lookupEJB(). Context ejbRootNamingContext = (Context) new InitialContext(props). then the subsequent EJB invocations on the returned EJB (proxy) would start failing in doEJBInvocation() since the EJB client context is no longer available. As you might have noticed. That's the reason why the EJB client API doesn't automatically close the EJB client context. // do some other work bean..doSomething().put("org. final MyBean bean = ejbRootNamingContext. the ejbRootNamingContext) is eligible for GC. // mark it for scoped EJB client context props.

4 based applications Spring applications using JPA may choose between: using a server-deployed persistence unit.3 Native Spring/Hibernate applications Applications that use the Hibernate API directly with Spring (i.2 as described in SPR-8096).such as logging frameworks or persistence providers to run on WildFly 8. At the same time. 34. 34. using a Spring-managed persistence unit. This makes it easier for Spring applications that package their own dependencies . depending on the type of deployment as shown here.1 Dependencies and Modularity WildFly 8 has a modular class loading strategy. which enforces a better class loading isolation between deployments and the application server itself. this does not mean that duplications and conflicts cannot exist on the classpath. 34. JPA-based applications. 34.1 (and may be supported by Spring 3. Hibernate 4 (which is provided through the 'org. JBoss Community Documentation Page 473 of 617 . through either one of LocalSessionFactoryBean or AnnotationSessionFactoryBean) may use a version of Hibernate 3 packaged inside the application. so adding this module as a dependency is not a solution. Spring applications can be: native Hibernate applications. different from previous versions of JBoss AS. Some module dependencies are implicit.hibernate' module of WildFly 8) is not supported by Spring 3. This reduces significantly the risk of running into a class loading conflict and allows applications to package their own dependencies if they choose to do so. A detailed description can be found in the documentation dedicated to class loading in WildFly 8.e.WildFly 8 34 Spring applications development and migration guide This document details the main points that need to be considered by Spring developers that wish to develop new applications or to migrate existing applications to be run into WildFly 8.0 and Spring 3. native JDBC applications.2 Persistence usage guide Depending on the strategy being used.

persistence. the persistence context or persistence unit are available to be looked up in JNDI. In order to use the server-deployed persistence units from within Spring. JBoss Community Documentation Page 474 of 617 .e.4.WildFly 8 34.xml as follows: <persistence-context-ref> <persistence-context-ref-name>persistence/petclinic-em</persistence-unit-ref-name> <persistence-unit-name>petclinic</persistence-unit-name> </persistence-context-ref> or.persistence classes and persistence provider (Hibernate) are contained in modules which are added automatically by the application when the persistence unit is deployed.EntityManagerFactory"/> JNDI binding JNDI binding via persistence.EntityManager"/> or <jee:jndi-lookup id="entityManagerFactory" jndi-name="java:comp/env/persistence/petclinic-emf" expected-type="javax.xml properties is not supported in WildFly 8. respectively: <persistence-unit-ref> <persistence-unit-ref-name>persistence/petclinic-emf</persistence-unit-ref-name> <persistence-unit-name>petclinic</persistence-unit-name> </persistence-unit-ref> When doing so.persistence. as follows: <jee:jndi-lookup id="entityManager" jndi-name="java:comp/env/persistence/petclinic-em" expected-type="javax. the javax.1 Using server-deployed persistence units Applications that use a server-deployed persistence unit must observe the typical Java EE rules in what concerns dependency management. i. either the persistence context or the persistence unit need to be registered in JNDI via web.

WEB-INF/classes/META-INF/persistence. and consequently of the entire deployment. Spring applications can easily avoid this type of conflict. Persistence unit definition files can exist in other locations than META-INF/persistence. In most cases. the corresponding definition can be: <bean id="entityManagerFactory" class="org.xml and the location can be indicated through the persistenceXmlLocation property of the factory bean class. which will fail the deployment of the persistence unit.other definitions --> </bean> JBoss Community Documentation Page 475 of 617 .xml (or. such definition files are not compliant with the Java EE requirements.xml"/> <!-.xml).4.springframework. Assuming that the persistence unit is in the META-INF/jpa-persistence.2 Using Spring-managed persistence units Spring applications running in WildFly 8 may also create persistence units on their own.LocalContainerEntityManagerFactoryBean"> <property name="persistenceXmlLocation" value="classpath*:META-INF/jpa-persistence. it will attempt to create a persistence unit based on what is provided in the file. using the LocalContainerEntityManagerFactoryBean. by using a feature of the LocalContainerEntityManagerFactoryBean which is designed for this purpose.WildFly 8 34.xml. for that matter.orm. This is what these applications need to consider: Placement of the persistence unit definitions When the application server encounters a deployment that has a file named META-INF/persistence.jpa. mostly because required elements such as the datasource of the persistence unit are supposed to be provided by the Spring context definitions.

the application server will automatically add the 'org. due the presence of @PersistenceUnit or @PersistenceContext annotations on the application classes.3 Managing dependencies Since the LocalContainerEntityManagerFactoryBean and the corresponding HibernateJpaVendorAdapter are based on Hibernate 3.0"> <deployment> <exclusions> <module name="org. the Hibernate 3 jars must be included in the deployment. for web applications.hibernate' module as a dependency. include a META-INF/jboss-deployment-structure.xml with the following content: <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1. Therefore.4. This can be avoided by instructing the server to exclude the module from the deployment's list of dependencies. At the same time.hibernate"/> </exclusions> </deployment> </jboss-deployment-structure> JBoss Community Documentation Page 476 of 617 . In order to do so. it is required to use that version with the application.WildFly 8 34. WEB-INF/jboss-deployment-structure.xml or.

In short. The server automatically generates and publishes the abstract contract (i. Plain old Java Object (POJO) Let's take a look at simple POJO endpoint implementation. The latest project documentation is available here.e. All marshalling/unmarshalling is delegated to JAXB. Below is a brief overview of the most basic functionalities.WildFly 8 35 Webservices reference guide The Web Services functionalities of WildFly are provided by the JBossWS project integration.1. wsdl+schema) for client consumption.1 WS User Guide The Java API for XML-Based Web Services (JAX-WS / JSR-224) defines the mapping between WSDL and Java as well as the classes to be used for accessing webservices and publishing them. JAX-WS User Guide JAX-WS Tools wsconsume wsprovide Advanced User Guide Predefined client and endpoint configurations Authentication Apache CXF integration WS-Addressing WS-Security WS-Trust and STS WS-Reliable Messaging SOAP over JMS HTTP Proxy WS-Discovery WS-Policy JBoss Modules and WS applications 35. All endpoint associated metadata is provided via JSR-181 annotations JBoss Community Documentation Page 477 of 617 . This section covers the most relevant topics for the JBossWS version available on WildFly 8. an endpoint implementation bean is annotated with JAX-WS annotations and deployed to the server. hence users can reference it for any vendor agnostic webservice usage need. 35. JBossWS implements the latest JAX-WS specification.1 Web Service Endpoints JAX-WS simplifies the development model for a web service endpoint a great deal.

You can get the deployed endpoint wsdl address there too. Accessing the generated WSDL A successfully deployed service endpoint will show up in the WildFly managent console.xml"> <classes dir="${build. it is also possible to generate the abstract contract off line using JBossWS tools.WildFly 8 @WebService @SOAPBinding(style = SOAPBinding.Style.resources. <war warfile="${build. only the endpoint implementation bean and web.RPC) public class JSEBean01 { @WebMethod public String echo(String input) { ..jsr181pojo. For details of that please see Bottom-Up (Java to WSDL).dir}/libs/jbossws-samples-jsr181pojo.> <servlet> <servlet-name>TestService</servlet-name> <servlet-class>org.jboss..xml descriptor: <web-app . } } The endpoint as a web application A JAX-WS java service endpoint (JSE) is deployed as a web application. Here is a sample web.samples.jaxws.ws.war" webxml="${build..dir}/samples/jsr181pojo/WEB-INF/web.class"/> </classes> </war> Note. JBoss Community Documentation Page 478 of 617 ..JSEBean01</servlet-class> </servlet> <servlet-mapping> <servlet-name>TestService</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> </web-app> Packaging the endpoint A JSR-181 java service endpoint (JSE) is packaged as a web application in a war file. Note.dir}/classes"> <include name="org/jboss/test/ws/samples/jsr181pojo/JSEBean01.test.xml are required.

} } Above you see an EJB-3..dir}/libs/jbossws-samples-jsr181ejb.class"/> <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3RemoteInterface. Note.. Packaging the endpoint A JSR-181 EJB service endpoint is packaged as an ordinary ejb deployment.Style. For details of that please see Bottom-Up (Java to WSDL). JBoss Community Documentation Page 479 of 617 .jar"> <fileset dir="${build. @Stateless @Remote(EJB3RemoteInterface.class"/> </fileset> </jar> Accessing the generated WSDL A successfully deployed service endpoint will show up in the WildFly managent console.WildFly 8 EJB3 Stateless Session Bean (SLSB) The JAX-WS programming model supports the same set of annotations on EJB3 stateless session beans as on POJO endpoints. You can get the deployed endpoint wsdl address there too.class) @RemoteBinding(jndiBinding = "/ejb3/EJB3EndpointInterface") @WebService @SOAPBinding(style = SOAPBinding.dir}/classes"> <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3Bean01. <jar jarfile="${build.RPC) public class EJB3Bean01 implements EJB3RemoteInterface { @WebMethod public String echo(String input) { . it is also possible to generate the abstract contract off line using JBossWS tools.0 stateless session bean that exposes one method both on the remote interface and as an endpoint operation.

JBoss Community Documentation Page 480 of 617 . in some cases it is desirable for services to be able to operate at the XML message level. each of which consists of a port type bound to a particular protocol and available at a particular endpoint address.PAYLOAD) public class ProviderBeanPayload implements Provider<Source> { public Source invoke(Source req) { // Access the entire request PAYLOAD and return the response PAYLOAD } } Note. One of these will be the service.e.Mode. either directly or via the use of annotations. The Provider interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level. Service.Mode. 35. However. Therefore it is necessary to specify the wsdlLocation with the @WebServiceProvider annotation. Java SEIs provide a high level Java-centric abstraction that hides the details of converting between Java objects and their XML representations for use in XML-based messages.WildFly 8 Endpoint Provider JAX-WS services typically implement a native Java service endpoint interface (SEI). A WSDL service is a collection of related ports.2 Web Service Clients Service Service is an abstraction that represents a WSDL service.1. For most clients. perhaps mapped from a WSDL port type. A Provider based service instances invoke method is called for each message received for the service.MESSAGE to access the entire SOAP message (i. with MESSAGE the Provider can also see SOAP Headers) The abstract contract for a provider endpoint cannot be derived/generated automatically. you will start with a set of stubs generated from the WSDL. and you will create objects of that class in order to work with the service (see "static case" below).wsdl") @ServiceMode(value = Service. @WebServiceProvider(wsdlLocation = "WEB-INF/wsdl/Provider. You can also use Service.Mode.PAYLOAD is the default and does not have to be declared explicitly.

If you need to work with the XML payload directly or with the XML representation of the entire SOAP message. serviceName).com/stocks. URL wsdlLocation = new URL("http://example.Service { public StockQuoteService() { super(new URL("http://example. have a look at Dispatch. QName serviceName = new QName("http://example. and generate some stubs using JBossWS tools like wsconsume. The following code snippet shows the generated constructors from the generated class: // Generated Service Class @WebServiceClient(name="StockQuoteService". a web service client uses Service. when nothing is generated. JBoss Community Documentation Page 481 of 617 . serviceName).create to create Service instances. This usually gives a mass of files. } Section Dynamic Proxy explains how to obtain a port from the service and how to invoke an operation on the port.wsdl").org/sample".wsdl"). These are set implicitly from the @WebServiceClient annotation that decorates the generated class.com/stocks". one with no arguments and one with two arguments. representing the wsdl location (a java.namespace. In this case the WSDL location and service name are those found in the WSDL.com/stocks". wsdlLocation="http://example. } . Service service = Service. the following code illustrates this process..ws. The generated implementation class can be recognised as it will have two public constructors.xml.org/my.com/stocks.QName) respectively.. targetNamespace="http://example. } public StockQuoteService(String wsdlLocation. This is the service implementation class. one of which is the top of the tree. QName serviceName) { super(wsdlLocation.WildFly 8 Service Usage Static case Most clients will start with a WSDL file. "MyService"). Usually you will use the no-argument constructor.create(wsdlLocation. "StockQuoteService")). new QName("http://example.URL) and the service name (a javax.wsdl") publicclass StockQuoteService extends javax.xml. Dynamic case In the dynamic case.net.

Dynamic Proxy You can create an instance of a client proxy using one of getPort methods on the Service. The parameter * <code>serviceEndpointInterface</code> specifies the service * endpoint interface that is supported by the returned proxy. Handler Framework describes the handler framework in detail. per-port or per-protocol binding basis. * **/ public <T> T getPort(Class<T> serviceEndpointInterface) { .. When a Service instance is used to create a proxy or a Dispatch instance then the handler resolver currently registered with the service is used to create the required handler chain. **/ public <T> T getPort(QName portName. A Service instance provides access to a HandlerResolver via a pair of getHandlerResolver / setHandlerResolver methods that may be used to configure a set of handlers on a per-service. or Dispatch instances. } /** * The getPort method returns a proxy. that may be used to extend the capabilities of a JAX-WS runtime system. The <code>serviceEndpointInterface</code> * specifies the service endpoint interface that is supported by * the created dynamic proxy instance.concurrent. Subsequent changes to the handler resolver configured for a Service instance do not affect the handlers on previously created proxies. The executor will then be used to invoke any asynchronous callbacks requested by the application. * In the implementation of this method.Executor. known as handlers.WildFly 8 Handler Resolver JAX-WS provides a flexible plug-in framework for message processing modules. /** * The getPort method returns a proxy. Class<T> serviceEndpointInterface) { . } JBoss Community Documentation Page 482 of 617 .... the JAX-WS * runtime system takes the responsibility of selecting a protocol * binding (and a port) and configuring the proxy accordingly. * The returned proxy should not be reconfigured by the client. A service client * uses this proxy to invoke operations on the target * service endpoint.util. The setExecutor and getExecutor methods of Service can be used to modify and retrieve the executor configured for a service. Executor Service instances can be configured with a java.

QName serviceName) { super(wsdlLocation. In this case. the type and value element will both refer to the generated service class type.localdomain:8080/jaxws-samples-webserviceref?wsdl") publicclass TestEndpointService extends Service { . 2. To define a reference whose type is a SEI. These methods also return dynamic proxies that implement the SEI.xml.jboss. JBoss Community Documentation Page 483 of 617 . publicclass EJB3Client implements EJB3Remote { @WebServiceRef public TestEndpointService service4. the type and value elements MAY have the default value (Object.class).getPort(TESTENDPOINTPORT.WildFly 8 The service endpoint interface (SEI) is usually generated using tools. overrides theWSDL location information specified in the WebService annotation of the referenced generated service class. that is). } @WebEndpoint(name = "TestEndpointPort") public TestEndpoint getTestEndpointPort() { return (TestEndpoint)super. public TestEndpointService(URL wsdlLocation. For details see Top Down (WSDL to Java) A generated static Service usually also offers typed methods to get ports. but the value element MUST always be present and refer to a generated service class type (a subtype of javax. serviceName). targetNamespace = "http://org. Moreover. @WebServiceRef public TestEndpoint port3. the type element MAY be present with its default value if the type of the reference can be inferred from the annotated field/method declaration. if present.ws/wsref".Resource annotation in JSR-250. if the reference type can be inferred by the field/method declaration the annotation is applied to..ws. } } WebServiceRef The @WebServiceRef annotation is used to declare a reference to a Web service. In this case.Service).. If the type cannot be inferred. To define a reference whose type is a generated service class.class.annotation. It follows the resource pattern exemplified by the javax. @WebServiceClient(name = "TestEndpointService". The wsdlLocation element. There are two uses to the WebServiceRef annotation: 1. then at least the type element MUST be present with a non-default value. TestEndpoint. wsdlLocation = "http://localhost.

createDispatch(portName.org/'/>". The Dispatch interface provides support for this mode of interaction.ws. a client application would work with the contents of the SOAP Body rather than the SOAP message as a whole.org/'/>". StreamSource.test. when used with a SOAP protocol binding.jboss.Service..PAYLOAD). serviceName).jaxws.xml.test.Service..Mode. identified by the constants javax. Dispatch is a low level API that requires clients to construct messages or message payloads as XML and requires an intimate knowledge of the desired message or payload structure. Service service = Service.class. The higher level JAX-WS APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages. client applications work with the payload of messages rather than the messages themselves. a client application would work directly with a SOAP message. String payload = "<ns1:ping xmlns:ns1='http://oneway.invokeOneWay(new StreamSource(new StringReader(payload))).samples. Message Payload In this mode. when used with a SOAP protocol binding. Dispatch supports two usage modes.PAYLOAD respectively: Message In this mode.MESSAGE and javax. but in some cases operating at the XML message level is desirable.WildFly 8 Dispatch XMLWeb Services use XML messages for communication between services and service clients. E. payload = "<ns1:feedback xmlns:ns1='http://oneway. dispatch. JBoss Community Documentation Page 484 of 617 .ws. Mode.invoke(new StreamSource(new StringReader(payload))). client applications work directly with protocol-specific message structures.g.g. Dispatch is a generic class that supports input and output of messages or message payloads of any type.ws.ws.jboss.Mode. Source retObj = (Source)dispatch.samples.xml.jaxws. E. Dispatch dispatch = service.create(wsdlURL.

echoAsync("Async").info("ping"). QName serviceName = new QName(targetNS. } } JBoss Community Documentation Page 485 of 617 . Service service = Service. @WebMethod @Oneway publicvoid ping() { log. Typically.create(wsdlURL. // access future String retStr = (String) response. BindingProvider instances may provide asynchronous operation capabilities.get(). Response response = port. asynchronous operation invocations are decoupled from the BindingProvider instance at invocation time such that the response context is not updated when the operation completes. Instead a separate response context is made available using the Response interface. return feedback.class).RPC) publicclass PingEndpointImpl { privatestatic String feedback. TestEndpoint port = service. public void testInvokeAsync() throws Exception { URL wsdlURL = new URL("http://" + getServerHost() + ":8080/jaxws-samples-asynchronous?wsdl").info("feedback"). } @WebMethod public String feedback() { log. it is implemented by proxies and is extended by the Dispatch interface. feedback = "ok". "TestEndpointService"). @WebService (name="PingEndpoint") @SOAPBinding(style = SOAPBinding.WildFly 8 Asynchronous Invocations The BindingProvider interface represents a component that provides a protocol binding for use by clients. When used. serviceName). } Oneway Invocations @Oneway indicates that the given web method has only an input message and no output. assertEquals("Async". retStr).Style.getPort(TestEndpoint. a oneway method returns the thread of control to the calling application prior to executing the actual business method.

Inbound messages are processed by handlers prior to binding provider processing. Handler Framework The handler framework is implemented by a JAX-WS protocol binding in both client and server side runtimes.handler. "1000").1. Different types of handlers are invoked with different types of message context. Handlers are invoked with a message context that provides methods to access and modify inbound and outbound messages and to manage a set of properties. //Set timeout until the response is received ((BindingProvider) port).put("javax. and Dispatch instances. Logical handlers are protocol agnostic and are unable to affect protocol specific parts of a message.receiveTimeout".echo("testTimeout").xml.ws. } 35.3 Common API This sections describes concepts that apply equally to Web Service Endpoints and Web Service Clients. The handlers within a handler chain are invoked each time a message is sent or received. Outbound messages are processed by handlers after any binding provider processing.LogicalHandler. known collectively as binding providers. "6000").put("javax. each use protocol bindings to bind their abstract functionality to specific protocols.xml.WildFly 8 Timeout Configuration There are two properties to configure the http connection timeout and client receive time out: public void testConfigureTimeout() throws Exception { //Set timeout until a connection is established ((BindingProvider)port).connectionTimeout".ws. Logical Handler Handlers that only operate on message context properties and message payloads.ws. Client and server-side handlers are organized into an ordered list known as a handler chain.client. JBoss Community Documentation Page 486 of 617 .getRequestContext().xml. port.getRequestContext(). Proxies. Message context properties may be used to facilitate communication between individual handlers and between handlers and client and service implementations. Logical handlers are handlers that implement javax.client.

. (ex: http://myhandlers. handlers are defined using the @HandlerChain annotation. bindingProvider.xml) Service client handlers On the client side.class). // important! JBoss Community Documentation Page 487 of 617 . A relative path from the source file or class file.handler. An absolute java.xml.handler.ws.foo.com/handlerfile1.Handler except javax. serviceName).xml") publicclass SOAPEndpointSourceImpl { . List<Handler> handlerChain = new ArrayList<Handler>(). (ex: bar/handlerfile1.ws.add(new LogHandler()). Protocol handlers are handlers that implement any interface derived from javax.WildFly 8 Protocol Handler Handlers that operate on message context properties and protocol specific messages. handlerChain. Endpoint port = (Endpoint)service. Protocol handlers are specific to a particular protocol and may access and change protocol specific aspects of a message.add(new AuthorizationHandler()).xml. BindingProvider bindingProvider = (BindingProvider)port..add(new RoutingHandler()).setHandlerChain(handlerChain). handlerChain.net. handlerChain.xml) 2. Service service = Service.getBinding().LogicalHandler.URL in externalForm.getPort(Endpoint. @WebService @HandlerChain(file = "jaxws-server-source-handlers. Service endpoint handlers On the service endpoint.create(wsdlURL. handler can be configured using the @HandlerChain annotation on the SEI or dynamically using the API. } The location of the handler chain file supports 2 formats 1.

1) and service endpoint implementations.2. The defaultscope for a property is HANDLER.. SOAPMessageContext extends MessageContext with methods to obtain and modify the SOAP message payload.g. that property will also be available to any protocol handlers in the chain during the execution of an MEP instance. APPLICATION scoped properties are also made available to client applications (see section 4. It extends Map<String. The SOAP binding defines that a logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message. A protocol binding defines what component of a message are available via a logical message context. if a logical handler puts a property in the message context. JBoss Community Documentation Page 488 of 617 . E. LogicalMessageContext extends MessageContext with methods to obtain and modify the message payload.Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example. Properties are scoped as either APPLICATION or HANDLER. Logical Message Context Logical Handlers are passed a message context of type LogicalMessageContext when invoked. a handler may use the put method to insert a property in the message context that one or more other handlers in the handler chain may subsequently obtain via the get method.WildFly 8 Message Context MessageContext is the super interface for all JAX-WS message contexts. it does not provide access to the protocol specific aspects of amessage. All properties are available to all handlers for an instance of an MEP on a particular endpoint. SOAP Message Context SOAP handlers are passed a SOAPMessageContext when invoked.

It is used to capture the name of the fault element used when marshalling the JAXB type generated from the global element referenced by the WSDL fault message. see section 2.addChildElement("test"). thrownew SOAPFaultException(fault).4 WS Annotations For details. JBoss Community Documentation Page 489 of 617 . whether a provider wants to have access to protocol message payloads (e.createFault("this is a fault string!".xml. SOAPFault fault = factory.5.e.Java API for XML-Based Web Services (JAX-WS) 2.ServiceMode The ServiceMode annotation is used to specify the mode for a provider class.1. see JSR-224 .WebFault The WebFault annotation is used when mapping WSDL faults to Java exceptions. "Some validation error").WildFly 8 Fault Handling An implementation may thow a SOAPFaultException public void throwSoapFaultException() { SOAPFactory factory = SOAPFactory.ws. } In case of the latter. 123.g. fault. It can also be used to customize the mapping of service specific exceptions to WSDL faults. javax. } or an application specific user exception public void throwApplicationException() throws UserException { thrownew UserException("validation".g.newInstance(). a SOAP envelope).2 javax.xml.actor"). JBossWS generates the required fault wrapper beans at runtime if they are not part of the deployment 35.addDetail().ws. "FooCode")). a SOAP body) or the entire protocol messages (e. new QName("http://foo". fault. i.setFaultActor("mr.

this annotation is used to resolve overloading conflicts in document literal mode.xml.BindingType The BindingType annotation is applied to an endpoint implementation class.xml.ws. javax.xml. The WebServiceProvider and WebService annotations are mutually exclusive. It is used to capture the JAXB generated request wrapper bean and the element name and namespace for marshalling / unmarshalling the bean.ws. The default value of localName element is the operationName as defined in WebMethod annotation and the default value for the targetNamespace element is the target namespace of the SEI.When starting from Java.ws. It is used to associate a get method with a specific wsdl:port. It is used to capture the JAXB generated response wrapper bean and the element name and namespace for marshalling / unmarshalling the bean.Provider.1/HTTP one. javax.ws. Only the className element is required in this case. this annotation is used to resolve overloading conflicts in document literal mode.ws.WebEndpoint The WebEndpoint annotation is specified on the getPortName() methods of a generated service class (see 2.ResponseWrapper The ResponseWrapper annotation is applied to the methods of an SEI. javax.xml. It is used to declare that a class that satisfies the requirements for a provider (see 5. Only the className element is required in this case. javax. JBoss Community Documentation Page 490 of 617 .7). identify by a URL to a WSDL document and the qualified name of a wsdl:service element.1) does indeed define a Web service endpoint.xml. When starting from Java. javax.xml.xml. much like the WebService annotation does for SEI-based endpoints.WebServiceClient The WebServiceClient annotation is specified on a generated service class (see 2.ws. identified by its local name (a NCName). It specifies the binding to use when publishing an endpoint of this type.WildFly 8 javax.WebServiceProvider The WebServiceProvider annotation is specified on classes that implement a strongly typed javax. It is used to associate a class with a specific Web service. The default binding for an endpoint is the SOAP 1.ws. The default value of the localName element is the operationName as defined in the WebMethod appended with ”Response” and the default value of the targetNamespace element is the target namespace of the SEI.7).RequestWrapper The RequestWrapper annotation is applied to the methods of an SEI.

JBoss Community Documentation Page 491 of 617 .1. each WebServiceRef annotation inside a WebServiceRefs MUST contain name and type elements with non-default values.ws.Action The Action annotation is applied to the methods of a SEI. This annotation follows the resource pattern exemplified by the javax. javax. 35. javax.annotation. javax.ws.xml.Resource annotation in JSR-250 [JBWS:32].xml. It is necessary to work around the limition against specifying repeated annotations of the same type on any given class.FaultAction The FaultAction annotation is used within the Action annotation to generate the wsa:Action element on the wsdl:fault element of each wsdl:operation mapped from the annotated methods.ws. For details. javax. The WebServiceRef annotation is required to be honored when running on the Java EE 5 platform. The WebServiceRef annotation is required to be honored when running on the Java EE 5 platform. see JSR 181 .xml.xml. which prevents listing multiple javax.WebMethod Customizes a method that is exposed as a Web Service operation.5 181 Annotations JSR-181 defines the syntax and semantics of Java Web Service (JWS) metadata and default values. or a Java interface as defining a Web Service interface.WebServiceRefs The WebServiceRefs annotation is used to declare multiple references to Web services on a single class.Resources annotation in JSR-250.WebServiceRef annotations one after the other. javax.jws.WebServiceRef The WebServiceRef annotation is used to declare a reference to a Web service.Web Services Metadata for the Java Platform. where it is subject to the common resource injection rules described by the platform specification [JBWS:33].WebService Marks a Java class as implementing a Web Service.jws.WildFly 8 javax.annotation.ws. It used to generate the wsa:Action on wsdl:input and wsdl:output of each wsdl:operation mapped from the annotated methods.ws. It follows the resource pattern exemplified by the javax. Since no name and type can be inferred in this case. where it is subject to the common resource injection rules described by the platform specification.

jws.x.style of RPC. Methods that do not have a SOAPBinding annotation accept the SOAPBinding behavior defined on the type.jws.SOAPBinding Specifies the mapping of the Web Service onto the SOAP message protocol. JBoss Community Documentation Page 492 of 617 . The annotation target includes METHOD and FIELD for use by JAX-WS-2.jws. 35. Implementations MUST report an error if the SOAPBinding annotation is placed on a method with a SOAPBinding.WildFly 8 javax. Typically. javax.WebResult Customizes the mapping of the return value to a WSDL part and XML element.OneWay Indicates that the given web method has only an input message and no output.HandlerChain The @HandlerChain annotation associates the Web Service with an externally defined handler chain. javax. The service implementation bean's @HandlerChain is used if @HandlerChain is present on both.WebParam Customizes the mapping of an individual parameter to a Web Service message part and XML element. and then proceed to the client.2 WS Tools The JAX-WS tools provided by JBossWS can be used in a variety of ways.jws.jws.style is DOCUMENT. javax. First we will look at server-side development strategies. declares any checked exceptions or has any INOUT or OUT parameters. The SOAPBinding annotation has a target of TYPE and METHOD. a oneway method returns the thread of control to the calling application prior to executing the actual business method. The @HandlerChain annotation MAY be present on the endpoint interface and service implementation bean. It is an error to combine this annotation with the @SOAPMessageHandlers annotation. javax. A JSR-181 processor is REQUIRED to report an error if an operation marked @Oneway has a return value. The annotation may be placed on a method if and only if the SOAPBinding. The @HandlerChain annotation MAY be specified on the type only.

a vender that calls you back using an already defined protocol). This can be as simple as creating a single class: JBoss Community Documentation Page 493 of 617 . For example. and provides the abstract contract.2.WildFly 8 35. Used for bottom-up development. and you can't break compatibility with older clients Exposing a service that conforms to a contract specified by a third party (e. or from the abstact contract (WSDL) that defines your service ( top-down development). so only the @WebService annotation is required. wsconsume Consumes the abstract contract (WSDL and Schema files).g. If this is a new service (no existing contract). you only need to add a few annotations to your classes to get a service up and running. However.1 Server side When developing a Web Service Endpoint (the server-side) you have the option of starting from Java ( bottom-up development). Bottom-up use cases: Exposing an already existing EJB3 bean as a Web Service Providing a new service. the bottom-up approach is the fastest route. Used for top-down and client development Bottom-Up (Using wsprovide) The bottom-up strategy involves developing the Java code for your service. and produces artifacts for both a server and client. and then annotating it using JAX-WS annotations. However. it is far simpler to use the top-down approach. Creating a service that adheres to the XML Schema and WSDL you developed by hand up front The following JAX-WS command line tools are included in JBossWS: Command Description wsprovide Generates JAX-WS portable artifacts. These annotations can be used to customize the contract that is generated for your service. if you are developing a service with an already defined contract. since the provided tool will generate the annotated code for you. all of the annotations have sensible defaults. you can change the operation name to map to anything you like. and you want the contract to be generated for you Top-down use cases: Replacing the implementation of an existing Web Service.

@javax.WildFly 8 package echo. we generate these as well. to generate portable JAX-WS artifacts.java $ wsprovide -w echo.Echo Generating WSDL: EchoService. this service defines one operation. which requires that wrapper classes be generated using an offline tool. if you want your deployment to be portable to other application servers.class echo/jaxws/EchoResponse. and since we do not believe in burdening a developer with a bunch of additional steps. "echo": <portType name='Echo'> <operation name='echo' parameterOrder='echo'> <input message='tns:Echo_echo'/> <output message='tns:Echo_echoResponse'/> </operation> </portType> JBoss Community Documentation Page 494 of 617 . and it is the only Java code needed to deploy on JBossWS.jar Echo. The WSDL. This is the primary purpose of the wsprovide tool.wsdl Writing Classes: echo/jaxws/Echo. you will unfortunately need to use a tool and add the generated classes to your deployment. } } A JSE or EJB3 deployment can be built using this class.class Inspecting the WSDL reveals a service called EchoService: <service name='EchoService'> <port binding='tns:EchoBinding' name='EchoPort'> <soap:address location='REPLACE_WITH_ACTUAL_URL'/> </port> </service> As expected.jws. -classpath jboss-jaxws. Additionally. This can be obtained by invoking wsprovide using the "-w" option: $ javac -d . The reason for this requirement is purely a vender implementation problem. However. This actually goes beyond the JAX-WS specification. it can be used to "provide" the abstract contract (WSDL file) for your service. and all other Java artifacts called "wrapper classes" will be generated for you at deploy time.WebService public class Echo { public String echo(String input) { return input.

class(in = 340) (out= 247)(deflated 27%) adding: WEB-INF/web.sun. and you are using the default settings.com/xml/ns/j2ee" xmlns:xsi="http://www. it should be available in the server management console.com/xml/ns/j2ee http://java. JBoss Community Documentation Page 495 of 617 . You only need it for generating portable artifacts and/or the abstract contract for your service.xsd" version="2.sun. which will generate the WSDL.WildFly 8 Remember that when deploying on JBossWS you do not need to run this tool.xml needs to be created: <web-app xmlns="http://java. For a portable JAX-WS deployment.xml(in = 576) (out= 271)(deflated 52%) The war can then be deployed to the JBoss Application Server.Echo</servlet-class> </servlet> <servlet-mapping> <servlet-name>Echo</servlet-name> <url-pattern>/Echo</url-pattern> </servlet-mapping> </web-app> The web.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java. this will internally invoke wsprovide.war WEB-INF added manifest adding: WEB-INF/(in = 0) (out= 0)(stored 0%) adding: WEB-INF/classes/(in = 0) (out= 0)(stored 0%) adding: WEB-INF/classes/echo/(in = 0) (out= 0)(stored 0%) adding: WEB-INF/classes/echo/Echo.sun. The wsconsume tool is then used to consume this contract. the wrapper classes generated earlier could be added to the deployment.com/xml/ns/j2ee/web-app_2_4. Down (Using wsconsume) The top-down development strategy begins with the abstract contract for the service. and produce annotated Java classes (and optionally sources) that define it. A simple web. If deployment was successful.The war can then be deployed to the JBoss Application Server.xml WEB-INF $ jar cvf echo. which includes the WSDL file and zero or more schema files.xml and the single class can now be used to create a war: $ mkdir -p WEB-INF/classes $ cp -rp echo WEB-INF/classes/ $ cp web. Let's create a POJO endpoint for deployment on WildFly.w3.4"> <servlet> <servlet-name>Echo</servlet-name> <servlet-class>echo.

java Holder for JAXB package annotations EchoService.wsdl echo/Echo. instead of providing just classes: $ wsconsume -k EchoService. however.java echo/ObjectFactory.java echo/Echo.java Wrapper bean for request message EchoResponse.java echo/package-info.java echo/Echo_Type.java JAXB XML Registry package-info.java echo/EchoResponse.java echo/EchoService.java Service Endpoint Interface Echo_Type.java echo/ObjectFactory.java Used only by JAX-WS clients Examining the Service Endpoint Interface reveals annotations that are more explicit than in the class written by hand in the bottom-up example.java The following table shows the purpose of each generated file: File Purpose Echo.java Wrapper bean for response message ObjectFactory.java echo/EchoResponse.java echo/EchoService.java echo/Echo_Type.WildFly 8 wsconsume may have problems with symlinks on Unix systems Using the WSDL file from the bottom-up example.java echo/package-info. The "-k" option is passed to wsconsume to preserve the Java source files that are generated. a new Java implementation that adheres to this service can be generated. these evaluate to the same contract: JBoss Community Documentation Page 496 of 617 .

Echo_Type") @ResponseWrapper(localName = "echoResponse". the recommended methodology for developing a client is to follow the top-down approach. even if the client is running on the same server. for whatever reason. instead of the one generated offline by wsprovide.WebService(endpointInterface="echo. even though they can be used in this way. targetNamespace = "http://echo/") public interface Echo { @WebMethod @WebResult(targetNamespace = "") @RequestWrapper(localName = "echo". className = "echo. package echo. which can now be written. your software does not adhere to this principal. or written in any particular programming language. running on any particular OS.EchoResponse") public String echo( @WebParam(name = "arg0". targetNamespace = "http://echo/". although using the deployed WSDL. then you should not be using Web Services. This value must be computed at deploy time. } The only missing piece (besides for packaging) is the implementation class. @javax. There are much better technologies for this (CORBA. So because of this. className = "echo. Offline version: JBoss Community Documentation Page 497 of 617 . using the above interface. If.WildFly 8 @WebService(name = "Echo". The reason why we do this is just to get the right value for soap:address. since it is based on container configuration specifics. } } 35. and RMI for example). For the above reasons. Web Services were designed specifically for interoperable coarse-grained correspondence. There is no expectation or guarantee that any party participating in a Web Service interaction will be at any particular location. it is important to clearly separate client and server implementations. Web Services are not the best fit for internal RPC. You could of course edit the WSDL file yourself.2 Client Side Before going to detail on the client-side it is important to understand the decoupling concept that is central to Web Services.jws. targetNamespace = "") String arg0). Let's repeat the process of the top-down section. although you need to ensure that the path is correct. targetNamespace = "http://echo/". The only thing they should have in common is the abstract contract definition.Echo") public class EchoImpl implements Echo { public String echo(String arg0) { return arg0.2.

java echo/Echo_Type.WildFly 8 <service name='EchoService'> <port binding='tns:EchoBinding' name='EchoPort'> <soap:address location='REPLACE_WITH_ACTUAL_URL'/> </port> </service> Online version: <service name="EchoService"> <port binding="tns:EchoBinding" name="EchoPort"> <soap:address location="http://localhost.java echo/ObjectFactory.java echo/EchoService.localdomain:8080/echo/Echo"/> </port> </service> Using the online deployed version with wsconsume: $ wsconsume -k http://localhost:8080/echo/Echo?wsdl echo/Echo.java echo/EchoResponse.java echo/package-info.java. was EchoService.java echo/EchoResponse.java echo/EchoService.java echo/Echo_Type.java echo/ObjectFactory. JBoss Community Documentation Page 498 of 617 .java The one class that was not examined in the top-down section. Notice how it stores the location the WSDL was obtained from.java echo/Echo.java echo/package-info.

Instead. javax. or use the URL version of the constructor to provide a new WSDL location.class). This causes network I/O every time you instantiate the Service Object.printStackTrace(). } catch (MalformedURLException e) { e. The only method we really care about is the getEchoPort() method. } } As you can see. While you can use Service directly. static { URL url = null. } public EchoService(URL wsdlLocation.xml. Any WS operation can then be called by just invoking a method on the returned interface. this generated class extends the main client entry point in JAX-WS.Service. wsdlLocation = "http://localhost:8080/echo/Echo?wsdl") public class EchoService extends Service { private final static URL ECHOSERVICE_WSDL_LOCATION. QName serviceName) { super(wsdlLocation. All that is left to do. "EchoService")). try { url = new URL("http://localhost:8080/echo/Echo?wsdl"). which returns an instance of our Service Endpoint Interface. It's not recommended to refer to a remote WSDL URL in a production application. targetNamespace = "http://echo/". serviceName). Echo. is write and compile the client: JBoss Community Documentation Page 499 of 617 . "EchoPort").ws. new QName("http://echo/". } public EchoService() { super(ECHOSERVICE_WSDL_LOCATION.WildFly 8 @WebServiceClient(name = "EchoService".getPort(new QName("http://echo/". this is far simpler since it provides the configuration info for you. } @WebEndpoint(name = "EchoPort") public Echo getEchoPort() { return (Echo)super. } ECHOSERVICE_WSDL_LOCATION = url. use the tool on a saved local copy.

} EchoService service = new EchoService(). bp.getRequestContext(). BindingProvider bp = (BindingProvider)echo. Command Line Tool The command line tool has the following usage: JBoss Community Documentation Page 500 of 617 .*. System.out.ENDPOINT_ADDRESS_PROPERTY. Echo echo = service.echo(args0)).WildFly 8 import echo.length != 1) { System. endpointURL). setting the ENDPOINT_ADDRESS_PROPERTY as shown below: EchoService service = new EchoService().println("Server said: " + echo. 35.getEchoPort().put(BindingProvider. /* Set NEW Endpoint Location */ String endpointURL = "http://NEW_ENDPOINT_URL".out. Echo echo = service.err. System.3 wsconsume wsconsume is a command line tool and ant task that "consumes" the abstract contract (WSDL file) and produces portable JAX-WS service and client artifacts.println("usage: EchoClient <message>"). System. public class EchoClient { public static void main(String args[]) { if (args.2.println("Server said: " + echo.echo(args0)).getEchoPort().exit(1). } } It is easy to change the endpoint address of your operation at runtime.

--nocompile Do not compile generated sources The wsdlLocation is used when creating the Service to be used by clients and will be added to the @WebServiceClient annotation. --extension Enable SOAP 1. --source=<directory> The directory to put Java source -t. JBoss Community Documentation Page 501 of 617 .2 binding extension -a. --help Show this help message -b. --load-consumer Load the consumer and exit (debug utility) -e.2> The JAX-WS specification target -q.WildFly 8 usage: wsconsume [options] <wsdl-url> options: -h. --additionalHeaders Enables processing of implicit SOAP headers -n. --verbose Show full exception stack traces -l. --target=<2. --quiet Be somewhat more quiet -v. for an endpoint implementation based on the generated service endpoint interface you will need to manually add the wsdlLocation to the @WebService annotation on your web service implementation and not the service endpoint interface. --binding=<file> One or more JAX-WS or JAXB binding files -k.1|2. --keep Keep/Generate Java source -c --catalog=<file> Oasis XML Catalog file for entity resolution -j --clientjar=<name> Create a jar file of the generated artifacts for calling the webservice -p --package=<name> The target package for generated source -w --wsdlLocation=<loc> Value to use for @WebServiceClient. --output=<directory> The directory to put generated artifacts -s.wsdlLocation -o.0|2.

wsconsume and wsconsume-test. The plugin has two goals for running the tool.wsdl Generate source and class files using multiple binding files: wsconsume -k -b wsdl-binding. The wsconsume plugin has the following parameters: JBoss Community Documentation Page 502 of 617 .xml Maven Plugin The wsconsume tools is included in the org.wsdl Generate source and class files in the org.foo Example.xml -b schema2-binding.foo package: wsconsume -k -p org.wsdl Generate source and class files in a custom directory: wsconsume -k -o custom Example.ws.xml -b schema1-binding.wsdl Generate source and class files: wsconsume -k Example. which basically do the same during different maven build phases (the former triggers the sources generation during generate-sources phase.WildFly 8 Examples Generate artifacts in Java class form only: wsconsume Example. the latter during the generate-test-sources one).plugins:maven-jaxws-tools-plugin plugin.jboss.

wsdl file and generate SEI and wrappers' java sources.outputDirectory} or ${project. The following example makes the plugin consume the test.dirs=..xml file.build.wsdlLocation generated outputDirectory The output directory for generated artifacts.</argLine> fork Whether or not to run the generation task in a separate false VM.build. target A preference for the JAX-WS specification target Depends on the underlying stack and endorsed dirs if any Examples You can use wsconsume in your own project build simply referencing the maven-jaxws-tools-plugin in the configured plugins in your pom. ${project. ${project.. wsdls The WSDL files or URLs to consume n/a extension Enable SOAP 1. etc. can be used to set endorse dir. Example <argLine>-Djava. The generated sources are then compiled together with the other project classes. enable debugging.WildFly 8 Attribute Description Default bindingFiles JAXWS or JAXB binding file true classpathElements Each classpathElement provides a library file to be added to classpath ${project. generated bindingFiles One or more JAX-WS or JAXB binding file none wsdlLocation Value to use for @WebServiceClient.endorsed. false argLine An optional additional argline to be used when running in none fork mode. JBoss Community Documentation Page 503 of 617 .2 binding extension.testOutputDirectory} sourceDirectory The output directory for Java source.directory}/wsconsume/jav verbose Enables more informational output about command false progress.build.compileClasspathElements} or ${project.testClasspathElements} catalog Oasis XML Catalog file for entity resolution none targetPackage The target Java package for generated code.

wsdl</wsdl> </wsdls> <targetPackage>foo.wsdl</wsdl> <wsdl>${basedir}/test2. you might want to use the wsconsume-test goal as follows: JBoss Community Documentation Page 504 of 617 . as well as force the target package.plugins</groupId> <artifactId>maven-jaxws-tools-plugin</artifactId> <version>1.1.2 binding and turn the tool's verbose mode on: <build> <plugins> <plugin> <groupId>org.wsdl</wsdl> </wsdls> </configuration> <executions> <execution> <goals> <goal>wsconsume</goal> </goals> </execution> </executions> </plugin> </plugins> </build> You can also specify multiple wsdl files.plugins</groupId> <artifactId>maven-jaxws-tools-plugin</artifactId> <version>1.GA</version> <configuration> <wsdls> <wsdl>${basedir}/test.WildFly 8 <build> <plugins> <plugin> <groupId>org.GA</version> <configuration> <wsdls> <wsdl>${basedir}/test.jboss.bar</targetPackage> <extension>true</extension> <verbose>true</verbose> </configuration> <executions> <execution> <goals> <goal>wsconsume</goal> </goals> </execution> </executions> </plugin> </plugins> </build> Finally.0.0. enable SOAP 1.ws.ws.jboss.1. if the wsconsume invocation is required for consuming a wsdl to be used in your testsuite only.

WSConsumeTask) has the following attributes: JBoss Community Documentation Page 505 of 617 .ws.0.wsdl</wsdl> </wsdls> </configuration> <executions> <execution> <goals> <goal>wsconsume-test</goal> </goals> </execution> </executions> </plugin> </plugins> </build> Plugin stack dependencyThe plugin itself does not have an explicit dependency to a JBossWS stack. The plugin will rely on the that for using the proper tooling.GA</version> </dependency> </dependencies> Be careful when using this plugin with the Maven War Plugin as that include any project dependency into the generated application war archive.xml to the desired JBossWS stack version. as it's meant for being used with implementations of any supported version of the JBossWS SPI.plugins</groupId> <artifactId>maven-jaxws-tools-plugin</artifactId> <version>1. You might want to set <scope>provided</scope> for the JBossWS stack dependency to avoid that.ws. <dependencies> <dependency> <groupId>org.tools.GA</version> <configuration> <wsdls> <wsdl>${basedir}/test.0.1.WildFly 8 <build> <plugins> <plugin> <groupId>org. Ant Task The wsconsume Ant task (org.jboss. So the user is expected to set a dependency in his own pom.ant.jboss.0.ws.cxf</groupId> <artifactId>jbossws-cxf-client</artifactId> <version>4.jboss.

generated binding A JAX-WS or JAXB binding file none wsdlLocation Value to use for @WebServiceClient. false additionalHeaders Enables processing of implicit SOAP headers false Users also need to put streamBuffer. Also.2 binding extension.wsdlLocation generated destdir The output directory for generated artifacts. value of destdir target The JAX-WS specification target. true keep Keep/Enable Java source code generation.2 verbose Enables more informational output about command progress. 2. for an endpoint implementation based on the generated service endpoint interface you will need to manually add the wsdlLocation to the @WebService annotation on your web service implementation and not the service endpoint interface. "output" sourcedestdir The output directory for Java source.1 and 2. The wsdlLocation is used when creating the Service to be used by clients and will be added to the @WebServiceClient annotation. false catalog Oasis XML Catalog file for entity resolution none package The target Java package for generated code. the following nested elements are supported: Element Description Default binding A JAXWS or JAXB binding file none jvmarg Allows setting of custom jvm arguments JBoss Community Documentation Page 506 of 617 . Allowed values are 2.0.jar to the classpath of the ant task to generate the appropriate artefacts.WildFly 8 Attribute Description Default fork Whether or not to run the generation task in a separate VM. false wsdl The WSDL file or URL n/a extension Enable SOAP 1.jar and stax-ex.

wsdl: <wsconsume fork="true" verbose="true" destdir="output" sourcedestdir="gen-src" keep="true" wsdllocation="handEdited. JBoss Community Documentation Page 507 of 617 .2.xml" excludes="bad.wsdl"> <binding dir="binding-files" includes="*.xml"/> </wsconsume> 35. It also has the option to "provide" the abstract contract for offline usage. and a list of binding files from foo.wsdl" wsdl="foo.WildFly 8 Examples Generate JAX-WS source and classes in a separate JVM with separate directories. Maven plugin and Ant task that generates portable JAX-WS artifacts for a service endpoint implementation. a custom wsdl location attribute.4 wsprovide wsprovide is a command line tool.

--quiet Be somewhat more quiet -t.plugins:maven-jaxws-tools-plugin plugin.jar:application2. --help Show this help message -k.jboss.2 binding extension -q. --keep Keep/Generate Java source -w.jar foo. --source=<directory> The directory to put Java source -e.Endpoint Maven Plugin The wsprovide tools is included in the org. --address The generated port soap:address in wsdl -c. which basically do the same during different Maven build phases (the former triggers the sources generation during process-classes phase. --show-traces Show full exception stack traces Examples Generating wrapper classes for portable artifacts in the "generated" directory: wsprovide -o generated foo. --extension Enable SOAP 1.WildFly 8 Command Line Tool The command line tool has the following usage: usage: wsprovide [options] <endpoint class name> options: -h. --resource=<directory> The directory to put resource artifacts -s. wsprovide and wsprovide-test. --output=<directory> The directory to put generated artifacts -r. the latter during the process-test-classes one). The plugin has two goals for running the tool. The wsprovide plugin has the following parameters: JBoss Community Documentation Page 508 of 617 .Endpoint Using an endpoint that references other jars wsprovide -o generated -c application1.Endpoint Generating wrapper classes and WSDL in the "generated" directory wsprovide -o generated -w foo. --wsdl Enable WSDL file generation -a. --classpath=<path> The classpath that contains the endpoint -o.ws.

xml file.build. extension Enable SOAP 1.directory}/wsprovide/java source. The following example makes the plugin provide the wsdl file and artifact sources for the specified endpoint class: JBoss Community Documentation Page 509 of 617 . sourceDirectory The output directory for Java ${project.outputDirectory} artifacts.2 binding false extension. Examples You can use wsprovide in your own project build simply referencing the maven-jaxws-tools-plugin in the configured plugins in your pom. portSoapAddress The generated port soap:address in the WSDL endpointClass Service Endpoint Implementation. or ${project.testOutputDirectory} resourceDirectory The output directory for resource ${project.testClasspathElements} classpath outputDirectory The output directory for generated ${project.compileClasspathElements} a or library file to be added to ${project.build.WildFly 8 Attribute Description testClasspathElements Each classpathElement provides Default ${project. generateWsdl Whether or not to generate false WSDL. verbose Enables more informational output false about command progress.build.directory}/wsprovide/resources artifacts (WSDL/XSD).build.

GA</version> <configuration> <verbose>true</verbose> <endpointClass>org.tools.WildFly 8 <build> <plugins> <plugin> <groupId>org.jboss.0. but is meant for use in your own testsuite: <build> <plugins> <plugin> <groupId>org.jboss.1.ws. So the user is expected to set a dependency in his ownpom. as it's meant for being used with implementations of any supported version of the JBossWS SPI.1.plugins.GA</version> <configuration> <verbose>true</verbose> <endpointClass>org.plugins</groupId> <artifactId>maven-jaxws-tools-plugin</artifactId> <version>1.ws.ws. The plugin will rely on the that for using the proper tooling.xml to the desired JBossWS stack version.wsprovide.TestEndpoint2</endpointClass> <generateWsdl>true</generateWsdl> </configuration> <executions> <execution> <goals> <goal>wsprovide-test</goal> </goals> </execution> </executions> </plugin> </plugins> </build> Plugin stack dependencyThe plugin itself does not have an explicit dependency to a JBossWS stack.jboss.TestEndpoint</endpointClass> <generateWsdl>true</generateWsdl> </configuration> <executions> <execution> <goals> <goal>wsprovide</goal> </goals> </execution> </executions> </plugin> </plugins> </build> The following example does the same.test.jboss.plugins.tools.plugins</groupId> <artifactId>maven-jaxws-tools-plugin</artifactId> <version>1.test.0. JBoss Community Documentation Page 510 of 617 .wsprovide.ws.

ws.WildFly 8 <dependencies> <dependency> <groupId>org. You might want to set <scope>provided</scope> for the JBossWS stack dependency to avoid that.cxf</groupId> <artifactId>jbossws-cxf-client</artifactId> <version>4.GA</version> </dependency> </dependencies> Be careful when using this plugin with the Maven War Plugin as that include any project dependency into the generated application war archive. JBoss Community Documentation Page 511 of 617 .jboss.0.0.

" false Examples Executing wsprovide in verbose mode with separate output directories for source. verbose Enables more informational output about command progress.jaxws.jsr181.ws.2 binding extension. "output" resourcedestdir The output directory for resource artifacts (WSDL/XSD).ws.ant.DocWrappedServiceImpl"> <classpath> <pathelement path="${tests.WSProvideTask) has the following attributes: Attribute Description Default fork Whether or not to run the generation task in a separate VM. classpath The classpath that contains the service endpoint implementation.WildFly 8 Ant Task The wsprovide ant task (org. false genwsdl Whether or not to generate WSDL.jboss.jboss. value of destdir extension Enable SOAP 1. false destdir The output directory for generated artifacts. ".soapbinding.dir}/classes"/> </classpath> </wsprovide> </target> JBoss Community Documentation Page 512 of 617 .WSProvideTask"> <classpath refid="core. and classes: <target name="test-wsproivde" depends="init"> <taskdef name="wsprovide" classname="org.jboss. value of destdir sourcedestdir The output directory for Java source.tools.classpath"/> </taskdef> <wsprovide fork="false" keep="true" destdir="out" resourcedestdir="out-resource" sourcedestdir="out-source" genwsdl="true" verbose="true" sei="org. false address The generated port soap:address in wsdl.output.test. resources.ant. sei Service Endpoint Implementation.tools.ws. true keep Keep/Enable Java source code generation.

the handler can be added to the desired client/endpoints (programmatically / using @HandlerChain JAX-WS annotation).1 Logging Logging of inbound and outbound messages is a common need. Different approaches are available for achieving that: WS Handler approach A portable way of performing logging is writing a simple JAX-WS handler dumping the messages that are passed in it. JBoss Community Documentation Page 513 of 617 .WildFly 8 35.3.3 Advanced User Guide Logging JAX-WS Handler approach Apache CXF approach System property Manual interceptor addition and logging feature WS-* support Address rewrite Server configuration options Dynamic rewrite Configuration through deployment descriptor context-root element config-name and config-file elements property element port-component element webservice-description element Schema validation of SOAP messages JAXB Introductions 35. The predefined client and endpoint configuration mechanism allows user to add the logging handler to any client/endpoint or to some of them only (in which case the @EndpointConfig annotation / JBossWS API is required though).

35. Finally. Those interceptors can be added to client. the system property is easily set by adding what follows to the standalone / domain server configuration just after the extensions section: <system-properties> <property name="org.cxf.3.apache.apache.LoggingFeature that can be used on clients and endpoints (either annotating them with @org.enabled system property to true causes the logging interceptors to be added to any Bus instance being created on the JVM. Please refer to the Apache CXF documentation for more details.WildFly 8 Apache CXF approach Apache CXF also comes with logging interceptors that can be easily used to log messages to the console or configured client/server log files. the whole WS-Security Policy framework is fully supported.cxf.apache. In details information available further down in this documentation book.apache.enabled" value="true"/> </system-properties> Manual interceptor addition and logging feature Logging interceptors can be selectively added to endpoints using the Apache CXF annotations @org.2 * support JBossWS includes most of the WS-* specification functionalities through the integration with Apache CXF.logging.Logging).apache. Alternatively. The same is achieved on client side by programmatically adding new instances of the logging interceptors to the client or the bus. enabling full contract driven configuration of complex features like WS-Security.OutInterceptors. the interceptors and feature can also be configured using Spring descriptors when Spring is available for the JBossWS-CXF integration on the application server.Features or directly with @org. In particular.apache.cxf.apache.logging.cxf.feature.interceptor.feature.cxf. JBoss Community Documentation Page 514 of 617 .InInterceptors and @org. Apache CXF also comes with a org.cxf.interceptor.annotations. On WildFly.cxf. endpoint and buses in multiple ways: System property Setting the org.

undefined.address} can be used to set the address which the application is bound to at each startup. Server configuration options The configuration options are part of the webservices subsystem section of the application server domain model. JBossWS allows for both the soap:address in the wsdl and the wsdl address in the console to be rewritten with the host use in the client request.com/xml/ns/javaee" xmlns:jaxwsconfig="urn:jboss:jbossws-jaxws-config:4.undefined.WildFly 8 35. JBoss Community Documentation Page 515 of 617 .3. JBossWS will not rewrite it unless modify-wsdl-address is true.1" xmlns:javaee="http://java. To trigger this behaviour. Dynamic rewrite When the application server is bound to multiple addresses or non-trivial real-world network architectures cause request for different external addresses to hit the same endpoint. the ports will be identified by querying the list of installed connectors.bind. The wsdl-secure-port and wsdl-port attributes are used to explicitly define the ports to be used for rewriting the SOAP address.sun.host</wsdl-host> <modify-wsdl-address>true</modify-wsdl-address> Of course. <subsystem xmlns="urn:jboss:domain:webservices:1. If these attributes are not set. This way. the addresses are always rewritten using https protocol and the port currently configured for the https/ssl connector.3 Address rewrite JBossWS allows users to configure the soap:address attribute in the wsdl contract of deployed services. If the content of <soap:address> is not a valid URL instead. a static rewrite of the soap:address may not be enough. the jbossws.0"> <wsdl-host>localhost</wsdl-host> <modify-wsdl-address>true</modify-wsdl-address> <!-<wsdl-port>8080</wsdl-port> <wsdl-secure-port>8443</wsdl-secure-port> --> </subsystem> If the content of <soap:address> in the wsdl is a valid URL. when a confidential transport address is required. users always get the right wsdl address assuming they're connecting to an instance having the endpoint they're looking for. Please note that the variable ${jboss. <wsdl-host>jbossws. JBossWS will always rewrite it using the attribute values given below.host value has to be specified for the wsdl-host element. If multiple connectors are found the port of the first connector is used.

xml for POJO webservice deployments and EJB webservice endpoints bundled in war archives The structure of file is the following (schemas are available here): <webservices> <context-root/>? <config-name/>? <config-file/>? <property>* <name/> <value/> </property> <port-component>* <ejb-name/> <port-component-name/> <port-component-uri/>? <auth-method/>? <transport-guarantee/>? <secure-wsdl-access/>? </port-component> <webservice-description>* <webservice-description-name/> <wsdl-publish-location/>? </webservice-description> </webservices> context-root element Element <context-root> can be used to customize context root of webservices deployment.xml for EJB webservice deployments WEB-INF/jboss-webservices.4 Configuration through deployment descriptor The jboss-webservices. <webservices> <context-root>foo</context-root> </webservices> JBoss Community Documentation Page 516 of 617 .3.WildFly 8 35.xml deployment descriptor can be used to provide additional configuration for a given deployment. The expected location of it is: META-INF/jboss-webservices.

For further details on the endpoint configurations and their management in the domain model. Allowed property names and values are mentioned in the guide under related topics. <property> <name>prop. Endpoint configuration are either specified in the referenced config file or in the WildFly domain model (webservices subsystem).xml</config-file> </webservices> property element <property> elements can be used to setup simple property values to configure the ws stack behavior. <webservices> <port-component> <ejb-name>TestService</ejb-name> <port-component-name>TestServicePort</port-component-name> <port-component-uri>/*</port-component-uri> <auth-method>BASIC</auth-method> <transport-guarantee>NONE</transport-guarantee> <secure-wsdl-access>true</secure-wsdl-access> </port-component> </webservices> JBoss Community Documentation Page 517 of 617 .WildFly 8 config-name and config-file elements Elements <config-name> and <config-file> can be used to associate any endpoint provided in the deployment with a given endpoint configuration. <webservices> <config-name>Standard WSSecurity Endpoint</config-name> <config-file>META-INF/custom.value</value> </property> port-component element Element <port-component> can be used to customize EJB endpoint target URI or to configure security related properties.name</name> <value>prop. please see the related documentation.

<webservices> <webservice-description> <webservice-description-name>TestService</webservice-description-name> <wsdl-publish-location>file:///bar/foo.WildFly 8 webservice-description element Element <webservice-description> can be used to customize (override) webservice WSDL publish location.wsdl</wsdl-publish-location> </webservice-description> </webservices> JBoss Community Documentation Page 518 of 617 .

or using the @org. true).cxf.apache... Schema validation can be turned on programmatically on client side ((BindingProvider)proxy).3. } Alternatively.SchemaValidation..put("schema-validation-enabled"..WildFly 8 35.SchemaValidation annotation on server side import javax.5 Schema validation of SOAP messages Apache CXF has a feature for validating incoming and outgoing SOAP messages on both client and server side.annotations.apache. Finally. The validation is performed against the relevant schema in the endpoint wsdl contract (server side) or the wsdl contract used for building up the service proxy (client side). @WebService(. any endpoint and client running in-container can be associated to a JBossWS predefined configuration having the schema-validation-enabled property set to true in the referenced config file.WebService.cxf.jws.. <client-config name="Standard-Client-Config"> <property name="schema-validation-enabled" value="true"/> </client-config> </subsystem> JBoss Community Documentation Page 519 of 617 .annotations.getRequestContext(). import org...) @SchemaValidation public class ValidatingHelloImpl implements Hello { . JBossWS also allows for server-wide (default) setup of schema validation by using the Standard-Endpoint-Config and Standard-Client-Config special configurations (which apply to any client / endpoint unless a different configuration is specified for them) <subsystem xmlns="urn:jboss:domain:webservices:1..2"> . <endpoint-config name="Standard-Endpoint-Config"> <property name="schema-validation-enabled" value="true"/> </endpoint-config> .

The scenario is this: you are trying to annotate your classes with JAXB annotations to make it XML bindable. but some of the classes are coming from libraries and JDK.WildFly 8 35. using which users can define annotations in XML and make JAXB see those as if those were in the class files (perhaps coming from 3rd party libraries). This is currently leveraged by the JBoss JAXB Introductions project. Take a look at the JAXB Introductions page on the wiki and at the examples in the sources. To solve this JAXB has been designed to provide hooks for programmatic introduction of annotations to the runtime. one common complaint from the JAXB users is the lack of support for binding 3rd party classes. JBoss Community Documentation Page 520 of 617 . and thus you cannot put necessary JAXB annotations on it.3.6 JAXB Introductions As Kohsuke Kawaguchi wrote on his blog.

and POST handler chains are executed after those objects have executed. Properties Key/value properties are used for controlling both some Apache CXF internals and some JBossWS options. Configurations defined in an application are local to the application. There can be many endpoint configuration definitions in the webservice subsystem and in an application. Handlers Each endpoint configuration may be associated with zero or more PRE and POST handler chains. --> Client The same applies for client configurations. * Server inbound messages Client --> . JBoss Community Documentation Page 521 of 617 ...api.7 Predefined client and endpoint configurations Overview JBossWS enables extra setup configuration data to be predefined and associated with an endpoint.WildFly 8 35. Each handler chain may include JAXWS handlers.. Endpoint implementations declare the use of a specific configuration through the used of the org. such as with annotation @HandlerChain.. For inbound messages the POST handler chains are executed before any handler that is attached to the endpoint using the standard means and the PRE handler chains are executed after those objects have executed. For outbound messages the PRE handler chains are executed before any handler that is attached to the endpoint using the standard means.annotation.3. Predefined endpoint configurations can be used for JAX-WS client and JAX-WS endpoint setup. --> POST HANDLER --> ENDPOINT HANDLERS --> PRE HANDLERS --> Endpoint * Server outbound messages Endpoint --> PRE HANDLER --> ENDPOINT HANDLERS --> POST HANDLERS --> . Endpoint configurations can include JAX-WS handlers and key/value properties declarations that control JBossWS and Apache CXF internals. An endpoint configuration defined in an application must be referenced by deployment descriptor file name and the configuration name in the annotation. Each endpoint configuration must have a name that is unique within the server.jboss. Endpoint configurations can be defined in the webservice subsystem and in a deployment descriptor file within the application. An endpoint configuration defined in the webservices subsystem is available to all deployed applications on the system and can be referenced by name in the annotation.ws. Specific supported values are mentioned where relevant in the rest of the documentation.EndpointConfig annotation.

The configuration name is not referencable by endpoint implementations outside the application.WildFly 8 Assigning configurations Endpoint configuration assignment Annotation. The file must reside in directory WEB-INF for a web application and directory META-INF for a client and EJB application. configName = "Custom WS-Security Endpoint") public class ServiceImpl implements ServiceIface { public String sayHello() { return "Secure Hello World!". The file name must end with extension . the relative path to the deployment descriptor and the configuration name must be specified. When assigning a configuration that is defined in the application. Each configuration must have a name that is unique within the server on which the application is deployed. When assigning a configuration that is defined in the webservices subsystem only the configuration name is specified.EndpointConfig is used to assign an endpoint configuration to a JAX-WS endpoint implementation.jboss. JBoss Community Documentation Page 522 of 617 .api.xml but this is not required.ws.xml". All endpoint configuration definitions for a given archive must be provided in a single deployment descriptor file. } } Endpoint Configuration Deployment Descriptor Java EE archives that can contain JAX-WS endpoint implementations can also contain predefined endpoint configurations.annotation. Many endpoint configurations can be defined within the deployment descriptor file. org. @EndpointConfig(configFile = "WEB-INF/jaxws-endpoint-config.xml and be an implementation of schema jbossws-jaxws-config Common practice is to use the file name jaxws-endpoint-config.

getPort(Endpoint.echo("Kermit"). Explicit setup Alternatively. true). . or .xml".api. a JAXWS Feature extension provided by JBossWS: import org.api.class..configuration. "Custom Client Config"))..getPort(Endpoint.jboss.. The configuration file must be found as a resource by the classloader of the current thread. serviceName)..class.xml"..WildFly 8 Client configuration assignment JAXWS Feature The most practical way of setting a configuration is using org. port = service.getPort(Endpoint.jboss. new ClientConfigFeature(null.echo("Kermit")..ClientConfigFeature. new ClientConfigFeature("META-INF/jaxws-client-config. "Custom Client Config").ws.echo("Kermit").create(wsdlURL.class. The jbossws-jaxws-config schema defines the descriptor contents and is included in the jbossws-spi artifact.ClientConfigFeature. Endpoint port = service. ... //reads from current container configurations if available port. Service service = Service. port = service. JAXWS handlers read from client configurations as follows: JBoss Community Documentation Page 523 of 617 .ws. JBossWS parses the specified configuration file. port. or .configuration. . new ClientConfigFeature("META-INF/jaxws-client-config. testConfigName)).... //setup properties too from the configuration port. JBossWS API comes with facility classes that can be used for assigning configurations when building a client.

. port. similarly. port.api. "Custom Client Config 2"). Endpoint port = service. "META-INF/jaxws-client-config.. configurer. "META-INF/jaxws-client-config.echo("Kermit").setConfigHandlers(bp..ws.WildFly 8 import org. ClientConfigUtil.class). "META-INF/jaxws-client-config. .setConfigHandlers(bp. //reads from current container configurations if available port. .configuration.xml".ClientConfigUtil. import org. configurer.echo("Kermit")..setConfigHandlers(bp. "Custom Client Config 1").ws. port. Service service = Service.jboss. "Container Custom Client Config").api..create(wsdlURL. null. "Custom Client Config 3").xml".echo("Kermit"). .configuration. properties are read from client configurations as follows: JBoss Community Documentation Page 524 of 617 . .. serviceName)...resolveClientConfigurer().jboss.setConfigHandlers(bp. .getPort(Endpoint.xml". ClientConfigurer configurer = ClientConfigUtil..ClientConfigurer.echo("Kermit"). configurer. BindingProvider bp = (BindingProvider)port..

ws...class).echo("Kermit"). if any. .ws..echo("Kermit"). The jbossws-jaxws-config schema defines the descriptor contents and is included in the jbossws-spi artifact.echo("Kermit"). . "Custom Client Config 2").configuration. The default ClientConfigurer implementation parses the specified configuration file. . configurer. null. port. serviceName). Service service = Service.jboss.api.api.. "META-INF/jaxws-client-config. port.ClientConfigUtil. JBoss Community Documentation Page 525 of 617 . configurer.. ClientConfigUtil.resolveClientConfigurer(). Endpoint port = service.xml".xml".setConfigProperties(port.. . "Container Custom Client Config"). "META-INF/jaxws-client-config. "Custom Client Config 1").setConfigProperties(port.setConfigProperties(port.getPort(Endpoint.echo("Kermit").xml"... //reads from current container configurations if available port. ClientConfigurer configurer = ClientConfigUtil.WildFly 8 import org. after having resolved it as a resources using the current thread context classloader.configuration. "Custom Client Config 3"). port. configurer.create(wsdlURL. "META-INF/jaxws-client-config.jboss.ClientConfigurer. import org.setConfigProperties(port.

Those are used unless different configurations are set as previously described.jboss.integration:main module classloader. Standard configurations Clients running in-container as well as endpoints are assigned standard configurations by default. As a consequence it is possible to declare server-wide handlers to be added to the chain of each endpoint or client assigned to a given configuration.WildFly 8 Application server configurations WildFly allows declaring JBossWS client and server predefined configurations in the webservices subsystem section of the server model.. The allowed contents in the webservices subsystem are defined by the schema included in the application server. Examples JBoss AS 7. please note the handler class needs to be available either through each ws deployment classloader or the org. Handlers classloading When setting a server-wide handler.. to be used in the WildFly webservices subsystem are Standard-Client-Config and Standard-Endpoint-Config.webservices.RecordingServerHandler"/> </pre-handler-chain> </endpoint-config> <client-config name="Standard-Client-Config"/> </subsystem> JBoss Community Documentation Page 526 of 617 .jboss.server..2 default configurations <subsystem xmlns="urn:jboss:domain:webservices:1. remove or modify handlers and properties. As a consequence proper module dependencies might need to be specified either in the deployments that are going to leverage a given predefined configuration or directly in the previously mentioned AS7 module.2"> <!-. The name for such default configuration.ws.invocation.common.as. This way administrators can tune default handler chains for client and endpoints developers did not assign a specific configuration to. --> <endpoint-config name="Standard-Endpoint-Config"/> <endpoint-config name="Recording-Endpoint-Config"> <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM"> <handler name="RecordingHandler" class="org. Please refer to the webservices subsystem documentation for any detail on managing the webservices subsystem to add.

org/2001/XMLSchema-instance" xmlns:javaee="http://java.jboss.policy. --> <client-config name="Standard-Client-Config"> <property name="schema-validation-enabled" value="true"/> </client-config> </subsystem> 35.signature.encryption.username</property-name> <property-value>alice</property-value> </property> <property> <property-name>ws-security.3...callback-handler</property-name> <property-value>org. --> <endpoint-config name="Standard-Endpoint-Config"> <property name="schema-validation-enabled" value="true"/> </endpoint-config> <!-.signature..KeystorePasswordCallback</property-value> </property> </endpoint-config> </jaxws-config> JBoss AS 7.properties</property-name> <property-value>bob.wsse.properties</property-value> </property> <property> <property-name>ws-security.basic.com/xml/ns/javaee" xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.2"> <!-.test.sun.properties</property-name> <property-value>bob.samples. JBoss Community Documentation Page 527 of 617 .WildFly 8 A configuration file for a deployment specific ws-security endpoint setup <jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.username</property-name> <property-value>bob</property-value> </property> <property> <property-name>ws-security.jaxws.xsd"> <endpoint-config> <config-name>Custom WS-Security Endpoint</config-name> <property> <property-name>ws-security..w3.ws.2 default configurations modified to default to SOAP messages schema-validation on <subsystem xmlns="urn:jboss:domain:webservices:1.properties</property-value> </property> <property> <property-name>ws-security..8 Authentication This page explains the simplest way to authenticate a web service user with JBossWS..encryption.0 schema/jbossws-jaxws-config_4_0.

..xml: <security-constraint> <web-resource-collection> <web-resource-name>All resources</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>friend</role-name> </auth-constraint> </security-constraint> <security-role> <role-name>friend</role-name> </security-role> Specify the security domain Next. @DenyAll annotation. specify the security domain for this deployment. JBoss Community Documentation Page 528 of 617 .. @Stateless @RolesAllowed("friend") public class EndpointEJB implements EndpointInterface { . The allowed user roles can be set with these annotations both on the bean class and on any of its business methods. } or modifying the jboss-web.WildFly 8 First we secure the access to the SLSB as we would do for normal (non web service) invocations: this can be easily done through the @RolesAllowed. This is performed using the @SecurityDomain annotation for EJB3 endpoints @Stateless @SecurityDomain("JBossWS") @RolesAllowed("friend") public class EndpointEJB implements EndpointInterface { .. @PermitAll. } Similarly POJO endpoints are secured the same way as we do for normal web applications in web.xml for POJO endpoints <jboss-web> <security-domain>JBossWS</security-domain> </jboss-web> The security domain as well as its the authentication and authorization mechanisms are defined differently depending on the application server version in use.

getPort(TestEndpoint. qname).USERNAME_PROPERTY.toURL(). port = (TestEndpoint)service. "kermit").put(BindingProvider.put(BindingProvider.ws. QName qname = new QName("http://org.PASSWORD_PROPERTY. authMethod="BASIC".getRequestContext(). Using HTTP Basic Auth for security To enable HTTP Basic authentication you use the @WebContext annotation on the bean class @Stateless @SecurityDomain("JBossWS") @RolesAllowed("friend") @WebContext(contextRoot="/my-cxt". transportGuarantee="NONE". "TestEndpointService")..jboss.xml adding the auth-method element: <login-config> <auth-method>BASIC</auth-method> <realm-name>Test Realm</realm-name> </login-config> JBoss Community Documentation Page 529 of 617 .WildFly 8 Use BindingProvider to set principal/credential A web service client may use the javax.BindingProvider interface to set the username/password combination URL wsdlURL = new File("resources/jaxws/samples/context/WEB-INF/wsdl/TestEndpoint. bp.ws/jaxws/context".wsdl").. bp. we modify the web. "thefrog").class).xml. Service service = Service.create(wsdlURL. secureWSDLAccess=false) public class EndpointEJB implements EndpointInterface { . BindingProvider bp = (BindingProvider)port.getRequestContext(). urlPattern="/*". } For POJO endpoints.

WildFly 8 35.3.9 Apache CXF integration JBossWS integration layer with Apache CXF Building WS applications the JBoss way Portable applications Direct Apache CXF API usage Spring descriptors usage Client side Server side Bus usage Creating a Bus instance Using existing Bus instances Bus selection strategies for JAXWS clients Thread bus strategy (THREAD_BUS) New bus strategy (NEW_BUS) Thread context classloader bus strategy (TCCL_BUS) Strategy configuration Server Side Integration Customization Deployment descriptor properties WorkQueue configuration Policy alternative selector MBean management Schema validation WS-Discovery enablement JBoss Community Documentation Page 530 of 617 .

Apache CXF basically parses Spring cxf. given direct Apache CXF API usage won't be very handy.WildFly 8 JBossWS integration layer with Apache CXF All JAX-WS functionalities provided by JBossWS on top of JBoss Application Server are currently served through a proper integration of the JBoss Web Services stack with most of the Apache CXF project modules. This said.xml descriptors. In the next sections a list of technical suggestions and notes on the integration is provided. with services speaking a variety of protocols such as SOAP and XML/HTTP over a variety of transports such as HTTP and JMS. without Spring. Apache CXF is an open source services framework. this is performed internally leveraging Apache CXF without requiring the user to deal with it. nowadays almost any Apache CXF functionality can be configured and used through direct API usage. Similar reasoning applies on client side. JBoss Community Documentation Page 531 of 617 . please also refer to the Apache CXF official documentation for in-depth details on the CXF architecture. Apache CXF can be used to deploy webservice endpoints on any servlet container by including its libraries in the deployment. Building WS applications the JBoss way The Apache CXF client and endpoint configuration as explained in the Apache CXF official user guide is heavily based on Spring. The integration layer (JBossWS-CXF in short hereafter) is mainly meant for: allowing using standard webservices APIs (including JAX-WS) on JBoss Application Server. where a Spring based descriptor offers a shortcut for setting up Apache CXF internals. It allows building and developing services using frontend programming APIs (including JAX-WS). those may contain any basic bean plus specific ws client and endpoint beans which CXF has custom parsers for. the JBossWS-CXF integration supports the JBoss ws endpoint deployment mechanism and comes with many internal customizations on top of Apache CXF. In order for achieving the goals above. in such a scenario Spring basically serves as a convenient configuration option. allowing using Apache CXF advanced features (including WS-*) on top of JBoss Application server without requiring the user to deal with / setup / care about the required integration steps for running in such a container.

the installation of Spring Framework libraries on application server is the suggested approach. That can be performed using the JBossWS-CXF installation script or by manually populating a org.xml descriptor for such a module please refer the relevant JBoss AS documentation on creating modules. As a consequence of the reasoning above. users might still want to consume Spring descriptors ( discouraged approach). Generally speaking. WS-Addressing. no need for embedding any Apache CXF or any ws related dependency library in user deployments.xml descriptor described below on this page. The following two paragraphs provide few directions on how to deploy or use applications explicitly relying on Apache CXF.. in any case it would look similar to: JBoss Community Documentation Page 532 of 617 .springframework. users should however prefer the portable application approach whenever possible. The WS-* related sections of this documentation cover all the details on configuring applications making use of WS-* through policies. For writing the module. JBoss Application Server already comes with a JAX-WS compliant implementation. in some cases. it actually provides users with a fully compliant target platform for Java EE applications.WildFly 8 Portable applications The JBoss Application Server is much more then a servlet container. so that client and endpoint configuration is basically a matter of setting few ws context properties.) should also be configured in the most portable way.spring JBoss AS module with the required Spring