Portlet Factory v6.1.2 Install Guide

 

+

Search Tips   |   Advanced Search

 

  1. Installation overview
  2. Installing WebSphere Portlet Factory
  3. Installation notes
  4. Removing IBM WebSphere Portlet Factory
  5. Appendix A - Upgrading plug-in files, projects, and portlets
  6. Appendix B - Enabling IBM Tivoli License Manager tracking
  7. Appendix C - Using JAWS For Windows during installation
  8. Notices and trademarks

 

Installation overview

Installation involves the following steps:

Step 1 - Install WebSphere Portlet Factory Designer
Run the installation program to install WebSphere 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 deploy to your application server or portal server.

 

1.2 Pre-installation information

The default Installation selection will include a supported version of Eclipse. Alternatively, WebSphere Portlet Factory can be installed into a supported version of one of the following IDE's:

  • IBM Rational Application Developer
  • IBM Rational Software Architect
  • IBM Rational Web Developer
  • Eclipse (Eclipse SDK versions only)

Prior to installation, install IBM WebSphere Portal or one of the supported application servers. Refer to the supported platforms section in your product Release Notes for application server versions and patch levels.

 

1.3 Existing installations of WebSphere Portlet Factory

If you have an existing installation of WebSphere Portlet Factory do not install the new version over the old one in the same directory.

To use the same directory for the new installation, follow these steps:

  1. Consider a backup of your existing installation
  2. Back up any private files, such as SAP libraries
  3. Remove the old version using the process detailed in Removing IBM WebSphere Portlet Factory
  4. Install the new version using the process detailed in Installing WebSphere Portlet Factory
  5. Move any backed up private files into the correct directory in the new installation.

 

2. Installing WebSphere Portlet Factory

Follow the steps described in Step 1 - Install WebSphere Portlet Factory on Windows and Install WebSphere Portlet Factory on Linux to install WebSphere Portlet Factory on the desired platform, and then Step 2 - Run the tutorial: creating a Web application project to begin exploring the product.

 

Step 1 - Install WebSphere Portlet Factory on Windows

  1. Launch the installation executable (Factory.exe).
  2. When prompted, select your preferred language for using the product.
  3. An introduction page displays with copyright and other information. To proceed with installation, then click Next
  4. Read the license agreement and select I accept the terms of the License Agreement to proceed with installation, then click Next.

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

  5. You can choose one of the following options:

    • Standard installation provides everything needed to get started quickly

      Select this option to include Eclipse and WebSphere Application Server Community Edition with your WebSphere Portlet Factory installation. If this option is selected, the installation program installs Eclipse, WebSphere Portlet Factory Designer, and IBM WebSphere Application Server Community Edition (WAS CE) . If you choose this option, skip to step 9.

    • Custom installation enables you to choose features and installation options

      Select this option if you need to specify in detail your software options and their installation location.

      In the Select installation directory field, specify the location to install WebSphere Portlet Factory files and click Next.

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

    • Install Designer with a new copy of Eclipse

      Select this option if you do not have an IDE. If this option is selected, the installation program installs Eclipse and WebSphere Portlet Factory Designer.

      If you select this option and select a directory that contains an existing installation of Eclipse, a warning message displays. Choose a different directory to continue the installation.

    • Install into existing IBM Rational Application Developer*

      Select this option if you want to use a Rational Development Environment you have already installed. This includes Rational Application Developer, Rational Software Architect, and Rational Web Developer. The installation program will add Portlet Factory-specific menu items to the current version of your Rational Development Environment.

    • Install into existing Eclipse

      Select this option to use a version of the Eclipse-based IDE that is already installed. The installation program adds to the current version of your Eclipse IDE menu items specific to WebSphere Portlet Factory Designer.

  7. In the Specify IDE screen, specify the IDE location and click Next. If you need to browse for the location, click Choose.
  8. The option to install IBM WebSphere Application Server Community Edition (WAS CE) displays. WAS CE is an open source Java 2 Platform, Enterprise Edition (J2EE) application server based on Apache Geronimo. You can use WAS CE to enable quick and easy development and testing of applications. Click Install WAS CE as a development test server and choose the install location if you want to install WAS CE.
  9. 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.
  10. 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).

  11. If you install into an existing Eclipse-based WebSphere Portlet Factory Designer installation, upgrade WebSphere Portlet Factory Designer plug-ins if you are installing over a previous version of WebSphere Portlet Factory. For information about the steps required to upgrade plug-ins, see Appendix A - Upgrading plug-in files, projects, and portlets.

 

