servlet hosting logo
Contact us: +44 (0) 1491 413606 - contact@nameonthe.net
Members of
Members of Nominet Ripe member WorldPay Guarantee
We accept the following payment methods:
Visa payments supported by WorldPay Visa/Delta payments supported by WorldPay Visa/Electron payments supported by WorldPay Mastercard payments supported by WorldPay Switch payments supported by WorldPay JCB Solo payments supported by WorldPay
JBOSS - Quick Start Guide

This guide assumes you have a working nameonthe.net JBOSS account to use. Other assumptions include some knowledge of working within a Unix shell.

Upon account creation nameonthe.net will have installed a working version of jboss integrated with tomcat into an area of your webspace. By default your jboss server will not be started when you log in for the first time.

Starting Jboss

By default jboss is installed in the /usr/jboss directory of your chrooted (private area) account. To start up jboss when you log in for the first time, use the run.sh script located in the /usr/jboss/bin directory. Jboss will send it's output to the console so you will see screens of the messages jboss sends to the console as it starts up. Since these messages will also be placed within the jboss log directory it is often useful to suppress these if working from within the shell. To suppress messages being sent to the console invoke the run.sh script as shown below which instruts the shell to ignore any messages from STDERR. ./run.sh 2>/dev/null &

If your jboss server started with no errors (which will be typically caused by errors in the configuration files), you will find that you can contact your jboss/tomcat server by looking at your domain in a web browser. As you have not placed any content into the web area you will see a Tomcat error page telling you that no context is enabled to handle the request. This is normal. If your browser times out, view the log files (/usr/jboss/server/default/logs/server.log and /usr/jboss/server/default/logs/boot.log) and look for any evidence of Exceptions. When you start up JBoss for the first time you should not see any Exceptions, please contact support for assistance.

JBoss Ports

When JBoss starts up it binds to ports which provide the TCP/IP interface clients use to access the JBoss services. When Name On The Net set up your JBoss account it will be configured to listen on a range of ports. When configuring clients to access JBoss services you must be aware that the port(s) may differ from the stock JBoss distribution. For example, JBoss ships with JNDI listening on 1099, however you will find that this will be 1xx99 where xx is the range assigned to your JBoss account.

Deploying a web application

Once Jboss has successfully started the first step is to create and deploy a web application. Web applications are often packaged within a .war file which are simply the contents of the web application's directory structure compressed and packaged within a file. The .war extension presents JBoss with the type of resource it will deploy (in this case a webapp). JBoss is configured to look for new resources to deploy within the /usr/jboss/server/default/deploy directory. The jar utility which ships with the JDK can be used to create a war file:

jar cf webapp.war directory

Substitute the webapp.war and directory parameters to those appropriate to the web application being packaged. The name of the war file (minus the .war extension) is used to determine the URI where the webapp can be located. For example, trolley.war would be deployed at the following location: http://www.yourdomain.com/trolley/. Standalone Tomcat deploys a ROOT.war file at the root of the URI: http://www.yourdomain.com/. Tomcat as a JBoss resources does not follow this standard, to instrut JBoss to deploy a webapp at the root level a JBoss specific jboss-web.xml file must be packaged within the war file. The contents can be seen below:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, 
Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<jboss-web>
   <context-root>/</context-root>
</jboss-web>
Alternatives to using .war files to package and deploy web applications are the following

1) Create a .war directory with the deploy directory using the contents of your web application

2) Create a .ear file

A minimal web application would have the following directory structure:

/index.jsp
/WEB-INF/
/WEB-INF/web.xml

To create a war file using jar use this command:

jar cf ROOT.war .

where you are located within the / directory relative to the WEB-INF directory.

Adding EJBs

After you have deployed your web application(s) the next step is to begin using EJBs. In the same process as deploying web applications outlined above, Jboss views EJBs as resources which need to be packaged within .jar files. A minimal EJB .jar file which adheres to the EJB specification would have the following directory structure:

/[path to the interface implemented by the concrete bean]
/[path to the concrete(non abstract) bean]
/[path to the home interface]
/META-INF/ejb-jar.xml
/META-INF/jboss.xml

The xml files within the .jar file provide the EJB container (JBoss in this instance) with the information needing during the deployment and the handling of the bean (security, transactions, JNDI naming etc). Note the jboss.xml is not mandatory, it allows the EJB deployer to supply jboss specific details which are outside the EJB specification's scope. An overview of how to generate the java classes and the subsequent jar file as labeled above is beyond the scope of this guide, the reader is asked to consult external documentation to carry out these step. Once the jar file has been successfully created, the EJB is carried out by copying the .jar file to a directory configured within Jboss to be a deployment directory. As outlined above, the deployment directory is /usr/jboss/server/default/deploy. Once the ejb file has been copied into a deployment directory Jboss will attempt to deploy it. The time taken for Jboss to recognise a new resource is configurable within the jboss.xml file, the default is 5 seconds. After this has been carried out Jboss will have deployed the EJB, check the logs for confirmation.

Using a EJB

Using the business logic contained within the deployed EJB from within a web application involves making the following steps:

It is useful to view this chain of events from within the scope of java code annotated with comments.

  // Create a property object with parameters
  Properties props = new Properties();
  // The class to use to create the InitialContext
  props.put(Context.INITIAL_CONTEXT_FACTORY, 
    "org.jnp.interfaces.NamingContextFactory");
  // The port number, remember the port number is specific
  props.put(Context.PROVIDER_URL,"jnp://localhost:1099");
  props.put(Context.URL_PKG_PREFIXES,
    "org.jboss.naming:org.jnp.interface");

  // Get the Initial Context (1)
  InitialContext jndiContext = new InitialContext(props);
  out.println("Got context");

  // Lookup and get a home instance (2)
  Object ref  = jndiContext.lookup("testbean");
  InterestHome home = (InterestHome) 
    PortableRemoteObject.narrow(ref, TestBeanHome.class);
  
  // Get a instance from the Home interface (3)
  Interest testbean = home.create();

  // Call a method on the business object (4)
  out.println(testbean.callBusinessLogic());

The code above omits key elements such as importing the classes required by the client, error handling and importing the required libraries used the code. However, you should find that the business object returns the correct response. An important aspect is the port used to connect to the JNDI server, this will be assigned to you so you will need to make appropriate adjustments to your code.

Stopping Jboss

With the ability of jboss to hot deploy stopping Jboss will be a rarity except in occasions where the underlying JBoss configuration is modified. The shutdown.sh script located within the same folder as run.sh (/usr/jboss/bin) will shutdown jboss, later versions of JBoss require an additional parameter. The syntax of the shutdown.sh command is:
bin/shutdown -s localhost:[jndi port]

For exhaustive documentation in using and configuring Jboss please consult the Jboss documentation found here: Jboss

username
password
>> Login <<
Latest Java news
System Status
(Sun Feb 05 06:09:11 GMT+00:00 2012)
There are no known network or server problems

Valid XHTML 1.0!

Valid CSS!

Copyright © www.nameonthe.net 1999-2008, All Rights Reserved
All prices exclude VAT