OSGi development issues


This is a post written out of frustration and the hope to get some assistance figuring out what I’m screwing up.  I did not proof-read it (will soon though), and I am certain there is some detail that is missing.  This is more of an article for me to remember what I’ve learned so far.  If you’re interested, go for it!


A few weeks ago, I started setting up a development environment with eclipse where I could mainly view the extension library code and perhaps edit and add to it.  This eventually was extended in the hopes of creating my own OSGi Plug-ins.  Let me quickly describe the deployment strategies that I have seen and partially used myself.

1. Central template

The first deployment strategy is going to be the clearest for Notes Developers, I believe.  In fact, it is very common that there is a central application that serves as the main design template and that all other corporate applications use that database.  Most of the time, this primary template contains very little more than images, css files, and maybe a few administrative views which assist with conflicts.  Often the next level of templates will increase the functionality to include libraries and so on.  Of course, this can be done with XPage elements and with Java classes and so on.

This is the method that I started off with, and still use in a few cases, but I found a few issues, or at least I had a few issues.  More than likely, I just found a few cool new ways of messing up and did not realize how.  My main issue was when I distributed Java source code in this manner, I ended up with a great deal of SecurityExceptions and the occasional Serializable- or ClassCastException.  The program would run for a while without any issues whatsoever, and then suddenly I would be getting these stupid errors and they would not go away.  I could only solve it by going into designer, refractoring to change the name of the offending class, and then change the name back again.  I had tried to clean the project, rebuild the project, and there were even a few times I deleted the entire class and recopied the text.  (That last one also worked)  This was annoying.  To fix this issue, the cleanest option I found was to package the source code in a jar (easy to do in eclipse) and then distribute the jar.  This can also be completed with the same sort of template distribution, but the source code is not present, or taken off the build path.  I have had problems just removing the source or old jars from the build path though.  It seems there is a cache that is present that gets in the way, so it is best just to delete it.

2. I vaguely remember some other strategy that I am not going to touch upon….

3. OSGi Development

This is the way I want to go.  The main push to develop my utility files in this fashion is my desire to publish them on openNTF.  Of course this is not any sort of requirement that I have read about, I just find it cleaner, more professional, and easier to maintain and update, not just for me, but also for the customer.  Basically, my components and java files will work in a way similarly exactly like the Extension Library content.  I can have them installed on designer and on the server and just go to town.  At least that is the theory.  There are a few obsticals that I want to touch upon here because I am still not able to do this the way I should and I am pretty stuck.  I do not know if my environment is set up incorrectly, if I am just being stupid, or what the heck is going on.  I am to the point where I do not even know what to ask anymore to try to figure out the issue.  Instead, I am just going to write about my experiance here as best I can in the hopes that someone can help me figure this out.

Eclipse Setup

Setting up eclipse in order to get this to work was my first chore and did not go well.  Again, my goal at this point was to set up eclipse in such a way that I could play with the code for the Extension Libraries.  I starting using this video to set up my environment.  I did have a few issues with this.  The main issue was that the Development package described in the video is not available.  I tried for hours to somehow find it, but it was simply sent to nothingness.  Wonderful.  Using this StackOverflow question, some help from Paul Withers, and a great deal of playing with build paths and workspace settings, I eventually got the code loaded with only a few errors.  The errors that I had were mostly in test packages from the ExtLibs.  I closed those packages and hid my head in the sand refusing to see any of the numerous warnings that I also have, and still have.  The one that bothers me the most is the “Access Restriction” warning saying that a particular class or whatever is not accessible.  I somehow managed to get them to go away (mostly) but I do not remember what I did. If I do, I will post it here.

After a few weeks of a break, I picked it back up again because I wanted to develop my own stuff.  I want to rely on the openNTF Domino API as well as the Extension Library.  Because of this, it makes the most sense to work in that same workspace and just add my projects to it.

 Noob Problems

I will confess right here and now that I am not well versed on OSGi, Plug-in development, or JSF.  I learn by doing, and if I can find a book on the subject, I will buy that mother and soak it up from cover to cover and complete every single understanding exercise it contains, or make up my own in case the author opted out of such a cool idea.  **Hint Hint to all of you authors out there that this person might buy your book if you can come up with something that deals with Domino OSGi dev**  

First off, it is not enough to just copy your source code from designer to eclipse and call it a day.  There are a few different types of projects that you have to create.

1. Project file

In my case, this Project was named de.holistic.utils.  It is the heart and soul of what I am trying to do.  It contains all of the code from designer and is what I want to publish.  I made this a plug-in project, and I am not entirely certain this was correct, but that is the current stand.

