Skip to main content

Glassfish V3 Resources with the Administration CLI tool (asadmin)

Posted by felipegaucho on March 4, 2010 at 10:47 AM PST

I just updated the Cejug-Classifieds Project to support Maven 2 builds and I added some new features, including a Shell Script able to configure the resources and also to deploy the the application in the Glassfish V3. The script creates all Java EE resources required by the application, like the DataSource, the JavaMail connection and the JMS Queues. In the next sections I will describe how to create each of this resources using the "Glassfish's Administration CLI tool" (the asadmin command line).

The Glassfish's Administration CLI tool

The CLI tool is available when you install Glassfish in your machine and include the %AS_HOME\bin in the PATH environment variable. In order to test if your configuration is ok, just open a terminal and type:

	asadmin version
Version = GlassFish v3 (build 74.2)
Command version executed successfully.

You should see the Glassfish version on the screen, otherwise, please review the installation of Glassfish before to proceed reading the rest of this blog.

Important: I will assume you know what Java EE resources are and specially that you know what is a DataSource, a JMS Queue and a JavaMail resource.

Environment configuration

The following details should be configured in your machine in order to execute the sample commands of this blog:

  • Install Glassfish V3 with the default configuration values.

  • Install MySQL with user=root and password=adminadmin. If you use different values, please adapt the commands in the scripts below.

  • Be sure to have the MySQL driver installed in the Glassfish lib folder. If you didn't installed the driver yet, just copy the MySQL Connector/J 5.1.12 jar file to the AS_HOME\domains\domain1\lib folder.

  • Be sure to create the classifieds database before to proceed, ust open a terminal (or DOS window) and type:

    mysql -uroot -padminadmin
    mysql> create database classifieds;
    mysql> Query OK, 1 row affected (0.00 sec)
    mysql> exit;
         

The resources of Cejug-Classifieds

The goal of this entry is not to replace the excellent Glassfish documentation, it is just a shortcut for the ones interested in collaborate in the CEJUG open-source projects. I will use the Cejug-Classifieds Shell Script as example of asadmin usage, and if you are using Windows there are just few details you should change in order to obtain the same results. The resources to be created are the ones highlighted in the right image of the Glassfish Administrative console. These resources are:

  1. jdbc/classifiedsPool - a MySQL JDBC Connection Pool

  2. jdbc/classifieds - a MySQL Data Source

  3. NotificationQueueConnectionfactory - a JMS connection factory used by the notification features.

  4. RegistrationQueueConnectionfactory - a JMS connection factory used by the pedantic registration use case.

  5. NotificationQueueConnectionfactory - the notification JMS Queue.

  6. RegistrationQueueConnectionfactory - the registration JMS Queue.

  7. mail/classifieds - the JavaMail resource, used to messages through the GMail SMTP server.

res.png

After executing the instructions below you should check the resources of your Glassfish accessing http://localhost:4848 and then navigate in the left pane to find each resource. You can also use the impressive Admin GUI of Glassfish to modify the resources you created through the line commands or even create the resources directly in the Admin GUI. The reason I prefer the asadmin line commands is due to the higher productivity and - specially - due to the chance to integrate the resources creation in the continuous integration of the project. Nevertheless it is a personal choice and it is up to you to find your best way of doing that.

Creating a DataSource resource with asadmin

Data Sources are the resource you need to connect your Java EE Application to a database. It depends on two configurations: a connection pool and the JDBC resource itself. Your application will connect to the JDBC resource and the container will manage the connections pool - so you don't need to add boiler plate code to your application just to manage the life cycle of the JDBC connections.

  1. Create the connection pool:

    asadmin create-jdbc-connection-pool --datasourceclassname com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource --restype javax.sql.ConnectionPoolDataSource --property "User=$MYSQL_USER:Password=$MYSQL_PASSWORD:URL=$DB_URL" jdbc/classifiedsPool

    Where:

    • $MYSQL_USER is the database user

    • $MYSQL_PASSWORD is the database user's password

    • $DB_URL is the database connection URL. Unfortunatelly the database connection is slightly different for each operational system due to the slashes '/' differences.

    Example with the real values for Cejug-Classifieds:

    • Linux:

      asadmin create-jdbc-connection-pool --datasourceclassname com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource --restype javax.sql.ConnectionPoolDataSource --property "User=root:Password=adminadmin:URL=jdbc\\:mysql\\://localhost\\:3306/classifieds" jdbc/classifiedsPool
    • Windows:

      asadmin create-jdbc-connection-pool --datasourceclassname com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource --restype javax.sql.ConnectionPoolDataSource --property "User=root:Password=adminadmin:URL=jdbc\:mysql\://localhost\:3306/classifieds" jdbc/classifiedsPool

    Test the connection pool:

    asadmin ping-connection-pool jdbc/classifiedsPool
    Command ping-connection-pool executed successfully.
  2. Create the JDBC resource:

    asadmin --user=$ASADMIN_USER create-jdbc-resource --connectionpoolid jdbc/classifiedsPool jdbc/classifieds

    Where:

    • $ASADMIN_USER is the Glassfish administrator username

    Example with the real values for Cejug-Classifieds:

    • The same command for both Linux and windows:

      asadmin --user=admin create-jdbc-resource --connectionpoolid jdbc/classifiedsPool jdbc/classifieds
  3. Test the JDBC resource:

    asadmin --user admin list-jdbc-resources
    jdbc/__TimerPool
    jdbc/__default
    jdbc/arena
    jdbc/classifieds

    Command list-jdbc-resources executed successfully.

You can find here an example of JPA 2.0 persistence.xml file using this resource.

Creating JMS resources with asadmin

Messaging is one of the most powerful resource of Java EE applications, because it enable asynchronous tasks in your application and also provides a mechanism to Queue processes when your application is busy. Several use cases can respond much faster to the client request if the some tasks are processed in background, and that is the way Cejug-Classifieds uses the Glassfish JMS: for customers notifications and for the registration use case. The registration case is the easier example: a new customer register an account in the classifieds system, and then the system sends an email to confirm the customer request. SMTP is always a complicated resource because it is not guaranteed to deliver the messages and also because the SMTP can be down in the moment the customer tries to register. To not block the application or to force the customer to wait for the SMTP server response, every new registration is stored in a Queue and then the application immediately respond to the customer application saying "please check your email for the confirmation message". After that, the server releases the resources used by the registration use case and other process will handle the email sending to the new customer - faster and more reliable than trying to handle the whole use case in memory.

  1. Create the JMS connection factories:

    asadmin create-jms-resource --restype=javax.jms.QueueConnectionFactory --description="Cejug-Classifieds Registration Connection Factory." RegistrationQueueConnectionFactory

    asadmin create-jms-resource --restype=javax.jms.QueueConnectionFactory --description="Cejug-Classifieds Notification Connection Factory." NotificationQueueConnectionFactory

    Notice that JMS is a bit simpler than DataSource, you don't need to specify users and passwords since the Open JMS is part of the Glassfish itself (instead of accessing an external database)

    Test the JMS connection pool (yes, the test is the same since all connections pools are the same type resource in Glassfish):

    asadmin ping-connection-pool RegistrationQueueConnectionFactory
    Command ping-connection-pool executed successfully.
  2. Create the JMS Queues:

    asadmin create-jms-resource --restype=javax.jms.Queue --description="Queue used to register Cejug-Classifieds users." RegistrationQueue

    asadmin create-jms-resource --restype=javax.jms.Queue --description="Queue used to notify Cejug-Classifieds users." NotificationQueue

    The same command is valid for both Linux and windows.

  3. Test the JMS resource:

    asadmin --user admin list-jms-resources
    RegistrationQueue
    NotificationQueue

    Command list-jms-resources executed successfully.

Here you can find a sample code using the notification queue and here you find another MessageDrivenBean consuming the registration queue.

Creating a JavaMail resource with asadmin

