Appistry CloudIQ Maven plugin: Update fabric / far version

Ever since Appistry CloudIQ Maven plugin has been open-sourced on Google code, enhancements and features are being added regularly. A recent feature that was added was the update fabric/far version goal.

Update fabric/far version
The update fabric/far version goal of the Appistry CloudIQ Maven plugin automates the version update of the fabric/far artifact and integrates this process into the Maven build life-cycle of the CloudIQ artifact.

During development or build/run/test cycle, the process of manually having to update the version of the fabric/far becomes painful real quick. And heaven forbid that your forget to update the version and attempt a deploy – Appistry CloudIQ rejects the artifact with a nasty message stating that the version that you are attempting to deploy is older than the version it has currently.

The cloudiq:update-far-version goal alleviates the above problem by automating the update of the version value.

Usage
To update the version of the fabric/far application, run this goal as:

mvn cloudiq:update-far-version

Assuming you have configured the Appistry CloudIQ Maven plugin as follows in your project pom:

<build>
    <plugins>
        <plugin>
		<groupId>com.appistry.maven.plugins</groupId>
		<artifactId>maven-cloudiq-plugin</artifactId>
		<version>0.0.1-SNAPSHOT</version>
		<configuration>
			<appName>CreditRules_App</appName>
			<appFilename>CreditRules_App</appFilename>
			<remoteSshHost>192.168.5.55</remoteSshHost>
			<remoteSshPort>22</remoteSshPort>
			<remoteSshUsername>fabricuser</remoteSshUsername>
			<remoteSshPassword>fabricuser</remoteSshPassword>
			<!--
				<farVersionUpdateSkip>false</farVersionUpdateSkip>
				<farVersion>99</farVersion>
			-->
		</configuration>
	</plugin>
</plugins>
</build>

the mvn package cloudiq:update-far-version command will update (increment by 1) the version value in the fabric/far application descriptor (in this case, CreditRules_App.xml). Currently the only requirement is that the version defined in the application descriptor is an integer. We will talk a little more about this requirement a little later.

Note: This goal (cloudiq:update-far-version) is part of the cloudiq:package goal which essentially performs the following:

1. copies the resources/scripts files (cloudiq:copy-resources goal) to a work directory,
2. updates the version of the fabric/far application descriptor (cloudiq:update-far-version goal),
3. gathers the dependent (if any) jars (cloudiq:assemble-dependencies goal), and
4. runs fabric_pkg to create the actual fabric/far artifact.

99.99% of the time you will run the cloudiq:package goal which as described above will update the version and package the app as a deployable CloudIQ artifact.

Configuration
The cloudiq:update-far-version goal does not need any configuration since all it does is read the existing version and increment it. But there are some configuration parameters around this goal that come in handy when needed.

farVersionUpdateSkip
Setting this parameter to true will skip the execution of the cloudiq:update-far-version goal. This comes in handy if you want to update the version by hand or using some other process. The default is false i.e. the version gets updated when either cloudiq:package goal or cloudiq:update-far-version goal is run.

farVersion
This parameter allows you to specify a version that will be used and hence overrides the default behavior of the cloudiq:update-far-version goal which is to increment the version by 1.
This parameter takes a string as it value. That’s right, a String rather than an integer. So you could set it to a value like “1.0″ or “5.0.2″.
I generally use this parameter when I tag my build in my source control management (SCM) and then use the tag value as the version. Of course, the version (SCM tag) is higher than the version deployed (which generally is an older SCM tag). This helps in co-relating what the version deployed to the version tagged in SCM.

Best Practices
Recall, a little above I stated that one of the requirements is that the version defined in the application descriptor is an integer. But then in the farVersion property I contradicted it by saying that you could pass in a string.
Well, let’s clear this up.

Development environment/cloud
Generally during development, you are building from HEAD (or TRUNK or MAIN branch) of your SCM and deploying to a development cloud. And during development you frequently build, deploy and test your changes. During this time, you don’t really care what the version is of the fabric/far as long as it is greater than the existing one so you can deploy it without Appistry CloudIQ baulking at your deploy attempts. Therefore during this time the “increment by 1″ strategy comes in handy. Hence it is a good practice to:

• Set the initial version in the fabric/far application descriptor to an integer, say 1
• Do not specify a farVersion property

and let the plugin do the job of updating the version every time you build.

Test or QA or Production environment/cloud
Once you are ready to deploy to a test/QA/production cloud, tag your code in SCM and use the tag as the value of the farVersion property. This way you know what version of code is deployed in your test/qa/production environments and you can reproduce those artifacts at will.