Tutorial – Creating a WebSphere Portlet Factory Project 

---

This is the first of four tutorials that introduce you to the many powerful features of IBM® WebSphere® Portlet Factory. In this tutorial you will learn how to create a WebSphere Portlet Factory project for WebSphere Portal.

For a tutorial focused on creating a project for WebSphere Application Server Community Edition (WAS CE), see Quick Start for using IBM WebSphere Portlet Factory with IBM WebSphere Application Server CE.

Using these tutorials

This set of tutorials are a great starting point for a new WebSphere Portlet Factory developer. Each of the four parts of this tutorial take between 30 and 45 minutes to complete. The tutorials should be completed in the following order, as each builds on knowledge obtained in the previous tutorial. In addition, we recommend visiting the WebSphere Portlet Factory Learning Roadmap on the WebSphere Portlet Factory wiki after completing these tutorials to further advance your WebSphere Portlet Factory learning experience.

Table 1.

Tutorial order	Description
Creating a Web Application Project	In this tutorial you will learn how to create a web application project.
Creating an application	In this tutorial, you will build a simple "hello world" application and then create a portlet from that application.
Creating a database application	In this tutorial you will create a service provider model against a sample database using the SQL Table Create builder, and then create a user interface service consumer model, using the Service Consumer and Data Services User Interface builder.
Using profiling in your new application	Continuing from the "hello world" application tutorial you add the power of profiling to your application.

What you will learn

After installing IBM WebSphere Portlet Factory, the first step in creating a portlet is to create a WebSphere Portlet Factory project using WebSphere Portlet Factory Designer. The project serves as the foundation for your portlet or application and contains all the artifacts required to publish your portlet or application.

In this tutorial, you create a WebSphere Portlet Factory project, configure it for use with a IBM WebSphere Portal environment, and run a sample to ensure that the setup is correct. After completing these tasks, you are ready to complete other tutorials to learn the basics of developing web applications and portlets with WebSphere Portlet Factory.

Before you start

The following setup is required to run the tutorial.

• To test the portlets you need access to a local or networked installation of WebSphere Portal. To publish your project, WebSphere Portal server must be running. The instructions in this tutorial assume that you have the WebSphere Portal server installed locally, though other configurations are possible, as described below. If you do not have a portal you can test the applications on a local development server, but cannot complete the portal specific steps.
• WebSphere Portlet Factory Designer must be installed locally. WebSphere Portlet Factory Designer is the development environment for creating web applications and portlets. It is installed into an integrated development environment (IDE) such as Eclipse or Rational Application Developer (RAD). If you do not have Eclipse or RAD installed already, you can install Eclipse as part of the WebSphere Portlet Factory installation procedure.
• You need access to an application server for running your applications from the Designer while they are under development. WebSphere Portal runs on top of WebSphere Application Server, so if you have installed WebSphere Portal, you can use its instance of the WebSphere Application Server as your test environment. You can also use WebSphere Application Server Community Edition (WAS CE), or Tomcat.
  

Creating the Project

1. Start WebSphere Portlet Factory Designer. If you are presented with a welcome page, close it.
   
Note: When using RAD, you should locate the workspace close to the top level of your file system (for example, C:\\factory\\my_projects\\) to prevent path/file names from exceeding the Windows 256-character limit.

2. Switch to the WebSphere Portlet Factory perspective by choosing Window -> Open Perspective -> Other... -> WebSphere Portlet Factory.
3. Create a WebSphere Portlet Factory Web Application project by completing these steps
1. From the menu, choose File -> New -> WebSphere Portlet Factory Project. You will be guided through a wizard that assists you in creating the project.
   
Note: Be sure to choose WebSphere Portlet Factory Project from the list rather than Project.

2. For the Project Name step, enter MyFirstProject without any spaces. Spaces and certain special characters are not permitted in project names. Click Next when finished naming the project.
   
4. Add the Tutorials and Samples feature set:
1. At the Feature Sets dialog box, all available feature sets are listed. Choose Tutorials and Samples to select all components within that feature set. This option adds the files needed to run the tutorials that ship with WebSphere Portlet Factory Designer.
2. Click Next to continue.
   
5. Understand the test server configurations.
   
   
You will only need to create one Server Configuration. This server configuration will publish the your project to both the Application Server for testing your project during development and will publish the Portlets to Portal for view there.

There are many different configurations a developer can set up. The most common types of configuration are described below:

Table 2. Common types of Portalconfiguration

Configuration Type	Description
Locally installed Portal and Application servers	You have installed WebSphere Portal Server and the embedded WebSphere Application Server locally. When you create new server configurations, references to critical folders such as the application server's installedApps folder will point to your local hard drive. This configuration is very easy to use but requires a powerful development machine with a minimum of 2 GB of RAM in order to achieve acceptable levels of performance.
Remotely installed Portal and Application Servers	WebSphere Portal server and the embedded WebSphere Application Server are installed on another machine accessible across the network.



