Here’s an excerpt:

A New York City subway train holds 1,200 people. This blog was viewed about 4.800 times in 2011. If it were a NYC subway train, it would take about 4 trips to carry that many people.

Click here to see the complete report.

Image via Wikipedia

Article copied from December 2011 Clippings.

**************************************************************
GURU GUIDANCE
**************************************************************

READING AND PARSING AN ATOM FEED
By Julian Robichaux, nsftools.com

In my previous article, I discussed how to read and parse an RSS feed using Java. In that example, we used standard Java classes to load the feed into an XML parser, and the individual elements of the feed that were important got extracted as we went through the feed. In this article, we will use a feed parsing library to simplify the task.

Atom feeds are becoming much more common than RSS feeds “in the wild”, especially because the Atom feed format is often used to provide REST API functionality for publish/subscribe and document-centric types of operations. The Atom format is also more extensible than RSS, and as such it generally has a lot more elements to sort through when you’re retrieving information.

Luckily, there are some feed parsing libraries that can remove a lot of the complexity and guesswork (and RFC reading) for you.

The Two Kinds of Atom Feeds

There are actually two different kinds of Atom feed formats: The Atom Syndication Format (as described by RFC 4287) and the Atom Publishing Protocol (as described by RFC 5023).

The Syndication Format is more of what most people think of when they talk about “feeds” — like an RSS feed, it is used for listing content like news articles, blog entries, etc. The Publishing Protocol is what is used for REST API applications, where document-type data can be listed, added, edited, and deleted.

In general, with a Syndication feed, you simply read the feed data and you’re done with it; with a Publishing feed, you can drill down into the data, first pulling the high-level Service feed, and then pulling child Collection feeds (sometimes several levels deep) to get your data.

Good descriptions of both feed formats can be found at the AtomEnabled.org Web site: http://www.atomenabled.org/developers/syndication and http://atomenabled.org/developers/protocol

Libraries: ROME, Apache Abdera, Apache Wink

