Development Guide

Procedure 1.14. Replace the Default Welcome Web Application With Your Own Web Application

1. Disable the Welcome application.

   Use the Management CLI script EAP_HOME/bin/jboss-cli.sh to run the following command. You may need to change the profile to modify a different managed domain profile, or remove the /profile=default portion of the command for a standalone server.

   /profile=default/subsystem=web/virtual-server=default-host:write-attribute(name=enable-welcome-root,value=false)

2. Configure your Web application to use the root context.

   To configure your web application to use the root context (/) as its URL address, modify its jboss-web.xml, which is located in the META-INF/ or WEB-INF/ directory. Replace its <context-root> directive with one that looks like the following.

   <jboss-web>
       <context-root>/</context-root>
   </jboss-web>

3. Deploy your application.

   Deploy your application to the server group or server you modified in the first step. The application is now available on http://SERVER_URL:PORT/.

1. Go to Apache Maven Project - Download Maven and download the latest distribution for your operating system.
2. See the Maven documentation for information on how to download and install Apache Maven for your operating system.

Procedure 2.1. Download and Install the JBoss EAP 6 Maven Repository to the Local File System

1. Open a web browser and access this URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform.
2. Find "Red Hat JBoss Enterprise Application Platform 6.3.0 Maven Repository" in the list.
3. Click the Download button to download a .zip file containing the repository.
4. Unzip the file on the local file system into a directory of your choosing.
5. Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”.

Procedure 2.2. Download the JBoss EAP 6 Maven Repository ZIP archive

1. Open a web browser and access this URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform.
2. Find "Red Hat JBoss Enterprise Application Platform 6.3.0 Maven Repository" in the list.
3. Click the Download button to download a .zip file containing the repository.
4. Unzip the files in a directory that is web accessible on the Apache server.
5. Configure Apache to allow read access and directory browsing in the created directory.
6. Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”.

Procedure 2.3. Download the JBoss EAP 6 Maven Repository ZIP archive

1. Open a web browser and access this URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform.
2. Find "Red Hat JBoss Enterprise Application Platform 6.3.0 Maven Repository" in the list.
3. Click the Download button to download a .zip file containing the repository.
4. Unzip the files into a directory of your choosing on the server hosting Nexus.

Procedure 2.4. Add the JBoss EAP 6 Maven Repository using Nexus Maven Repository Manager

1. Log into Nexus as an Administrator.
2. Select the Repositories section from the Views → Repositories menu to the left of your repository manager.
3. Click the Add... dropdown, then select Hosted Repository.
4. Give the new repository a name and ID.
5. Enter the path on disk to the unzipped repository in the field Override Local Storage Location.
6. Continue if you want the artifact to be available in a repository group. Do not continue with this procedure if this is not what you want.
7. Select the repository group.
8. Click on the Configure tab.
9. Drag the new JBoss Maven repository from the Available Repositories list to the Ordered Group Repositories list on the left.

   Note

   Note that the order of this list determines the priority for searching Maven artifacts.
10. Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”.

Procedure 2.5. Configure Maven Settings to Use the JBoss EAP 6 Maven Repository

1. Configure the Maven repository using Maven settings

   This is the recommended approach. Maven settings used with a repository manager or repository on a shared server provide better control and manageability of projects. Settings also provide the ability to use an alternative mirror to redirect all lookup requests for a specific repository to your repository manager without changing the project files. For more information about mirrors, see http://maven.apache.org/guides/mini/guide-mirror-settings.html.
   This method of configuration applies across all Maven projects, as long as the project POM file does not contain repository configuration.
   Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”.

2. Configure the Maven repository using the project POM

   This method of configuration is generally not recommended. If you decide to configure repositories in your project POM file, plan carefully and be aware that it can slow down your build and you may even end up with artifacts that are not from the expected repository.

   Note

   In an Enterprise environment, where a repository manager is usually used, Maven should query all artifacts for all projects using this manager. Because Maven uses all declared repositories to find missing artifacts, if it can't find what it's looking for, it will try and look for it in the repository central (defined in the built-in parent POM). To override this central location, you can add a definition with central so that the default repository central is now your repository manager as well. This works well for established projects, but for clean or 'new' projects it causes a problem as it creates a cyclic dependency.

   Transitively included POMs are also an issue with this type of configuration. Maven has to query these external repositories for missing artifacts. This not only slows down your build, it also causes you to lose control over where your artifacts are coming from and likely to cause broken builds.
   This method of configuration overrides the global and user Maven settings for the configured project.
   Section 2.3.4, “Configure the JBoss EAP 6 Maven Repository Using the Project POM”.

Procedure 2.6. Configure Maven Using the Settings Shipped with the Quickstart Examples

1. This procedure overwrites the existing Maven settings file, so you must back up the existing Maven settings.xml file.
   1. Locate the Maven install directory for your operating system. It is usually installed in USER_HOME/.m2/ directory.

      • For Linux or Mac, this is: ~/.m2/
      • For Windows, this is: \Documents and Settings\USER_NAME\.m2\ or \Users\USER_NAME\.m2\
   2. If you have an existing USER_HOME/.m2/settings.xml file, rename it or make a backup copy so you can restore it later.
2. Download and unzip the quickstart examples that ship with JBoss EAP 6. For more information, see Section 1.4.1.1, “Access the Quickstarts”
3. Copy the QUICKSTART_HOME/settings.xml file to the USER_HOME/.m2/ directory.
4. If you modify the settings.xml file while Red Hat JBoss Developer Studio is running, follow the procedure below entitled Refresh the Red Hat JBoss Developer Studio User Settings.

Procedure 2.7. Manually Edit and Configure the Maven Settings To Use the Online JBoss EAP 6 Maven Repository

1. Locate the Maven install directory for your operating system. It is usually installed in USER_HOME/.m2/ directory.

   • For Linux or Mac, this is ~/.m2/
   • For Windows, this is \Documents and Settings\USER_NAME\.m2\ or \Users\USER_NAME\.m2\
2. If you do not find a settings.xml file, copy the settings.xml file from the USER_HOME/.m2/conf/ directory into the USER_HOME/.m2/ directory.
3. Copy the following XML into the <profiles> element of the file.

   <!-- Configure the JBoss GA Maven repository -->
   <profile>
     <id>jboss-ga-repository</id>
     <repositories>
       <repository>
         <id>jboss-ga-repository</id>
         <url>http://maven.repository.redhat.com/techpreview/all</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <id>jboss-ga-plugin-repository</id>
         <url>http://maven.repository.redhat.com/techpreview/all</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </pluginRepository>
     </pluginRepositories>
   </profile>
   <!-- Configure the JBoss Early Access Maven repository -->
   <profile>
     <id>jboss-earlyaccess-repository</id>
     <repositories>
       <repository>
         <id>jboss-earlyaccess-repository</id>
         <url>http://maven.repository.redhat.com/earlyaccess/all/</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <id>jboss-earlyaccess-plugin-repository</id>
         <url>http://maven.repository.redhat.com/earlyaccess/all/</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </pluginRepository>
     </pluginRepositories>
   </profile>
   

   Copy the following XML into the <activeProfiles> element of the settings.xml file.

   <activeProfile>jboss-ga-repository</activeProfile>
   <activeProfile>jboss-earlyaccess-repository</activeProfile>
   

