JBoss API: Class AbstractWebContainer

org.jboss.web
Class AbstractWebContainer

java.lang.Object
  |
  +--javax.management.NotificationBroadcasterSupport
        |
        +--org.jboss.util.ServiceMBeanSupport
              |
              +--org.jboss.web.AbstractWebContainer
All Implemented Interfaces:
AbstractWebContainerMBean, javax.management.MBeanRegistration, javax.management.NotificationBroadcaster, Service, ServiceMBean

public abstract class AbstractWebContainer
extends ServiceMBeanSupport
implements AbstractWebContainerMBean

A template pattern class for web container integration into JBoss. This class should be subclasses by web container providers wishing to integrate their container into a JBoss server. It provides support for mapping the following web-app.xml/jboss-web.xml elements into the JBoss server JNDI namespace: - env-entry - resource-ref - resource-env-ref - ejb-ref - ejb-local-ref - security-domain Subclasses need to implement the performDeploy() and performUndeploy() methods to perform the container specific steps and return the web application info required by the AbstractWebContainer class. Integration with the JBossSX security framework is based on the establishment of a java:comp/env/security context as described in the linkSecurityDomain comments. 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: // Get the username & 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(); SecurityManager securityMgr = (SecurityManager) 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... } An outline of the steps for authorizing the user is: // Get the username & 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... } The one thing to be aware of is the relationship between the thread context class loader and the JNDI ENC context. Any method that attempts to access the JNDI ENC context must have the ClassLoader in the WebApplication returned from the performDeploy as its thread context ClassLoader or else the lookup for java:comp/env will fail with a name not found exception, or worse, it will receive some other web application ENC context. If your adapting a web container that is trying be compatible with both 1.1 and 1.2 Java VMs this is something you need to pay special attention to. For example, I have seen problems a request interceptor that was handling the authentication/authorization callouts in tomcat3.2.1 not having the same thread context ClassLoader as was used to dispatch the http service request. For a complete example see the JBossSecurityMgrRealm in the contrib/catalina module.

Version:
$Revision: 1.4.4.14 $
Author:
Scott.Stark@jboss.org
See Also:
#performDeploy(WebApplication webApp, String warUrl, WebDescriptorParser webAppParser), performUndeploy(String), parseWebAppDescriptors(ClassLoader, WebMetaData), linkSecurityDomain(String, Context), , , ,

Inner Class Summary
static interface AbstractWebContainer.WebDescriptorParser
           
 
Field Summary
protected  java.util.HashMap deploymentMap
          A mapping of deployed warUrl strings to the WebApplication object
 
Fields inherited from class org.jboss.util.ServiceMBeanSupport
log, server
 
Fields inherited from interface org.jboss.util.ServiceMBean
STARTED, STARTING, states, STOPPED, STOPPING
 
Constructor Summary
AbstractWebContainer()
           
 
Method Summary
protected  void addEnvEntries(java.util.Iterator envEntries, javax.naming.Context envCtx)
           
 void deploy(java.lang.String ctxPath, java.lang.String warUrl)
          A template pattern implementation of the deploy() method.
 java.lang.String[] getCompileClasspath(java.lang.ClassLoader loader)
          A utility method that walks up the ClassLoader chain starting at the given loader and queries each ClassLoader for a 'URL[] getURLs()' method from which a complete classpath of URL strings is built.
 org.w3c.dom.Element getConfig()
          Access any arbitrary config information.
 WebApplication getDeployedApp(java.lang.String warUrl)
          Get the WebApplication object for a deployed war.
 java.util.Iterator getDeployedApplications()
          Returns the applications deployed by the web container subclasses.
 boolean isDeployed(java.lang.String warUrl)
          See if a war is deployed.
protected  void linkEjbLocalRefs(java.util.Iterator ejbRefs, javax.naming.Context envCtx)
           
protected  void linkEjbRefs(java.util.Iterator ejbRefs, javax.naming.Context envCtx)
           
protected  void linkResourceEnvRefs(java.util.Iterator resourceEnvRefs, javax.naming.Context envCtx)
           
