How does the IDK work?

Last time I promised a more in-depth technical post than my previous ruminations on Ensemble. I'm not one to go back on my word, so I give you my latest airport-delay-inspired technical breakdown... an analysis of the Aqualogic IDK. The point of this exercise will be to show you both how I initially broke down the IDK, and how it functions under the covers. This should, at the very least, make you a hit at most cocktail parties.

What is the IDK?

The IDK/EDK, or whatever else we're calling it these days, is essentially a two headed monster: a method for retrieving information from the portal when a custom application renders a portlet (the IDK portlet API), and an object model for manipulating the portal and its associated services (the PRC or Remote API). In other words, the portlet API is bunch of information about the current state of the portal, and the PRC is a way to change the portal programmatically.

At the end of the day, even though I've broken them down, both of these pieces ride under the auspices of the IDK. For the first part of this article, I'm going to be delve into the portlet portion of the IDK, after which I'll work my way into the operation of the PRC.

How does the IDK work?

In a nutshell, whether you are developing a portlet in .NET or Java, the IDK is simply a set of libraries you can include in your web project. They are either .NET dll's or jar files which use the com.plumtree namespace to expose portal features.

Under the covers, the IDK's operation is actually pretty simple. The IDK portlet API is a set of objects instantiated inside a .NET or Java based page. The objects themselves are constructed using the factory pattern, and are really just wrappers for a typical .NET or Java HTTP request/response object.

The second portion of the IDK (the PRC) is a set of object mappings to web services which are hosted on the portal API server. This is the portion of the product you install which usually has a URL similar to http://localhost:11904/ptapi/services/QueryInterfaceAPI. This URL can be found in the Administrative Utilities | Portal Settings | Portal URL Manager | Soap Server Url portion of the portal. Later, I'll explain a bit more about its configuration and use. Before I get there, let's take a step back and look at how the IDK works under the covers...

Creating a portlet to capture HTTP Headers

One of the first things I did way back when I wanted to see what was going on with the portal, was to create a portlet to display HTTP headers. The IDK itself pretty much uses HTTP headers as its information transfer mechanism, so if you want to see what's really going on, this is a good place to start. For those familiar with web development, the exercise should be pretty elementary. I'm going to go with a .NET example for this particular post. Below, you'll find source for the Page_Load method of my Print.aspx page, which is basically just a header dump to the HTTP response:

private void Page_Load(object sender, System.EventArgs e)
{
	Response.Write("<p><br><i>Last Update: " + DateTime.Now + "</i></p>\r\n");
	Response.Write("<hr>");

	Response.Write("<p><b>HTTP Headers</b></p>\r\n");
	Response.Write("<table style="margin: 6px" cellspacing="1" cellpadding="2" border="1">");
	foreach (string key in this.Request.Headers.AllKeys)
	{
		Response.Write("<tbody><tr>");
		Response.Write(
			"<td style="padding-right: 15px; padding-left: 5px; font-style: italic">"
 + key + "</td><td style="padding-right: 15px; padding-left: 5px">" + 
this.Request.Headers.Get(key) + "</td></tr>\r\n");
	}
	Response.Write("</tbody></table>\r\n");
}

I don't really want to get into portlet setup in this post, since this is an elementary step in the development process, and is covered pretty extensively in the edocs. Basically, though, I created a Remote Server, Web Service and Portlet to point to the Print.aspx page on my laptop. After that I simply added it to a My Page and took a look at the results:

HTTP Headers

Accept	text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Accept-Charset	ISO-8859-1,utf-8;q=0.7,*;q=0.7
Accept-Encoding	gzip
Accept-Language	en-us
Host	localhost:80
Referer	http://localhost/portal/server.pt?in_hi_userid=1&space=MyPage& parentid=0&cached=false&control=SetPage&PageID=0&parentname=Login
User-Agent	Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.4) Gecko/20070515 Firefox/2.0.0.4
CSP-Protocol-Version	1.3
CSP-Can-Set	Gadget-User,User
CSP-Gateway-Specific-Config	PT-User-Name=Administrator,PT-User-ID=1, PT-Stylesheet-URI=http://localhost/imageserver/plumtree/common/public/css/mainstyle2-en.css, PT-Hostpage-URI=http%u003A%u002F%u002Flocalhost%u002Fportal%u002Fserver %u002Ept%u003Fopen%u003Dspace%u0026name %u003DMyPage%u0026id%u003D2%u0026cached%u003Dtrue%u0026in%u005Fhi%u005Fuserid%u003D1%u0026control%u003D SetPage%u0026PageID%u003D222%u0026, PT-Community-ID=0,PT-Gadget-ID=255,PT-Gateway-Version=2.5, PT-Content-Mode=1,PT-Return-URI=http://localhost/portal/server.pt/gateway/PTARGS_16_0_0_0_43/a?b=c& ,PT-Time-Zone=America%u002FNew%u005FYork, PT-Imageserver-URI=http://localhost/imageserver/,PT-User-Charset=UTF-8,PT-Page-ID=222, PT-SOAP-API-URI=http://localhost:11904/ptapi/services/QueryInterfaceAPI, PT-Portal-UUID={5eaaa679853b9ecc-10b9583e62f0},PT-Class-ID=43,PT-Guest-User=0
CSP-Aggregation-Mode	Multiple
CSP-Gateway-Type	Plumtree