4. If you modify the settings.xml file while Red Hat JBoss Developer Studio is running, follow the procedure below entitled Refresh the Red Hat JBoss Developer Studio User Settings.

Procedure 2.8. Configure the Settings to Use a Locally Installed JBoss EAP Repository

1. Locate the Maven install directory for your operating system. It is usually installed in USER_HOME/.m2/ directory.

   • For Linux or Mac, this is ~/.m2/
   • For Windows, this is \Documents and Settings\USER_NAME\.m2\ or \Users\USER_NAME\.m2\
2. If you do not find a settings.xml file, copy the settings.xml file from the USER_HOME/.m2/conf/ directory into the USER_HOME/.m2/ directory.
3. Copy the following XML into the <profiles> element of the settings.xml file. Be sure to change the <url> to the actual repository location.

   <profile>
     <id>jboss-eap-repository</id>
     <repositories>
       <repository>
         <id>jboss-eap-repository</id>
         <name>JBoss EAP Maven Repository</name>
         <url>file:///path/to/repo/jboss-eap-6.x-maven-repository</url>
         <layout>default</layout>
         <releases>
           <enabled>true</enabled>
           <updatePolicy>never</updatePolicy>
         </releases>
         <snapshots>
           <enabled>false</enabled>
           <updatePolicy>never</updatePolicy>
         </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <id>jboss-eap-repository-group</id>
         <name>JBoss EAP Maven Repository</name>
         <url>
         file:///path/to/repo/jboss-eap-6.x-maven-repository
         </url>
         <layout>default</layout>
         <releases>
           <enabled>true</enabled>
           <updatePolicy>never</updatePolicy>
         </releases>
         <snapshots>
           <enabled>false</enabled>
           <updatePolicy>never</updatePolicy>
         </snapshots>
       </pluginRepository>
     </pluginRepositories>
   </profile>
   

   Copy the following XML into the <activeProfiles> element of the settings.xml file.

   <activeProfile>jboss-eap-repository</activeProfile>
   

4. If you modify the settings.xml file while Red Hat JBoss Developer Studio is running, follow the procedure below entitled Refresh the Red Hat JBoss Developer Studio User Settings.

Procedure 2.9. Refresh the Red Hat JBoss Developer Studio User Settings

1. From the menu, choose Window → Preferences.
2. In the Preferences Window, expand Maven and choose User Settings.
3. Click the Update Settings button to refresh the Maven user settings in Red Hat JBoss Developer Studio.
   

   Figure 2.1. Update Maven User Settings

Procedure 2.10. Configure Maven in Red Hat JBoss Developer Studio

1. Click Window→Preferences, expand JBoss Tools and select JBoss Maven Integration.
   

   Figure 2.2. JBoss Maven Integration Pane in the Preferences Window

2. Click Configure Maven Repositories.
3. Click Add Repository to configure the JBoss GA Tech Preview Maven repository. Complete the Add Maven Repository dialog as follows:
   1. Set the Profile ID, Repository ID, and Repository Name values to jboss-ga-repository.
   2. Set the Repository URL value to http://maven.repository.redhat.com/techpreview/all.
   3. Click the Active by default checkbox to enable the Maven repository.
   4. Click OK
   

   Figure 2.3. Add Maven Repository - JBoss Tech Preview

4. Click Add Repository to configure the JBoss Early Access Maven repository. Complete the Add Maven Repository dialog as follows:
   1. Set the Profile ID, Repository ID, and Repository Name values to jboss-earlyaccess-repository.
   2. Set the Repository URL value to http://maven.repository.redhat.com/earlyaccess/all/.
   3. Click the Active by default checkbox to enable the Maven repository.
   4. Click OK
   

   Figure 2.4. Add Maven Repository - JBoss Early Access

5. Review the repositories and click Finish.
   

   Figure 2.5. Review Maven Repositories

6. You are prompted with the message "Are you sure you want to update the file 'MAVEN_HOME/settings.xml'?". Click Yes to update the settings. Click OK to close the dialog.
   The JBoss EAP Maven repository is now configured for use with Red Hat JBoss Developer Studio.

1. Open your project's pom.xml file in a text editor.
2. Add the following repository configuration. If there is already a <repositories> configuration in the file, then add the <repository> element to it. Be sure to change the <url> to the actual repository location.

   <repositories>
      <repository>
         <id>jboss-eap-repository-group</id>
         <name>JBoss EAP Maven Repository</name>
         <url>file:///path/to/repo/jboss-eap-6.3.0-maven-repository/</url>
         <layout>default</layout>
         <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
         </releases>
         <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
         </snapshots>
      </repository>
   </repositories>
   

3. Add the following plug-in repository configuration. If there is already a <pluginRepositories> configuration in the file, then add the <pluginRepository> element to it.

   <pluginRepositories>
      <pluginRepository>
         <id>jboss-eap-repository-group</id>
         <name>JBoss EAP Maven Repository</name>
         <url>file:///path/to/repo/jboss-eap-6.3.0-maven-repository/</url>
         <releases>
            <enabled>true</enabled>
         </releases>
         <snapshots>
            <enabled>true</enabled>
         </snapshots>
      </pluginRepository>
   </pluginRepositories>
   

Procedure 2.11. Update the Maven Repository

1. Open a browser and log into https://access.redhat.com.
2. Select Downloads from the menu at the top of the page.
3. Find Red Hat JBoss Enterprise Application Platform in the list and click on it.
4. Select the correct version of JBoss EAP from the Version drop-down menu that appears on this screen, then click on Patches.
5. Find Red Hat JBoss Enterprise Application Platform 6.3 CPx Incremental Maven Repository in the list and click Download.
6. You are prompted to save the ZIP file to a directory of your choice. Choose a directory and save the file.
7. Locate the path to JBoss EAP Maven repository, referred to in the commands below as EAP_MAVEN_REPOSITORY_PATH, for your operating system. For more information about how to install the Maven repository on the local file system, see Section 2.2.3, “Install the JBoss EAP 6 Maven Repository Locally”.
8. Unzip the Maven patch file directly into the installation directory of the JBoss EAP 6.3.x Maven repository.
   • For Linux, open a terminal and type the following command:

     [standalone@localhost:9999 /] unzip -o jboss-eap-6.3.x-incremental-maven-repository.zip -d EAP_MAVEN_REPOSITORY_PATH

   • For Windows, use the Windows extraction utility to extract the ZIP file into the root of the EAP_MAVEN_REPOSITORY_PATH directory.

1. Add the deployment descriptor file

   Add the jboss-deployment-structure.xml deployment descriptor file to the META-INF directory of the EAR if it doesn't already exist and add the following content:

   <jboss-deployment-structure>
   
   </jboss-deployment-structure>

