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.
Nathan T. Freeman pointed out another good reason for turning off Build Automatically. Suppose two developers are working on local replicas, with an XPage that contains Custom Control A that contains Custom Control B. Developer 1 makes a change to Custom Control A and builds, then replicates up. Developer 2 makes a change to Custom Control B and builds. This also builds Custom Control A and when he / she replicates, Developer 1’s changes are lost. This is a good reason not only for turning off Build Automatically, but also using some kind of Source Control!
Nathan also pointed me towards Project – Properties and Builders section. There an XSP Builder and a Java Builder. Sometimes I’m seeing XSP Builder before Java Builder, sometimes after.
I’ve also found that if I open Designer afresh and open a database, only the activator gets built. If I immediately only another database, again, just the activator gets built. Only after I’ve done a build in Designer – of any database – then when I open a database, everything gets built. More testing to follow…
You can change the ctrl + B shortcut to e.g. ctrl + shift + B (see designer preferences). This works everywhere. Don’t know why it’s ctrl + B by default.
Last week I gone crazy during a XPages application release. Few XPage design elements were not opening in the browser. The error message read – “Item not found exception” (as if a field is missing if it were in classic domino). I tried the project clean which is supposed to build from scratch discarding any previous class files. That did not resolve the problem. Then I checked for the java files of these XPages/Custom Controls. The .java files of the XPages those were not opening in browser had weird name (suffixed with UNID of the design note). I manually deleted those .java files and did a new build. That finally fixed the problem.
This is a nice article and thanks for explaining well. However one thing I wanted to say, I have the build automatically turned off. And I never had to build twice except the last week (as explained above). I usually keep only one database open in designer and do the Ctrl+B
The Project Explorer view didn’t show the .class files (I tried all different customize options). But I figured the Navigator view displays the .class files (WebContentWEB-INFClasses)
There are quite a few filters applied by default, so types that are hidden. Deselecting *.class resources alone doesn’t make the class files appear. I think it’s the Local types option that is needed as well.
Thanks for explaining the double build. Up until reading this I doubted myself when I didn’t see the changed I just made.
Do you know if “Build Project” helps in preventing Designer building all opened databases?
Build Project should only build the current project. I haven’t worked out how to add a quick shortcut for this yet though.
You can add a shortcut from Designer’s Preferences, search for “Keys” in the left pane and “Build Project” in the right.
Regarding adding shortcut for “Build Project”, that only seems to work when you have focus on the Package Explorer pane. So it’s not very convenient.
Another good reason to turn Build Automatically off. You may not know all dependencies of an application until you open it. If you open up an application that requires the Extension Library, some other library or Java files, you may break the application! https://www.intec.co.uk/when-xpages-dont-work-why-do-i-see-ssjs/
I’ve worked out some more on the vagaries of Build. If you open a database in Designer, make a change to an XPage or Custom Control, then build, it only does an incremental build and builds the changed design elements into the Local folder. You need to build again to do a full build to include design elements for the whole NSF in the Local folder, so have a full set of files required by the XSP Command Manager and so see the changes in the browser.
This correlates with Build Automatically, which runs the full build on the whole database as soon as Designer is opened, so the build after changing a design element (the incremental build) means the changes show immediately.
Thank you for the valuable information. Can you give me some insights on what’s the difference between ‘Project Clean’ and ‘Project Build’
In LotusScript terms, think of ‘Project Build’ as like saving a Script Library or Agent. ‘Project Clean’ is then like ‘Recompile All LotusScript’.
Thanks much !
Clean–recompiles/builds all the design elements ? & build– Just recompiles/builds just the modified ones ?
It’s a standard Eclipse function, but it looks like the actions depend on the builders in use http://stackoverflow.com/questions/4549161/function-of-project-clean-in-eclipse. If you look at Project > Properties, then the Builders option in that dialog, there are builders for a lot of elements, including the LotusScript Editor. But most are XPages ones. I think only the XPages ones interpret the clean command. It’s worth remembering that those get compiled down to .java files and from there to .class files, which is what the XPages runtime actually uses. I think Clean basically discards all .class files and recreates them.
Thank you for explanation. Quite helpful !!
I follow Protecting Xpages Application as suggested in http://www.wissel.net/blog/d6plinks/SHWL-99W7MJ (Wissel,net). Do all steps with ANT run (buld.xml). The result is to get a jar file which can be seen custom control classes locating in xsp package folder after building path (classpath). And their xsp-config files are in WebContent/WEB-INF. When I try to run an xPage and get the error “HTTP Code: 500. If I add some custom control.xsp files in the same folder as their xsp-config files, it works. I’m not sure the jar that can’t be found or maybe the “composite-file” property in the xsp-config file points to the wrong file or class. (/customcontrol name.xsp). Please kindly help if any idea.
If it’s throwing an Error 500, the message on the server should point to the log files that will give you more information. The key to being able to use this approach is likely to be knowing how the compiled Java files used by the XPages runtime for each custom control is bound to the relevant xsp-config. But since I’ve never used the approach and I don’t see a use case for me or any of our mentoring package customers needing it in the upcoming future, it’s not something I’m going to investigate. Almost certainly, though, dropping the jar file into an NSF will need an HTTP restart before any changes can be picked up.
Hi Mr. Paul Withers, I verified 2 errors from 2 log files (Notes & Web) as you suggested with the following. 1. It throws an Error: 404 NOT FOUND (Server could not find the given resource) if I remove a jar from bin (I think xsp-config points correctly each). 2. It throws an Error: 500 INTERNAL ERROR (The server could not fulfill the request because of an unexpected condition) if I import a jar in bin back. I’m not sure about any classes in the jar whether are proper or not. Or any other causes please kindly suggest.
As mentioned, it’s not something I have a need to investigate. I’d recommend posting to StackOverflow. But first, error 500 is usually immediately followed by a message pointing the developer to another log file. If that’s there, do so before posting to StackOverflow. If it’s not, paste a screenshot of the console messages to StackOverflow or responses will tell you to look to that log.
Thank a lot.