7.3 Bowstreet Portlet Factory for WebSphere

---

7.3 Bowstreet Portlet Factory for WebSphere

Overview

Bowstreet Portlet Factory for WebSphere is a framework and set of tools for rapidly creating and maintaining customized portlets for the WebSphere Portal environment. With Portlet Factory, developers build portlets by pulling together a sequence of reusable software components called Builders. Developers assemble Builders into models. These models are then executed at runtime to dynamically generate application code. The code generated includes JSPs, Java classes, XML documents, and all of the low-level artifacts required to create a portlet application. Thus, developers can capture and automate the process of building portlets instead of explicitly coding each portlet.

Bowstreet Portlet Factory for WebSphere comes with the Lotus Collaboration Extension. This is a set of builders (that is, tools) that assist the developer in building portlets to access Domino applications.

Bowstreet Portlet Factory is not targeted exclusively to Domino developers. In addition to the Lotus Collaboration extension, it includes a large number of tools for accessing relational databases, building stand-alone applications, and so forth.

A key strength of this tool is that it does not completely insulate a developer from the J2EE framework. If a specific task is not possible with the tools provided, a Java developer can code a method or class in Java and include this code in the Bowstreet development environment.

A detailed knowledge of Java and J2EE is not a requirement. However, Bowstreet Portlet Factory is very J2EE-centric. A basic understanding of Java and J2EE technologies will greatly increase a developer's productivity with these tools.

Bowstreet provides developers with:

• Ability to leverage existing Domino applications

• Ability to more easily create of custom portlets

• Robust personalization and customization capabilities

• Simplified portlet-to-portlet communication

• Categorization and search

• Many single sign-on options

• People awareness

Bowstreet development tool

Bowstreet Portlet Factory has a WebSphere Studio plug-in, Bowstreet Designer, used for creating, viewing, and running portlets. Bowstreet Designer plugs into the Eclipse and WebSphere Workbench IDEs.

Portlets created with the Bowstreet Portlet Factory follow a standard J2EE model-view-controller design. In order to simplify the task of writing custom portlet Java and JSP code, Bowstreet introduces the developer to a few key objects used to create a portlet application.

Builder

A builder is the core building block that automates design and development tasks performed by developers. Simply put, a builder is a collection of Java classes and XML documents that represent a specific pattern or high-level component of a Web application. A builder provides a wizard-like UI for gathering configuration information from the developer, as well as the code for rendering the pattern or context-aware elements within the Web application.

A simple builder might add a button to a JSP page, while another might render a Domino view. Builders can analyze the application and perform tasks in the context of what previous builders have created. For example, a "page navigation control" builder could reference a set of JSP pages and create a set of navigational controls relevant to the context of those pages. If a page changes, then the navigational controls update automatically in a ripple effect that can cascade through the entire application.

Model

A model is a sequenced collection of builders that generate the application components representing the behavior, structure, data, and presentation of the portlet application. Underneath the covers, a model is simply an XML file containing a series of calls to builders.

Each model can be turned into a portlet, or can be run as a stand-alone J2EE application.

Profile

A profile contains a set of inputs that vary the way a portlet behaves. Profile settings can be edited after a portlet is deployed by clicking the configuration icon for the portlet. A profile feeds values into builders based on user identity or other contextual information (such as day of the week). Using profiles, you can automatically generate different variations of a generic portlet (from the same model) for different users or situations.

Configurable profiles are very easy to implement with Bowstreet Portlet Factory.

Regeneration

When a model is regenerated, each builder in the model executes in sequence and creates pieces of your portlet, such as JSP pages or Java methods. During regeneration, profiles can feed different inputs to builders based on the user or situation, automatically creating custom portlets "on the fly."

There is a negligible performance hit associated with regeneration; less than 1% of the total processing resources in a typical "regen-enabled" execution environment are spent performing regeneration. This is because generated objects are cached at optimal levels of granularity, as are sessions. Furthermore, it's possible to break a model into a hierarchy of components, whereby models are selectively regenerated.

