From Ingres Community Wiki

Using JBoss Information Page

Through this and other pages I'm documenting what I've done and used to get JBoss working with Ingres. Please feel free to email me with suggestions, problems, questions, etc. at murray.armfield@ingres.com. I've covered the open source versions of JBoss as well as the Red Hat enterprise versions.

Contents 1 JBoss Overview... 2 JBoss is open source... 3 Flavours of JBoss... 4 JBoss components... 5 Getting started with JBoss... 5.1 Directory structure and type of server to start... 5.2 Databases and JBoss Application server 5.3 Using Ingres as the JBoss Application server's database server... 6 The QAD method of getting JBoss going on Ingres... 6.1 JBoss Application Server version 4.2.3.GA 6.1.1 Using the 'default' server configuration: 6.1.2 Using the 'all' server configuration: 6.1.3 Using JBoss Messaging with JBoss Application Server 4.2.3.GA 6.2 JBoss Application Server version 5.0.0.GA 6.2.1 Using the 'default' server configuration: 6.2.2 Using the 'all' server configuration: 6.2.3 Using JBoss Messaging with JBoss Application Server 5.0.0.GA 6.3 Red Hat SOA Platform 4.3.0.GA 7 Porting of JBoss to use Ingres DBMS

JBoss Overview...

'JBoss' is a term that really means 'a JBoss Application Server'. JBoss Application Server is an open source application server. It is a comprehensive platform for developing, testing, integrating and running enterprise class applications. It really consists of a selectable group of components all running on top of a microcontainer kernel providing an application stack for the end user application to run on.

JBoss technology is nearly all built with java. There are only a few platform binaries here and there and unless specifically mentioned in these notes or some documentation, you will not be using them. Hence JBoss can run on any platform that java runs on. The version of java used is at least version 1.5. Some of the components also support java 6. Using the latest version of Sun's Java virtual machine 1.5 is my recommended version to use, but feel free to investigate the documentation of the different components and using Java v6. Using either 32bit or 64bit java is supported.

A 'neat' picture illustrating this architecture can be found here.

This picture illustrates many of the JBoss components available and where the run/sit with respect to each other.

JBoss application server can run as a distributed and/or clustered architecture for active/active redundancy of applications and the server itself, and providing scalability etc.

JBoss is open source...

All of the JBoss components and server are open source projects. Each project is effectively run as an independent project with their own project owners, leaders, architects, developers, testers etc. All of the projects are housed around the jboss.org site and make use of a lot of common infrastructure such as issue tracking, source code control, wikis, etc. The actual team members of a project may be employees of Red Hat or other commercial entities, but with respect to a JBoss component, it is their open source identity that controls and runs the project.

Flavours of JBoss...

The primary JBoss project in a sense is the JBoss Application Server. While inidividual components can be used in a standalone fashion, and are such as hibernate or seam, to use JBoss means to have a running JBoss Application Server. When you download the application server, it comes pre-bundled with a set of JBoss components but not all and the set varies from version to version. The base JBoss Application Server comes with only a minimal set of JBoss components pre configured. Red Hat also distributes a set of JBoss Application Servers which have additional JBoss components pre-configured into the server for specific roles. Red Hat offers the following JBoss Application Server stacks:

   * JBoss Enterprise Application Platform
   * JBoss Enterprise Portal Platform
   * MetaMatrix? Enterprise Data Services Platform
   * JBoss Enterprise SOA Platform
   * Red Hat Application Stack 

Additionally, Red Hat offers some additional products to help develop, manage and operate your JBoss Application Servers. They are:

   * JBoss Developer Studio
   * Red Hat Developer Professional and Enterprise
   * JBoss Operations Network 

These Red Hat products can be browsed at the following link, [1]

Red Hat offers extensive support for development and production, patches and updates, multi-year maintenance policies and software assurance for the jboss.com offering which can be found at the following link, [2]

JBoss components...

JBoss Application Server(AS) supports the running of many different technologies and infrastructure pieces.

Some of the JBoss AS solution components are:

