= Packaging a management plug-in pack update

A management plug-in pack update contains one or more updated management plug-ins for a plug-in pack. They are cumulative meaning that in addition to the updated plug-ins for the existing release of the plug-in pack, all plug-ins that have not been updated since the prior update or GA release of the plug-in pack are included. This allows easy installation of plug-ins by grabbing the latest plug-in pack for a product or product family and installing it. There would be no need to install the prior updates or original GA released plug-in pack.

== Obtain the Brew build package name, version, and release number for the updated plug-in pack and its associated server archive

The bases for packaging a new plug-in pack update is the actual plug-in pack build from Brew which includes the updated plug-in(s). The package information is necessary as you will need to download the server archive for the associated plug-in pack build along with the plug-in pack archive from the build itself.

For example, the Brew build URL https://brewweb.engineering.redhat.com/brew/buildinfo?buildID=514697 represents a build containing a new version of the Fuse Management Plug-in Pack for JBoss ON 3.3. The Brew build ID or _NVL_ is `org.jboss.on-jboss-on-parent-3.3.0.GA-103`.  From this you can see that the _package name_ is `org.jboss.on-jboss-on-parent`; the _package version_ is `3.3.0.GA`; and the _package release_ is `103`. Using this information, we can craft a URL to download the required files directly from Brew.

== Download the updated plug-in pack and its associated server archive from the Brew build

Using the Brew build information you can download the necessary files that are required to package a plug-in pack update. Specifically, you will download the new plug-in pack build along with the server archive from the same build.

Using the same Fuse Management Plug-in Pack build from earlier, we can download the necessary files from the build using the following commands:

.Shell commands to download server and plug-in pack archives from Brew
[source,bash]
----
# Set necessary variables
brewRootUrl='http://download.devel.redhat.com/brewroot'
packageName=org.jboss.on-jboss-on-parent
packageVersion=3.3.0.GA
packageRelease=103
pluginPackName=fuse
# Download server archive
curl -L -o "jon-server-${packageVersion}-${packageRelease}.zip" "${brewRootUrl}/packages/${packageName}/${packageVersion}/${packageRelease}/maven/org/jboss/on/jon-server/${packageVersion}/jon-server-${packageVersion}.zip"
# Download plug-in pack archive
curl -L -o "jon-plugin-pack-${pluginPackName}-${packageVersion}-${packageRelease}.zip" "${brewRootUrl}/packages/${packageName}/${packageVersion}/${packageRelease}/maven/org/jboss/on/jon-plugin-pack-${pluginPackName}/${packageVersion}/jon-plugin-pack-${pluginPackName}-${packageVersion}.zip"
----

== Download the previous management plug-in pack update

Because plug-in pack updates are cumulative, the previous update is required in order to build a new plug-in pack update. If a previous update does not exist -- such as this is the very first update for this release version of JBoss ON -- use the GA plug-in pack from the original GA release.

.Shell commands to download server and plug-in pack archives from Brew
[source,bash]
----
# Set necessary variables
productRootURL='http://download.devel.redhat.com/released/JBossON'
productVersion=3.3
packageVersion=3.3.0.GA
previousUpdateNumber=05
pluginPackName=fuse
# Download previous plug-in pack
curl -L -o "jon-plugin-pack-${pluginPackName}-${packageVersion}$( [ -n "${previousUpdateNumber}" ] && echo -update-${previousUpdateNumber}).zip" "${productRootURL}/${productVersion}/jon-plugin-pack-${pluginPackName}-${packageVersion}$( [ -n "${previousUpdateNumber}" ] && echo -update-${previousUpdateNumber}).zip"
----


== Create a plug-in pack file change set list

To add or replace existing plug-ins from the previous plug-in pack update and to remove old plug-ins, a change set list is needed. The change set list is simply a list of plug-in or license file names that will be added or removed from the new plug-in pack update.

The goal should be to only include plug-ins that have had actual code changes. This is to limit the number of plug-ins that get updated in a customer's JBoss ON system. You should carefully select plug-ins based on what actually changed and what is required in the customer's environment.

Continuing with the Fuse Plug-in Pack Update example from earlier, a change set list will look like the following:

[source,text]
.BZ${updateId}-changeset.txt
----
-servicemix3-plugin-7.5.0.redhat-621070.jar
-servicemix4-plugin-7.5.0.redhat-621070.jar
-fabric-plugin-7.5.0.redhat-621070.jar
-fabric-groups-plugin-7.5.0.redhat-621070.jar
-cxf-plugin-7.5.0.redhat-621070.jar
-camel-plugin-7.5.0.redhat-621070.jar
-activemq-plugin-7.5.0.redhat-621070.jar
-jboss-fuse-plugin-7.5.0.redhat-621070.jar
-fuse-jboss-as-7-plugin-7.5.0.redhat-621070.jar
servicemix3-plugin-7.5.1.redhat-630187.jar
servicemix4-plugin-7.5.1.redhat-630187.jar
fabric-plugin-7.5.1.redhat-630187.jar
fabric-groups-plugin-7.5.1.redhat-630187.jar
cxf-plugin-7.5.1.redhat-630187.jar
camel-plugin-7.5.1.redhat-630187.jar
activemq-plugin-7.5.1.redhat-630187.jar
jboss-fuse-plugin-7.5.1.redhat-630187.jar
fuse-jboss-as-7-plugin-7.5.1.redhat-630187.jar
----

Essentially what the above change set list means is that all the plug-ins that contain `7.5.0.redhat-621070` in their name will be removed from the new plug-in pack and all plug-ins that contain `7.5.1.redhat-630187` in their name will be added from the new plug-in pack build.

The Fuse example is not typical however. In most cases only one or two plug-ins are actually updated. You will need to be very careful to only include plug-ins that are actually updated. Just because the version number is newer does not mean there was actually any code changes in the plug-in. By including plug-ins that have new names or new build times, you will put a huge amount of unnecessary load on the customer's production system when a plug-in scan and update is performed. This is because the change of the file or version information will result in all resource types being removed and re-added to the database and a resource upgrade being performed for every single resource in the system. This is very bad and should be avoided if at all possible.

It is also possible to specify a file to be added to the new plug-in pack update which is from another zip archive. The zip archive can either be located on the local file system or can be downloaded via a web URL. The format of the change set entry is `<path to archive>!/<path to file within archive>`. For example:

[source,text]
.changeset.txt showing file from archive change set entries
----
/tmp/my-other-plugin-pack.zip!/my-awesome.plugin.jar
http://download.example.com/jon-plugins/others.zip!/plugins/my-other-plugin.jar
----

If the file is not found in the archive at the path specified, an attempt is made to locate the path within a directory named `plugins/` at the root level of the archive. If the file is still not found, a final attempt is made to locate the path within a directory named the same as the archive.

For example, the change set entry `archive.zip!/my-plugin.jar` would result in an attempt to extract the file `my-plugin.jar` from `archive.zip`. If that fails, an attempt is made to extract the file `plugins/my-plugin.jar`. And finally, if that fail, an attempt is made to extract the file `archive/my-plugin.jar`.

== Generate the plug-in pack update archive

Now that all the files and information for the plug-in pack update has been obtained, you are ready to package the new plug-in pack using the `jon/dist/server-patch/src/main/scripts/generate-jon-pluginpack-update` utility found in the _jon.git_ repository.

For help using the utility and the command-line options available, use the utilities --help command-line option. For our example, we will continue with the Fuse Plug-in Pack Update we have been using througout.

.Example `generate-jon-pluginpack-update` command for Fuse
[source,bash]
----
# Set necessary variables
newUpdateNumber=06
updateId=1343188
pluginPackName=fuse
changeFile=BZ${updateId}-changeset.txt
newPluginPack="jon-plugin-pack-${pluginPackName}-${packageVersion}-${packageRelease}.zip"
previousPluginPack="jon-plugin-pack-${pluginPackName}-${packageVersion}$( [ -n "${previousUpdateNumber}" ] && echo -update-${previousUpdateNumber}).zip"
serverArchive="jon-server-${packageVersion}-${packageRelease}.zip"
# Package the plug-in pack update archive
generate-jon-pluginpack-update "${newUpdateNumber}" "${updateId}" \
    --changeset-file "${changeFile}" \
    --prev-plug-in-pack-archive "${previousPluginPack}" \
    --plug-in-pack-archive "${newPluginPack}" \
    --server-archive "${serverArchive}" \
    --update-type ${pluginPackName}
----

If no errors or warnings are displayed, you should now have a complete plug-in pack update archive in your current work directory. In the case of the Fuse example being used here, the resulting plug-in pack update archive should be named `jon-plugin-pack-fuse-3.3.0.GA-update-06.zip` and is ready to pass along to _quality engineering_ for final testing before publishing the update to the customer portal.