The three major Java libraries I’ve found and attempted to use for Atom feed parsing are ROME ( https://rometools.jira.com/wiki/display/ROME/Home ), Apache Abdera ( http://abdera.apache.org ), and Apache Wink ( http://incubator.apache.org/wink ).

ROME and Apache Abdera both seemed to work well with Notes/Domino 8.5, and both were very easy to use. ROME was smaller in terms of the size of the JAR files and required dependencies, while Abdera had more recent updates.

I was able to make Apache Wink work with XPages, but I consistently got errors trying to use it with script libraries and agents. As a result, I will not show code samples for Wink in this article. However, Niklas Heidloff has a good example of using Wink with XPages on the OpenNTF Web site ( http://www.openntf.org/p/XPages%20For%20Connections and http://www.openntf.org/blogs/openntf.nsf/d6plinks/NHEF-8CCDTQ ).

Including the Libraries in Domino

The first thing you have to do (after choosing a library) is decide how to add the library to your Domino server in such a way that your code can use it. Keep in mind that when I talk about a “library” in this sense, it’s not just a single JAR file. Each of the libraries also has other JAR file dependencies you will need to include, as well.

For XPages, this normally means adding the library files to the WebContent/WEB-INF location in your database. Basic instructions for adding a JAR file to the WEB-INF folder and calling the code from an XPage can be found at http://www-10.lotus.com/ldd/ddwiki.nsf/dx/reuse_java_xpage.htm

For agents, you can import the library files into a script library and then include the script library with your agents. However, if you have permissions to do so on the server (or your Admin is nice enough to do this for you), often the best thing to do is to have the Domino server load the library files on startup and retain it in memory. This will generally give you the best performance because the server won’t have to reload the JAR files every time they are needed. Your two options for doing this are to add all the JAR files to your Domino server’s jvm/lib/ext directory, or to put them in an arbitrary directory on the server and use the JavaUserClasses or JavaUserClassesExt notes.ini variables to point to them.

Reading and Parsing a Syndication Feed

With that as an intro, on to the examples! Here is sample code for reading and parsing an Atom Syndication feed using both ROME and Apache Abdera:

ROME
import lotus.domino.*;
import java.net.URL;
import java.util.Iterator;

import com.sun.syndication.feed.synd.SyndEntry;
import com.sun.syndication.feed.synd.SyndFeed;
import com.sun.syndication.io.SyndFeedInput;
import com.sun.syndication.io.XmlReader;

public class JavaAgent extends AgentBase {
   public void NotesMain() {
     try {
         URL feedUrl = new URL( "http://www.nsftools.com/blog/blog.xml" );
         SyndFeedInput input = new SyndFeedInput();
         SyndFeed feed = input.build(new XmlReader(feedUrl));

         Iterator entryIter = feed.getEntries().iterator();
         while (entryIter.hasNext()) {
             SyndEntry entry = (SyndEntry) entryIter.next();
             System.out.println(entry.getTitle());
         }
     } catch(Exception e) {
         e.printStackTrace();
      }
  }
}
 
Abdera
import lotus.domino.*;
import java.net.URL;
import java.util.Iterator;

import org.apache.abdera.Abdera;
import org.apache.abdera.model.Entry;
import org.apache.abdera.model.Feed;
import org.apache.abdera.parser.Parser;

public class JavaAgent extends AgentBase {
   public void NotesMain() {
     try {
         URL feedUrl = new URL( "http://www.nsftools.com/blog/blog.xml" );
         Abdera abdera = new Abdera();
         Parser parser = abdera.getParser();
         org.apache.abdera.model.Document doc = parser.parse(feedUrl.openStream());
         Feed feed = (Feed) doc.getRoot();

         Iterator entryIter = feed.getEntries().iterator();
         while (entryIter.hasNext()) {
             Entry entry = (Entry) entryIter.next();
             System.out.println(entry.getTitle());
         }
     } catch(Exception e) {
         e.printStackTrace();
      }
  }
}

You can see that the code in both examples is structured in much the same way: You generate a Feed object by passing in a URL, and then you can iterate through multiple Entry objects inside the feed. While the examples only demonstrate getting the title of the feeds, there are also methods like getAuthor(), getContent(), etc.

Also, in both cases the HTTP transport layer is handled for you, so you don’t have to worry about the process of actually making the connection to the feed server and retrieving the content.

Reading and Parsing a Publishing Feed

Here is some sample code for reading and parsing an Atom Publishing feed using both ROME and Apache Abdera:

ROME
import lotus.domino.*;
import java.util.Iterator;

import com.sun.syndication.propono.atom.client.AtomClientFactory;
import com.sun.syndication.propono.atom.client.ClientAtomService;
import com.sun.syndication.propono.atom.client.NoAuthStrategy;
import com.sun.syndication.propono.atom.common.AtomService;
import com.sun.syndication.propono.atom.common.Collection;
import com.sun.syndication.propono.atom.common.Workspace;

import lotus.domino.*;

public class JavaAgent extends AgentBase {
   public void NotesMain() {
     try {
         String endpoint = "http://quickr.example.com/dm/atom/introspection";

         // NOTE: the ROME Propono Atom Service parser is VERY picky about namespaces,
         // and if all the nodes in the feed aren't specifically designated as
         // being in the "http://www.w3.org/2007/app" namespace then the feed
         // parsing will fail.
         ClientAtomService service = AtomClientFactory.getAtomService(endpoint, new NoAuthStrategy());
         Workspace workspace = (Workspace)service.getWorkspaces().get(0);

         Iterator collIter = workspace.getCollections().iterator();
         while (collIter.hasNext()) {
             Collection coll = (Collection) collIter.next();
             System.out.println(coll.getTitle());
         }
     } catch(Exception e) {
         e.printStackTrace();
      }
  }
}
 
Abdera
import lotus.domino.*;
import java.net.URL;
import java.util.Iterator;

import org.apache.abdera.Abdera;
import org.apache.abdera.model.Collection;
import org.apache.abdera.model.Service;
import org.apache.abdera.model.Workspace;
import org.apache.abdera.parser.Parser;

public class JavaAgent extends AgentBase {
   public void NotesMain() {
     try {
         Abdera abdera = new Abdera();
         Parser parser = abdera.getParser();
         URL url = new URL( "http://quickr.example.com/dm/atom/introspection" );

         org.apache.abdera.model.Document doc = parser.parse(url.openStream());
         Service service = (Service) doc.getRoot();
         Workspace workspace = (Workspace)service.getWorkspaces().get(0);

         Iterator collIter = workspace.getCollections().iterator();
         while (collIter.hasNext()) {
             Collection coll = (Collection) collIter.next();
             System.out.println(coll.getTitle());
         }
     } catch(Exception e) {
         e.printStackTrace();
      }
  }
}

As before, the process is essentially the same with both libraries — create a Service object from a URL, get the first Workspace in that feed, then iterate through the Collection objects in the Workspace — although with Abdera, the parsing classes are built-in, while with ROME, there is an additional library called “Propono” that also has to be used. You can just include the Propono JAR in the same location that the other ROME-related JARs are stored.

However, I have found the Abdera parser to be much more “forgiving” of the incoming feed format than the ROME parser. As noted in the code above, if the Atom feed doesn’t explicitly use an XML namespace that ROME Propono is looking for, the parsing will fail. I was able to get around this in testing by doing some minor customizations of the ClientAtomService methods, but in practice it’s often easier just to use Apache Abdera.

Authentication

If you have to authenticate with a username and password in order to access a feed, both libraries have support for that as well. Code snippets for how basic authentication works for each library are as follows:

ROME
         HttpURLConnection con = (HttpURLConnection)feedUrl.openConnection();
         String encoding = new sun.misc.BASE64Encoder().
           encode( (username + ":" + password).getBytes() );
         con.setRequestProperty ("Authorization", "Basic " + encoding);

         SyndFeedInput input = new SyndFeedInput();
         SyndFeed feed = input.build(new XmlReader(con));
 
Abdera
         AbderaClient client = new AbderaClient(abdera);
         client.usePreemptiveAuthentication(true);
         client.addCredentials("https://myserver.example.com", null, null,
                 new UsernamePasswordCredentials(username, password));
         AbderaClient.registerTrustManager();         response = client.get(feedUrl);
         org.apache.abdera.model.Document doc = parser.parse(response.getInputStream());

From there, you can plug back into the code from the Syndication examples earlier in this article.

Performance

I didn’t do very much performance testing to compare the two libraries against each other, so I can’t give an opinion on which one is faster than the other. Unscientifically, they both seemed to have similar performance.

The big performance killer is really just loading the libraries in the first place, because it involves loading several megabytes worth of JAR files into memory before the code can even start running. Script libraries performed poorly, while pre-loading the libraries (either on the classpath or on an XPage) made a huge difference.

Of course, this is also a consideration with using a third-party parsing library like ROME or Abdera, versus retrieving and parsing the feed XML manually like we did in the previous article. Certainly, using fewer libraries and fewer levels of abstraction can sometimes improve performance, especially load-time performance . . . but that’s the classic tradeoff between ease-of-coding and raw speed. If we were only worried about speed, we’d still be programming in assembler.

Image by Oldmaison via Flickr

In our 4-day XP852 – Lotus Domino Designer 8.5.2. Basic XPages Applications course we have examples of how to use JavaScript regular expressions in Custom Converters to remove unnecessary spaces and in Custom Validators to validate an e-mail address.

In these regular expression special characters can be used. DevGuru has a web page which explains these characters:

http://www.devguru.com/technologies/ecmascript/quickref/regexp_special_characters.html.

Image via Wikipedia

Martin Meijer heeft bij OpenNTF een Custom Control geplaatst waarmee je een Google Maps positie kunt tonen in XPages. Ziet er zeer gaaf uit:

http://www.openntf.org/Projects/pmt.nsf/ProjectLookup/Google%20Maps%20Custom%20Control

<link rel=”stylesheet” type=”text/css” href=”/domjava/xsp/theme/webstandard/xsp.css”>
<link rel=”stylesheet” type=”text/css” href=”/domjava/xsp/theme/webstandard/xspLTR.css”>
<link rel=”stylesheet” type=”text/css” href=”/domjava/xsp/theme/webstandard/xspIE78.css”>

When you define your own stylesheet for an XPage then still the default ones are loaded. This can cause problems in your application.

How to suppress them?

Jeroen de Boer one of the students of our XPage course came with the next solution:

Define <empty> as default Theme on the XPages tab of the Application Properies.

Want to learn more?

XP852 – Lotus Domino Designer 8.5.2 Basic XPage Application

This post will show you how to display a warning when the user forgets to select a value from the list.

To achieve this you have to change the selector.xsp XPage (discussed in my prevous post) in 4 steps:

1. Add a “requiredValidator” validator to the List Box Control;
2. Define the onclick event of the List Box Control as Partial Update and point to the Link Control;
3. Make the Link type of the Link Control computed;
4. Define some dummy code for the  onclick event of the Link Control.

Step 1

• Open the selector.xsp XPage in the Domino Designer;
• Select the List Control and open the Properties view;
• Select All properties\data\validators -> plus(+)-button and select xp:validateRequired from the list;
• Add a  warning message, e.g. Please select a value from the list.

Step 2

• With the List Control still selected, open the Events view and select the onclick onchange event;
• In de Server Options box select Partial Update;
• Click on the Select Element… button;
• Select link1 from the list and press OK.

Step 3

• Select the Link Control;
• In the Properties view select the Link tab;
• In the Options box change the Link type to Compute value… and add the following Server-Side JavaScript code:

var listBox1:com.ibm.xsp.component.xp.XspSelectManyListbox =
       getComponent("listBox1");
if (listBox1.getValue() == null) {
    return "";
} else {
    return "/xPerson.xsp"; // open person form
}

Step 4

• The Link Control still selected, open the Events view;
• Add the next Server-Side JavaScript dummy code to the onclick event:

var x = null; // somehow you need a statement

Success

More information

XP852 – Lotus Domino Designer 8.5.2 Basic XPage Applications

Related Articles

• Simulation @Prompt with dijit.Dialog (appligate.wordpress.com)
• dijit.Dialog (appligate.wordpress.com)

Using dijit.Dialog in our Disney Employee application

In a recent XPages project we needed to simulate the @Prompt function where the user could select a company from a list before a new XPage contact form was opened. Some essential company data had to be put in corresponding fields on the contact form automatically.

We used the dijit.Dialog widget to simulate more or less the look and feel of the @Prompt function.

How did we achieved this?

Step 1

Create a Notes View (e.g. Companies) consisting of two columns. The first (sorted) column contains the data you want to be displayed in list. The second column contains the return value when the user selects a company, in our case the Document UniqueID. Use the next column formula:

@Text(@DocumentUniqueID)

Step 2

Create an XPage with a View Control containing the contact info.

Add a Button Control to the page to enable the user to add a new contact. Add the following Client-Side JavaScript code to the onclick event:

// URL XPage with the List Box Control
var url = "http://server01/xpages/Test.nsf/selector.xsp";

var dialog = new dijit.Dialog({
 title: "New Contact",
 content: "<iframe src='" + 
        url +
        "' height='250' width='380' frameborder='0' scrolling='no'>",
 style: "width: 400px;"
});
dialog.show();

Modify the XPage properties:

• All properties\basics\resources -> plus(+)-button -> dojoModule\name -> dijit.Dialog

• All properties\dojo\dojoTheme -> true

Step 3

Create a XPage (e.g. selector.xsp) which can be used in the dijit.Dialog box. This XPage contains the next Controls:

• Label Control
• List Box Control (height: 180, width 350)
• Link Control

Label Control: add instructions for the user (e.g. Select a company).

List Box Control: add the next value formula (on the Value tab -> Add Formula Item..):

var columnNbrCompany = 1;
var columnNbrUNID = 2;
@DbColumn(@DbName(), "Companies", columnNbrCompany) + "|" +
        @DbColumn(@DbName(), "Companies", columnNbrUNID);

Link Control: change the label of the link (e.g. Continue) and add the next Server-Side JavaScript code to the onclick onchange event:

var listBox1:com.ibm.xsp.component.xp.XspSelectManyListbox =
         getComponent("listBox1");
sessionScope.put("value", listBox1.getValue());  // store documentUNID

Also change the properties of the Link Control into (Options box of the Link tab):

• Link type: Open Page
• XPage: contact (the XPage contact form, eg. contact.xsp)
• Window behavior (computed): return “_top”;

Step 4

Create the XPages contact form (e.g. contact.xsp). Populate the XPage with the needed fields, including the fields for the company data. Add the next Server-Side JavaScript code to the afterPageLoad event of the XPage.

var value = sessionScope.get("value");  // get documentUniqueId

var doc:NotesDocument = database.getDocumentByUNID(value);  // open the document
var name:string = doc.getItemValueString("Name"); // get the company name
var inputText1:com.ibm.xsp.component.xp.XspInputText =
        getComponent("inputText1"); // create a handle to the control
inputText1.setValue(name); // set the company name

Want to learn more:

XP852 – Lotus Domino Designer 8.5.2 Basic XPage Applications

Related Articles

• Simulation @Prompt with dijit.Dialog – part 2 (appligate.wordpress.com)
• dijit.Dialog (appligate.wordpress.com)

As a solution the dijit.Dialog control can be used.

In the example below the code is placed in the onclick event of a Button Control.  In the code there are two callback function defined who modify the content of a Edit Box Control on the XPage.

In the XPages All Properties:

• basics\resources: define a dojoModule with the name dijit.Dialog

• dojo: define the dojoForm, dojoParseOnLoad and dojoTheme properties as true

You have to replace “PUT HERE AN IFRAME TAG WITH URL TO PDF” by a <iframe>-tag with the next attributes: src=’URL_PDF’, height=’500′, width=’780′ and  frameborder=’0′.

var dialog = new dijit.Dialog({
 title: "Confirmation Notice of Race",
 content: "PUT HERE AN IFRAME TAG WITH URL TO PDF" +
 "<br/><br/><p style='font-weight: bold'>Have you read the NOR and do you agree?</p>" +
 "<input id='b1' type='button' value='Yes' />" +
 "<input id='b2' type='button' value='No' />",
 style: "width: 800px;"
});

dojo.style(dialog.closeButtonNode, "visibility", "hidden");

var handle1 = dojo.connect(dojo.byId("b1"), "onclick", function(){
 // Your Client-side JavaScript code
 dojo.byId("#{id:inputText1}").value = "yes";

 dialog.hide();
 dialog.destroy();
 dojo.disconnect(handle1);
});

var handle2 = dojo.connect(dojo.byId("b2"), "onclick", function(){
 // Your Client-side JavaScript code
 dojo.byId("#{id:inputText1}").value = "no";

 dialog.hide();
 dialog.destroy();
 dojo.disconnect(handle2);
});dialog.show();

Want to learn more:

XP852 – Lotus Domino Designer 8.5.2 Basic XPage Applications

Related Articles

• Simulation @Prompt with dijit.Dialog (appligate.wordpress.com)

Fig 1. Error message is shown when user type wrong Dutch zip code

In our 4-days XPages course we look at the several possible input validation strategies, client-side and server-side.

One of the students, Oscar Bout,  expert on Dojo told me he was missing the client-side Dojo strategy using the dijit.form.ValidationTextBox control in combination with and dojo.form.Form.

We tried his code which gaves the error popup as shown in fig. 1

How to implement this?

1. Select the Edit Box Control and select All Properties\dojo \dojoType and enter dijit.form.ValidationTextBox;
2. Select All Properties \ Dojo \ dojoAttributes and click 3 time on the + button to create three attributes (see fig 2):
   1. Dojo attribute 1: name: invalidMessage, value: your error message
   2. Dojo attribute 2: name: required, value: true
   3. Dojo attribute 3: name: regExp, value (your regular expression to test the input):
      [0-9]{4}[ a-zA-Z][a-zA-Z]{1,2}
3. Select the XPage and select All Properties\dojo and enter the next values (see fig 3):
   1. dojoForm: true
   2. dojoParseOnLoad: false
   3. dojoThemo: true