• JBoss Web Services[3] providing SOA and standards based web services.
• JBoss Cache[4] providing a tree-structured, clustered, transactional cache providing the back bone technology for many application server clustered services
• JBoss Transactions[5] providing an application level transaction server to provide complete, accurate business transactions for java based applications.
• JGroups[6] a flexible protocol stack for reliable multicast communication between AS nodes.
• JBoss Remoting[7] providing a single API for network based invocations and pluggable transports using data marshallers.
• JBoss Messaging[8] providing an enterprise messaging system integrated with JBoss Transactions.
• JBoss Web[9] providing an enterprise web server built on top of tomcat.
• JBoss Portal[10] for hosting and serving a portal's web interface, publishing and managing content and customising a users experience.
• JBoss ESB[11] providing the next generation of Enterprise Application Integration as part of a Service Orientation Infrastructure.
• JBoss jBPM[12] providing business process management over workflow to service orchestration.
• Drools[13] providing a business rule management system and an enhanced rules engine implementation.
• Mobiclients[14] providing a high performance core engine for Service Delivery Platforms(SDP) and IP Multimedia subsystems(IMS).

Some of the JBoss AS technologies involved are:

• Hibernate[15] providing powerful, high-performance object/relational persistence and query services.
• JBoss AOP[16] providing aspect orientated programming for organising cross cutting concerns.
• JBoss Security[17] and identity management and Single-Sign-On providing security.
• JBoss Serialization[18] providing a new approach to java object serialization.
• JBoss EJB3[19] providing enterprise java beans version 3 implementation of enterprise java beans greatly simplifying and empowering java development.
• Seam[20] providing a powerful development environment for rich internet applications writen in java.
• Profiling, debugging and development tools for development platforms such as eclipse.

Getting started with JBoss...

The first thing to do to get started with JBoss is to download the application server from here. Currently there are two main distribution lines, version 4.X which is up to version 4.2.3.GA and version 5.X which is up to version 5.0.0.GA as of writing this page. Version 5.0.0.GA was released recently on 2008-12-05.

Once you have download the application server, you can read the documentation on the application server wiki page, located here, or read below on how to get started. This will tell you how to extract the download and configure some environmental variables etc.The application server with very little configuration is ready to start.

The basic things to do to get started are:

1. Extract your JBoss Application server download to where you want it installed.
2. Ensure you have the correct version of java JDK install. Sun java SDK 1.5 is safest. Both 32bit and 64bit work correctly. Check product documentation if you can use Sun java SDK 6. If you don't have the rught version of java installed, please consult your operating systems/platforms notes/guides/etc for help.
3. Make sure the following environment variables are set. JAVA_HOME to your Java JDK directory and JBOSS_HOME to your JBoss Application Server install and the bin directories under both added to your path. This can be done by adding the following lines to your .bashrc file or similar.

        export JAVA_HOME=/usr/java/jdk1.5.0_14

        export PATH=$PATH:$JAVA_HOME/bin

        export JBOSS_HOME=/usr/jboss/jboss-4.2.3.GA

        export PATH=$PATH:$JBOSS_HOME/bin

Once you have done this and reloaded your .bashrc or similar for the environment variables to take affect, you can start the JBoss application server by opening a terminal and changing to the directory $JBOSS_HOME/bin and typeing ./run.sh. The terminal will now display all the messages as the server starts up. It will take a few minutes. Once that is done, you should be able to open a web browser to http://localhost:8080/ and get a page from your JBoss server with some resource and management links.To stop the JBoss application server, just enter <Control>-C in the terminal window. This cleanly shuts down the application server.

Directory structure and type of server to start...

Once you have installed/extracted the application server download, the following directory structure is created.

jboss-4.2.3.GA/

    bin/

    client/

    docs/

    lib/

    server/

        all/

        default/

        minimal/ 

The directories under the jboss-4.2.3.GA/server/ directory are the three different configurations that shipped with this application server download. 'default' is a standalone basic JBoss server while 'all' has more components and is ready to run as a clustered JBoss server. If you started the application server as above by typing ./run.sh, it started the default server. The server that starts can be controlled by entering ./run.sh -c all for example to start the 'all' configuration. Again, entering <Control>-c in the terminal window will shutdown the application server.

If you want to use an init.d type script and have jboss starting/stopping with your machine, here are three scripts you can use. One for JBoss Application Server 4.2.3.GA, one for JBoss Application Server 5.0.0.GA and one for Red Hat SOA Platform 4.3.0.GA. These scripts I have adapted to work on opensuse. If you use them, please remember to ensure that you have the correct JBoss install and java JDK install details in your version. Please feel free to email me scripts for other platforms or add them yourself to this page.

