Product Installation Guide

 

 

 WebSphere Portlet Factory

 

 

Table of Contents

1. Installation Overview
Pre-Installation Information

2. Install WebSphere Portlet Factory
Step 1 - Install WebSphere Portlet Factory Designer
Step 2 - Run the Tutorial: Creating a Web Application Project

3. Installation Notes
WebSphere Application Server 5.x
WebSphere Portal 5.x
Apache Tomcat
Native Language Support

4. Removing WebSphere Portlet Factory
Remove Designer
Remove Project WAR Files

Appendix A - Embedded Test Server Additional Procedures
Appendix B - Upgrading Plug-in Files, Projects and Portlets
Appendix C - Access a Remote WebSphere Installation
Appendix D - Enabling IBM Tivoli License Manager Tracking

First Edition (August 2006)
This edition applies to version 6.0.1 of IBM WebSphere Portlet Factory (product number 5724-O03) and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2006, 2007. All rights reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

 

1. Installation Overview

 

This guide applies to WebSphere Portlet Factory. Installation involves the following steps:

  • Step 1 - Install Portlet Factory Designer - By running the Installation program Factory.exe. This program installs Portlet Factory Designer and related support files.

  • Step 2 -  Create and Deploy a Web application project - Use the tutorial provided to create a Web application project that you will deploy to your application server or portal server.

 

1.2 Pre-Installation Information

This product operates as a plugin to Eclipse-based Integrated Development Environments (IDEs). If you do not have one of the following supported IDEs, the Installation program will provide Eclipse 3.1:

 

1.2.1 Supported Development Environments

IBM Rational Application Developer 6
IBM Rational Software Architect
IBM Rational Web Developer
Eclipse 3.1

Prior to installation install WebSphere Portal or one of the supported application servers. Refer to the supported platforms section in your product's Release Notes for application server versions and patch levels. The Release Notes are available from http://www.ibm.com/developerworks/websphere/zones/portal/portletfactory/proddoc.html.

top

 

2. Install WebSphere Portlet Factory

 

Follow these steps to install WebSphere Portlet Factory.

 

Step 1 - Install Portlet Factory Designer

  1. Launch the installation executable (Factory.exe).

  2. When prompted, select your preferred language for using the product.

  3. Read the license agreement and select "I accept the terms of the License Agreement" to proceed with installation and click Next.

    Note that If you do not accept the license terms, you will be prompted to quit the installation.

  4. In the Choose Install Location screen, specify the location where you want to install WebSphere Portlet Factory files and click Next.

  5. In the Specify install items screen, select an integrated development environment (IDE) to use with WebSphere Portlet Factory Designer. We can choose one of the following options:

    • Into existing IBM Rational Application Developer - Select this option if you want to use the Rational Development Environment. The installation program will add Portlet Factory-specific menu items to the current version of your Rational Development Environment.

    • Into Existing Eclipse - Select this option to use a version of the Eclipse-based IDE that is already installed. The installation program adds Factory specific menu items to the current version of your Eclipse IDE. If you install into an existing Eclipse-based Designer installation, be sure to see Appendix B for instructions on updating Portlet Factory Designer plug-in files.

    • And Eclipse - Select this option if you do not have an IDE. If this option is selected, the installation program installs Eclipse 3.1 as well as Portlet Factory Designer.

  6. In the Specify IDE screen specify the IDE location and click Next. If we need to browse for the location, click Choose.

  7. Review the Pre-Installation Summary screen and if all information is correct, click Install. An Install progress screen is displayed and, once installation is complete, the Install Complete screen is displayed.

  8. Click Done to close the Factory installer.

    A browser opens and displays a Welcome page containing information about Next Steps. Upon successful installation, an install log is created in the  install location (for example, C:\Program Files\IBM\WebSphere Portlet Factory).

  9. If you have installed into an existing Eclipse-based Designer installation, update Designer Plug-in files. See  Appendix B in this guide for the steps required to update plug-ins.

 

Step 2 - Run the Tutorial: Creating a Web application project

Once you have successfully installed the Portlet Factory Designer, you must create a new project. In the course of creating a project, you will provide application server- and portal server- specific information about your installation. This process completes the deployment phase of Portlet Factory installation.

The Designer provides a New Project wizard to help you create a project. This multi-page wizard walks you through the steps involved in project creation and deployment and also builds the project for you. F1 Help that describes project settings and parameters is available for each page of the wizard. Refer to F1 Help to learn about the settings on a given page and to access links to additional information.

The best way to create your first project is to run the tutorial that describes this process. This tutorial is available from the Welcome page, or from the Start menu at: Start | Programs | IBM | WebSphere Portlet Factory | Tutorials.

top

 

3. Installation Notes

 

 

3.1 WebSphere 5.x Application Server

Set Class Loading Order  -- In a WebSphere 5 environment, set the class load order on the WebApp project so that the class loader for the Factory application context looks at the JARs in the project's WEB-INF/lib before looking at those shipped with the WebSphere Portal. This ensures that latest versions of third-party JAR files are correctly picked up. Here's how:

  1. In the WebSphere Application Server Console, go to Applications |Enterprise Applications.

  2. Click on the enterprise application name for your Factory installation, for example, "portlet_factory". (When you click on the enterprise application name, you display a list of properties for the enterprise application.)

  3. In the Related Items list of the Configuration Tab, click the Web Modules link.

  4. Click on the wpf.war file, displaying the General Properties for the WPF WAR file.

  5. Change the Class loader Mode to " PARENT_LAST " and click OK.

  6. Save the changes to your local configuration.

  7. Restart the server.

top

 

3.2 WebSphere Portal

The following addition configurations are required for WebSphere 6 Portal:

  1. Configure Heap Size -- By default, WebSphere Portal 6 sets 512 MB as the maximum allowed size for the heap. This maximum should be raised to 1 GB. WebSphere Portal 5.x sets 64 MB as the maximum heap size. This maximum should be raised to 400 MB. Use the WebSphere Administrative console to set the heap size. For more information on configuring the heap size, see the WebSphere Administrative Console Help.

  2. Update the Cookie Path  -- The default settings on the WebSphere Portal do not include the Factory's root directory in the cookie path. If you are using a development configuration on WebSphere Portal, the Factory's root directory must be added to the cookie path in order to save your session information.

You may experience problems with refresh and caching of web pages before you update the cookie path. You will not be able to successfully complete the Portlet Factory tutorials without changing the cookie path. Use the WebSphere Administrative console to replace "/ wps " with "/" in your cookie path.

  1. (WebSphere Portal 5.1 only) Add " pbportlet.jar " File -- This file is need only if you plan to build portlets based on deprecated IBM Portlet API, rather than the Java Standard API (recommended). This JAR file, included in previous versions of the WS Portal, is not provided with version 5.1 As a result, procure this file and add it to your system. If you have access to a 5.0 version of the WebSphere Portal, we can find this file at: WebSphere\PortalServer\pb\lib . Alternately, we can get a copy of this file from IBM Customer Support.

The default web.xml used to create Factory Portlet WARs includes a reference to the WebSphere C2A Portlet wrapper ( com.ibm.wps.pb.wrapper.PortletWrapper ). As a result, all Portlet WARs must include the appropriate version of pbportlet.jar. When developing against WebSphere Portal 5.1 server, manually specify the location of the directory that contains the pbportlet.jar file.

Once you acquire the pbportlet.jar file, place it in an accessible directory on the system on which you are installing WebSphere Portal 5.1.

Create a project and, when the WebSphere Portlet Settings page is displayed, use the PB Portlet Jar Location input widget and browse to the location of the pbportlet.jar file. Then select the file and complete project creation.

After you select this file the first time, it will be automatically included in the portlet WAR created by the factory.

top

 

3.3 Apache Tomcat

After running the Designer's New WebApp Project wizard restart Tomcat. This ensures that all libraries are loaded correctly.

 

3.4 Native Language Support

WebSphere Portlet Factory Designer supports Group 1 languages, including: German, Spanish, French, Italian, Japanese, Korean, Portuguese (Brazil), Traditional Chinese and Simplified Chinese.

To use Portlet Factory Designer in a language other than English, you must download a language pack from the Eclipse Web site, and install that pack into your Eclipse IDE. To enable Group 1 language support:

  1. Halt Portlet Factory Designer.

  2. Access the Eclipse.org Web site home page and navigate to: Downloads | All Versions | 3.1.1 Language Packs.

  3. In the Language Packs: 3.1.x screen, download the NL-1 pack zip files for the Windows platform. (Two zip files are required.)

  4. Extract these zip files into your Eclipse installation, making sure to do so at the correct directory level.

  5. Start Portlet Factory Designer. If Microsoft Windows is configured to use a non-English, Group 1, language, Eclipse will now run in that language.

    Note: Multi-byte characters are not supported for project names or the names of folders in the path.

Note: We can force Eclipse to run in any Group 1 language by adding a language identifier to the Eclipse startup command. For example, by adding: -Duser.language=es -Duser.country=ES to the startup command, we can run Eclipse in Spanish, regardless of the language the system is configured to use.

top

 

4. Removing WebSphere Portlet Factory

 

Follow these steps to remove Designer files and project WAR files.

 

