Brian Stansberry [https://community.jboss.org/people/brian.stansberry] modified the document: "Extending AS 7" To view the document, visit: https://community.jboss.org/docs/DOC-25627 -------------------------------------------------------------- Like all releases of JBoss Application Server, AS 7 provides a relatively small core set of functionality, along with APIs that can be used to extend this core functionality in order to provide the services external clients need. As in previous releases, the AS ships with extensions to its core functionality that provide capabilities like Java EE support. And, as in previous releases, it is possible for custom extensions to the AS to be integrated, either by organizations (e.g. other open source projects or ISVs) who want to distribute a modified version of the AS to others, or by organizations who directly run the AS. The means by which AS & can be extended is significantly different than it was in previous releases. This article is intended to discuss those differences, and to elicit thoughts on best practices. The article is focused on educating organizations who want to distribute a modified version of the AS, but hopefully the information herein will be useful to organizations who directly run the AS. h2. How Extending AS 7 is Different from Previous Versions The fundamental difference between AS 7 and previous versions is that in AS 7 +everything isn't a deployment+. In AS 6 and early, the core AS provided some basic functionality including a couple of basic services called +deployers+. Deployers could recognize the existence of content on the filesystem, a.k.a. "deployments", process that content and install new services into AS's core service container. Most of the services provided by the AS itself were themselves +deployments+.  The web container, the EJB container, the transaction manager, the naming service, etc, all were installed as +deployments.+ Even additional deployers, beyond the basic ones that were part of the core AS, were themselves deployments. Those additional deployers could do things like parsing a web.xml, making it possible to deploy additional kinds of deployments (e.g. a war file), but they themselves were deployments. And, of course, end user applications like Java EE ears and war, were also deployments. So, in this architecture, end user applications were logically equivalent to the web container, the EJB container -- all extended the core capabilities of the AS and all were +deployments.+ In AS 7, the basic design philosophy is that deployments are end user applications. Adding new fundamental capabilities to the application server is done by installing +extensions+. However, since deployments and extensions in the end add new capabilities to the core server, what are the differences between the two? Why would someone wishing to extend the AS choose one or the other? h2. Extensions and Subsystems An +extension+ is an implementation of the org.jboss.as.controller.Extension interface, packaged in a directory structure accessible to the JBoss Modules modular classloading layer used by the AS. An extension can register one or more +subsystems+ with the core AS. A subsystem is a set of functionality; e.g. the web container is a subsystem. See the https://docs.jboss.org/author/display/AS71/Extending+JBoss+AS+7 Extending JBoss AS 7 documentation for more details on how to write an extension. Extensions are packaged as JBoss Modules modules. Typically you would place your extension's module(s) in the $JBOSS_HOME/modules directory. (You can place your modules in another location if before running standalone.sh or domain.sh you set the $JBOSS_MODULE_PATH environment variable to a value that includes both your location and the location of the $JBOSS_HOME/modules directory.) Why would you use an extension to add functionality to the AS? * You want to make aspects of your new functionality manageable by your end users, e.g. via the AS's CLI tool and via the standalone.xml and domain.xml configuration files. The Extension interface is the means by which the core AS is told about the management API exposed by your new functionality, and about the xml parsing and marshalling logic used to read and write its configuration. One of the main new features in AS 7 is a consistent management solution; if you want your functionality to properly integrate with these management features you need to use an extension. * You want to be able to process deployments. AS 7 has "deployment unit processors" which are conceptually similar to "deployers" in early releases. They are invoked during deployment and undeployment of deployments and can perform processing work on the deployment. Only extensions can register deployment unit processors with the core AS. * Patching. We will introduce a patching tool in later releases of AS 7. Extensions will have significant advantages over deployments when it comes to patching. See the section on this below. * You wish to differentiate your extension from end user applications. End users will typically use deployments to extend the AS's functionality (e.g. deploying a WAR deployment adds new functionality). Using deployments instead of extensions for things other than end-user applications mixes end user stuff with non-end-user stuff, somewhat muddying the waters. In particular:* The actual physical binaries may be mixed. If instead of using an extension you put a deployment in standalone/deployments, now your binaries will be mixed with end user binaries. To avoid this, you either need to configure a separate deployment scanner to deploy your content from a different location, or require some sort of installation process (e.g. execution of a CLI script) to get your deployment installed. The "configure a separate deployment scanner" approach is only available for standalone servers, since deployment scanners are not supported in a managed domain. * Your deployments will be mixed with the end user deployments in the management resource tree. For example if an admin starts the CLI and executes ls deployment they will see your deployments in the same list as their own. Same thing with the admin console. h2. Deployments A deployment in AS7 is binary content that is installed into the server via a mangement client (or a deployment scanner, which is really just an automated management client.) The management client either uploads the content to the server or informs it of its filesystem location, and then asks the server to install that content. The server does so by taking the deployment's bits and making them available to the various deployment unit processors (DUPs) that have been added by the server's extensions. The DUPs examine the contents of the deployments and take the necessary actions to start the necessary services for the deployment and integrate them with the needed container services. Why would you use a deployment to add functionality to the AS? * You're an end user installing an EE application. * You're an end user adding new mbean services or JBoss MSC services and you are not concerned with making your new functionality manageable via the AS's CLI tool or via the standalone.xml and domain.xml configuration files. You could use an extension for your new functionality instead of a deployment, but many users will find using a deployment easier, particularly if they are porting something from a previous AS release. * You're not an end user, but your new functionality requires complex integration with the AS's EE containers. The deployment unit processors that handle deployments take care of that integration for you. h2. A Mixed Approach It is possible to mix extensions and deployments. For example, if you wanted to expose aspects of your new functionality's configuration to admins via the AS's management APIs, but also need to accept end user requests via the servlet container, you could package a war inside your extension's module and then have the "add" operation handler for your subsystem deploy the war. See https://github.com/bstansberry/wildfly/commit/197f7b64b48f4a28a7d44be4820... https://github.com/bstansberry/wildfly/commit/197f7b64b48f4a28a7d44be4820... for a prototype extension with a subsystem that deploys an ear when it is added to the server. This approach still suffers from the drawback that your extension's war will appear alongside end-user applications in the management resource tree. Note that most of the content of that prototype extension commit is boilerplate.  The key technical bits that do the deployment/undeployment are in two classes: * https://github.com/bstansberry/wildfly/commit/197f7b64b48f4a28a7d44be4820... The subsystem add operation handler * https://github.com/bstansberry/wildfly/commit/197f7b64b48f4a28a7d44be4820... The subsystem remove operation handler The rest of the commit relates to creating an extension module as well as making that module part of the standard JBoss AS build. The latter part is not relevant to extensions whose source code isn't part of the AS source tree. h2. Implications for Patching In a future AS 7 release we will be introducing a patching feature, with a tool that stage a patch in an AS 7 installation and then (optionally) restart the standalone server of Host Controller + servers running on that installation. The feature will include the ability to roll back patches. This feature has implications for the decision about whether to add functionality to the AS via extensions or deployments. Extensions are packaged as JBoss Modules modules, typically located in the $JBOSS_HOME/modules directory. It will be quite simple for the patching tool support staging/installation/rollback of modules. When the AS launches, it is provided with a "modules path", a list of filesystem locations under which modules can be found. This "modules path" is conceptually very similar to an OS $PATH environment variable. It's an ordered list of locations; when the AS needs to locate a module for the first time it iterates through that list of locations checking each for the desired module; once found the search stops. This behavior makes it simple to apply staging/install/rollback behavior to modules by storing the patch's modules in a new directory location specific to the patch and then manipulating the "modules path" used by the AS. The upshot of all this is functionality added to the AS via an extension will be easily patchable. The patching tool will also be able to patch arbitrary non-module files located in the AS installation (e.g. the bin/standalone.sh script). It will do this by storing a copy of the original file in a private working area, and then replacing the file with the patched one. Rollback of the patch means restoring the original file by copying it back from the private working area. This works fine, +unless the server is actively using the original file+. If the server is actively using the original file, the patch cannot be +staged+. As soon as the patch tool lays down the new file, it will be visible to the running server. An example of the kind of problem this can cause is if your added functionality was packaged as a deployment located in standalone/deployments. If you create a patch file with a new version of your deployment and ask your users to use the patching tool to install it, the tool will put a new version of the file in standalone/deployments -- and the deployment scanner will see that new version and tell the patching tool to deploy it. -------------------------------------------------------------- Comment by going to Community [https://community.jboss.org/docs/DOC-25627] Create a new document in JBoss AS 7 Development at Community [https://community.jboss.org/choose-container!input.jspa?contentType=102&a...]