IBM Web Experience Factory 8: A developer's

perspective

Deepak Gupta (Deepak.Gupta@in.ibm.com), IBM

June 2012

Copyright International Business Machines Corporation 2012. All rights reserved.

Summary: Understand the key concepts of the IBM Web Experience Factory 8 tool, key
capabilities, and benefits over conventional portlet development tools, and learn how to leverage
them in developing portlet applications.

Table of Contents
1 Overview...................................................................................................................................2
1.2 Capabilities of WEF...........................................................................................................2
2 WEF architecture and key concepts..........................................................................................2
2.1 Models...............................................................................................................................3
2.2 Profiles..............................................................................................................................6
2.3 Builders.............................................................................................................................6
2.3.1 Builder types..............................................................................................................6
2.3.2 Key components of Builders......................................................................................7
2.3.3 Features of Builders...................................................................................................9
3 WEF application framework....................................................................................................10
4 Creating a WEF Project..........................................................................................................10
4.1 Create the Run Configuration and test the sample Model...............................................16
5 Creating a Hello World portlet using WEF...............................................................................20
5.1 Create a basic Model.......................................................................................................20
5.2 Add a Text Builder Call to the Model................................................................................25
5.3 Test the Model using standalone application server........................................................28
5.4 Test the Model on the WebSphere Portal Framework......................................................29
6 WEF Web application directory structure................................................................................30
7 Dynamic profiling with WEF....................................................................................................39
8 Custom Builder in WEF...........................................................................................................42
8.1 Creating a custom Builder using WEF.............................................................................43
9 Key points about WEF development.......................................................................................47
10 Comparing WEF with conventional portlet development.......................................................48
11 Troubleshooting, debugging, and error handling...................................................................49
12 Conclusion............................................................................................................................49
13 Resources.............................................................................................................................49
14 About the author....................................................................................................................50

1
1 Overview
IBM Web Experience Factory (formerly named IBM WebSphere Portlet Factory) is a
powerful and flexible tool for an Eclipse-based integrated development environment (IDE) that
facilitates the building of portlet applications, JavaTM 2 Platform Enterprise Edition (J2EE)
applications, and widgets. It allows for the creation of portlets on top of a service-oriented
architecture (SOA) without the need to write any code.

Web Experience Factory (hereafter called WEF) facilitates a Rapid Application Development
environment by automatically generating the code for your application. It creates Web
applications into portlet-enabled applications with a click of a button and, by eliminating the need
to code, WEF simplifies development, deployment, and change management.

The advantage of using WEF for developing portlets is that they can be tested on an application
server without IBM WebSphere Portal Server. The portlets work exactly the same standalone as
they do inside a WebSphere Portal environment.

1.2 Capabilities of WEF

The capabilities of WEF include:

Reduced need for hand coding, hence faster development times and reduced application
delivery time.
Supports SOA.
Automatically generates application code using best practices and standards.
Multi-page custom portlets without coding.
Robust integration capabilities with enterprise applications and data.
Automatic integration with WebSphere Portal.
Automation of frequently occurring development tasks.
Native integration with WebSphere Portal Server.
Dedicated portlet development environment.

2 WEF architecture and key concepts

WEF is based on a three-tier architecture:

Data source
Services and portlets
WebSphere Portal Server Framework

WEF applications consist of three main building blocks: Models, Profiles, and Builders (see
figure 1). Builders can be thought of as wizard/form interfaces that expect some input and
automatically generate JavaTM code for it. Builders can have profiled inputs for generating
multiple variants of the application from the same code base.

Models act as a container for Builders, and a series of Builders defines the application behavior.
An application can include more than one Model, and each Model can have an integration of
multiple Builders.

2
 Figure 1. WEF building blocks

2.1 Models
Models are basically a collection of Builder calls that generate the application components
implementing the behavior, structure, data, and presentation of the application. These are stored
as XML files, thus making them portable and easily distributable. Basically, a Model is a
blueprint for an application.

A Model acts like a use case of a project such as a portlet, a flow of navigation between different
pages, or related services (see listing 1). A Model can be invoked via the following ways:

URL. Every model in WPF has a URL, which can be invoked by a user request.
Default Builder. Every Model includes a default Builder that launches a set of actions when
the model is invoked.
Events. A Model also reacts to events such as portlet events, asynchronous events, etc.

Listing 1. Model file explaining various elements

<Model id = "test/Date">

<BuilderCallList> <!--it lists all builders, called for this model -->

<BuilderCall id = "actionListBuilder"> <!-- actionListBuilder definition

-->

