© Copyright International Business Machines Corporation 2003. All rights reserved.

Introduction

IBM ® WebSphere® Portal (hereafter called Portal) has influenced how many WebSphere developers now build their Web applications. Portals have become a hot technology for Web development. WebSphere Portal 4.1.2 provides the IBM Portal Toolkit plug-in for WebSphere Studio Application Developer (hereafter called Application Developer). With Portal Toolkit, developers can use Application Developer to build portlets through special portlet-creation wizards. One issue affecting portlet development teams using Application Developer is how to organize the teams, and what processes to use so that the teams can work efficiently together.

In a J2EE^TM team development scenario, you need to understand how to handle the metadata portions of a J2EE application. A J2EE application consists of three parts:

• The Java^TM compiled code (.class files) that form the servlets, portlets, and utility classes
• Resources such as HTML and JSP files
• Metadata defined by the J2EE specifications, including the ejb-jar.xml file, the web.xml file, and the application.xml file, and vendor-specific metadata such as Portal's portlet.xml file

Metadata is unique in one respect: while individual developers can take ownership of specific Java classes (such as portlets) and resources (such as JSPs), the metadata files are shared resources that the developer needs to modify whenever a new component is added, or when a component configuration changes. Therefore, understanding what these metadata files do and how tools like Application Developer work with them is key to developing a process for efficient team development. This article examines common team development scenarios using the Portal Toolkit for Application Developer, and provides best practices for handling common problems.

Back to top

Relationship between the web.xml and portlet.xml files

The portlet.xml file defines the metadata information for the portlet; this information is necessary to render the portlet. When installing the portlet, Portal reads this file and populates the database with the information from portlet.xml. The web.xml file defines the servlet (portlet) classes and the portlet.xml file references the classes it needs with the servlet ID through HREFs. The relationships between the different elements in web.xml and portlet.xml are shown in Listings 1 and 2 below.

Figure 1 shows how the elements within the portlet.xml file are connected.

This metadata structure demonstrates how important it is that the two files, portlet.xml and web.xml, remain synchronized. As you can see from the above example, the portlet ID used in the portlet.xml file refers to a specific servlet ID that was previously defined in the web.xml file. Likewise, the portlet.xml file contains internal references. As you can imagine, if these references become misplaced, there can be chaos. The scenarios and best practices presented in this article should help to reduce or eliminate problems stemming from a poor synchronization of these files in a team environment. In particular, the article discusses putting the following best practices in place:

• Since most Portal projects will contain only a single portlet, developers can choose to use either sequential or parallel development within the portal project. This means that you can rely on the standard features of Application Developer's team development environment to successfully merge multiple changes to a single portlet component.
• If a portal project contains more than one portlet, multiple developers can work on the existing portlets contained within the project in either a sequential or parallel fashion in most cases (this is an extension of the previous case). This is because when you modify a portlet, the shared data does not change.
• In the case where a portal project contains more than one portlet, development should only occur sequentially when you need to create a new portlet within the portlet project. This is due to problems created by duplicated IDs within the shared web.xml and portlet.xml files for the portlet project. Once the new portlet has been created and the metadata files properly updated and stored in the code repository, then parallel development can resume.

Back to top

Prerequisites

The team development simulation demonstrated in this article is based on WebSphere Studio Application Developer 4.0.3 for Windows® and CVS version 1.11.1.3 (build 57i). CVS user accounts cvsdev1 and cvsdev2 have been created. The Portal Toolkit plug-in is provided with WebSphere Portal 4.1.2 for Multiplatforms.

Back to top

Configuration

The scenarios described here assume that there are two developers, Developer 1 and Developer 2, on a team. The developers each use their own instances of Application Developer. The scenarios use two separate workspaces to simulate these two developers, and demonstrate branching and merging changes in a team environment.

To set up the team environment used in this scenario, complete the following:

1. Create two workspace folders, for example, run the following commands from the command line:
   
   
   • md d:\workspace\cvsdev1
   • MD d:\workspace\cvsdev2
     
     
