User: gropi
Date: 01/09/19 11:38:23
Modified: src/xdocs basicconfiguration.xml
Log:
Revised version by Fernando Garcia-Loygorri.
Revision Changes Path
1.2 +703 -307 manual/src/xdocs/basicconfiguration.xml
Index: basicconfiguration.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/xdocs/basicconfiguration.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- basicconfiguration.xml 2001/08/29 09:19:36 1.1
+++ basicconfiguration.xml 2001/09/19 18:38:22 1.2
@@ -1,321 +1,717 @@
<?xml version = "1.0" encoding = "UTF-8"?>
+
+<!-- $Id: basicconfiguration.xml,v 1.2 2001/09/19 18:38:22 gropi Exp $ -->
+
<chapter id = "configuration">
- <title>Configuration</title>
- <para>Authors:</para>
+
+ <title>Configuration</title>
+
+ <para>Authors:</para>
+
+ <para>
+
+ <author>
+ <firstname>Scott</firstname>
+ <surname>Stark</surname>
+ </author>
+
+ <email>[EMAIL PROTECTED]</email>
+
+ </para>
+
+ <para>
+
+ <author>
+ <firstname>Vladimir</firstname>
+ <surname>Blagojevic</surname>
+ </author>
+
+ <email>[EMAIL PROTECTED]</email>
+
+ </para>
+
+ <section>
+
+ <title>Introduction</title>
+
<para>
- <author>
- <firstname>Scott</firstname>
- <surname>Stark</surname>
- </author>
- <email>[EMAIL PROTECTED]</email>
+ JBoss ships preconfigured, so there's nothing you need to do to get
+ it up and running. However, you will likely need to make minor
+ configuration changes to support your specific applications and
+ environment.
</para>
+
<para>
- <author>
- <firstname>Vladimir</firstname>
- <surname>Blagojevic</surname>
- </author>
- <email>[EMAIL PROTECTED]</email>
+ The following section gives you an overview of the directory
+ structure of a standard JBoss installation. The next section
+ briefly describes all of the various configuration files present
+ in the <filename>conf</filename> directory.
</para>
- <section>
- <title>Introduction</title>
- <para> JBoss ships preconfigured, so there's nothing you need to do
to get it up
- and running. However, you will likely need to make minor configuration
- changes to support your specific applications. This section gives an
- overview of the configuration files and directories. The Advanced
- Configuration section gives detailed instructions for
- specific configuration changes you may require.</para>
- </section>
-
-
- <section id = "directory-structure">
- <title>Directory structure</title>
- <para>All directories referred to in the next section are
- relative to <![CDATA[<jboss-home> i.e top directory of the
- JBoss installation. As shown in ]]><xref linkend =
"directories.jpg"/>
- directories are the following:
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>bin</para>
- <para>All the binaries included with JBoss
distribution are located in this
- directory. Using the Batch (Windows) or Shell (UNIX)
- scripts here, you can start the server. You can also run
the EJX
- deployment descriptor editor by double-clicking on it
- (if your platform supports that) or issuing the command: java
-jar ejx.jar </para>
- </listitem>
- <listitem>
- <para id = "lib-and-libext-dir">lib and
lib/ext</para>
- <para>The two directories contain java
libraries in jar and zip format that
- JBoss uses. There is a split between
- those libraries which had to be in the system
classpath (.ie jars in lib
- directory) vs the other ones in lib/ext
- directory that are made available to the JBoss server
MLet based
- classloader.</para>
- <para>
- If there is a need to add some java libraries to
JBoss, for example jdbc
- driver jars, these should be dropped in lib/ext
- directory and will be picked up by JBoss
automatically.</para>
- </listitem>
- <listitem>
- <para>db</para>
- <para>Directory containing hypersonic and
instantdb databases related files
- (configuration files, indexing tables etc ) as well
- as JBossMQ - JMS provider message queue files.</para>
- </listitem>
- <listitem>
- <para>deploy</para>
- <para>This is JBoss's deployment directory.
Just drop your jars here and
- they will be deployed automatically.</para>
- </listitem>
- <listitem>
- <para>log</para>
- <para>JBoss log files are located in this
directory. File logging is turned on by default.</para>
- </listitem>
- <listitem>
- <para>conf</para>
- <para>JBoss configuration set(s) are located
here. By default there is only one
- configuration set - "default". Adding more than one
configuration set is permitted. If you run
- JBoss bundled with a web container (Tomcat or Jetty),
a special configuration set is used
- ("tomcat" or "jetty").
- See <xref linkend = "configuration-files"/>
- for more details. </para>
- </listitem>
- <listitem>
- <para>client</para>
- <para>Libraries required for clients are in
the client directory. A
- typical client requires jboss-client.jar,
- jbosssx-client.jar, jaas.jar, jnp-client.jar, ejb.jar,
and
- jta-spec1_0_1.jar. If you client is not running JDK
1.3, it
- will require jndi.jar as well. If you are going to
be using
- JBossMQ JMS provider you will also need
jbossmq-client.jar.
- </para>
- </listitem>
- </itemizedlist>
- <figure id = "directories.jpg">
- <title>Distribution directory layout</title>
-
- <mediaobject>
- <imageobject>
-
- <imagedata fileref =
"images/directories.png"/>
-
- </imageobject>
-
- </mediaobject>
-
- </figure>
-
- </para>
-
- </section>
-
-
- <section id = "configuration-files">
- <title>Configuration files</title>
- <para>Default Jboss configuration set is located in the conf
directory.
- JBoss allows possibility of more than one configuration set which are
easily created
- and maintained. All you have to do is to copy all the files from the
default
- configuration and place under a new directory in conf. For example,
"myjboss"
- configuration (directory) would contain the same files as default
- configuration but with possibly altered certain setting. When invoking
JBoss through
- platform-dependent scripts just pass configuration name as a paramater.
For example
-
- <command>run.bat myjboss
- </command>
-
- </para>
- <para>There are a number of configuration files for JBoss. The
contents
- of each are give here:
- </para>
-
+
+ <para>
+ Read the rest of the document to obtain more detailed instructions
+ on how to make the specific configuration changes you may require.
+ </para>
+
+ </section>
+
+ <section id = "directory-structure">
+
+ <title>Directory structure</title>
+
+ <para>
+ A standard JBoss installation includes the following directories
+ immediately below the top directory <![CDATA[<jboss-home>]]>, as
+ shown in <xref linkend = "directories.jpg"/>:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+
+ <para><filename>bin</filename></para>
+
+ <para>
+ It contains all the executable files (both scripts and JARs)
+ included in the JBoss distribution to
+ </para>
+
<itemizedlist>
- <listitem>
- <para>jboss.properties</para>
- <para>This is a standard Java Properties format file
that is loaded into the System properties on startup of the JBoss server. System
properties that are not required to be available prior to invocation of the JBoss
server main method can be specified here.</para>
- </listitem>
-
- <listitem>
-
- <para id = "jboss.conf-file">jboss.conf</para>
- <para> Configuration file jboss.conf typically
contains only those core service MBeans that are
- necessary to achieve the initial "bootstrap" of JBoss . These services
- include the classpath extension inclusion mechanism shown in
- <xref linkend = "jboss.conf-excerpt"/> , logging ,configuration service,
service control, etc.</para>
-
- <figure id = "jboss.conf-excerpt">
- <title>Excerpt from jboss.conf</title>
-
- <programlisting><![CDATA[
+
+ <listitem>
+
+ <para>
+ start the server with a Batch (MS-Windows) or Shell
+ (Unix) script.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para>
+ run the EJX deployment descriptor editor by
+ double-clicking on it (if your platform supports
+ this) or issuing the command
+ <command>java -jar ejx.jar</command>
+
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>run the EJB Verifier in Ant.</para>
+ </listitem>
+
+ <listitem>
+ <para>monitor EJB caching.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ </listitem>
+
+ <listitem>
+
+ <para id = "lib-and-libext-dir">
+ <filename>lib</filename> and <filename>lib/ext</filename>
+ </para>
+
+ <para>
+ These two directories contain java libraries in JAR format
+ that JBoss uses. The <filename>lib</filename> directory
+ contains JARs that need to be in the system class path; the
+ JARs in <filename>lib/ext</filename> are made available to
+ the JBoss server MLet-based classloader.
+ </para>
+
+ <para>
+ If there is a need to add some java libraries to JBoss, like
+ JDBC driver JARs, for example, these should be dropped in
+ the <filename>lib/ext</filename> directory to be picked up
+ by JBoss automatically.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>db</filename></para>
+
+ <para>
+ Directory containing other directories with files related
+ to the Hypersonic and Instantdb databases (configuration,
+ indexing, tables, etc.) as well as queue files belonging to
+ JBossMQ, the JMS provider.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>deploy</filename></para>
+
+ <para>
+ This is the deployment directory. Just drop your JAR and EAR
+ files here and they will be deployed automatically.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>log</filename></para>
+
+ <para>
+ The JBoss log files are located in this directory. File
+ logging is turned on by default.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>conf</filename></para>
+
+ <para>
+ The JBoss configuration set(s) are located here. By default
+ there is only one configuration set, located in subdirectory
+ <filename>default</filename>. Adding more than one
+ configuration set is permitted. The bundled installation of
+ JBoss with a web container (either Tomcat or Jetty) creates
+ an additional configuration set (<filename>tomcat</filename>
+ or <filename>jetty</filename>). See
+ <xref linkend = "configuration-files"/> for more details.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>client</filename></para>
+
+ <para>
+ This is the directory where libraries required for clients
+ are placed. A typical client requires
+ <filename>jboss-client.jar</filename>,
+ <filename>jbosssx-client.jar</filename>,
+ <filename>jaas.jar</filename>,
+ <filename>jnp-client.jar</filename>,
+ <filename>ejb.jar</filename> and
+ <filename>jta-spec1_0_1.jar</filename>. If your client is
+ not running JDK 1.3, it will require
+ <filename>jndi.jar</filename> as well. If you are going to
+ be using the JBossMQ JMS provider, you will also need
+ <filename>jbossmq-client.jar</filename>.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>docs</filename></para>
+
+ <para>
+ It contains the JBoss API documentation, Javadoc-style, and
+ other documentation in HTML format.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>external</filename></para>
+
+ <para>
+ It contains the libraries
+ <filename>jboss-util.jar</filename> and
+ <filename>metadata.jar</filename>.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>src</filename></para>
+
+ <para>
+ Under this directory you will find the full tree of Java
+ classes, in source form, that make up JBoss.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>tmp</filename></para>
+
+ <para>
+ This is a work directory used by the AutoDeployer to store
+ files temporarily.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ <figure id = "directories.jpg">
+
+ <title>Distribution directory layout</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref = "images/directories.png"/>
+ </imageobject>
+ </mediaobject>
+
+ </figure>
+
+ </section>
+
+ <section id = "configuration-files">
+
+ <title>Configuration files</title>
+
+ <para>
+ The default JBoss configuration set is located in the
+ <filename>conf/default</filename> directory.
+ </para>
+
+ <para>
+ JBoss allows the administrator to maintain more than one
+ configuration set. All one has to do is to copy all the files from
+ the default configuration into a new subdirectory of
+ <filename>conf</filename>.
+ </para>
+
+ <para>
+ For example, you can create a new configuration
+ <emphasis>"myjboss"</emphasis> by creating under the
+ <filename>conf</filename> directory a subdirectory called
+ <filename>myjboss</filename> and copying all the files from
+ subdirectory <filename>conf/default</filename> into
+ <filename>conf/myjboss</filename>. After possibly altering certain
+ settings in the newly created files, you can run JBoss with the new
+ configuration by invoking the platform-dependent scripts and just
+ passing the configuration name as a parameter, like this:
+ </para>
+
+ <para><command>run.bat myjboss</command></para>
+
+ <para>
+ There are several configuration files for JBoss. A description of
+ each is given below:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+
+ <para><filename>jboss.properties</filename></para>
+
+ <para>
+ This is a file in the standard Java Properties format that
+ is loaded into the System properties on startup of the JBoss
+ server. System properties that are not required to be
+ available prior to the invocation of the JBoss server main
+ method can be specified here.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para id = "jboss.conf-file">
+ <filename>jboss.conf</filename>
+ </para>
+
+ <para>
+ The configuration file <filename>jboss.conf</filename>
+ contains typically only those core service MBeans that are
+ necessary to achieve the initial bootstrap of JBoss, like
+ the class path extension inclusion mechanism shown in
+ <xref linkend = "jboss.conf-excerpt"/>, logging,
+ configuration service, service control, etc.
+ </para>
+
+ <figure id = "jboss.conf-excerpt">
+
+ <title>Excerpt from <filename>jboss.conf</filename></title>
+
+ <programlisting>
+ <![CDATA[
<MLET CODE="org.jboss.util.ClassPathExtension" ARCHIVE="jboss.jar"
CODEBASE="../../lib/ext/">
<ARG TYPE="java.lang.String" VALUE="../../log/">
-</MLET>
- ]]></programlisting>
-
- </figure>
-
-
-
- <para>
- This file is loaded by an instance of the javax.management.loading.MLet
class and uses standard MLET syntax for JMX MBeans (refer to <ulink url =
"http://java.sun.com/products/JavaManagement";>JMX specification</ulink> for more
details). Any standard JMX MBean could be placed in the jboss.conf file as long as it
does not depend on JBoss service MBeans like naming. MBeans that do depend on JBoss
service MBeans need to be configured in the jboss.jcml file so that startup
dependencies can be controlled.</para>
-
-
- <para> Usually you would never have to change this
file.</para>
- </listitem>
-
-
-
- <listitem>
-
-
- <para id = "jboss.jcml-file">jboss.jcml</para>
- <para> This file lists all JMX MBeans
(services) that are going to be included
- in running instance of JBoss. Notice that contrary to the MLET syntax,
- this file contains well-formed XML.</para>
- <para>
- The need for deviation from MLET syntax is justified since MLET
- doesn't allow named parameters, but rather only TYPE-VALUE pairs. Having only
- TYPE-VALUE pairs easily leads to mismatching MBean parameters problems.
</para>
-
- <para> jboss.jcml syntax allows named
parameters to be used in MBean instantiation
- directives and is as such mush easier to use. For example,
- <xref linkend = "jboss.jcml-example-entry"/> shows MBean
- element for creating and including MailService in JBoss.</para>
-
- <para>
- <figure id = "jboss.jcml-example-entry">
- <title>Excerpt from jboss.jcml</title>
-
- <programlisting><![CDATA[
+</MLET>
+ ]]>
+ </programlisting>
+
+ </figure>
+
+ <para>
+ This file is loaded by an instance of the
+ <literal>javax.management.loading.MLet</literal> class and
+ it is written following the standard MLet syntax for JMX
+ MBeans (refer to the
+
+ <ulink url = "http://java.sun.com/products/JavaManagement";>
+ JMX specification
+ </ulink>
+
+ for more details). Any standard JMX MBean can be placed in
+ the <filename>jboss.conf</filename> file as long as it does
+ not depend on JBoss service MBeans like naming. MBeans that
+ depend on JBoss service MBeans need to be configured in the
+ <filename>jboss.jcml</filename> file so that startup
+ dependencies can be managed.
+ </para>
+
+ <para>Usually, you would never have to change this file.</para>
+
+ </listitem>
+
+ <listitem>
+
+ <para id = "jboss.jcml-file">
+ <filename>jboss.jcml</filename>
+ </para>
+
+ <para>
+ This file lists all the JMX service MBeans that need to be
+ included in the running instance of JBoss. Notice that,
+ contrary to the MLet syntax, this file contains well-formed
+ XML.
+ </para>
+
+ <para>
+ The need for deviation from MLet syntax is justified by the
+ fact that MLet doesn't allow named parameters, only
+ TYPE-VALUE pairs. Having only TYPE-VALUE pairs easily leads
+ to problems due to MBean parameter mismatches.
+ </para>
+
+ <para>
+ The syntax of <filename>jboss.jcml</filename> allows the use
+ of named parameters in MBean instantiation directives and it
+ is a lot easier to use. For example,
+ <xref linkend = "jboss.jcml-example-entry"/> shows an MBean
+ element used to create and include MailService in JBoss.
+ </para>
+
+ <para>
+
+ <figure id = "jboss.jcml-example-entry">
+
+ <title>
+ Excerpt from <filename>jboss.jcml</filename>
+ </title>
+
+ <programlisting>
+ <![CDATA[
<mbean code="org.jboss.mail.MailService" name="DefaultDomain:service=Mail">
- <attribute name="JNDIName">Mail</attribute>
- <attribute name="ConfigurationFile">mail.properties</attribute>
- <attribute name="User">user_id</attribute>
- <attribute name="Password">password</attribute>
-</mbean>
- ]]></programlisting>
- </figure>
-
- </para>
-
- <para> In a nutshell:
- <itemizedlist>
-
- <listitem>
- <para>code attribute of the
mbean element specifies which class to
- load and instantiate</para>
- </listitem>
- <listitem>
- <para>name attribute of the
mbean element specifies unique name of
- the MBean under certain JMX domain</para>
- </listitem>
- <listitem>
- <para>attribute child elements
of the mbean element specify
- according attributes of the instatiated MBean. Values of the attributes
- can be any Java primitives and String object.</para>
- </listitem>
- </itemizedlist>
-
-
- </para>
- <para>The jboss.jcml file is loaded by the
org.jboss.configuration.ConfigurationService MBean. This service acts much like the
standard JMX MLet class in that it loads and configures MBeans. The dependencies
between MBeans are managed by the org.jboss.util.ServiceControl MBean. The
ServiceControl MBean listens for REGISTRATION_NOTIFICATION and
UNREGISTRATION_NOTIFICATION JMX events to determine which MBeans are available. The
order of registration determines the order of initialization and startup. The
ServiceControl expects that MBeans which require depdendency management to conform to
the org.jboss.util.Service interface. This interface allows for the ordered
initialization, starting, stopping and destorying of MBeans. The ordering is based on
the order in which MBeans are specified in the jboss.jcml file. See <xref linkend =
"howto.mbeans"/> for the details of creating an MBean with depedencies on other
MBeans.</para>
+<attribute name="JNDIName">Mail</attribute>
+<attribute name="ConfigurationFile">mail.properties</attribute>
+<attribute name="User">user_id</attribute>
+<attribute name="Password">password</attribute>
+</mbean>
+ ]]>
+ </programlisting>
+
+ </figure>
+
+ </para>
+
+ <para>
+
+ In a nutshell:
+
+ <itemizedlist>
+
+ <listitem>
+
+ <para>
+ The <literal>code</literal> attribute of the
+ MBean element specifies which class to load and
+ instantiate.
+ </para>
+
</listitem>
+
<listitem>
- <para id =
"jboss.dependencies-file">jboss.dependencies</para>
- <para> For the reason of simplicity and ease of
configuration JBoss's DependancyManager
- was deprecated in 2.1 release, so this file is no longer used.</para>
-
- <para> Now all MBeans listed in jboss.jcml have
"vertical" dependency on each other.
- For example, JNDI provider is required for DataSource wrappers since
- DataSource wrapper has to store reference to itself in JNDI, thus JNDI
provider
- MBean has to be listed before DataSource wrapper. See <xref linkend =
"howto.mbeans"/> for the details of the depedency mechanism.</para>
-
- </listitem>
-
-
-
- <listitem>
- <para id = "jboss-auto-file">jboss-auto.jcml</para>
- <para> JBoss has a very powerful feature of being
able to record runtime snapshot
- of all of it's running MBeans including their attributes and then later
reproduce
- that snapshot in another JBoss instance. </para>
-
- <para>
- When such snapshot is taken it is recorded in xml format in jboss-auto.jcml
file.
- </para>
-
-
- <para> Consider the following scenario:</para>
- <para>
- Administrator takes a running JBoss instance, adds a few MBeans, modifies
attributes
- of other few MBeans , saves configuration and finally gracefully shuts
- JBoss.</para>
- <para> Next time when JBoss is started all
dynamically added Mbeans from previous
- run are recreated and their attributes set. Jboss also resets any other
modified
- attributes no matter if MBean was added dynamically(runtime) or
statically (through
- jboss.jcml).</para>
-
- <para> Dependency between jboss.jcml and
jboss-auto.jcml</para>
- <para>
- If you are using both jboss.jcml and jboss-auto.jcml capabilities you have
- to note the following. If there is a need to remove any of the MBeans listed
in
- jboss.jcml you also have to remove it from jboss-auto.jcml (if such is
listed in jboss-auto.jcml ) to
- achieve the desired effect.</para>
-
- <para> You also have an option not to use the
advanced feature of jboss runtime snapshots,
- in which case you can safely delete jboss-auto.jcml file without affecting
- JBoss.
- In this case you won't have an option of recording any changes to MBeans
made in runtime.
- </para>
- </listitem>
- <listitem>
- <para id =
"mail.properties-file">mail.properties</para>
- <para> JBoss , according to EJB spec provides mail
resource access utilizing standard JavaMail APIs.
- This file specifies provider properties, i.e where to find smtp server, pop
server, as well
- as other mail related configuration.</para>
-
- <para>
- Note that you are allowed to have multiple set of configurations by having
multiple mail.properties
- files. All you have to do is to specify additional MailService mbeans with
different "ConfigurationFile"
- attributes in your jboss.jcml file. See <xref linkend = "howto.javamail"/>
for additional details.</para>
- </listitem>
-
- <listitem>
- <para id = "jndi.properties-file">
jnp.properties and jndi.properties</para>
- <para>
- These two files are JNDI related. The first one contains properties of the
JBoss's
- JNDI provider implementation - JNP while jndi.properties specifies
properties for JNDI
- clients. </para>
-
- <para>
- JNDI clients can specify properties listed in jndi.properties and drop
- jndi.properties file anywhere in their classpath. This way you don't have to
- specify these properties in the actual code which leads to
- greater code portability. Note that you have to change
java.naming.provider.url=localhost
- property-value pair if you are using clients that reside on the machine
- other than the JBoss server itself.</para>
- </listitem>
- <listitem>
- <para id =
"standardjaws.xml-file">standardjaws.xml</para>
-
- <para>
- Represents a default configuration file for JBossCMP engine. It contains
jndi name of a default
- DataSource , per database Object -jdbc- sql mappings , default CMP entity
beans settings etc. See <xref linkend = "jaws"/> for additional details.</para>
- </listitem>
- <listitem>
- <para>auth.conf</para>
- <para> This file is a JAAS login module
configuraiton file as supported by the default javax.security.auth.login.Configuration
implementation. It contains sample server side authentication configurations that are
applicable when using JAAS based security. See <xref linkend = "JBossSX"/> for
addition details on the JBoss security framework.</para>
- </listitem>
-
- <listitem>
- <para> server.policy</para>
- <para> The default Java2 security policy for
the JBoss server. Currently, this is set to allow all permissions and is unused as the
JBoss server does not run with a security manager by default. See <xref linkend =
"JBossSX"/> for a description of the JBoss security framework.</para>
+
+ <para>
+ The <literal>name</literal> attribute of the
+ MBean element specifies the unique name of the
+ MBean under the specified JMX domain.
+ </para>
+
</listitem>
- <listitem>
- <para>standardjboss.xml</para>
- <para> This file provides the default
container configurations. Use of this file is an advanced topic covered by <xref
linkend = "adv.config"/>
- </para>
+
+ <listitem>
+
+ <para>
+ The attribute child elements of the MBean
+ element specify the corresponding attributes of
+ the instantiated MBean. The values of the
+ attributes can be any Java primitives or String
+ objects.
+ </para>
+
</listitem>
- </itemizedlist>
- </section>
-</chapter>
\ No newline at end of file
+
+ </itemizedlist>
+
+ </para>
+
+ <para>
+
+ The <filename>jboss.jcml</filename> file is loaded by the
+
+ <literal>
+ org.jboss.configuration.ConfigurationService
+ </literal>
+
+ MBean. This service acts much like the standard JMX MLet
+ class in that it loads and configures MBeans. The
+ dependencies among MBeans are managed by the
+ <literal>org.jboss.util.ServiceControl</literal> MBean. The
+ ServiceControl MBean listens for
+ <literal>REGISTRATION_NOTIFICATION</literal> and
+ <literal>UNREGISTRATION_NOTIFICATION</literal> JMX events to
+ determine which MBeans are available. The order of
+ registration determines the order of initialization and
+ startup. The ServiceControl expects MBeans requiring
+ dependency management to conform to the
+ <literal>org.jboss.util.Service</literal> interface. This
+ interface allows for the orderly initialization, startup,
+ stop and destroying of MBeans. The sequence is based on the
+ order in which MBeans are specified in the
+ <filename>jboss.jcml</filename> file. See
+ <xref linkend = "howto.mbeans"/> for the details on how to
+ create an MBean that has dependencies on other MBeans.
+
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para id = "jboss.dependencies-file">
+ <filename>jboss.dependencies</filename>
+ </para>
+
+ <para>
+ For reasons of simplicity and ease of configuration, the
+ DependencyManager of JBoss was deprecated in the 2.1
+ release, so this file is no longer used.
+ </para>
+
+ <para>
+ Now all the MBeans listed in <filename>jboss.jcml</filename>
+ have <emphasis>vertical</emphasis> dependency on each other.
+ For example, a JNDI provider is required for DataSource
+ wrappers because a DataSource wrapper needs to store a
+ reference to itself in JNDI; therefore, a JNDI provider
+ MBean has to be listed before the DataSource wrapper. See
+ <xref linkend = "howto.mbeans"/> for the details of the
+ dependency mechanism.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para id = "jboss-auto-file">
+ <filename>jboss-auto.jcml</filename>
+ </para>
+
+ <para>
+ JBoss has the very powerful feature of being able to record
+ a runtime snapshot of all of its running MBeans, including
+ their attributes, and later reproduce that snapshot in
+ another JBoss instance.
+ </para>
+
+ <para>
+ When such a snapshot is taken, it is recorded in XML format
+ in the <filename>jboss-auto.jcml</filename> file.
+ </para>
+
+ <para>Consider the following scenario:</para>
+
+ <para>
+ The administrator takes a running JBoss instance, adds a few
+ MBeans, modifies attributes of other MBeans, saves the
+ configuration and finally gracefully shuts down JBoss.
+ </para>
+
+ <para>
+ The next time that JBoss is started, all the dynamically
+ added Mbeans from the previous run are recreated and their
+ attributes set. JBoss also resets any other modified
+ attributes, regardless whether an MBean was added
+ dynamically (at runtime) or statically (through
+ <filename>jboss.jcml</filename>).
+ </para>
+
+ <para>
+ You also have the option not taking runtime snapshots; to
+ do so, simply delete the
+ <filename>jboss-auto.jcml</filename> file before starting
+ JBoss, in which case JBoss will not record any of the
+ MBeans changes at runtime.
+ </para>
+
+ <para>
+
+ <emphasis>
+ Dependency between <filename>jboss.jcml</filename> and
+ <filename>jboss-auto.jcml</filename>
+ </emphasis>
+
+ </para>
+
+ <para>
+
+ If while using the runtime snapshot feature there is a need
+ to remove an MBean listed in
+ <filename>jboss.jcml</filename>, you also have to remove it
+ from <filename>jboss-auto.jcml</filename>, if it appears
+ there, to achieve the desired effect. Do not remove the
+ entire <filename>jboss-auto.jcml</filename> file unless you
+ want to stop taking runtime snapshots; to remove
+ <emphasis>all</emphasis> the MBeans, create a functionally
+ empty <filename>jboss-auto.jcml</filename> file, like this:
+
+ <programlisting>
+ <![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+
+<server>
+</server>
+ ]]>
+ </programlisting>
+
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para id = "mail.properties-file">
+ <filename>mail.properties</filename>
+ </para>
+
+ <para>
+ Following the EJB specification, JBoss provides access to a
+ mail resource through the standard JavaMail APIs. This file
+ specifies properties of the mail provider, such as where to
+ find the SMTP and POP servers, as well as other mail-related
+ configuration settings.
+ </para>
+
+ <para>
+ Note that you are allowed to specify multiple sets of
+ configurations by creating multiple
+ <filename>mail.properties</filename> files. All you have to
+ do is to specify additional MailService MBeans with
+ different <literal>ConfigurationFile</literal> attributes in
+ the <filename>jboss.jcml</filename> file. See
+ <xref linkend = "howto.javamail"/> for additional details.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para id = "jndi.properties-file">
+ <filename>jnp.properties</filename> and
+ <filename>jndi.properties</filename>
+ </para>
+
+ <para>
+ These two files are JNDI related. The first one contains
+ properties of JNP, the JNDI provider implementation in
+ JBoss, while the second specifies properties for JNDI
+ clients.
+ </para>
+
+ <para>
+ JNDI clients can read properties listed in a
+ <filename>jndi.properties</filename> file as long as it
+ appears somewhere in their class path. This improves the
+ portability of the client program because it is not written
+ to operate in a particular configuration. Note that you have
+ to change the
+ <literal>java.naming.provider.url=localhost</literal>
+ property-value pair if you are using clients that reside on
+ a machine other than the JBoss server host itself.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para id = "standardjaws.xml-file">
+ <filename>standardjaws.xml</filename>
+ </para>
+
+ <para>
+ Represents a default configuration file for the JBoss CMP
+ engine. It contains the JNDI name of a default DataSource,
+ per database JDBC Object-SQL mappings, default CMP entity
+ beans settings, etc. See <xref linkend = "jaws"/> for
+ additional details.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>auth.conf</filename></para>
+
+ <para>
+ This file is a JAAS login module configuration file,
+ supported by the default
+ <literal>javax.security.auth.login.Configuration</literal>
+ implementation. It contains sample server side
+ authentication configurations that are applicable when using
+ JAAS based security. See <xref linkend = "JBossSX"/> for
+ additional details on the JBoss security
+ framework.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>server.policy</filename></para>
+
+ <para>
+ The default Java2 security policy for the JBoss server.
+ Currently, this is set to an all-open configuration, but
+ it is unused because the JBoss server does not run with a
+ security manager by default. See
+ <xref linkend = "JBossSX"/> for a description of the JBoss
+ security framework.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para><filename>standardjboss.xml</filename></para>
+
+ <para>
+ This file provides the default container configuration. The
+ use of this file is an advanced topic covered by
+ <xref linkend = "adv.config"/>.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+</chapter>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/jboss-development