<BuilderDefID>com.bowstreet.builders.webapp.ActionListBuilder</BuilderDefID>
<Inputs>
<Input name = "Name">main</Input>
<Input name = "Actions">
<Actions>
<Action>

3
 <ActionType>Page</ActionType>
<ActionName>page1</ActionName>
</Action>
</Actions>
</Input>
<Input name = "BuilderCallEnabled">Enabled</Input>
<Input name = "BuilderCallCategory">General</Input>
<Input name = "BuilderCallComment">"main" is the first method
or action list called when a model is executed.
</Input>
</Inputs>

</BuilderCall>

<BuilderCall id = "pageBuilder"> <!-- pageBuilder definition -->

<BuilderDefID>com.bowstreet.builders.webapp.PageBuilder</BuilderDefID>
<Cache>
<HTMLData>
<HTML>
<HEAD>
<HTMLContent><TITLE>Builder Test
Page</TITLE></HTMLContent>
</HEAD>
<BODY>
<FORM name = "myForm" method = "post">
<HTMLContent><H2>The Date & Time is:</HTMLContent>
<SPAN name = "placeholder"></SPAN>
<HTMLContent></H2></HTMLContent>
</FORM>
</BODY>
</HTML>
</HTMLData>
</Cache>

<Inputs>
<Input name = "BuilderCallEnabled">Enabled</Input>
<Input name = "BuilderCallCategory">General</Input>
<Input name = "PageData">
<html>
<head><title>Builder Test Page</title></head>
<body>
<form>
<h2>The Date& Time is:

4
 <span name="placeholder"/>
</h2>
</form></body></html></Input>
<Input name = "Name">page1</Input>
<Input name = "BuilderCallComment">This is the default first page in the model called by
"main"</Input>
</Inputs>
</BuilderCall>

<BuilderCall id = "dateBuilder"> <!-- dateBuilder definition -->

<BuilderDefID>com.bowstreet.samples.builders.DateBuilder</BuilderDefID>
<Cache></Cache>
<Messages></Messages>
<Inputs>
<Input name = "BuilderCallEnabled">Enabled</Input>
<Input name = "BuilderCallCategory">General</Input>
<Input name = "PageLocation">
<SimplePageLocation>
<Page>page1</Page>
<NameSearch>placeholder</NameSearch>
</SimplePageLocation>
</Input>
<Input name = "Format">HH:mm:ss:z</Input>
</Inputs>
</BuilderCall>

<BuilderCall id = "htmlBuilder"> <!-- hTMLBuilder definition -->

<BuilderDefID>com.bowstreet.builders.webapp.HTMLBuilder</BuilderDefID>
<Inputs>
<Input name = "BuilderCallEnabled">true</Input>
<Input name = "ReplaceTargetElement">true</Input>
<Input name = "ParseMode">rawText</Input>
<Input name = "Name">SkipNavigation</Input>
<Input name = "PageLocation">
<CompletePageLocation>
<Node>AllPages</Node>
<Node>XPath</Node>
<Node>//BODY</Node>
<Node>InsertInsideTop</Node>
<Node>SkipNav</Node>
</CompletePageLocation>
</Input>

5
 <Input name = "HTML"><%@ include file="/factory/pages/samples/skipnav.jsp"
%></Input>
</Inputs>
</BuilderCall>
</BuilderCallList>

<Properties>
<RequiredFactoryVersion>5.0.0</RequiredFactoryVersion>
<Version>0.0.0</Version>
<Description>Model that provides the minimum requirements to
run.</Description>
<Contained>false</Contained>
<EnableGenerationCaching>true</EnableGenerationCaching>
<Roles></Roles>
<EnableFailover>false</EnableFailover>
</Properties>

<Dependencies></Dependencies>
<ExternalProperties></ExternalProperties>

</Model>

2.2 Profiles
A Profile contains a set of inputs that varies the way a portlet behaves, feeding values into
Builder inputs based on contextual information. Using profiles, different variations of the same
portlet application can automatically be generated from a single source model. It also eliminates
hand-coding of variations.

2.3 Builders
A Builder is an ATOM of a Model. It is based on modular approach, that is, it provides a piece of
functionality that is reusable. Builders are wizard-type interfaces that generate code based on
the inputs received from the user. It automates design and development tasks performed by
developers.

Builders are added to the Model through a palette and configured using data entry forms to
enter parameters. Builders are a core component of the WEF tool.

2.3.1 Builder types

There are two types of Builders:

User interface (UI) Builders. These Builders are responsible for creating the UI of an
application, determining what the application's page contains, and how the page elements
interact.

