Just to head off any technical support requests for Stubby or the Weather Fetcher database, please let me remind you that Lotus Notes agents that call web services from a server require a security access of 2. Allow restricted operations.

This is because they're making network connections, which is a restricted operation. In addition, the person who signs the agent needs to have the following access set on the server document of the server the agent runs on:

• Run unrestricted methods and operations
• Run restricted LotusScript/Java agents

If not, you get errors like:

java.lang.SecurityException: not allowed to make a socket connection to www.foo.com

And don't get me started on the loose naming convention that was used, which allowed "unrestricted" and "restricted" to mean the same thing. I've talked about that already, long ago.

I just posted a slightly updated version of Stubby: the Axis Stub File Generator Database to the OpenNTF site. It's version 1.1. There were no bug fixes, but I did add the following features:

• You can now pass a user name and password to authenticate (for basic authentication) or pass a session cookie (for session-based authentication) when you're calling a web service method. I also provided information on how this works in the example agent code that is generated.

• The Java source files are now zipped up with their directory structure intact, and the zip file stored on the Stubby document. This is convenient if you want to recompile the source files yourself (from scratch).

If you want to do the authentication thing, you'll need to recreate the stub files in the new database first (which should take all of about 5 seconds). I had to hack the service interface class a tiny bit to give you easy access to a method that's available in the stub class that gets generated. Don't ask... just enjoy.

For a little more information on the Stubby database and what it does, please see my previous blog entry about it.

UPDATE: Looks like Phillipe Gauvin described this technique two months ago on his blog. I was scooped again! Nice job, Phillipe.

Yesterday I mentioned how easy it was to use script.aculo.us to create an auto-complete text box on a Domino web page. There's an example in my Weather Fetcher database (the "CityLookupAjax" Page), but if you want the step-by-step instructions, here they are:

1. Download the script.aculo.us library and extract the contents of the zip file to your hard drive.

2. Add the following files as JavaScript Script Libraries in a Lotus Notes database:

• prototype.js (from the /lib folder, all the other files are in the /src folder)
• scriptaculous.js
• builder.js
• controls.js
• dragdrop.js
• effects.js
• slider.js
• unittest.js

For each .js file, you need to create a new JavaScript Script Library, paste the contents of the .js file in, and name the Script Library exactly the same name as the .js file (like "prototype.js").

3. Create a new Page in the database and include the "prototype.js" and "scriptaculous.js" libraries. You can do this by going to the "JS Header" part of the page (a few items below where you set the Window Title), right-clicking in the script area, and choosing "Insert Resource". Here's a screenshot (click it to see the full-size image):

4. Add the following style definitions to the "HTML Head Content" section of the page:

"
<style>
    body {
      font-family: Verdana, Geneva, Arial, sans-serif;
      font-size: 0.9em;
    }
    div.autocomplete {
      position:absolute;
      width:250px;
      background-color:white;
      border:1px solid #888;
      margin:0px;
      padding:0px;
    }
    div.autocomplete ul {
      list-style-type:none;
      margin:0px;
      padding:0px;
    }
    div.autocomplete ul li.selected { 
      background-color: #ffb;
    }
    div.autocomplete ul li {
      list-style-type:none;
      display:block;
      margin:0;
      padding:2px;
      height:1.2em;
      cursor:pointer;
    }
    div.autocomplete span.informal {
      display: none;
    }
</style>
"

You can paste it in just like that, with quotation marks and everything (that way it's a valid Formula language string).

5. Add the following text on the Page, as Pass-Through HTML:

Lookup: <input type="text" id="lookupField" name="lookupField" size="50"/>
<div id="lookupDiv" class="autocomplete"/>
<script type="text/javascript">
new Ajax.Autocompleter("lookupField", "lookupDiv", "LookupAgent?OpenAgent", {
    paramName: "lookupval"
    });
</script>

So you have a text input field called "lookupField", with a div called "lookupDiv" that will display the auto-complete results, and you're creating an Ajax.Autocompleter that will listen on that field and call an agent called "LookupAgent" to get the values that will be displayed for the auto-completer.

You could do this with a regular field on a Form too, just set the HTML ID property on the field and paste the div and script parts afterwards. Please note that you have to put the "new Ajax.Autocompleter" line AFTER the lookup field on the page/form.

6. Save and close the Page, because you're done with that. Create a LotusScript agent called "LookupAgent" that looks something like this:

Sub Initialize
	Dim session As New NotesSession
	Dim doc As NotesDocument
	Dim q As String, qArray As Variant
	Dim decodeVal As Variant
	Dim fieldName As String
	Dim lookupVal As String
	
	'** get the request (HTTP POST request)
	Set doc = session.DocumentContext
	q = doc.Request_Content(0)
	qArray = Split(q, "&")
	fieldName = "lookupval"
	
	Forall stuff In qArray
		decodeVal = Evaluate(|@URLDecode("Domino";"| & _
		stuff & |")|)
		
		If (Instr(1, decodeVal(0), fieldName, 5) = 1) Then
			lookupVal = Strright(decodeVal(0), fieldName & "=")
		End If
	End Forall
	
	'** find the matches
	Dim db As NotesDatabase
	Dim view As NotesView
	Dim vc As NotesViewEntryCollection
	Dim ve As NotesViewEntry
	Dim returnString As String
	
	Set db = session.CurrentDatabase
	Set view = db.GetView("MyLookupView")  '** MODIFY THIS
	Set vc = view.GetAllEntriesByKey(lookupVal, False)
	Set ve = vc.GetFirstEntry
	
	Do Until (ve Is Nothing)
		returnString = returnString & "<li>" & _
		ve.ColumnValues(0) & "</li>"
		Set ve = vc.GetNextEntry(ve)
	Loop
	
	'** return a <ul> list, which is what script.aculo.us wants
	returnString = "<ul>" & returnString & "</ul>"
	
	Print |Content-Type: text/plain|
	Print |Cache-Control: private|
	Print ||
	Print returnString
End Sub

The agent is a little bit long, but not really complicated. It gets the value entered in our lookup field (passed as an HTTP POST parameter called "lookupval", as defined in the Ajax.Autocompleter params), looks the value up in a view, and returns the results as a <ul> list, which is what script.aculo.us is expecting.

Ideally you would do lookups against a static list rather than hitting a view each time, but this should be okay for a small view.

In any case, now you're done! Open your Page as a web page and watch the Ajax goodness. It should look something like this:

UPDATE #2: Phillipe Gauvin just added a comment with another nice way to work with HTTP POST data:

• Instead of calling an agent, make a URL call to create a document with ?CreateDocument
• The "LookupVal" field on the form will contain the lookup value that is being passed
• The other field on the form should have a computed value of something like this:

val := @DbLookup("":"nocache"; "";"myview"; lookupVal; 1);
@If(@IsError(val); ""; "<ul>" + @Implode("<li>" + val + "</li>") + "</ul>")



• You can also set a $SaveOptions field of "0" to not save the new document

I haven't tried this before, but I'd guess you also have to hide everything but the computed field, have the form set to "Content Type: HTML" or "Content Type: Other", and allow anonymous users to create new documents. I won't know until I've played around with it. Pretty interesting technique.

technorati tag: Show-n-tell thursday, SnTT

So, I've been tinkering a little more with the Weather Fetcher database and I ended up with:

• a few updates to the zip code list
• a sample web page that uses script.aculo.us (and therefore prototype.js) to do cool things like auto-complete a city name lookup field and dynamically update a div using AJAX
• code for an example Sametime bot to do weather lookups from Sametime (attached to the "About" page -- unfortunately, I had nothing to test it against, so I'm not sure that it actually works)

I'm only just now starting to play around with script.aculo.us, and I couldn't believe how easy it was to add to a Domino web page. Just include the JavaScript libraries, add some CSS styles, and do a tiny amount of code and... whoomp, there it is! See the "CityLookupAjax" page in the Weather Fetcher database to see what I did.

BTW, the download link for the Weather Fetcher database is the same -- WeatherFetcher.zip -- but the file has been updated (so if you downloaded before, you'll have to do it again).

And yes, the download is still 19 MB. Sorry it's so big, but it has over 42,000 US zip codes in 5 indexed views, and all that ends up taking some space. It's worth it though, trust me...
;-)

technorati tag: Show-n-tell thursday, SnTT

I'll be the first to admit that I have not and probably will not have a chance to look at this, but it's pretty amazing stuff to me anyway. Sun has released the OpenSSO Project as free, open source software. From the home page:

The Open Web SSO project (OpenSSO) provides core identity services to simplify the implementation of transparent single sign-on (SSO) as a security component in a network infrastructure. OpenSSO provides the foundation for integrating diverse web applications that might typically operate against a disparate set of identity repositories and are hosted on a variety of platforms such as web and application servers.

It's amazing to me because this kind of enterprisey software is traditionally so expensive and so complex. And if nothing else, what other open source projects have this kind of documentation?

via Simon Phipps

As I mentioned in our last podcast, I developed an example application that uses code from my new Stubby database. It started off simple, and then... well, it was hard to know when to stop. Anyway, here's the database:

Weather Fetcher: use web services to get the current weather

It's a 19MB download, so plan accordingly.

I started off with the stub files I generated from Stubby, based on the NOAA web service. Then I wrote some classes to interpret the information that came back from the service (it was raw XML, not a complex class like you'd expect), and wrote an LS2J class to access all that information.

It ended up being pretty cool. As an example, on my local copy of the database if I go to my browser and point to the URL http://localhost/WeatherFetcher.nsf/GetWeatherHTML?OpenAgent&zip=32256 , I get:

The agent is all LotusScript, even though it's using Java and web services in the background. There's also an example of using it in the front-end, to prompt a user for a zip code and return weather information in a messagebox.

Anyway, download and enjoy. Remember that it's Notes 7 only though...

I just realized today that you can use XPath statements in Notes 7 (using Java, not LotusScript). For example:

import org.w3c.dom.*;
import javax.xml.parsers.*;
import java.io.*;
import org.apache.xpath.*;

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
factory.setValidating(false);
org.w3c.dom.Document domDoc = factory.newDocumentBuilder().parse(
	new ByteArrayInputStream(xmlString.getBytes()));
Node n = XPathAPI.selectSingleNode(domDoc, "//temp[@type='max']/value");

Nice! That saves all sorts of work when you're parsing XML, once you get the hang of it (and admittedly, I still haven't got the hang of it). For a couple of reference links, Jake Howlett talked about XPath and JavaScript a while back, and there are some nice examples on the Java Developers Almanac (as always).

I just created a new project on the OpenNTF site:

Stubby - The Apache Axis stub file generator for Lotus Notes

This database is meant to help you create Apache Axis "stub" files that can be used to call web services from a Lotus Notes client or server. The files that are produced here can be used in Lotus Notes/Domino 7 with NO modifications to the client or server, and NO external library dependencies. I even have an LS2J example agent that uses LotusScript to call a web service, using the generated files.

All you have to do is create a new Stub Doc in the database, enter the URL of the WSDL file you want to make stubs for, and click the "Generate Stub Files" button. Everything you need to start writing an agent will be generated for you!

The magic that happens when you click the "Generate Stub Files" button is mainly controlled by the "StubGenerator" script library. The methods in this library will:

• Read and parse the WSDL file
• Generate stub files (Java source files) in a temporary directory
• Compile those stub files into java class files
• Package the class files up into a JAR file
• Generate sample agent code based on the stub files

The normal course of action after doing all this (it's all done with the single button click) is to create a new Java agent, paste the sample code into it, and use the "Edit Project" button in the agent to attach the JAR file. You now have a working agent that can call a web service!

As a visual, here's a screenshot of a document in the database after you've clicked the "Generate Stub Files" button (click the image for a full-size picture -- sorry for the huge graphic... there are several tabs):

There are several example agents in the database to help you get started.

And in related news, Joachim Dagerot just wrote a great developerWorks article about using Apache Axis to call web services from Notes: Consuming Web services from a Lotus Domino Java agent. His technique involves generating the stub files manually and adding the Axis library as an external reference (whereas the Stubby database uses the built-in Notes Axis libraries), and it's really good material.

It's very possible that this has been discussed elsewhere (maybe over at Mikkel's site), but I didn't see any references to this problem in a Google or Notes.net search, so here you go.

I'm playing around with some Java code right now, and I put a Java JAR file in a Lotus Notes script library so I could easily reference it from multiple agents. Nothing fancy, I just opened the library, did an "Edit Project", and attached the JAR file. Then I saved and closed the script library -- I've done all this many, many times before.

However, when I opened my agent and tried to reference the new script library, it wouldn't "stick". I would click "Edit Project", switch to "Shared Java Libraries", choose the script library and click "Add/Replace Files". Everything looked like it worked, but if I clicked "OK" and then went back to "Edit Project", the script library was no longer listed on the right-hand side as a resource. I could choose it again, and add/replace it again, but it kept disappearing. I was unable to reference it in the agent.

I also noticed that the script library didn't have a little icon next to the name, like all the other script libraries did. For example, see this screenshot:

You see how the "test 1.0" script library on the left-hand side doesn't have an icon? I can "Add/Replace" it as much as I want and it won't stay referenced in the agent.

After a lot of trial and error, I found out that it wasn't the contents of the script library that was the problem (my original assumption). It was the NAME. This unfortunate bit of functionality will happen with any Java script library that has a period in the name. Like "1.0". Somehow that little dot is messing things up.

All I had to do was rename the script library (to "test" or "test 1_0" or something with no period) and everything was fine again.

This happened to me on the Notes 6.5 and the Notes 7.0 clients. And no, I don't have any PMR's I can use to officially report this problem to IBM, but if someone else wants to it would probably be a good idea.

For anyone who thought that Quickplace was a lost technology, fear no more. Bruce and I recently recorded a podcast interview with Satwik Seshasai and Rob Novak talking about Quickplace 8.0. Coming soon to servers near you...

UPDATE: Stu Downs wrote a nice review (with good bullet points)

I'm not sure if the IBM Business Partner promotion to migrate customers to Linux is still going on or not, but even if it's not this should be helpful.

Someone posted a Quickstart guide for installing Domino 7 on SLES 9 on the Novell site, complete with screenshots for every single thing you have to do to get Domino up and running. It even has a solution to a "bindsock" issue that a lot of people seem to have (see the very end of the article). Very good information on installing the server from start to finish.

Anyway, even though I'm a pretty loyal Ubuntu user, I also really like SUSE. I think it has a very nice interface, it's possibly the easiest operating system install in the world, and YaST rocks.

From the IBM/Domino standpoint, SUSE is a good bet too. As reported recently in DominoPower, Lenovo will soon be pre-loading SLED 10 on Thinkpads. In addition (as I've mentioned before, IBM has a special relationship with Novell. In an interview with Jack Messman a few years ago, we learned this:

Q: So how did you wind up buying SUSE?

A: We entered into negotiations in October 2003. There was an auction and the price got up to $210 million, which was quite high for a company doing $40 million in revenue. We felt that was a high price and we wanted some support. We had $750 million in the bank, so we didn’t need cash. We wanted a show of support that our purchase of SUSE was seen as a strong, viable option by the industry. And our friends at IBM stepped up. They agreed to make a $50 million investment in Novell as a sign of their support for this concept and to give us the encouragement to go ahead and make the deal. It was a good investment for IBM. They invested $50 million on a handshake, and then in January that $50 million of stock was worth $75 million. That’s the history of the relationship.

Which makes me feel good about the fact that IBM will be likely to continue to provide "first class" support for SUSE Linux on its product lines.

Here are some screenshots from my install of the Lotus Notes Client on Linux on a CentOS virtual machine -- should be the same instructions for RHEL4:

** Installing the Lotus Notes 7.01 Linux Client **

As vowe already pointed out, it wasn't as easy as double-clicking an install file and letting it run (or installing an RPM or DEB package), but as long as I followed the instructions it went pretty smoothly.

I haven't done any real stress testing of the client so far, so don't ask me about that yet.
;-)