2. Add the <ear-subdeployments-isolated> element

   Add the <ear-subdeployments-isolated> element to the jboss-deployment-structure.xml file if it doesn't already exist with the content of false.

   <ear-subdeployments-isolated>false</ear-subdeployments-isolated>

1. Add imports

   Add the import statements for the JBoss Logging class namespaces that you will be using. At a minimum you will need to import import org.jboss.logging.Logger.

   import org.jboss.logging.Logger;

2. Create a Logger object

   Create an instance of org.jboss.logging.Logger and initialize it by calling the static method Logger.getLogger(Class). Red Hat recommends creating this as a single instance variable for each class.

   private static final Logger LOGGER = Logger.getLogger(HelloWorld.class);

3. Add logging messages

   Add calls to the methods of the Logger object to your code where you want it to send log messages. The Logger object has many different methods with different parameters for different types of messages. The easiest to use are:

   debug(Object message)

   info(Object message)

   error(Object message)

   trace(Object message)

   fatal(Object message)

   These methods send a log message with the corresponding log level and the message parameter as a string.

   LOGGER.error("Configuration file not found.");

   For the complete list of JBoss Logging methods refer to the org.jboss.logging package in the JBoss EAP 6 API Documentation.

Procedure 5.1. Add Configuration File to the Application

• The directory into which the configuration file is added depends on the deployment method: EAR, WAR or JAR.

  • EAR deployment

    Copy the logging configuration file to the META-INF directory.

  • WAR or JAR deployment

    Copy the logging configuration file to either the META-INF or WEB-INF/classes directory.

Procedure 5.2. Add Logging Profile configuration to an Application

• Edit MANIFEST.MF

  If your application does not have a MANIFEST.MF file: create one with the following content, replacing NAME with the required profile name.

  Manifest-Version: 1.0
  Logging-Profile: NAME

  If your application already has a MANIFEST.MF file: add the following line to it, replacing NAME with the required profile name.

  Logging-Profile: NAME

Procedure 7.1. Create an EJB Project in Red Hat JBoss Developer Studio

1. Create new project

   To open the New EJB Project wizard, navigate to the File menu, select New, and then EJB Project.
   

   Figure 7.1. New EJB Project wizard

2. Specify Details

   Supply the following details:
   • Project name.
     As well as the being the name of the project that appears in Red Hat JBoss Developer Studio this is also the default filename for the deployed JAR file.
   • Project location.
     The directory where the project's files will be saved. The default is a directory in the current workspace.
   • Target Runtime.
     This is the server runtime used for the project. This will need to be set to the same JBoss EAP 6 runtime used by the server that you will be deploying to.
   • EJB module version. This is the version of the EJB specification that your enterprise beans will comply with. Red Hat recommends using 3.1.
   • Configuration. This allows you to adjust the supported features in your project. Use the default configuration for your selected runtime.
   Click Next to continue.

3. Java Build Configuration

   This screen allows you to customize the directories will contain Java source files and the directory where the built output is placed.
   Leave this configuration unchanged and click Next.

4. EJB Module settings

   Check the Generate ejb-jar.xml deployment descriptor checkbox if a deployment descriptor is required. The deployment descriptor is optional in EJB 3.1 and can be added later if required.
   Click Finish and the project is created and will be displayed in the Project Explorer.
   

   Figure 7.2. Newly created EJB Project in the Project Explorer

5. Add Build Artifact to Server for Deployment

   Open the Add and Remove dialog by right-clicking on the server you want to deploy the built artifact to in the server tab, and select "Add and Remove".
   Select the resource to deploy from the Available column and click the Add button. The resource will be moved to the Configured column. Click Finish to close the dialog.
   

   Figure 7.3. Add and Remove dialog

Procedure 7.2. Create an EJB Archive project in Maven

1. Create the Maven project

   An EJB project can be created using Maven's archetype system and the ejb-javaee6 archetype. To do this run the mvn command with parameters as shown:

    mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=ejb-javaee6 

   Maven will prompt you for the groupId, artifactId, version and package for your project.

   [localhost]$ mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=ejb-javaee6
   [INFO] Scanning for projects...
   [INFO]                                                                         
   [INFO] ------------------------------------------------------------------------
   [INFO] Building Maven Stub Project (No POM) 1
   [INFO] ------------------------------------------------------------------------
   [INFO] 
   [INFO] >>> maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom >>>
   [INFO] 
   [INFO] <<< maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom <<<
   [INFO] 
   [INFO] --- maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom ---
   [INFO] Generating project in Interactive mode
   [INFO] Archetype [org.codehaus.mojo.archetypes:ejb-javaee6:1.5] found in catalog remote
   Define value for property 'groupId': : com.shinysparkly
   Define value for property 'artifactId': : payment-arrangments
   Define value for property 'version':  1.0-SNAPSHOT: : 
   Define value for property 'package':  com.shinysparkly: : 
   Confirm properties configuration:
   groupId: com.company
   artifactId: payment-arrangments
   version: 1.0-SNAPSHOT
   package: com.company.collections
   Y: : 
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 32.440s
   [INFO] Finished at: Mon Oct 31 10:11:12 EST 2011
   [INFO] Final Memory: 7M/81M
   [INFO] ------------------------------------------------------------------------
   [localhost]$

2. Add your enterprise beans

   Write your enterprise beans and add them to the project under the src/main/java directory in the appropriate sub-directory for the bean's package.

3. Build the project

   To build the project, run the mvn package command in the same directory as the pom.xml file. This will compile the Java classes and package the JAR file. The built JAR file is named artifactId-version.jar and is placed in the target/ directory.

Procedure 7.3. Create an EAR Project containing an EJB Project

1. Open the New EAR Application Project Wizard

   Navigate to the File menu, select New, then Project and the New Project wizard appears. Select Java EE/Enterprise Application Project and click Next.
   

   Figure 7.4. New EAR Application Project Wizard

2. Supply details

   Supply the following details:
   • Project name.
     As well as the being the name of the project that appears in Red Hat JBoss Developer Studio this is also the default filename for the deployed EAR file.
   • Project location.
     The directory where the project's files will be saved. The default is a directory in the current workspace.
   • Target Runtime.
     This is the server runtime used for the project. This will need to be set to the same JBoss EAP 6 runtime used by the server that you will be deploying to.
   • EAR version.
     This is the version of the Java Enterprise Edition specification that your project will comply with. Red Hat recommends using 6.
   • Configuration. This allows you to adjust the supported features in your project. Use the default configuration for your selected runtime.
   Click Next to continue.

3. Add a new EJB Module

   New Modules can be added from the Enterprise Application page of the wizard. To add a new EJB Project as a module follow the steps below:

   1. Add new EJB Module

      Click New Module, uncheck Create Default Modules checkbox, select the Enterprise Java Bean and click Next. The New EJB Project wizard appears.

   2. Create EJB Project

      New EJB Project wizard is the same as the wizard used to create new standalone EJB Projects and is described in Section 7.2.1, “Create an EJB Archive Project Using Red Hat JBoss Developer Studio”.
      The minimal details required to create the project are:
      • Project name
      • Target Runtime
      • EJB Module version
      • Configuration
      All the other steps of the wizard are optional. Click Finish to complete creating the EJB Project.
   The newly created EJB project is listed in the Java EE module dependencies and the checkbox is checked.

