JBoss.orgCommunity Documentation
Version: 1.0.1.GA
Copyright © 2008, 2009 JBoss, a division of Red Hat
September 2008
Starting from 3.0.0.Alpha1 version, JBoss set of plugins extends JBoss Portal features. Thus, this guide is intended to explain you how to manage the functionality JBoss Tools provide to ease the development with JBoss Portal.
JBoss Portal provides an open source platform for hosting and serving a portal's Web interface, publishing and managing its content, and customizing its experience. It supports a wide range of features, including standard portlets, single sign-on, clustering, and internationalization.
The next table lists key features supplied by JBoss Portal Tools.
Table 1.1. Key Functionality of JBoss Portal Tools
| Feature | Benefit | Chapter |
|---|---|---|
|
Wizards for creating Projects with Portlet Facets |
New Dynamic Web Project wizard allows you to select a proper Configuration to enable Portlet Facet in it. | Creating a Dynamic Web Project |
|
Create Java Portlet wizard |
The wizard enables creating a JSR-186/JSR-286 compliant portlet. | Adding Java Portlet to a project |
|
Create JSF/Seam Portlet wizard |
This wizard allows to create JSF/Seam portlets | Creating JSF Portlet Creating Seam Portlet |
Stable JBossTools/JBDS documentation (supplied with the latest JBDS release, 1.1.0 GA currently)
This section provides you with the steps on how to start with JBoss Portal and integrated features using JBoss Tools.
First, you need to have Eclipse Ganymede with JBoss Tools 3.0.0.Alpha1 and higher installed.
Tip:
Read JBoss Tools Installation section in our Getting Started documentation to find out how to install JBoss Tools onto Eclipse.
Next, download the JBoss Portal + JBoss AS bundle from JBoss Portal Download page
Note:
You need JBoss Portal 2.7 if you want to work with a Portlet 2.0
Extract the bundle wherever you want on your hard drive
Now, when you have it installed, we are going to demonstrate some powerful features of JBoss Portal tooling for Eclipse.
To get started with JBoss Portal and JBoss Tools, you should first have a Web Project pointed to the JBoss Portal Runtime. Thus, in this chapter we are going to show you how to create a Dynamic Web Project, add Java Portlet to it and deploy it to the JBoss Portal.
To create a Dynamic Web Project, go to File > New > Dynamic Web Project if you are in the Web Perspective or File > New > Other > Web > Dynamic Web Project in any other Perspective. The first page of the New Dynamic Web Project wizard looks as follows.
Fill out the name of your project. Next, click the New button in the Target Runtime section to specify a new Target Runtime. Choose JBoss Community > JBoss 4.2 Runtime and select the Create a new local server checkbox. Click Next.
On the next page you should give a name to the runtime. Let's call it JBoss Portal 2.7 Runtime , and then point it to the location of your JBoss AS + Portal installation.
Note:
The JBoss Tools Portlet feature has been tested using 2.6.5 and 2.7.0.ALPHA versions of JBoss Portal. Remember, if you want to use Portlet version 2.0 (JSR-268), you have to choose JBoss Portal 2.7.
At this point a new JBoss Server instance will be created. Here you can verify the defined runtime information. If something is incorrect, press Back to return on the previous wizard page.
Click Finish.
On the next step you should click the Modify button next to the Configuration section to enable Portlet Facets for the project.
On this page you should check the JBoss Core Portlet and press OK .
Note:
If the portlet libraries aren't available in the runtime you targeted, JBoss Portlet facets will be hidden on this page.
To made portal functionality always visible no matter what the runtime support, you should go to Window > Preferences and then JBoss Tools > JBoss Portlet and deselect Check runtimes for Portlet Components checkbox (see figure below).
The next page is for configuring web modules. Here all values are set, so you can leave everything as it is.
Finally, the last wizard page will ask you to add JBoss Portlet capabilities to your project. Here you can choose whether to set up user libraries, libraries provided by server runtime or not include libraries at all.
To set up server runtime libraries, you need to select Libraries provided by server runtime in the list box.
For setting up user libraries, select User library in the list box and then press Add in the User Library section.
Then press New and type the user library name in the appeared dialog.
Next add necessary jar's.
Hit OK. The user library will be added.
If you don't need to include libraries at all, just deselect the Enable implementation library checkbox.
After setting JBoss Portlet capabilities press Finish.
That's it! Our base project is done.
Now, let's look at the structure of the just created project.
Here JBoos Tools added JBoss Portlet facet to the project, created an empty portlet.xml file and added the Portlet library to the project classpath.
At this point we'll show what the steps you need to proceed to add a new Java Portlet to the project.
Call the Create Portlet wizard by selecting New > Other > JBoss Tools Web > Portlet > Java Portlet.
The wizard fills in the Web Project and Source Folder fields for you. Then you need to specify the Java package and the Class name and click Next .
On the other page you will be able to set the display name of the Portlet, a title, a description, the supported modes and init parameters.
On the next screen you can define which methods from GenericPortlet you want to override.
The last screen lets you build JBoss Portal specific descriptors to create an instance during the deployment and place it directly on the Portal.
Tip:
If you uncheck the Create Portlet Instance checkbox, JBoss Tools won't create the deployment elements in the default-object.xml and portlet-instances.xml files.
Once Java Portlet is created, new resources have been added to the project structure. As you can see on the figure below, it adds a Java Portlet class ( TestPortlet.java in our case), default-object.xml and portlet-instances.xml files and updates portlet.xml as well.
Thus, now the Project is ready to be built and deployed.
You can deploy the created project in the way you deploy any other Web Application. Right click on the project and do Run As > Run On Server and accept the defaults. On the Add and Remove Projects page move the created Project to the right and click Finish.
It will deploy the Portlet Web Application and start JBoss AS.
Tip:
You should use http://localhost:8080/portal URL to see your Portlet in the Browser.
In the Browser the Portlet looks as follows:
Consequently, here you learnt how to create a Dynamic Web Project, add Java Portlet to it and deploy the project to JBoss Portal.
This chapter will explain how you can configure JSF Portlet within Dynamic Web Project and JSF Project by using the wizards JBoss Tools provides.
To add JSF Portlet to a Dynamic Web Project, you should set the Configuration to JavaServer Faces v1.1 Project or JavaServer Faces v1.2 Project and configure the JSF Portlet Facets in the New Dynamic Web Project wizard by clicking the Modify button.
On the Project Facets dialog you should select JBoss Core Portlet and JBoss JSF Portlet check boxes.
Next wizard page is for configuring JSF Capabilities. You can leave everything as it is here.
To support Portlets in JSF/Seam applications JBoss Tools works with JBoss Portlet Bridge. Thus on the next page you should add JSF Portlet capabilities by pointing to the Portletbridge Runtime location.
Tip:
You can download JBoss Portlet Bridge 1.0.0.B4 from here.
Next click Finish to organize the Project.
To add JSF Portlet to generated project you should call the Create Portlet wizard by navigating to New > Other > JBoss Tools Web > Portlet > JSF/Seam Portlet.
As you see, the Seam and JSF Portlet wizards are merged into one. We set JSF Configuration for the project, so default values in this wizard will be set as for a JSF portlet.
Click Finish to complete JSF Portlet creation. Now you can deploy the project the same way as it was described above.
In the Browser JSF Portlet looks as follows.
How to organize a JSF Project you can find out in our JSF Tools Reference Guide. Just remember to point Target Runtime to JBoss Portal directory location.
Before adding a Portlet to the project you should enable necessary facets for it. Right-click the created project and click Preferences to open the Project Preferences screen.
On the Project Facets page select the JBoss Core Portlet and JBoss JSF Portlet checkboxes. And then the screen will ask you to enable JavaServer Faces facet as well.
Notice, "Further configuration required..." warning appears at the bottom of the screen. It means that you should click it to configure JSF and JSF Portlet Capabilities in the project.
After setting the path to Portletbridge Runtime location, click OK and then OK again.
Now you can add JSF Portlet to the generated JSF Project. How to do it we showed in the previous section.
This chapter covers the steps on how to configure Seam Portlet within Dynamic Web Project and Seam Project by using the wizards JBoss Tools provides.
To add Seam Portlet to a Dynamic Web Project first you should organize New Dynamic Web Project with the Configuration setting to JBoss Seam Portlet Project v2.0.
It will add all needed facets to your project. By clicking the Modify button you can observe the chosen configuration of facets as well as modify it. As you can see, all JBoss Portlets are checked.
Next wizard pages are for adjusting the Project Web Modules and JSF Configuration. They include default values, so you can skip them by pressing Next.
On the Seam Facet page set Connection Profile and hit Next.
Last wizard page will prompt you to set the path to Portletbridge Runtime location.
Tip:
Thus you should have JBoss Portlet Bridge downloaded and extracted somewhere on your hard drive. You can download JBoss Portlet Bridge 1.0.0.B4 from www.jboss.org/portletbridge/download.
Now, to add Seam Portlet to the project you should follow to New > Other > JBoss Tools Web > Portlet > JSF/Seam Portlet. This will call the wizard for creating JSF/Seam Portlets.
As we set Seam Configuration for the Dynamic Web Project, the wizard puts the values as for Seam Portlet.
After creating the Seam Portlet, you should deploy the project to JBoss Portal and start the Server. In a Browser you'll see the following:
First start a Seam Project by following to New > Other > Seam > Seam Web Project. On the first wizard page specify JBoss Portal directory location as Target Runtime and JBoss Seam Portlet Project v2.0 as Configuration.
Next steps will be the same as we did for the Dynamic Web Project in the Adding Seam Portlet to Dynamic Web Project section.
Starting from JBoss Tools 3.0.0.Beta1 version the JBoss Portlet wizards no longer require a WTP project to be able to create Portlets.
Note:
Please note, if the project does not have the proper portlet API jar's, the generated classes will have compile errors.
In conclusion, with this document you've learnt how to get started with JBoss Portal using JBoss Tools suite of Eclipse plugins. The above chapters walked you through the steps on how to organize a web project with portlets which includes a sample staff and deploy it onto the JBoss Portal.
If you still have questions or suggestions you are always welcome on our Forum. Your feedback will be very much appreciated.