There is plenty I could say about the information passing mechanisms between the portal and its remote portlets, but I am going to try to keep my analysis in the context of the IDK. Other details can be left to future posts, or the minds of my readers.

Analyzing IDK Headers

You'll notice a couple of things here, most important of which is the CSP-Gateway-Specific-Config. This header contains most of the settings which are sent to a portlet via the portal. In fact, when you instantiate an instance of the IDK in your portlet, the method calls which retrieve information will usually provide it via this header. Does this mean you could potentially read the information directly out of the header? Of course. Would it be supported by BEA? Of course not. I'd be willing to bet Chris Bucchere is doing something similar with bdg's PHP and Ruby IDKs.

The next thing you can do, to view more information, is to enable advanced features of a web service and see what happens to your portlet headers. For instance, when I turn on Send Login Token to Portlets under the Advanced Settings portion of the Web Service Settings, I see a new header called CSP-Session-Token, which contains an odd sort of token value (which is a Login Token).

In fact, both the login token I mention above, and some of the information in the CSP-Gateway-Specific-Config can be used to manipulate a more advanced feature of the IDK, the PRC. If you're only interested in the IDK portlet API, feel free to tune out here. Otherwise, keep reading...

How does the PRC Work?

When you or your administrator initially configured the portal (install/setup), one of the components which was installed was the portal API server (SOAP server, IDK host, whatever else it may be called). This server is actually just a web services based host for the PRC. The server itself abstracts back-end methods for connecting up to any of the various ALUI products you can manipulate via the IDK (Collaboration, Publisher), as well as a sort of back-end connection for the portal itself.

The server URL is actually configured as I enumerated above, in the administrative settings for the portal. The PRC can then be instantiated in one of two ways:

1. Explicitly starting up a session using your favorite development environment and and the RemoteSessionFactory.getExplicitLoginContext method (see the edocs again)
2. Instantiating a PRC session implicitly, inside a portlet

Creating an explicit session can actually be done from a console application, thick client, or even Windows service. All that is required from any IDK program utilizing the PRC is that it has connectivity to the IDK URL mentioned under the What is the IDK? section of this post.

IDK Authentication

If you utilize the IDK inside your portlets often enough, you'll notice certain methods will throw an exception if you don't configure your web services to pass a login token to your remote portlet (see above). You may also notice these are part of the com.plumtree.prc namespace. What gives?

What's happening is the portal is actually re-authenticating a user when the the PRC is first instantiated. Want to manipulate user/portlet/web service information? Guess what... the portal has to know who you are, and knowing that you're a portlet just isn't good enough (otherwise, anyone could manipulate the portal back end via the API web service).

That's where login tokens come in. They are used to tell the portal your user ID and session expiration time. They're generated by the portal itself, then passed to a remote portlet (you must explicitly tell the portal to pass a login token by configuring a web service's advanced settings). When you execute a method in the PRC, it decodes the login token your portlet passes to it (via the IDK) and makes sure you are authorized to execute that method.

Of course, this adds the extra step of authentication and session instantiation. What this means to you, the portal developer, is that calls become more expensive if you use the PRC.

Performance Considerations

The IDK portlet API (the part of a portlet where you are just requesting information about the user, portlet and environment) requires little overhead from the portal, since as we saw in the header analysis, all of this information is provided to a portlet without any kind of round trip to the API server. Thus, if you expect heavy traffic in your portlets, you would be well advised to stick to header information only (this is where looking at HTTP headers can sometimes pay dividends).

If you want to use the PRC, you should be aware that a separate session is going to be instantiated with the IDK, a session which comes with all of the same baggage as logging into the portal (user login, authentication, etc). Not only that, but if you decide to use a method which is non-native to the portal (anything which uses the search server, collaboration, publisher, etc), then a separate call must be made from the IDK host to the service you are manipulating. Since these services aren't always on the same box as the API server, you could be in for some additional transport overhead.

For instance, let's say you write a portlet that uses the PRC to perform an administrative search for portal users. A typical use case might look something like this:

1. User hits page in portal, request gets sent to your portlet.
2. Your portlet reads HTTP header information to display the user's name back to them in the portal.
3. User types a name to search for and hits the 'Search' button.
4. Your portlet reads the HTTP header to retrieve a login token.
5. Your portlet reads the HTTP header to retrieve the API server URL.
6. Your portlet sends a request to the API server URL to log in using the token.
7. The API server decides whether or not the user who hit your portlet can log in.
8. Your portlet sends a request to the API server to search for a user with the string that was entered in your search box.
9. The API server decides whether or not the user of your portlet can perform administrative searches.
10. The API server sends a search request to the search server using the string passed in.
11. The search server returns the search results to the API server.
12. The API server returns the search results to your portlet.
13. Your portlet returns the search results to the portal.
14. The portal returns your portlet HTML to the user as part of a larger page.

As you can see, there are a lot back-end calls above that are completely abstracted when you utilize the IDK. If you're not aware of what's going on, you can get yourself in a lot of performance related trouble.

The Final Word...

Some of the information I enumerated above is covered pretty extensively in the documentation (see links above), but it's not always clear what is happening or why it is happening. Hopefully, this post will give you a clearer understanding of the under the covers mechanisms that power the IDK, and serve as a useful supplement to the IDK documentation. As always, I am sure there are things I've left out or missed that will be covered in the comments.