protected  void linkResourceRefs(java.util.Iterator resourceRefs, javax.naming.Context envCtx)
           
protected  void linkSecurityDomain(java.lang.String securityDomain, javax.naming.Context envCtx)
          This creates a java:comp/env/security context that contains a securityMgr binding pointing to an AuthenticationManager implementation and a realmMapping binding pointing to a RealmMapping implementation.
protected  WebMetaData parseMetaData(java.lang.String ctxPath, java.lang.String warUrl)
          This method creates a context-root string from either the WEB-INF/jboss-web.xml context-root element is one exists, or the filename portion of the warURL.
protected  void parseWebAppDescriptors(java.lang.ClassLoader loader, WebMetaData metaData)
          This method is invoked from within subclass performDeploy() method implementations when they invoke WebDescriptorParser.parseWebAppDescriptors().
protected abstract  void performDeploy(WebApplication webApp, java.lang.String warUrl, AbstractWebContainer.WebDescriptorParser webAppParser)
          This method is called by the deploy() method template and must be overriden by subclasses to perform the web container specific deployment steps.
protected abstract  void performUndeploy(java.lang.String warUrl)
          Called as part of the undeploy() method template to ask the subclass for perform the web container specific undeployment steps.
 void setConfig(org.w3c.dom.Element config)
          This method is invoked to import an arbitrary XML configuration tree.
 void undeploy(java.lang.String warUrl)
          A template pattern implementation of the undeploy() method.
 
Methods inherited from class org.jboss.util.ServiceMBeanSupport
destroy, destroyService, getName, getObjectName, getServer, getState, getStateString, init, initService, nextSequenceNumber, postDeregister, postRegister, preDeregister, preRegister, start, startService, stop, stopService
 
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, getNotificationInfo, removeNotificationListener, sendNotification
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.jboss.util.ServiceMBean
getName, getState, getStateString
 
Methods inherited from interface org.jboss.util.Service
destroy, init, start, stop
 

Field Detail

deploymentMap

protected java.util.HashMap deploymentMap
A mapping of deployed warUrl strings to the WebApplication object
Constructor Detail

AbstractWebContainer

public AbstractWebContainer()
Method Detail

deploy

public void deploy(java.lang.String ctxPath,
                   java.lang.String warUrl)
            throws DeploymentException
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: ClassLoader appClassLoader = thread.getContextClassLoader(); URLClassLoader warLoader = URLClassLoader.newInstance(empty, appClassLoader); thread.setContextClassLoader(warLoader); WebMetaData metaData = parseMetaData(ctxPath, warUrl); WebDescriptorParser webAppParser = ...; WebApplication warInfo = new WebApplication(metaData); performDeploy(warInfo, warUrl, webAppParser); ClassLoader loader = warInfo.getClassLoader(); deploymentMap.put(warUrl, warInfo); thread.setContextClassLoader(appClassLoader); The subclass performDeploy() implementation needs to invoke webAppParser.parseWebAppDescriptors(loader, metaData) to have the JNDI java:comp/env namespace setup before any web app component can access this namespace.
Specified by:
deploy in interface AbstractWebContainerMBean
Parameters:
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.
warUrl, - The string for the URL of the web application war.

performDeploy

protected abstract void performDeploy(WebApplication webApp,
                                      java.lang.String warUrl,
                                      AbstractWebContainer.WebDescriptorParser webAppParser)
                               throws java.lang.Exception
This method is called by the deploy() method template and must be overriden by subclasses to perform the web container specific deployment steps.
Parameters:
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.
warUrl, - The string for the URL of the web application war.
webAppParser, - The callback interface the web container should use to setup the web app JNDI environment for use by the web app components. This needs to be invoked after the web app class loader is known, but before and web app components attempt to access the java:comp/env JNDI namespace.
Returns:
WebApplication, the web application information required by the AbstractWebContainer class to track the war deployment status.

undeploy

public void undeploy(java.lang.String warUrl)
              throws DeploymentException
A template pattern implementation of the undeploy() method. This method calls the performUndeploy() method to perform the container specific undeployment steps and unregisters the the warUrl from the deployment map.
Specified by:
undeploy in interface AbstractWebContainerMBean

