Saturday, August 20, 2011

Deploy a Java EE application on OpenShift Express (with AS7 support)

During the past few years, I've been hearing about "cloud" services more and more. Initially I wasn't really curious to try them out. But a few months (a year?) back, I decided to see what it was all about. I have been involved with Java EE development for more than 7 years now, so I decided to see what it takes to deploy my Java EE application to the cloud. I set out looking for documentation and other usual blog articles and such. At that point, whichever cloud services I thought of trying out, would require me to provide my credit card details even to try out a trial application. I wasn't too keen to provide my credit card details just to try out a few applications of mine. So I kind of gave up on trying out my applications on cloud, although I kept reading about what other developers were doing to deploy their applications on cloud.

At about the same time, I came across this elaborate writeup on how one of the developers had setup his application involving Weld and JSF, on Google App Engine - Part1, Part2. The blog was well written and explained what was required to get your Java EE application up and running on a cloud service. But the important piece of information in those articles was that, users who had an application which was implemented as per Java EE standards (to be portable) had to change many of the application parts just to get them running on cloud. This was because many of the Java EE technologies weren't supported by the cloud service provider. This didn't look appealing to me. After all, what would I gain by doing that. So at that point, I as a Java EE developer, wasn't too interested in experimenting with deploying my application on cloud.

Enter OpenShift!

