ImagoX Extensions Design Notes 

Within each XSL transform it is possible to define extension elements. This is a standard mechanism for extending the functionality of the Xalan transformer and is documented there. For our purposes the extension author writes a standard extension element. The only differences are that by calling:

    context.getTransformer().getParameter( org.xenei.imago.Defaults.IMAGO_DATA )

the extension method can access the ImagoData object, and by calling:

    context.getTransformer().getParameter( org.xenei.imago.Defaults.IMAGO_FILTER )

the method can access the current Imago filter.

The ImagoData object contains all the standard servlet-accessable objects (e.g. HttpServletRequest, HttpServletResponse, HttpSession, etc.). In addition many of the Imago services are also available (e.g. getRawDocument(), getProcessedDocument(), newDocument(), etc.). The ImagoFilter controls any caching functionality. An example of a simple extension element is provided below. Note that all extension elements must have the two parameters in the order listed. The return type may be any Java object however best results are seen when the objects are limited to String, DocumentFragment, int, double, float, or void.

/**
* Returns one of the servlet request parameter values.
*
* The 'item' attribute specifies which parameter value to return.
* If the item attribute is null or the parameter value specified by the
* item attribute is not found a null is returned.
*
* If the returned value is non-null the XeneiFilter is set to dynamic
* thus these requests are not cached and subsequent stylesheet transforms
* will not be cached either.
*
* @return java.lang.String
* @param context org.apache.xalan.extensions.XSLProcessorContext
* @param element org.apache.xalan.templates.ElemLiteralResult
*/
public String parameter(
    org.apache.xalan.extensions.XSLProcessorContext context,
    org.apache.xalan.templates.ElemExtensionCall element)
    throws javax.xml.transform.TransformerException {
    // the return value
    String value = null;
    // get the ImagoData
    ImagoData data = (ImagoData) context.getTransformer().getParameter(
        org.xenei.imago.Defaults.IMAGO_DATA);
    // make sure we are running under Imago
    if (data != null)
    {
        HttpServletRequest req = data.getHttpServletRequest();
        if (req != null)
        {
            // get the "Item" attribute of the "parameter" element
            // <parameter item="x"/>
            String item =
                element.getAttribute(
                    "item",
                    context.getContextNode(),
                    context.getTransformer());

            if (item != null)
            {
                value = req.getParameter(item);
                ((ImagoFilter)context.getTransformer().getParameter(
                    org.xenei.imago.Defaults.IMAGO_FILTER
                    )).setDynamic( true );
            }
        }
    }
    return value;
}

Extension elements may be derived from org.xenei.imago.extensions.ImagoExtension to get access to a numer of convenience methods. In the above example:

    ImagoData data = (ImagoData) context.getTransformer().getParameter(
        org.xenei.imago.Defaults.IMAGO_DATA);

would be replaced by:

    ImagoData data = getImagoData( context );

and:

    ((ImagoFilter)context.getTransformer().getParameter(
        org.xenei.imago.Defaults.IMAGO_FILTER)).setDynamic( true );

would be replaced by:

    setDynamic( true );

There are several static methods in ImagoExtension that could be used without deriving from it.


Go to Imago Design Notes.