performUndeploy

protected abstract void performUndeploy(java.lang.String warUrl)
                                 throws java.lang.Exception
Called as part of the undeploy() method template to ask the subclass for perform the web container specific undeployment steps.

isDeployed

public boolean isDeployed(java.lang.String warUrl)
See if a war is deployed.
Specified by:
isDeployed in interface AbstractWebContainerMBean

getDeployedApp

public WebApplication getDeployedApp(java.lang.String warUrl)
Get the WebApplication object for a deployed war.
Parameters:
warUrl, - the war url string as originally passed to deploy().
Returns:
The WebApplication created during the deploy step if the warUrl is valid, null if no such deployment exists.

getDeployedApplications

public java.util.Iterator getDeployedApplications()
Returns the applications deployed by the web container subclasses.
Specified by:
getDeployedApplications in interface AbstractWebContainerMBean
Returns:
An Iterator of WebApplication objects for the deployed wars.

getConfig

public org.w3c.dom.Element getConfig()
Access any arbitrary config information. This method always returns null and so must be overriden by subclasses to provide information set via setConfig.
Specified by:
getConfig in interface AbstractWebContainerMBean

setConfig

public void setConfig(org.w3c.dom.Element config)
This method is invoked to import an arbitrary XML configuration tree. Subclasses should override this method if they support such a configuration capability. This implementation does nothing.
Specified by:
setConfig in interface AbstractWebContainerMBean

parseWebAppDescriptors

protected void parseWebAppDescriptors(java.lang.ClassLoader loader,
                                      WebMetaData metaData)
                               throws java.lang.Exception
This method is invoked from within subclass performDeploy() method implementations when they invoke WebDescriptorParser.parseWebAppDescriptors().
Parameters:
loader, - the ClassLoader for the web application. May not be null.
webApp, - the root element of thw web-app.xml descriptor. May not be null.
jbossWeb, - the root element of thw jboss-web.xml descriptor. May be null to indicate that no jboss-web.xml descriptor exists.

addEnvEntries

protected void addEnvEntries(java.util.Iterator envEntries,
                             javax.naming.Context envCtx)
                      throws java.lang.ClassNotFoundException,
                             javax.naming.NamingException

linkResourceEnvRefs

protected void linkResourceEnvRefs(java.util.Iterator resourceEnvRefs,
                                   javax.naming.Context envCtx)
                            throws javax.naming.NamingException

linkResourceRefs

protected void linkResourceRefs(java.util.Iterator resourceRefs,
                                javax.naming.Context envCtx)
                         throws javax.naming.NamingException

linkEjbRefs

protected void linkEjbRefs(java.util.Iterator ejbRefs,
                           javax.naming.Context envCtx)
                    throws javax.naming.NamingException

linkEjbLocalRefs

protected void linkEjbLocalRefs(java.util.Iterator ejbRefs,
                                javax.naming.Context envCtx)
                         throws javax.naming.NamingException

linkSecurityDomain

protected void linkSecurityDomain(java.lang.String securityDomain,
                                  javax.naming.Context envCtx)
                           throws javax.naming.NamingException
This creates a java:comp/env/security context that contains a securityMgr binding pointing to an AuthenticationManager 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.

getCompileClasspath

public java.lang.String[] getCompileClasspath(java.lang.ClassLoader loader)
A utility method that walks up the ClassLoader chain starting at the given loader and queries each ClassLoader for a 'URL[] getURLs()' method from which a complete classpath of URL strings is built.

parseMetaData

protected WebMetaData parseMetaData(java.lang.String ctxPath,
                                    java.lang.String warUrl)
                             throws java.net.MalformedURLException
This method creates a context-root string from either the WEB-INF/jboss-web.xml context-root element is one exists, or the filename portion of the warURL. It is called if the DeploymentInfo webContext value is null which indicates a standalone war deployment. A war name of ROOT.war is handled as a special case of a war that should be installed as the default web context.


Copyright 2000 The JBoss Organization. All Rights Reserved.