Deploying a Portlet to Sun Java Portal Server

April 2006 [Revision number: V2.1-1]

Copyright 2006 Sun Microsystems, Inc.

This tutorial describes the process of deploying a JSR-168-compliant JavaServer Faces portlet application that you developed using Sun Java Studio Creator's Integrated Development Environment (IDE) to a stand-alone Sun Java System Portal Server. You create a web application archive (WAR) file for your portlet using the IDE, configure settings in the portal server, and then deploy the WAR file on the Sun Java System Portal Server. To complete this tutorial, you must have access to a stand-alone Sun Java System Portal Server and you should be familiar with portal server technology. If you are unfamiliar with the Sun Java System Portal Server, download it, install it, and read its documentation before proceeding with this tutorial. Make sure that you download and install the latest available version of the Sun Java System Portal Server. You need to use at least version 6. Online help is available from the portal server menu. This tutorial is based upon Sun Portal Server versions 6 and 7 for the Solaris operating system. Before you deploy your portlet to a stand-alone Sun Java System Portal Server, you must first ensure that the portlet deploys successfully to the Apache Pluto Portlet container that is bundled with the IDE. If your application uses JDBC data sources, you must integrate the corresponding database drivers into the portal server before you deploy your portlet. Contents - About Portlet Deployment - Exporting the Portlet WAR File - Configuring EJB Components in the sun-web.xml File - Adding the sun-web.xml File Into the Exported WAR File - Configuring a Sample Data Source - Deploying the Portlet on Sun Portal Server 6 - Deploying the Portlet on Sun Portal Server 7

About Portlet Deployment

Deploying portlet applications is similar to deploying regular web applications. Before you work through this tutorial, familiarize yourself with the deployment process and with portlet development. Creating a Portlet Application is a useful introduction to creating portlets using the IDE. As you develop a portlet application, you test it by building and running it from the IDE. The IDE automatically deploys the portlet application to its built-in portlet container, the Apache Pluto Portal server. When you complete developing and testing the portlet, you deploy it to a production portal server. The first step in the deployment process is to create a web application archive (WAR) file for the portlet so that you can deploy it to a stand-alone Sun Java System Portal Server. The WAR file contains the complete portlet in compressed form. If your portlet application uses Enterprise JavaBeans (EJB) components or data sources, you ensure that they are correctly configured for the target Sun Application Server by editing the container-specific deployment descriptor file, sun-web.xml. The sun-web.xml file is automatically created when you run the project. You next add the modified sun-web.xml file to the portlet's exported WAR file and copy the WAR file to the system on which you installed the target Sun Java Portal Server. If your portlet application uses database tables, you must configure the portlet's JDBC resources on the target Sun Application Server before you deploy the portlet. If your portlet application does not reference EJB components or data sources, you do not need to make any changes. After you export the portlet WAR file, your portlet is ready for deployment. To deploy to Sun Portal Server 6, see Deploying the Portlet on Sun Portal Server 6. To deploy to Sun Portal Server 7, see Deploying the Portlet on Sun Portal Server 7.

Exporting the Portlet WAR File

1. In the Projects window, right-click the portlet node and choose Export WAR File from the pop-up menu. The Export WAR dialog box opens, as shown in the following figure.

Figure 1: Export WAR Dialog Box 2. Choose the J2EE platform that matches the platform of the target web container on which your production portal server is running. If you are not sure, check with your portal administrator for the correct platform. 3. Select a file name for the exported WAR file and then click OK. The IDE builds the portlet WAR file and displays a BUILD SUCCESSFUL message when the build process completes. If the process is not successful, the IDE displays an appropriate error message.

Configuring EJB Components in the sun-web.xml File

The next sections explain how to configure the EJB component references within the sun-web.xml file and how to repackage the sun-web.xml file within the WAR file you just exported. This ensures that the databases or EJB components referenced by your portlet application are correctly configured for your target production portal server: the JNDI names referenced in your sun-web.xml file must match the resources configured on your target server. If your portlet application does not reference EJB components or databases, you do not need to make any modifications and your portlet is ready for deployment. To deploy to Sun Portal Server 6, see Deploying the Portlet on Sun Portal Server 6. To deploy to Sun Portal Server 7, see Deploying the Portlet on Sun Portal Server 7. 1. In the IDE, run the portlet project. Running the portlet project automatically generates a sun-web.xml file that contains all the necessary XML portlet deployment descriptor tags. 2. From the Files window, expand your-portlet-project > web > WEB-INF, where your-portlet-project is the name of your portlet application. 3. Right-click the sun-web.xml file and choose Edit from the pop-up menu. The sun-web.xml file opens in the IDE. 4. Copy the entire contents of the sun-web.xml file. Outside of the IDE, create a sun-web.xml file in a different directory and paste the contents into the new sun-web.xml file. For example, the sun-web.xml file for a portlet application named AllServices is similar to the following.

Code Sample 1: Sample sun-web.xml File <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc. //DTD Application Server 8.1 Servlet 2.4//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd "> <sun-web-app error-url=""> <!--# ++ properties ++ #Fri Jan 27 10:04:06 MST 2006 project.is_portlet=true project.portlet_name=AllServices project.web_context=/AllServices --> <context-root>/AllServices</context-root> <ejb-ref> <ejb-ref-name>GreeterEJB</ejb-ref-name> <jndi-name>corbaname:iiop:localhost:23700#GreeterEJB</jndi-name> </ejb-ref> <resource-ref> <res-ref-name>jdbc/Travel</res-ref-name> <jndi-name>jdbc/Travel</jndi-name> </resource-ref> <class-loader delegate="false"/> <jsp-config> <property name="classdebuginfo" value="true"> <description>Enable debug info compilation in the generated servlet class</description> </property> <property name="mappedfile" value="true"> <description>Maintain a one-to-one correspondence between static content and the generated servlet class' java code</description> </property> </jsp-config> </sun-web-app>

Note that the EJB component reference <jndi-name>corbaname:iiop:localhost:23700#GreeterEJB</jndi-name> refers to localhost. To correctly configure the EJB component reference, replace localhost with the name of your Sun Java Portal Server host machine.

Adding the sun-web.xml File Into the Exported WAR File

This section explains how to add the modified sun-web.xml file into your exported portlet WAR file. 1. Create a directory with the same name as the WAR file, then copy the WAR file into the directory. 2. Extract the WAR file contents as follows: jar xvf warfilename where warfilename is the name of your portlet project's exported WAR file. For example, if you exported a WAR file named JDBCPortlet. WAR to your project's dist directory on the Solaris operating system, you would use commands similar to the following: Code Sample 2: Extracting the Exported WAR File cd Creator/Projects/JDBCPortlet/dist mkdir JDBCPortlet cd JDBCPortlet jar xvf ../JDBCPortlet.war

3. Copy the sun-web.xml file that you created in the previous section to the portlet project's WEB-INF directory. For example: cp ../../web/WEB-INF/sun-web.xml ./WEB-INF 4. In the portlet application's project directory, remove the original exported WAR file. 5. Recreate the WAR file. For example: jar cvf ../JDBCPortlet.war *

The process of recreating the WAR file adds the modified sun-web.xml file to the exported WAR file. 6. Copy the modified WAR file to the target system on which your Sun Java Portal Server is installed. The exported WAR file's default location is in the portlet project directory's dist directory. For example, Creator/Projects/ portletname/dist/portletname.war.

Configuring a Sample Data Source

If your portlet application references databases, you must create the JDBC resources on the application server or portal server's host machine. This section explains how to create a JDBC resource that points to the Travel sample data source in Java Studio Creator 2 Update 1. The instructions use the Sun Application Server Admin Console. You use similar steps to configure any data source on your Sun Application Server. If your portlet application does not reference databases, your portlet is ready for deployment. To deploy to Sun Portal Server 6, see Deploying the Portlet on Sun Portal Server 6. To deploy to Sun Portal Server 7, see Deploying the Portlet on Sun Portal Server 7. 1. Log in to the Sun Application Server Admin Console on your portal server's host machine using your administrator login and password. For example, go to https:// hostname :portnumber , where hostname is the name of your Sun Application Server host and portnumber is the port number where the Admin Console resides. 2. In the Common Tasks window of the Admin Console, expand Resources > JDBC, then choose Connection Pools. The Connection Pools window opens, showing the current connection pools, similar to the following figure.

Figure 3: Connection Pools 3. Click New. The Create Connection Pool wizard opens in your web browser. 4. Enter the following values in the General Settings section: Property Value Name TravelDBPool Resource Type Choose javax.sql.DataSource from the drop-down menu. Database Vendor Leave this text field blank. 5. Click Next. The page refreshes, showing the information you just entered as well as the default Datasource Classname. 6. Enter a name in the Datasource Classname field (for example, com.sun.sql.datasource.DriverAdapter) and click Next. More Connection Pool wizard sections display, including the Pool Settings, Connection Validation, Transaction Isolation, and Properties sections. You accept the default values for most of these sections. 7. Enter the following values in the Properties section: Property url Value jdbc:derby//hostname:21527/sample

Username travel Password travel driverClassName org.apache.derby.jdbc.ClientDriver User travel 8. Click Finish. The Connection Pool window opens in the admin console. The Current Pools list includes TravelDBPool. 9. Create a JDBC resource that points to the TravelDB connection pool. From the Common Tasks window, expand the Resources > JDBC nodes, then click JDBC Resources. The JDBC Resources window opens in your web browser, displaying a list of current resources, similar to the following figure.

Figure 4: JDBC Resources Window 10. Click New. The JDBC Resource wizard opens, as shown in the following figure.

Figure 5: JDBC Resources Wizard 11. Enter the following values: Resource Value JNDI Name jdbc/Travel Pool Name Choose TravelDBPool from the drop-down menu. Enable Status Targets Click the Add button to move server from the Available pane to the Selected pane.

12. Click OK.

The JDCB Resources window opens in your web browser. The jdbc/Travel resource appears in the Current Resources list. 13. Copy the driveradapter.jar library from the Sun Java Studio Creator installation directory to the Sun Application Server lib directory. For example, on the Solaris operating system, copy ${CREATOR_HOME}/SunAppServer8/lib/driveradaptor.jar to /opt/ SUNWappserver/appserver/lib on the Sun Application Server host. 14. Copy ${CREATOR_HOME}/SunAppServer8/lib/derbyclient.jar and derbynet.jar to /opt/SUNWappserver/ appserver/lib on the Sun Application Server host. 15. Restart the Application Server.

For more information about configuring JDBC Resources in the Sun Application Server, see Chapter 3 in the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

Deploying the Portlet on Sun Portal Server 6

This section explains how to implement the deployment steps on Sun Portal Server 6. Unless otherwise noted, implement the deployment steps on the target system where Sun Java Portal Server 6 is running. You deploy the portlet to the portal container, register a channel for the portlet, and add the channel to the container. Note: There is a problem that prevents a Creator portlet application from deploying with Sun Portal Server 6. See the Sun Java Studio Creator Bug List for more information. Deploying the Portlet to the Portal Container 1. On the target system where Sun Portal Server 6 is running, run the command line function pdeploy. The pdeploy command deploys the portlet to the Sun Java Portal Server 6 portlet container. Note: Running the pdeploy command requires that the user have root privileges. The syntax for pdeploy is: pdeploy deploy -u ui -w password {-g|-d dn} -p webcontainerpasswor warfile where warfile is the name of the WAR file you exported earlier. The pdeploy options are: -u -w -g -d -p Specifies the distinguished name of the user to use to bind to the Sun Java System Directory Server. Specifies the password of the distinguished name of the user used to bind to the Directory Server. Specifies the global level node in LDAP to access the display profile document. The -d or -g option is required. Specifies the distinguished name in the LDAP node to access the display profile document. The -d or -g option is required. Specifies the web container password.

Note: For a complete description of pdeploy, see Chapter 11 in the Sun Java System Portal Server 6 2005Q1 Technical Reference Guide. The following example illustrates the pdeploy command for an exported WAR file named Portlet1.war. Code Sample 3: pdeploy Command /opt/SUNWps/bin/pdeploy deploy \ -u "uid=amAdmin,ou=People,dc=sesta,dc=com" \ -w admin \ -p sunjava \ -d "dc=sesta,dc=com" \ /tmp/Portlet1.war

2. After successfully executing, pdeploy displays the following message: Done Updating Display Profile! Deploying War File to Web Container... SUCCESS. 3. To deploy the same portlet application a second time, you must first undeploy the portlet as follows: pdeploy undeploy -u uid -w password {-g|-d dn} -p webcontainerpassword portlet-name where webcontainerpassword specifies the password of the portlet application's web container, and portlet-name specifies the name of the portlet application to undeploy.

Note: For a complete description of pdeploy undeploy, see Chapter 11 in the Sun Java System Portal Server 6 2005Q1 Technical Reference Guide.

Registering a Channel For the Portlet Now you use the Sun Java System Access Manager Administration Console to update the Portal Server display profile and register a channel for the portlet. The default location for the Administration Console is http://host:port/amconsole.

1. Log in as administrator to the Sun Java System Access Manager Administration Console. The default administrator login is amadmin. After you log in, the console by default selects Identity Management in the location pane, and the navigation pane displays all created organizations. 2. Select the organization, suborganization, or role to which you want to add a channel. When you log in as a delegated administrator, the console automatically takes you to the organization, suborganization, or role to which you have administrative access. 3. Choose Services from the View menu in the navigation pane. 4. Open the Portal Desktop attributes (or properties) page. Click the properties arrow next to Portal Desktop in the navigation pane. This opens the Desktop attributes page in the data pane. 5. Click the Manage Channels and Containers link in the Desktop page. The Channels page displays with the container path set to the root level. 6. Click New Portlet Channel to open the New Channel page and add the portlet channel to the root of the display profile. 7. In the New Channel page, enter a channel name (following the rules outlined in the page) and select the portlet identifier. The Portlet identifier menu lists the exported portlet from the IDE. 8. Click OK to create the channel. The Channels page appears. You can see the portlet channel you just created by scrolling to the list of channels.

Adding the Channel To a Container You next add the channel you just created to a container so that the channel displays on the portal desktop. You add the channel to a container using the Sun Java System Access Manager Administration Console.

1. From the list of Container Channels at the top of the Channels page, click the name of the container to which you want to add the new portlet channel. For example, for the default sample portal, MyFrontPageTabPanelContainer is the container for the front page tab on that portal. 2. Scroll to Channel Management and select the channel you just created and registered. 3. Click the Add button for the option to move the channel to Available to End Users on the Content Page. 4. While the channel is still selected, click the Add button for the option to move the channel to Visible on the Portal Desktop. 5. Click Save. Note: Once you update the Sun Java Portal Server 6 display profile for your portlet application, you do not have to do further updates if you are undeploying and redeploying the same portlet application, assuming that you keep the same portlet and channel names. To learn more about administering the display profile, see Chapter 10 in the Sun Java System Portal Server 6 2005Q1 Administration Guide.

Deploying the Portlet on Sun Portal Server 7

This section explains how to implement the deployment steps on Sun Portal Server 7. You set up the portlet deployment values, register a new channel for the portlet, and add your portlet to the channel. Unless otherwise noted, perform the deployment steps on the target system where Sun Java Portal Server 7 is running. Setting Up Portlet Deployment Values 1. Log in to the portal admin console at http://your-host:port/psconsole, where your-host is the name of the host running Sun Portal Server 7 and port is the http port number. 2. Choose Deploy Portlet. The Deploy Portlet wizard opens, similar to the following figure.

Figure 6: Deploy Portlet Wizard 3. Enter the following values: Deployment Setting Value Select Portal portal1 Select Location DeveloperSample 4. Click Next. 5. Choose File. The Choose a War File window opens, displaying files on the target file system on which you are running the Sun Portal Server 7 admin console. Choose the portlet WAR file that you copied earlier to the target system. 6. Click Finish.

Selecting the Portlet's Portal and Location 1. Choose Manage Channels & Containers. The Manage Channels & Containers wizard opens. 2. Enter the following values: Setting Value Select Portal: portal-name, where portal-name is the name of your target portal Select Location DeveloperSample 3. Click OK.

Creating a New Channel for the Portlet 1. Select the tab container MyFrontPageTabPanelContainer under JSPTabContainer. 2. Select New Channel/Container under Container Tasks. The New Channel wizard opens, similar to the following figure.

Figure 7: New Channel Wizard 3. Enter the following values: Setting Select Portal Select Location Type 4. Click Next. 5. For Channel Type, enter JSR 168 Portlet Channel, then click Next. A list of portlets appears. 6. Choose your deployed portlet, then click Next. 7. Choose a Channel Name, then click Next. 8. Click Finish. The portlet application deploys to the production Sun Portal Server 7. You can now log in to the Sun Portal Server desktop to test the portlet channel. The test user account login is developer, password developer. To learn more about Sun Portal Server 7, see Sun Java System Portal Server 7 documentation. See Also:
q q q q q

Value portal1 DeveloperSample Channel

Creating a Portlet Application Sun Java Enterprise System documentation Sun Developer Network Forum - Portal Server David Botterill's Weblog Greg Ziebold's Weblog

More Developer Resources: For more tutorials, articles, tips, forums, updates, and expert advice for developers, visit the Java Studio Creator developer resources on the Sun Developer Network (SDN) at http://developers.sun.com/jscreator/.

This page was last modified: April 27, 2006

Sun and Third-party Trademarked Terminology

The following Sun trademarked terms might be used in the Sun Java(tm) Studio Creator tutorials:

q q q q q q q q q

Sun Java Studio Creator integrated development environment (IDE) Sun Java System Application Server version number (Application Server) Java Platform, Standard Edition technology (Java SE(tm) platform) JavaServer(tm) Faces technology JavaServer Pages(tm) technology (JSP(tm) technology) Sun Java System Web Server version number (Web Server) Java Database Connectivity software (JDBC software) Enterprise JavaBeans(tm) specification (EJB(tm) specification) Solaris(tm) Operating System software (Solaris OS software)

The following third-party trademarked terms might be used in the Sun Java Studio Creator tutorials:
q q

UNIX(R) software SPARC(R) processor

Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. Sun, Sun Microsystems, the Sun logo, Java and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.This product is covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. Note: Sun is not responsible for the availability of third-party web sites mentioned in this document and does not endorse and is not responsible or liable for any content, advertising, products, or other materials on or available from such sites or resources. Sun will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services available on or through any such sites or resources.

Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, tats-Unis. Tous droits rservs. Sun Microsystems, Inc. dtient les droits de proprit intellectuels relatifs la technologie incorpore dans le produit qui est dcrit dans ce document. En particulier, et ce sans limitation, ces droits de proprit intellectuelle peuvent inclure un ou plus des brevets amricains lists l'adresse http://www.sun. com/patents et un ou les brevets supplmentaires ou les applications de brevet en attente aux tats-Unis et dans les autres pays. L'utilisation est soumise aux termes de la Licence. Sun, Sun Microsystems, le logo Sun, Java et le logo Java Coffee Cup sont des marques de fabrique ou des marques dposes de Sun Microsystems, Inc. aux tats-Unis et dans d'autres pays.Ce produit est soumis la lgislation amricaine en matire de contrle des exportations et peut tre soumis la rglementation en vigueur dans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nuclaires,des missiles, des armes biologiques et chimiques ou du nuclaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou rexportations vers les pays sous embargo amricain, ou vers des entits figurant sur les listes d'exclusion d'exportation amricaines, y compris, mais de manire non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une faon directe ou indirecte, aux exportations des produits ou des services qui sont rgis par la lgislation amricaine en matire de contrle des exportations et la liste de ressortissants spcifiquement dsigns, sont rigoureusement interdites. Sun Microsystems n'est pas responsable de la disponibilit de tiers emplacements d'enchanement mentionns dans ce document et n'approuve pas et n'est pas responsable ou iresponsable d'aucun contenu, de la publicit, de produits, ou d'autres matriaux dessus ou fournis par de tels emplacements ou ressources. Sun ne sera pas responsable ou iresponsable d'aucuns dommages ou perte causs ou allgus pour tre caus par ou en liaison avec l'utilisation de ce produit ou la confiance dans des tels contenu, marchandises, ou services disponibles sur ou par des tels emplacements ou ressources.

10