IzPack standalone compiler: Custom langpacks

See my first post for a general introduction.

In this post, I discuss how to include custom langpacks in the installer when using the standalone-compiler.jar.

NOTE: The IzPack documentation talks about custom langpacks and how to reference them in your installation file. However, these langpacks are limited, and do not provide the ability to customize all the text strings used by an IzPack-based installer and uninstaller.

If you use the normal IzPack installation to create your installer, to customize the text strings for a given language, you edit/replace the appropriate XML file under bin/langpacks/installer of the IzPack installation. When creating an installer with IzPack, IzPack copies the files in that location into the the installer jar created, and if an uninstaller is created, they will be included in it also. Which files are copied is based upon the langpack setting(s) in your installation file.

For standalone-compiler.jar usage, all that is required is create the sub-tree bin/langpacks/installer in some directory, and place your customized language files in it.

If you are using the izpack ant task, just include the directory that contains the sub-tree in the classpath when defining the task, and you are good to go. For example:

<taskdef name="izpack"
classname="com.izforge.izpack.ant.IzPackTask">
<classpath>
<pathelement location="${project.build.rc-install}"/>
<pathelement location="${contrib.izpack.dir}/standalone-compiler.jar"/>
</classpath>
</taskdef>

In the above, ${project.build.rc-install} represents the pathname to the directory containing the bin/langpacks/installer sub-tree.

IzPack standalone compiler: Registering custom listeners

IzPack is an open source Java-based software installer. In a project I work on, I use it to create the installer for the project by using the standalone-compiler.jar, and things works pretty good.

One problem though is that for certain customizations tasks, the IzPack documentation is oriented in using an IzPack installation and its tree structure vs standalone-compiler.jar usage. This, post is the start of ways I have found to leverage the customization features of IzPack, but sticking with the standalone-compiler.jar.

Note, I'm working with IzPack 4.3.0, so no guarantees if the methods I describe are applicable to other versions.

In this first post, I figured out how to register a custom listener. In my case, I needed an uninstaller listener. The IzPack documentation for custom action discusses how to implement a listener, but the instructions, and previously noted, is based on working with a regular IzPack installation vs standalone-compiler.jar.

For standalone-compiler.jar, you still need create your listener class, and it must implement the appropriate interface. Since I needed an uninstall listener, I extended com.izforge.izpack.event.SimpleUninstallerListener. For sake of this blog post, my listener class is com.earlhood.izpack.MyUninstallListener.

I compile the class and jar it up in a file called MyInstallListener.jar.

In my IzPack installation file, I add the following tag within the
<listeners> element:

<listener uninstaller="MyUninstallListener"

   jar="${path.to.dir.containing.my.jar}/MyUninstallListener.jar"/>

where ${path.to.dir.containing.my.jar} is the pathname to where the jar file is located.

IMPORTANT: The uninstaller attribute value must be the basename of the class. IzPack scans the jar file to find any .class entry whose basename matches this value. The package name is irrelevant for purposes of IzPack finding the .class file representing the listener.

NOTE: The jar attribute is undocumented. I discovered it when examining the IzPack source.

That is basically it. Of course, I have Ant build scripts to automate the entire build process and use the izpack ant task to create the project installer.

Dynamically changing log4j levels in web application

Log4j is a popular logging library for Java, and I've been using it for many years.

One thing I have found handy, especially with web applications, is the ability to dynamically change the logging level (like to DEBUG) of any category (aka logger) in a running application. I can selectively choose which components I want to change w/o affecting the logging level of other components.

A long time ago, I wrote a servlet to provide this capability, but it requires registering in web.xml and it depends on some utility classes. Although this is generally sufficient, I'm recently working on a project where adding my own custom servlets to the application is awkward, but dropping in a JSP can be done easily. Plus, since servlet engines (e.g. Tomcat) generally support dropping in a JSP at any time, having a JSP allows setting of logging levels w/o having to modify an application's web descriptor.

As a quick hack, I created a JSP version of the servlet, one that is self-contained. The JSP may not be a good example of good JSP coding style since I wanted to spend minimal time in getting things to work. The JSP is self-contained, requiring no external dependencies except log4j.

The JSP can be downloaded from the following location:

http://www.earlhood.com/blogspot/files/log4j.jsp

The interface is simple, but it does the job. When started, it will list out all the logging categories that are currently defined, with each a link to an edit form to change its logging level.

If you need to set the logging level for a category not yet loaded, you can select any other category and then edit the Category field to the category name you desire before submitting the form.

Categories that have their level explicitly set will have the level rendered in bold. Categories that have an inherited value will have the applicable level rendered in italics.

Detecting when DOM node comes into view with Dojo

Working on a project that uses dojo, the need arose to have the ability to automatically be notified when a DOM node comes into view in the browser window. For example, the node may below the fold, and when the page is scrolled, and the node comes into view, the application is notified.