6
 Service and Integration Builders. These Builders work on creating a Web service layer
over existing backend systems, Representational State Transfer (REST) services,
Enterprise Java Beans (EJBs), etc.

2.3.2 Key components of Builders

There are three main objects that form a Builder in WEF:

BuilderDef file. An XML file that includes information about the Builder and its UI. This file
specifies the name, description, and handler class of the Builder. It also includes information
about the Builder Help, domain, category, and the Builder's data.

A BuilderDef file also describes the Builder input via the <InputDefinitions> element. This
input helps to build a rich, consistent UI while Builder is used by the WEF designer.
Listing 3 shows a BuilderDef file explaining the required elements.

Listing 3. BuilderDef file explaining the required elements

<?xml version="1.0"?>

<BuilderDef id="com.bowstreet.builders.webapp.DataColumnAdder"
xmlns="http://www.bowstreet.com/2001/Schemas">

<!-- Description about Builder --!>

<ReadableName>Data Column Adder</ReadableName>
<GenHandlerClassName>com.bowstreet.builders.webapp.pageautomation.PageAutomationGenHandler
</GenHandlerClassName>
<HelpFile>factory/product_documentation/designer/data_field_definition.htm</HelpFile>
<RequiredFactoryVersion>5.6.0</RequiredFactoryVersion>
<Description>Adds a Column in a Data Page Table</Description>
<Domains>
<Domain>WebApp</Domain>
</Domains>

<Category>Page Modifiers</Category>
<BuilderData>
<BuilderDataEntry
name="BuilderClassName">com.bowstreet.builders.webapp.DataColumnAdder</BuilderDataE
ntry>
</BuilderData>

<!-- Builder Coordinator class--!>

<CoordinatorClassName>com.bowstreet.builders.webapp.pageautomation.PageAutomationCoordinator
Base</CoordinatorClassName>

<!-- Builder input element--!>

<InputDefinitions>

7
 <InputDefinition name="Name" base="com.bowstreet.core.Base.BuilderName" />

<InputDefinition name="SingleField">
<Prompt>Container Field</Prompt>
<HelpText>Select field whose child elements will be modified.</HelpText>
<Required>true</Required>
<Type>String</Type>
<Visible>true</Visible>
<Callable>true</Callable>
<ProfileType>Value</ProfileType>
<Editor
JavaClass="com.bowstreet.builders.webapp.pageautomation.PageAutomationFieldChooserWid
get" >
<Argument name="ContainersOnly">true</Argument>
</Editor>
</InputDefinition>

</InputDefinitions>

</BuilderDef>

Builder Handler class. This is a Java class that is called during regeneration of a WebApp.
This class helps to add or modify WebApp elements and implements either
WebAppControlBuilder or WebAppBuilder interfaces, which are Builder regeneration
interfaces (see listing 4).

This class has a doBuilderCall method that is called whenever a model containing your
Builder is regenerated. This method can create or modify elements in the WebApp objects.

Listing 4. Builder Handler class

import com.bowstreet.builders.webapp.api.Text;
import com.bowstreet.builders.webapp.foundation.WebAppControlBuilder;
import com.bowstreet.builders.webapp.pagelocation.PageLocation;
import com.bowstreet.generation.BuilderCall;
import com.bowstreet.generation.BuilderInputs;
import com.bowstreet.generation.GenContext;
import com.bowstreet.webapp.WebApp;

public class DateBuilder implements WebAppControlBuilder

{
/**

8
 * This is the method that's called during generation of the WebApp.
* This builder creates a JSP scriptlet that outputs a formatted Date.
*/
public void doBuilderCall(GenContext genContext, WebApp webApp, BuilderCall builderCall,
BuilderInputs builderInputs, PageLocation pageLocation)
{
System.out.println("DateBuilder builderInputs: " + builderInputs);

Get the format string from builder input

String formatString = builderInputs.getString("Format", "MM/dd/yyyy:HH:mm:ss:z"); //$NON-
NLS-1$//$NON-NLS-2$

// Construct the JSP scriptlet

String dateExpression = "<%= new java.text.SimpleDateFormat(\""; //$NON-NLS-1$

dateExpression += formatString;
dateExpression += "\").format(new java.util.Date()).toString() %>"; //$NON-NLS-1$

// Call the Text builder to insert the scriptlet at specified location

Text textBuilder = new Text(builderCall, genContext);

textBuilder.setPageLocation(pageLocation);
textBuilder.setText(dateExpression);
textBuilder.invokeBuilder();

}
}