4. Optional: add an application.xml deployment descriptor

   Check the Generate application.xml deployment descriptor checkbox if one is required.

5. Click Finish

   Two new project will appear, the EJB project and the EAR project

6. Add Build Artifact to Server for Deployment

   Open the Add and Remove dialog by right-clicking in the Servers tab on the server you want to deploy the built artifact to in the server tab, and select Add and Remove.
   Select the EAR resource to deploy from the Available column and click the Add button. The resource will be moved to the Configured column. Click Finish to close the dialog.
   

   Figure 7.5. Add and Remove dialog

Procedure 7.4. Add an Deployment Descriptor to an EJB Project

1. Open the Project

   Open the project in Red Hat JBoss Developer Studio.

2. Add Deployment Descriptor

   Right-click on the Deployment Descriptor folder in the project view and select Generate Deployment Descriptor Stub.
   

   Figure 7.6. Adding a Deployment Descriptor

Procedure 7.5. Add Session Beans to a Project in Red Hat JBoss Developer Studio

1. Open the Project

   Open the project in Red Hat JBoss Developer Studio.

2. Open the "Create EJB 3.x Session Bean" wizard

   To open the Create EJB 3.x Session Bean wizard, navigate to the File menu, select New, and then Session Bean (EJB 3.x).
   

   Figure 7.7. Create EJB 3.x Session Bean wizard

3. Specify class information

   Supply the following details:
   • Project
     Verify the correct project is selected.
   • Source folder
     This is the folder that the Java source files will be created in. This should not usually need to be changed.
   • Package
     Specify the package that the class belongs to.
   • Class name
     Specify the name of the class that will be the session bean.
   • Superclass
     The session bean class can inherit from a super class. Specify that here if your session has a super class.
   • State type
     Specify the state type of the session bean: stateless, stateful, or singleton.
   • Business Interfaces
     By default the No-interface box is checked so no interfaces will be created. Check the boxes for the interfaces you wish to define and adjust the names if necessary.
     Remember that enterprise beans in a web archive (WAR) only support EJB 3.1 Lite and this does not include remote business interfaces.
   Click Next.

4. Session Bean Specific Information

   You can enter in additional information here to further customize the session bean. It is not required to change any of the information here.
   Items that you can change are:
   • Bean name.
   • Mapped name.
   • Transaction type (Container managed or Bean managed).
   • Additional interfaces can be supplied that the bean must implement.
   • You can also specify EJB 2.x Home and Component interfaces if required.

5. Finish

   Click Finish and the new session bean will be created and added to the project. The files for any new business interfaces will also be created if they were specified.

Procedure 7.6. Add a JMS-based Message-Driven Bean in Red Hat JBoss Developer Studio

1. Open the Create EJB 3.x Message-Driven Bean Wizard

   Go to File → New → Other. Select EJB/Message-Driven Bean (EJB 3.x) and click the Next button.
   

   Figure 7.9. Create EJB 3.x Message-Driven Bean Wizard

2. Specify class file destination details

   There are three sets of details to specify for the bean class here: Project, Java class, and message destination.

   Project

   • If multiple projects exist in the Workspace, ensure that the correct one is selected in the Project menu.
   • The folder where the source file for the new bean will be created is ejbModule under the selected project's directory. Only change this if you have a specific requirement.

   Java class

   • The required fields are: Java package and class name.
   • It is not necessary to supply a Superclass unless the business logic of your application requires it.

   Message Destination

   These are the details you must supply for a JMS-based Message-Driven Bean:

   • Destination name. This is the queue or topic name that contains the messages that the bean will respond to.
   • By default the JMS checkbox is selected. Do not change this.
   • Set Destination type to Queue or Topic as required.

   Click the Next button.

3. Enter Message-Driven Bean specific information

   The default values here are suitable for a JMS-based Message-Driven bean using Container-managed transactions.
   • Change the Transaction type to Bean if the Bean will use Bean-managed transactions.
   • Change the Bean name if a different bean name than the class name is required.
   • The JMS Message Listener interface will already be listed. You do not need to add or remove any interfaces unless they are specific to your applications business logic.
   • Leave the checkboxes for creating method stubs selected.
   Click the Finish button.

Procedure 7.7. Implement Property Substitution in an MDB Application

1. Configure the JBoss EAP server to enable property substitution.

   The JBoss EAP server must be configured to enable property substitution. To do this, set the <annotation-property-replacement> attribute in the ee subsystem of the server configuration file to true.
   1. Back up the server configuration file. The helloworld-mdb quickstart example requires the full profile for a standalone server, so this is the standalone/configuration/standalone-full.xml file. If you are running your server in a managed domain, this is the domain/configuration/domain.xml file.
   2. Start the JBoss EAP server with the full profile.
      For Linux:

      EAP_HOME/bin/standalone.sh -c standalone-full.xml

      For Windows:

      EAP_HOMEbin\standalone.bat -c standalone-full.xml

   3. Launch the Management CLI using the command for your operating system.
      For Linux:

      EAP_HOME/bin/jboss-cli.sh --connect

      For Windows:

      EAP_HOME\bin\jboss-cli.bat --connect

   4. Type the following command to enable annotation property substitution.

      /subsystem=ee:write-attribute(name=annotation-property-replacement,value=true) 

   5. You should see the following result:

      {"outcome" => "success"}

   6. Review the changes to the JBoss EAP server configuration file. The ee subsystem should now contain the following XML.

      <subsystem xmlns="urn:jboss:domain:ee:1.2">
          <spec-descriptor-property-replacement>false</spec-descriptor-property-replacement>
          <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
          <annotation-property-replacement>true</annotation-property-replacement>
      </subsystem>

2. Define the system properties.

   You can specify the system properties in the server configuration file or you can pass them as command line arguments when you start the JBoss EAP server. System properties defined in the server configuration file take precedence over those passed on the command line when you start the server.
   • Define the system properties in the server configuration file.
     1. Start the JBoss EAP server and Management API as described in the previous step.
     2. Use the following command syntax to configure a system property in the JBoss EAP server:

        /system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE) 

        For the helloworld-mdb quickstart, we configure the following system properties:

        /system-property=property.helloworldmdb.queue:add(value=java:/queue/HELLOWORLDMDBPropQueue)
        /system-property=property.helloworldmdb.topic:add(value=java:/topic/HELLOWORLDMDBPropTopic)
        /system-property=property.connection.factory:add(value=java:/ConnectionFactory)

     3. Review the changes to the JBoss EAP server configuration file. The following system properties should now appear in the after the <extensions>.

        <system-properties>
            <property name="property.helloworldmdb.queue" value="java:/queue/HELLOWORLDMDBPropQueue"/>
            <property name="property.helloworldmdb.topic" value="java:/topic/HELLOWORLDMDBPropTopic"/>
            <property name="property.connection.factory" value="java:/ConnectionFactory"/>
        </system-properties>

   • Pass the system properties as arguments on the command line when you start the JBoss EAP server in the form of -DPROPERTY_NAME=PROPERTY_VALUE. The following is an example of how to pass the arguments for the system properties defined in the previous step.

     EAP_HOME/bin/standalone.sh -c standalone-full.xml -Dproperty.helloworldmdb.queuejava:/queue/HELLOWORLDMDBPropQueue -Dproperty.helloworldmdb.topic=java:/topic/HELLOWORLDMDBPropTopic -Dproperty.connection.factory=java:/ConnectionFactory