2. XSP Plug-in

This is a plug-in that I was not aware was mandatory.  In all honesty in only makes sense though.  This plug-in will point to the “com.ibm.xsp.Library” extension point.  This should act as a flag (as far as i can tell) that tells designer (and I bet Domino) that it is an addition to the Xpage runtime.  I am not really doing anything here other than setting up the XSPLibrary and Activator classes.  Additionally, I have a domino-faces-config.xml file which I have found out can store bean information like the faces config file in the .nsf’s.  My current stand is that I just copied the file directly from the development database and I have not cleaned it up.  The only thing I did was to make sure that the class names are all correct.

3. Feature project

The feature project seems to be fairly simple.  As far as I can tell, it is just a glorified library of plug-ins that are going to be installed into the runtime later.  I do not think there is any real magic happening, it is just an xml file with a pretty front end.

4. Update Site Project

The update site is also just a glorified XML file that points to one or more features.  This produces what we can later zip up and send to customers to install exactly like the ExtLibs.  Again, no magic.

Just getting this far seemed to be a bit of a hassle.  I had no idea that so much was involved in getting one jar file out onto the server.  It does make sense, but I was not expecting it.  Your welcome for the heads up.  😉

 Current Stand and Issues (my Noob-i-ness is painful – especially to me)

Here is the point where I say that I do not know where I am going wrong.  I have posted a few more questions onto StackOverflow mostly because of the symptoms I am seeing, and not really understanding what my issue is to begin with.  The problem that I am having is that I cannot access my classes in a project.  There is no further problem that that.  The rest is all guesswork as to what it can be caused by. Using this article and the answer to my question from SO, I discovered I needed to create an xsp plug-in and correctly set the extension point.  I have since done this.  That tutorial is mainly component based, and while I am sure this is going to come in handy in the future as some of my utilities are components currently used as custom controls.  I have not really had much luck figuring out what to do with java libraries and adding that to the developer’s toolbox.  The issue that the library cannot be chosen in the xsp.properties is still a concern, although i have set the XSPLibrary to global, so that should not be too much of an issue right now.  It is mostly something that I need to clean up in the future.  **I THINK**

When I run an Xpage right now, the beans that I defined in the configuration cannot be created.  It cannot find the class.  I have checked the spelling (but since I am in a really bad mood right now — yes bloody shirt type bad mood for those who read my last latest blog series) I am not so certain that I did not mess that up.  I have made the utility plug in project required for the Xsp project and I added it to the build path.  I have tried many different settings and many different combinations.  I would not be so surprised if I have shot myself in the foot by now and changed stuff that is the cause for my own issues.

The code has been published at GitHub under: https://github.com/GregReeder/de.holistic.utils
I am pretty new to GitHub, so you will not see too much from me there.  I also like to keep my code local and am not sure how often I will publicly commit code, but in this case, it is the best option.

As soon as I figure out what I am screwing up, I will be sure to post about it.

Thanks for the support!

About reederProgramming

I already have an about me page, so I will just put a quick bit of info here. I am a Notes/Domino developer at holistic-net GmbH located in Hannover, Germany. I use Java primarily at home and as often as I can at work. I have dabbled in C# and a few other languages and platforms. This website started out as a place for me to quickly store and access some of my most important how-tos and has started to become a place where I can really help others too!
Tagged , , , , , , , , , , , . Bookmark the permalink.