WebApp

The WebApp is a profile-specific instance of a portlet application that is dynamically created by the factory regeneration engine. Each builder, when called during regeneration, creates objects that get woven into the portlet application, such as pages, buttons, variables, or methods. The regeneration engine creates the WebApp by combining the regeneration of a model with a unique instance of profile data. The WebApp objects are then processed by the factory's execution engine to instantiate the executable J2EE application sessions.

Bowstreet server components

Portlets created with Bowstreet Designer plug in to the WebSphere Portal and application server. The Portlet Factory's Automation Engine leverages WebSphere's HTTP stack as well as all of the services from WebSphere Application Server and WebSphere Portal, such as clustering, failover, J2EE security, and session management.

Bowstreet Portlet Factory integrates with the WebSphere Portal via the Bowstreet Portlet Adapter WAR. This is a standard WPS portlet WAR that includes the portlet factory classes (JAR files). When a request comes in from the portal, the Bowstreet Adapter Portlet class calls in to the portlet factory code at the layer below the servlet layer (the WebAppRunner class). Note that this WAR file is deployed into WebSphere Portal only once, eliminating the need to re-deploy a WAR with every iteration or variation.

Figure 7-16 on page 375 illustrates the code execution architecture.

Figure 7-16: Bowstreet Portlet Factory for WebSphere code execution architecture

Implementation issues

• Applicable portlet patterns

  Bowstreet Portlet Factory is capable of implementing all four portlet patterns:

  • Link

  • Display

  • Integrated

  • Migrated

• Development time

  Moderate.

  Development time can be significantly less than developing an application from scratch using the JSP and Java options, especially once developers become experienced with the Bowstreet development tools at their disposal.

  Certain types of portlets require less time to create than others. For example, view navigation, document display (without rich text), and click to action functionality are significantly easier to develop with Bowstreet Portlet Factory.

  Other functionality, such as document creation and editing, can be more challenging, especially when input validation, input translation, computed fields, or dynamic keyword values are involved.

• Developer skill set

  In addition to learning the Bowstreet development tools and techniques, a developer should have good understanding of Domino, HTML, and JavaScript development. While not required, a solid understanding of Java, JSPs, and portal technologies is very beneficial when using some of the more advanced builder configuration options, or when implementing a task not easily performed by an available builder.

• Range of applications

  Bowstreet offers a powerful set of builders for developing a rich portal interface with a high level of functionality. A great number of builders are available and more are being made available with each release. High-level builder functionality can be customized using a wide variety of configuration settings and by adding lower-level builders to your model.

  In the event that a builder is not available to provide specific functionality, it is possible to write a custom builder, or add a builder that supports custom Java code. Both of these options, of course, require Java development skills and significantly more development time.

• Rich text handling

  At the time of this writing, rich text fields cannot be viewed or edited using the forms generated by Bowstreet Portlet Factory.

  Note that it is possible to configure the Bowstreet Domino view builder to open documents in a new browser window. Using this option, documents will be rendered using Domino's HTTP engine and can therefore leverage all of the Web-based rich text functionality provided by Domino.

Performance

Bowstreet has done extensive performance testing on portlets created with the Bowstreet Portlet Factory for WebSphere. The benchmark they made concludes that the Bowstreet Portlet Factory provides all the benefits of rapid creation of portlets without sacrificing performance. The portlets that the portlet factory generates exhibit performance characteristics (throughput, response time, and CPU utilization) that are highly comparable to traditional hand-coded portlets. Contact Bowstreet to obtain detailed information about performance.

Currently no metrics are available on performance related to portlets accessing Domino data. As with all integration techniques, performance testing is recommended before deploying a portal application using Bowstreet Portlet Factory.

• Session management

  Bowstreet Portlet Factory can implement session pooling for connecting to Domino servers. This will significantly increase the scalability of Domino portal applications.

  Note that the session pooling option can be used only when "Use regen credentials" is specified as the runtime credentials for connecting to Domino.