3. Modify the code to use the system property substitutions.

   Replace hard-coded @ActivationConfigProperty and @Resource annotation values with substitutions for the newly defined system properties. The following are examples of how to change the helloworld-mdb quickstart to use the newly defined system property substitutions within the annotations in the source code.
   1. Change the @ActivationConfigProperty destination property value in the HelloWorldQueueMDB class to use the substitution for the system property. The @MessageDriven annotation should now look like this:

      @MessageDriven(name = "HelloWorldQueueMDB", activationConfig = {
          @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
          @ActivationConfigProperty(propertyName = "destination", propertyValue = "${property.helloworldmdb.queue}"),   
          @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge") })
      

   2. Change the @ActivationConfigProperty destination property value in the HelloWorldTopicMDB class to use the substitution for the system property. The @MessageDriven annotation should now look like this:

      @MessageDriven(name = "HelloWorldQTopicMDB", activationConfig = {
          @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Topic"),
          @ActivationConfigProperty(propertyName = "destination", propertyValue = "${property.helloworldmdb.topic}"),   
          @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge") })

   3. Change the @Resource annotations in the HelloWorldMDBServletClient class to use the system property substitutions. The code should now look like this:

      @Resource(mappedName = "${property.connection.factory}")
      private ConnectionFactory connectionFactory;
      
      @Resource(mappedName = "${property.helloworldmdb.queue}")   
      private Queue queue;
      
      @Resource(mappedName = "${property.helloworldmdb.topic}")
      private Topic topic;
      

   4. Modify the hornetq-jms.xml file to use the system property substitution values.

      <?xml version="1.0" encoding="UTF-8"?>
      <messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
          <hornetq-server>
              <jms-destinations>
                  <jms-queue name="HELLOWORLDMDBQueue">
                      <entry name="${property.helloworldmdb.queue}"/>
                  </jms-queue>
                  <jms-topic name="HELLOWORLDMDBTopic">
                      <entry name="${property.helloworldmdb.topic}"/>
                  </jms-topic>
              </jms-destinations>
          </hornetq-server>
      </messaging-deployment>

4. Deploy the application. The application will now use the values specified by the system properties for the @Resource and @ActivationConfigProperty property values.

Procedure 7.8. Add Maven Project Configuration for Remote Invocation of Session Beans

1. Add the required project dependencies

   The pom.xml for the project must be updated to include the necessary dependencies.

2. Add the jboss-ejb-client.properties file

   The JBoss EJB client API expects to find a file in the root of the project named jboss-ejb-client.properties that contains the connection information for the JNDI service. Add this file to the src/main/resources/ directory of your project with the following content.

   # In the following line, set SSL_ENABLED to true for SSL
   remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
   remote.connections=default
   # Uncomment the following line to set SSL_STARTTLS to true for SSL
   # remote.connection.default.connect.options.org.xnio.Options.SSL_STARTTLS=true
   remote.connection.default.host=localhost
   remote.connection.default.port = 4447
   remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false
   # Add any of the following SASL options if required
   # remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false
   # remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOPLAINTEXT=false
   # remote.connection.default.connect.options.org.xnio.Options.SASL_DISALLOWED_MECHANISMS=JBOSS-LOCAL-USER
   

   Change the host name and port to match your server. 4447 is the default port number. For a secure connection, set the SSL_ENABLED line to true and uncomment the SSL_STARTTLS line. The Remoting interface in the container supports secured and unsecured connections using the same port.

3. Add dependencies for the remote business interfaces

   Add the Maven dependencies to the pom.xml for the remote business interfaces of the session beans.

   <dependency>
      <groupId>org.jboss.as.quickstarts</groupId>
      <artifactId>jboss-ejb-remote-server-side</artifactId>
      <type>ejb-client</type>
      <version>${project.version}</version>
   </dependency>

Procedure 7.9. Obtain a Bean Proxy using JNDI and Invoke Methods of the Bean

1. Handle checked exceptions

   Two of the methods used in the following code (InitialContext() and lookup()) have a checked exception of type javax.naming.NamingException. These method calls must either be enclosed in a try/catch block that catches NamingException or in a method that is declared to throw NamingException. The ejb-remote quickstart uses the second technique.

2. Create a JNDI Context

   A JNDI Context object provides the mechanism for requesting resources from the server. Create a JNDI context using the following code:

   final Hashtable jndiProperties = new Hashtable();
   jndiProperties.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
   final Context context = new InitialContext(jndiProperties);

   The connection properties for the JNDI service are read from the jboss-ejb-client.properties file.

3. Use the JNDI Context's lookup() method to obtain a bean proxy

   Invoke the lookup() method of the bean proxy and pass it the JNDI name of the session bean you require. This will return an object that must be cast to the type of the remote business interface that contains the methods you want to invoke.

   
   final RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
       "ejb:/jboss-ejb-remote-server-side//CalculatorBean!" + 
       RemoteCalculator.class.getName());
   

   Session bean JNDI names are defined using a special syntax. For more information, see Section 7.8.1, “EJB JNDI Naming Reference” .

4. Invoke methods

   Now that you have a proxy bean object you can invoke any of the methods contained in the remote business interface.

   int a = 204;
   int b = 340;
   System.out.println("Adding " + a + " and " + b + " via the remote stateless calculator deployed on the server");
   int sum = statelessRemoteCalculator.add(a, b);
   System.out.println("Remote calculator returned sum = " + sum);

   The proxy bean passes the method invocation request to the session bean on the server, where it is executed. The result is returned to the proxy bean which then returns it to the caller. The communication between the proxy bean and the remote session bean is transparent to the caller.

Procedure 7.10. Configure an EJB Using a Map-Based Scoped Context

1. Set the Properties

   Configure the EJB client properties programmatically, specifying the same set of properties that are used in the standard jboss-ejb-client.properties file. To enable the scoped context, you must specify the org.jboss.ejb.client.scoped.context property and set its value to true. The following is an example that configures the properties programmatically.

   // Configure  EJB Client properties for the InitialContext
   Properties ejbClientContextProps = new Properties();
   ejbClientContextProps.put(“remote.connections”,”name1”);
   ejbClientContextProps.put(“remote.connection.name1.host”,”localhost”);
   ejbClientContextProps.put(“remote.connection.name1.port”,”4447”);
   // Property to enable scoped EJB client context which will be tied to the JNDI context
   ejbClientContextProps.put("org.jboss.ejb.client.scoped.context", “true”);
   

2. Pass the Properties on the Context Creation

   // Create the context using the configured properties
   InitialContext ic = new InitialContext(ejbClientContextProps);
   MySLSB bean = ic.lookup("ejb:myapp/ejb//MySLSBBean!" + MySLSB.class.getName());
   

Procedure 7.11. Create the Descriptor File to Configure the Container Interceptor

1. Create a jboss-ejb3.xml file in the META-INF directory of the EJB deployment.
2. Configure the container interceptor elements in the descriptor file.
   1. Use the urn:container-interceptors:1.0 namespace to specify configuration of container interceptor elements.
   2. Use the <container-interceptors> element to specify the container interceptors.
   3. Use the <interceptor-binding> elements to bind the container interceptor to the EJBs. The interceptors can be bound in either of the following ways:
      • Bind the interceptor to all the EJBs in the deployment using the * wildcard.
      • Bind the interceptor at the individual bean level using the specific EJB name.
      • Bind the interceptor at the specific method level for the EJBs.

      Note

      These elements are configured using the EJB 3.1 XSD in the same way it is done for Java EE interceptors.
3. Review the following descriptor file for examples of the above elements.

   Example 7.2. 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</interceptor-class>
               </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</interceptor-class>
               </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</interceptor-class>
                   <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</interceptor-class>
                       <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.MethodSpecificContainerInterceptor</interceptor-class>
                       <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ContainerInterceptorOne</interceptor-class>
                   </interceptor-order>
                   <method>
                       <method-name>echoInSpecificOrderOfContainerInterceptors</method-name>
                   </method>
               </jee:interceptor-binding>
           </ci:container-interceptors>
       </jee:assembly-descriptor>
   </jboss>
   
   

   The XSD for the urn:container-interceptors:1.0 namespace is available at EAP_HOME/docs/schema/jboss-ejb-container-interceptors_1_0.xsd.

Procedure 7.12. Change the Identity of the Security Context

1. Create the client side interceptor

   The client side interceptor must implement the org.jboss.ejb.client.EJBClientInterceptor interface. The interceptor must pass the requested identity through the context data map, which can be obtained via a call to EJBClientInvocationContext.getContextData(). The following is an example of client side interceptor code:

   public class ClientSecurityInterceptor implements EJBClientInterceptor {
   
       public void handleInvocation(EJBClientInvocationContext context) throws Exception {
           Principal currentPrincipal = SecurityActions.securityContextGetPrincipal();
   
           if (currentPrincipal != null) {
               Map<String, Object> contextData = context.getContextData();
               contextData.put(ServerSecurityInterceptor.DELEGATED_USER_KEY, currentPrincipal.getName());
           }
           context.sendRequest();
       }
   
       public Object handleInvocationResult(EJBClientInvocationContext context) throws Exception {
           return context.getResult();
       }
   }
   

   User applications can insert the interceptor into the interceptor chain in the EJBClientContext in one of the following ways:

   • Programmatically

     With this approach, you call the org.jboss.ejb.client.EJBClientContext.registerInterceptor(int order, EJBClientInterceptor interceptor) method and pass the order and the interceptor instance. The order determines where this client interceptor is placed in the interceptor chain.

   • ServiceLoader Mechanism

     With this approach, you create a META-INF/services/org.jboss.ejb.client.EJBClientInterceptor file and place or package it in the classpath of the client application. The rules for the file are dictated by the Java ServiceLoader Mechanism. This file is expected to contain a separate line for each fully qualified class name of the EJB client interceptor implementation. The EJB client interceptor classes must be available in the classpath. EJB client interceptors added using the ServiceLoader mechanism are added to the end of the client interceptor chain, in the order they are found in the classpath. The ejb-security-interceptors quickstart uses this approach.

2. Create and configure the server side container interceptor

   Container interceptor classes are simple Plain Old Java Objects (POJOs). They use the @javax.annotation.AroundInvoke to mark the method that will be invoked during the invocation on the bean. For more information about container interceptors, refer to: Section 7.6.1, “About Container Interceptors”.

   1. Create the container interceptor

      This interceptor receives the InvocationContext with the identity and requests the switch to that new identity. The following is an abridged version of the actual code example:

          public class ServerSecurityInterceptor {
      
          private static final Logger logger = Logger.getLogger(ServerSecurityInterceptor.class);
      
          static final String DELEGATED_USER_KEY = ServerSecurityInterceptor.class.getName() + ".DelegationUser";
      
          @AroundInvoke
          public Object aroundInvoke(final InvocationContext invocationContext) throws Exception {
              Principal desiredUser = null;
              UserPrincipal connectionUser = null;
      
              Map<String, Object> contextData = invocationContext.getContextData();
              if (contextData.containsKey(DELEGATED_USER_KEY)) {
                  desiredUser = new SimplePrincipal((String) contextData.get(DELEGATED_USER_KEY));
      
                  Collection<Principal> connectionPrincipals = SecurityActions.getConnectionPrincipals();
      
                  if (connectionPrincipals != null) {
                      for (Principal current : connectionPrincipals) {
                          if (current instanceof UserPrincipal) {
                              connectionUser = (UserPrincipal) current;
                              break;
                          }
                      }
      
                  } else {
                      throw new IllegalStateException("Delegation user requested but no user on connection found.");
                  }
              }
      
      
              ContextStateCache stateCache = null;
              try {
                  if (desiredUser != null && connectionUser != null
                      && (desiredUser.getName().equals(connectionUser.getName()) == false)) {
                      // The final part of this check is to verify that the change does actually indicate a change in user.
                      try {
                          // We have been requested to use an authentication token
                          // so now we attempt the switch.
                          stateCache = SecurityActions.pushIdentity(desiredUser, new OuterUserCredential(connectionUser));
                      } catch (Exception e) {
                          logger.error("Failed to switch security context for user", e);
                          // Don't propagate the exception stacktrace back to the client for security reasons
                          throw new EJBAccessException("Unable to attempt switching of user.");
                      }
                  }
      
                  return invocationContext.proceed();
              } finally {
                  // switch back to original context
                  if (stateCache != null) {
                      SecurityActions.popIdentity(stateCache);;
                  }
              }
          }
      

   2. Configure the container interceptor

      For information on how to configure server side container interceptors, refer to: Section 7.6.3, “Configure a Container Interceptor”.

3. Create the JAAS LoginModule

   This component is responsible for verifying that user is allowed to execute requests as the requested identity. The following abridged code examples show the methods that peform the login and validation:

       @SuppressWarnings("unchecked")
       @Override
       public boolean login() throws LoginException {
           if (super.login() == true) {
               log.debug("super.login()==true");
               return true;
           }
   
           // Time to see if this is a delegation request.
           NameCallback ncb = new NameCallback("Username:");
           ObjectCallback ocb = new ObjectCallback("Password:");
   
           try {
               callbackHandler.handle(new Callback[] { ncb, ocb });
           } catch (Exception e) {
               if (e instanceof RuntimeException) {
                   throw (RuntimeException) e;
               }
               return false; // If the CallbackHandler can not handle the required callbacks then no chance.
           }
   
           String name = ncb.getName();
           Object credential = ocb.getCredential();
   
           if (credential instanceof OuterUserCredential) {
               // This credential type will only be seen for a delegation request, if not seen then the request is not for us.
   
               if (delegationAcceptable(name, (OuterUserCredential) credential)) {
   
                   identity = new SimplePrincipal(name);
                   if (getUseFirstPass()) {
                       String userName = identity.getName();
                       if (log.isDebugEnabled())
                           log.debug("Storing username '" + userName + "' and empty password");
                       // Add the username and an empty password to the shared state map
                       sharedState.put("javax.security.auth.login.name", identity);
                       sharedState.put("javax.security.auth.login.password", "");
                   }
                   loginOk = true;
                   return true;
               }
           }
   
           return false; // Attempted login but not successful.
       }
   
       protected boolean delegationAcceptable(String requestedUser, OuterUserCredential connectionUser) {
       if (delegationMappings == null) {
           return false;
       }
   
       String[] allowedMappings = loadPropertyValue(connectionUser.getName(), connectionUser.getRealm());
       if (allowedMappings.length == 1 && "*".equals(allowedMappings[1])) {
           // A wild card mapping was found.
           return true;
       }
       for (String current : allowedMappings) {
           if (requestedUser.equals(current)) {
               return true;
           }
       }
       return false;
   }
   

Procedure 7.13. Pass Security Information for EJB Authentication

1. Create the client side interceptor

   This interceptor must implement the org.jboss.ejb.client.EJBClientInterceptor. The interceptor is expected to pass the additional security token through the context data map, which can be obtained via a call to EJBClientInvocationContext.getContextData(). The following is an example of client side interceptor code that creates an additional security token:

   public class ClientSecurityInterceptor implements EJBClientInterceptor {
   
       public void handleInvocation(EJBClientInvocationContext context) throws Exception {
           Principal currentPrincipal = SecurityActions.securityContextGetPrincipal();
   
           if (currentPrincipal != null) {
               Map<String, Object> contextData = context.getContextData();
               contextData.put(ServerSecurityInterceptor.DELEGATED_USER_KEY, currentPrincipal.getName());
           }
   
           context.sendRequest();
       }
   
       public Object handleInvocationResult(EJBClientInvocationContext context) throws Exception {
           return context.getResult();
       }
   
   }
   

   For information on how to plug the client interceptor into an application, refer to Section 7.6.6, “Use a Client Side Interceptor in an Application”.

2. Create and configure the server side container interceptor

   Container interceptor classes are simple Plain Old Java Objects (POJOs). They use the @javax.annotation.AroundInvoke to mark the method that is invoked during the invocation on the bean. For more information about container interceptors, refer to: Section 7.6.1, “About Container Interceptors”.

   1. Create the container interceptor

      This interceptor retrieves the security authentication token from the context and passes it to the JAAS (Java Authentication and Authorization Service) domain for verification. The following is an example of container interceptor code:

      public class ServerSecurityInterceptor {
      
          private static final Logger logger = Logger.getLogger(ServerSecurityInterceptor.class);
      
          static final String DELEGATED_USER_KEY = ServerSecurityInterceptor.class.getName() + ".DelegationUser";
      
          @AroundInvoke
          public Object aroundInvoke(final InvocationContext invocationContext) throws Exception {
              Principal desiredUser = null;
              UserPrincipal connectionUser = null;
      
              Map<String, Object> contextData = invocationContext.getContextData();
              if (contextData.containsKey(DELEGATED_USER_KEY)) {
                  desiredUser = new SimplePrincipal((String) contextData.get(DELEGATED_USER_KEY));
      
                  Collection<Principal> connectionPrincipals = SecurityActions.getConnectionPrincipals();
      
                  if (connectionPrincipals != null) {
                      for (Principal current : connectionPrincipals) {
                          if (current instanceof UserPrincipal) {
                              connectionUser = (UserPrincipal) current;
                              break;
                          }
                      }
      
                  } else {
                      throw new IllegalStateException("Delegation user requested but no user on connection found.");
                  }
              }
      
      
              ContextStateCache stateCache = null;
              try {
                  if (desiredUser != null && connectionUser != null
                      && (desiredUser.getName().equals(connectionUser.getName()) == false)) {
                      // The final part of this check is to verify that the change does actually indicate a change in user.
                      try {
                          // We have been requested to use an authentication token
                          // so now we attempt the switch.
                          stateCache = SecurityActions.pushIdentity(desiredUser, new OuterUserCredential(connectionUser));
                      } catch (Exception e) {
                          logger.error("Failed to switch security context for user", e);
                          // Don't propagate the exception stacktrace back to the client for security reasons
                          throw new EJBAccessException("Unable to attempt switching of user.");
                      }
                  }
      
                  return invocationContext.proceed();
              } finally {
                  // switch back to original context
                  if (stateCache != null) {
                      SecurityActions.popIdentity(stateCache);;
                  }
              }
          }
      
      

   2. Configure the container interceptor

      For information on how to configure server side container interceptors, refer to: Section 7.6.3, “Configure a Container Interceptor”.

3. Create the JAAS LoginModule

   This custom module performs the authentication using the existing authenticated connection information plus any additional security token. The following is a shortened example of code that uses the additional security token and performs the authentication. The complete code example can be viewed in the ejb-security-interceptors quickstart that ships with JBoss EAP 6.3 or later.

   public class DelegationLoginModule extends AbstractServerLoginModule {
   
       private static final String DELEGATION_PROPERTIES = "delegationProperties";
   
       private static final String DEFAULT_DELEGATION_PROPERTIES = "delegation-mapping.properties";
   
       private Properties delegationMappings;
   
       private Principal identity;
   
       @Override
       public void initialize(Subject subject, CallbackHandler callbackHandler, Map<String, ?> sharedState, Map<String, ?> options) {
           addValidOptions(new String[] { DELEGATION_PROPERTIES });
           super.initialize(subject, callbackHandler, sharedState, options);
   
           String propertiesName;
           if (options.containsKey(DELEGATION_PROPERTIES)) {
               propertiesName = (String) options.get(DELEGATION_PROPERTIES);
           } else {
               propertiesName = DEFAULT_DELEGATION_PROPERTIES;
           }
           try {
               delegationMappings = loadProperties(propertiesName);
           } catch (IOException e) {
               throw new IllegalArgumentException(String.format("Unable to load properties '%s'", propertiesName), e);
           }
       }
   
       @SuppressWarnings("unchecked")
       @Override
       public boolean login() throws LoginException {
           if (super.login() == true) {
               log.debug("super.login()==true");
               return true;
           }
   
           // Time to see if this is a delegation request.
           NameCallback ncb = new NameCallback("Username:");
           ObjectCallback ocb = new ObjectCallback("Password:");
   
           try {
               callbackHandler.handle(new Callback[] { ncb, ocb });
           } catch (Exception e) {
               if (e instanceof RuntimeException) {
                   throw (RuntimeException) e;
               }
               return false; // If the CallbackHandler can not handle the required callbacks then no chance.
           }
   
           String name = ncb.getName();
           Object credential = ocb.getCredential();
   
           if (credential instanceof OuterUserCredential) {
               // This credential type will only be seen for a delegation request, if not seen then the request is not for us.
   
               if (delegationAcceptable(name, (OuterUserCredential) credential)) {
   
                   identity = new SimplePrincipal(name);
                   if (getUseFirstPass()) {
                       String userName = identity.getName();
                       if (log.isDebugEnabled())
                           log.debug("Storing username '" + userName + "' and empty password");
                       // Add the username and an empty password to the shared state map
                       sharedState.put("javax.security.auth.login.name", identity);
                       sharedState.put("javax.security.auth.login.password", "");
                   }
                   loginOk = true;
                   return true;
               }
           }
   
           return false; // Attempted login but not successful.
       }
   
   
   

4. Add the Custom LoginModule to the Chain

   You must add the new custom LoginModule to the correct location the chain so that it is invoked in the correct order. In this example, the SaslPlusLoginModule must be chained before the LoginModule that loads the roles with the password-stacking option set.

   • Configure the LoginModule Order using the Management CLI

     The following is an example of Management CLI commands that chain the custom SaslPlusLoginModule before the RealmDirect LoginModule that sets the password-stacking option.

     /subsystem=security/security-domain=quickstart-domain:add(cache-type=default)
     /subsystem=security/security-domain=quickstart-domain/authentication=classic:add
     /subsystem=security/security-domain=quickstart-domain/authentication=classic/login-module=DelegationLoginModule:add(code=org.jboss.as.quickstarts.ejb_security_plus.SaslPlusLoginModule,flag=optional,module-options={password-stacking=useFirstPass})
     /subsystem=security/security-domain=quickstart-domain/authentication=classic/login-module=RealmDirect:add(code=RealmDirect,flag=required,module-options={password-stacking=useFirstPass})

     For more information about the Management CLI, refer to the chapter entitled Management Interfaces in the Administration and Configuration Guide for JBoss EAP 6 located on the Customer Portal at https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/

   • Configure the LoginModule Order Manually

     The following is an example of XML that configures the LoginModule order in the security subsystem of the server configuration file. The custom SaslPlusLoginModule must precede the RealmDirect LoginModule so that it can verify the remote user before the user roles are loaded and the password-stacking option is set.

     <security-domain name="quickstart-domain" cache-type="default">
         <authentication>
             <login-module code="org.jboss.as.quickstarts.ejb_security_plus.SaslPlusLoginModule" flag="required">
                 <module-option name="password-stacking" value="useFirstPass"/>
             </login-module>
             <login-module code="RealmDirect" flag="required">
                 <module-option name="password-stacking" value="useFirstPass"/>
             </login-module>
         </authentication>
     </security-domain>
     

5. Create the Remote Client

   In the following code example, assume the additional-secret.properties file accessed by the JAAS LoginModule above contains the following property:

   quickstartUser=7f5cc521-5061-4a5b-b814-bdc37f021acc
   

   The following code demonstrates how create the security token and set it before the EJB call. The secret token is hard-coded for demonstration purposes only. This client simply prints the results to the console.

   import static org.jboss.as.quickstarts.ejb_security_plus.EJBUtil.lookupSecuredEJB;
   
   public class RemoteClient {
   
       /**
        * @param args
        */
       public static void main(String[] args) throws Exception {
           SimplePrincipal principal = new SimplePrincipal("quickstartUser");
           Object credential = new PasswordPlusCredential("quickstartPwd1!".toCharArray(), "7f5cc521-5061-4a5b-b814-bdc37f021acc");
   
           SecurityActions.securityContextSetPrincipalCredential(principal, credential);
           SecuredEJBRemote secured = lookupSecuredEJB();
   
           System.out.println(secured.getPrincipalInformation());
       }
   }
   

Procedure 7.14. Plug the Interceptor into

• • Programmatically

    With this approach, you call the org.jboss.ejb.client.EJBClientContext.registerInterceptor(int order, EJBClientInterceptor interceptor) API and pass the order and the interceptor instance. The order is used to determine where exactly in the client interceptor chain this interceptor is placed.

  • ServiceLoader Mechanism

    With this approach, you create a META-INF/services/org.jboss.ejb.client.EJBClientInterceptor file and place or package it in the classpath of the client application. The rules for the file are dictated by the Java ServiceLoader Mechanism. This file is expected to contain a separate line for each fully qualified class name of the EJB client interceptor implementation. The EJB client interceptor classes must be available in the classpath. EJB client interceptors added using the ServiceLoader mechanism are added to the end of the client interceptor chain, in the order they are found in the classpath. The ejb-security-interceptors quickstart uses this approach.

Procedure 9.1. Configure the Web Session Cache

1. Change the default cache mode to DIST.

   /profile=ha/subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=dist)
   

2. Set the number of owners for a distributed cache.

   The following command sets 5 owners. The default is 2.

   /profile=ha/subsystem=infinispan/cache-container=web/distributed-cache=dist/:write-attribute(name=owners,value=5)
   

3. Change the default cache mode back to REPL.

   /profile=ha/subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=repl)
   

4. Restart the Server

   After changing the web cache mode, you must restart the server.

Procedure 9.2. Make your Application Distributable

1. Required: Indicate that your application is distributable.

   If your application is not marked as distributable, its sessions will never be distributed. Add the <distributable/> element inside the <web-app> tag of your application's web.xml descriptor file. Here is an example.

   Example 9.1. Minimum Configuration for a Distributable Application

   <?xml version="1.0"?>
   <web-app  xmlns="http://java.sun.com/xml/ns/j2ee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
             xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
                                 http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" 
             version="2.4">
             
         <distributable/>
       
   </web-app>
   
   

2. Modify the default replication behavior if desired.

   If you want to change any of the values affecting session replication, you can override them inside a <replication-config> element which is a child element of the <jboss-web> element of your application's jboss-web.xml file. For a given element, only include it if you want to override the defaults. The following example lists all of the default settings, and is followed by a table which explains the most commonly changed options.

   Example 9.2. Default <replication-config>Values

   <!DOCTYPE jboss-web PUBLIC
       "-//JBoss//DTD Web Application 5.0//EN"
       "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
   
   <jboss-web>
      
      <replication-config>
         <cache-name>custom-session-cache</cache-name>
         <replication-trigger>SET</replication-trigger>
         <replication-granularity>ATTRIBUTE</replication-granularity>
         <use-jk>false</use-jk>
         <max-unreplicated-interval>30</max-unreplicated-interval>
         <snapshot-mode>INSTANT</snapshot-mode>
         <snapshot-interval>1000</snapshot-interval>
         <session-notification-policy>com.example.CustomSessionNotificationPolicy</session-notification-policy>
     </replication-config>
   
   </jboss-web>