init.d script for opensuse, jboss AS 4.2.3, the init.d script is called 'jboss4'

init.d script for opensuse, jboss AS 5.0.0.GA, the init.d script is called 'jboss5'

init.d script for opensuse, Red Hat SOA platform 4.3.0.GA, the init.d script is called 'jboss'

These startup scripts can be downloaded from this zip file, jboss-init.zip.

These scripts can as per usual be used manually with the usual start/stop parameters to start and stop the application server. These scripts want to run the jboss server under a username jboss in the jboss group. You may need to create this username and group. The JBoss installation directory should then all be owned by the jboss:jboss user/group.

NOTE: If you use the above start/stop scripts, you have to create an additional directory in your JBoss Application server install for logging. The directory to create is $JBOSS_HOME/log. It should also be writable by the jboss:jboss user/group. This is where the startup and shutdown messages go instead of the console. It is handy to watch this file as the server starts up for problems.

Databases and JBoss Application server

The application server be default is configured to run using the hsql java database server for all JBoss server components. If you have started running the server, this is what it is using. This datasource configuration is saved in the JNDI as DefaultDS. The definition for this connection is in the server/'srvr config'/deploy directory in a file hsqldb-ds.xml.

Adding the definition for using another database server via jdbc is very easy. All that needs to be done is add your xml datasource configuration file to the server/'srvr config'/deploy directory. The specification of this xml file can be found in the jboss-ds_1_5.dtd file in the dtd directory in the docs directory. A sample data source configuration file for ingres is provided below. It is loaded into the JNDI as IngresDS.

Sample ingres datasource configuration file is inside this zip: ingres-ds.zip

This file should be updated with your particular ingres server settings.

If you start your application server now, you should see this datasource mentioned by its JNDI name in the start-up with no errors. From here you can write something to use the Ingres database server.

Using Ingres as the JBoss Application server's database server...

The JBoss documentation says very strongly that the hsql java database server should not be used in a production installation of a JBoss server, hence the hsqldb-ds.xml file should be removed and replaced with a production database server configuration file. In the Ingres datasource configuration file, the JNDI name should be changed to DefaultDS.

The consequences of this is that Ingres as a database server needs to be tested and proven against each component of the JBoss Application Server that uses the DefaultDS jndi resource for a fully compliant, tested and proven JBoss Application server running on Ingres. This work can be broken down into several subjobs of which substantial progress has been made.

These instructions are specifically for Ingres version 9.2 enterprise. The community versions of Ingres 9.2 or higher can be made to work, but additional work is required due to the differences in the SQL language between the community and enterprise versions. The Ingres database platform being used for all this work is linux 32-bit.

The recommended settings for your Ingres 9.2 enterprise database server are:

    DBMS Server -> blob_etab_page_size = 8192

    DBMS Server -> connect_limit = 128 (or more)

    DBMS Server -> qsf_guideline = large (or 'huge')

    DBMS Server -> system_lock_level = row

    DBMS Server -> table_auto_structure = on

    Locking System -> per_tx_limit = 2500 (or more) 

There are other settings you can play with to help benefit performance, but these will be implementation dependant. The above settings should be a minimum configuration.

For example:

1. Increasing cache_guideline for 2K and 8K DMF Caches.
2. Setting DBMS Server -> blob_etab_structure = HASH speeds up some of the stress tests of JBoss Messaging.

The QAD method of getting JBoss going on Ingres...

JBoss Application Server version 4.2.3.GA

In your JBoss AS 4.2.3.GA install, there is a directory docs/examples which has several directories below it with sample files for getting things going with a different underlying database. The ingres versions of these files are named as below and are in the zip file below.

docs/examples/jca/ingres-ds.xml

docs/examples/jms/ingres-jdbc2-service.xml

The above-two files should be used as per the JBoss Application server documentation with respect to using a different database server. Remember to change the JNDI name of the ingres data source to DefaultDS in both of the above two files if you are planning to use ingres as the database.

The steps required to make the application server work on Ingres are below and depend on the server configuration you wish to use.

Here is a zip file containing all the files needed for using JBoss AS 4.2.3.GA with Ingres: jboss4-ingres.zip