Builders are invoked during model regeneration, considering the class defined above, as
follows:

1. The Builder's regeneration class is looked up from the BuilderDef and a corresponding
object get instantiated.

2. The doBuilderCall method is invoked with all Builder inputs.

3. From the doBuilderCall method, Builders create, modify any part of the generated
WebApp as occurred in the above DateBuilder call. It first calculates the date in the
required format and then calls TextBuilder to print the same.

Coordinator Java Class. Is an optional class file that helps to implement a custom
dynamic interface for the Builder.

2.3.3 Features of Builders

Here are some features of Builders:

9
 Easy-to-use. A user-friendly, wizard-type interface eliminates the need for writing code, and
data entry forms for parameters can be changed any time to update the application.

Code automation. For a specific functionality, a single Builder can generate a whole set of
code itself, along with metadata, and can be easily adapted to automate any type of
software development.

Customization and personalization. Builders are consumed by the profiling feature of

WEF, which makes it easy to customize and personalize an application.

Performance. It increases developer productivity, decreases coding errors, and enforces

coding standards across the application.

3 WEF application framework

The WEF application framework resembles the Model-View-Controller (MVC) paradigm as
follows:

Model: Variables and schemas. Variables represent the state of the application. Builders
are responsible for declaring variables and can be associated with different contexts or
current user request. Variables can be updated through actions. The WEF tool supports
String-, Integer-, and XML-schema-based data types.

Controller: Action, Events and Data services. Actions, Events and Data services defines
the behavior of Web applications. Action defines a sequence of steps that should be
performed together such as call to a database, put the result in a variable, and show it on a
page.

Data service is a special kind of action and can represent a backend call. It may have a set
of inputs that should be initiated before the call and a result set.

View: Pages. Web Experience application forms view of the application via HTML
templates or Builder that add dynamic content based on the values of variables.

4 Creating a WEF Project

This section provides the steps that help a developer to create a WEF project, using WEF
Models Eclipse perspective.

1. Launch the Designer client installed on your machine via the shortcut on your desktop

or from the All Programs list in the Start menu.

2. Select a workspace, for example, specify the workspace as a folder called \workspace, in
the folder where you installed Eclipse (see figure 2). Click OK.

10
Figure 2. Select a workspace

3. In the next window, ensure the current perspective is WebSphere Portlet Factory; if it's not,
then change it by clicking the Open perspective button. An Eclipse plug-in provides a
perspective named WebSphere Portlet Factory, which integrates WEF-specific actions
including model and profile set building, project navigation, and package management.

4. To create the WEF project, select File - New --- WebSphere Portlet Factory project, as
shown in figure 3.

Figure 3. Select WEF Project

5. In the Project Name window, enter name of project (see figure 4). Project names are used
to deploy applications to the server. Leave all other settings in this window as is.

11
Figure 4. Project Name window

6. In the Feature Set page window, select the Feature Sets that you will use in the project, as
shown in figure 5; click Next.

12
Figure 5. Feature Set page window

7. In the Server configuration window, click the Create Server Configuration button (see figure
6). Click Finish.

13
Figure 6. Server configuration window

8. A pop-up box appears asking if you would like to publish your project now (see figure 7).
Click Yes.

14
Figure 7. Publish request pop-up

9. A WebSphere Portlet Factory Publish window displays showing the progress of the
deployment (see figure 8), which is complete when the progress bar no longer displays.

Figure 8. WebSphere Portlet Factory Publish window

15
A series of warning messages will appear in the Problems tab, as shown in figure 9. These are
Java complier messages originating from some of the sample code installed with Tutorials.

Figure 9. Problems tab

Follow these steps to modify the error/warning settings:

1. From the Eclipse menu, select Window --- Preferences.

2. In the left-hand navigation tree, select Java --- Complier --- Error/Warnings.
3. In the Error/Warnings list, expand the Unnecessary code section and change the following
preferences from Warning to Ignore:

Local variable is never used

Unused import
Unused local or private member change other preferences if required.

4. Click OK to accept the changes, and click Yes to allow the project to rebuild.

The Problems tab should no longer contain messages.

4.1 Create the Run Configuration and test the sample Model
To do this:

1. In the Project Explorer tab in Eclipse, expand the project, locate

models/tutorials/solutions/basics/Tutorial_MyFirstPortlet.model, and double-click it (see
figure 10).

16
Figure 10. Project Explorer tab

2. The Model editor opens in the Eclipse Designer window, in which the Builder Call List is
located in the Outline view, and the WebApp Tree view of the model's generated product is
on the right-hand side of the window, as shown in figure 11.

