XPages: Build Project Investigations
One of the first things I do when I install Domino Designer is disable Build Automatically. If you’re not using XPages – or, more importantly, if you’re not working on applications that use XPages – it’s not an issue. However, if you’re working on XPages and either working in a team or may open a database on a production server, then Build Automatically should be switched off. Let me explain why.
Hopefully all XPages developers know that the XPages and Custom Controls visible in the Applications Navigator are not what is actually run on the server. If you look at the Package Explorer, you will see Java files for each XPages or Custom Control under the Local category, as below.
These Java files are human readable code that allows you to see the Java methods and functions compiled from the XPages and Custom Controls. Beneath the Local folder you may also see a folder if you have added proprietary Java code in the traditional manner for managed beans etc. Alternatively, if you have used the new Java design element in 8.5.3, they will appear in the Code/Java area.
However, none of these files are actually executed by the server in an XPages application. The Build process takes those Java files and compile them down to Class files, which are run by the relevant server. These can be seen from the Project Explorer view (note, not Package Explorer). This can be added by going to Window – Show Eclipse Views – Other…. In the resulting dialog box you can type Project Explorer to launch the window. By default Class files are not shown, but by clicking on the Menu icon and selecting Customize View, all restrictions can be unticked to show all files.
Now (you may need to right-click on the window to initialise it) you will see all Projects and all files underneath. If you drill down to WebContent – WEB-INF – classes you can access the Class files created. For any proprietary Java code, those Class files will show under WebContent and the relevant folder.
The Build process creates these files as well as initialising all managed beans. So any user currently using the application will lose any data stored in managed beans. I’ve not verified, but I would expect any XPages would revert to the default state (so values stored in the server map would be lost and pagers would default back to Page 1 etc). More importantly, the application will then be running under the authority of the person who last initiated a build.
So if you don’t have access to run XPages on the production server, when you open a database in Designer will Build Automatically enabled, the application will stop working.
By default, the Build process will build all projects, so if you have opened lots of applications open and you have Build Automatically switched on, it will update all applications you have. This happens every time you save a design element. So Domino Designer performance is impacted and anyone using an application you have open in Designer is impacted.
Consequently, I strongly recommend everyone working on XPages to switch Build Automatically off.
But this has implications. From the Project menu there is an option to Build Project, but there is no shortcut. There is a shortcut Ctrl + B to Build All, but that doesn’t work in the Design pane of an XPage or Custom Control, because it just changes the focussed content to bold! Furthermore, it builds all projects. For this reason and also for Domino Designer performance in general, I would recommend closing applications not being used regularly, but this can only be done out-of-the-box from a view like the Package Explorer view.
But there is another implication of switching off Build Automatically, which is the focus of this article. Namely, if you open a database in Designer, make a change to an XPage, you will usually need to build twice.
From the information that I’ve covered so far, it becomes apparent why this happens. If you open a database in Designer and look at the Package Explorer, you will not see Java files for your XPages and Custom Controls. You will just see an Activator file, like this:
After the first Build, all the XPages and Custom Control Java files will be added, like this:
But if you look at the Project Explorer, you will not be able to find any Class files. All you will see is a Class file for the Activator file, like this:
At this point I find that cached files are used by the server, so I see XPages and Custom Controls as they were when the database was first opened. It is the second Build that creates the class files for the XPages and Custom Controls, like this:
Now the full files show and any changes I had made since opening Domino Designer are available.