2. Start two instances of Application Developer. From the Start menu, select Programs => IBM WebSphere Studio Application Developer => IBM WebSphere Studio Application Developer, or run the following commands from the command line:
   
   
   • For Developer 1:
     
     X:\Program Files\IBM\Application Developer\wsappdev.exe -data d:\workspace\cvsdev1
     
     
   • For Developer 2:
     
     X:\Program Files\IBM\Application Developer\wsappdev.exe -data d:\workspace\cvsdev2
     
     where X:\ is the directory in which Application Developer is installed.
     
     
3. In each IDE, switch to the Repositories view, and create a connection to the CVS repository with a CVS userID and password. This article uses CVS userIDs, cvsdev1 for Developer 1, and cvsdev2 for Developer 2.

Back to top

Concurrent development scenarios

First, consider the most common team development scenarios used when developing portal applications with Application Developer. In your development environment, your team will of course select the team development scenario that is most suitable for your requirements and your development process. In this set of scenarios, the term portlet project is used. This term refers to an Application Developer Web project that includes portlets and a portlet.xml file (and therefore represents a portlet application).

The scenarios described here include:

• Sequential portlet development within a single portlet project. In this scenario, only one developer at a time works within a portlet project. This is the most common scenario since in most cases a portlet project is comprised of only one portlet.
  
  
• Parallel portlet development within a single portlet project. In this scenario, two or more developers can modify the same portlet at the same time. This is a special case of the previous example, but this article will show, this scenario poses no special difficulties to the portlet developer.
  
  
• Multiple parallel portlet development within the same portlet project. This is the most complicated scenario, and also the only scenario that can pose difficulties to the development team if not handled correctly. In this case, several developers each create and modify one or more portlets within the same portlet project. This is not the most common scenario; the only situations in which it is recommend that a portlet project contain multiple portlets would be when the portlets must communicate with one another (either through shared HttpSession data or through portlet-portlet communication), or where you are building a shared portlet library many different teams to use.

Sequential portlet development

Sequential portlet development is the simplest team development scenario. In this scenario, while all team members work in the same stream, only one developer works on a portlet project at any one time, and all the changes are made sequentially. As a result, this is no need to merge changes. This is shown in Figure 2 below:

Here, we see an example of sequential portlet development. In this scenario, Developer 1 creates a portlet called PortletTeamTest, and then releases it to the stream. Developer 2 catches up the new version of PortletTeamTest into her workspace from the stream, modifies the portlet, and then releases PortletTeamTest with change #1 to the stream. Developer 1 catches up change #2 of PortletTeamTest, modifies PortletTeamTest, and releases it with change #2 to the stream. Again, Developer 2 picks up change #2 from the stream. This cycle continues until PortletTeamTest is finalized.

This scenario assumes that no concurrent changes will occur on any portlet in the stream. A small team with mechanisms in their development process to prevent concurrent development can use this scenario successfully. These mechanisms are outside the scope of the Application Developer team support. Often, such mechanisms consist of e-mailing or communicating through instant messaging tools, or perhaps relying on a chart on a team white board to indicate who is currently working on a particular project.

Sequential portlet development simulation

To understand how sequential development works, you can simulate the sequential portlet development scenario with the two workspaces created in the Configuration section. In this scenario, you will create and release a single portlet within a portlet project. Here, you will work with a single portlet that extends HttpServlet along with its accompanying JSP within a single Application Developer Web project.

Developer 1: Create the portlet application and release the file to the stream

1. Switch to the Portlet perspective. Create a new Portlet Application project called PortletTeamTest. The default location is d:\workspace\cvsdev1\ PortletTeamTest.
2. On the Define the Portlet project page, complete as follows:
   1. In the Project name field, enter PortletTeamTest.
   2. Select the Use default location check box.
   3. In the Enterprise Application project name field, select PortletTeamEAR.
   4. In the Context root field, enter PortletTeamTest.
   5. Click Next.
3. You will use an MVC portlet for this test. Select MVC portlet, and click Next.
4. Click Finish to create the portal application.
5. Switch to the Team perspective. Right-click PortletTeamTest, and select Properties from the context menu. Switch to the Team category, and click Change.
6. Select the repository entry you created, and then select the HEAD stream, and click OK.
7. Click OK again to close the Properties dialog. The project is now assigned to the HEAD stream.
8. From the projects context menu, select Team => Synchronize with Stream. This opens the Release Mode in the Synchronize view.
9. Select the PortletTeamTest project entry in the Structure Compare Panel, and select Release from its context menu.
10. Enter the comment, Initial development completed, and click OK.