Searching around, I came across this useful post:

http://www.dustindiaz.com/element-scroll-into-view/

However, the code uses YUI, while I needed something that works with dojo (v1.4). Also, what Mr. Diaz provides does not deal with resize events that can cause a node to become visible, or the case when the node is already visible (before any scroll or resize occurs).

So I wrote up a mini-library to provide something that works with dojo. A couple of the utility functions can probably be replaced if using a later version of dojo, but since I needed something to work with dojo 1.4, I could not use newer convenience functions to access window dimensions (like dojo.window.getBox).

Basic usage:

dojo.require('ewh.nodeview');
ewh.nodeview.connect(domNode, func, cdata);

domNode is the DOM node that you want monitored.
func is the function that is called when domNode comes into view.
cdata is an arbitrary object to pass into func when it is called.

Note: Some may say that call-data can be attached to func itself and/or use dojo.hitch(), but I wanted to provide an interface that was friendly to those who may not be familiar with such techniques.

When func is called, it is passed an object. The object contains the following properties:

• node: The DOM node.
  
• cdata: Callback object.
  
• event: Associated event object, which can be undefined.
  

The function is only ever called once. Once called, the internal event hooks are disconnected. If for whatever reason the caller needs to be notified again for the node, they can call the connect method again for it.

Source code:
http://www.earlhood.com/blogspot/files/nodeview.js

Avoiding URL length limits when loading pages with Javascript

Working on a web application that must work with IE, I encountered problems with opening windows (via window.open), or loading content in iframes, that required a large set of parameters to the URL provided. IE has a hard-coded limit on the size of URL strings, so parameter data could get clipped.

Also, it is not pretty to have a large URL string showing in the address bar.

Therefore, the solution was to use an HTTP POST based method.

My first attempt was to use AJAX with a POST request to retrieve the desired page, and then do a document.write() into a blank window. However, I discovered that IE does not process data in a serial manner via document.write(). For example, if the page content contains <script> elements referencing external resources to load, IE will not process those in sequential order, so if you have Javascript code that calls a function that is defined by a previous <script>, you can get a runtime error. IE will load the external javascript resources, but they are done asynchronously, with IE not waiting to execute subsequent Javascript in the page that comes after the <script>.

The solution I came up with is to create a transient page that performs a form post. I.e. In the blank window, I create dynamic HTML page that contains an HTML form with the set of parameter data defined as hidden fields. The HTML page created has an onLoad action to submit the form.

With this approach, the browser is directly fetching the resource, so the document.write() problem described earlier (for IE) is no longer a factor.

What follows is a function for loading a document using a POST-based method:

loadDocument = function(
    /*Object*/args
)
{
  // summary:
  //      Load a document for a given document node.
  // description:
  //      This function uses a POST-style method for loading the
  //      contents of a document node, where the document requested
  //      takes an arbitrary number of request parameters.  This
  //      function works-around limitations of some browsers where
  //      there is a limit to the length of query-string parameters
  //      for GET-based requests.
  //
  // args: Object
  //      Object contain the following properties:
  //
  //      doc: Node
  //            Document node to load content for.
  //      url: String
  //            URL to fetch content from.
  //      params: Object?
  //            Properties of string values representing parameters
  //            for the request denoted by url.
  //      message: String?
  //            Message text (HTML) to display while content is
  //            loading.

  var doc = args.doc;
  doc.open();
  doc.write('<html>');
  doc.write('<script type="text/javascript">');
  doc.write('function submitForm(){document.forms[0].submit();}');
  doc.write('</script>');
  doc.write('<body style="background-color:#FFF;" onLoad="submitForm()">');
  if (args.message) {
    doc.write(args.message);
  }
  doc.write('<form method="post" action="');
  doc.write(args.url);
  doc.write('">');
  if (args.params) {
    for (var p in args.params) {
      var v = args.params[p];
      if (v instanceof Array || typeof v == "array") {
        for (var i=0; i < v.length; ++i) {
          doc.write('<input type="hidden" name="');
          doc.write(p);
          doc.write('" value=\'');
          doc.write(escapeHTML(v[i]));
          doc.write('\'></input>');
        }
      } else {
        doc.write('<input type="hidden" name="');
        doc.write(p);
        doc.write('" value=\'');
        doc.write(escapeHTML(args.params[p]));
        doc.write('\'></input>');
      }
    }
  }
  doc.write('</form></body></html>');
  doc.close();
}