4.1 Remove Designer

  1. Use the Windows Control panel to access the Add/Remove Programs tool.

  2. Select the product to uninstall and click Change/Remove.

  3. When the Uninstall screen appears, click Uninstall.

Product files, registry entries and shortcuts are removed from your system.

 

4.2 Remove Project WAR files

  1. Use your application and portal server administration tools to remove installable and installed WAR files.

  2. If necessary, delete from the server's file system any remaining application or portlet related directories and files.

top

 

Appendix A - Embedded Test Server Additional Procedures

 

Installing in an embedded test server environment requires a few additional procedures and steps. If you are installing the Factory on IBM Rational Development Environment Studio Application Developer in an embedded test environment (application server or portal server), complete the following procedures.

 

Step 1 - Install the Factory

Install as you normally would using the Installation program. In an embedded server environment, it is advisable to locate the workspace at a high level in order to prevent path/file names from exceeding the 256-character limit imposed by Microsoft Windows.

When starting up Rational Development Environment Studio, you are prompted for a workspace location. In response to this prompt, specify a location close to the top level of your directory system. For example: c :\ factory\my_projects\ .

 

Step 2 - Turn off Validation (Optional)

Validating all the HTML and XML files in the Factory project can take a long time. You may want to turn validation off before refreshing your project.

This procedure applies to all projects in the workspace. To disable validation for Factory-related projects only, disable the settings listed below by using the Factory and Factory Web Project Properties dialogs.

To turn off validation:

  1. In Rational Developer select Window | Preferences.

  2. Select Validation and click the Deselect all button.

  3. Click Apply.

  4. In the left pane, select: Web Tools |Links |Validation | Refactoring.

  5. De-select the Enable LinksBuilder check box.

  6. Click Apply.

  7. Click OK to close the Preferences window.

 

Step 3 - Configure the Test Server

This step publishes the application and starts the test server.

  1. Right-click the Web application project and select Run on Server.

  2. Select the WAS version and configuration desired, then click OK.

If you have not specified a server configuration, the default WebSphere 5 server configuration can be used.

Note: Attaching to a remote server has not been tested.

 

Step 4 - Modify the Method Compiler Classpath Setting

In order to use Factory builders that utilize code in third-party JAR files, you might need to change the bowstreet.methods.classPath property in your cluster.properties file.

To change this property:

  1. Open in a text editor, such as Notepad: < project_name >/ WebContent /WEB-INF/ config / cluster.properties .

  2. Find the property called  bowstreet.methods.classPath .

  3. Append the path to the appropriate j2ee.jar file to this property's value. For example, to use the j2ee12.jar file that ships with the Factory, use the following as the value to append to this property:  ${ bowstreet.rootDirectory} / clientLibs /j2ee12.jar .  (This file is stored in: bowstreet_root_directory /WEB-INF/ clientlibs )

  4. Save and close the cluster.properties file.

  5. Restart RAD to apply the changes to this property.

 

Step 5 - Open and run a Model

After you have completed all the preceding steps, we can start using the Factory in Application Developer:

  1. Double-click on a model in the WEB-INF\models directory to open the model in the Portlet Factory Designer.

  2. Choose Run | Run Last Launched from the menu or click the "Run" icon in the toolbar to run the model.

  3. When you run a model, the embedded server you configured is used.

Access step-by-step instructions for developing a simple application by running the introductory tutorials available from the Portlet Factory Designer Help system's Table of Contents.

top

 

Appendix B - Upgrading Plug-in Files, Projects and Portlets

 

This section discuss the procedures required to upgrade Portlet Factory plug-in files in an existing Eclipse installation. This is necessary when Designer is installed into an existing copy of Eclipse. This section also describes how to update a project built with a previous version of Designer to a 5.12 project version. Finally, this section describes how to upgrade portlets to the new IBM Portlet API standard

 

Upgrading Designer 5.11x and 5.12 Plug-in Files

To upgrade WebSphere Portlet Factory Designer 5.11 or 5.12, replace old Designer plug-in files with new versions. Follow these steps to update Designer plug-in files:

  1. During WebSphere Portlet Factory 6 installation, choose to install into an existing Eclipse.

  2. Use the Eclipse Update Manager to disable the old versions of the plug-in files. From the Designer menu bar select: Help| Software Updates |Manage Configuration.

  3. In the left pane of the Project Configuration window, right-click on ...\BowstreetDesigner\eclipse and choose "Disable."

  4. Restart Designer. The new WebSphere Portlet Factory 6 plug-in files will now be used.

  5. To pickup the new plug-ins, you might need to cycle the server after you update the project.

  6. Upgrade any projects to use new Designer components. (See next section.)

Note: In some cases, during project creation an error message might be displayed indicating that the system cannot find the file specified. This is caused by Eclipse persisting parameters set prior to upgrade. Should this occur, start Eclipse using the -clean flag. See Eclipse documentation for additional details about the -clean option.

 

Upgrading a Project

You must modify any projects you created using the old plug-in files so these projects can pick up changes related to the new plug-in files. To do this:

  1. Upgrade the Designer as described above.

  2. Load a legacy project into Designer.

  3. Right-click on the project in the Navigator and select WebSphere Portlet Factory Project | Modify... from the right-click menu.

  4. When prompted, click OK. The project will be updated to use the latest components.

 

Upgrading Portlets to the Java Standard Portlet API

As of WebSphere Portal 6, there is a new Java Standard Portlet API for WebSphere portlets. While portlets designed for use in previous version of WebSphere Portal, and built using the now deprecated IBM Portlet API, will continue to run in WebSphere Portal 6, it is recommended that any new portlets be built using the Java Standard Portlet API.

However, we can upgrade portlets built using the deprecated IBM Portlet API to the new Java Standard Portlet API. To do so modify the project containing the portlet models. To upgrade a portlet built in a previous version of the Portlet Factory to use the new Java Standard API:

  1. Load the project containing the portlet model into the Portlet Factory Designer.

  2. Select the project and, from the project right-click menu, choose: WebSphere Portlet Factory Project | Modify...

  3. Using the WebSphere Portlet Administration tool, remove the old portlet WAR file from the WebSphere Portal.

  4. In Portlet Factory Designer, use the Auto-Deploy function to deploy the updated portlet WAR file to the WebSphere Portal.

  5. Use the WebSphere Administration tool to place the update portlets on Portal pages.

 

Upgrading to Eclipse 3.2

If you decide to upgrade to this latest version of Eclipse, do so by following these steps:

  1. Download the Eclipse 3.2 software.

  2. Install the Eclipse program over your existing version of Eclipse.

  3. Start Designer and note that it is running in the 3.2 version of Eclipse.

top

 

Appendix C - Access a Remote WebSphere Installation

 

To enable the Designer to access a remote WebSphere installation, for example on a UNIX machine, map a drive on your Windows machine to the remote computer. When mapping this Drive:

  1. Point the mapped drive to the WebSphere root directory of the remote machine (/opt/WebSphere).

  2. Verify that you have write access to the following folders on your mapped drive:

/WebSphere/ PortalServer /installableApps
/WebSphere/ PortalServer /installedApps
/WebSphere/ AppServer /installableApps
/WebSphere/ AppServer / installedApps

  1. Start Eclipse using the - consolelog argument. This will allow you to see if the Designer is having a problem (due to permissions) copying a model to the server when you save or run the model.

 

Appendix D - Enabling IBM Tivoli License Manager Tracking

 

IBM Tivoli License Manager (ITLM) recognizes and monitors what products and their versions, releases, and fix packs are installed, and used, on a system. This allows IBM to communicate updates for products installed in its customer base, and appropriately bill for the product and the amount of usage. It also prevents billing for multiple installations of the same product that is bundled with various IBM software packages.

The usage of applications and portlet WAR files created with the WebSphere Portlet Factory can be monitored and tracked by ITLM. To enable this capability place certain, ITLM-recognizable, files generated by the Portlet Factory at the root level of an application or portlet EAR file.

 To enable ITLM Usage tracking:

  1. Drag the WEB-INF\bin\itlm\ directory, and all of it's contents, to the root of the deployed EAR file.

Note: Verify the WEB-INF\bin\itlm\ directory is in one location only.  ITLM will report dual usage if multiple copies of this directory exist in an EAR file.

Note: ITLM provides Inventory tracking only if you do not move the WEB-INF\bin\itlm\ directory to the root of the EAR file.

See your WebSphere Portal documentation for additional information about using ITLM.

top

 

Notices

 

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. We can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive Armonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Copyrights and Acknowledgments
Licensed Materials - Property of IBM
Copyright IBM Corp. 2006, 2007 All Rights Reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by SGA ADP Schedule Contract with IBM Corp.

Supplemental Copyrights and Acknowledgments
The following Copyrights and Acknowledgments apply to various software components included in IBM WebSphere Portlet Factory, but neither created nor owned by IBM.
This offering is based on technology from the Eclipse Project (http://www.eclipse.org/).
This product includes software developed by the Apache Software Foundation (http://www.apache.org).
Portions of this software provided by JDOM. Copyright (C) 2001 Brett McLaughlin & Jason Hunter. All rights reserved.
Portions of this software provided by the membership of the XML-DEV mailing list. We can obtain a copy of the SAX copyright status at http:// www.megginson.com /SAX/.
The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both:
Cloudscape
IBM
Lotus
WebSphere
Workplace

top