6. Create the server configuration. If you have an existing configuration that works you can use it. Otherwise you will need to create a new configuration.
1. Click Create Server Configuration in the project properties window.
2. Choose the server configuration that is correct for your environment and click OK. The Edit Server Configuration dialog displays.
3. The configuration name and description of the configuration are loaded by default.
   
Use the online help to complete the configuration for your environment.

4. Click Test Server Connection to verify the connection to the WebSphere Application Server. If you receive an error then make sure your server is running and then click Test Server Connection again.
5. Click OK to continue.
   
7. When you click Finish, your project will be created according to the details and features you have specified. You will be prompted Would you like to publish you project now?. Click Yes.
   
If you are using a local installation of WebSphere Portlet Factory 6.x, security for WebSphere Application Server is enabled by default. As a result, you may be prompted for credentials during the creation of the WAR files. Use the WebSphere Application Server administrator credentials and not the WebSphere Portal administrator credentials. Also, be sure to wait for this prompt before leaving the publishing process unattended. The prompt will time out if you ignore it and your WAR file will not be automatically published. In this case, you can still install and configure the WAR file manually via the WebSphere Administrative Console.

8. If the servers are remote or if you have chosen not to use the Publish Application function for your application, you will see an error message in the Problems view. This message will state that the WebSphere Portlet Factory Dev WAR location does not exist. You will also see this message if the Publish Application function failed for some reason, such as if your server was not running. If you receive this error you will need to publish the Portlet WAR file manually via the WebSphere Portal Administrative console.
   

Testing the Setup

Now that you have created the WebSphere Portlet Factory project you will run a sample application on the server to test that everything is properly configured.

1. Test your configuration by opening one of the sample models from the Tutorials And Samples feature set by following these steps:
1. In the Project Explorer view, expand the models\\tutorials folder. All of the models you will create in other tutorials will go into this same folder.
2. Locate the Tutorial_MyFirstPortlet.model inside the tutorials folder and double-click it to open it: \\solutions\\basics\\MyFirstPortlet_Solution.
   
2. Create a run configuration
1. From the menu, choose Run -> Run... or click above the workspace. Select the default run configuration that was created when the WebSphere Portlet Factory Model project was created. This is the current active model.
2. If everything has been configured correctly, you should see a web application in your default browser that will display "Tutorial Basics - Hello World!". It is not necessary to do anything with this application. Simply seeing it in the browser confirms that the setup is correct and that WebSphere Application Server is running the application.
   
3. Clean up Java compiler messages and warnings (Optional)
1. Switch back to WebSphere Portlet Factory WebSphere Portlet Factory Designer. In the Problems tab at the bottom of the workspace, you may see several warnings about and unused local variables. These messages are about unnecessary code in the sample Java files in the Tutorials and Samples - Builders feature set. These variables will get used if you complete the tutorial called Creating a Custom Builder. If you prefer to suppress these warnings for now, continue with this step. Otherwise, skip to step 5.
2. Follow these steps to suppress unnecessary code warnings.
1. From the menu, choose Window -> Preferences to bring up the Preferences dialog box.
2. On the left side of this dialog box, select Java -> Compiler -> Errors/Warnings .
3. On the right side, there should be several collapsed sections. Expand the section labeled Unnecessary code.
4. There are a few fields in this section whose values are set to Warning such as Local variable is never read. Set all of the fields in this section to Ignore.
5. Click OK to save these changes.
6. Eclipse will now need to rebuild all of the currently open projects. When prompted to do a full build to apply these changes, click Yes. After the rebuild process has completed, the warnings should be gone.
   
4. Test a portlet model in WebSphere Portal to ensure the portlet published properly.
1. Log into WebSphere Portal as an administrator or a user with rights to create pages and add portlets to pages.
2. Add the portlet whose title is Tutorial Basics - My First Portlet Solution to a new or existing page. If you did everything correctly while creating the project, you should see this portlet easily. Close out of page management when finished.
3. Open the WebSphere Portal to the page containing this new portlet and examine the portlet. It should look like the MyFirstPortlet_Solution model you tested at the beginning of this section.
4. Close WebSphere Portal when you are satisfied that the portlet published properly.
   
5. Close all open models and files in WebSphere Portlet Factory Designer by choosing from the menu File -> Close All.
   

Lessons learned and next steps

Congratulations! You have successfully created a WebSphere Portlet Factory project and run a sample application to confirm your configuration. The WebSphere Portlet Factory project that you created will contain all of the models you create plus all of the supporting code and artifacts needed to develop, publish, and test WebSphere Portlet Factory web applications and portlets.

Now you are ready to move forward to learn how to develop web applications and portlets with WebSphere Portlet Factory Designer. Start with the tutorial for Creating an application.

Parent topic: Tutorials for IBM WebSphere Portlet Factory: wpf7