Install WebSphere Portlet Factory on Linux

Prerequisites Before you install WebSphere Portlet Factory, you should install:

  • An application server such as Tomcat, WAS CE or IBM WebSphere Portal.
  • Eclipse with Web Tools. Check the WebSphere Portlet Factory release notes for the supported Eclipse release.

Permissions and IBM WebSphere Portal

If you are deploying to WebSphere Portal you will need to perform the following steps:

  1. Create a group for your user, for example "wpfDev". This group will have write permissions to the WebSphere directories.
  2. With WebSphere Application Server running, open the administration console, and navigate to: Application servers > WebSphere_Portal > Process Execution. Change the umask value to 002. Change the 'run as group'' to wpfDev. Perform the same step for server1. This will allow you to change the file permissions for the portal server. Any file written by the portal server will now have read / write execute permissions for the portal user, and the group to which the portal user belongs.
  3. Stop the WebSphere Portal server.
  4. Make yourself a member of the newly created group (wpfDev in this example).
  5. From a command line run the following commands as root:
    chgrp -R wpfDev <WP_INSTALL_DIR>/AppServer/  chgrp -R wpfDev <WP_INSTALL_DIR>/PortalServer/  
    If the directories are not writable by group, then run the following commands:
    chmod -R g+w <WP_INSTALL_DIR>/AppServer/  chmod -R g+w <WP_INSTALL_DIR>/PortalServer/
    This allows write access to the those folders after the WAR files are deployed.
  6. Restart WebSphere Portal server.

Installing WebSphere Portlet Factory on Linux

  1. Launch the installer: ./Factory.bin. The installer checks for space and other prerequisites and displays the first panel.
  2. When prompted, select your preferred language for using the product.
  3. An introduction page displays with copyright and other information. To proceed with installation, then click Next
  4. Read the license agreement and select I accept the terms of the License Agreement to proceed with installation, then click Next.

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

  5. In the Choose Install Folder screen, specify the location to install WebSphere Portlet Factory files and click Next.
  6. Specify the location where Eclipse with Web Tools is installed and click Next
  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, /root/IBM/).

 

Installing WebSphere Portlet Factory into Rational Application Developer/Rational Software Architect on Linux

If you are installing WebSphere Portlet Factory into and existing Rational® Application Developer/Rational Software Architect installation on Linux, you will need to preform these steps:

  1. Install WebSphere Portlet Factory with the user account of the WebSphere Portlet Factory user. The Eclipse installation location should be a directory that the user account has write access to. You may need to choose a location other than the Rational Application Developer installation location. There does not need to be an existing Eclipse in this location.
  2. If you chose to install Eclipse into the Rational Application Developer install location in the previous step, skip this step. Using an account with write privileges to the Rational Application Developer install location, copy the links directory created by the installer to the correct directory in the Rational Application Developer install location. The links folder should be located just within the Rational Application Developer installation directory. You can also copy the WebSphere Portlet Factory link file directly to a previously created links directory within Rational Application Developer.
  3. Start Rational Application Developer with the -clean flag as root (or the Rational Application Developer owner) and verify WebSphere Portlet Factory is installed. Use Help > About to verify that the WebSphere Portlet Factory button displays.
  4. Restart Rational Application Developer with the -clean flag as the WebSphere Portlet Factory user, if it is not the user in the previous step, and verify as in the previous step.
  5. Restart Rational Application Developer normally as the WebSphere Portlet Factory user. You do not need to use the -clean flag at this point.

 

Step 2 - Run the tutorial: creating a Web application project

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

The WebSphere Portlet FactoryDesigner 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. If you are using a Windows client, this tutorial is available from the Welcome page, or from Start. Click Start > Programs > IBM > WebSphere Portlet Factory > Tutorials. If you are using a Linux client, this tutorial is available from the WebSphere Portlet Factory Help system.

 

