Version 36
Created by starksm64 on Jul 22, 2006 12:50 PM. Last modified by starksm64 on Jan 20, 2011 4:35 AM.

    JBoss5 Virtual Deployment Framework

    TODO: update for beta3

    http://www.jboss.com/index.html?module=bb&op=viewtopic&t=112181

     

    Design Overview

    The JBoss5 virtual deployemnt framework takes the aspect oriented design of many of the earlier JBoss containers and applies it to the deployment layer. It is also based on the POJO microntainer rather than JMX as in previous releases. For an overview of the classes as a UML diagram see JBoss5DeploymentFrameworkClasses. The key classes in that diagram are:

    • MainDeployer : this interface defines the contract for the MainDeployer. The MainDeployer handles parsing of deployment archives into Deployment instances and deployment of those instances into the microcontainer. This in is an update of the JMX based MainDeployer from earlier versions to a one based on the Microcontainer, JBoss5VirtualFileSystem, and Virtual Deployment Framework(VDF). Deployers are registered with the MainDeployer as an ordered list of deployers. MainDeployer contains two sets of deployers:

    • StructureDeployers used to analyze the structure of a DeploymentContext when addDeploymentContext(DeploymentContext) is invoked. For each StructureDeployer the determineStructure(DeploymentContext) method is invoked to analyze the deployment. A StructureDeployer returns true to indicate that the deployment was recognized and no further StructureDeployer should analyze the DeploymentContext.

    • Deployers used to translate a DeploymentUnit into a runtime kernel beans when the MainDeployer.process is run. The Deployer methods are:

      • isRelevant() : does the deployer want to process the unit

      • prepareDeploy() : take the new deployment to the ready stage

      • prepareUndeploy() : get ready to undeploy

      • handoff(new, old) : handover control from new to old

      • commitDeploy() : new deployment is now in control

      • commitUndeploy() : old deployment is out of here

      • getRelativeOrder() : specify the relative order of the deployer in a chain

    • DeploymentUnit : a representation of a runtime unit of work a Deployer operates on.

    • DeploymentContext : a representation of structural aspects of deployable content.

    • ManagedObject : a representation of the manageable properties for a deployment.

    • VFS : the api for representing the read-only file system of the deployment.

    • VirtualFile : the api for a file in the deployment.

    • DomainClassLoader/ClassLoadingDomain : A generalization of the legacy JMX based unified class loading model. This is still in progress. The org.jboss.vfs.classloding.VFSClassLoader is the current simple implementation.

     

    MainDeployerImpl

    The org.jboss.deployers.plugins.deployment.MainDeployerImpl implementation of the org.jboss.deployers.spi.deployment.MainDeployer interfaces, includes the following standard method details:

    • DeploymentContext getDeploymentContext(String name) : obtain the DeploymentContext associated with the given name from all of the DeploymentContexts that have been added to the MainDeployer. This includes top level and all child contexts.

    • Collection<DeploymentContext> getTopLevel() : get a list of all of the top level DeploymentContexts added via the addDeploymentContext(DeploymentContext) method.

    • Collection<DeploymentContext> getAll() : get all of the DeploymentContexts, top-level and child associated with the MainDeployer.

    • Collection<DeploymentContext> getErrors() : get the DeploymentContexts that have failed to be structurally analyzed or deployed.

    • Collection<DeploymentContext> getMissingDeployer() : get the DeploymentContexts that are not deployed (isDeployed() == false) and are not root .jar files.

    • void addDeploymentContext(DeploymentContext context) throws DeploymentException : add a top-level deployment context. This runs a structural analysis of the DeploymentContext if its StructureDetermined state is not PREDETERMINED. If the structural analysis succeeds, the DeploymentContext is added for deployment during process.

    • boolean removeDeploymentContext(String name) throws DeploymentException : remove the top-level deployment associated with name.

    • void process() : runs through all DeploymentContexts that have been removed undeploys each top-level DeployemntContext. The undeployment involves invoking performUndeploy(DeploymentUnit) on each DeploymentContext.getDeploymentUnit(). Then for each component DeploymentContext, performUndeploy(DeploymentUnit) on the component DeploymentContext.getDeploymentUnit() is performed. Next, the top-level DeploymentContexts that have been added are deployed by invoking commitDeploy on each deployer. The details of the deployment process are that each deployer is run on top-level context DeploymentUnit by invoking Deployer.commitDeploy(DeploymentUnit), followed by the deployment of each context of the top-level DeploymentContext components (DeploymentContext.getComponents()).

    • void shutdown() : removes all top-level DeploymentContexts, and then invokes process to perform the undeployments.

     

    In addition, the implementation adds the following methods.

    • public synchronized void addDeployer(Deployer deployer) : add a component deployer for non-structurual processing.

    • public synchronized void removeDeployer(Deployer deployer) : removes a component Deployer.

    • public synchronized Set<Deployer> getDeployers() : get the registered component deployers.

    • public synchronized void setDeployers(Set<Deployer> deployers) : set the component deployers.

    • public synchronized void addStructureDeployer(StructureDeployer deployer) : add a structurual deployer.

    • public synchronized void removeStructureDeployer(StructureDeployer deployer) : remove a structurual deployer.

    • public synchronized Set<StructureDeployer> getStructureDeployers() : obtain the registered structural deployers.

    • public synchronized void setStructureDeployers(Set<StructureDeployer> deployers) : set the structural deployers.

     

    Current StructureDeployers JBoss5StructureDeployerClasses

    • org.jboss.deployers.plugins.structure.vfs.AbstractStructureDeployer

      • org.jboss.deployers.plugins.structure.vfs.file.FileStructure

      • org.jboss.deployers.plugins.structure.vfs.jar.JARStructure

      • org.jboss.deployers.plugins.structure.vfs.war.WARStructure

     

    Deployer Helper/Base Classes JBoss5BaseDeployerClasses

    • org.jboss.deployers.plugins.deployer.AbstractDeployer - simply stubs out isRelevant to return true and getRelativeOrder to return Integer.MAX_VALUE.

      • org.jboss.deployers.plugins.deployers.helpers.AbstractSimpleDeployer - essentially collapses the Deployer contract to deploy(DeploymentUnit) and undeploy(DeploymentUnit) by stubbing out:

        • prepareDeploy to do nothing

        • commitDeploy to call deploy

        • prepareUndeploy to call undeploy

        • commitUndeploy to do nothing

        • handoff to do nothing.

        • org.jboss.deployers.plugins.deployers.helpers.AbstractClassLoaderDeployer - implements org.jboss.deployers.spi.classloader.ClassLoaderFactory, and deploy(DeploymentUnit u) as u.createClassLoader(this).

          • org.jboss.deployers.plugins.deployers.helpers.AbstractTopLevelClassLoaderDeployer - Adds a createTopLevelClassLoader(DeploymentContext)/removeTopLevelClassLoader(DeploymentContext) methods and implements createClassLoader to invoke createTopLevelClassLoader if context.isTopLevel() is true, to return context.getTopLevel().getClassLoader() otherwise.

        • org.jboss.deployers.plugins.deployers.helpers.AbstractRealDeployer<T> - adds an attatchment type T known as the deploymentType and a SimpleDeploymentVisitor<T> visitor. The deploy implementation obtains a deploymentType metadata from the deployment unit and then delegates deployment to  visitor.deploy(DeploymentUnit, metadata) for each deploymentType metadata. Undeploy similarly delegates to visitor.undeploy(DeploymentUnit, metadata).

          • org.jboss.deployers.plugins.deployers.helpers.AbstractComponentDeployer<D, C> - in addition to a deployment type D, a component type C is introduced along with a SimpleDeploymentVisitor<C> compVisitor. Deployer.deploy(DeploymentUnit) invokes super.deploy(unit) to process the deployment type metadata, and then obtains unit.getAllMetaData(C) and delegates to compVisitor.deploy(unit, metadata) to process the component metadata. Undeploy similarly invokes super.undeploy(unit) and the delegates to compVisitor.undeploy(unit, metadata). The component visitor is expected to create DeploymentUnit components (DeploymentUnit.addComponent(String)) for the component metadata.

        • org.jboss.deployers.plugins.deployers.helpers.AbstractTypedDeployer<T> - adds an attatchment type T known as the deploymentType and accessor, but no new behavior.

          • org.jboss.deployers.plugins.deployers.helpers.AbstractParsingDeployer<T> - adds a notion of obtaining an instance of the deploymentType by parsing a metadata file. The helper methods added include:

            • protected T getMetaData(DeploymentUnit unit, String key) - returns unit.getAttachment(key, getDeploymentType());

            • protected void createMetaData(DeploymentUnit unit, String name, String suffix) - calls createMetaData(unit, name, suffix, getDeploymentType().getName());

            • protected void createMetaData(DeploymentUnit unit, String name, String suffix, String key) - calls parse(unit, name) if suffix is null, parse(unit, name, suffix) otherwise. The result is added as an attachment to unit.getTransientManagedObjects() under key with expected type T.

            • protected T parse(DeploymentUnit unit, String name) - locates VirtualFile unit.getMetaDataFile(name), and if found, calls T result = parse(unit, file); init(unit, result, file);

            • protected T parse(DeploymentUnit unit, String name, String suffix) - locates List<VirtualFile> files = unit.getMetaDataFiles(name, suffix), and if found, calls T result = parse(unit, files.get(0)); init(unit, result, file);

            • protected abstract T parse(DeploymentUnit unit, VirtualFile file) - abstract.

            • protected void init(DeploymentUnit unit, T metaData, VirtualFile file) - empty.

            • org.jboss.deployers.plugins.deployers.helpers.JAXPDeployer<T> - implements parse(DeploymentUnit unit, VirtualFile file) to obtain the org.w3c.dom.Document corresponding to file using JAXP DocumentBuilder and file InputStream. This is parsed into deploymentType T by calling parse(unit, file, document).

              • protected abstract T parse(DeploymentUnit unit, VirtualFile file, Document document) throws Exception - abstract method.

              • org.jboss.deployers.plugins.deployers.helpers.XSLDeployer<T> - add an xslPath that corresponds to a class loader resource for an xsl document. It also overrides parse(DeploymentUnit unit, VirtualFile file) to transform the jaxp document obtained from JAXPDeployer.doParse, and then parses this into deploymentType T by calling the abstract parse(unit, file, document).

            • org.jboss.deployers.plugins.deployers.helpers.ObjectModelFactoryDeployer<T> - add an abstract JBossXB ObjectModelFactory accessor that is used from within an overriden parse(DeploymentUnit unit, VirtualFile file) to unmarshall the xml document represented by file into an instance of deploymentType T.

            • org.jboss.deployers.plugins.deployers.helpers.SchemaResolverDeployer<T> - uses JBossXB UnmarshallerFactory with a SchemaBindingResolver from within an overriden parse(DeploymentUnit unit, VirtualFile file) to unmarshall the xml document represented by file into an instance of deploymentType T. The xml document must have a valid schema with JBossXB annotations.

          • org.jboss.deployers.plugins.deployers.helpers.AbstractSimpleRealDeployer<T> - adds two abstract methods:

            • public abstract void deploy(DeploymentUnit unit, T deployment);

            • public abstract void undeploy(DeploymentUnit unit, T deployment);

            • overrides deploy(DeploymentUnit unit) to obtain the deploymentType instance using unit.unit.getAttachment(getDeploymentType()), and invokes deploy(DeploymentUnit unit, T deployment).

            • overrides undeploy(DeploymentUnit unit) to obtain the deploymentType instance using unit.unit.getAttachment(getDeploymentType()), and invokes undeploy(DeploymentUnit unit, T deployment).

     

    Current Deployers

    • org.jboss.deployers.plugins.deployers.kernel.BeanDeployer

    • org.jboss.deployers.plugins.deployers.kernel.KernelDeploymentDeployer

    • org.jboss.deployers.plugins.deployers.kernel.BeanMetaDataDeployer

    • ServiceDeployments

      • org.jboss.system.deployers.SARDeployer

      • org.jboss.system.deployers.ServiceClassLoaderDeployer

      • org.jboss.system.deployers.ServiceDeploymentDeployer

      • org.jboss.system.deployers.ServiceDeployer

    • JBoss5WebDeployments

      • org.jboss.deployment.WebAppParsingDeployer

      • org.jboss.deployment.JBossWebAppParsingDeployer

      • org.jboss.web.tomcat.tc6.deployers.TomcatDeployer

    • org.jboss.resource.deployers.RARDeployer

    • org.jboss.resource.deployers.RARParserDeployer

     

    Virtual File System JBoss5VirtualFileSystem

    The virtual file system model of the deployment framework provides a consistent api for accessing logical files in logical file systems referenced by a URI/URL.

    • VFS : the main API for accessing read-only file system of the deployment. A VFS instance represents a virtual file system mount for a given root URI/URL.

    • VirtualFile : the api for a file in the deployment.

     

    MetaData Repository

    • TODO: how deployers share data and aspects obtain metadata at runtime.

    • Discussion

     

    Early design notes

     

    TODO

     

    Source Code

    The source code for the deployers is found in the deployers module of the jbossmc project. See the SVN section of the JBossMicrocontainer page.

     

    See also

     

    Referenced by: