Develop OSGi Bundle Using Adoble CQ CRXDE Lite

It is often confusing as to how to set up an OSGi development environment for CQ5. In this post, I'll set what is to be coded aside, but focus on how to quickly and easily use CRXDE Lite (the web interface of CQ5) for 

1. setting up an OSGi project skeleton for development, 
   
2. adding libraries to OSGi project's internal build path, 
   
3. building OSGi projejct, 
   
4. deploying the compiled OSGi bundle in to CQ5 container.
   

What OSGi Bundle Can Bring to CQ

CQ5 runs in an Apache Felix OSGi container. To add configurable modular code to CQ, the code must also be an OSGi bundle jar. Out of the box, Adoble CQ5 is deployed with several OSGi components that you can configure them. To extend CQ's functionalities, you can develop your own OSGi bundle and deploy it into Felix, the OSGi container. 


For example, if you want to write a custom library in Java that your JSP can import and use from any JSP file, you can develop an OSGi bundle. Or, if you want to some code to be triggered and executed whenever you 'activate/publish' a page node, you can develop an custom Workflow OSGi bundle with code of jobs to be executed whenever such an 'activate/publish' event is fired.

Create OSGi Bundle with CRXDE Lite

step #1: Create an OSGi bundle project skeleton

Shoot up your CQ instance, log on as admin, go to CRXDE Lite. In CRXDE Lite, find a folder named 'src' (/apps/[your project]/src) under which is where your OSGi project will/should reside. To create a OSGi project skeleton, simply right-click src, select Create, then Create Bundle:

In the pop-up, give information to the bundle you'd create. 

• Symbolic Name: will be used toward the final OSGi bundle jar's name. 
  
• Name: is the name for displaying purposes in the CQ's Web console interface. 
  
• Package: is the full Java package name of the bundle you'd create. CQ will create corresponding folder to hold the java code.

After you hit OK, the following file structure with folders will be generated, include a BND file and an Activator.java.

Adobe CQ is not very user friendly. A common mistake developers make is forget to save along the way. Until now, nothing I created so far is saved. I have to explicitly save them by clicking on 'Save All.' You must remember to save often and I'm not going to remind you any more from this point on.

What if you have libraries (e.g., jars) to add to the build path for the project to compile in? I do not know any official documentation from Adobe about this but my experiments indicate if I create a folder named libs at the same level as the src folder, jars put under this libs folder will be built toward the project. In addition, I learned that /etc/crxde/profiles/default/libs/ is probably also part of the buildpath that you can also drop libraries there.

To demonstrate, I created a folder named libs, under which I put a dom4j jar and it will be picked up by CRXDE Lite's default bundle build step. Also, for demonstration purposes, I created some more Java classes (PageActivationEventHandler.java and PostpageActivationWorkflow.java) as if I had developed them and put them under the proper folder just to show where your custom Java source should go.

step #2: Modify bnd file

BND is a command-line tool used internally by CQ for building OSGi bundles from a  given descriptor file (.bnd file) to structure your JARs/Bundles by generating not just the MANIFEST.MF but also bundle up the JAR itself.

It is the auto-generated com.test.service.bnd file that I modified to overwrite the default to export all package and import all package:

Export-Package: *                          # 1
Import-Package: *
Private-Package: com.test.service
# Include-Resource: 
Bundle-Name: Test Bundle
Bundle-Description: 
Bundle-SymbolicName: com.test.service
Bundle-Version: 1.0.0-SNAPSHOT
Bundle-Activator: com.test.service.Activator

[1] For some reason, in CRXDE Lite, this '*' is required for making a specific component 'configurable' via CQ's configuration console. Otherwise, even you annotate a component with metatype=true (so Metatype Service data is generated in the metatype.xml file for this component) which in terms instructs CQ5 to provide a configuration page in the Felix Web console, the configuration interface still won't show under Web Console.

step #3: Build bundle

To build, high-light the .bnd file, select Tools, then Bunld Bundle:

The result is the final bundle jar file generated under a folder named install which is at the same level as the src folder. As a reminder, the generated bundle jar won't show on CRXDE Lite until you refresh the install folder:

Install OSGi Bundle Built by CRXDE Lite

Once a bundle (.jar) file is generated under install folder, this bundle Jar file under install folder will be automatically picked up and installed by CQ5, specifically, by the JCR Installer module implicitly. In other words, if you followed step #3 for the first time that generated the bundle file (.jar) for the first time, the .jar should be installed for you already.

To verify the bundle jar is installed, you can always go to CQ's Web Console (probably at http://localhost:4502/system/console/configMgr), and look under OSGi, Bundles to see if the bundle name specified in step #1 above shows up.

Re-install OSGi Bundle Build by CRXDE Lite

Chances are, you'll be using CRXDE Lite to change your OSGi bundle code, build, install it, change the code, re-build, and re-install it over and over as part of the development process. I concluded the following steps to be most reliable:

1. Delete the old OSGi bundle (.jar) file under install folder. Click 'Save' to persist the deletion. This deletion will remove the bundle from appearing in the OSGi console. In other words, delete the .jar will uninstall the bundle.
2. Modify your OSGi code with enhancement or bug fixes. Rebuild (refer to step #3 as mentioned before) it, which will re-generate bundle file (.jar) under install folder.
3. Go to OSGi Console, locate the Bundle, click on it to bring up a page that only shows that bundle, click on "Refresh Packages."

'Refresh packages' instructs Felix OSGi container to reload the package dependency related to the package.

The same OSGi bundle under your development is now re-deployed.

References

• Developing with CRXDE Lite
  
• Hello, OSGi, Part 1: Bundles for beginners