XAgent is a term that describes the equivalent of a classic Notes web agent in XPages technology: an XPage is called via URL and produces any kind of data (e.g. HTML, dynamic images, data in JSON format or ODF documents) by sending Strings or even raw bytes directly to the browser.
How to write an XAgent To write an XAgent, you basically need to do two things: first you add the attribute rendered="false" to the xp:view tag of an XPage to prevent the XPages engine from rendering any output. Second, you need to write the code that produces the data and add it to the beforeRenderResponse event of an XPage.
Here are two simple example XAgents. The first one writes XML content to the writer object of the servlet response (which is used to return character data):
<xp:this.beforeRenderResponse>><![CDATA[#{javascript:try { var uName = session.createName(session.getEffectiveUserName()); var exCon = facesContext.getExternalContext(); var response = exCon.getResponse(); var writer = response.getWriter(); response.setContentType("text/xml"); response.setHeader("Cache-Control", "no-cache"); writer.write("<?xml version="1.0" encoding="UTF-8"?>n"); writer.write("<test>Hello "+uName.getAbbreviated()+"</test>"); facesContext.responseComplete(); } catch (e) { _dump(e); }}]]></xp:this.beforeRenderResponse></xp:view>
The second example demonstrates how you can load a file resource from the database design and write it to the output stream object of the servlet response:
<xp:this.beforeRenderResponse><![CDATA[#{javascript:try { var exCon = facesContext.getExternalContext(); var response = exCon.getResponse(); var outStream = response.getOutputStream();
//load a file resource from db design and write it to the output stream var cl=com.ibm.domino.xsp.module.nsf.NotesContext.getCurrent().getModule().getModuleClassLoader(); var buf=new byte[16384]; var len; var filePath="/test/document.docx"; var inStream=cl.getResourceAsStream(filePath); if (inStream==null) { var errMsg="File "+filePath+" not found"; _dump(errMsg); response.sendError(404, errMsg); } else { //set mime type according to file type response.setContentType("application/vnd.openxmlformats-officedocument.wordprocessingml.document"); response.setHeader("Cache-Control", "no-cache"); //send http header with filename (needed so that the browser does not use the XPage's name as filename) response.setHeader("Content-Disposition", 'attachment; filename="document.docx"');
//read bytes from inStream into the buffer while ((len=inStream.read(buf))>-1) { //and write the data to the output stream outStream.write(buf, 0, len); } inStream.close(); outStream.close(); } facesContext.responseComplete(); } catch (e) { _dump(e); }}]]></xp:this.beforeRenderResponse></xp:view>
The loaded file resource must be part of the NSF project's build path to make the XPage code find it (that's where the module classloader is looking for files). Please refer to part two of this XPages series to get more information about how to add a folder to the build path.
If you just want to offer a file for download, developing an XAgent to stream the data would probably be the wrong solution.
In that case, you should add your files to the database design in the Java Perspective of Domino Designer instead and reference them directly in a URL. This is something that is used in the OpenNTF project XPages Mobile Controls to add a newer Dojo version (e.g. 1.6 with advanced mobile device support) to a Domino server than the default one (e.g. version 1.4.3 for Lotus Domino 8.5.2).
But the second code example from above could of course be modified to do something more useful, for example to replace placeholders in the file, create a zip file from multiple files on the fly using Java's ZipOutputStream or render a captcha image for spam protection.
Sounds great? Well, before you start thinking about building large applications based on this approach, you should read on to get to know about it's limitations.
The limitations What I'm going to show you is not only a limitation of XAgents, but of XPages technology in general. For XPages producing the user interface of an application, this limitation may not be critical, but it can become a show stopper for using them the XAgent way.
I've created a small test application with three XPages: Start.xsp, Frame1.xsp and Frame2.xsp (download link). The first one (Start.xsp) contains two iframes and a button. By clicking on the button, the other two XPages are loaded as iframe contents:
var now=new Date(); var nowTime=now.getTime(); var iframe1=document.getElementById("iframe1"); var iframe2=document.getElementById("iframe2"); iframe1.src=document.location.pathname+"/Frame1.xsp?startTime="+nowTime; iframe2.src=document.location.pathname+"/Frame2.xsp?startTime="+nowTime;
Frame1.xsp contains beforeRenderResponse event code that delays the rendering for 5000 milliseconds (java.lang.Thread.sleep(5000)), while Frame2.xsp waits for 2500 milliseconds.
You would expect that both XPages are opened and rendered concurrently. Because of the delay, Frame2.xsp should be visible first, then Frame1.xsp.
Unfortunately, the output looks like this instead (click on the image to open the test application):
Frame1.xsp is displayed first, followed by Frame2.xsp. Frame2.xsp takes about 7600 milliseconds to be rendered, which is the sum of both delays, because the XPages engine does not render multiple XPages in an application at the same time for a single user.
It was a real surprise when we noticed this effect in a customer project. Our UI was based on the Ext JS toolkit which is heavily using REST services to read the UI component data. Our plan was to use XAgents for those REST services, but we quickly noticed that all UI elements only received data one at a time, which was a no-go for the application UI performance. Nothing was loading in parallel.
There are technical reasons for such a restriction, as Philippe Riand, XPages Chief Architect at IBM, explained to me in April 2011. As you may know, the XPages runtime is based on JSF technology, which uses a tree of components on the server side that represents the structure of a web page and its current state. The tree is created/restored when a HTTP request comes in and saved/discarded after it is completed. Unfortunately, this tree does not support being accessed by two concurrent threads, which would break many things like data sources and component states.
To prevent this to happen, XPages synchronizes on the user session object (HttpSession), so that only one thread can access the tree at a time. But by synchronizing on the user session (and not just on the component tree instance), the XPages dev crew also prevented any other XPage in an application from running (the Domino server seems to assign session objects on a per database basis).
The consequence is that you should think twice about your XPages application architecture, if you have many concurrent HTTP requests or if some of them take a lot of time to be processed. An XAgent may be the easiest solution to deploy, but may not produce the best user experience in all cases.
Workarounds and solution There is some hope that the situation will improve in Domino 8.5.3.
As Philippe said, the next XPages engine will be smarter in synchronization and synchronize less than previously. In addition, there will be a new database property called xsp.session.transient. This flag means that unique session objects will be created per request to the server and discarded right after the request ended. This is a first attempt to provide session less mode. If you use this option, then you can create one database with all the services and no synchronization will happen, as each request will have its own session object.
I have requested a more granular option so that you can activate session less mode for single XPages in an application, but I'm not sure if this will make 8.5.3.
For Domino 8.5.2, I can see three things that you can do if you can't live with this performance issue:
1. Move XPages that run for a long time to separate databases This does not help a lot, but if you have an XPages application with an XPage that needs some time to process, you could move it to different database. In that case, the rest of the application would still be responsive, although your long running XPage for example produces a 100 MB log output in XML format that you want to download.
2. Write your own servlet in Java By writing your own servlet as an Eclipse plugin running in Domino 8.5.2's OSGi framework, your code can run without any performance bottleneck caused by synchronization. See this article in the OpenNTF blog for implementation details.
3. There is an app for that :-) As you may know, we have developed XPages2Eclipse, an extensive toolkit for XPages development, which is currently in beta-testing (June 2011). The articles Building servlets in JavaScript and Building servlets in Java demonstrate how you can write your own servlet implementation in JavaScript or Java language. This solution reads all your code from the database design, so that you don't have to deploy every servlet individually. Just install the toolkit on a Domino server once, then you can create any number of servlets by writing code in Domino Designer and replicate them to the server.
My EntwicklerCamp 2013 slides: Dojo 1.8 and AMD (German)
Wed, Mar 13th 2013 8:12a Karsten Lehmann The closing session of EntwicklerCamp 2013 has just finished. Here are the slides for my EntwicklerCamp 2013 session about "Dojo 1.8 and AMD": Download archive: Slides as ZIP-Archive To all English speaking readers: Google Translate is your friend - the slides are in German :-) My plan is to translate them to English though and publish my demos as soon as possible. [read] Keywords: archive
dojo
google
287
Quick tip: Fixing Dojo drag and drop issues in a Windows 8 VMWare on the Mac
Wed, Mar 6th 2013 11:59p Karsten Lehmann I am currently setting up a new dev environment with Windows 8 and Notes/Domino 9 to work on demos for my Dojo 1.8/AMD session at Entwicklercamp next week. To my surprise, I noticed yesterday, that drag and drop operations on Dojo widgets did not work as expected. For example, I could not drag the splitters of a BorderContainer layout widget and the columns of a LazyTreeGrid could not get resized. It seemed as if mouse events got lost, but I only got that effect in Firefox and Chrome. In IE, [read] Keywords: domino
notes
dojo
firefox
mac
vmware
widget
widgets
767
Download links for IBM Connect 2013 session slides
Thu, Jan 31st 2013 7:23a Karsten Lehmann As in previous years, I copied the download URLs of all the already available session slides from the socialbizonline.com website. Unfortunately, a lot of slides are still missing and some are only provided in black and white mode with 2-on-1 page. Use your preferred download manager to download the files. I use DownThemAll for this purpose. You need to be logged in to the website to access the files. Here are the download links: Connect2013_PDFs.html And here is the spreadsheet I u [read] Keywords: ibm
lotusphere
ods
firefox
Session accepted for Entwicklercamp 2013: Dojo 1.8 and AMD
Sun, Sep 30th 2012 1:57p Karsten Lehmann I just received confirmation that my session submission for next years developer conference Entwicklercamp 2013 in Gelsenkirchen (11th - 13th of March) got accepted. The session is about the new Dojo toolkit 1.8 that we have already used in a customer project since its release in August 2012. Sessions at Entwicklercamp are held in German language, so here is the translated abstract and the original one in German. Dojo 1.8 and AMD The session provides an introduction to web application [read] Keywords: application
applications
development
dojo
mobile
New address of Mindoo GmbH in Karlsruhe, Germany
Sat, Jun 30th 2012 6:55a Karsten Lehmann Please note that we have moved. As of 1st of July 2012, our new company address in Karlsruhe, Germany is Mindoo GmbH Heid-und-Neu-Strasse 7 76135 Karlsruhe Germany [read] Keywords:
