## 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.15 $
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.