Using the 'default' server configuration:

1. In the server/default/deploy/ejb3.deployer/META-INF/persistence.properties file, uncomment the following line and change it to

    #hibernate.dialect=org.hibernate.dialect.HSQLDialect

    to

    hibernate.dialect=org.hibernate.dialect.IngresDialect 

2. Replace the server/default/conf/standardjbosscmp-jdbc.xml file with the one in the zip file above. It has an updated Ingres CMP and the fk-contraint property set is set to true.

3. Copy your iijdbc.jar file into the server/default/lib directory from your ingres install (its in the lib directory)

4. Copy the ingres data source file in the zip file above, ingres-ds.xml, into server/default/deploy and delete the hsqldb-ds.xml file in the same folder. Remember to change the jndi name of the datasource as mentioned above.

5. Copy the ingres jmx persistence file in the zip file above, ingres-jdbc2-service.xml into server/default/deploy/jms and delete the hsqldb-jdbc2-service.xml file in the same folder. This step is slightly different if you are using the 'all' server configuration - see below. Again, remember to change the jndi name of the data source to use as mentioned above.

Using the 'all' server configuration:

If you want to use the 'all' server configuration, repeat the steps above for the 'default' server configuration in the 'all' server directory except for the last step, step 5. Step 5 is replaced with step 1 below.

You will need the additional files in this zip file, jboss4-all-ingres.zip.

1. In the above instructions for the 'default' server configuration, a different ingres-jdbc2-service.xml file needs to go into the server/all/deploy-hasingleton/jms directory and delete the hsqldb-jdbc2-service.xml file in the same folder.

This file needs to be renamed to ingres-jdbc2-service.xml before inserting into the all/deploy-hasingleton/jms directory.

2. In server/all/deploy/juddi-service.sar/META-INF/ddl, replace the following files with their ingres versions from the zip file above

    juddi_create_db.ddl

    juddi_data.ddl

Using JBoss Messaging with JBoss Application Server 4.2.3.GA

JBoss Messaging can be used as a replacement messaging implementation on JBoss AS 4.2.3.GA. The instructions on how to do this can be found on the JBoss Messaging wiki page.

JBoss Application Server version 5.0.0.GA

In your JBoss AS 5.0.0.GA install, there is a directory docs/examples which has several directories below it with sample files for getting things going with a different underlying database. The ingres versions of these files are named as below and are in the zip file below.

docs/examples/jca/ingres-ds.xml

docs/examples/jms/ingres-persistence-service.xml

The above-two files should be used as per the JBoss Application server documentation with respect to using a different database server. Remember to change the JNDI name of the ingres data source to DefaultDS in the ingres-ds.xml file. The ingres-persistence-service.xml file already has its jndi data source set to DefaultDS.

The steps required to make the application server work on Ingres are below and depend on the server configuration you wish to use.

Here is a zip file containing all the files needed for using JBoss AS 5.0.0.GA with Ingres: jboss5-ingres.zip

Using the 'default' server configuration:

1. In the server/default/deployers/ejb3.deployer/META-INF/persistence.properties file, uncomment the following line and change it to

    #hibernate.dialect=org.hibernate.dialect.HSQLDialect

    to

    hibernate.dialect=org.hibernate.dialect.IngresDialect 

Note that the directory is 'deployers' on AS 5.X instead of 'deploy' on AS 4.X

2. Replace the server/default/conf/standardjbosscmp-jdbc.xml file with the one in the zip file above. It has an updated Ingres CMP and the fk-contraint property set is set to true.

3. Copy your iijdbc.jar file into the server/default/lib directory from your ingres install (its in the lib directory)

4. Copy the ingres data source file from the zip file above, ingres-ds.xml, into server/default/deploy and delete the hsqldb-ds.xml file in the same folder. Remember to change the jndi name of the datasource as mentioned above.

5. Copy the ingres messaging persistence file from the zip file above, ingres-persistence-service.xml, into server/default/deploy/messaging and delete the hsqldb-persistence-service.xml file in the same folder. This step is slightly different if you are using the 'all' server configuration - see below.

Using the 'all' server configuration:

If you want to use the 'all' server configuration, repeat the steps above for the 'default' server configuration in the 'all' server directory except for the last step, step 5. Step 5 is replaced with step 1 below.

