Starting from 3.0.0.Alpha1 version, the JBoss set of plugins includes tools for supporting JBoss Portal and JSR-186/JSR-286 portlets. Thus, this guide provides instructions on how to get started and manage JBoss Portlet Tools.
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.
With JBoss Portlet Tools you can easily create a Java, JSF and Seam portlet and deploy it to JBoss Portal.
JBoss Portlet Tools supports the JSR-168 Portlet Specification (Portlet 1.0) and JSR-286 Portlet Specification (Portlet 2.0) and works with JBoss Portlet Bridge for supporting Portlets in JSF/Seam applications. To enable these features, you need to add the JBoss Portlet facet to a new or an existing web project (see Chapter 2, JBoss Portlet Tools Tasks). The project could be a non-WTP project, but you should know that if it does not have the proper portlet API JAR's, the generated classes will have compile errors.
The next table lists key features supplied by JBoss Portlet Tools.
Table 1.1. Key Features of JBoss Portlet Tools
Feature | Benefit | Chapter |
---|---|---|
JBoss Portlet facets |
JBoss Portlet Tools provides the Java, JSF and Seam Portlet facets that could be enabled for a Web project. | Chapter 2, JBoss Portlet Tools Tasks |
Java Portlet wizard |
The wizard helps create a JSR-186/JSR-286 compliant portlets | Section 3.2.1, “Java Portlet Wizard” |
JSF/Seam Portlet wizard |
This wizard helps create JSF/Seam portlets | Section 3.2.2, “JSF/Seam Portlet Wizard” |
This chapter shows how to create a Dynamic Web Project, add a Java Portlet to it and deploy it to the JBoss Portal.
Follow the next procedure to create a Web project with JBoss Portlet capabilities pointed to the JBoss Portal runtime.
Select Web perspective or select → → → → in any other perspective. This will display the New Dynamic Web Project wizard.
→ → if you are in theSpecify the name of the project.
Click the Target Runtime area to create a JBoss Portal runtime. Choose JBoss Community > JBoss 4.2 Runtime and select the Create a new local server check box below. Click the button.
in theThe New Server Runtime Environment wizard appears. In the Name field, type JBoss Portal 2.7 Runtime, and then use the button to point to the location of JBoss Portal + JBoss AS extracted. Click button to proceed.
At this point a new JBoss Server instance will be created. On the next page you can verify the runtime information and configuration. If something is incorrect, press the
button to return to the previous wizard page. Click the button.Click the Configuration area to enable a portlet facet for the project.
button in theIn the Project Facets dialog, check JBoss Core Portlet and click the button.
If the portlet libraries aren't available in the runtime you targeted, JBoss Portlets facets will be hidden on this page.
To make them always visible no matter what the runtime is set, you should enable the appropriate option in Section 3.3, “JBoss Portlet Preferences”.
The Java and Web Module pages are for configuring Java and Web modules in the project. Here the default values are fine, so leave everything as it is.
The last wizard page will ask you to add JBoss Portlet capabilities to the project. Select Portlet Target Runtime Provider and click the button to complete the project creation.
All types available under Portlet Implementation Library are fully described in the Wiki article at: http://www.jboss.org/community/wiki/PortletFacetLibraries.
As the result, JBoss Portlet Tools adds
JBoss Core Portlet
facet to the project,
creates an empty portlet.xml
file and adds the JBoss Portlet library to the project classpath.
At the previous section you have created a web project with JBoss Portlet capabilities. The next steps will show you how to add a new Java portlet to the project.
Right-click the project and select
→ → → → .The Create Portlet wizard starts (for information about the wizard options, see Section 3.2.1, “Java Portlet Wizard” in the guide reference). The wizard fills in the Project and Source Folder fields for you. You should specify a Java package and a class name (for instance, org.example and TestPortlet). Then click the button.
You may leave the next three pages with default values, on the last one click the
button.
Once a Java portlet is created, new resources are added to the project structure: a Java portlet class (TestPortlet.java
), default-object.xml
and portlet-instances.xml
files and the portlet.xml
descriptor is updated as well.
Now the project is ready to be built and deployed.
You can deploy a portlet project in the way you deploy any other web application.
Right-click the project and select Run On Server wizard starts.
→ . TheSelect JBoss Portal 2.7 Server created before and click the button.
On the Add and Remove page move the created project to the right and click Finish.
It will deploy the portlet application and start JBoss AS.
Use the http://localhost:8080/portal/portal/default/default URL to see your portlet in the browser.
This chapter will explain how you can configure a JSF portlet within a JSF project with JBoss Portlet capabilities and then deploy it to JBoss Portal.
You can create a JSF project with JBoss Portlet capabilities in two ways:
Create a dynamic Web project with the JavaServer Faces and JBoss JSF Portlet facets enabled (see Section 2.2.1.1, “Creating a Dynamic Web Project with the JBoss Portlet Capabilities”)
Or create a JSF project using the wizard provided by JBoss JSF Tools, then enable JSF and JBoss Portlet facets and add JBoss Portlet capabilities (see Section 2.2.1.2, “Creating a JSF Project and adding the JBoss Portlet Capabilities”)
Refer to the further sections for the procedures on how to do this.
The basic steps to create a dynamic Web project with the JBoss Portlet capabilities are as follows:
Start the Dynamic Web Project wizard navigating to → → → → .
You can also select the Java EE perspective and then selecting → → .
Specify the project name and set the target runtime to JBoss Portal by following the points 3, 4 and 5 in the Section 2.1.1, “Creating a Web Project with JBoss Portlet Capabilities” procedure.
In the Configurationarea, click the button and enable JavaServer Faces,JBoss Core Portlet and JBoss JSF Portlet facets. Click the button.
You may leave the next two wizard pages with their defaults, just press the
button to proceed.On the JBoss Portlet Capabilities page, select Portlet Target Runtime Provider and click the button.
All types of the portlet implementation library are described more closely in the wiki article at: http://www.jboss.org/community/wiki/PortletFacetLibraries.
Next wizard page is for configuring JSF capabilities. You can leave everything as it is here.
On the JBoss JSF Portlet Capabilities page, select JSF Portlet Target Runtime Provider as the JSF portlet implementation library. It will copy Portlet Bridge libraries from the server runtime to the project classpath.
On this page, it is also possible to add the RichFaces libraries from the RichFaces distribution by checkingAdd/Change Richfaces Libraries.
You can select the JSF Portletbridge Runtime Provider type. Then it is necessary to set the home of the Portlet Bridge distribution.
For information about all the JSF Portlet facet library providers, refer to the wiki article at: http://community.jboss.org/wiki/PortletFacetLibraries.
Click the
button. The project will be created in the workbench.For information on how to organize a JSF project you can read the JSF Tools User Guide. Just remember to point the target runtime to JBoss Portal directory location (see how it is done for a dynamic Web project with steps 3, 4 and 5 in the Section 2.1.1, “Creating a Web Project with JBoss Portlet Capabilities” procedure).
To add the JBoss Portlet capabilities to the JSF project you should complete the next steps:
Right-click the project and click Properties sheet. Select Project Facets on the left and enable the JavaServer Faces, JBoss Core Portlet and JBoss JSF Portlet facets.
to open the projectNotice that the "Further configuration available..." warning appears at the bottom of the screen. It means that next you should configure the JSF Portlet capabilities in the project. Click the link. The Modify Faceted Project wizard appears.
Complete all wizard pages the same way as described in the steps 5, 6, 7 of the Section 2.1.1, “Creating a Web Project with JBoss Portlet Capabilities” procedure. Click the button.
To apply the changes click the Properties sheet.
button and then the button to close the projectThe previous section demonstrated how to create a JSF project with JBoss Portlet and JSF Portlet capabilities enabled. Use the following procedure to add a JSF portlet to the created project and deploy it to JBoss Portal.
Display the Create Portlet wizard by selecting → → → → from the context menu of the project (for information about the wizard options, see Section 3.2.2, “JSF/Seam Portlet Wizard” in the guide reference).
As you see, the JSF and Seam Portlet wizards are merged into one. We have set the JSF configuration for the project, so the default values in this wizard will be set as for a JSF portlet.
Leave all the wizard pages with default values by clicking the
button, on the last one click the button to complete the JSF portlet creation.Complete the steps described in the Section 2.1.3, “Deploying a Portlet to JBoss Portal” procedure to deploy a JSF portlet to JBoss Portal. Just use the other URL to see it in the browser: http://localhost:8080/portal/portal/default/JSFPortlet.
This chapter covers the steps required to configure a Seam portlet within a Seam project with the help of the JBoss Portlet Tools features.
One of the following two procedures can be used to create a Seam project with JBoss Portlet capabilities enabled:
Create a dynamic Web project with the Seam and JBoss Portlets facets enabled (see Section 2.3.1.1, “Creating a Dynamic Web Project with Seam and JBoss Portlet Capabilities”)
Create a Seam project with the JBoss Seam portlet configuration using the wizard JBoss Seam Tools provides and follow all the wizard steps to enable JBoss Portlet capabilities (see Section 2.3.1.2, “Creating a Seam Project with JBoss Portlet Capabilities”)
To create a dynamic Web project with Seam and JBoss Portlet capabilities you should complete the following steps:
Select. New Dynamic Web Project wizard will then be displayed.
→ → → → . TheGive the project a name and follow the steps 3, 4, 5 of the Section 2.1.1, “Creating a Web Project with JBoss Portlet Capabilities” procedure to set the target runtime.
In the Configuration area of the first wizard page, select JBoss Seam Portlet Project v2.0. It will add needed facets to the project.
If you now click the JavaServer Faces,Jboss Portlets and Seam facets enabled.
button, you should see theThe next two pages are for adjusting the project Java and Web modules. They include the default values, so you can skip them by clicking the
button.On the Jboss Portlet Capabilities page, select Portlet Target Runtime Provider as the portlet implementation library.
All types of the portlet implementation library are described more closely in the wiki article at: http://www.jboss.org/community/wiki/PortletFacetLibraries.
The next page is for configuring JSF capabilities. As it contains the default values, just click the
button to proceed.On the Seam Facet page, set a Seam runtime and a connection profile.
For details about how to set a Seam runtime and a connection profile, see Configure Seam Facet Settings in the Chapter 2 of the Seam Dev Tools Reference Guide.
On the JBoss JSF Portlet Capabilities page, select the JSF Portlet Target Runtime Provider type of the implementation library.
If you have JBoss Portlet Bridge downloaded, alternatively you can select JSF Portletbridge Runtime Provider and then provide a path to the JBoss Portlet Bridge distribution.
It will add JBoss Portlet Bridge libraries to the project classpath.
Click the
button to complete the project creation.The steps to create a Seam project with JBoss Portlet capabilities are as follows:
Select New Seam Project wizard will be displayed.
→ → → → . TheNext steps are the same as in the Section 2.3.1.1, “Creating a Dynamic Web Project with Seam and JBoss Portlet Capabilities” procedure starting from the step 2.
The previous section has demonstrated how to create a Web project with Seam and JBoss Portlet capabilities. Now you can create a Seam portlet and deploy it to JBoss Portal by following the next procedure:
Select
→ → → → → .The Create Portlet wizard is displayed (for more information about wizard options, see Section 3.2.2, “JSF/Seam Portlet Wizard” in the guide reference). As the Seam configuration is set for the project, the wizard enters the values for the Seam portlet.
Next two pages are filled out with default values, just click the
button to proceed. On the last one click the button to complete the procedure.To deploy and run the portlet on JBoss Portal complete the steps described in the Section 2.1.3, “Deploying a Portlet to JBoss Portal” procedure. Just use the following URL to see it in the browser: http://localhost:8080/portal/portal/default/SeamPortlet.
This chapter includes detailed reference information about JBoss Portlet Tools.
In order to a web project with portlets could be deployed to JBoss Portal, it should include certain descriptors. The next table lists and describes these configuration files.
Table 3.1. JBoss Portlet Descriptors
Name | Description |
---|---|
portlet.xml | The mandatory portlet descriptor defined by the JSR-168 Portlet Specification. It is used during deployment. |
portlet-instances.xml | The optional JBoss Portal specific descriptor. It allows to create a portlet instance from a portlet class definition. |
*-object.xml | The optional JBoss Portal specific descriptor. It helps define the layout of the portal. |
jboss-portlet.xml | The optional JBoss Portal specific descriptor. It allows to use JBoss specific functionality within a portlet application. |
For more detail information about each descriptor, see "Portlet Descriptors" in Chapter 6, "JBoss Portal Reference Guide".
This section describes the JBoss Portlet Tools wizards:
The Java Portlet wizard helps you create a new Java portlet (1.0 or 2.0). It is based on the WTP's Create Servlet wizard, but adapted to JBoss Portlet. You can call it from the File or context menu of your project by following to New > Other > JBoss Tools Web > Portlet > Java Portlet.
The wizard consists of the four pages:
The first one includes the next options to adjust:
Table 3.2. Java Portlet Wizard. First Page Options.
Option | Description | Default |
---|---|---|
Project | Select the project to add a new Java portlet | The project selected when the wizard has been started |
Source folder | The path to the source folder relative to the selected project | The source folder of the project selected in the Project field |
Java package | Enter a package to contain a new portlet. Either type a valid package name or click Browse to select a package via the dialog box. | <blank> |
Class name | Type a name for a new Java portlet class | <blank> |
Superclass | Type or click Browse to select a superclass for a Java portlet class | javax.portlet.GenericPortlet |
Use an existing Portlet class | Select this check box if you want to use an existing Java portlet class. In the appeared Class name field type or click Browse to select an existing portlet class. | Cleared |
The second wizard page is for specifying modifiers, interfaces to implement and method stubs to generate.
The descriptions of the options listed on this page are in the following table.
Table 3.3. Java Portlet Wizard. Second Page Options.
Option | Description | Default |
---|---|---|
Modifiers | Select one or more access modifiers for a new Java portlet class:
| Public |
Interfaces | Click Add to choose interfaces that a new class implements | <blank> |
Which method stubs would you like to create? | Choose which methods from superclass to override in the Java portlet class:
| Inherited abstract methods, doView |
The third page is for adjusting the portlet deployment descriptor settings.
Table 3.4. Java Portlet Wizard. Third Page Options.
Option | Description | Default |
---|---|---|
Name | Enter the portlet name. It does not have to be the portlet class name. | The name of the portlet class |
Display name | Enter the display name of the Java portlet | The name of the portlet class |
Title | Enter the title of the portlet | The name of the portlet class |
Description | Enter the description of the portlet's function | <blank> |
Portlet Modes | Select one or more of three modes defined by the JSR-286 specification:
| View |
Initialization Parameters | Specify initialization parameters to create an initial state inside your portlet class. Click Add and fill in the Name, Value and Description (optional) fields to set a parameter. | <blank> |
The last wizard page helps configure the JBoss Portlet specific descriptors.
Table 3.5. Java Portlet Wizard. Last Page Options.
Option | Description | Default |
---|---|---|
Create Portlet Instance | Clear the Create Portlet Instance check box,
if you don't wont the wizard to create the deployment elements
in the default-object.xml and
portlet-instances.xml files | Selected |
If Exists | Select one of two options:
| overwrite |
Instance Name | Enter a name of the portlet instance that the portlet window represents | [Portlet class name]Instance |
Page Name | If set, the portlet page is created with the name defined | <blank> |
Window Name | Enter a name of the portlet window | [Portlet class name]Window |
Parent Reference |
Define a reference to the parent object. The syntax for this element is For example, | default.default |
Region | Specify the region where the window should appear on the page | center |
Height | Define the height of the window | 1 |
Initial Window State | Set the window state indicator by selecting one of three states defined by the JSR-168 specification:
| maximized |
The JSF/Seam Portlet wizard, that is merged into one JSF and Seam Portlet wizards, helps you create a JSF/Seam portlet that uses the JBoss Portlet Bridge libraries. The default values in this wizard depend on the configuration set for the project. For instance, if you set the JSF configuration, the default values in this wizard will be as for a JSF portlet.
The JSF/Seam Portlet wizard could be started from the File or context menu of your project by following to New > Other > JBoss Tools Web > Portlet > JSF/Seam Portlet.
The wizard includes three pages to adjust JSF/Seam portlet setting:
The first wizard page asks to select a project to add JSF/Seam portlet and set a class file destination.
Table 3.6. JSF/Seam Portlet Wizard. First Page Options.
Option | Description | Default |
---|---|---|
Project | Select the project to add a new JSF/Seam portlet | The project selected when the wizard has been started |
Class name | Type or click Browse to select a class for a JSF/Seam portlet | javax.portlet.faces.GenericFacesPortlet |
The second page allows to configure a portlet deployment descriptors.
Table 3.7. JSF/Seam Portlet Wizard. Second Page Options.
Option | Description | Default (JSF / Seam) |
---|---|---|
Name | Enter the portlet name. It does not have to be the portlet class name. | riPortlet / seamPortlet |
Display name | Enter the display name of the Java portlet | JBoss JSF Portlet / JBoss Seam Portlet |
Title | Enter the title of the portlet | JBoss JSF Portlet / JBoss Seam Portlet |
Description | Enter the description of the portlet's function | <blank> |
Portlet Modes | Select one or more of three modes defined by the JSR-286 specification:
| View, Edit, Help / View |
Initialization Parameters | Specify initialization parameters to create an initial state inside your portlet class. Click Add and fill in the Name, Value and Description (optional) fields to set a parameter. | javax.portlet.faces.defaultViewId.view, javax.portlet.faces.defaultViewId.edit, javax.portlet.faces.defaultViewId.help / javax.portlet.faces.defaultViewId.view |
The last wizard page helps you configure the JBoss Portlet specific information.
Table 3.8. JSF/Seam Portlet Wizard. Third Page Options.
Option | Description | Default (JSF / Seam) |
---|---|---|
Create Portlet Instance | Clear the Create Portlet Instance check box,
if you don't wont the wizard to create the deployment elements
in the default-object.xml and
portlet-instances.xml files | Selected |
If Exists | Select one of two options:
| overwrite |
Instance Name | Enter a name of the portlet instance that the portlet window represents | JSFPortletInstance / SeamPortletInstance |
Page Name | If set, the portlet page is created with the name defined | JSFPortlet / SeamPortlet |
Window Name | Enter a name of the portlet window | JSFPortletWindow / SeamPortletWindow |
Parent Reference |
Define a reference to the parent object. For example, | default |
Region | Specify the region where the window should appear on the page | center |
Height | Define the height of the window | 1 |
Initial Window State | Set the window state indicator by selecting one of three states defined by the JSR-168 specification:
| maximized |
Create JBoss Application |
Select to add the riPortletApp / seamPortletApp - the default name of the JBoss application. You can change it by typing a new one in the JBoss Application Name field. | Selected |
Add the jboss-portlet.xml file | Select to create the jboss-portlet.xml file | Selected |
Copy JSF Templates | Select to add the folder with JSF templates (edit.jsp , help.jsp ,
view.jsp ) to the project | Cleared |
To open JBoss Portlet Preferences property sheet, go to → and then →
The Check runtimes for Portlet Components option makes the JBoss Portlet functionality always visible no matter what the runtime is set. By default the option is checked.
In conclusion, with this document you could easily get started with JBoss Portlet Tools. The above chapters walked you through the steps on how to organize a web project with JBoss Portlet capabilities enabled, create a Java portlet, JSF or Seam portlet and deploy them to JBoss Portal. The document also includes the reference of JBoss Portlet Tools features.
If you have questions or suggestions concerned both the documentation and tools behavior, you are welcome to JBoss Tools Users forum.
Please, use Jira to report bugs and requests on documentation.
JBoss Portal home page: http://www.jboss.org/jbossportal/
JBoss Portal Wiki at: http://wiki.jboss.org/wiki/JBossPortal
JBoss Portal documentation set at: http://docs.jboss.org/jbportal/
JBoss Tools home page at: http://www.jboss.org/tools/
The latest JBossTools/JBDS documentation builds at: http://download.jboss.org/jbosstools/nightly-docs/
JBoss Developer Studio/JBoss Tools release documentation you can find at http://docs.jboss.org/tools in the corresponding release directory.