Trials with JPA and XPages


Don’t get me wrong, I love working with Domino and documents and all that ūüėČ , but with XPages I sometimes want to use good old fashioned SQL or even hybrid solutions. I do not want to be bothered with writing sql statements myself in the DAO classes, and I just want to use a prebuilt solution that just works. Enter JPA.

Before I go too much into this, I want to thank the guys on Slack for giving me a hand with the bits and pieces of this. I had a great deal of problems getting this thing going and it is still very far from perfect. I can at least say, however, that it runs.

Quick trial history

I started out with a simple PoC concept of trying to build a type of registry for DVDs I have. (Not creative, just quick and simple). I also decided to do this with eclipselink and built in Eclipse mars. I quickly built a few entity classes and I used the xml orm to map those entities to the database. When this was done, I exported that project to a jar file and then imported that jar into an *.nsf. This first try failed. I am sure I can think of numerous reasons why it did not work. The main issue I had was that the persistence unit I tried to configure could not be found on the runtime. At this point, I copied the eclipselink jars into the nsf directly, and copied the entities into the .nsf.  In other words, the JPA Layer was no longer its own single jar. This allowed me to try to move the configuration files around to other locations. I tried everything I could think of. Fail.

Rethink and Rework

(in other words, ask around…)

Let me just say that if you are not already a member of the XPages Slack community, why aren’t you? JOIN!!!

I went into the random channel, and posted a general question if anyone had success with JPA and XPages. Jesse Gallagher pointed out this post by Toby Samples which uses the hibernate JPA framework. I had seen this presentation before, but I must admit that it lacks the meat and potatoes needed to get it off the ground.  Dont get me wrong, it is a great resource! The other reason why I did not do much with this at first is that it was done in eclipse and not Notes Designer. Most of the stuff that I program for XPages is done directly in Designer and not in eclipse. After talking to the guys on Slack, and seeing that Toby Samples had success with hibernate, I decided to indeed give it a try.

Downloading Hibernate

In the slides (see the above link), Toby describes talks about hibernate tools being downloaded and installed in eclipse. As we all know, Notes is now based off of eclipse, albeit an older version of eclipse…¬† After a lot of searching, I did find an updateSite with the tools and I downloaded a copy of them. I then installed them onto my client as a Widget and also onto the server. This really did nothing worth while.¬† I could not access the tools in designer, nor were they available on the server. I deleted them pretty quickly. Instead, I¬†found this site to download an older version of the ORM. It is necessary to take the 4.3.11 version because Notes/Domino runs on a bitterly out-dated version of java. Once this is downloaded, I imported the required jars into my .nsf. I also put these jars into the <domino>/jvm/lib/etc/ directory as described in the slides. The only issues I had at this point was that designer couldn’t process the source quickly enough to give me the code suggestions and I had the feeling that designer was always a step away from crashing.¬† Indeed it did crash once or twice… (After a system restart it seems to have gotten better)

Configuration and Setup

The first thing that I did was to create the hibernate.cfg.xml file. This is all pretty straight forward.¬† I am also not going to discuss how this file is to be created, but I will show you my copy…

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE hibernate-configuration PUBLIC 
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"

   <session-factory name="hibernateSessionFactory">
        <property name="hibernate.connection.driver_class">com.mysql.jdbc.Driver</property>
            <property name="hibernate.connection.password">****</property>
            <property name="hibernate.connection.url">jdbc:mysql://</property>
            <property name="hibernate.connection.username">DB_Programmatic_User</property>
            <property name="hibernate.show_sql">true</property>
            <property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property>
            <property name="">false</property>
            <!-- <property name="">create</property>  -->

            <mapping class="de.domain..bluemix.jpa.entities.Actor"></mapping>
            <mapping class="de.domain.bluemix.jpa.entities.DVD"></mapping>
            <mapping class="de.domain.jpa.entities.Genre"></mapping>	

The second thing I did was create an application listener with static information for creating sessions.



import org.hibernate.SessionFactory;
import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
import org.hibernate.cfg.Configuration;
import org.hibernate.service.ServiceRegistry;


public class PersistenceManager implements Serializable, ApplicationListener2 {

      private static final long serialVersionUID = 1L;

      private static SessionFactory sessionFactory;