• Clustering

  Bowstreet Portlet Factory does not natively support server fail-over in a clustered Domino environment.

• Requires single sign-on

  Bowstreet supports a wide range of single sign-on options. It can be configured to use LPTA or the Credentials Vault. Also, by configuring a Bowstreet portlet with a valid Domino username and password, it can allow users to connect with Domino servers that do not support SSO.

Required software versions

• Lotus Domino 5.0.10 or later or 6.0 or later

• WebSphere Portal v4.1, 4.2 or WebSphere Portal Express 4.1

• Bowstreet Portlet Factory for WebSphere v5.6+

• Bowstreet Portlet Factory Lotus Collaboration Extension

Note 

People Awareness requires WebSphere Portal Extend.

7.3.1 Implementation details

At a high level, development consists of three main steps:

1. Develop the model.

2. Test the model.

3. Deploy and test the model as a portlet.

Developing the model primarily involves adding and configuring builders. It may also involve the development of custom builders, or the insertion of custom Java code into a builder supporting this action.

Launching the Bowstreet Designer client

After installing and configuring a Bowstreet development environment, all development is performed within the Bowstreet Designer. The Bowstreet Designer client is contained within the WebSphere Studio Application Developer client.

To launch the Bowstreet Designer, open the WebSphere Studio Application Developer and select Bowstreet → New Model or Bowstreet → Open Model.

Figure 7-17: Launching the Bowstreet Designer from WebSphere Studio

Creating a new model

Use the following steps to create a new model:

1. After selecting Bowstreet→ New Model, you are prompted to select the type of model to create. For Domino Portlets, it is generally best to start with an Empty model (Figure 7-18).

   
   Figure 7-18: Creating a new Bowstreet model- Selecting model type

2. When prompted, enter a model file name and file path. It is best to keep related models in a common subdirectory.

   
   Figure 7-19: Creating a new Bowstreet model- Saving .model file

Once you have created your model file, you are ready to begin adding and configuring builders.

Adding the Domino View & Form builder

Bowstreet provides a great number of builders, each with a very wide range of available configuration options. When building a Domino portlet, you will generally start by adding the Domino View & Form builder and then refine this builder's functionality with other builders.

1. To add the Domino View & Form builder (or any other builder) select Model → Add Builder Call.

   
   Figure 7-20: Adding a Bowstreet builder to a model file

2. From the Bowstreet Builder Palette window, select All → Domino View & Form.

   Note 

   The Domino View & Form builder type will only be available after you have successfully installed the Lotus Collaboration Extension pack.

   
   Figure 7-21: Bowstreet Builder Palette window