// Helper function to escape HTML specials for use above.
escapeHTML = function(/*String*/s) {
  // summary: Convert HTML special characters to entity references.
  // s: String to escape.
  if (!(typeof s == "string" || s instanceof String)) {
    s = s + ""; // force it to a string
  }
  return s.replace(/&/g, "&amp;")
          .replace(/</g, "&lt;")
          .replace(/>/g, "&gt;")
          .replace(/"/g, "&quot;")
          .replace(/'/g, "&#39;");
}

The primary function works on a Document object, allowing it to not just be used for new windows, but for any object that contains a Document object, like frames and iframes.

Simple example using the above:

var w = window.open("");
loadDocument({
  doc: w.document,
  url: "http://example.com/some/resource/",
  params: {
    p1: "Hello",
    p2: "World!"
  }
  message: 'Loading..."
});

HOW-TO: Posting to Gmail servers with non-SSL/TLS-aware MUAs

I'm a long-time user of the nmh mail user agent (MUA), <http://www.nongnu.org/nmh/>, and its predecessor MH before that.

It's an old MUA. It currently does not support submitting emails to mail servers that require SSL/TLS connections. Other venerable MUAs have the same problem. Fortunately, there is an OSS program that provides proxy capabilities that can negotiate the SSL/TLS part, and if necessary, the SMTP AUTH part if the MUA does not support it: DeleGate, <http://www.delegate.org/>.

DeleGate provides proxy capabilities for various Internet protocols (e.g. http, ftp), but for this article, all we care about is its SMTP capabilities.

Nice thing about DeleGate is you do not need root priviledges to run it. You can have it listen to local client requests on any port you choose and forward the request to remote server (which will be smtp.gmail.com in this article).

Best way to show how to use it is with an example:

The following starts delegated on the local system on port 25 (the standard SMTP port):

delegated -Plocalhost:20025 +=$HOME/delegate/conf/gmail.conf

This says to listen for client requests on port 20025 and to read additional configuration parameters from gmail.conf located under delagate/conf of your home directory (you can specify all parameters on command-line, but that gets kind of ugly). In my gmail.conf file, I have something like the following:

SERVER=smtp://smtp.gmail.com:587
STLS=fsv
AUTHORIZER=-list{localuser:MD5:964ba203464913531aa73b9f774b58f7}
MYAUTH=username@gmail.com:pass:smtp

SERVER specifies what remote server the proxy should connect to. In this case, we specify that is the SMTP server smtp.gmail.com on port 587 (TLS port).

STLS setting specifies that SSL/TLS should be used when connecting to remote server (smtp.gmail.com).

The AUTHORIZER parameter is not required, but if specified, client must (SASL) authenticate to the proxy. The username is "localuser" (change to whatever your want). This may be handy so other users on the local system cannot hijack your proxy server and post email thru your Gmail account. If you are the sole user of your system, client authentication may not be needed. Also, if your MUA does not support SASL, you should not set AUTHORIZER.

To determine if your MUA supports SASL, if your MUA provides the ability to specify an username and password when posting a message to a mail server, it probably supports SASL. If no such capability is provided, it probably does not.

The password listed for AUTHORIZER can be provided in plaintext, but DeleGate will show in its log the MD5 hash of it, which you can then insert into the configuration file. A plaintext version of AUTHORIZER is as follows:

AUTHORIZER=-list{localuser:password}

The MYAUTH specifies the username/password to use for authenticating to the remote server (smtp.gmail.com). This should be set to your gmail address and gmail password. Unfortunately, the password cannot be encrypted since DeleGate needs to send the password to the remote server. Therefore, make sure the configuration file is only readable by you and no one else. For Unix-based users, the chmod command can be used:

chmod 600 gmail.conf

For Windows users, right click on the file and select Properties. Then select the Security tab. Make sure you are the only user that has read access to the file.

With DeleGate running, just configure your MUA to post messages to localhost:2005 and you should be good to go.

NOTES:

If you cannot specify an alternate port number for posting messages, you will need to run DeleGate on port 25. If this is the case, you will need to have admin priviledges to start DeleGate. DeleGate does provide an option for it to drop priviledges to a separate user. See documentation for more details.

DeleGate supports multi-user access, but configuration becomes more complex. If you want to support multi-user access, see the documentation.

For nmh user, SASL is supported, so client-based connections can be restricted, especially if running DeleGate as a personal proxy. However, for nmh, if DeleGate is not running on port 25, the whom command at the "What Now?" will not work. The command will also not work if you enable SASL for client connections. For whom to work, nmh code modifications are required. I've committed changes into the nmh project so SASL support is available for the whom command. You'll need to check out the latest source and build if you need the feature.

Converting XML Catalogs to TR9401 Catalogs

Having worked with SGML/XML for some time now, I still encounter software that does not support XML Catalogs (including software I wrote), but do support TR9401 Catalogs.

Instead of trying to update/modify older software, I found it easy to write an XSLT to convert an XML Catalog into a TR9401 catalog. The XSLT is viewable/downloadable from the following link: xmlcat-to-opencat.xsl

For features supported in XML Catalogs but not in TR9401, the XSLT will print out warnings, but continue processing.

Unsure if anyone else may find the transform useful, but it comes in handy when I need to use my old DTD parsing tools.