. 55
( 87 .)


5.0 Data Source. Select Next. Provide a data source name of your choice.
Enter a JNDI name of your choice, keeping the jdbc/ pre¬x. The name you
enter here (after jdbc/) is the data source name that you will use in the
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

326 Chapter 17

Figure 17-2 Server con¬guration.

portlet con¬guration. For Component-managed authentication alias select
the JAAS Authentication Entry that you created. Uncheck the check box for
Use this Data Source in Container Managed Persistence (CMP). This is the
minimal set of changes you need to make. Make other changes as needed
for your environment. Select Next.
Enter the database name on this page. This is the only required con¬gu-
ration on this page. Make other changes as needed for your environment.
Select Finish. The data source has been de¬ned. Close the server con¬gu-
ration edit and save the changes.
A portal server con¬guration is like a server con¬guration with the addi-
tion of portal-speci¬c con¬guration information kept in the wps-info.xml
¬le. You can view the con¬guration ¬les through a ¬lter change. Switch to
the Web perspective and from the Project Navigator in the left pane click
on the menu icon. From the drop-down list select Filters. From the Filters
dialog box that appears, select Server in the project types list and select OK.
Back in the Server perspective, the server has been con¬gured but we
have not associated any portlet projects with it. Right-click on the server
you just added from the Server view. Select Add and Remove Projects. You
will add Enterprise Application (EAR) projects to the server con¬guration
(see Figure 17-3). When you created the portlet project, it was associated
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

Portlet Interactive Debug and JSR 168 Example 327

Figure 17-3 Adding and removing projects.

with an EAR, DefaultEAR, by default. If you did not change that then add
the DefaultEAR project to the server con¬guration.
To change the EAR a portlet project is deployed into, open the EAR de-
ployment descriptor (application.xml). Select the Module tab and use
the Add and Remove buttons to change the Web applications associated
with this EAR.
When the Portal test environment is started, the Poll portlet (and any
other portlets in the DefaultEAR project) will be deployed on a debug
portal page.
You can publish, start, and stop the server manually. Publishing copies
the application project, resource, and con¬guration ¬les to the correct server
location. After the publishing is complete you can start the server. You can
also start the server in debug mode. If not started in debug mode you will be
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

328 Chapter 17

Figure 17-4 Portal page.

able to execute your portlets; in debug mode you can set breakpoints, inter-
rogate code, and inspect variables. These actions can be performed from the
Server view from the pop-up menu and the server. After the server starts you
can open a browser to http://hostname:9081/wps/myportal where
hostname is your server hostname and 9081 is the HTTP server port that
was con¬gurable when the server was created.
As an alternative you can start the server and launch your portlet in a
Studio Web browser by right-clicking the portlet project and selecting either
Debug on Server or Run on Server from the pop-up menu. After logging
in with the default portal admin id (wpsadmin) the portlet is shown (see
Figure 17-4).

Portal Debug Mode
When you start the server in debug mode you can set breakpoints in your
Java source ¬les or JSP ¬les and then, using the Debug perspective, debug
your code. You can step through the code, inspect variables, and evaluate
expressions in context of the current thread™s stack frame.
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

Portlet Interactive Debug and JSR 168 Example 329

Figure 17-5 Debugging your code.

Breakpoints can be made conditional and they can be active based on a
hit count. You can set exception breakpoints or breakpoints can be set on
binary types where there is no source code available.
In our example application we added a breakpoint to the following line
in the ConfigVerifyDatasourceAction actionPerformed method:

DbBroker dbBroker = new DbBroker(formData.getDatasource());

Then when we ran the portlet and clicked the Verify button in con¬gure
mode, the Debug perspective opened, with processing suspended at that
breakpoint. Figure 17-5 shows the debugger opened, with execution sus-
pended at that method. You see in the Variables view the current values
of the method variables. The current stack is shown along with the current
class outline. We can continue execution by stepping through the code to
trace the application execution. We can also inspect code expressions in the
current method or through the Expressions view.
We can make changes to our portlet code and have those changes imme-
diately re¬‚ected in our executing test environment. There is generally no
need to restart the server or republish the application in order to test code
modi¬cations. However, if changes are made to the deployment descrip-
tors for example, those changes require a server restart. But, changes can
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

330 Chapter 17