3. After clicking OK, you will be given the Domino View & Form builder configuration interface (Figures 7-18 and 7-19).

   
   Figure 7-22: Bowstreet Domino View & Form Builder- Configuration window part 1

   
   Figure 7-23: Bowstreet Domino View & Form Builder- Configuration window part 2

   Note 

   It is important to verify that the HTTP and DIIOP tasks are running on the targeted Domino Server. You should also verify that the user id & password used has permissions to run Java agents on this server (see the server document in the server's Domino Directory (names.nsf)), and that the id has the appropriate access level to the database being accessed.

4. All settings for the Domino View & Form builder are controlled from this window. The configuration options available include:

   • Domino server, database, view, and form to use with this model

   • Authentication method (passed ID and password, LTPA, credentials vault)

   • Interface options:

     • View options (search, category selection, and so forth)

     • Document link method (no link, new window, create integrated form)

     • Document viewing, creation, edit, and deletion options

   • Many other options

5. Once configuration is complete, click OK. You will be taken back to the model and should notice that Java code has been generated based on the builder you have configured.

Figure 7-24: Java code generated from the Bowstreet Domino View & Form builder

It is possible to change the settings in the Domino View & Form builder configuration window (or any other builder's configuration window) at any time simply by double-clicking the builder name listed in the left-most window of the model interface.

Testing a Bowstreet Model

It is possible to easily test this model directly from the Bowstreet Designer client. To test a model simply click the Run Model icon in the top left corner of the Bowstreet model interface.

Figure 7-25: Test run of a model based on the Bowstreet Domino View & Form builder

Running a model from the Bowstreet Designer makes it very easy iteratively to add or configure a builder, and then quickly test the changes to confirm the change had the intended effect.

This action will test most aspects of the application with a few exceptions, such as Click to Action, which must be tested from within WebSphere Portal.

Deploying a Bowstreet Model as a Portlet

Turning a Bowstreet Model into a portlet is a fairly straightforward task. Simply add and configure the WPS Portlet Adapter builder to your model. For instructions on adding a builder to a model, see "Adding the Domino View & Form builder" on page 379.

Figure 7-26 lists the configuration options for the WPS portlet adapter builder.

Figure 7-26: Bowstreet WPS Portlet Adapter builder configuration window

Once you have added this builder, you are ready to deploy your model as a WebSphere Portlet. You should find this to be quite simple. All Bowstreet portlets are actually concrete portlets referencing a single abstract portlet. The difference between portlets is simply the model the concrete portlet references.

The easiest way to create a new concrete instance of a Bowstreet portlet is to use the Bowstreet Portlet Creator portlet. This portlet works in much the same way as the Web Clipping portlet configuration tool. It provides a simple interface to create and configure each concrete Bowstreet portlet.

To use the Bowstreet Portlet Creator, log in to the WebSphere Portal where Bowstreet Portlet Factory is installed. Open a page containing the Bowstreet Portlet Creator portlet. If no page contains this portlet, simply create a new page and add this portlet.

From within the Bowstreet Portlet Creator, you can create a portlet based on your newly created model.

Figure 7-27: Bowstreet Portlet Creator portlet

After you have created your new portlet, simply add it to a page. It will look and function in much the same way as it did in your test environment.

It is also possible to package a Bowstreet portlet as a WAR which can run on any WebSphere Portal server, even if Bowstreet Portlet factory has not been installed. This process requires that you be familiar with the Jakarta ANT package, an open-source application used for building WAR files.

Implementing communication between Bowstreet models

When implementing Click to Action, one portlet (for example, model) is the event listener and another portlet triggers this event.

Note 

Because Bowstreet uses the standard WebSphere Portal Messaging API (like Click to Action), it is possible to implement a non-Bowstreet portlet that triggers a Bowstreet event listener. It is also possible to trigger an event in a non-Bowstreet portlet.

Implementing a communication listener

In the Bowstreet model that will be an event listener, add and configure the WPS Event Declaration and Event Handler builders.

Figure 7-28: Bowstreet WPS Event Declaration builder configuration window

Figure 7-29: Bowstreet Event Handler builder configuration window

In the Event Handler builder, you must specify an Action to be called when this event is triggered. You can select an Action generated by the Domino View & Form builder, or you can use parameters passed by the event trigger and chain a series of Actions together by adding and configuring an Action List builder.

Figure 7-30: Bowstreet Action List builder configuration window

Implementing a Click to Action trigger

To trigger a Click to Action event from a Bowstreet portlet, add and configure the Link builder. Make sure the Action Type setting is set to "Link to an Action."

Figure 7-31: Bowstreet Link builder configuration window

You will also need to add and configure an Action List builder to define the action called by the Link builder. The Action List builder can trigger one or more events, and pass any number of required parameters, based on which link was selected.

Figure 7-32: Bowstreet Action List builder configuration window

7.3.2 Implementation example

With the assistance of a Bowstreet expert, we implemented the Sales Tracking application case study introduced earlier. Within a day we had developed a fully functional portal workspace, complete with a Click to Action interface between portlets.

Figure 7-33: Bowstreet implementation of Sales Tracking case study

We created four models to implement this portal workspace, one for each portlet:

1. Customers view

2. Customer profile

3. Customer contacts

4. Sales activities

With each model, we started with the Domino View and Form builder, which generated a simple Notes view and form interface. We then configured the Domino View and Form builder and added additional builders to refine the interface and add functionality such as Click to Action.

Bowstreet's model-builder development technique requires some time to get used to. However, with a little bit of effort it ultimately proved very effective in developing our desired portal application. The ease with which we implemented the challenging functionality of Click to Action across multiple portlets was impressive.

There were a few spots where we added straight Java code. For example, we used a custom Java method to grab values from the product view for use in selection fields.

The following four tables summarize the builders used to generate our portal application. Some of these builders required detailed configuration that has not been captured in these tables.

Table 7-1: Customer profile

Builder Used	Description
Domino View & Form	Creates the base Domino form & view model: Customers\by Customer number, Customer form
WPS Event Declaration	Defines a Click to Action event within this portlet for triggering the action to open a customer profile document
Event Handler	Maps the event to the action, opens a customer profile document based on UNID
WPS Portlet Adapter	Turns this model into a portletl
Action List	Opens the "blank" startup page
Data Field Modifier	Hides the $$return field
Variable	Declares a "customer Selected" variable and sets to false
Visibility Setter	Hides the Domino view for this portlet
Action List	Creates the action of opening a page by UNID
Page	Declares the "blank" startup page
Visibility Setter	Hides the "back" button from customer documents, preventing the view from opening in this portlet
Domino View	Declares the sales people\by employee number view
Data Field Modifier	Modified employee_number field behavior in edit mode

Table 7-2: Customers

Builder used	Description
Domino View & Form	Creates the base Domino form & view model: Customers by Name view, Customer form
WPS Event Declaration	Defines a Click to Action event within this portlet for triggering the action to open a profile document by UNID
Link	Called when user selects a customer, triggers the action list, which triggers three Click to Action events
WPS Portlet Adapter	Turns this model into a portlet
Data Column Modifier	Sales Activity Name view, Adjust the tables, alignment, order, ordering and visibility of the view columns created by initial port of the Domino view
WPS Event Declaration	Declares a Click to Action event to handle when a customer name is selected
Action List	Triggers three Click to Action events, one in each of the other three portlets

Table 7-3: Customer contacts

Builder used	Description
Domino View & Form	Creates the base Domino form & view model: Customer Contacts\by Customer Name, Customer Contact form
WPS Portlet Adapter	Turns this model into a portlet
Data Column Modifier	Customer Contact form page: Adjust the labels, alignment, order, sorting, and visibility of fields created by the initial port of the form
Visibility Setter	Hide Employer column in view when employer category is selected
Visibility Setter	Hide system-generated edit button in the view interface
Visibility Setter	Hide system-generated delete Button in the view interface.
Data Column Modifier	Customer Contacts\by Customer Name view, Adjust the labels, alignment, order, ordering and visibility of the view columns crated by initial port of the Domino view
Action List	Set up an action instructing the portlet how to filter documents by a customer number
WPS Event Declaration	Defines a Click to Action event within this portlet for triggering the action to filter documents by customer name
Event Handler	Maps the event to the action, the event is triggered, the action is executed.

Table 7-4: Sales activities

Builder used	Description
Domino View & Form	Creates the base Domino form & view model: Sales Activity\by Customer view, Sales Activity form
WPS Portlet Adapter	Turns this model into a portlet
Data Column Modifier	Sales Activity Name view, Adjust the labels, alignment, order, ordering, and visibility of the view columns created by initial port of the Domino view
Data Column Modifier	Sales Activity formAdjust the labels, alignment, order, ordering and visibility of the view columns created by initial port of the form
Domino View	Products by Name View, used to look up product name values from the products database
Method	Write a custom Java method to access the product name values
Data Field Modifier	Creates drop-down list entries product selection fields
Variable	Creates a Java variable
Action List	Set up an action instructing the portlet how to filter documents by a customer number
WPS Event Declaration	Defines an Click to Action event within this portlet for triggering the action to filter documents by customer name
Event Handler	Maps the event to the action; when the event is triggered, the action is executed
Data Page Formatter	Formats the date created field

---