You will need the additional files in this zip file, jboss5-all-ingres.zip.

1. A different version of the ingres messaging persistence file, ingres-persistence-service.xml, needs to be used instead of the one above. It is in the 'all' zip file above.
2. In server/all/deploy/juddi-service.sar/META-INF/ddl, replace the following files with their ingres versions

    juddi_create_db.ddl

    juddi_data.ddl

Using JBoss Messaging with JBoss Application Server 5.0.0.GA

With JBoss Application Server 5.0.0.GA, JBoss Messaging has been incorporated as the default messaging implementation, replacing the messaging service found in the previous releases of JBoss Application Server.

Red Hat SOA Platform 4.3.0.GA

The Red Hat SOA Platform 4.3.0.GA installation directory layout is different to the JBoss Application Server directory layouts. The top level directory is jboss-soa-p.4.3.0. Under this directory is the directory jboss-as. This is the application server directory of the installation and the path of this directory is what should be used in your environment variable JBOSS_HOME.

In the jboss-as directory, there is a tools directory. In the tools directory, there is a schema directory. The schema directory is a utility to automate the configuration of the application server to use a different database provider. In order to use this with Ingres, download the schema.zip tarball and extract it over the schema directory. It should add and update the files in the schema directory for using Ingres. Once that is done, you will need to copy your ingres jdbc library jar file(iijdbc.jar) into the schema/ingres/driver directory.

The 'schema' tool can be used either interactively or automated. To use its automated method, the build.properties file needs to be edited with the following changes:

1. Uncomment org.jboss.esb.server.config=all and leave 'all' or change it to the server configuration you wish to run the tool against.
2. Uncomment org.jboss.esb.server.database=ingres
3. Uncomment source.dir=ingres
4. Uncomment db.name and set it equal to the name of the ingres database you wish to use.
5. Uncomment db.hostname and set it equal to the name of the ingres server you wish to use.
6. Uncomment db.port and set it equal to the ingres port you wish to use (eg II7).
7. Uncomment db.username and db.password and set them equal to the ingres username and password you wish to use.

Once you have set all your values, just execute 'ant' in the schema directory to run the build.xml file. I recommend using the automated method so you can re-use it readily for other server configurations, or rerun it trying different changes on our own.

Then you should download the following zip file which has all the files for the steps below. Media:jboss-soa-2.zip

Then perform the steps below before starting the server. They are:

1. In server/all/deploy/juddi-service.sar/META-INF/ddl, replace the following files with their ingres versions

           juddi-service.sar/META-INF/ddl/juddi_create_db.ddl
           juddi-service.sar/META-INF/ddl/juddi_data.ddl

2. In server/all/deploy/jbossesb.esb/message-store-sql, create an ingres directory and add the following two files to it:

           jbossesb.esb/message-store-sql/ingres/create_database.sql
           jbossesb.esb/message-store-sql/ingres/drop_database.sql

3. In server/all/deploy/jbossesb.sar/juddi-sql, create an ingres directory and add the following files to it:

           jbossesb.sar/juddi-sql/ingres/create_database.sql
           jbossesb.sar/juddi-sql/ingres/import.sql
           jbossesb.sar/juddi-sql/ingres/README

4. In the server/all/deploy/ejb3.deployer/META-INF/persistence.properties file, uncomment the following line and change it to

    #hibernate.dialect=org.hibernate.dialect.HSQLDialect

    to

    hibernate.dialect=org.hibernate.dialect.IngresDialect 

5. Replace the server/all/conf/standardjbosscmp-jdbc.xml file with the one in the zip file above. It has an updated Ingres CMP and the fk-contraint property set is set to true.

Porting of JBoss to use Ingres DBMS

In order for a JBoss Application Server to operate on Ingres out-of-the-box, Ingres support must be added to each software component in the stack that uses a database backend as part of its operation in the JBoss stack. Considering that each individual JBoss component is a project in its own right, the porting work needs to be done on an individual component basis working up to the whole. Below are links to individual wiki pages on the each of the different components of JBoss and using them with Ingres.

• Using JBoss Messaging with Ingres
• Using JBoss ESB with Ingres
• Using Apache jUDDI with Ingres
• Using Apache Jackrabbit with Ingres