Sun IdM, XPress and myself

Lately I’ve been working in a project for a large corporation implementing an identity management solution based on Sun Identity Management 8.0.

As part of the project, we’re doing a lot of customization to the product. A lot of the customization is done because the built in components are in desperate need of adjustments — especially when it comes to the interface (the built in interfaces have probably never even been looked at by interaction designers or graphic designers), but we’re also adding to the existing functionality.

When customizing IdM, you soon realize that writing logic in XPress (Sun’s proprietary XML based programming language) is a painful process.

Although it is simple enough, XPress code is more tedious to write and maintain, and you also loose the benefits of tools such as good editor support and unit testing. Not to speak of the verboseness of XML, and writing an application in an XML-based language.

Nested <cond> tags, complex <rule>s (which could take 10s of lines in XPress compared to a few in Java), and too much logic in your <form>s or <field>s soon turn out to be a real mess. It’s just plain horrible.

I’m sure XPress was, or at least ought to, never have been meant for implementation of complex business logic, and that it might be better suited for simple customizations made by non-programmers. Still, from what I see on the WWW, "complex" logic (at least beyond doing string replacement, simple conditionals, etc.) is often placed in XPress forms and rules.

Unfortunately, there is only little documentation on IdM’s Java API available, though, and the JavaDocs are terrible. Further, the documentation that do exist, is, as is the case with many commercial products, of poor quality. Therefore, you might soon find yourself in XPress hell.

This is why I want to share some of my experiences doing customization to IdM in the Java layer — such as creating custom views, and integrating your Java code with XPress.

Basic Java Calls in XPress

The IdM docs reveals that we can do simple Java calls from XPress by using <invoke> and <new>.

Example:

<defvar name="myDateStr">
    <invoke name="dateToString" class="com.waveset.util.Util">
        <new class="java.util.Date" />
        <s>yyyy-MM-dd</s>
    </invoke>
</defvar>

Compared to Java:

import com.waveset.util.Util;
import java.util.Date;

String myDateStr = Util.dateToString( new Date(), "yyyy-MM-dd" );

Which one looks better?

Of course, this is just the most basic example, and XPress might suffice for this kind of stuff. But if you want to do even slightly more complex stuff, or for example database querying, XPress turns out to be no fun at all.

If you have worked with XPress for more than a couple of weeks you already know this. And that’s why you’ll want to do more of the logic in Java.

Custom View Handlers

As you probebly know, views are an important concept of IdM. When the built in JSPs are loaded, different views are generated in the back end. The views hold variables that are available to XPress forms.

As part of the aforementioned project, we have built reporting functionality that is not part of the product (could not be accomplished with the built in Auditor). As part of this, we insert and fetch records from separate database tables.

Doing all of this in XPress is, if you ask me, a no-no. It is just way too messy and a sure source of bugs.

We still want to use the built in functionality for displaying the data, though, and take advantage of built in validation, etc.

Where to start

What we wanted to do was to use

• XPress for viewing the data
• XPress for <validation>, setting required fields, etc.
• Custom Java code for logic

Since what we’re doing is to extend the product, we also need a custom JSP. Using a custom JSP would have been the most clean way to go if we were to do it all in XPress anyway — instead of using one of the built in JSPs intended to serve a different purpose (loading a completely random view).

To accomplish our goal, what we have to build is therefore as follows:

• A custom XPress form for displaying the data
• A custom JSP
• A custom Form (Java), used by our JSP
• A custom View Handler, for getting, setting, and refreshing the view.

Custom XPress form

Below is an examle of an XPress form that prints out data which has been fetched from an external source and populated into the view by our custom view handler (please pay no attention to the lowercase and invalid XPress tag names — it is just WordPress’ attempt at cleaning up my code):

< ?xml version='1.0' encoding='UTF-8'?>
< !DOCTYPE Configuration PUBLIC 'waveset.dtd' 'waveset.dtd'>
<configuration id='#ID#UserForm:MyCorp-MyCustomForm' name='MyCorp-MyCustomForm'
	wstype='UserForm'>
	<extension>
		<form noDefaultButtons='true'>
			<field>
				<display class="SortingTable">
					<property name="columns">
						<list>
							<s>Role</s>
							<s>System</s>
							<s>Application</s>
						</list>
					</property>
				</display>
				<fieldloop for="role" in="roles[*].name">
					<field name="roles[$(role)].name">
						<display class="Label" />
					</field>
					<field name="roles[$(role)].system">
						<display class="Label" />
					</field>
					<field name="roles[$(role)].application">
						<display class="Label" />
					</field>
				</fieldloop>
			</field>
		</form>
	</extension>
	<memberobjectgroups>
		<objectref type='ObjectGroup' id='#ID#Top' name='Top' />
	</memberobjectgroups>
</configuration>