17
Figure 11. Eclipse Designer window

3. Click the Run button in Eclipse, and open the Run Configuration window.
4. Highlight WebSphere Portlet Factory Model in the configuration list, right-click it, and
select New.
5. In the Name field, enter WebApp model, accept all the default settings, and then click Run
(see figure 12).

18
Figure 12. Create, manage, and run configurations window

6. The Designer opens a browser and calls the model by its URL; the output from the Model is
displayed in the browser as shown in figure 13.

19
Figure 13. Output from Model

5 Creating a Hello World portlet using WEF

In this section we create a basic model with the Designer, and test it with a standalone
application server and then as a portlet in WebSphere Portal Server v8.0.

5.1 Create a basic Model

1. Open the WEF perspective and create a new WEF Model, selecting File --- New ---
WebSphere Portlet Factory Model.
2. In the Choose Project window, select Test_Project, and click Next (see figure 14).

20
Figure 14. Choose Project window

3. In the Select Model window, select Main and Page for the Model type field; click Next (see
figure 15).

21
Figure 15. Select Model window

4. In the Page Settings window (see figure 16), select Simple Page for the Page Type field
and click Next (a Simple Page is an HTML page created in the model, and an Imported
Page is an HTML page imported from a file into the model).

22
Figure 16. Page Settings window

5. In the Save New Model window, set the Enter or Select a Folder field to models/test, and
set the Model Name field to HelloWorld (see figure 17).

23
Figure 17. Save New Model window

6. Click Finish to create the model, after which the WEF perspective looks like that shown in
figure 18.

24
Figure 18. WEF perspective

5.2 Add a Text Builder Call to the Model

To do this:

1. Click the Add Builder Call button (see figure 19).

Figure 19. Add Builder Call button

25
2. The Builder Picker window opens; select Text Builder and click OK (see figure 20).

Figure 20. Builder Picker window

3. In the Eclipse main work area, the Builder call editor tab is highlighted, and the Text
Builder's edit page displays. Edit the following values, leaving the others as is (see figure
21):

Page: page1
Tag: namedTag
Text: <type in text of your choice>

26
Figure 21. Eclipse main work area

4. To have the model to function inside the WebSphere Portal Server framework, we need to
add the Portal Adapter Builder. Follow the same steps as above to add this Builder, setting
the following values (see figure 22):

Name: WebExperience_HelloWorld
Portlet Title: Web Experience Hello World
Portlet Description: Portlet using WebExperience Factory

NOTE: You can put in any value for these fields.

5. Save the Model.

27
Figure 22. Eclipse window showing Portal Adapter Builder

5.3 Test the Model using standalone application server

This section discusses the steps for testing the Model created above on a standalone
application server:

1. Verify that the server is running and that the project standalone WAR application is
running on the server.
2. Click the Run WebApp Model icon in the Eclipse tool bar.
3. The WEF Automation Engine regenerates a WebApp for HelloWorld, applies the
JavaServer Page (JSP) defined by page 1, and displays it in browser (see figure 23).
4. Verify the contents of the browser page and then close it.

28
Figure 23. HelloWorld WebApp in browser

5.4 Test the Model on the WebSphere Portal Framework

Now we test the model as a .war file on a WebSphere Portal server. Since WebSphere Portal
server installs portlet applications as .war files, we first build the Project portlet .war file to
incorporate the HelloWorld model.

Follow these steps to build the Project portlet WAR:

1. Right-click the WebApp project in the project pane and select Build Portlet Factory WAR ---
Build Portlet WAR.

29
2. Place the Portlet on a page, following these steps:

a) Browse to WebSphere Portal Server URL, using any available browser.

b) Log in as administrator, and go to the Administrator console.
c) Go to Manage Pages and search for the page where you want to add the portlet.
d) Edit page properties and click Add portlets.
e) Search and select the required portlet and click OK.
f) Verify the new portlet has been added to the left-hand column; click Done, to return to
the user portal page.

The HelloWorld portlet displays in the Portal, as shown in figure 24.

Figure 24. HelloWorld portlet

6 WEF Web application directory structure

This section provides images of the directory structures of a Web application built via WEF (see
figure 25). It will help us locate the resources of the application.

30
Figure 25. WEF Web application directory structure

models. Contains all models that take part in the application (see figure 26).

Figure 26. Models directory

profiles. Contains all profile sets (see figure 27).

31
Figure 27. profiles directory

WEB-INF. Contains all Java classes, profile sets, other non-servable resources for WEF itself,
and all Web applications (see figure 28).

