Configuration in the Registry

The Database Browser Portlet uses an SQL statement and JDBC to create a database browser form inside of a portlet. The browser runs off the Torque connection pools and data sources configured in your Torque.properties file. The standard functionality of the browser doesn't require any coding. The portlet is configured with parameters entered in the portlet registry. The minimal parameters and attributes required are highlighted below:

<portlet-entry name="TutorialCoffeesBrowser" hidden="false" type="ref"   
               parent="DatabaseBrowserPortlet" application="false">
<meta-info>
    <title>Coffees Browser</title>
    <description>Browses Over the Coffees Table</description>
</meta-info>
<parameter name="sql" value="select * from coffees" 
           hidden="false"/>
<parameter name="windowSize" value="15" hidden="false"/>

...

</portlet-entry>

You must derive the portlet-entry from the DatabaseBrowserPortlet, which is deployed with the Jetspeed distribution. This gives you all the base functionality. The sql parameter provides the query string. In our example, the string is not hidden so it can be modified by the user. The windowSize parameter controls how many rows to display in the portlet. That is all you need. The portlet generates the rest for you:

The database browser portlet is a standard Velocity Portlet, and it has an action, template, and customizer template associated with it. This three parameters must be entered. You can select default values or implement your own. In our example, we implement our own action but use the default template and customizer template. You may want to override these to customize the layout of the browser. The default templates can be used as the basis for writing your own templates.

<parameter name="template" value=" database-browser-portlet" 
           hidden="true"/>
<parameter name="customizeTemplate" 
           value="database-browser-customize" hidden="true"/>
<parameter name="action" value="portlets.CoffeesBrowserAction" 
           hidden="true"/>

Our action class extends the default action class to provide the added functionality of refreshing the browser content by passing a query parameter in the URL string. The base class handles everything else. Here we are overriding the standard Velocity Portlet content generation method, buildNormalContext:

protected void buildNormalContext( VelocityPortlet portlet,
                                       Context context,
                                       RunData rundata )
    {
        String refresh = 
            rundata.getParameters().getString(BROWSER_COMMAND);
        if (refresh != null && refresh.equals(BROWSER_REFRESH))
        {
            this.clearDatabaseBrowserIterator(portlet,rundata);
        }
        super.buildNormalContext(portlet, context, rundata);
    }

When we find the refresh command, the browser content is re-queried. By default, the browser will not refresh its content unless explicitly invalidated.

Another useful method to overwrite is the getQueryString() method. The tutorial example does not do so, but here is an example of how it could be done. This method provides you with a way to generate the query string dynamically. It is called whenever the browser is invalidated, and needs to re-query the database in order to generate a new result set.

public String getQueryString(RunData rundata, Context context)
 {
     String sql = null;
     try
     {
            sql = PortletConfigState.getConfigParameter(portlet, 
                                         Constants.SQL_QUERY, null);
            SomeObject so = (SomeObject)
                SessionHelper.getSessionAttribute(rundata, 
                                     Constants.SOME_OBJECT, null);
            if(so == null)
            {
                throw new Exception("Failed to get Object from session");
            }

            List parameters = new ArrayList();
            parameters.add(so.getName());
            parameters.add(so.getCity());
            super.setSQLParameters(parameters);

        }
        catch (Exception e)
        {
            Log.error(e);
        }
        return sql;
    }

Your SQL string in the registry would then need to have JDBC parameters:

<parameter name="sql" 
   value="select name, city, state from people where name=? and city=?" 
    hidden="false"/>