10 Responses to OSGi development issues

  1. Cameron Gregor says:

    Hey Greg I forked your project and made some changes.

    Check out my version and look at the commit messages for explanations.

    I haven’t tested it on an actual server but it should work and it at least explains the issues a little bit.

    also forgot to mention in the commit about ‘target platform’ locations, you may need to hit ‘reload’ after editing your target platform.

    • reederProgramming says:

      Thank you very much! I am taking a look at it now, and will get back to you soon, or just write about it here.

      • Cameron Gregor says:

        good luck, while I think about it, you may also need to move your managed bean classes (the ones mentioned in the faces config) from the util plugin to the to the same plugin as the XspLibrary.

        • reederProgramming says:

          Just to speak to this point for future readers, I tested it to be unnecessary to add your library to the xsp plug-in. As long as those classes/packages are exported from the original plug-in, the xsp plug-in can still define those classes as beans in the files declared by its getFacesConfigFiles().

          With that being said, I think I am over the learning curve mountain and can start getting some real work done. That was anything but simple, but I am excited to get started. I still have the issue that I cannot select the library in an application in designer as “required” in the Xsp Properites file of an .nsf, but I can still set it as global and use it anyway.

    • reederProgramming says:

      In one video that I watch, I cannot remember which one it was, it told me to deselect all target platforms and set the Framework to Domino OSGi Framework and autostart to false. Is this accurate, and if not, which target platform would be the correct one for designing the plug-ins for domino use and designer developoment? …I admit I may have missed a comment or two in the git commits. At any rate that was a huge help. I was able to go through the two projects and see where the differences were and fix my local copy. There are a lot of good things in there. Once again, thank you very much for your help!

      • reederProgramming says:

        Also, I am assuming that I am selecting run with the feature since it is what points to everything that I need. I just thought I’d mention that since we know what ass/u/me-ing does.

      • Cameron Gregor says:

        I know the video you are talking about, the step you are describing is to do with creating the debugging configuration for your domino server. The instruction would have been “deselect all the plugins from the target platform as these will automatically be added back in” and this is an accurate instruction, however it is a slightly separate issue to setting up your IDE for plugin dev and choosing target platform. To explain I will break up into 2 steps:
        1. Setup eclipse to DEVELOP plugins
        2. Configure Domino server (local dev one) to DEBUG the plugins you are working on

        The two openntf projects mentioned in Niklas Heidloff video that you download : XPages SDK and Domino Debug plugin deal separately with each step. despite being downloaded from the same project, they were developed independantly of each other

        1. DEVELOP – uses XPages SDK
        To develop plugins,we need to specify the JVM so we know what classes etc are available by default in that JVM, then we also need to specify the target platform (basically what set of plugins will be alongside the ones we are developing). The XPages SDK does this by looking at your existing installations of notes OR domino, and using the JVM and set of plugins that exist currently for that installation. So you can create a domino target platform, or a notes one depending on what you have installed on your dev machine. For xpages you want domino target platform, but if you were doing ui tooling for domino designer, you would want notes target platform. You can only have one selected at a time in eclipse. It is also worth pointing out, when you create a new plugin project,it will put the default eclipse JVM library on your build path, you should ‘configure build path’ remove the eclipse system library and then add the ‘system library’ of the domino JVM.
        So this answers the question ‘which target platform’ to eelect , it should be domino target platform the you created with XPages SDK

        2. DEBUG – Domino debug plugin
        So this step is less about your IDE and more about configuring your domino server. Basically you choose your settings and hit ‘debug’ but this doesn’t start a debugger of anything, it just creates a file pde.launch.ini which points to another file, the ‘configuration area’. They way the debug plugin is written, it only wants to know ‘which plugins from your ide workspace would you like to include in addition to the normal ones for the domino server?’ It doesn’t really care what your target platform\jvm settings in eclipse are, it will inspect you domino server config directly and include all the standard plugins (which is why you deselect them as they are added anyway). The next time domino http starts it will see pde.launch.ini and say ‘ hey don’t do what I normally do, instead I will use this configuration’

        If you find the configuration area you can see all the plugins listed including the references directly to your plugins in your workspace

        Hope this makes sense, let me know

        • reederProgramming says:

          Thank you for the clarification. I was misunderstanding something and it is all good now. Thanks for the great information!

  2. Cameron Gregor says:

    hi Greg, sorry to hear your frustrations, I have been through the same feelings when learning this as I am sure many others have, but when you come out the other side you will have the scars to remember how to do it all 🙂

    I can see 2 issues. first one: you do not seem to be ‘exporting’ any packages or classes. osgi plugins are like black boxes in that other plugins can only see the classes/packages that have been made available to other plugins via ‘exporting’. you can either export at package level or individual classes. usually simpler at package level. you do this in the manifest.mf, have a look at extlib source code for example. you need to export your XspLibrary as well as any classes (beans, components etc) that xpages needs to use.

    secondly your XspLibrary should be in the same plugin as your utils.
    imagine you develop all your code then finally you add the XspLibrary class to the plugin which is just extra information needed to describe to xpages how to use in xpages.

    finally I noticed your getFacesConfigFiles doesn’t include the domino-faces-config file you mentioned. this function should return a string array of all the faces config files to load, also see extlib for example.

    hope that gives you some ideas to check, I had already recorded some videos on this so I might publish them in the next couple of days and let you know so it might explain the process a bit clearer than articles, I recorded them specifically because (as you said) all articles I found focused on control dev and not java/beans

Leave a Reply

Your email address will not be published. Required fields are marked *