32
Figure 28. WEB-INF directory

WEB-INF/builders. Contains Builder definition files (.bdef) used in a project (see figure 29).

33
Figure 29. WEB-INF/builders directory

WEB-INF/classes. Contains the deployable Java classes used by application (see figure 30).

Figure 30. WEB-INF/classes:

WEB-INF/clientLibs. Contains the deployable .jar files used by a Web application (see figure
31).

34
Figure 31. WEB-INF/clientLibs

WEB-INF/config. Contains the properties files used by WEF (see figure 32).

Figure 32. WEB-INF/config directory

WEB-INF/factor/generated/genjava. Contains all Java files that the Automation Engine

generates for the methods in your model (see figure 33).

35
Figure 33. WEB-INF/factor/generated/genjava directory

WEB-INF/factory/themes. Contains theme files used by the Web application (see figure 34).

Figure 34. WEB-INF/factory/themes directory

WEB-INF/lib. Contains all .jar files used by WEF (see figure 35).

36
Figure 35. WEB-INF/lib directory

WEB-INF/logs. Contains files that record entries for all activities under WEF (see figure 36).

37
Figure 36. WEB-INF/log directory

WEB-INF/models. Contains all default and user-created models (see figure 37).

Figure 37. WEB-INF/models directory

WEB-INF/work. Contains sample Java source files and classes (see figure 38).

38
Figure 38. WEB-INF/work directory

7 Dynamic profiling with WEF

These days, customization or personalization of applications for individual users is one of the
most desirable requirement of industries.

Profiling helps to overcome maintenance and scalability challenges occurring during

customization based on user preferences, roles, groups, and interest of application. Profiling
helps to build applications that automatically adapt themselves to the preferences and
characteristics of each individual using the system.

Web Experience Factory helps to achieve this profiling via its Dynamic Profiling feature by
defining a set of parameters for each profile that vary the way an application behaves. A profile
feeds these values to Builders based on preferences, and hence can create different variations
of a portlet application.

The following are two basic steps associated with profiling in WEF:

(1) Enabling a model to accept inputs via a profile. Profiling cannot be achieved until we
expose models to accept inputs for different variations of an application. This process is
independent of the input source.

39
(2) Managing profile data. Profile data can be stored in profile sets and applied to a model for
a given regeneration.

The Profile Manager editor is the tool to modify profile sets and corresponding values. These
profile sets are stored as XML files with a .pset extension under the WEB-INF/profiles directory.

Steps for creating a Profile set using WEF:

1. Click the New wizard icon, or select File - New --- Other; the Select a wizard window
displays (see figure 39). Choose WebSphere Portlet Factory Profile Set and click Next.

Figure 39. Select a wizard window

2. In the New Profile Set window, enter the following values (see figure 40):

Name: Name of new profile set.

Description: About the profile.

40
 Note that (a) the name of profile set can contain only letters, digits, and periods; and (b) the
profile set's description is a required field.

Figure 40. New Profile Set window

3. Click Finish. Once the Profile set is created, you can create one or more profiles.

Example of a Profile Set

We have created an example Profile set, Greetings, with three different profiles based on users'
choices, providing options to greet the user based on day and time (see listing 5).

Listing 5. Example Profile set (xml file, .pset)

<ProfileSet name="Greetings" useQualifiedProfileNames="true"><Description>Profile set for creating
different greetings based on time</Description>
<LastModifiedBy>Administrator</LastModifiedBy>
<ProfileSelectionClass>Explicit Handler</ProfileSelectionClass>
<Models />
</Models>

41
<ProfileDef><Entries><Entry name="GoodMoring" isRuntime="true"><UI
type="Select"><Prompt>Prompt</Prompt>
<ExtraData>Good Morning, Good Afternoon,Good Evening</ExtraData>
</UI>
</Entry>
</Entries>
</ProfileDef>
<Profiles><Profile name="Greet1" last_modified="1337237541000"
isContainer="true"><Values><Value name="GoodMoring">Hello, Good Morning!
</Value>
</Values>
<Roles />
</Profile>
<Profile name="Greet2" last_modified="1337237541000" isContainer="true"><Values><Value
name="GoodAfternoon">Hello, Good Afternoon!</Value>
</Values>
<Roles />
</Profile>
<Profile name="Default" last_modified="1337237541000" isContainer="true"><Values><Value
name="Hello">Hello, Good Day!</Value>
</Values>
<Roles />
</Profile>
</Profiles>
</ProfileSet>

where the various elements of a Profile set are defined as follows:

Entries. Each entry corresponds to one flavor of customization of a Web application. It

determines how it is displayed in the Profile manager and UI control to set its
value.<sentence doesn't make sense; please rewrite for clarity>

Profiles. Contains a set of profile elements.

Profile. Contains a value for each entry element included in the Profile set.

8 Custom Builder in WEF

So far we've learned about WEF, its framework, the development of Web / portlet applications
using WEF, and other useful aspects of the product. Although all components of WEF are
equally important, we found that Builder is the core component level of WEF; it is the part that
decides what model executes.

WEF is enriched with many default Builders that are sufficient to build any Web application to
meet the user's requirements, but having the capability to create custom Builders makes the
tool more powerful in that developers can create any kind of custom Builder.

42
The following are the most common situations in which custom Builders are most needed:

To automate a repetitive task, avoiding the need to write the same piece of code repeatedly.

If a project consumes two or more default Builders every time, then a consolidated Builder
can be formed, to make the Builder Call List simple.

8.1 Creating a custom Builder using WEF

To do this:

1. Start WEF and create a Project, as described in the above sections.

2. Make sure the current Model is running without any error message.

3. Open the NewBuilderWizard model as shown in figure 41. This Builder is used as a
container for the Builder Skeleton Builder.

Figure 41. NewBuilderWizard model

4. Double-click the Builder Skeleton Builder call in the Outline view; the Builder Call Editor
opens.

5. In the Builder Call Editor, click the Reset all inputs to defaults button and enter following
values (see figure 42):

Builder Type: Choose per your requirement; in this example, Basic Builder is chosen.

Builder ID: This corresponds to unique ID of the Builder in the format of com.[company
name].builders.[custom Builder name]. In this example, it's
com.ibm.builders.testCustomBuilder.

Readable Name: This corresponds to the user-visible name of the Builder and that appears
in the Builder Picker window; in this example, it is set to MyCustomBuilder.

Description: Specify the Builder description that appears at the top of Builder UI.

43
 Builder Inputs: Specify the Builder input under the Builder Inputs section per your
requirement.

Figure 42. Builder Skeleton window

6. Click OK to save the properties. To verify the creation of the custom Builder, open the
Builder Picker window and go to the custom Builder section; your Custom Builder should be
there (see figure 43). Save the Model.

44
Figure 43. Builder Picker window

7. Now go to the Application Tree view, expand the Comments section, and select your Builder
files. The two files generated for the custom Builder are displayed, that is, Builder class and
BuilderDef file (see figure 44):

Builder Class: \work\source\com\ibm\builders\testCustomBuilder.java

BuilderDef: \builders\com\ibm\builders\testCustomBuilder.bdef

45
Figure 44. Application Tree view

8. Open the Builder Java file in Edit mode. Here you can write the code for what your custom
Builder must perform, an example of which is shown in listing 6.

Listing 6. Custom Builder Java File

import com.bowstreet.builders.webapp.foundation.*;
import com.bowstreet.builders.webapp.methods.BuilderHelperUtil;
import com.bowstreet.generation.*;
import com.bowstreet.util.*;
import com.bowstreet.webapp.*;