Custom JSP

The custom JSP used to present our custom XPress form should look like any other IdM JSP. All we want to do, is to use our custom form.The contents of the JSP could therefore look like so:

< %@ include file="../includes/copyright.jsp"%>
< %@ include file="../includes/headStart.jsp"%>
< %@ include file="../includes/headEnd.jsp"%>

<jsp :useBean id="form" scope="page"
	class="com.mycorp.myproj.ui.web.MyCustomForm" />

< %
	try {
		form.setPostURL("custom/myCustom.jsp");
		form.setNextURL("custom/myCustom.jsp");
		form.setCancelURL("custom/myCustom.jsp?newView=true");
		String url = form.process(req);
		if (url != null) {
			LoginHelper.redirect(req, out, url);
			return;
		}
	} catch (Throwable th) {
		form.addError(th.getLocalizedMessage());
%>
< %=com.waveset.util.Util.stackToHtmlComment(th)%>
< %
	}
%>

< %@ include file="../includes/bodyStart.jsp"%>

< %=form.generateHTML()%>

< %@ include file="../includes/bodyEnd.jsp"%>

As you can see, the JSP doesn’t contain much special. The most important part is using a custom Form, or JSP bean (line 5).

Custom Java Form

The custom Java form that we need does not contain much code. It just provides us with the basic functionality for using the custom view:

package com.mycorp.myproj.ui.web;

import com.waveset.ui.util.ViewSource;
import com.waveset.ui.util.GenericViewSource;
import com.waveset.ui.util.GenericEditForm;
import com.waveset.util.WavesetException;

public class MyCustomForm extends GenericEditForm {

	@Override
	public ViewSource createViewSource() throws WavesetException {
		GenericViewSource vs = new GenericViewSource(req);
		vs.setViewId("MyCustom:customView");
		return vs;
	}

}

When this form is loaded, IdM will try to load a view handler named “MyCustomViewer” (based on the part of the view id before the colon + “Viewer”) of package com.waveset.view and assign the ID “customView” to the loaded view. We therefore create a new viewer for this form.

Custom View Handler

The custom view handler is our real hook into Java layer. From here we can manipulate the view and call whatever code we might want to, such as perhaps a Topic Maps engine

package com.waveset.view;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

import com.waveset.object.Form;
import com.waveset.object.GenericObject;
import com.waveset.object.ViewMaster;
import com.waveset.object.WavesetResult;
import com.waveset.util.WavesetException;

/**
 * @author Trond K. Pettersen
 */
public class MyCustomViewer extends AbstractViewHandler {

	// The getView() method should only return a GenericObject
	// which in fact is the view. This is called on the initial
	// loading of our view.
	@Override
	public GenericObject getView(ViewMaster vm, String id, Map options)
			throws WavesetException {
		GenericObject view = new GenericObject();
		view.put("roles", findAllRoles());
		return view;
	}

	// Refreshes the view. This is called if the form is e.g.
	// submitted by the user, or the view for some other reason
	// should be refreshed.
	@Override
	public GenericObject refreshView(ViewMaster vm, GenericObject view,
			Map options) throws WavesetException {

		// We could e.g. refresh the data
		view.put("roles", findAllRoles());

		// We could also do stuff like
		String command = view.getString("display.command");
		if("deleteRole".equals(command)) {
			// deleteRoleByIdOrSomething();
		}

		return view;
	}

	// This is called initially and returns the form associated
	// with this view. The formId is the ID of our custom XPress form
	@Override
	public Form getForm(ViewMaster vm, GenericObject view, String formId,
			Map options) throws WavesetException {
		formId = "MyCorp-MyCustomForm";
		return super.getForm(vm, view, formId, options);
	}

	// We just want to make sure that nothing special happens if
	// the checkinView is called on our view
	@Override
	public WavesetResult checkinView(ViewMaster vm, GenericObject view,
			Map jspOptions) throws WavesetException {
		return new WavesetResult();
	}

	// We just want to make sure that nothing special happens if
	// the checkoutView is called on our view
	@Override
	public GenericObject checkoutView(ViewMaster vm, String id, Map options)
			throws WavesetException {
		return getView(vm, id, options);
	}

	private List<GenericObject> findAllRoles() {
		// Just initialize some test data
		List<GenericObject> roleList = new ArrayList<GenericObject>();
		GenericObject aGenObj = new GenericObject();
		aGenObj.setId("role92001");
		aGenObj.setName("someRole");
		aGenObj.put("application", "someApplication");
		aGenObj.put("system", "someSystem");
		roleList.add(aGenObj);
		return roleList;
	}

}

And voila. We have created a custom form and view handler and can do whatever we want to do in Java

Now tell me you don’t also want to change that interface…

(Since WordPress is such a crappy tool to post <code> from, have a look at the example code).