You have now created version 1.1 of the portlet in the HEAD stream.

Developer 2: Retrieve the file, make change #1, and release the portlet application to the stream

1. Switch to the Team perspective.
2. Refresh the Repositories view. Expand the HEAD stream and you will see the PortletTeamTest module.
3. Right-click PortletTeamTest, and select Add to Workspace.
4. Switch to the portlet perspective. Open view.jsp in page designer.
5. Replace the current text, Operating in View mode, with Change #1.
6. Save the changes and close the editor.
7. Right-click the PortletTeamTest project, and select Team => Synchronize with Stream. This opens the team perspective in Release Mode.
8. Right-click the project and select Release.
9. Add the comment, Change #1 completed, and click OK.

Now you have created version 1.2 of the portlet in the HEAD stream.

Developer 1: Catch up change #1, make change #2, and release the portlet application to the stream

1. Select the PortletTeamTest project. From its context menu, select Team => Synchronize with stream.
2. The Synchronize view opens in Catch-up mode. The view.jsp file is selected with the incoming change shown in the Java Source Compare panel.
3. From the context menu of the portlet, select the Catch-up menu option.
4. Switch back to the Portlet perspective. Open the view.jsp file in the page editor, and add, Change #2 to the text.
5. Right-click the PortletTeamTest project, and select Team => Synchronize with stream.
6. The View.jsp file is again displayed with an outgoing change. Select the portlet application in the Structure Compare view, and select Release.
7. Enter the comment, Change #2 completed, and click OK.

You have now created version 1.3 of the portlet application in the HEAD stream.

Developer 2: Catch up change #2

1. From the portlet perspective, right-click the PortletTeamTest project, and select Replace with => Stream contents.
2. Open the view.jsp file; you will see that both changes have been included in the file.
3. Right-click view.jsp, and select Team => Show in Resource History. The version number of view.jsp increments from 1.1 to 1.2 and then to 1.3 in the Resource History window. An asterisk is displayed next to 1.3 because it is the base version for view.jsp in the workspace of Developer 2.

Parallel portlet development

You will continue to develop the portlet created in the sequential portlet development scenario above. This scenario is shown in Figure 3 below. Both Developer 1 and Developer 2 catch up version 1.3 of the portlet from the stream. Developer 1 modifies the portlet and releases change #3 to the stream. Simultaneously, Developer 2 modifies the portlet and is ready to release change #4 to the stream. Developer 2 needs to merge change #3 made by Developer 1 with his change #4, and then release the portlet with both changes to the stream. Application Developer lets you detect the conflict, compare different versions of the files, and merge the changes in the stream.

Parallel portlet development simulation

The simulation in this section continues the simulation described above in the section, Sequential portlet development simulation.

Developer 1: Make change #3 and release the portlet to the stream

1. Open PortletTeamTest, and edit the view.jsp file. Add new text: Change #3.
2. Save the changes and close the editor.
3. Release the portlet to the stream, adding the comment, Change #3 completed. The portlet is stored as version 1.4 in the HEAD stream.

Developer 2: Make change #4 and merge changes #3 and #4

1. Developer 2 is unaware of the new version 1.4 and completes change #4 on her local copy, whose base version is still 1.3. To simulate this, open the portlet perspective, and edit the view.jsp file. Add new text: Change #4.
2. Save the changes and close the editor.
3. Synchronize the project PortletTeamTest with the HEAD stream. The Synchronize view opens in Catch-up mode. The view.jsp file is shown with a double-headed arrow icon, which means that changes have been made to the stream that conflict with the version that Developer 2 wants to release.
4. To view the cause of the conflict, select the portlet from the Navigator view, and launch the resource history on the resource.
5. We can see from the resource history that Developer 1 has made change #3 to the view.jsp file since the base version was created.
6. From the Structure Compare panel in the Synchronize view, double-click on view.jsp. This opens the Structure Compare panel.
7. Note the differences in files.
8. Catch up change #3.
9. Save the workspace edition of the portlet, which should contain both changes. Switch to the Release Mode.
10. Select the portlet and from its context menu. Select Release.
11. Enter the comment, Change #4 completed, and click OK.
12. Open the resource history for the portlet and notice that the new version is 1.5. If you release the portlet without merging the changes, the current top of the stream would have been replaced with a version of view.jsp that did not include change #3.