/**
* Bowstreet builder regen class
*/
public class testCustomBuilder implements WebAppBuilder
{

/**
* This is the method that's called during generation of the WebApp.
*/
public void doBuilderCall(GenContext genContext, WebApp webApp,
BuilderCall builderCall, BuilderInputs builderInputs)
{
// System.out.println("builderInputs: " + builderInputs);

/*##GENERATED_BODY_BEGIN#InputAccessorCode#*/
// Generated code to get all the builder inputs
String name = builderInputs.getString(Constants.Name, null);

46
 /*##GENERATED_BODY_END*/

// @todo: Add your builder code here

}

/**
* Interface that has constants for all the builder input names
*/
static public interface Constants
{
/*##GENERATED_BEGIN*/
public static final String Name = "Name";
/*##GENERATED_END*/

9. Save Java file and compile. Include your custom Builder in your model and regenerate.

10. Run the model; you should see your customized Builder functionality in the Web
application.

9 Key points about WEF development

Note these key points regarding WEF development:

The Model is represented as XML,so when we open it in the Editor, it generates a Web
application according to its Builder Call List.

The process of regeneration occurs when a Model is opened and when Builder calls are
added, are dragged around, and are cut and pasted in the Builder Call List.

At the time of Model construction in Designer, any changes are pushed out to the
application server when you save the Model.

All Model-generated files (executable files, JSPs, method classes, etc.) are generated
directly on server by the regeneration process.

Rebuild Portlet .war files only when making changes such as adding a Portlet Adapter
Builder call to a Model, removing Portlet Adapter call from a model, update existing Portlet
Adapter Builder call, to Portlet adapter Builder calls in the model.

During iterative development/testing, there's no need to rebuild Portlet .war files because
WEF automates the migration of files and code onto the application and or WebSphere
Portal server.

47
 Model comments are used for two principal purposes:

Description. Each Model has an About this model comment to describe its purpose
and operations.
Organization. Use Comment Builder calls to organize Builder Call Lists into logical
groups.

The order of Builder Calls in the Builder Call List does not matter, and it can be organized to
improve the readability of model.

Comment Builder Call with Name only causes it to act as heading.

Creating a separate Model for individual functionality has following advantages:

Builder Call Lists become shorter and more readable.

A single model can be used for multiple models, which centralizes the control of
imported models.
Development becomes faster as each developer can work on a separate model.

While creating a Profile do not use a navigator to rename the Profile set; WEF uses the ID
for the Profile set.

Among the different approaches to building Profiles, one is to build an application without
profiling any Builder Call and, once built, you can determine which part needs customization
and then profile the specific Builder Call to achieve that.

When using the Error Handler Builder, always use it at the top-level portlet Model actions.

10 Comparing WEF with conventional portlet development

Now let's highlight some of the main differences between portlet development using WEF and
using the conventional way, for example, IBM Rational Application Developer (RAD):

In WEF, Builder Call generates the code automatically, whereas it is required to code from
scratch via the conventional way.

The Profiling feature of WEF helps to form variations of Web applications easily from a
single source. In the traditional way it is done via hard coding for each variation.

In WEF, Web applications can be converted into a portlet WAR with the click of button,
whereas in the traditional way, re-engineering is required.

WEF takes less time to develop than does the traditional way, in which hard coding is done.

The availability of Builders in WEF makes development easy, fast, scalable, and easy to
maintain, which is not the case via the conventional way.

48
In short, you should use WEF when you need to:

Have shortened development and delivery times.

Develop an application as a service producer/consumer.
Remove manual coding of variations for the application.
Develop the same application as a portlet and as a Web application.
Develop Java Server Request (JSR) 168/268 variants of a single portlet application.

11 Troubleshooting, debugging, and error handling

In this section we discuss some core techniques for troubleshooting a WEF application and
handling runtime errors:

The Problem tab of the Eclipse tool depicts all compilation errors occurring during the
design time of an application. The errors are displayed along with the details, which you can
open by double-clicking on each individual error. Based on the error message, code can be
fixed. The error details also include the path of the Model Java file, which can be opened to
get more details.

All runtime errors can be captured from the browser following a request to the application.
Usually the WEF default error page is returned with exceptions information. This default
error page can be customized as per the application to convey messages to the end users.
The error page is a JSP file located in WebContent/factory/webapp/defaulterror.jsp.

Always refer to error logs of an application, errors, and standard outputs of the server
as this helps to understand whether the root cause of issue is due to previous/old errors.

Use Eclipse Java debugger to debug generated Java methods, printing models and their
values, and WEF tracing utility.

WEF includes two utility JSPs, TestDataSourceConnection.jsp and

testDominoConnection.jsp, to debug backend and connectivity issues, respectively.

WEF is packaged with the Error Handler Builder, to handle errors corresponding to Model
actions. This Builder is similar to the Java try/catch mechanism and works with all Models in
which try-catch can be specified in Builder inputs.

12 Conclusion
Developers who work on portlet application development using traditional means can build their
experience with the IBM Web Experience Factory tool and take advantages of its capabilities to
enhance their business.

13 Resources
IBM Web Experience Factory wiki:
http://www-10.lotus.com/ldd/pfwiki.nsf

developersWorks Web Experience Factory product page:

http://www.ibm.com/developerworks/websphere/zones/portal/portletfactory/

49
IBM Web Experience Factory customer discussion forums document:
http://www-304.ibm.com/support/docview.wss?rs=3044&uid=swg27011853

14 About the author

Deepak Gupta is a Staff Software Engineer based at IBM's Delhi, NCR, India, facility, where he
works on WebSphere Portal development and customer engagements. He is currently the
worldwide focal point for People Components for WebSphere Portal and is a Subject Matter
Expert for WebSphere Portal. Deepak holds a Bachelor's degree in Computer Science and
Engineering from the Indraprastha University, India.

Trademarks
developerWorks, IBM, Rational, and WebSphere are trademarks or registered trademarks
of IBM Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

50