3. Installation notes

You may have to set class loading order for IBM WebSphere Application Server or provide additional configuration steps for IBM WebSphere Portal.

 

3.1 WebSphere Portal configuration

The following additional configuration step is required for WebSphere Portal 6:

Configure heap size

By default, WebSphere Portal 6 sets 512 MB as the maximum allowed size for the heap. Raise this maximum to 1 GB.

Use the WebSphere Administrative console to set the heap size. For more information about configuring the heap size, see the WebSphere Administrative Console Help.

 

3.2 Apache Tomcat

After you run the WebSphere Portlet Factory Designer New WebApp Project wizard, restart Tomcat. This ensures that all libraries are loaded correctly.

 

3.3 Native language support for Eclipse

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

To use WebSphere Portlet Factory Designer in a language other than English, 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 WebSphere Portlet Factory Designer.
  2. Access the Eclipse.org Web site home page and navigate to Downloads > All Versions > 3.2 Language Packs.
  3. In the Language Packs: 3.2.x screen, download the NL-1 pack zip files for the Windows platform.

    Two zip files are required.

  4. Extract these archive files to your Eclipse installation location and ensure that you use the correct directory level.
  5. Start WebSphere Portlet Factory Designer. If Microsoft Windows is configured to use a non-English Group 1 language, Eclipse now can run in that language.

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

  6. Optional: You can force Eclipse to run in any Group 1 language by adding a language identifier to the Eclipse startup command.

    For example, if you add the following identifiers to the startup command, you can run Eclipse in Spanish, regardless of the language the system is configured to use:

    -Duser.language=es -Duser.country=ES

    The same languages are supported in IBM Rational Application Developer. To install language support into Application Developer, use the Installation Manager (or install it when you install Application Developer). See to the Application Developer documentation for instructions on installing language support.

 

3.4 Eclipse Double byte language issues on Linux

Linux installations of WebSphere Portlet Factory on double byte languages may not display correct fonts. Possible solutions include:

  • Install all available fonts for the language you are using.
  • Start the installer with a JRE on your system that is compatible with your language selection. For example:
    /Factory.bin LAX_VM $JAVA_HOME/bin/java 

The same languages are supported in IBM Rational Application Developer, and for users to refer to the Application Developer documentation for instructions on installing language support.

 

4. Removing IBM WebSphere Portlet Factory

Follow the steps in 4.1 Removing WebSphere Portlet Factory Designer for Windows or 4.1.1 Removing WebSphere Portlet Factory Designer for Linux (depending on your client platform) and then4.2 Removing project WAR files to remove WebSphere Portlet Factory Designer files and project WAR files.

 

4.1 Removing WebSphere Portlet Factory Designer for Windows

  1. Use the Windows Control panel to access Add/Remove Programs.
  2. Select the product to uninstall and click Change/Remove.
  3. When the Uninstall window appears, click Uninstall.

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

 

4.1.1 Removing WebSphere Portlet Factory Designer for Linux

With a Linux installation, you will need to manually remove certain files and directories created by the installer.

  1. Delete the Designer directory and the log file in the installation directory.
  2. Delete the <original install directory>/IBM/license directory if desired
  3. Delete the WebSphere Portlet Factory link file called com.bowstreet.designer.link which is located in the <IDE_INSTALL_DIR>/links directory. For example, /opt/IBM/SDP75/links

 

4.2 Removing project WAR files

  1. Use your application and portal server administration tools to remove installable and installed WAR files.
  2. The administration tool removes only the installed applications, so it may be necessary to manually delete any remaining application or portlet related directories and files.

 

Appendix A - Upgrading plug-in files, projects, and portlets

This section discusses the procedures required to upgrade IBM WebSphere Portlet Factory plug-in files if you have installed a new version of WebSphere Portlet Factory into an IDE (Eclipse or IBM Rational) that has a previous version installed. This section also describes how to update a project built with a previous version of WebSphere Portlet Factory Designer to the latest project version. Finally, this section describes how to upgrade portlets to the Java. Portlet Standard API.

 