Developing multiple portlet applications in a single portal project

Developing multiple portlet applications in a single portal project is the most complex development scenario. In this scenario, while all team members work in the same stream, multiple developers work on different portlets of the same project simultaneously. Application Developer lets you detect the conflicts, compare different versions of files, and merge the changes in the stream (refer to Parallel portlet development section above). However, there is one caveat to consider when creating multiple portlets within a single project. This is discussed below.

Developing multiple portlet applications in a single portal project simulation

1. Developer 1 creates a portlet project called PortletTeamTest.
2. View the XML in Application Developer by clicking on portlet.xml and web.xml.
   
   Listing 3. The web.xml file
   
   
   Listing 4. The portlet.xml file
   
   
3. Developer 1 synchronizes and releases the content to CVS.
4. Developer 2 gets the project from the stream and adds it to her workspace. Developer 2 manually creates a second portlet, called Second Portlet, and adds it to the project.
   
   Note: You can manually create the portlet by updating web.xml and portlet.xml. Many developers find it faster to simply add portlets this way rather than by using the wizards. Regardless of which method you choose for creating your portlet, the issues remain the same.
   
   
5. View the XML in Application Developer by clicking on portlet.xml and web.xml.
   
   Listing 5. Modified web.xml file
   
   
   Listing 6. Modified portlet.xml file
   
   
   Listing 6. Modified portlet.xml file continued
   
   
6. Developer 2 synchronizes and releases the content to CVS.
7. While Developer 2 was creating her second portlet, Developer 1 was creating his Third Portlet.

Notice what happens with portlet.xml and web.xml when Developer 2 synchronizes with the stream. Here you see what happens when the references in the portlet.xml and web.xml files become misplaced. In particular, pay attention to the differences in the web.xml files shown in Figure 4 and the differences in the portlet.xml files shown in Figure 5. You can see that the servlet IDs are the same in the web.xml files, while the actual portlets the IDs refer to are different. Similarly, within the portlet.xml file, the internal references also point to different portlets.

When developing multiple portlet applications in a single portal project, you must use unique servlet IDs and portlet IDs. The Portlet Wizard increments the servlet IDs and portlet IDs sequentially from the last ID contained within its local copy of the web.xml and portlet.xml files. So, if you create a new portlet, it is recommended that you always manually edit both portlet.xml and web.xml to reflect unique IDs before releasing the portlet to the stream.

This is not a difficult task; the only issue is that you must remember to update not only the definitions but the references as well. Also, since the tool will not always indicate to you that the files differ (for example, if the portlet names and titles are the same, then the browser would not notice a difference between the two files), then you must always remember to perform this step, even when the comparison browser does not prompt you to do so. A better solution is to simply avoid the issue by restricting the creation of new portlets to sequential development. Ensure that only a single developer is working in a project when he or she creates a new portlet, and the problem will not arise.

Back to top

Conclusion

This article covered several portlet team development scenarios with WebSphere Studio Application Developer and CVS. It discussed some common development scenarios, and showed how team development for portals can proceed smoothly in most cases. In particular, keep the following recommendations in mind when developing portlets as a team:

• In portal projects containing only a single portlet, developers can choose to use either sequential or parallel development within the portlet project .
• If a portal project contains more than one portlet, multiple developers can work on the existing portlets contained within the project in either a sequential or parallel fashion in most cases.
• In the case where a portal project contains more than one portlet, development should only occur sequentially when a new portlet needs to be created within the portlet project. This is due to the problems resulting from duplicated IDs within the shared web.xml and portlet.xml files for the portlet project.

Back to top

Acknowledgments

The authors would like to thank Tim Hanis, Denise Hatzadakis, and Skyler Thomas for reviewing the article, and providing valuable suggestions and contributions.

About the authors

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Relationship between the web.xml and portlet.xml files
• Prerequisites
• Configuration
• Concurrent development scenarios
• Conclusion
• Acknowledgments
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Portal Express
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Portal Express

Dig deeper into WebSphere on developerWorks

Discover knowledge paths

Skill-building guides for WebSphere, Linux, open source, cloud, Java, business analytics, and more.

Special offers