Instructions for experimenting with the "Single Installation Patching" feature currently being developed.

These instructions assume basic git knowledge and knowledge of how to work with the AS 7 code base. See "Hacking on JBoss AS7" for basic background.

Getting and Building the Source

The patching feature is currently on a topic branch being maintained by Emanuel Muckenhuber. Until that branch is merged into master:

1) If you haven't already, clone the AS repo

$ git clone git://github.com/jbossas/jboss-as.git

2) Add Emanuel's github repo as a remote

$ cd jboss-as
$ git remote add -f emanuel git://github.com/emuckenhuber/jboss-as.git

3) Checkout a new branch "patches-master" to track Emanuel's branch

$ git checkout -t emanuel/patches-master

4) Build the AS

$ ./build.sh

add the -DskipTests option to skip running tests if you want the build to go a bit faster.

Generating Patches

TBD.

Applying Patches

Only an AS release that includes the patching feature can be patched using the patching tool. So, that means you can only experiment with applying patches to an AS distribution you built following the instructions in the "Getting and Building the Source" section above. That limits things a bit as far as what patches you can try to apply; for example you couldn't generate a patch that represents the difference between 7.1.2.Final and 7.1.3.Final and then apply it to 7.1.2.Final.

To apply a patch, you need:

1. A patch file, prepared as described in the "Generating Patches" section.
2. An unzipped AS distribution that represents the "applies-to" distribution. This can be the exact same "applies-to" distribution you used when creating the patch, or, if you want to experiment with how the patch tool deals with the (typical) situation where the user has in some way modified a standard AS version, you can make some sort of modification.

We use the standard AS CLI tool to provide the user interface for the patch application tool. To see how to apply the patch, cd into the root of the installation being patched, launch the CLI and get the help for the "patch" command:

$ bin/jboss-cli.sh -c
[standalone@localhost:9999 /] patch --help
SYNOPSIS

    patch
      <action> <action_arguments>*
      [--override-all]
      [--override-modules]
      [--override=path(,path)*]
      [--preserve=path(,path)*]
      [--host=<host>]

          where <action> can be

  apply           - apply a patch
  info            - information about the installed patches

  rollback        - rollback a patch that has been applied

          and <action_arguments> depends on the <action>

ACTION: apply

   Apply a patch


   ....

This document won't include any more details on actually executing the patch command. Part of the goal of experimenting with it is to see if the --help output is adequate for users to understand what to do.

The patch command only stages the patch (i.e. modifies the filesystem in a way that should not impact the running target process.) To actually have the patch take effect in the runtime, the target process needs to be restarted:

[standalone@localhost:9999 /] :shutdown(restart=true)
{"outcome" => "success"}

Note that simply reloading the target process (using the :reload operation) is insufficient.

TODO add options to the patch command to automatically restart the process if staging is successful.

The patch info

The patch info shows all currently active patches. In case there is no cumulative patch active it will return "base".

[standalone@localhost:9999 /] patch info
{
    "outcome" : "success",
    "result" : {
        "addon" : null,
        "cumulative-patch-id" : "base",
        "patches" : [],
        "release-patch-id" : "base",
        "version" : "8.0.0.Alpha2-SNAPSHOT",
        "layer" : {"base" : null}
    }
}

Conflict resolution

Conflict dection is run for both applying and rolling back patches. In case conflicts are detected and the patch operation will fail and return all found conflicts as part of the failure-description. Since modules are not directly touched there is only a single swtich to ignore those (--override-modules).

Following Progress

The patching feature is still under active development, so if you want update your build and see what's new:

1) cd into the git repo you cloned in step 1) of "Getting and Building the Source" above.

2) Pull down the latest

$ git fetch emanuel

3) Make sure you have a clean repo

$ git status

4) Rebase your branch onto the latest

$ git checkout patches-master

$ git rebase emanuel/patches-master

5) Build again