      private static boolean init = false;
      public static SessionFactory getSessionFactory() {
            if((sessionFactory == null) || (sessionFactory.isClosed())){
                  throw new IllegalStateException("Session Factory is null or closed!");
            return sessionFactory;
      public static boolean isInit() {
            return init;
      private void init(){
                        System.out.println("Initializing Session Factory");
                        Configuration conf = new Configuration().configure();
                        ServiceRegistry serviceRegistry= new StandardServiceRegistryBuilder().applySettings(conf.getProperties()).build();
                        sessionFactory = conf.buildSessionFactory(serviceRegistry);
                        init = true;
                  } catch(Throwable t){

      public void reInit(){
      private void destroy(){
            System.out.println("Destroying Entity Manager Factory");
            init = false;
            if(sessionFactory != null)	sessionFactory.close();
            sessionFactory = null;

      public void applicationCreated(ApplicationEx arg0) {

      public void applicationDestroyed(ApplicationEx arg0) {

      public void applicationRefreshed(ApplicationEx arg0) {

The point of the application listener is to make sure clean up is done correctly and to make sure that everything is initialized correctly.  It probably is not needed in this way, but I found it at the very least to be a cool idea. This class must also be registered. Here is a screen shot with the location of these files.







Primary Problem

This configuration worked…. almost. I kept getting security exceptions. The runtime was not being granted the permissions it needed to run the code. Only after I added the following lines to the java.policy document was I able to get the code to execute properly.

permission java.lang.RuntimePermission "getClassLoader"; 
permission java.lang.RuntimePermission "setContextClassLoader"; 

permission java.util.PropertyPermission "jboss.i18n.generate-proxies" "write"

This is a situation that I find sucky. It is alright for a test environment, but I would not want to mess with the policy file for an end-customer. My question is, does anyone have a possible solution for this?


It is possible to use JPA and it works well,  but I am not happy about the wide-open security window that was necessary in order to get it to work.

One more time, thank you to those on Slack who gave me a hand…

Toby Samples, David Leedy, Jesse Gallagher, and others who had hints…


Attachments and Java Beans

Up until this point, I must admit that I have been lazy. Even though most of the XPages I have created in the last two years have made extensive use of Java Beans, I have left the attachments to the XspDocument and the typical upload and download controls. I did not want to open that can of worms and just wanted to stick with what I know works. Well, that is dumb. It is fine for one or two minor applications that are never going to be used anyway, but when it comes down to it, I want it to be correct. Today, I started that adventure and, with all new things, a google search was performed for anything that could help me and point me in the correct direction. (Honestly, what did you old folks do without search engines? I’d be lost! Or at the very least spending 10 hours a day at the public library!) What I did not find was a document that contained upload and download information. Since I do not want to loose what I found today, I decided to write a quick post. Thank you to everyone that I am stealing from to write this…. ūüėõ

The first thing that I noticed was that my concept was faulty. At least I think it was. I wanted to have a single file in my Java Bean that I could upload and download at will and access and save in my DAO layer. Of course I could be mistaken, but it does not seem to work that way. Uploading documents and downloading them again needs to be performed in two different actions, and in two different ways, and with different objects. Futhermore, I do not even offer both functions on the same page, though both are possible with the same bean.

First off, my test bean is very simple. If I were to extract an interface (just to get a quick look at what the bean contains, it would hold the following information

public interface IFileTest {

* This function contains the information to save the document. Normally, I do this in a seperate DAO layer Object.
* The example that I used had the majority of the information in one single class.
* I did not experiment as I wanted to keep everything as simple as possible. Such experiments are further on my to-do list.
public abstract void save() throws Exception;

* This function contains the logic to download the attachement. It is performed in a separate XPage containing only this function call.
public abstract void downloadAttachment() throws Exception;

* This function returns a string that points to the xpages with the download attachment function call.
public abstract String getDownloadURL();

* This function will read the parameters from the URL in order to initialize the data for the viewscoped bean.
* Normally with the Beans I create, this function will access the DAO and set the data in an object contained by this Bean.
* This Bean is a controller in the MVC design pattern.
public abstract void init();

* I just find this helpful.
public abstract String getUnid();

* This object is used ONLY in the upload core XPage control.
public abstract UploadedFile getFile();

public abstract void setFile(UploadedFile file);



As i said, this test is done with as simple a construct as possible.

After this was completed, I worked on uploading a document. It seemed the most logical starting point. My primary source for this was a StackOverflow question posted by David Leedy so, note that the following code is primarily coming from Mark Leusink, the accepted answerer of Mr. Leedy’s question. The first part is the most simple. I have a property in my Bean that is of type . I have a corresponding getter/setter pair. I use EL to link the core control for uploading data to the bean. The real magic happens in the save logic.

public void save() throws Exception{
    /* I use the openNTF Domino API (ODA) for nearly all of my
     * applications. If this was not the case, we would have to worry about
     * proper recycling. Keep in mind that this is also just a test. Normally
     * my routines have much cleaner error handling.
     * The following statement uses a utility that I built that helps me get
     * key objects. I am assuming here that you know how to get a handle on the current
     * document. 
    Document doc = ODASessionHelper.getCurrentDatabase().createDocument();
    doc.replaceItemValue(FIELD_FORM, FORM_NAME);
    // file is and instance of UploadedFIle. This is the Property that is bound to the core FileUpload control
    if(file != null){ 
      IUploadedFile fl = file.getUploadedFile();
      //File is the standard variant.
      File file = fl.getServerFile();
      String fileName = fl.getClientFileName();
      // this gave me ONLY the name of the file without any path information.
      System.out.println(String.format("clientFileName: '%s'", fileName)); 
      // on my system, this gave the character ";"
      System.out.println(String.format("seperator is '%s'", File.pathSeparator));
      // This gives you the location of the file that was uploaded by the control on the server.
      File realNameFile = new File(file.getAbsoluteFile() + File.pathSeparator + fileName);
      System.out.println(String.format("realFile name: '%s'", realNameFile.getAbsoluteFile()));
      boolean renamedFile = file.renameTo(realNameFile);
        //typical code to attach a file to a document.
        RichTextItem body = doc.createRichTextItem(FIELD_BODY);
        body.embedObject(EmbeddedObject.EMBED_ATTACHMENT, "", realNameFile.getAbsolutePath(), null);
      } else {
        throw new Exception("file could not be renamed");
       * Normally at this stage, I save the UNID so that I get that document again
       * to prevent a bunch of new documents being created.  This is just me being 
       * lazy and wanting to get a test out ASAP.
    } else {
      throw new NullPointerException("file was null");

The only issue that I have with the above code is that the new name of the attachment is a bit messed up. I do not know if it is because the operating system is windows, or if it is because of the domino version, but the attachment name is changed to “_<strangenumbers>tmp;realAttachmentName.txt” . This is because File.pathSeperator is a semicolon. I have a workaround for this in my download function, but a workaround is still only a workaround.

As I previously said, I did not find a post with both upload and download functionality explained. I did find an awesome article on openNTF regarding downloading attachments programmatically. So, here is a quick shout-out to Naveen Maurya who posted the XSnippet. In the example provided, an XPage was built which called a server-side JavaScript function which got a handle on the FacesContext and the server response to download all files in a zip file. I just edited this to be run in my Bean and not in JavaScript.

   * same disclaimer. I wanted to this quickly. Normally my error handling is 
   * significantly better. I just want the theory here.
  public void downloadAttachment() throws Exception{
    Database db = null;
    Document doc = null;
    OutputStream stream = null;
    ZipOutputStream out = null;
    BufferedInputStream in = null;
      if(StringHelper.isNullOrEmpty(getUnid())) throw new IllegalStateException("Unid is null");
      // again, I am using ODA, and this is just a way to get the current database.
      db = ODASessionHelper.getCurrentDatabase();
       * I normally do this in multiple steps.
       * 1. try to get the document with the UNID
       * 2. try to get the document with the noteID
      doc = db.getDocumentByUNID(getUnid());
        throw new IllegalStateException("body not located");
      } else {
        Item item = doc.getFirstItem(FIELD_BODY);
        if(!(item instanceof RichTextItem)){
          // I would assume that I would have to come up with a MIME variant as well.
          throw new IllegalStateException("item is not of type richtext");
        } else {
          // normally I ask if item is instanceof RichTextItem
          RichTextItem body = (RichTextItem)item;
          Vector objs = body.getEmbeddedObjects();
            throw new IllegalStateException("body has no objects to download");
          } else {
            ExternalContext extContext = FacesContext.getCurrentInstance().getExternalContext();
            // javax.servlet.http.HttpServletResponse;
            HttpServletResponse response = (HttpServletResponse)extContext.getResponse();
            response.setHeader("Cache-Control", "no-cache");
            response.setDateHeader("Expires", -1);
            response.setContentType("application/zip"); // change this for different types.
            // I gave a static name to my zip file, but the original code was dynamic
            response.setHeader("Content-Disposition", "attachment;");
            stream = response.getOutputStream();
            out = new ZipOutputStream(stream);
            for(EmbeddedObject att : objs){
              in = new BufferedInputStream(att.getInputStream());
              int length = in.available();
              byte[] data = new byte[length];
    , 0, length);
              String nm = att.getName();
               * This is my workaround for the file names. Although they are saved in the document
               * with the incorrect name, I could at least download them again with the proper name.
              ZipEntry entry = new ZipEntry(nm.contains(";") ? StringHelper.rightSubstring(nm, ";") : nm);
          // cleanup should be done properly.  this is a 'do as I say, not as I do' moment.....
    } catch(Exception e){
      // very nasty error handling....
      throw e;

In conclusion, I have a test XPage application with one form, and with two xpages. The one xpage allows saving attachments. It has the File Upload control available by the XPages core and a save button. The second XPage is only used for downloading the attachments. It holds no content, but gets the file to download via the HTTPServletResponse in the beforeRenderResponse XPage action. The UNID of the document is passed with the URL.

Although not implemented in an xpage, I also built the logic to open the URL in a new window using client side javascript:"#{javascript:FileTest.getDownloadURL()}", "_blank");

FileTest in the above example is the name of the bean as configured in the FacesConfig.xml file.

My next steps would be

  • to build a view with which I could display the file names and other typical information available for file downloads
  • export files without being compressed into a zip file
  • it goes without saying that I would have to refine the above functions and build in proper cleanup and error handling

Happy Programming!!

Java Beans and funny stuff

I have such a backlog of posts that I have written and have neglected to post, it is not even funny.  I have a few videos that still need to be edited or redone and it is nuts. So first off, I am sorry for the long breaks in posts, but life tends to get in the way.

Today I was working with an apprentice and getting him involved with XPages.  He seems to enjoy it so far, and it is a help for me because I give some of the more mundane things to him.  He has zero Notes/Domino experience and has focused primarily on .NET development.  If you go to, you can see a bit of his handy work.  Of course he worked with another apprentice of ours to build that site, and I must say together they built one awesome application.  But I digress.  Of course I think our apprentices are amazing, but we want to quickly discuss our adventures of the day with Beans and XPages.

As readers may or may not be aware, I have spent a great deal of time developing a standard java library that I use in all of my XPage applications for use both internally and for customers.  It includes custom controls, standard beans, and now a configuration.  But a simple configuration was not good enough for me.  Let me quickly get into my use case.

Up until now, I have been using a file saved under the Resources/Files tab of the project. ¬†I wanted to get around needing profiles which can be a cached pain in the rear, I originally did not want to have a view to look up a specific document, and I did not want to touch the xsp.config xml file. Of course there are some wonderful snippets available from Paul Withers in case you would prefer that approach. ¬†I wanted to save values that differ from database instance to database instance, as well as from dev version to QA version to productive version. ¬†As far as I am aware, performing a design refresh also rewrites the config.xml file. ¬†Really the best way to get the functionality I wanted was a good old fashioned NotesDocument, a good old fashioned view, and the wonderful ODA view method “getFirstDocumentByKey()”. #ODAOnceMoreForTheWin .

This brought on interesting points that I could discuss with the apprentice: abstract classes, Beans, and expression language.   I wanted to build the following structure:

-contains the view alias for lookups which will be used for all XPage configurations
-abstract init() method
-abstract getLookupKey() method
-a few other methods that are sensible for our use case but may not be needed for all.

AbstractDashboardConfiguration => AbstractConfig (just an example)
-implements init() to fetch the needed data
-protected final Strings for each field in the NotesDocument
-private members for each field value and the appropriate getter/setters

DashboardConfigurationDocument => AbstractDashboardConfiguration (just an example)
-save() implementation
-specific XPage rendering helper functions
-is set up as a viewScope variable

DashboardConfiguration => AbstractDashboardConfiguration (just an example)
-Specific methods to use a re-init interface that I built so that all of my applicationScoped beans can be reinitialized with a click of a button by an admin
-obviously applicationScoped

As you can see, the build up is pretty complex, and this is the easiest of examples. ¬†There are probably a few “WTF?” questions that I should touch upon, so let me get to them first.

First off, I am sure the reason for an AbstractConfig class is clear.  When all configuration documents are already being saved in the same view, then why not.  Certain fields need to be set in order to guarantee that they are displayed in the correct view. Also, why should the name of the view be set in each configuration class?  It just makes sense to have a single abstractconfig java class.  But, the question that probably comes to mind is, why is there a need for another abstract class before the real implementation?

The answer is pretty simple: I hate StackOverflowExceptions. ¬†I started to create two classes to handle configuration information. ¬†One bean would be responsible for saving and editing the information (DashboardConfigurationDocument), and the other would be responsible for caching the information in the applicationScope (DashboardConfiguration). ¬†Without the abstract class I am left with the following¬†conundrum…..

It is clear that DashboardConfigurationDocument should get it’s information from the document… I mean…. ¬†it is sort of implied in the name. ¬†It should also save itself. It then needs to inform the applicationScoped DashboardConfiguration bean that it should refresh its data. This data¬†could be read from DashboardConfigurationDocument to get around needing to write the int() function twice. ¬†Right there we have a problem because¬†we have two classes that call each other. ¬†It just makes the most sense that both of these classes have the same key functions and members in the abstract version, and the rest of the key implementation in the concrete classes. ¬†It makes for a much cleaner implementation at the cost of hereditary chaos. ¬†ūüôā ¬† Truth be told I find it awesome.

The second major question that I should directly address is, why do I just not save the DashBoardConfigurationDocument bean in the application scope? Basically I am a control freak wanting to do crazy things. ¬†No…. ¬†I assure you that I have a reason. ¬†Let’s look at lazy admin A and multi-tasker admin B. ¬†Admin A makes a single change, directly in the appScoped bean before going for coffee, and admin B gets a phone call after doing the same. ¬†Neither are finished with their changes, neither of them had to save the changes explicitly, yet both of the have a change that is already potentially putting the application in an unstable state. ¬†Baaaaaaaddddd ¬†vooodooo…. ¬†baaaaaaaadddddd. ¬†For this reason, I also like to separate my editing logic from my global configuration logic. Additionally, I can have XPage UI specific logic in the viewScoped class without feeling guilty about caching stupid spam members in the appScope bean.

I can use this pattern as often as I want, and I can be sure that I do not forget anything.  All of my field names are saved as final strings and I can use them in other sub-classes if I need to.  I can even decide later that I want to override my save function in another bean to get SQL support or whatever. It is just clean, and I like clean.

After taking some time to explain a lot of this to the apprentice, we dove into Expression Language and getting some good old binding done. ¬†It worked like a charm…. almost.

This goes into another crazy use case.  I only wanted one configuration XPage.  I have an enum where I have specific configuration keys saved.  These values are then presented to the user in a combobox where a specific configuration key can be selected, and the document is opened, and the information is displayed.  We did this with Expression Language.  The ComboBox held string values representing each of the values in the enum, and the bean had the necessary getter and setter to take the string and set the enum value for that document.  This setter also triggered a process whereby the configuration was fetched and the values were refreshed.  It was a thing of beauty until we realized that the values were not being refreshed on the XPage although the values in the bean were being refreshed with the contents of the NotesDocument.  It took us two hours to figure this issue out.  The correct getters/setters were being called, the init() function was being called, the correct document was being retrieved, and the values were correct in the bean.  Why were they not refreshed on the XPage?

First off, I thought it was a simple refresh problem.  The errorMessages control displayed no errors, and I thought that it was just a simple case of needing to either perform a full refresh, a refresh directly on the component, or some other crazy thing.  We messed around without any success.  In the end, this was one instance where a simple EL expression just was not enough.  We saw that the EL expression was calling the correct methods;  the onChange partial refresh on the page was working correctly.  My suspicion is that the partial refresh was being performed faster than the methods called by the EL expression.  We took out the EL data binding and instead implemented a SSJS function calling the setter method for the configuration key.  When we did this, everything worked as planned.  We also now have one page that can be used for multiple similar configuration documents that can easily be extended without changes in the design.

Lesson learned:  Java is awesome, EL is cool, but ssjs still has to be used for certain things.

XPage Java dev Tutorial 2 – AdminPanel prt 1


General Feels and Gratitude

Hello Everybody!!  Today I am really happy to present my first NotesIn9 video!  It was really great being able to make this sub-series and be a part of the tutorials that really got me going with XPage development.  I want to thank David Leedy for giving me the opportunity as well as thank my employer for allowing me to use what I learn on company time to create content for others.  This is turning out to be a hobby that is really starting to take off.  Again, I have to thank twitter, David Leedy, and Paul Withers for sharing my first blog posts and spreading the word that this blog is out and about.  I would not be so into this right now if it were not for the fresh feeling of being able to do good for others and not just use this website as my own knowledge repository. Thank you to those who read these posts, watch the videos, and of course who retweet, comment and like what I am doing.  All that really makes it easier to stay motivated.


Down to Business

What is this mini/sub -series all about?

As you may or may not be aware, everything that we are doing here has a basis in my day to day development.  I started out using java for my xpage dev about a year ago (I had already used java extensively in my daily programming, just not in combination with XPages for which I mostly relied on JavaScript.) To really get started with Java, I decided to make a utility package that included everything that I needed to know to really get going.  I started off with making a sessionHelper.  I did this because I needed to learn how to get a session object.  I did not know anything about the variable resolver at first, and I also had a lot of trouble finding resources to figure it out.  After I managed that, I moved on to one of the most important features of all databases that I develop, the Admin Panel.

The Admin Panel is (currently) a custom control where I store tables that show the variable names and values of all objects located in the applicationScope, the sessionScope, and the viewScope. ¬†I do not waste my time with the requestScope, although I suspect that such a thing would be possible if I found a use case for it. ¬†Additionally to this, I show another HTML table that presents cookie information. ¬†This is a part of another module that I call “the cookie helper”. ¬†Finally, a larger and more complex table presents logging information to the user with a particular role. ¬†The custom control contains functions that erase the variables located in the scoped maps (although I have not made that work without causing errors) add string variables to the scopes (not very helpful, but cool), and delete logging information shown in the debug section of the admin panel. ¬†A great feature of the debug table is that there are six different error levels that all use different row styles. ¬†This allows the trace information to be shown in a more understated way, and fatal errors to pop out like a sore thumb. ¬†Later, I turned this same functionality around to store and show entire session logging documents in a logging database.

Today we are going to look at how to build your own Admin Panel using information built, retained, and retrieved in Java.

How is this sub-series built?

Due to time, I broke this down into three different parts.  Since I am actually coding on camera as much as possible, it is taking a while to get through it.  I am doing this so that you can see where I have difficulty, so that you can hear me commenting as I go, and because my entire concept in this Java Tutorial is to program an application from start to finish together.  When it is just taking too long and when I do not have a lot to say, I do edit out some parts.

Part one (this part) is going to be a basic introduction.  We do, for this one time only, go through a PowerPoint presentation where I go into what we are doing, the three parts, and some basic information about myself.  One thing that changed from the making of the PowerPoint slides to the videos is that the concept had to be changed from asking question before the recording of the next part to all the questions being asked in comments and through email and me answering them in a written format or in a fourth video.  It makes sense for numerous reasons, but we do not need to get into that.

Part two is primarily Java construction.  Although some Java classes were started in the first part, in part two we really get going.  I do not want to spoil it too much here, but we basically finish up all the beans that we are going to need for the custom control.

Part three is being my slight PITA.  I recorded it once already, but am not pleased with how it turned out.  I really need to stop doing my recordings after 1 AM.  I am going to be deleting the changes and redoing the video.  Part three includes registering the beans that we already made with the faces-config.xml file and designing our custom control.  We go into how to add a few custom properties, although we admittedly do not go into every detail that you could possibly go over.  There are numerous NotesIn9s if you need help specifically with Custom Controls.

 Why is this a sub-series?

This is a sub-series because it is a small part in the project that we are building together. ¬†I was trying to find some way to make videos for this page’s main tutorial while also making content for NotesIn9. ¬†I decided that it would be awesome to make some of the content that can really stand alone its own sub series and give them to David Leedy. ¬†For those who follow along here, it should seem pretty seamless. ¬†To those who watch the NotesIn9s, it is my hope that you can watch that content and get what you need without too much knowledge of what we are doing in the rest of the tutorials. ¬†At any rate, I am posting the code on this website. ¬†That being said, without any further ado- I give you the video, and following the video, the code! ¬†Enjoy!


Find the video here!



XPage dev Why Java

I recently received a comment that I would like to address:

Hey Greg. I watched the tutorial and followed it quite easily. My biggest block to Java is why should I use it? I am having difficulty understanding what the great benefits are, other than getting skilled in a new field.
I also am perplexed as to why, for example, would I need a session helper when I have session info with my standard XPage. Another thing, having an object of a Domino document and using the object to read and write fields back to my source data seems rather tedious seeing that I can read and write straight to my source data?!?
I’m missing something for sure because everyone seems to be wanting to go the Java route.
If I had 1000 users open an XPage application and view a document then why create 1000 objects, one for each document and session helpers. Does that not take needless memory?

But I am looking forward to the next tutorial!!

There are a few questions in here that I find good to ask and that can cause some debate in the professional world.  I will start off my answering my part to the question why.

Why use Java instead of JavaScript?

Some people will say, “Use Java! ¬†Why? ¬†Because ..¬†white noise………”

I am sure that all of you have heard the “Because it is faster”. ¬†Faster for whom? ¬†The computer? ¬†The difference is negligible. ¬†In a test done by a colleague, iterating over a view with 75,000 documents, touching every one completed only about two seconds faster when done in Java as opposed to JavaScript (14 seconds rather than 16 seconds). ¬†I say, if you are doing something in the real world that needs to touch that many documents and the user is waiting on you, then you are doing something wrong! ¬†I do not care if that is done in JavaScript or Java. ¬†Now, keep in mind that he was doing this for a test and to see if there was a measurable difference. ¬†There was. ¬† We thank him for doing his tests and for sharing the results with us! But to that end, lets make our first point:

Use the correct tool for the correct job!

First off let me say that I find this debate stupid.  It reminds me of the debates that I had to listen my friends engage in regarding their preferences to C# vs Java and Windows vs Linux or Mac.  Every task has its goals, and every goal has its best practice and optimized structure and technology.  If you are working on a project that will be small, used by few, and only requires a few pieces of JavaScript code, than maybe it is best to use pure JavaScript in your implementation.  Likewise, if you are going to be building an application that has code that focuses on customizing the controls, then that too might be best to be done in a pure JavaScript environment.  JavaScript simply is the tool for those jobs.  If you are going to be working on code that needs to be well documented, used by others, maintained by others, or shared between applications or one day may be shared by applications, then Java is the way to go, no doubt about it.  It just is the tool for that job!  Likewise, if you have to build code that handles jobs and working with many documents, then the code does not belong in either of them, but rather run in [scheduled] Agents.*

I know that the separation of Business Logic and UI Logic is another big push the separation of JavaScript and Java.  To that I say bullocks.  Because of the JSF infrastructure and the ability to change existing HTML generation code into actual controls, Java might indeed be the best place to store your code rather than using JavaScript to generate the code for <ComputedField>s set to HTML.  Granted customizing those controls must still be done using JavaScript, but depending on the use case, you might even have some of that logic kept in a Java Object.

Yeah, but, Why Java

Maintainability, Readability, Usability.  There is no better way to put it.

Think back to another Blog Series I did when I discussed the issues I had with debugging JavaScript.  I mentioned that the stupid error

if(apples = oranges) doSomething();

as opposed to:

if(apples == oranges) doSomething();

and that this was an error that should be caught, but never is.  This is my number one reason for pushing for java.  The stupid errors that can cost a great deal of debugging time are caught by the compiler and are easy to fix.  Another case, you have a larger function.  You are dealing with many different kinds of objects, and you accidentally try to set a document object to a documentcollection object.  In JavaScript, you will not discover this error until you run the program and you get an error that states that the desired function is not available, or you end up debugging because it manifested itself in some other way.  In java, a variable declared as a document can only be used for a document.  The error will never happen.  My first reason for pushing for Java in XPages is Usability.  You are not going to have as much code that contain errors and his hidden or uncaught by a compiler.

Another reason why I say usability is improved with java is the tooltips/inteli-sense or whatever else you want to call this feature.  If the javadoc for the API you are using is connected in the build path, you are able to look at detailed information provided by the developers, assuming that they maintained their javadoc well.  This also goes for the javacode that you write.  Of course you have the ability to write and look up comments in SSJS, but they do not show up like they do in Java.  If I am wrong about that please tell me, but I do not believe I am.  In Java, you have the ability to simply use shortcuts to import packages and classes using the inteli-sense, keyboard shortcuts, and see what members and functions are available in those classes whether they are known to designer or not.**  You write a class, that class is known by the inteli-sense. It is that simple.  It may not seem like a lot, but when you can quickly see what code does what, import, and comment all in one place, then why would you not want to?

Readability is also highly improved.  Lets say you have your classes all defined and you are using them.  In JavaScript, you do not have the ability to click on the method being called and have that method opened up in designer, at least not when those functions are defined in two different files.  With Java, this is not an issue at all.  Click on the call, file opens right to the spot in question, time is saved, finish.  The reader is just put into a position where it is efficient to go through your code and figure out what to do.  Another thing: in that same series I linked before, I mentioned that embedded JavaScript function calls are not listed in the outline view.  In Java, this is not the case.  All members, functions and embedded classes and their members are listed in the outline view thus adding to the readability of your code.

Because you are writing your code in a place that makes it readable and because it is in a very usable format that will not require a lot of learning about your code (ie reading your script files to learn how to use it and instead getting the comments via the javadoc and inteli-sense), you are saving time of future programmers who are using your code.  You are also saving yourself time when you need to change something 16 months later and do not remember what you did any longer.  You are also creating something that can be added to later!  Let me explain this.  By saying that, I am not referring to adding some code at some point down the line.  If you want to do that, than JavaScript is completely reasonable.  I am talking about finding out that there are these few classes that you use over and over and over again.  You have to port them into every database you own.  By having these classes in java already, you are in a position where it is not that expensive to port them over into OSGi Libraries that can be put on the server as globally available beans.  If you have them in JavaScript, you also need to translate them.  Furthermore, if you have an HTML generation function that you use for a computed field that displays html code, then it is not so far off to take that code one day and make a real JSF control out of it.  Likewise if you decide to make that code into a control, you can share that control via an OSGi extension.  Overkill?  Nope.  You are simply writing your application in a way that allows for future sustainability.

Why Java?  Not for the negligible speed increase, but for Maintainability, Readability, Usability.

Why a SessionHelper object?

This question refers to a video that I posted as a part of my Java XPage tutorial. ¬†I created a Java object in order to access the session. ¬†First off, I just would like to mention that this is primarily a class to assist other Java classes and not JavaScript. ¬†I most likely would not put this into the faces-config file and register it as a bean, although I have done so in the past. ¬†As the object stands right now, it is merely a list for static methods. ¬†This is a poor candidate for a bean as an instance of the class is not necessary to use its functionality. ¬†Get it when you need it, otherwise leave it. ¬†The only functionality in this particular SessionHelper class that might¬†be helpful down the line in JavaScript is the getODASession(). ¬†Otherwise, if I remember correctly, ODA creates a bean called “openSession” that allows you to access the ODA session object simply in JavaScript without any sort of self made utility¬†class. ¬†Even then, you could always access the ODA Factory utility.

There will be some who will say that my approach to getting a session in an external class is a bad idea.  I can only say to that that I have not had any issues getting the session or the database from other helper objects and methods.  An absolute no-go would be getting the objects under the database object.  Your cleanup would either be messy, or give you NotesExceptions depending on how you went about it.

 Java and Object Retention

Beans and the scoped maps are there for a reason. ¬†Lets assume we have an external database that holds language information: labels, keyword lists and so on. ¬†A typical approach from a few applications that I have taken over require that each form retrieve its own values using @DbLookup to fetch them from the source DB. ¬†In XPages, this is dumb. ¬†Likewise, this would be an asinine thing to do for a computed field or hiddenText field, it would be a horrible idea to put it into the viewScope, a dumb thing for sessionScope, and perfect for an applicationScope Bean which maintains a ¬†HashMap of document labels and keywords based on some key and correctly retrieved by reading out the sessionScope bean that contains the preferred language information for the current user as read from his user document. ¬†By putting it into the applicationScope in a bean you are creating a way to cache your expensive values and provide a way to reset those values at will. ¬†Of course you can do similar things with JavaScript, but you cannot put a JavaScript “object” or function into the scoped maps. ¬†We will be getting into such patterns later on in the tutorial.


As Scotty said in Star Trek V, “How many times do I have to tell you, the right tool for the right job!” ¬†There are times when Java is the right tool, there are times when JavaScript is the right tool. ¬†Do not let yourself be put into the position of thinking that only one option is correct, but keep an¬†open mind and remember that future sustainability is¬†directly influenced on your programming technique and tool decision. ¬†Don’t get caught up in the stupid debate of which is better. ¬†Do not listen to the “java is faster” crap. ¬†The real reasons go much deeper than any of that, and if you are having performance problems, then there are much more likely causes than the language choice.

Java is also the only place where you can define classes for beans to be used with scoped maps.  Otherwise, you are just saving raw variables into your map and cluttering it up.  Use Java to correctly store and access your information so that it can be readily accessed and executed.  I am a strong supporter of Java use in XPage applications.  I hope that this article has helped explain why.


* This is really a case by case decision and must be decided upon specifically when designing the application.
** By “known to designer”, I am referring to basically hard coding the inteli-sense. ¬†I actually do not know how this works and am merely guessing. ¬†Does not matter though.

XPage Java dev Tutorial 1


The time has finally arrived for the first tutorial in XPage Java development.  In this tutorial we will learn how to get a handle on the current session in both the opentNTF Domino API (ODA) and the lotus domino API.  We will briefly go over what we did last time, and we will really hammer out some java code.  Stay tuned for next time when we will actually use Java and Custom controls to log data out to the user/XPage_Admin!!  That tutorial is planned to be given to David Leedy to be shown on NotesIn9!  Please make sure that you take a look at the comments that I added to the code which is displayed below!

Happy Programming!



package com.reederprogramming.utils;


import javax.faces.context.FacesContext;

import org.openntf.domino.utils.Factory;

import com.reederprogramming.exceptions.NullDatabaseException;
import com.reederprogramming.exceptions.NullSessionException;

import lotus.domino.Database;
import lotus.domino.Session;

 * This class is going to contain key methods for dealing with the current session.
 * It implements Serializable in case I want to put this class in the sessionScope later and
 * use from JavaScript as well.  This may not be necessary, but it is easy to implement the interface
 * and take it out later if I need to, or leave it in since it does not hurt anything.
 * Note that all java beans MUST implement Serializable if they are going to be retained in server
 * memory.
 * @see
 * @author
public class SessionHelper implements Serializable {

	private static final long serialVersionUID = 2014071001L; //yyyyMMdd0v
	 * This is an example of how to get the current database using the utility class provided 
	 * by the Extension Libraries.  Alternatively, you could alter the getCurrentSession() to
	 * return the database.  Alternatively, you could also create an enum that includes all of
	 * valid strings and use that to get the object you desire from the VariableResolver.
	 * @return returns an instance of the lotus.domino.Database.
	 * @throws NullDatabaseException thrown when the current database is null.  Should never happen, but
	 * can during multi-threading operations.
	 * @see lotus.domino.Database
	 * com.reederprogramming.exceptions.NullDatabaseException
	public static Database getCurrentDatabase() throws NullDatabaseException{
		Database d  = null;
		d = ExtLibUtil.getCurrentDatabase();
		if(d == null){
			throw new NullDatabaseException("The current database could not be found!");
			/* This is an example of a checked Exception.  It must be handled or else the 
			*  compiler will yell.
		return d;
	 * This method shows two different examples.  The first one is how to get the 
	 * current session and the current database using the Factory enum provided by ODA
	 * @see org.openntf.domino.utils.Factory
	 * @see org.openntf.domino.Database
	 * @see com.reederprogramming.exceptions.NullDatabaseException
	 * @return returns an instance of org.openntf.domino.Database from the ODA.
	 * @throws NullDatabaseException thrown when the current database is null.  Should never happen, but
	 * can during multi-threading operations.
	public static org.openntf.domino.Database getCurrentODADatabase() throws NullDatabaseException{
		org.openntf.domino.Database d = null;
		d = Factory.getSession().getCurrentDatabase();
		if(d == null){
			throw new NullDatabaseException("The current database could not be found!");
		return d;
	 * This method displays a few things.  First off, we see how to check to see if an object is 
	 * the same as another class, and then we perform a cast to a higher level object.  Additionally,
	 * we see how to use the variableResolver to get the session instance.  This will be the same
	 * session object as returned by the session JavaScript keyword variable.
	 * We also see an example of the FIX-ME and TO_DO keywords to aide with development processes.
	 * @see lotus.domino.Session
	 * @see com.reederprogramming.exceptions.NullSessionException
	 * @return returns an instance of the lotus.domino.Session class
	 * @throws NullSessionException
	public static Session getCurrentSession() throws NullSessionException{
		Object o = null;
		Session s = null;
		FacesContext context = FacesContext.getCurrentInstance();
		o = context.getApplication().getVariableResolver().resolveVariable(context, "session");
		if(o instanceof Session){
			s = (Session)o;
		if(s == null){
			//FIXME add logging!!
			//TODO this must be expanded.
			throw new NullSessionException();
		return s;

	 * This is a similar example to the getCurrentDatabase() where we use the Extension Library utility
	 * class to get a handle on the current session.  This assumes that the Extension library is used
	 * and will always be used.  Becauase this is a class that should always be available, such an
	 * approach may not be wise.
	 * @see
	 * @see lotus.domino.Session
	 * @see com.reederprogramming.exceptions.NullSessionException
	 * @return returns an instance of the lotus.domino.Session class.
	 * @throws NullSessionException
	public static Session getCurrentExtLibSession() throws NullSessionException{
		Session s = null;
		s = ExtLibUtil.getCurrentSession();
		if(s == null){
			//FIXME add logging!!
			throw new NullSessionException();
		return s;
	 * This method illustrates how to get a handle on the current session using ODA.  This is only
	 * one possible way.  Furthermore, it shows how to wrap a normal lotus.domino object (they will always extend
	 * lotus.domino.Base) and return an ODA object.  According to one of the authors (Paul Withers), 
	 * it is however preferable to use the Factory.getSession() method.
	 * @see org.openntf.domino.Session
	 * @see com.reederprogramming.exceptions.NullSessionException
	 * @see org.openntf.domino.utils.Factory
	 * @return returns an instance of org.openntf.domino.Session
	 * @throws NullSessionException
	public static org.openntf.domino.Session getCurrentODASession() throws NullSessionException{
		 * if you look at the above method declaration, you will notice that I am 
		 * specifying which Session object should be returned.  This is done because other
		 * methods in this class work with the lotus.domino.Session class. I must insert the full
		 * name (including package) in order to prevent ambiguity.  I can, however, debate if
		 * either of them should be imported, or which one makes more sense to import.
		//TODO change this method to simply use the getSession()  This is only for the sake of example
		org.openntf.domino.Session s = null;
		s = Factory.fromLotus(getCurrentSession(), org.openntf.domino.Session.class, null); 
		 * normally we would have to catch the NullSessionException given by the getCurrentSession().
		 * in this case, it just makes more sense for it to bubble up to the next method and let it deal with it.
		if(s == null){
			//FIXME add logging!!
			throw new NullSessionException("Missing session of type: " + org.openntf.domino.Session.class);
		return s;


package com.reederprogramming.exceptions;

 * This is an Exception class to mark that a session object could not be returned.
 * It can be used for ODA or for lotus.
 * @author
public class NullSessionException extends Exception {
	private static final long serialVersionUID = 2014071001L; //yyyyMMdd0v

	public NullSessionException() {

	public NullSessionException(String arg0) {

	public NullSessionException(Throwable arg0) {

	public NullSessionException(String arg0, Throwable arg1) {
		super(arg0, arg1);



package com.reederprogramming.exceptions;

 * This is an Exception class to mark that a Database object could not be returned.
 * It can be used for ODA or for lotus.
 * @author
public class NullDatabaseException extends Exception {
	private static final long serialVersionUID = 2014071001L; //yyyyMMdd0v

	public NullDatabaseException() {

	public NullDatabaseException(String arg0) {

	public NullDatabaseException(String arg0, Throwable arg1) {
		super(arg0, arg1);

	public NullDatabaseException(Throwable arg0) {


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 “” 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 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:
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!

A few Years of XPage Developement – Part 6


My XPage journey being laid out before you, I now come to a point where I want to say what we need in order to be more productive in XPage development.

  1. We need a centralized help application.  Forums and demos are good, but they are not good for everything.  We need a central place to get information on every JavaScript, java, and control function.  We need a listing of all methods opened by each control, and should not have to search long, for example, to figure out how to get the NoteID of a selected document in a view control.
  2. The IDE must be optimized.  This must be done in a few ways.
    1. JavaScript errors must be found at design time.  This is pointing to my if-statement error again.
    2. Nested functions must also be listed in the left side panel of the SSJS editor.
    3. All functions must be listed alphabetically in the left side panel of the SSJS editor
    4. Better and complete java-doc documentation of all JavaScript and java functions which can be seen in the IDE, including better parameter variable names when selecting function.  (control+space).  arg0, arg1, arg2 is just awful.
    5. While binding fields to a control, the field names must be sorted alphabetically and not randomly.  It would be helpful if this alphabetizing was done ignoring caps.
    6. It would be helpful if field names while binding data were also available when using a separate database as a source.
    7. Adding to point f, it would be nice if fields from a selected list of subforms could also be added to the binding options, and that it would work more like type-ahead.
    8. It should be possible to completely ignore the drag and drop and often buggy nature of the Design panel.  I would request that the source editor be optimized for direct xml input.  See visual studio to see what I am talking about.
  3. For those projects where the customer does not want to install the openNTF Domino API, programmers must fall back on the IBM Domino API.  For this, a must have would be a detailed documentation on the use of the API, when to recycle, when not to recycle, and the design patterns that they see as correct and incorrect.  Most designers are left completely in the dark and set up to fail when it comes to recycling and memory management.
  4. Setting properties for multiple controls in background documents was very easy.  Highlight a few controls, add some code, make a few clicks and done.  The designer/programmer never had to search through the property window long before finding what was needed.  The following are things to consider:
    1. Too many clicks are needed to configure controls on the XPage.  There must be a way to optimize this.
    2. Support for changing the values of multiple values at the same time.
  5. Themes.  You can create your own theme in theory, but a lot of stuff is based on dojo and, most of the time, to get what you want you need to get into the innards of Dojo theming.  In the case of OneUI, you have to first understand how it all works.  There should be better theme development support in designer.  This should include altering the Dojo level themes as well as stuff on OneUI.  Optimize this, and you will increase designer productivity by a lot and make point 4b a lot simpler.
  6. With the openNTF Domino API, this point is moot, but get rid of the NotesException.¬† Completely. It. Must. Go.¬† I need to handle a SecurityException (User does not have sufficient ACL access) differently than a NullDocumentException (document with given key not found in view) and that differently from IllegalStateException (document was removed or recycled). By having one exception for everything and just changing the ‚ÄúText‚ÄĚ variable (an already bad design), the developer cannot really alter the exception handling without parsing the Text first.
  7. Some issues, whether bugs or not, need to be addressed.  They may not be seen as bugs to the creators, but to the end user who only sees something different than what he sees in the client, it is wrong.
    1. Dynamic categorization in views must also be indented.  Building a view navigator is all well and good, but it is not what he sees in the client, and for many customers that is unsatisfactory.  This is true with the dynamicViewPanel, and the ViewPanel controls, and possibly others that I have not tried.
    2. The Calendar control is a nightmare.  It is complex to set up, buggy in IE, and questionable in other browsers.  It needs a major overhaul and fast.
    3.  I am sure I could think of plenty more if I gave myself the time.


XPages are a good idea in theory.  At its core, it offers a relatively easy way to get a Notes Database open to the web quickly while, under many conditions, not sacrificing usability.  It offers solutions to the current Big Data problem where a single Database cannot contain the data it needs to by offering a behind the scenes and invisible way to access numerous databases simultaneously, whether they are Domino, SQL, or a mixture.  The development of applications is a headache at best, and a catastrophe at worst.  XPages show great potential, but lack what I believe to be real support and backing from IBM.  Instead the XPage development community is left to fend for itself.  If we want XPages to succeed in the current market, than it must be able to compete alongside Microsoft Sharepoint, JSF/JSP applications, and other high end platforms.  This includes programmer efficiency, usability, extensibility, lack-of-buggy-ness, and support.  Call me a masochist, but I want XPages to succeed.

A few Years of XPage Developement – Part 5

Fixing River ‚Äď opentNTF Domino API

Introducing ‚ÄúopenNTF Domino API‚ÄĚ

This jewel has been created by a few wonderful developers with tier 5 status, XPage God.¬† (Yes, I skipped Tier 4 for now).¬† Developers with XPage God status are those that can create content that no developer can live without.¬† That content can be pure backend, controls, or both.¬† Up until now, I have only scratched the surface of what this beast can do.¬† Its main draw for me was that recycling is a thing of the past.¬† This was something that should have been done a long time ago by IBM itself.¬† If we do not have to clean up our objects in Lotusscript, why should we have to do so in Java?¬† But that is only the first of many improvements.¬† Iterating through documents in a DocumentCollection has become much simpler.¬† No longer must you use a while loop that quickly turns into an infinite loop that eventually crashes the HTTP task of the server.¬† Additionally, error handling is improved.¬† When an error occurs, the information is saved in files on the server, and if an openLog database is located on the server, the error information is saved there too.¬† No longer must you play with the NotesException class (a horrible invention to say the least, being the only Exception that I know of where the ‚ÄúgetMessage()‚ÄĚ method always returns null and that introduced the .Text public property).¬† The uses for this API are too many to list here.

Since the openNTF Domino API, or ODA as I like to call it, is so important, I have since made it a requirement for hxu version 3.  I have also updated all of my internal databases to incorporate that API.  Once I figured out how to get started with it, using the API is the simplest thing to do.  The methods are almost the same as the IBM Domino API.  The biggest advantages, however, are what to do if you have an issue.  The people who wrote the API are active members of StackOverflow.  If something does not work, you are unsure how to get started, or you get some strange error, write to the original authors via those forums, openNTF, or directly and get help.   Ask for such service from IBM, I dare you.

Future Outlooks

This brings us to the current day and the advent of a Tier 4 XPage developer, ‚ÄúXpage Sith Lord‚ÄĚ.¬† To Understand Lord status, let‚Äôs take a look at the current problem produced by all of my internal databases.¬† So far, I have about 6 internal active XPage applications.¬† This is not including development and QA copies.¬† Each of these applications relies on the hxu jar.¬† Furthermore, key properties are stored in a file under Resources/Files in the database itself.¬† Certain controls and libraries are being copied into each database instance.¬† When hxu changes, all applications implementing hxu must be changed individually.¬† This is starting to become a bit of a hassle.¬† Those with Lord Status no longer write stuff for a single database, but rather create OSGI plug-ins that can be easily installed on the server level affecting all applications which have those marked as required.¬† Controls and libraries need no longer be copied and pasted into new projects, properties can be saved in the file or in the domino notes.ini, and everything can be centrally controlled.¬† I have a long way to go before I can say that I have reached tier 4, but I can say that I recognize the next steps in my progress as a Notes XPage developer.

A few Years of XPage Developement – Part 4

River ‚Äď Customer Project 2

River is a workflow application where department heads can create new personnel requests and have these requests approved for human resources to later create positions for them.  It is the starting point to a much larger group of workflow applications.  It is used worldwide and is comprised of multiple databases and replicas on 15 different servers.  The major push for an XPage implementation was that they would like to get rid of the replicas in order to prevent conflicts.  Another major draw is that the notes client would no longer be needed and the future prospects of having a mobile version for the ease of workflow operations.

The implementation of River went very well.¬† The problems seen during the Solar project were almost completely eliminated.¬† I very quickly developed a few conventions that aided the development and that I will use from now on.¬† It was not until half way through that I found my enemy, the NotesException and his buddy, ‚ÄúThis Object has already been removed or recycled‚ÄĚ.

Let’s get technical for a moment and quickly touch upon a few things that I had no idea of before these lovely issues bared their ugly faces.  Let’s start with a story.  Once upon a time, IBM built Lotus Notes.  They used c++ and built an amazing system to store information in a document and notebook style application and people were (more often than not) happy.  Eventually, IBM decided to give the developers another tool to create agents with and created a Java API.  This API acts as a wrapper for the background C++ objects.  I assume Lotusscript does the same.  The programmer creates a Java object lotus.domino.Database and it points to a c++ object.  One issue however is Garbage Collection.  Using Lotusscript, the developer never has to think about clearing memory.  In java, it is necessary.  For someone who is well versed in java, this is a new concept.  After all, the only time a programmer needs to do that is with NIO and IO objects, (Network) Input Output.  Files, SQL database connections, and streams must always be closed at the end of a function.  When XPages came about many years later, this unintuitive API was still being used.  In my opinion, this was a bad call.   Because XPages is built on Java Server Faces, Java was destined to be a powerful force in XPage development.  Since a lot of developers who had worked with Lotusscript never had any reason to go into Java for most cases, it just became very frustrating.  Many were not just learning a new programming language, but were also trying to get a handle on this terrible API.

If you doubt its horror, take a look at a few use cases.  The user has a document open in an XPage.  This XPage has a function that creates a new document in the background using configured templates located in another database with values located in the current.  This background document is then saved to the user’s mail file and sent to the list of recipients as read from other documents in the same database.  To make matters worse, the XPage application is a dashboard application and all information is saved in other databases.  This is a complicated case, but is not by any stretch of the imagination unusual.  In order to solve this, the programmer makes a managed bean stored in the applicationScope to retrieve the templates from the template database.  It takes certain keywords or variables from the current document, searches for the fitting template, stores the UNID and key in a HashMap, and returns the template.  Everything is recycled and it works well.  The second part of the use case kicks in.  A recipient list is returned in the exact same way as the template.  A search with document keywords is made, the UNID and key are stored in a HashMap for future users, the values are returned, and cleanup is completed.  The source database is also recycled, and right there the problems begin.

The first problem can be solved with a little bit of experience.  In this example we have two different Java Objects: Mailer and RecipientTemplate.  The Mailer has a reference to the source database which is creating the Memo document.  RecipientTemplate also has a reference to the source database where these lists are configured.  The Mailer has created the Memo, retrieved the body template, and, before it is sent, has called the function in another bean to get the recipients.  The next line calls the send method of the memo document object and it fails.  NotesException, object has been removed or recycled.  After banging your head bloody on the desk, screaming so loud that the people in the basement call to ask if you are alright, and a coffee break later, you read this blog entry to figure out what happened.

The session as far as I can tell keeps a mapping of the c++ objects.¬† This mapping works in a few different ways.¬† In this example, the first mapping introduces the problem that the RecipientTemplate and the Mailer ‚ÄúDatabase‚ÄĚ objects point to the same single c++ object.¬† When the RecipentTemplate recycles its Database object, the C++ object is also ripped from the hands of the Mailer object.¬† But, that explains the database, but we are talking about the memo document being gone.¬† There is also a mapping of the objects stemming from the higher level objects.¬† When the database is gone, the documents, and the objects belonging to the documents are also either recycled or are unusable.¬† I am unsure which.¬† ¬†¬†Knowing this, the programmer can move the call to get the recipient list to the very beginning before the memo document is created.¬† The call to the function is successful and you go home happy and feeling accomplished, albeit with a headache and blood stains on your shirt.

The next morning you come in, you proudly test your function again.¬† The mail is sent and you proceed to continue to test your page.¬† You discover a JavaScript error when reading a value from the NotesXspDocument. Since you wrote ‚ÄúxspDoc.getItemValueString(‚Äúfld‚ÄĚ)‚ÄĚ at least ten thousand times by now, you know that it is written correctly, and you test that the xspDoc is null!¬† How in blazes did that happen?¬† Well, you recycled the database in the Mailer function.¬† Because of this, the current document is gone as well.¬† This is a case that is not always true either, as was the case with the River project. When the source databases were on a different server from the dashboard, recycling the database object in the Mailer classes did not influence the NotesXspDocument.¬† This was the case throughout all testing.¬† As soon as the productive system was created and all databases were hosted by the same server, this issue kicked in.¬† The first solution?¬† Delete all calls to recycle the source database because it was just too much trouble.¬† If there was a memory leak, so be it.

Alright, that is not a good solution, so what should be done to fix the issue without risking a server crash?  This was a question that took many hours of research to answer.  I was once again saying that XPages needed to be buried next to Jelly the hamster.  As was with the Solar project, I was frustrated, angry, and just saw no future for XPage development.  How can a framework exist that just introduces more and more problems?  One issue is solved and another shows up.  That is when I found the next little gem released on openNTF.