At this point I hope you already identified a pattern on creating resources in the Glassfish server, the commands are similar and the most important details are the parameter values. To create a connection with an SMTP server you need only one command, since there is no pooling for SMTP connections.

  1. Create the JavaMail resource:

    asadmin --interactive=false create-javamail-resource --mailhost=$MAIL_HOST --mailuser=$MAIL_USER --fromaddress=$MAIL_FROM --enabled=true --description="e-Mail account used to confirm the registration of the Arena PUJ users" --storeprotocol=imap --storeprotocolclass=com.sun.mail.imap.IMAPStore --transprotocol smtp --transprotocolclass com.sun.mail.smtp.SMTPSSLTransport --property mail-smtp.user=$MAIL_SMTP_USER:mail-smtp.port=465:mail-smtp.password=$MAIL_SMTP_PASSWORD:mail-smtp.auth=true:mail-smtp.socketFactory.fallback=false:mail-smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory:mail-smtp.socketFactory.port=$MAIL_SMTP_PORT:mail-smtp.starttls.enable=true mail/classifieds

    Example with the fake password for Cejug-Classifieds:

    • The same command for both Linux and windows:

      asadmin --interactive=false create-javamail-resource --mailhost=smtp.gmail.com --mailuser=cejug.classifieds --fromaddress=cejug.classifieds@gmail.com --enabled=true --description="e-Mail account used to confirm the registration of the Cejug-Classifieds users" --storeprotocol=imap --storeprotocolclass=com.sun.mail.imap.IMAPStore --transprotocol smtp --transprotocolclass com.sun.mail.smtp.SMTPSSLTransport --property mail-smtp.user=cejug.classifieds@gmail.com:mail-smtp.port=465:mail-smtp.password=fake:mail-smtp.auth=true:mail-smtp.socketFactory.fallback=false:mail-smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory:mail-smtp.socketFactory.port=465:mail-smtp.starttls.enable=true mail/classifieds
  2. Test the JavaMail resource:

    asadmin --user admin list-javamail-resources
    mail/classfieds

    Command list-javamail-resources executed successfully.

Here you find an example of code using the JavaMail resource.

Using Shell Script or BAT files to trigger asadmin commands

Now you are exposed to a sert of examples of useful asadmin commands, it is time to think about an efficient way of executing them - and the best way I can imagine is the authomatization of resources creation through script files. If you are working in a unix-like operational system you will use a Shell Script, and if you are using Windows you need to create a batch file (*.bat). The asadmin commands are the same, but we have three distinct points to care between linux and windows:

  1. Semi-colon X Colon: Windows uses semi-colon; while Linux uses colon: as parameters separator. And there is another hidden trap in our asadmin commands: when you pass quoted parameters to the asadmin like "User=$MYSQL_USER:Password=$MYSQL_PASSWORD:URL=$DB_URL" you always need to use colon since the String will be interpreted by a Java code and not by the operational system.

  2. Inverted Slashes: The wndows uses inverted slashes\ while Linux uses slashes/ as paths separator. This is important in the JDBC resources, because the JDBC URL depends on the OS - for example:

    • Linux: URL=jdbc\\:mysql\\://localhost\\:3306/classifieds

    • Windows: DB_URL=jdbc\:mysql\://localhost\:3306/classifieds

  3. Use CALL for executing the asadmin commands on Windows, otherwise the batch file will exit after the first command. Example:

    CALL asadmin --user=%ASADMIN_USER% create-jdbc-resource --connectionpoolid jdbc/classifiedsPool jdbc/classifieds
  4. You can also delete the Glassfish resources with the asadmin commands, that's useful to cleanup the Glassfish and also to be sure that a previous or misconfigured resource won't be used. For example:

    asadmin --passwordfile=$PASS_FILE delete-jms-resource RegistrationQueueConnectionFactory
    asadmin create-jms-resource --restype=javax.jms.QueueConnectionFactory --description="Cejug-Classifieds Registration Connection Factory." RegistrationQueueConnectionFactory

    The first command will throw some error messages if the resource is not present, but the second command will run anyway.

As example you can download the scripts of Cejug-Classifieds here:

Summary

asadmin is a powerful tool, specially if added to a continuous integration environment like Hudson. With scripts it is quite simple to do that, and it will push your project to a next quality level. I just can't imagine to run a project in Glassfish without such scripts, but it is up to you to evaluate this option. Also keep in mind that the above scripts are just a glimpse on the features of the asadmin, you can do much more like deploy and undeploy the Java EE applications or check if they are working fine. There are also a chance to extend the asadmin tool like demonstrated by Sreenivas Munnangi and by Nachiappan. I see a portability issue on this approach but eventually you need that so you know where to look for.

Any issue or question, please be my guest to contribute with my open-source projects.

AttachmentSize
res.png45.61 KB