Upgrading a project from versions 5.12, 6.0.0, 6.0.1, and 6.0.2

When upgrading 'flat' projects, create a new project and migrate your content to it using the Export > WebSphere Portlet Factory Archive function. A flat project is a 5.12 or 6.0 project that does not have a WebContent directory. You will not get the added benefits of facet support if you upgrade a flat project. You must modify any projects that you created using the old plug-in files so that these projects can include changes related to the new plug-in files. To upgrade a project, do this:

  1. Open an existing project into WebSphere Portlet Factory Designer.
  2. Right-click the project entry in the Project Explorer and click WebSphere Portlet Factory Project > Upgrade Project Version.
  3. A summary information displays. Click Next.
  4. Update the deployment information for this project if necessary. Check the deployment configuration and click Finish in the upgrade wizard.
  5. Before the upgrade process completes, you may be prompted to overwrite any WebSphere Portlet Factory files in the project that have changed, including files that were changed by WebSphere Portlet Factory functionality, not necessarily files that you have changed manually.
  6. You will need to redeploy the project to the servers. Click Yes when prompted to redeploy.

 

Upgrading portlets to the Java Portlet Standard API

As of WebSphere Portal 6, there is support for Java Portlet Standard API for WebSphere portlets. While portlets designed for use in previous version of WebSphere Portal and built using the deprecated WebSphere Native portlet API continue to run in WebSphere Portal 6, IBM recommends that any new portlets be built using the Java Portlet Standard API.

You can easily upgrade portlets built using the deprecated WebSphere Native Portlet API to the Java Portlet Standard API. To do so, modify the project that contains the portlet models.

If you have already upgraded the project, you can switch to Java Portlet Standard API by switching the project to a Java Portlet Standard API Portal deploy configuration by uninstalling the old WAR as described in the following steps and updating the project to use the Java Portlet Standard API deploy configuration. Redeploy when prompted

To upgrade a portlet built in a previous version of the WebSphere Portlet Factory to use the new Java Portlet Standard API, perform the following steps:

  1. Load the project containing the portlet model into the WebSphere Portlet Factory Designer.
  2. Select the project and click WebSphere Portlet Factory Project > Upgrade project version.
  3. Using the WebSphere Portlet Administration tool, remove the old portlet WAR file from the WebSphere Portal server. (If the project has already been upgraded, switch the project to a Java Portlet Standard API Portal deploy configuration, then update the project to use the Java Portlet Standard API deploy configuration and redeploy when prompted.)
  4. In WebSphere Portlet Factory Designer, use the Project Deployment Configurations dialog to deploy the updated portlet WAR file to the WebSphere Portal server.
  5. Use the WebSphere Administration tool to place the updated portlets on WebSphere Portal pages.

 

Appendix B - 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 IBM WebSphere Portlet Factory can be monitored and tracked by Tivoli License Manager. To enable this capability, place at the root level of an application or portlet EAR file certain files that are generated by the WebSphere Portlet Factory and recognizable by Tivoli License Manager.

To enable Tivoli License Manager usage tracking, perform the following operation:

Drag the WEB-INF\bin\itlm\ directory and its contents to the root of the deployed EAR file.

Ensure that the WEB-INF\bin\itlm\ directory is in one location only. You see a dual usage error if multiple copies of this directory exist in an EAR file.

Tivoli License Manager provides only inventory tracking if you do not move the WEB-INF\bin\itlm\ directory to the root of the EAR file.

 

Appendix C - Using JAWS For Windows® during installation

To install WebSphere Portlet Factory and use the JAWS screen reader for accessibility, you need to perform the following additional step to correctly start the installation.

You need to have Java Access Bridge for Microsoft Windows Operating System software installed on your system. Java Access Bridge for Microsoft Windows Operating System is provided by Sun Microsystems, Inc, Copyright (c) 2006 Sun Microsystems, Inc. Use the following command to start the WebSphere Portlet Factory installation:

Factory.exe LAX_VM installDir-for-java\java.exe
Where installDir-for-java\ is your local Java installation directory. This command forces the installation to use the JVM that you specified and that works with the Java Access Bridge.