Getting Started Guide
for Use with JBoss Enterprise Application Platform 5
Edition 5.2.0
Eva Kopalova
Petr Penicka
Russell Dickenson
Scott Mumford
Abstract
Chapter 1. Other Conventions
- <JBOSS_HOME>
- <JBOSS_HOME> refers to the directory that your instance of JBoss Enterprise Application Platform has been extracted/installed to. For example:
/home/USERNAME/jboss-eap-<VERSION>/
- <PROFILE>
- <PROFILE> refers to the directory that contains the server profile you are making changes to. It may be a test profile or a production profile.More information about server profiles and their locations is in Section 2.1, “Server Profiles”.
- <DOMAIN_NAME>
- <DOMAIN_NAME> refers to the name you have configured for your JBoss Enterprise Application Platform instance.This name is used in some configuration files. Replace this notation, where appropriate, with the name of your domain.
Chapter 2. JBoss Enterprise Application Platform Overview
*-jboss-beans.xml
) and legacy MBean (*.jboss-service.xml
) deployments. For more information refer to the Administration and Configuration Guide.
Important
2.1. Server Profiles
<JBOSS_HOME>jboss-as/server/
directory:
- all
- The
all
profile covers all available services and components, including the RMI/IIOP and clustering services, which are not loaded in the default configuration. - default
- The
default
profile is a base Java EE 5 server profile containing a default set of services. It covers the most frequently used services required to deploy a Java EE application. The JAXR service, the IIOP service and the clustering services are not included. This profile is applied if a server is started without specifying a configuration. - production
- The
production
profile is based on theall
profile and is intended for production. It has a reduced log verbosity, deployment scanning takes place every 60 seconds, and memory usage is tuned to accommodate production deployment requirements. - minimal
- The
minimal
profile uses the minimum services required to start JBoss. It starts the logging service, a JNDI server and a URL deployment scanner to find new deployments. You can use it when using JMX/JBoss to start your own services without any other Java EE 5 technologies. It starts only the server: no web container, EJB, or JMS support is available. - standard
- The
standard
profile is the JavaEE 5 certified configuration of services. - web
- The
web
profile is a lightweight web-container oriented profile that previews the JavaEE 6 web profile.
default
profile is used if you do not specify a configuration when running a server.
Chapter 3. Starting and Stopping the Server
3.1. Starting the Server
<JBOSS_HOME>/jboss-as/bin
directory and execute the run.sh
(on Red Hat Enterprise Linux) or run.bat
(on Microsoft Windows) script. The server instance is run with the configuration set in the default
profile as no other profile was specified.
Important
-b
option. To bind to all available interfaces and re-enable the legacy behavior use ./run.sh -b 0.0.0.0
on Linux . Make sure you secure your server properly.
-b
as part of the server's command line is equivalent to setting these individual properties: -Djboss.bind.address, -Djava.rmi.server.hostname, -Djgroups.bind_addr and -Dbind.address. Passing -Djboss.bind.address to the Java process as part of the JAVA_OPTS
variable in the run scripts will not work as it is a JBoss property not a JVM property.
[user@mypc bin]$ ./run.sh ========================================================================= JBoss Bootstrap Environment JBOSS_HOME: <JBOSS_HOME>/jboss-as JAVA: java JAVA_OPTS: -Dprogram.name=run.sh -server -Xms1503m -Xmx1503m -Dsun.rmi.dgc.client. gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv4Stack=true CLASSPATH: <JBOSS_HOME>/jboss-as/bin/run.jar =========================================================================
run
script are discussed in Section 3.1.1, “Starting the Server with Alternate Configuration” below.
Note
production
profile. This message may be observed in the server.log
file located in the server/production/log
subdirectory.
3.1.1. Starting the Server with Alternate Configuration
run.sh
without any arguments starts the server using the default
server profile file set. To start with an alternate profile file set, pass the name of the server configuration file set (same as the name of the server configuration directory under <JBOSS_HOME>/jboss-as/server/<PROFILE>/
) that you want to use, as the value to the -c
command line option. For example, to start with the minimal
profile file set you should specify:
[bin]$ ./run.sh -c minimal ... ... ... 15:05:40,301 INFO [Server] JBoss (MX MicroKernel) [5.0.0 (build: SVNTag=JBoss_5_0_0 date=200801092200)] Started in 5s:75ms
3.2. Stopping the Server
shutdown.sh
command.
[bin]$ ./shutdown.sh -S
Note
shutdown
command can be only used for servers that contain the jmx-invoker-service.xml
service. Hence you cannot use the shutdown
command with the minimal
profile.
Chapter 4. Server as a Service
4.1. Running as a Service on Microsoft Windows
Download the Native Components archive
Navigate to http://access.redhat.com and download the Native Components archive which matches the host's architecture.Extract thenative
directory (and any sub-directories) contained in the archive to$JBOSS_HOME
.Open a command prompt with elevated privileges.
Navigate toC:\Windows\System32
and right-click oncmd.exe
. Select Run as Administrator .Change to the JBoss Enterprise Application Platform directory where the service installation script is located.
cd
$JBOSS_HOME\native\sbin
Edit
service.bat
to specify the profile and local IP address to be used.Theservice.bat
file by default uses thedefault
profile and binds to IP address127.0.0.1
, neither of which are suitable for production use.ChangeSVCPROFILE=default
, replacingdefault
with the required profile's name.Changeset SVCBINDIP=127.0.0.1
, replacing127.0.0.1
with the required IP address.Note
For a full list of profiles and the services they include, refer to the Standard Server Profiles section of the Administration and Configuration Guide.Run the service installation script.
service.bat install
Check that the service is installed.
Under the Windows services list you will find this listed by the short nameJBAS52SVC
and the long nameJBoss Application Server 5.2
.
4.1.1. Removing the Service
Stop the service.
Stop the service using Service Manager.Delete the service.
Issue the following command from the command prompt with elevated privileges:sc delete JBAS52SVC
4.2. Running as a Service on Red Hat Enterprise Linux
/etc/init.d/jbossas
, which is run automatically when Red Hat Enterprise Linux starts.
/etc/sysconfig/jbossas
. If you want a profile other than "default" used, change the "JBOSSCONF=" line, specifying the required profile. The service must be restarted for this change to take effect.
Note
Note
Chapter 5. Basic Configuration Changes
5.1. Security Configuration
Important
Important
5.1.1. Security Configuration: JMX Console, Admin Console, HttpInvoker
Procedure 5.1. Create jmx-console, admin-console, and http invoker user account
Create a user in the default JAAS security domain
- Edit the file
$JBOSS_HOME/server/$PROFILE/conf/props/jmx-console-users.properties
. - Create a username = password pair.
Important
The commentedadmin=admin
username and password pair is an example of the username/password definition syntax. Do not use this for your user account.
Grant permissions to user
- Edit the file
$JBOSS_HOME/server/$PROFILE/conf/props/jmx-console-roles.properties
. - Create an entry for the user of the form:
username=JBossAdmin,HttpInvoker
- JBossAdmin
- Grant the user permission to access the JMX Console and Admin Console.
- HttpInvoker
- Grant the user permission to access the httpinvoker
5.1.2. Securing the HTTPInvoker
Procedure 5.2. Secure the HTTP Invoker
- Edit the
<JBOSS_HOME>/server/<PROFILE>/conf/bindingservice.beans/META-INF/bindings-jboss-beans.xml
file. - Add the
hostName
andfixedHostName
properties to the deploy/legacy-invokers-service.xml section:<!-- ************ deploy/legacy-invokers-service.xml ************ --> <!-- RMI/JRMP invoker --> <bean class="org.jboss.services.binding.ServiceBindingMetadata"> <property name="serviceName">jboss:service=invoker,type=jrmp</property> <property name="port">4444</property> <property name="description">Socket for the legacy RMI/JRMP invoker</property> <property name="hostName">localhost</property> <property name="fixedHostName">true</property> </bean> <!-- Pooled invoker --> <bean class="org.jboss.services.binding.ServiceBindingMetadata"> <property name="serviceName">jboss:service=invoker,type=pooled</property> <property name="port">4445</property> <property name="description">Socket for the legacy Pooled invoker</property> <property name="hostName">localhost</property> <property name="fixedHostName">true</property> </bean>
5.1.3. Security Configuration: Web Console
Procedure 5.3. Creating Web Console User Account
Create a user in the web-console JAAS security domain.
- Edit the file
web-console-users.properties
injboss-as/server/$PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/
. - Create a username = password pair.
Important
The commentedadmin=admin
username and password is an example of the username/password definition syntax. Do not use this for your user account.
Grant permissions to the user.
- Edit the file
web-console-roles.properties
injboss-as/server/$PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/
. - Create an entry for the user of the form:
username=JBossAdmin,HttpInvoker
- JBossAdmin
- Grant the user permission to access the Web-Console
- HttpInvoker
- Grant the user permission to access the HTTP Invoker
5.1.4. Security Configuration of JBoss Messaging
suckerPassword
in the messaging and server configuration files.
jboss-as/server/$PROFILE/deploy/messaging/messaging-jboss-beans.xml
file and the messaging-service.xml
file. These files contain directives that specify the encrypted suckerPassword
.
Changing the Password in messaging-jboss-beans.xml
messaging-jboss-beans.xml
.
Procedure 5.4. Setting suckerPassword for JBoss Messaging
- Navigate to the
<JBOSS_HOME>/server/<PROFILE>/deploy/messaging/
directory. - Open the
messaging-jboss-beans.xml
file in your preferred text editor. - Change the
suckerPassword
placeholder value from"CHANGE ME!!"
to a plain text password:<property name="suckerPassword">CHANGE ME!!</property>
Make note of the new password; it will be used in the next task. - Save the file.
Creating the encrypted JBoss Messaging suckerPassword
- In a terminal, change to
<JBOSS_HOME>/server/<PROFILE>/deploy/messaging/
. - Run the following command:
/path/to/java/executable -cp JBOSS_HOME/client/jboss-messaging-client.jar org.jboss.messaging.util.SecurityUtil PLAIN_TEXT_PASSWORD
- PLAIN_TEXT_PASSWORD is the password you set in
messaging-jboss-beans.xml
in the previous task.As an example:Example 5.1. Test Encrypted Password
Running the following command (from theJBOSS_HOME/jboss-as/server/$PROFILE/deploy/messaging/
directory) .../usr/bin/java -cp ../../../../client/jboss-messaging-client.jar org.jboss.messaging.util.SecurityUtil test
...produced the following encrypted password:key len: 14 length max: 2147483647 Encoded password: 5e2c1ae5a618317
- Make note of the encrypted password output; it will be used in the next task.
Specifying an encrypted suckerPassword for JBoss Messaging
Prerequisites
- You have a terminal open at the
<JBOSS_HOME>/server/<PROFILE>/deploy/messaging/
directory.
- In a text editor, open the
messaging-service.xml
file. - Paste the encrypted password from the previous procedure into the
SuckerPassword
attribute:<attribute name="SuckerPassword">ENCRYPTED_PASSWORD</attribute>
- Save the
messaging-service.xml
file.
5.2. Memory Settings for the Enterprise Application Platform
-Xms1303m
: initial heap size in megabytes-Xmx1303m
: maximum heap size in megabytes
- Allocate the same values for initial and maximum heap sizes.
- Use values smaller than the host's allocatable memory.
- Be aware of other services and applications running on the host, and allow for their usage of memory.
Procedure 5.5. Changing Memory Settings for the Enterprise Application Platform on Linux
- Navigate to
$JBOSS_HOME/jboss-as/bin
. - Open
run.conf
for editing. - Locate the line with the memory options:
JAVA_OPTS="-Xms1303m -Xmx1303m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Dsun.lang.ClassLoader.allowArraySyntax=true"
- Edit the line to include the new initial and maximum heap sizes for the JVM:
JAVA_OPTS="-XmsINITIAL_HEAP_SIZE -XmxMAX_HEAP_SIZE -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Dsun.lang.ClassLoader.allowArraySyntax=true"
- If the server is runnning, restart it to apply the new settings.
Procedure 5.6. Changing Memory Settings for the Enterprise Application Platform on Windows
- Navigate to
$JBOSS_HOME/jboss-as/bin
. - Open
run.conf.bat
for editing. - Locate the line with the memory options:
set "JAVA_OPTS=-Xms1303m -Xmx1303m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Dsun.lang.ClassLoader.allowArraySyntax=true"
- Edit the line to include the new initial and maximum heap sizes for the JVM:
set "JAVA_OPTS=-XmsINITIAL_HEAP_SIZEm -XmxMAX_HEAP_SIZEm -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Dsun.lang.ClassLoader.allowArraySyntax=true"
- If the server is runnning, restart it to apply the new settings.
5.3. Setting the Default Server Application
<JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/ROOT.war
as the default application on the server. So accessing http://localhost:8080/
results in displaying the index page of this application. If you want your application to be available as the default application, then you will wish to follow these steps:
- Rename
ROOT.war
in<JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy
to something else, for example,jboss.war
. - In your WAR file (the one which you want to be the default application), add a
jboss-web.xml
, in theWEB-INF
folder, with a configuration for the context-root:<?xml version="1.0"?> <!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 5.0//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd"> <jboss-web> <context-root>/</context-root> <!-- Other configurations as needed --> </jboss-web>
By setting the context-root to/
you are making your application the default application. Your application will now be available athttp://localhost:8080/
.Note
Renaming theROOT.war
tojboss.war
will make that application be available athttp://localhost:8080/jboss
5.4. Configuring Legacy Core Services
$JBOSS_HOME/server/PROFILE/conf/jboss-service.xml
file are started just after server starts up the microcontainer. The file contains MBeans for various services including logging, security, JNDI, JNDIView etc. If you commenting out a service, it is not loaded on startup.
Note
Example 5.2. JNDIView MBean Commented out
<!-- Section 1 commented out <mbean code="org.jboss.naming.JNDIView" name="jboss:service=JNDIView" xmbean-dd="resource:xmdesc/JNDIView-xmbean.xml"> --> <!-- The HANamingService service name --> <!-- Section two commented out <attribute name="HANamingService">jboss:service=HAJNDI</attribute></mbean> -->
JNDIView
service no longer appears in the JMX Management Console (JMX Console) listing. In practice, you should rarely, if ever, need to modify this file, though there is nothing to stop you adding extra MBean entries in here if you want to. The alternative is to use a separate file in the deploy
directory, which allows your service to be hot deployable.
5.5. Configuring Logging Service
log4j
is used for logging. If you are not familiar with the log4j
package, more information is available the Jakarta web site.
$JBOSS_HOME/server/PROFILE/conf/jboss-log4j.xml
file. This file defines a set of appenders that specify the log files, the categories of messages the log file should contains, the message format and the level of filtering. By default, JBoss produces output to both the console and a log file (log/server.log
).
Note
TRACE
, DEBUG
, INFO
, WARN
, ERROR
and FATAL
. The logging threshold on the console is INFO
, so that any informational messages, warning messages and error messages are returned to the console, while general debug and trace messages are only available in the log file. If no logging level is set for the server.log
file, it defaults to DEBUG
.
server.log
file to see if there are any debug messages which might help you to track down the problem. However, be aware that just because the logging threshold allows debug messages to be displayed, that does not mean that all of JBoss produces detailed debug information for the log file. You should also consider increasing the logging limits set for individual categories.
Example 5.3. Example Log Limits
<!-- Limit JBoss categories to INFO -->
<category name="org.jboss">
<priority value="INFO"/>
</category>
INFO
for all JBoss classes, with the exception of classes with more specific overrides. By default the root logger in the jboss-log4j.xml
is set to INFO
: any TRACE
or DEBUG
logger from any logger categories is not logged in any files or the console appenders. This setting is controlled through the jboss.server.log.threshold property. By default this is INFO
. If changed to DEBUG
, more detailed logging output is produced. Yuo can change this as follows:
- Pass the -Djboss.server.log.threshold=DEBUG parameter when starting the server:
./run.sh -Djboss.server.log.threshold=DEBUG
- Edit the
<JBOSS_HOME>/jboss-as/server/<PROFILE>/conf/jboss-log4j.xml
file directly:<root> <!-- Let us comment this out to set our own value <priority value="${jboss.server.log.threshold}"/>--> <priority value="DEBUG"/> <appender-ref ref="CONSOLE"/> <appender-ref ref="FILE"/> </root>
Note
The<JBOSS_HOME>/jboss-as/server/<PROFILE>/conf/jboss-log4j.xml
is scanned every 60 seconds (by default) on any changes. Therefore changing this file does not require a server restart.
DEBUG
level and to redirect it to a separate file, cmp.log
, in order to analyze the generated SQL commands. You would add the following code to the conf/jboss-log4j.xml
file:
<appender name="CMP" class="org.jboss.logging.appender.RollingFileAppender"> <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/> <param name="File" value="${jboss.server.home.dir}/log/cmp.log"/> <param name="Append" value="false"/> <param name="MaxFileSize" value="500KB"/> <param name="MaxBackupIndex" value="1"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/> </layout> </appender> <category name="org.jboss.ejb.plugins.cmp"> <priority value="DEBUG" /> <appender-ref ref="CMP"/> </category>
org.jboss.ejb.plugins.cmp
.
cmp.log
. Older files have the date they were written added to their file names. Please note that the log
directory also contains HTTP request logs which are produced by the web container.
server.log
appender is configured to retain log messages between server restarts. This is controlled by the Append property on the FILE
appender which corresponds to the server.log
file. By default this property is set to true; if you want the server.log
contents to be wiped out on server restarts then you can edit the <JBOSS_HOME>/jboss-as/server/<PROFILE>/conf/jboss-log4j.xml
file to set this property value to false. For example:
<appender name="FILE" class="org.jboss.logging.appender.DailyRollingFileAppender"> <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/> <param name="File" value="${jboss.server.log.dir}/server.log"/> <param name="Append" value="false"/> ...
5.6. Additional Services
deploy
directory (refer to Chapter 6, Hot Deployment of Services). They can be either XML descriptor files, *-service.xml, *-jboss-beans.xml
, MC .beans
archive, or JBoss Service Archive (SAR) files. SARs contains an META-INF/jboss-service.xml
descriptor and additional resources the service requires (for example, classes, library JAR files or other archives), all packaged up into a single archive. Similarly, a .beans
archive contains a META-INF/jboss-beans.xml
and additional resources.
Chapter 6. Hot Deployment of Services
JBOSS_DIST/jboss-as/server/<instance-name >/deploy
directory. Let’s have a look at a practical example of hot deployment of services.
JBOSS_DIST/jboss-as/server/default/deploy
directory. Remove the mail-service.xml
file and watch the output from the server:
13:10:05,235 INFO [MailService] Mail service 'java:/Mail' removed from JNDI Then replace the file and watch JBoss re-install the service: 13:58:54,331 INFO [MailService] Mail Service bound to java:/Mail
6.1. Hot-Deployment Configuration
HDScanner
MC bean configured in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hdscanner-jboss-beans.xml
file. For example, the bean sets the scanPeriod attribute, which controls the run interval for the thread that picks up the hot deployable changes. The scanPeriod property is set to 5 seconds by default (refer to Figure 6.1, “HDScanner Bean Default Configuration”).
<bean name="HDScanner" class="org.jboss.system.server.profileservice.hotdeploy.HDScanner"> <property name="deployer"><inject bean="ProfileServiceDeployer"/></property> <property name="profileService"><inject bean="ProfileService"/></property> <property name="scanPeriod">5000</property> <property name="scanThreadName">HDScanner</property> </bean>
Figure 6.1. HDScanner Bean Default Configuration
Note
hdscanner-jboss-beans.xml
file are hot deployable: no server restart is needed.
6.2. Adding a Custom Deploy Directory
JBOSS_DIST/jboss-as/server/<instance-name>/deploy
directory. However you can configure the server to include custom directories for scanning deployments. To do so, configure the BootstrapProfileFactory
MC bean in JBOSS_DIST/jboss-as/server/PROFILE/conf/bootstrap/profile.xml
file: add the custom directory to the applicationURIs property of the BootstrapProfileFactory
, which defines a list of URLs scanned for applications (refer to Example 6.1, “The /home/me/myapps Directory Defined as Custom Deploy Directory”).
Example 6.1. The /home/me/myapps Directory Defined as Custom Deploy Directory
<bean name="BootstrapProfileFactory" class="org.jboss.system.server.profileservice.repository. StaticProfileFactory"> ... <property name="applicationURIs"> <list elementClass="java.net.URI"> <value>${jboss.server.home.url}deploy</value> <value>file:///home/me/myapps</value> </list> ...
Important
JBOSS_DIST/jboss-as/server/PROFILE/conf/bootstrap/profile.xml
file, you need to restart the server for the changes to take effect.
VFSCache
MC bean configuration in JBOSS_DIST/jboss-as/server/PROFILE/conf/bootstrap/vfs.xml
(refer to Example 6.2, “The /home/me/myapps Directory Added to VFSCache”).
Example 6.2. The /home/me/myapps Directory Added to VFSCache
<bean name="VFSCache"> ... <property name="permanentRoots"> <map keyClass="java.net.URL" valueClass="org.jboss.virtual.spi.ExceptionHandler"> ... <entry> <key>file:///home/me/myapps</key> <value><inject bean="VfsNamesExceptionHandler"/></value> </entry> </map> </property> ...
Important
VFSCache
bean might result in growing disk space usage by the server.
Chapter 7. Console Pages
- Admin console
- JMX Console
- JBoss Web Console
- Tomcat status (full) (XML)
7.1. Admin Console
7.2. JMX Console
Example 7.1. JMX Console Usage
Procedure 7.1. View the JNDI Service
- Open the JMX Console.
- Find the
service=JNDIView
link and click on it.This particular MBean provides a service to allow you to view the structure of the JNDI namespaces within the server. - Now find the operation called
list
near the bottom of the MBean view page and click theinvoke
button.The operation returns a view of the current names bound into the JNDI tree, which is very useful when you start deploying your own applications and want to know why you can’t resolve a particular EJB name.
7.3. JBoss Web Console
Important
7.4. Tomcat Status
Chapter 8. Datasources
java:/DefaultDS
and its descriptor is the <$JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hsqldb-ds.xml
file.
DefaultDS
JNDI name and hsqldb-ds.xml
configuration is not required for normal platform operation. Delete this datasource before deploying a production instance.
Accessing the Database Manager of the Default Hypersonic Database
- Make sure JBoss Enterprise Application Platform is running.
- Open the JMX console located by default on http://localhost:8080/jmx-console/.
- On the displayed JMX Console page, click the
database=localDB,service=Hypersonic
entry in thejboss
section. - On the
JMX MBean View
page of the Hypersonic MBean, click Invoke in thestartDatabaseManager
row to invoke the GUI interface of the database manager.
Warning
- no transaction isolation
- thread and socket leaks (
connection.close()
does not tidy up resources) - persistence quality (logs commonly become corrupted after a failure, preventing automatic recovery)
- database corruption
- stability under load (database processes cease when dealing with too much data)
- not viable in clustered environments.
8.1. Configuring Datasources
-ds.xml
suffix. The docs/examples/jca
directory contains example files for several databases and it is recommended to adapt one of these files to create your configuration file.
Note
docs/dtd/jboss-ds_1_5.dtd
file. Additional documentation on the files and the JBoss JCA implementation are available in the Administration and Configuration Guide.
local-tx-datasource
element and XA-compliant ones using xa-datasource
. The example file generic-ds.xml
shows how to use both types and also some of the other elements that are available for things like connection pool configuration. Examples of both local and XA configurations are available for Oracle, DB2 and Informix.
firebird-ds.xml
, facets-ds.xml
and sap3-ds.xml
are defined with the connection-factories
root element rather than datasources
. That is because they use an alternative, more generic JCA configuration syntax used with a pre-packaged JCA resource adapter. The syntax is not specific to datasource configuration and is used, for example, in the <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/messaging/jms-ds.xml
file to configure the JMS resource adapter.
8.2. MySQL as the Default Datasource
Connector/J
5.1.8, the official JDBC driver. Both are available at www.mysql.com.
8.2.1. Creating a Database and User
-u
root option to run as the MySQL root user).
jboss
within MySQL for use by JBoss:
mysql> CREATE DATABASE jboss; Query OK, 1 row affected (0.05 sec)
mysql> SHOW DATABASES; +----------+ | Database | +----------+ | jboss | +----------+ 1 rows in set (0.00 sec)
jboss
with 'password' as the password to access the database:
mysql> GRANT ALL PRIVILEGES ON jboss.* TO jboss@localhost IDENTIFIED BY 'password'; Query OK, 0 rows affected (0.06 sec)
mysql> select User,Host,Password from mysql.user; +-------+-----------+------------------+ | User | Host | Password | +-------+-----------+------------------+ | root | localhost | | | root | % | | | | localhost | | | | % | | | jboss | localhost | 5d2e19393cc5ef67 | +-------+-----------+------------------+ 5 rows in set (0.02 sec)
8.2.2. Installing the JDBC Driver and Deploying the Datasource
Procedure 8.1. Red Hat Enterprise Linux 6
- Run the following command to install the connector:
yum install mysql-connector-java
- Run the following command to link the new connector to the JBoss Enterprise Application Platform installation:
ln -s /usr/lib[64]/gcj/mysql-connector-java/mysql-connector-java<version>.jar.so jboss-as/server/common/lib/mysql-connector-java.jar
Procedure 8.2. Other Platforms
- Download the MySQL Connector/J JDBC Connector from http://www.mysql.com
- Deploy the connector:
To make the connector available to all server profiles;
Extract themysql-connector-java-<version>.jar
file to<JBOSS_HOME>/server/common/lib
.To make the connector available to selected profiles only;
Extract the file to thelib
directory in those server profile directories.
mysql-ds.xml
with the following datasource configuration. Note that the database user name and password corresponds to the MySQL user that we created in the previous section:
<?xml version="1.0" encoding="UTF-8"?> <datasources> <local-tx-datasource> <jndi-name>DefaultDS</jndi-name> <connection-url>jdbc:mysql://localhost:3306/jboss</connection-url> <driver-class>com.mysql.jdbc.Driver</driver-class> <user-name>jboss</user-name> <password>password</password> <metadatda> <type-mapping>mySQL</type-mapping> </metadata> <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation> </local-tx-datasource> </datasources>
<JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy
folder, start the server and you will notice messages like these in the logs:
INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=MySqlDS' to JNDI name 'java:MySqlDS'
Note
Appendix A. Revision History
Revision History | ||||
---|---|---|---|---|
Revision 5.2.0-100.400 | 2013-10-30 | Rüdiger Landmann | ||
| ||||
Revision 5.2.0-100 | Wed 23 Jan 2013 | Russell Dickenson | ||
| ||||
Revision 5.1.2-100 | Thu Dec 8 2011 | Jared Morgan | ||
| ||||
Revision 5.1.1-100 | Mon Jul 18 2011 | Jared Morgan | ||
| ||||
Revision 5.1.0-100 | Wed Sep 15 2010 | Laura Bailey | ||
|