User: starksm
Date: 01/04/01 20:25:40
Modified: src/docs advconfig.xml basicconfiguration.xml
howtojavamail.xml jbossdocs.xml jbosssx.xml
Added: src/docs howtombeans.xml
Log:
Updated basic config files documentation and added some id tags for
references. Started an updated howto on custom MBeans.
Revision Changes Path
1.3 +1 -1 manual/src/docs/advconfig.xml
Index: advconfig.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/advconfig.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- advconfig.xml 2001/03/27 16:24:42 1.2
+++ advconfig.xml 2001/04/02 03:25:40 1.3
@@ -1,4 +1,4 @@
-<chapter>
+<chapter id="adv.config">
<title>Advanced container configuration</title>
<para>Author:
<author><firstname>Sebastien</firstname><surname>Alborini</surname></author>
1.6 +217 -227 manual/src/docs/basicconfiguration.xml
Index: basicconfiguration.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/basicconfiguration.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- basicconfiguration.xml 2001/04/01 02:14:14 1.5
+++ basicconfiguration.xml 2001/04/02 03:25:40 1.6
@@ -1,125 +1,116 @@
-
-<chapter id="configuration">
+<?xml version = "1.0" encoding = "UTF-8"?>
+<chapter id = "configuration">
<title>Configuration</title>
-
<para>Authors:</para>
<para>
- <author>
+ <author>
<firstname>Scott</firstname>
<surname>Stark</surname>
</author>
<email>[EMAIL PROTECTED]</email>
</para>
<para>
- <author>
+ <author>
<firstname>Vladimir</firstname>
<surname>Blagojevic</surname>
</author>
<email>[EMAIL PROTECTED]</email>
</para>
-
- <section>
- <title>Introduction</title>
- <para>
- JBoss ships preconfigured, so there's nothing you need to do to get it up
+ <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>
+ 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"/>
+
+ <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
+ </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
+ </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>
+ 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
+ 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
+ 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.
- 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
+ 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>
+ </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.
+
+ <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"
@@ -127,203 +118,202 @@
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>run.bat myjboss
</command>
- </para>
-
- <para>There are a number of configuration files for JBoss. The contents
+
+ </para>
+ <para>There are a number of configuration files for JBoss. The
contents
of each are give here:
</para>
- <itemizedlist>
- <listitem>
- <para id="jboss.conf-file">jboss.conf</para>
-
- <para>
- Configuration file jboss.conf contains only those core services that are
- necessary to achieve initial "bootstrap" of JBoss . Among these services
- are for example , classpath extension inclusion mechanism shown in
- <xref linkend="jboss.conf-excerpt"/> , logging ,configuration service etc.
</para>
-
- <figure id="jboss.conf-excerpt">
- <title>Excerpt from jboss.conf</title>
- <programlisting><![CDATA[
+
+ <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,
etc.</para>
+
+ <figure id = "jboss.conf-excerpt">
+ <title>Excerpt from jboss.conf</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>
-
+</MLET>
+ ]]></programlisting>
+
+ </figure>
- <para>
- The syntax used is a standard MLET syntax for JMX MBeans (refer to
- <ulink url="http://java.sun.com/products/JavaManagement">JMX
specification</ulink> for more details)</para>
-
- <para>
- Usually you would never have to change this file. </para>
- </listitem>
+
+ <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>
- <listitem>
+
+ <para> Usually you would never have to change this
file.</para>
+ </listitem>
- <para id="jboss.jcml-file">jboss.jcml</para>
+
+
+ <listitem>
- <para>
- This file lists all JMX MBeans (services) that are going to be included
+
+ <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>
+ 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>
+ TYPE-VALUE pairs easily leads to mismatching MBean parameters problems.
</para>
- <para>
- jboss.jcml syntax allows named parameters to be used in MBean instantiation
+ <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>
+ <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[
+ <para>
+ <figure id = "jboss.jcml-example-entry">
+ <title>Excerpt from jboss.jcml</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:
+</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
+
+ <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>
+ can be any Java primitives and String object.</para>
+ </listitem>
+ </itemizedlist>
- </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. </para>
- <para>
- Now all MBeans listed in jboss.jcml have "vertical" dependency on each
other.
+
+ </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, but it also manages
dependencies between MBeans as long as the MBean interface conforms to a certain
pattern described by the org.jboss.util.ServiceMBean 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>
+ </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.</para>
- </listitem>
+ 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
+
+ <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>
+ 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>
+ <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
+ 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>
+ jboss.jcml).</para>
- <para>
- Dependency between jboss.jcml and jboss-auto.jcml</para>
-
- <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>
+ achieve the desired effect.</para>
- <para>
- You also have an option not to use the advanced feature of jboss runtime
snapshots,
+ <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.
+ </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>
+ as other mail related configuration.</para>
- <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.</para>
-
- </listitem>
-
- <listitem>
- <para id="jndi.properties-file">
- jnp.properties and jndi.properties</para>
-
- <para>
+ 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>
+ clients. </para>
- <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. For more
- details see </para>
- </listitem>
+ other than the JBoss server itself.</para>
+ </listitem>
+ <listitem>
+ <para id =
"standardjaws.xml-file">standardjaws.xml</para>
- <listitem>
- <para>
- server.policy</para>
- <para>
- The default security policy for the JBoss server. Currently, this is set to
allow all permissions.</para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
-
+ <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>
+ </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>
+ </itemizedlist>
+ </section>
+</chapter>
\ No newline at end of file
1.3 +1 -1 manual/src/docs/howtojavamail.xml
Index: howtojavamail.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/howtojavamail.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- howtojavamail.xml 2001/03/21 08:30:20 1.2
+++ howtojavamail.xml 2001/04/02 03:25:40 1.3
@@ -1,5 +1,5 @@
<?xml version = "1.0" encoding = "UTF-8"?>
-<section>
+<section id="howto.javamail">
<title>Using JavaMail in JBoss</title>
<para>
<author>
1.11 +2 -0 manual/src/docs/jbossdocs.xml
Index: jbossdocs.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/jbossdocs.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- jbossdocs.xml 2001/03/30 02:30:43 1.10
+++ jbossdocs.xml 2001/04/02 03:25:40 1.11
@@ -25,6 +25,7 @@
<!ENTITY howtojpda.xml SYSTEM "howtojpda.xml">
<!ENTITY howtomssql.xml SYSTEM "howtomssql.xml">
<!ENTITY howtojetty.xml SYSTEM "howtojetty.xml">
+ <!ENTITY howtombeans.xml SYSTEM "howtombeans.xml">
<!ENTITY jbosssx.xml SYSTEM "jbosssx.xml">
]>
<book>
@@ -52,6 +53,7 @@
&howtojetty.xml;
&howtomssql.xml;
&howtormhexamples.xml;
+&howtombeans.xml;
&howtojmx.xml;
&howtotimer.xml;
&howtoj2eedeployer.xml;
1.5 +2 -2 manual/src/docs/jbosssx.xml
Index: jbosssx.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/jbosssx.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- jbosssx.xml 2001/03/31 00:19:50 1.4
+++ jbosssx.xml 2001/04/02 03:25:40 1.5
@@ -1,8 +1,8 @@
<?xml version = "1.0" encoding = "UTF-8"?>
-<!-- Version: $Revision: 1.4 $ -->
+<!-- Version: $Revision: 1.5 $ -->
<?xml-stylesheet href =
'file:///D:/usr/local/src/cvsroot/jBoss/manual/src/docs/jboss.xsl' type = 'text/xsl'?>
-<chapter>
+<chapter id="JBossSX">
<title>JBossSX Security Extension Framework</title>
<subtitle>Security in JBoss</subtitle>
<para>
1.1 manual/src/docs/howtombeans.xml
Index: howtombeans.xml
===================================================================
<?xml version = "1.0" encoding = "UTF-8"?>
<section id="howto.mbeans">
<title>How to Integrate Custom MBeans</title>
<para>
<author>
<firstname>Scott</firstname>
<surname>Stark</surname>
</author>
<email>[EMAIL PROTECTED]</email>
</para>
<section>
<title>Introduction</title>
<para>If you want to add services to the JBoss server, the best way to
do that is to write your own JMX MBeans. Then they can be configured in jboss.jcml
like the core JBoss MBeans. The best way for your EJBs to access your new services is
to make them accessible via JNDI.</para>
<para>More to come...
</para>
</section>
</section>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
