User: starksm
Date: 01/07/07 12:25:16
Modified: src/docs advconfig.xml jbossdocs.xml
Added: src/docs webconfig.xml
Log:
Add a section to the advanced config chapter about the use of the
jboss-web.xml deployment descriptor.
Revision Changes Path
1.13 +4 -0 manual/src/docs/advconfig.xml
Index: advconfig.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/advconfig.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- advconfig.xml 2001/06/23 08:37:50 1.12
+++ advconfig.xml 2001/07/07 19:25:16 1.13
@@ -684,4 +684,8 @@
</itemizedlist>
</section>
</section>
+
+<!-- Include a section of the jboss-web.xml web deployment descriptor -->
+&webconfig.xml;
+
</chapter>
1.19 +1 -0 manual/src/docs/jbossdocs.xml
Index: jbossdocs.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/jbossdocs.xml,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- jbossdocs.xml 2001/06/04 20:21:57 1.18
+++ jbossdocs.xml 2001/07/07 19:25:16 1.19
@@ -33,6 +33,7 @@
<!ENTITY howtonetbeansdebug.xml SYSTEM "howtonetbeansdebug.xml">
<!ENTITY howtovisualagedebug.xml SYSTEM "howtovisualagedebug.xml">
<!ENTITY howto_webcontainer.xml SYSTEM "howto_webcontainer.xml">
+ <!ENTITY webconfig.xml SYSTEM "webconfig.xml">
]>
<book>
<bookinfo>
1.1 manual/src/docs/webconfig.xml
Index: webconfig.xml
===================================================================
<?xml version = "1.0" encoding = "UTF-8"?>
<section id = "web-container.config">
<title>Web container configuration : use of jboss-web.xml</title>
<para>Author:<author>
<firstname>Scott</firstname>
<surname>Stark</surname>
</author>
<email>[EMAIL PROTECTED]</email>
</para>
<section>
<title>What is jboss-web.xml?</title>
<para>To deploy your web application, you have to specify (nearly)
everything about its
setup using the standard web.xml descriptor. This file is bundled in the war
archive in the WEB-INF directory.
The content and syntax of this file in specified in the servlet2.2
specification.</para>
<para>An important point is that the specification does not allow you
to add
vendor-specific configuration
in this file. While the web.xml is sufficient for most applications, there
may be cases where
you want to add JBoss-specific information in your deployment descriptor. This
can be done by providing another file named jboss-web.xml in the WEB-INF
directory.</para>
<para>The following sections will cover most common uses of the
jboss-web.xml file.
If you want to know all the details, you can get the DTD for jboss-web.dtd in the
<ulink url="http://www.jboss.org/doco_files/";>file section</ulink> of the manual. A
graphical
view of the DTD is given in <xref linkend = "jboss-web.dtd"/>
</para>
<figure id = "jboss-web.dtd">
<title>The jboss-web.xml DTD</title>
<mediaobject>
<imageobject>
<imagedata fileref =
"images/jboss_web_dtd.jpg"/>
</imageobject>
</mediaobject>
</figure>
</section>
<section>
<title>Declaring Resource References</title>
<para>Resource references are links to resource factory bindings. They
allow a servlet/JSP page developer to define a name relative to the ENC that
does not depend on the deployment time binding of the resource. The jboss-web.xml
descriptor maps from the developer defined resource name to the actual JNDI
binding of the resource factory as it was configured in the deployment environment.
An example web.xml descriptor that references JDBC, Mail and JMS resources and the
corresponding jboss-web.xml descriptor is:
</para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd";>
<web-app>
<servlet>
<servlet-name>AServlet</servlet-name>
<servlet-class>AServlet</servlet-class>
</servlet>
<!-- JDBC DataSources (java:comp/env/jdbc) -->
<resource-ref>
<description>The default DS</description>
<res-ref-name>jdbc/DefaultDS</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
<!-- JavaMail Connection Factories (java:comp/env/mail) -->
<resource-ref>
<description>Default Mail</description>
<res-ref-name>mail/DefaultMail</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
</resource-ref>
<!-- JMS Connection Factories (java:comp/env/jms) -->
<resource-ref>
<description>Default QueueFactory</description>
<res-ref-name>jms/QueFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
<res-auth>Container</res-auth>
</resource-ref>
</web-app>
]]></programlisting>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
<resource-ref>
<res-ref-name>jdbc/DefaultDS</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<jndi-name>java:/DefaultDS</jndi-name>
</resource-ref>
<resource-ref>
<res-ref-name>mail/DefaultMail</res-ref-name>
<res-type>javax.mail.Session</res-type>
<jndi-name>java:/Mail</jndi-name>
</resource-ref>
<resource-ref>
<res-ref-name>jms/QueFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
<jndi-name>QueueConnectionFactory</jndi-name>
</resource-ref>
</jboss-web>
]]></programlisting>
</section>
<section>
<title>Declaring an EJB reference</title>
<para>An EJB reference (see servlet2.2 specification, 9.9, p45) is
when a servlet
wants to call methods on a bean B. This call will look like this:.</para>
<programlisting>
public class AServlet extends HttpServlet
{
...
protected void service(HttpServletRequest req, HttpServletResponse res)
throws ServletException, IOException
{
...
InitialContext ctx = new InitialContext();
BHome home = (BHome) ctx.lookup("java:comp/env/ejb/myBean");
B bean = home.create(pk);
...
}
}</programlisting>
<para>To be allowed this call, the servlet must declare a reference to
the ejb its using in the its deployment descriptor. This is done by an
<![CDATA[<ejb-ref>
tag in the web.xml file. Two types of references exist; internal and external.
]]></para>
<section>
<title>Internal EJB reference</title>
<para>An EJB reference is called internal when the servlet is
in the same
application unit as the bean B. This means that the servlet and ejb is
physically packaged in the same ear. In this case, you must provide the
<![CDATA[<ejb-link> tag, and its value must
match the ]]><![CDATA[<ejb-name> of bean B. You don't have to provide anything
in the jboss-web.xml file. Your web.xml
file will look like this:
]]></para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<web-app>
<servlet>
<servlet-name>AServlet</servlet-name>
<servlet-class>AServlet</servlet-class>
</servlet>
<ejb-ref>
<ejb-ref-name>ejb/BHome</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>BHome</home>
<remote>B</remote>
<ejb-link>Bean B</ejb-link>
</ejb-ref>
</web-app>
]]></programlisting>
<para>Note that this only works if the ejb is using the default
binding
of its BHome interface which means the ejb-jar in which B is deployed does not use
a jboss.xml descriptor to change the default binding. If B does change the default
location of its JNDI binding, then the bean needs to be treated as an external bean
as described in the next section.
</para>
</section>
<section>
<title>External EJB reference</title>
<para>An EJB reference is called external when the bean B
comes from another
application unit, which may even be deployed on another server. It also refers to
non-standard bindings of EJBs into JNDI in the same application unit.
In this case, you cannot rely on the
standard <![CDATA[<ejb-link> ]]>tag in web.xml since there the beans are
not covered in the same file. Instead, you must
provide the full JNDI name of the bean B in jboss-web.xml. A full
name is of the form:
</para>
<para>protocol://host:1234/name/in/other/server
Note that the <![CDATA[<ejb-ref-name> ]]>tags in the 2 xml files must match.
</para>
<para>Here is an example web.xml and jboss-web.xml with
external EJB
references:</para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<web-app>
<servlet>
<servlet-name>AServlet</servlet-name>
<servlet-class>AServlet</servlet-class>
</servlet>
<ejb-ref>
<ejb-ref-name>ejb/BHome</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>BHome</home>
<remote>B</remote>
</ejb-ref>
<ejb-ref>
<ejb-ref-name>ejb/RemoteBHome</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>BHome</home>
<remote>B</remote>
</ejb-ref>
</web-app>
]]></programlisting>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
<!-- A reference to an EJB in the same server with a custom JNDI binding -->
<ejb-ref>
<ejb-ref-name>ejb/BHome</ejb-ref-name>
<jndi-name>someapp/ejbs/beanB</jndi-name>
</ejb-ref>
<!-- A reference to an EJB in an external server -->
<ejb-ref>
<ejb-ref-name>ejb/RemoteBHome</ejb-ref-name>
<jndi-name>jnp://otherserver/application/beanB</jndi-name>
</ejb-ref>
</jboss-web>
]]></programlisting>
<para>IMPORTANT NOTE: this will tell jboss where to look for
bean B. You also have
to tell jboss what bean B is: in case of an external ejb-reference to another
application be
sure to include bean B's home and remote interface in servlet war. </para>
</section>
</section>
<section>
<title>Declaring the Security Domain</title>
<para>The final element in the jboss-web.xml descriptor is the
security-domain.
This defines the JNDI name of the security manager implementation that should be
used to perform authentication and authorization of web clients. This element only
works with web containers that have been integrated into the JBoss server using
the org.jboss.web.AbstractWebContainer integration point and are using its security
interface. Currently both the contributed Tomcat and Jetty web containers support
this.
An example jboss-web with a security-domain element is:
</para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
<!-- Use the JaasSecurityMgr other security domain for authentication
and authorization of secured web content.
-->
<security-domain>java:/jaas/other</security-domain>
</jboss-web>
]]></programlisting>
<para>
See the JAAS HowTo and the JBossSX chapter for details on setting up
security.
</para>
</section>
</section>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
