User: starksm
Date: 01/05/21 15:16:21
Modified: src/docs jbossdocs.xml
Added: src/docs howto_webcontainer.xml
Log:
Initial draft of a servlet webcontainer howto
Revision Changes Path
1.17 +2 -0 manual/src/docs/jbossdocs.xml
Index: jbossdocs.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/jbossdocs.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- jbossdocs.xml 2001/04/27 08:46:30 1.16
+++ jbossdocs.xml 2001/05/21 22:16:21 1.17
@@ -31,6 +31,7 @@
<!ENTITY howtombeans.xml SYSTEM "howtombeans.xml">
<!ENTITY jbosssx.xml SYSTEM "jbosssx.xml">
<!ENTITY howtovisualagedebug.xml SYSTEM "howtovisualagedebug.xml">
+ <!ENTITY howto_webcontainer.xml SYSTEM "howto_webcontainer.xml">
]>
<book>
<bookinfo>
@@ -73,5 +74,6 @@
&howtojaxp.xml;
&howtoverifier.xml;
&howtopetstore.xml;
+&howto_webcontainer.xml;
</chapter>
</book>
1.1 manual/src/docs/howto_webcontainer.xml
Index: howto_webcontainer.xml
===================================================================
<?xml version = "1.0" encoding = "UTF-8"?>
<section id = "howto.webcontainer">
<title>How to Integrate a Web Container into JBoss</title>
<para>Author:<author>
<firstname>Scott</firstname>
<surname>Stark</surname>
</author>
<email>[EMAIL PROTECTED]</email>
</para>
<section>
<title>Introduction</title>
<para>This HowTo describes the steps for integrating a third party web
container into the JBoss application server framework. A web container is a J2EE
server component that enables access to servlets and JSP pages. Example servlet
containers include Tomcat and Jetty. Integrating a servlet container into JBoss
consists of mapping web-app.xml JNDI information into the JBoss JNDI namespace using
an optional jboss-web.xml descriptor as well as delegating authentication and
authorization to the JBoss security layer. These tasks are simplified by the
org.jboss.web.AbstractWebContainer class. The remainder of this HowTo describes howto
integrate a web container using the AbstractWebContainer class.</para>
</section>
<section>
<title>AbstractWebContainer Overview</title>
<para>The org.jboss.web.AbstractWebContainer class is an
implementation of a template pattern for web container integration into JBoss. This
class should be subclassed by web container providers wishing to integrate their
container into a JBoss server. AbstractWebContainer provides support for parsing the
standard J2EE web-app.xml web application deployment descriptor JNDI and security
elements as well as support for parsing the JBoss specific jboss-web.xml descriptor.
The AbstractWebContainer is an abstract class that implements the
AbstractWebContainerMBean JMX mbean interface used by the JBoss deployer when war
files need to be deployed. <xref linkend = "howto.webcontainer.AbstractWebContainer"/>
presents some of the key AbstractWebContainer methods.</para>
<figure id = "howto.webcontainer.AbstractWebContainer">
<title>Key AbstractWebContainer Class Methods</title>
<programlisting><![CDATA[
package org.jboss.web;
...
public abstract class AbstractWebContainer extends ServiceMBeanSupport implements
AbstractWebContainerMBean
{
]]><co id = "howto.webcontainer.deploy"/><![CDATA[
public synchronized void deploy(String ctxPath, String warUrl) throws
DeploymentException
{
WebApplication warInfo = performDeploy(ctxPath, warUrl);
ClassLoader loader = warInfo.getClassLoader();
Element webApp = warInfo.getWebApp();
Element jbossWeb = warInfo.getJbossWeb();
parseWebAppDescriptors(loader, webApp, jbossWeb);
deploymentMap.put(warUrl, warInfo);
}
]]><co id = "howto.webcontainer.performDeploy"/><![CDATA[
protected abstract WebApplication performDeploy(String ctxPath, String warUrl)
throws Exception;
]]><co id = "howto.webcontainer.undeploy"/><![CDATA[
public synchronized void undeploy(String warUrl) throws DeploymentException
{
performUndeploy(warUrl);
// Remove the web application ENC...
deploymentMap.remove(warUrl);
}
]]><co id = "howto.webcontainer.performUndeploy"/><![CDATA[
protected abstract void performUndeploy(String warUrl) throws Exception;
public boolean isDeployed(String warUrl)
{
return deploymentMap.containsKey(warUrl);
}
public WebApplication getDeployedApp(String warUrl)
{
WebApplication appInfo = (WebApplication) deploymentMap.get(warUrl);
return appInfo;
}
]]><co id = "howto.webcontainer.parseWebAppDescriptors"/><![CDATA[
private void parseWebAppDescriptors(ClassLoader loader, Element webApp, Element
jbossWeb) throws Exception
{
WebMetaData metaData = new WebMetaData();
metaData.importXml(webApp);
if( jbossWeb != null )
metaData.importXml(jbossWeb);
...
addEnvEntries(envEntries, envCtx);
Iterator resourceRefs = metaData.getResourceReferences();
linkResourceRefs(resourceRefs, envCtx);
Iterator ejbRefs = metaData.getEjbReferences();
linkEjbRefs(ejbRefs, envCtx);
String securityDomain = metaData.getSecurityDomain();
linkSecurityDomain(securityDomain, envCtx);
}
]]><co id = "howto.webcontainer.addEnvEntries"/><![CDATA[
protected void addEnvEntries(Iterator envEntries, Context envCtx)
throws ClassNotFoundException, NamingException
{
...
}
]]><co id = "howto.webcontainer.linkResourceRefs"/><![CDATA[
protected void linkResourceRefs(Iterator resourceRefs, Context envCtx)
throws NamingException
{
...
}
]]><co id = "howto.webcontainer.linkEjbRefs"/><![CDATA[
protected void linkEjbRefs(Iterator ejbRefs, Context envCtx)
throws NamingException
{
...
}
]]><co id = "howto.webcontainer.linkSecurityDomain"/><![CDATA[
protected void linkSecurityDomain(String securityDomain, Context envCtx)
throws NamingException
{
...
}
}
]]></programlisting>
<programlisting>public class WebApplication
{
/** Class loader of this application */
ClassLoader classLoader = null;
/** name of this application */
String name = "";
/** URL where this application was deployed from */
URL url;
/** The root element of thw web-app.xml descriptor. */
Element webApp;
/** The root element of thw jboss-web.xml descriptor. */
Element jbossWeb;
/** Arbitary data object for storing application specific data */
Object data;
...
// WebApplication property getters/setters...
}</programlisting>
</figure>
<calloutlist>
<callout arearefs = "howto.webcontainer.deploy">
<para>A template pattern implementation of the
deploy() method. This method
calls the performDeploy() method to
perform the container specific deployment steps and registers the
returned WebApplication in the deployment map. The steps performed are:
WebApplication warInfo = performDeploy(ctxPath, warUrl);
ClassLoader loader = warInfo.getClassLoader();
Element webApp = warInfo.getWebApp();
Element jbossWeb = warInfo.getJbossWeb();
parseWebAppDescriptors(loader, webApp, jbossWeb);
deploymentMap.put(warUrl, warInfo);
@param ctxPath, The context-root element value from the J2EE
application/module/web application.xml descriptor. This may be null
if war was is not being deployed as part of an enterprise application.
@param warUrl, The string for the URL of the web application war.</para>
</callout>
<callout arearefs = "howto.webcontainer.performDeploy">
<para>The method is called by the deploy() method and
must be overriden by
subclasses to perform the web container specific deployment steps. A WebApplication
object must
be returned that contains the web application class loader, web-app.xml web-app
document element
and the jboss-web.xml jboss-web document element if a jboss-web.xml existed in the
war.
@param ctxPath, The context-root element value from the J2EE
application/module/web application.xml descriptor. This may be null
if war was is not being deployed as part of an enterprise application.
@param warUrl, The string for the URL of the web application war.
@return WebApplication, the web application information required by the
AbstractWebContainer class to setup the JNDI ENC and track the war
deployment status.</para>
</callout>
<callout arearefs = "howto.webcontainer.undeploy">
<para>A template pattern implementation of the
undeploy() method. This method
calls the subclass performUndeploy() method to perform the container specific
undeployment steps and unregisters the
the warUrl from the deployment map.</para>
</callout>
<callout arearefs = "howto.webcontainer.performUndeploy">
<para>performUndeploy</para>
</callout>
<callout arearefs =
"howto.webcontainer.parseWebAppDescriptors">
<para> This method is called as part of the deploy()
method template to
parse the web-app.xml and jboss-web.xml deployment descriptors from a
war deployment. The method creates the ENC(java:comp/env) env-entry,
resource-ref, and ejb-ref element values. The creation of the env-entry
values does not require a jboss-web.xml descriptor. The creation of the
resource-ref and ejb-ref elements does require a jboss-web.xml descriptor
for the JNDI name of the deployed resources/EJBs.
Because the ENC context is private to the web application, the web
application class loader is used to identify the ENC. The class loader
is used because each war typically requires a unique class loader to
isolate the web application classes/resources. This means that the
ClassLoader passed to this method must be the thread context ClassLoader
seen by the server/jsp pages during init/destroy/service/etc. method
invocations if these methods interace with the JNDI ENC context.
@param loader, the ClassLoader for the web application. May not be null.
@param webApp, the root element of thw web-app.xml descriptor. May not be null.
@param jbossWeb, the root element of thw jboss-web.xml descriptor. May be null
to indicate that no jboss-web.xml descriptor exists.</para>
</callout>
<callout arearefs = "howto.webcontainer.addEnvEntries">
<para>The addEnvEntries creates the java:comp/env web
container
env-entry bindings that were specified in the web-app.xml descriptor.</para>
</callout>
<callout arearefs = "howto.webcontainer.linkResourceRefs">
<para>The linkResourceRefs method maps the
java:comp/env/xxx web container
JNDI ENC resource elements onto the deployed JNDI names using the mappings specified
in the
jboss-web.xml descriptor</para>
</callout>
<callout arearefs = "howto.webcontainer.linkEjbRefs">
<para>The linkEjbRefs method maps the
java:comp/env/ejb web container
JNDI ENC ejb elements onto the deployed JNDI names using the mappings specified in
the
jboss-web.xml descriptor.</para>
</callout>
<callout arearefs = "howto.webcontainer.linkSecurityDomain">
<para>This creates a java:comp/env/security context
that contains a
securityMgr binding pointing to an EJBSecurityMgr implementation
and a realmMapping binding pointing to a RealmMapping implementation.
If the jboss-web.xml descriptor contained a security-domain element
then the bindings are LinkRefs to the jndi name specified by the
security-domain element. If there was no security-domain element then
the bindings are to NullSecurityManager instance which simply allows
all access.</para>
</callout>
</calloutlist>
</section>
<section id = "howto.webcontainer.Subclassing">
<title>Integrating a Web Container by Subclassing
AbstractWebContainer</title>
<para>To integrate your web container into JBoss create a subclass of
AbstractWebContainer and implement
the required performDeploy(String, String) and performUndeploy(String) methods. See
the performDeploy and performUndeploy
method notes in the preceeding section for details of the method
implementations.</para>
</section>
<section id = "howto.webcontainer.Security">
<title>Delegating Web Container Authentication and Authorization to
JBoss</title>
<para>Ideally both web application and ejb authentication and
authorization is handled
by the same security code. To enable this for your web container you must hook into
the JBoss security
layer. This typically requires a request interceptor that maps from the web
container security callouts
to the JBoss security api calls. Integration with the JBossSX security framework is
based on the establishment
of a java:comp/env/security context as described in the linkSecurityDomain(String,
Context) method comments
in the overview section. The security context provides access to the JBossSX
security mgr interface
implementations for use by subclass request interceptors. A outline of the steps for
authenticating a user is:<example>
<title>Authentication Steps</title>
<programlisting> // Get the username and password
from the request context...
String username = f(request);
String password = f(request);
// Get the JBoss security manager from the ENC context
InitialContext iniCtx = new InitialContext();
EJBSecurityManager securityMgr = (EJBSecurityManager)
iniCtx.lookup("java:comp/env/security/securityMgr");
SimplePrincipal principal = new SimplePrincipal(username);
if( securityMgr.isValid(principal, password) )
{
// Indicate the user is allowed access to the web content...
// Propagate the user info to JBoss for any calls into made by the servlet
SecurityAssociation.setPrincipal(principal);
SecurityAssociation.setCredential(password.toCharArray());
}
else
{
// Deny access...
}</programlisting>
</example>An outline of the steps for authorizing a user with
the JBossSX api is:<example>
<title>Authorization Steps</title>
<programlisting> // Get the username and required
roles from the request context...
String username = f(request);
String[] roles = f(request);
// Get the JBoss security manager from the ENC context
InitialContext iniCtx = new InitialContext();
RealmMapping securityMgr = (RealmMapping)
iniCtx.lookup("java:comp/env/security/realmMapping");
SimplePrincipal principal = new SimplePrincipal(username);
Set requiredRoles = new HashSet(Arrays.asList(roles));
if( securityMgr.doesUserHaveRole(principal, requiredRoles) )
{
// Indicate the user has the required roles for the web content...
}
else
{
// Deny access...
}</programlisting>
</example>
</para>
</section>
</section>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