be made to Java classes or JSPs in the Portlet perspective, saved, and then
that code immediately executed.
Studio™s ability to interactively debug portlet code in a test environment
with dynamic changes provides an extremely powerful development en-
vironment. The portlet toolkit provides assistance for getting the port-
let application development started by creating the portlet project and
starting the base implementations. The portal test environment signi¬-
cantly enhances that by providing a highly productive execution envi-
ronment that assists in application code debugging while allowing devel-
opers to more quickly understand the portlet API through its interactive
The step-by-step debug mode of WebSphere Application Server lets you
debug WebSphere Portal internal methods. This is enabled by default. To
disable the step-by-step debug mode so that you stop only at the breakpoints
that you set, do the following:

1. Select Window ➪ Preferences from the menu bar
2. Select WAS Debug mode to open the WAS Debug page.
3. Deselect the Use step-by-step Debug mode check box.
4. Click OK.

Portal Trace Logging
The IBM Portlet API provides a logging mechanism so that portlet devel-
opers can easily write trace messages to a common log. By default, the
trace messages are written to a log ¬le named wps_<date>.log in the
<wp-root>/log directory, where <date> is the timestamp when the log
was ¬rst created.
WebSphere Portal also supports the redirection of its trace logging to
the WebSphere Application Server log. This function can be enabled in the
<wp_root>\shared\app\config\log.properties ¬le.
You can enable trace logging using an administrative portlet or through
a properties ¬le change. Using the Enable Tracing portlet will allow you to
specify the trace settings temporarily. When the server is restarted,
the trace settings return to the previous state. You can also update the same
log.properties ¬le and specify the trace setting there. In this case the
change will get applied when the server is restarted.
In either case the trace speci¬cation is through a trace string. See the
Portal Information Center in the section Using Logs for the de¬nition of
trace strings. For example, to enable tracing of portlets use the following
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

Portlet Interactive Debug and JSR 168 Example 331

trace string:

Enable tracing in our Portal test environment. The portal root (<wp-
root>) in Studio is <studio-root>\runtimes\portal_v50. So the log
¬le is at <studio-root>\runtimes\portal_v50\shared\app\log
.properties. Uncomment the traceString property and set it to the
string shown above.
You will recall that we had two trace messages in our portlet code. In
the service method and in the actionPerformed method we had the
following. Note it is good practice to test if logging is enabled before at-
tempting to write the trace message and also before constructing the trace
if (log.isDebugEnabled())
log.debug(this.getClass().getName()+".service() dispatching to "+

if (log.isDebugEnabled())
log.debug(this.getClass().getName()+".actionPerformed() dispatching to

So after executing our portlet with tracing turned on we should see port-
let trace messages in the <studio-root>\runtimes\portal_v50\log\
wps_2004.01.19-23.51.33.log ¬le (see Figure 17-6).

Figure 17-6 Portlet trace messages.
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

332 Chapter 17

Figure 17-7 Exporting a WAR ¬le.

Generating a Deployable WAR File
Generating a deployable WAR ¬le in Studio using the portal toolkit is very
easy. Since the portlet project is consistent with the expected contents of a
Web archive ¬le we simply need to export the project to a WAR ¬le. That
¬le can then be installed in WebSphere Portal.
For our Poll portlet simply right-click the Poll project in the Project
Navigator view and select Export (see Figure 17-7). You can install this
portlet application in Portal using the Install administrative portlet.

Deploying Using the Install Administrative Portlet
You can deploy the portlet application WAR ¬le into Portal using the In-
stall administrative portlet. Log in to portal as a user with administrative
privilege (is a member of wpsadmins) and navigate to the Install pages by
¬rst selecting the Administration page, then the Portlets page, and ¬nally
the Install page.
WY009-17 WY009-BenNatan-v1.cls May 11, 2004 14:51

Portlet Interactive Debug and JSR 168 Example 333

The Install page contains a single portlet, the Install portlet. From this
portlet you specify the location of the WAR ¬le on your local ¬le system and
then execute the install function. The portlet application will be installed in
portal. Typcially, the next administrative steps are to add portlet or portlets
that were installed with that portlet application to a portlet page and assign
resource permissions if required. Note that the Manage Portlet Applications
portlet can be used to update an existing portlet application. This updates
the portlets de¬ned in the WAR ¬le while preserving the portlet resource


. 55
( 87 .)