But this month, the OpenShift announcement about being able to deploy your JBoss AS7 Java EE applications to cloud, caught my eye. By the way, I do work for RedHat and am part of the JBoss AS7 team, but I wasn't keeping a watch on what the OpenShift team was upto, so this announcement came as a pleasant surprise! So I decided to give it a try. After reading some of the documentation on the project site, I found out that OpenShift offers two different services. One was "OpenShift Express" and the other "OpenShift Flex". OpenShift Express is free to use (that was one more good news for me) while OpenShift Flex requires your Amazon EC2 credentials and you'll be charged for the EC2 usage (there's however a free trial going on currently). I decided to give OpenShift Express a try since it was free and suits my current needs of just trying out a quick and simple Java EE application deployment and access to that application.

So here's what I did to be able to deploy my Java EE application which uses the technologies available in Java EE6 webprofile and which deploys fine on my local AS7 instance, to OpenShift Express. You might have already guessed that I'm no expert about OpenShift (or cloud services in general), so in this article doesn't have any advanced technical details, but contains more of a how-to on deploying Java EE applications to OpenShift Express.

So let's start then.

Sign up

The first step is to sign up here to create an account for yourself. The sign up just requires a valid email address to which your account details will be dispatched. On signing up, you'll receive a mail which contains a link to activate your account and will take you to the login screen. Login using the email id and password that you used to register.

Get Access to OpenShift Express

So let's got the OpenShift Express page. On that page you will notice a "Get Access to Express" button on left hand side. Click on it to get access to "Express". You'll be notified (immediately) through a mail to the email id which you registered. Check the mail which will contain a link to a quick start guide, to help you get started with OpenShift Express.

Install client tools

The quick start contains the instructions to get you started with the installation procedure. The first step includes installing a few client tools on your system to help you interact with OpenShift. Follow those instructions to install the client tools (I won't repeat them here, since it's well explained in that guide).

Create a domain

Now once we have the client tools, we are now ready to setup our "domain" on the OpenShift cloud. Setting up a domain will create a unique domain name that you can use for your applications. The domain name will be part of the URL which you will use to access the application and which you'll publish to your users for access. The command to create the domain is easy:
 rhc-create-domain -l <email-id-you-registered-with> -n <domain-name-of-your-choice>  
Running that command will ask you for the password that you used to register. Enter that password and let the command complete (a few seconds).

The "rhc-create-domain" is part of the client tool that you installed earlier. If you haven't yet installed those tools, then you won't be able to use these commands, so don't miss that step! The "rhc-create-domain" accepts a few more optional parameters. To see the list of accepted parameters, you can run the following command:
 rhc-create-domain --help  

Create a jbossas-7.0 application

Once you have successfully create a domain, your next step is to create an "application". Currently OpenShift Express supports different "types" of applications, each of them backed by Git (which is a version control system). At the point of writing this post, the supported application types are jbossas-7.0, perl-5.10, rack-1.1, wsgi-3.2 and php-5.3. I'm interested in deploying a Java EE application, so I'll be creating a "jbossas-7.0" application. This type of application provides you a JBoss AS 7.0.0 instance in the OpenShift cloud to which you can deploy your applications. So let's now create an application of type jbossas-7.0.

Note that the term "application" can be a bit confusing (atleast I found it a bit confusing) because all you are doing at this point is setting up JBoss AS7 server.

The command to create an application is rhc-create-app. The rhc-create-app accepts multiple options. For a complete list of options run:
 rhc-create-app --help  
To create a jbossas-7.0 application, we'll run the following command:
 rhc-create-app -a <application-name> -l <email-id-you-used-to-register> -t jbossas-7.0 -r <path-on-local-filesystem-for-the-repository>  
Running that command will ask you for the password that you used to register. Enter that password and let the command complete (a few seconds).

The -a option lets you specify the name for your application. This name will be part of the URL that you use to access your application. If your application name is "foo" and (the previously created) domain name is "bar", then the URL to access your application will be http://foo-bar.rhcloud.com/.

The -t option in that command, specifies the application type. In our case, we are interested in jbossas-7.0

The other option of importance is the -r option which you'll use to point to a folder on your local filesystem where OpenShift will store all the data related to your application. Part of that data will be a local copy of the git repo (version control system). We'll see this in more detail later on in this blog.

Access your server URL

So once you run the command and it successfully completes, it will print out the URL where the application is available. You can (immediately) use that URL to access the application. On accessing that URL you'll notice a welcome page, which is an indication that the application has been installed successfully and available for access. For me, the URL to the newly created application was http://jaikiran-jbossas.rhcloud.com/.

So at this point, we have created a domain and then an application and have made sure that it's accessible to the world. In short, your cloud server is up and running and you can now deploy your Java EE applications to that server.

Create and deploy a Java EE application

So let's now move to the step of creating and deploying a Java EE application. I didn't have any specific application in mind, but wanted to deploy an application which would involve accessing a database. Instead of creating a brand new application, I decide to use one of the quick start applications that come with JBoss AS7. The quick start applications for JBoss AS7 are available for download here. Once you have downloaded the quick start archive, unzip it to a location of your choice. Building the quick start examples will require Maven build tool be installed on your system. The details about the quick start applications and how to build them can be found here. Those interested in trying it out themselves, might want to look at that guide.

I chose the "kitchensink" application from those quick starts. The kitchensink application uses Java Persistence API (JPA) for persistence and by default uses the java:jboss/datasources/ExampleDS which is shipped by default by JBoss AS7. The ExampleDS uses H2 as its database.This is how the persistence.xml looks like:
 <?xml version="1.0" encoding="UTF-8"?>  
 <persistence version="2.0"  
   xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
   xsi:schemaLocation="  
     http://java.sun.com/xml/ns/persistence  
     http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">  
   <persistence-unit name="primary">  
    <!-- If you are running in a production environment, add a managed   
      data source, the example data source is just for proofs of concept! -->  
    <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source>  
    <properties>  
      <!-- Properties for Hibernate -->  
      <property name="hibernate.hbm2ddl.auto" value="create-drop" />  
      <property name="hibernate.show_sql" value="false" />  
    </properties>  
   </persistence-unit>  
 </persistence>  
That's enough for me now, to show how to deploy the application and also show the DB support available in OpenShift Express.

After building the application, the deployable war is named jboss-as-kitchensink.war and is available on my local file system. My next step would be to deploy it my JBoss AS7 server which we have setup on the OpenShift Express cloud. Let's see how that's done.

Deploy the application to OpenShift Express

Remember, while creating the "application" using the rhc-create-app command, we used the -r option to point to a folder on our local file system to create a local copy of the application repository. That's the place which will be used now for deploying our applications. In my case, I used /home/jpai/OpenShift/myapps/demo as the repo location. This is how that folder looks like:
 demo  
 |  
 |--- deployments  
 |  
 |--- pom.xml  
 |  
 |--- README  
 |  
 |--- src  
There's more than one way to deploy your application to OpenShift Express. One way is to write your code and commit the source code within the src folder of your local repository and then push your changes to the remote git repository. This will then trigger a Maven build for your project on the remote repository. More details about this approach is available in this blog.

In our case, we'll focus on how to deploy an already built Java EE application to your OpenShift Express cloud server. In the previous step, we built the jboss-as-kitchensink.war. Now, copy that war file to the "deployments" subfolder of your local git repository. In this case, it's /home/jpai/OpenShift/myapps/demo/deployments:
 cp /home/jpai/jboss-as-quickstarts-7.0.0.Final/kitchensink/target/jboss-as-kitchensink.war /home/jpai/OpenShift/myapps/demo/deployments  
Once you have copied it here, your next step is to "commit" this change using the git commit command:
 jpai@jpai-laptop:demo$ git add deployments/jboss-as-kitchensink.war  
 jpai@jpai-laptop:demo$ git commit -m "Deploy kitchensink application" deployments/jboss-as-kitchensink.war  
 [master 1637c21] Deploy kitchensink application  
  1 files changed, 0 insertions(+), 0 deletions(-)  
  create mode 100644 deployments/jboss-as-kitchensink.war  
So at this point your kitchensink application has been commited to your local git repo. Next we should "push" this commit to the remote git repo:
 jpai@jpai-laptop:openshift$ git push origin master  
 Counting objects: 6, done.  
 Delta compression using up to 2 threads.  
 Compressing objects: 100% (4/4), done.  
 Writing objects: 100% (4/4), 393.71 KiB, done.  
 Total 4 (delta 1), reused 0 (delta 0)  
 remote: Stopping application...  
 remote: done  
 remote: Found .openshift/config/standalone.xml... copying to ...  
 ....  
 ....  
 ....  
 remote: Starting application...done  
 To ssh://6a7ff43a6c2246999de28219a5aaa4ae@jaikiran-jbossas.rhcloud.com/~/git/jaikiran.git/  
   6e57976..1637c21 master -> master  
(trimmed some logs from the above output).

So with this "push" we have now deployed our application to the remote OpenShift Express JBoss AS7 server. The jboss-as-kitchensink.war will be deployed at the "jboss-as-kitchensink" web application context. So the URL to access the application will be http://jaikiran-jbossas.rhcloud.com/jboss-as-kitchensink. Go ahead and access that URL. The application does nothing fancy - it allows you to add a user name, email and phone number which will then be stored in the database.


Like I mentioned earlier, the kitchensink application uses ExampleDS datasource which is backed by H2 database. So all the data will be stored remotely in the H2 database.

Using the MySQL database available in OpenShift Express

OpenShift Express sets up a MySQL datasource template for you when you create a jbossas-7.0 application type. The details of the database can be found in the <path-to-local-repo>/.openshift/config/standalone.xml:
 <subsystem xmlns="urn:jboss:domain:datasources:1.0">  
      <datasources>  
           <datasource jndi-name="java:jboss/datasources/ExampleDS" enabled="true" use-java-context="true" pool-name="H2DS">  
                <connection-url>jdbc:h2:${jboss.server.data.dir}/test;DB_CLOSE_DELAY=-1</connection-url>  
                <driver>h2</driver>  
                <pool></pool>  
                <security>  
                     <user-name>sa</user-name>  
                     <password>sa</password>  
                </security>  
                <validation></validation>  
                <timeout></timeout>  
                <statement></statement>  
           </datasource>  
           <datasource jndi-name="java:jboss/datasources/MysqlDS" enabled="false" use-java-context="true" pool-name="MysqlDS">  
                <connection-url>jdbc:mysql://127.1.1.1:3306/mysql</connection-url>  
                <driver>mysql</driver>  
                <security>  
                 <user-name>admin</user-name>  
                 <password>changeme</password>  
                </security>  
           </datasource>  
           <drivers>  
                <driver name="h2" module="com.h2database.h2">  
                     <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>  
                </driver>  
                <driver name="mysql" module="com.mysql.jdbc">  
                     <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>  
                </driver>  
           </drivers>  
      </datasources>  
 </subsystem>  
You'll notice that apart from the ExampleDS that comes by default in AS7, OpenShift Express has setup a MySQL datasource which will be available at java:jboss/datasources/MysqlDS. The important piece to note here is that it is disabled (i.e. enabled=false) by default. Also notice that the password is "changeme". Basically, this datasource configuration for MysqlDS in the standalone.xml is there as a template. In order to enable that datasource, we first have to create a MySQL database for our application. That can be done by using the following command:
 jpai@jpai-laptop:openshift$ rhc-ctl-app -a <application-name> -l <email-id-we-used-to-register> -e add-mysql-5.1   
The rhc-ctl-app is passed the application name (which is the one that we used during rhc-create-app) and also our account id. Additionally, we use the -e option to specify what we want to do. In this case, we issue a "add-mysql-5.1" command. Running that command will ask you for your account password and on successful completion will show the output similar to:
 RESULT:  
 Mysql 5.1 database added. Please make note of these credentials:  
 Root User: admin  
 Root Password: as43n34023n  
 Connection URL: mysql://127.1.1.1:3306/  
Note down the user name, password and the connection url. Now open the <repo-home>/.openshift/config/standalone.xml in a text editor and update the MysqlDS configuration to use the connection URL, the user name and the new password. Also set the enabled flag to "true" so that the datasource is enabled. Ultimately the datasource configuration will look like:
 <datasource jndi-name="java:jboss/datasources/MysqlDS" enabled="true" use-java-context="true" pool-name="MysqlDS">  
      <connection-url>jdbc:mysql://127.1.1.1:3306/mysql</connection-url>  
      <driver>mysql</driver>  
      <security>  
       <user-name>admin</user-name>  
       <password>as43n34023n</password>  
      </security>  
 </datasource>  
Pay attention to the connection-url. It has to be of the format jdbc:mysql://<ip:port>/dbname. Typically, you don't have to touch that connection-url at all, since the rhc-ctl-app add-mysql-5.1 and the datasource template are in sync with the IP/port. The important pieces to change are the password and the enabled flag.

Once this file is updated, save the changes and commit it to your local git repo:
 jpai@jpai-laptop:demo$ git commit -m "Enable the MysqlDS and fix the password" ./  
 [master dd7b58a] Fix the datasource password  
 1 files changed, 1 insertions(+), 1 deletions(-)  
 Push these changes to remote repo:  
 jpai@jpai-laptop:openshift$ git push origin master  
 Counting objects: 9, done.  
 Delta compression using up to 2 threads.  
 Compressing objects: 100% (4/4), done.  
 Writing objects: 100% (5/5), 494 bytes, done.  
 Total 5 (delta 2), reused 0 (delta 0)  
 remote: Stopping application...  
 remote: done  
 ....  
 .....  
 remote: Starting application...done  
 To ssh://6a7ff43a6c2246999de28219a5aaa4ae@jaikiran-jbossas.rhcloud.com/~/git/jaikiran.git/  
 2d38fa8..dd7b58a master -&gt; master  
So we now have added MySQL DB and enabled the MysqlDS datasource which is available at java:jboss/datasources/MysqlDS jndi name on the server. So if the kitchensink application has to use MySQL as its database, instead of H2, then all it has to do is use the java:jboss/datasources/MysqlDS. Let's now edit the persistence.xml file that we saw earlier and use the MysqlDS instead:
 <?xml version="1.0" encoding="UTF-8"?>  
 <persistence version="2.0"  
   xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
   xsi:schemaLocation="  
     http://java.sun.com/xml/ns/persistence  
     http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">  
   <persistence-unit name="primary">  
    <!-- Changed to use MysqlDS -->  
    <jta-data-source>java:jboss/datasources/MysqlDS</jta-data-source>  
    <properties>  
      <!-- Properties for Hibernate -->  
      <property name="hibernate.hbm2ddl.auto" value="create-drop" />  
      <property name="hibernate.show_sql" value="false" />  
    </properties>  
   </persistence-unit>  
 </persistence>   
Additionally, just to "show" that this new application has been updated to use MySQL database, I also edited the index.xhtml page of the kitchensink application, to add a message on that page about MySQL database being used:
 <h3>  
       <span style="color: red;">  
            This application uses MySQL database as its persistence store  
        </span>  
 </h3>  
Next, I'll build the kitchensink application locally using Maven, to reflect these changes and generate the new jboss-as-kitchensink.war. Once built, let's now again copy it to our local git repo and then commit the change and push it to the remote git repo:
 jpai@jpai-laptop:kitchensink$ cp target/jboss-as-kitchensink.war /home/jpai/OpenShift/myapps/demo/deployments  

 jpai@jpai-laptop:demo$ git commit -m "Use MySQL database for kitchensink application" ./  
 [master ded2445] Use MySQL database for kitchensink application  
 1 files changed, 0 insertions(+), 0 deletions(-)  

 jpai@jpai-laptop:openshift$ git push origin master  
 Counting objects: 7, done.  
 Delta compression using up to 2 threads.  
 Compressing objects: 100% (4/4), done.  
 Writing objects: 100% (4/4), 1.35 KiB, done.  
 Total 4 (delta 2), reused 0 (delta 0)  
 remote: Stopping application...  
 remote: done  
 remote: Found .openshift/config/standalone.xml... copying to...  
 ...  
 ...  
 ...  
 remote: Starting application...done  
 To ssh://6a7ff43a6c2246999de28219a5aaa4ae@jaikiran-jbossas.rhcloud.com/~/git/jaikiran.git/  
 1637c21..ded2445 master -&gt; master  
 jpai@jpai-laptop:demo$   
(trimmed some logs from the output)

So at this point we have now changed our kitchensink application to use MySQL database and have deployed it to our OpenShift Express AS7 server. So let's access the application URL again http://jaikiran-jbossas.rhcloud.com/jboss-as-kitchensink. As you see, that page now prominently displays our message about MySQL DB being used. Go ahead and try out that app by adding some dummy user information.


That's it! We have successfully deployed our application to OpenShift Express server and the application is available for use.

Summary

It's been a pleasant experience so far with OpenShift. I plan to try out a few more things with OpenShift, in the coming days and blog about any interesting details.

Useful resources

While working on deploying this application, I had to use some documents and help from the OpenShift community to understand how this is all setup,. Here's a list of useful resources related to OpenShift in general:

OpenShift Express User guide
OpenShift forums
OpenShift IRC #openshift on irc.freenode.net. The folks here are very helpful!
Scott Stark's blog. Scott's blogs contain a lot of useful information about AS7 on OpenShift and OpenShift in general. Scott's blog is definitely a must read!

Where to look for help

OpenShift questions in general are answered in the OpenShift forums. For questions around AS7 on OpenShift, the best place to ask questions is the JBoss Cloud Group.


Friday, August 19, 2011

JBoss AS 6.1.0 released

This week at JBoss, we not only saw JBoss AS 7.0.1 being released but there also was the release of JBoss AS 6.1.0, a few days earlier. The download is available here. JBoss AS 6.1.0 is mainly is bug fix release. This release is mainly for those users who haven't yet migrated to AS7. Release notes are available here.

One of the highlights of this release, is that this was mainly driven by the community members.Many of the JBoss AS developers were busy with AS7 activities, so we had asked for community members to volunteer for providing fixes for 6.1.0. Shelly led the 6.1.0 release efforts (like she did with 6.0.0). We had some great help from the community for this release, notably from Daniel Bevenius who helped fix a number of issues. Thanks to Shelly, Daniel and other community members for making this release possible!

So, AS6 users, download this new release and give it a try! As always, if you have any questions or run into any issues, please visit our user forum and start a discussion.

JBoss AS 7.0.1 - Configuring EJB3 Pools

Now that AS 7.0.1 has been released, let's take a look at what new EJB3 features are available. Like I mentioned in my previous post AS 7.0.1 now allows you to configure pools for your stateless session beans and MDBs. Currently we allow configuring the pools at the subsystem level, which means that the pool will be applicable for all the beans deployed on the server. In some upcoming release, we'll allow configuring the pools at individual deployment and individual bean level. Let's, for now, see how the configuration looks like at the subsystem level.

In my previous post I mentioned that AS 7.0.1 has 2 distributions. One which is purely webprofile and the other (named "everything") has additional EE features like support for MDBs. In this post, I'll be using the "Everything" distribution and the JBOSS_HOME/standalone/configurations/standalone-preview.xml for explaining the configurations.

Before we begin with the configurations, for those of you who are new to AS7, let's just see how to start the server using a specific configuration file. First, download the server and the unzip the binary in a folder of your choice. Then from the command prompt, move to the "bin" folder of the installation. Within this folder, you will see a standalone.bat/standalone.sh and domain.bat/domain.sh. We'll be concentrating on the standalone server in this post, but the same applies to the EJB3 subsystem in the domain configurations.

Starting the standalone server

So let's start the server. I'm on a Linux system, so I'll use the standalone.sh file. Those of you on Windows, will have to use standalone.bat.

 jpai@jpai-laptop:bin$ ./standalone.sh  
Within around a couple of seconds, you'll see the server is up and running:

 jpai@jpai-laptop:bin$ ./standalone.sh  
 =========================================================================  
  JBoss Bootstrap Environment  
  JBOSS_HOME: /NotBackedUp/jpai/jboss-as-7.0.1.Final  
  JAVA: /opt/Java/SunJava-6/jdk1.6.0_21//bin/java  
  JAVA_OPTS: -server -Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djboss.modules.system.pkgs=org.jboss.byteman  
 =========================================================================  
 09:30:31,537 INFO [org.jboss.modules] JBoss Modules version 1.0.1.GA  
 09:30:31,765 INFO [org.jboss.msc] JBoss MSC version 1.0.0.GA  
 09:30:31,818 INFO [org.jboss.as] JBoss AS 7.0.1.Final "Zap" starting  
 09:30:32,618 WARN [org.jboss.as] No security realm defined for native management service, all access will be unrestricted.  
 09:30:32,693 INFO [org.jboss.as] creating http management service using network interface (management) port (9990)  
 09:30:32,694 WARN [org.jboss.as] No security realm defined for http management service, all access will be unrestricted.  
 09:30:32,703 INFO [org.jboss.as.logging] Removing bootstrap log handlers  
 09:30:32,720 INFO [org.jboss.as.connector.subsystems.datasources] (Controller Boot Thread) Deploying JDBC-compliant driver class org.h2.Driver (version 1.2)  
 09:30:32,739 INFO [org.jboss.as.clustering.infinispan.subsystem] (Controller Boot Thread) Activating Infinispan subsystem.  
 09:30:32,905 INFO [org.jboss.as.naming] (Controller Boot Thread) Activating Naming Subsystem  
 09:30:32,915 INFO [org.jboss.as.naming] (MSC service thread 1-1) Starting Naming Service  
 09:30:32,918 INFO [org.jboss.as.osgi] (Controller Boot Thread) Activating OSGi Subsystem  
 09:30:32,940 INFO [org.jboss.as.security] (Controller Boot Thread) Activating Security Subsystem  
 09:30:32,957 INFO [org.jboss.remoting] (MSC service thread 1-4) JBoss Remoting version 3.2.0.Beta2  
 09:30:32,968 INFO [org.xnio] (MSC service thread 1-4) XNIO Version 3.0.0.Beta3  
 09:30:32,982 INFO [org.xnio.nio] (MSC service thread 1-4) XNIO NIO Implementation Version 3.0.0.Beta3  
 09:30:33,182 INFO [org.apache.catalina.core.AprLifecycleListener] (MSC service thread 1-4) The Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path: /opt/Java/SunJava-6/jdk1.6.0_21/jre/lib/i386/server:/opt/Java/SunJava-6/jdk1.6.0_21/jre/lib/i386:/opt/Java/SunJava-6/jdk1.6.0_21/jre/../lib/i386:/usr/java/packages/lib/i386:/lib:/usr/lib  
 09:30:33,203 INFO [org.jboss.as.jmx.JMXConnectorService] (MSC service thread 1-2) Starting remote JMX connector  
 09:30:33,209 INFO [org.jboss.as.remoting] (MSC service thread 1-1) Listening on /127.0.0.1:9999  
 09:30:33,232 INFO [org.jboss.as.ee] (Controller Boot Thread) Activating EE subsystem  
 09:30:33,390 INFO [org.apache.coyote.http11.Http11Protocol] (MSC service thread 1-4) Starting Coyote HTTP/1.1 on http--127.0.0.1-8080  
 09:30:33,512 INFO [org.jboss.as.connector] (MSC service thread 1-1) Starting JCA Subsystem (JBoss IronJacamar 1.0.3.Final)  
 09:30:33,554 INFO [org.jboss.as.connector.subsystems.datasources] (MSC service thread 1-4) Bound data source [java:jboss/datasources/ExampleDS]  
 09:30:33,919 INFO [org.jboss.as.deployment] (MSC service thread 1-4) Started FileSystemDeploymentService for directory /NotBackedUp/jpai/jboss-as-7.0.1.Final/standalone/deployments  
 09:30:33,931 INFO [org.jboss.as] (Controller Boot Thread) JBoss AS 7.0.1.Final "Zap" started in 2636ms - Started 93 of 148 services (55 services are passive or on-demand)  

Using a different server configuration file

The standalone.sh command by default uses a configuration file named "standalone.xml" which is present in JBOSS_HOME/standalone/configuration folder. The command also allows you to specify a different configuration file, to start the server. Like I mentioned, earlier, I'll be using the standalone-preview.xml in this post. So let's start the server using the standalone-preview.xml.

 jpai@jpai-laptop:bin$ ./standalone.sh -server-config=standalone-preview.xml  
As you see, we pass the -server-config parameter with standalone-preview.xml as the parameter value. By default, the file is looked for in the JBOSS_HOME/standalone/configuration folder. The server starts up in around 3.5 seconds:

 09:35:59,694 INFO&nbsp; [org.jboss.as] (Controller Boot Thread) JBoss AS 7.0.1.Final "Zap" started in 3586ms - Started 125 of 184 services (59 services are passive or on-demand)  

EJB3 subsystem configurations

Now that we have seen how to startup the server, let's move on to see the configurations. In the standalone-preview.xml, look for the EJB3 subsystem which looks like this:
 <subsystem xmlns="urn:jboss:domain:ejb3:1.1" >  
      <timer-service>  
           <thread-pool core-threads="1" max-threads="4" />  
           <data-store path="timer-service-data" relative-to="jboss.server.data.dir" />  
      </timer-service>  
      <!-- EJB3 pools -->  
      <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"/>  
           </bean-instance-pools>  
      </pools>  
      <!-- Default MDB configurations -->  
      <mdb>  
           <resource-adapter-ref resource-adapter-name="hornetq-ra"/>  
           <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>  
      </mdb>  
      <!-- Session bean configurations -->  
      <session-bean>  
           <stateless>  
                <bean-instance-pool-ref pool-name="slsb-strict-max-pool"/>  
           </stateless>  
      </session-bean>  
 </subsystem>  
This is where the EJB3 subsystem level configurations are present. Let's quickly see what some of those are. The first piece of configuration is for EJB3 timerservices. We won't go into too much details of that in this post.

EJB3 Pools

The next piece of configuration is the "pools":
 <!-- EJB3 pools -->  
 <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"/>  
      </bean-instance-pools>  
 </pools>  
This is where you configure the pools used by EJB3. Within the "pools" element, you can configure the bean instance pools using the "bean-instance-pools" element. In AS 7.0.1, we only support "strict-max-pool" as a bean instance pool.

A strict max pool allows you to configure a maximum upper limit for the pool. At runtime, when all the bean instances from the pool are in use and a new bean invocation request comes in, the pool blocks the request till the next bean instance is available or till a timeout (set in instance-acquisition-timeout) is reached. Each pool has a unique name. The configurations above show 2 strict max pools named "slsb-strict-max-pool" and "mdb-strict-max-pool". You can add a new strict max pool in there and set a unique name of your choice to it. You can either edit the xml by hand (when the server is down) to add a new strict max pool or you can use the Command Line Client (CLI) that comes with AS7. We'll see how to use the CLI, later in this post.

Message driven bean configurations

Let's now move to the next configurations in that EJB3 subsystem:
 <!-- Default MDB configurations -->  
 <mdb>  
      <resource-adapter-ref resource-adapter-name="hornetq-ra"/>  
      <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>  
 </mdb>  
This section configures the MDB with the defaults.

Default resource adapter for MDBs

The "resource-adapter-ref" element specifies the default resource-adapter which will be used by the MDBs. In this example, it shows that we use hornetq-ra as the default RA.

Default bean instance pool for MDBs

The bean-instance-pool-ref acts as a reference to a bean-instance-pool, which will be used as the default pool configuration for all MDBs. In this example, we see that it points to "mdb-strict-max-pool" which we saw in the earlier section was configured as a strict max pool with 20 as the upper limit for the pool. If you want to change the default bean instance pool for MDBs, then just change the pool-name attribute of the bean-instance-pool-ref element to some other bean instance pool that's available. You can either do it by editing the xml directly (when the server is down) or use the CLI to do this (we'll see how that's done, later).

Stateless session bean configurations

Moving on to the next section in the EJB3 configurations, you'll see:
 <!-- Session bean configurations -->  
 <session-bean>  
      <stateless>  
           <bean-instance-pool-ref pool-name="slsb-strict-max-pool"/>  
      </stateless>  
 </session-bean>  
This is where you configure the defaults for the session beans. Like we saw with MDBs, the above configuration shows how we configure the default bean instance pool for the stateless session beans. Here we see that "slsb-strict-max-pool" is used as the default. Just like for MDBs, you can change the default bean instance pool for Stateless session beans by changing the pool-name attribute of the bean-instance-pool-ref element either directly in the xml or via the CLI.

Using the Command Line Client (CLI)

AS7 comes with a powerful command line client. Check the AS7 documentation on CLI for a quick reference. The command line client tool is started using the jboss-admin.sh/jboss-admin.bat scripts that are available in the JBOSS_HOME/bin folder:
 jpai@jpai-laptop:bin$ ./jboss-admin.sh  
On running that script, you will notice the following message which acts you to connect to the server:
 You are disconnected at the moment. Type 'connect' to connect to the server or 'help' for the list of supported commands.  
 [disconnected /]   
The CLI requires a running server to be able to connect. So if you haven't started the server, then start it first (as explained in one of the sections above). Now let's connect to the server through the command line:
 [disconnected /] connect  
 Connected to standalone controller at localhost:9999  
 [standalone@localhost:9999 /]   
So the CLI is now connected to the server which is listening on localhost on port 9999. The CLI can be passed a different hostname and port to connect to, but let's not get into that now.

Once you are connected to the server from the CLI, you can now run operations from the CLI to manage your running server. Let's now see how we can manage the bean instance pool configurations for EJB3 subsystem.

Create a new strict max bean instance pool from the CLI

After you have connected to the server from the CLI, you can create a new strict max bean instance pool as follows:
 [standalone@localhost:9999 /] /subsystem=ejb3/strict-max-bean-instance-pool=new-pool:add  
I would recommend that you read the CLI documentation to understand the command better. But let me just briefly split up the above command and explain what each part does.

An important thing to note is that you don't have to type all of that on the CLI. The CLI provides a very (very) useful tab completion feature! So typing in /subsystem= and pressing the tab will show you the available options.

Understanding the bean instance pool creation command

From the CLI documentation:
An operation request basically consists of three parts: The address, an operation name and an optional set of parameters.

The formal specification for an operation request is:
 [/node-type=node-name (/node-type=node-name)*] : operation-name [( [parameter-name=parameter-value (,parameter-name=parameter-value)*] )]  

In this example, our goal is to create a new strict max bean instance pool. This can be done by issuing a "add" operation. In the command that I posted above, notice the use of ":add" at the end. An operation always starts with a ":" followed by the operation name. So in the example above, we are issuing the ":add" operation.

Now the "add" operation will have to be executed on a particular "resource". i.e. the server has to know what to add and where. This is known as addressing. In order to run an operation, an address needs to be provided (don't confuse this with the hostname/port "address" of the server, that's completely different). In AS7 management terms, the server is made up of manageable "resources" and each resource has a address of its own. For example, each of the subsystems that make up the server configuration can be addressed. To refer to the ejb3 subsystem from the command line client, you use /subsystem=ejb3 (you can use the tab completion).

Let's say our new pool that we are creating is going to be named "new-pool". So ultimately the address at which the "add" operation needs to be carried out would look like:
 /subsystem=ejb3/strict-max-bean-instance-pool=new-pool  
Finally, we will combine the address and the operation and run it from the CLI
 [standalone@localhost:9999 /] /subsystem=ejb3/strict-max-bean-instance-pool=new-pool:add  
A sucessful completion of the operation will show you the following output:
 [standalone@localhost:9999 /] /subsystem=ejb3/strict-max-bean-instance-pool=new-pool:add  
 {"outcome" => "success"}  
All management operations are persisted to the server configuration file. In our case it's the standalone-preview.xml, since that's the one we used to start the server.

After running that operation, you can now open the standalone-preview.xml in a text editor and notice that a new strict max bean instance pool, named "new-pool" has been added to the "bean-instance-pools":
 <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="new-pool"/>  
      </bean-instance-pools>  
 </pools>  
The max-pool-size and the other attributes haven't been set and the default values will be used. That's because while running the operation, we did not specify any values for those attributes. Let's now try issuing a command to create one more pool (named "take2") with some specific attribute values. The command will now look like:
 [standalone@localhost:9999 /] /subsystem=ejb3/strict-max-bean-instance-pool=take2:add(max-pool-size=15,timeout=2)  
So the command above is similar to the previous one, except that the name of the pool is "take2" and we have additional specified a max-pool-size of 15 and a timeout of 2 and let the timeout-unit be the default. Note that you can use tab completion while writing that command. On running that command, you'll see the following output:
 [standalone@localhost:9999 /] /subsystem=ejb3/strict-max-bean-instance-pool=take2:add(max-pool-size=15,timeout=2)  
 {"outcome" => "success"}  
The standalone-preview.xml will now look like:
 <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="new-pool"/>  
           <strict-max-pool name="take2" max-pool-size="15" instance-acquisition-timeout="2"/>  
      </bean-instance-pools>  
 </pools>  
Notice the "take2" pool which has the max-pool-size and instance-acquisition-timeout values set to whatever we specified on the CLI.

So that's how you create a new bean instance pool from the CLI.

Setting/changing the default bean instance pool used by the MDBs and the SLSBs

In the previous section we saw how to create a new bean instance pool. Now if we want this new pool to be our default pool configuration for MDBs and/or SLSBs, then we can use the CLI to do that.

Let's first see how it's done for MDBs:
 [standalone@localhost:9999 /] /subsystem=ejb3:write-attribute(name=default-mdb-instance-pool, value=take2)  
So we are issuing a "write-attribute" operation on the /subsystem=ejb3 address to write the attribute named "default-mdb-instance-pool" with a value "take2". Effectively, this command is going to change the default MDB bean instance pool from "mdb-strict-max-pool" (remember, we saw this in the standalone-preview.xml earlier, in the bean-instance-pool-ref section of the MDB) to the "take2" pool that we create a few steps back. Running this command will show you the following output
 [standalone@localhost:9999 /] /subsystem=ejb3:write-attribute(name=default-mdb-instance-pool, value=take2)  
 {"outcome" => "success"}  
If you open the standalone-preview.xml in a text editor, you'll now notice that the changes have been done - the MDB configuration now uses "take2" as the default pool configuration for all MDBs (henceforth).
 <mdb>  
      <resource-adapter-ref resource-adapter-name="hornetq-ra"/>  
      <bean-instance-pool-ref pool-name="take2"/>  
 </mdb>  
We can do the same for Stateless session bean configuration too. The command is:
 [standalone@localhost:9999 /] /subsystem=ejb3:write-attribute(name=default-slsb-instance-pool, value=new-pool)  
 {"outcome" => "success"}  
Here we set the default-slsb-instance-pool to the "new-pool" that we created earlier. The standalone-preview.xml file will now look like:
 <session-bean>  
      <stateless>  
           <bean-instance-pool-ref pool-name="new-pool"/>  
      </stateless>  
 </session-bean>  
So that's it! We have now used the CLI to configure/manage our EJB3 pools.

Disabling pooling for MDBs and Stateless Session Beans

We also allow pooling to be disabled for MDBs and SLSBs. However, it's not always recommended since it can have performance impacts. If as a developer, you know that your beans aren't too heavy during construction (i.e. nothing in constructor and nothing in @PostConstruct), then it sometimes help to disable pooling for the beans. Currently the only way to do this, is by removing the <bean-instance-pool-ref> element from the <mdb> and/or <stateless> elements in the EJB3 subsystem configuration. We don't currently have a way to do this via the CLI nor do we have a way to specify this at per deployment or per bean level.

So, if you know disabling the pooling benefits you, then that's how you can disable it.

Summary

I hadn't thought that this blog would get this lengthy. But since most of this is new in AS7, it was worth writing this up. So, in this blog we saw how and where the EJB3 bean instance pools are configured, how to create new bean instance pools, how to change the default bean instance pools for MDBs and Stateless session beans. We also saw how all of this can be done using the CLI in AS7.

I plan to write some more blog posts in the upcoming days, to explain some other features of AS7 and/or EJB3 in AS7. If you have any questions or run into issues, please visit us in our user forums.



Thursday, August 18, 2011

JBoss AS 7.0.1 released!




JBoss AS 7.0.1 "Zap" has been released today. It's been one month since AS 7.0.0 was released, so this new release has come in quick time. This new release includes a lot of bug fixes (135 issues in total) that have been mainly reported in the community. Apart from the bug fixes the major features/additions to 7.0.1 are as follows:

* Better JPA integration and plug-ability


As many of you might already know, AS 7.0.0 came bundled with Hibernate 4 version. Users could still package Hibernate 3 within their application and use it. But many users reported issues with Hibernate 3 bundled within their application. Moreover, 7.0.0 did not have a way to allow other JPA implementations (like EclipseLink) to be integrated. As such, major changes were implemented in 7.0.1 to introduce better JPA plug-ability. The JPA reference guide for AS7 is good place to look at the details.

* MDB support


AS 7.0.0 had 2 distributions. One, a purely "web-profile" certified distribution which included EJB3.1 "Lite" support (as mandated by webprofile spec). The other distribution (named "everything") had some more features in addition to "web-profile". EJB3.1 "Lite" doesn't include MDB support. So in AS 7.0.0 we didn't have MDB support. Many users in the forums asked for MDB support to be included in the near future. We decided that it would be good to include it in 7.0.1 and as such, we now support MDBs in the "everything" distribution of 7.0.1. We have had some very good community feedback, on the MDB support, while the development was in progress. So thanks to that feedback, we were able to fix some issues with MDB integration, right in time for the 7.0.1.

So try out the MDB support available in the "everything" distribution of AS 7.0.1 and let us know how it goes.

* EJB3 pool configurations


AS 7.0.0 had hardcoded pool configurations for Stateless session beans. There wasn't a way to configure the pool for the beans. In AS 7.0.1 we have introduced a way to configure pools for Stateless session beans and MDBs. We also allow disabling pools for both Stateless session beans and MDBs. Disabling pools benefits in some cases where the bean construction isn't heavy (like not much in @PostConstruct etc...). I'll blog more about the EJB3 pool configurations in a separate post.

* Ability to bundle application specific JSF version


Users can now bundle their own version of JSF in their applications.

7.0.1 (and AS7 in general) has had a huge community feeback and contribution. A lot of the issues that have been fixed, have been raised by our community members. A big thanks to them for helping us all along, towards AS7 efforts!

As always, give the new release a try and let us know how it goes. We are always looking for inputs to make AS7 better. Report any issues or ask for help in our user forum

I plan to write some more posts around 7.0.1 in the coming days. Also, keep a watch on other blogs from JBoss AS developers and community members around AS7.