6.4 HelloWorldFromDominoServer portlet

< Day Day Up >

Overview

This section guides you through the process of coding your first Java-based portlet, the "HelloWorldFromDominoServer" portlet. This is the simplest portlet you can write using the Domino Java API in portlet development. It has the following functionalities:

Creates a session to Domino server.
Saves a session, so that it can be reused.
Gets some basic data from the server, like Notes version, platform, server name, and server URL.
Once a portlet is refreshed, it uses the same session what was created at first.

Implementation details and example

In order to create Portlet applications suitable for deployment in WebSphere Studio Application Developer, you need to use the wizard. To manually construct the necessary folder structure and deployment descriptors would be tedious and utterly pointless.

To start creating a new Portlet Application, launch WebSphere Studio Application Developer and switch to the Portlet Perspective by selecting Perspective → Open → Other → Portlet.
Start the Portlet Application wizard in one of the following ways:
1. Select File → New → Portlet Application Project.
2. Right-click the Portlet Perspective and select New → Portlet Application Project from the context menu.
3. The wizard can also be started from any perspective by selecting File → New → Other → Portlet development → Portlet application project.
When the wizard has started, you will see the screen shown in Figure 6-4.

Figure 6-4: First screen of the Portlet Application project wizard
The options in this dialog are the following:
- Project Name: This value will determine the name of the project created by this wizard. The value entered here will be used throughout the remainder of the wizard as the default value for other parameters.
  
  To follow our example, for a Project name field type: HelloWorldFromDominoServer
- Use default location: This checkbox indicates that you would like the entire contents of the application stored in the workspace. If you would like the contents of the application stored somewhere else on the file system, deselect this box.
  
  If you deselect the Use Default Location check box, this field is enabled and allows you to specify the file path where the application will be saved.
  
  To follow our example, check to use the default location.
- Enterprise Application project name: Though the Portal does not recognize EAR files, the Portlet application in WebSphere Studio must be contained in a Enterprise Application. When using the Portal debugging environment, all portlet applications contained in an EAR file are deployed together. You may choose an existing EAR file or enter a new one to be created.
  
  To follow our example, type: HelloWorldFromDominoEAR
- Context root: This value will be used in the application.xml and .websettings files. It will not be the context root of the portlet application when deployed. Since the EAR is not used to deploy the portlet application into a full server, this value is only used when the ear is published to debug Portal server connected to WebSphere Studio Application Developer.
  
  To follow our example, type: HelloWorldFromDominoServer
Click Next. This will bring up another dialog box, where you can select the type of portlet you would like to create inside the portlet application. The second window is shown in Figure 6-5 on page 315.

Figure 6-5: Second screen of the Portlet application project wizard

If you select Finish in the first screen of the wizard, an empty portlet application will be created. We don't want to do this in our sample.

Presently, there are six options when deciding which kind of portlet you want included in the portlet application. You can only create a single portlet in an application via the wizard. For this example, choose Basic portlet.

The six types of portlets that can be created are as follows:
- None: This is the default option and will not create a portlet in the application. If you choose this option, you will need to manually add portlets to the application, as well as the deployment descriptors.
- Basic portlet: This is by far the most common option and will create a simple portlet in the portlet application. The portlet will extend from PortletAdapter and contain meaningful implementations of all four do methods. The implementations will adhere to the MVC approach. A bean will also be created for you to encapsulate your business logic.
- JSP portlet: This option assumes the entire application will be contained in a JSP. The application will specify the com.ibm.wps.portlets. JSPPortlet for deployment. This portlet simply forwards calls to a JSP. The JSP that is called is specified in the config-param of the concrete portlet section in the portlet xml. By default, the wizard will specify and create a view.jsp file for you. You can choose a different name for the JSP in the third screen of the wizard. In the source folder, the wizard will place a dummy.java file that contains no code.
- MVC portlet: This choice utilizes the MVCPortlet provided as part of the com.ibm.wps.portlets package. This Portlet relays calls to Controller classes dedicated to servicing a specific markup. As such, if you select this type of portlet, a controller bean will be created for each markup you choose to support. The third screen of the wizard requires that you enter the base name of the controller classes. This name can be any value you like but is defaulted to MyController. This option will also create complete JSP structures for each markup.
- Servlet invoker portlet: This option will deploy the com.ibm.wps.portlets. ServletInvokerPortlet portlet and specify a URL as a parameter to the config-param in the portlet deployment descriptor. If you choose this option, the wizard requires you to provide a URL pointing to the servlet you wish to serve. The ServletInvoker portlet simply uses the ContentAccess Service to return unfiltered HTML. You must specify the URL you wish to serve in the final screen of the wizard. The resulting folder structure will contain a dummy.java file containing no code.
- XSL portlet: This option makes use of the com.ibm.wps.portlets.xslt. WpsXSLTPortlet. This portlet simply accepts an xml file and a style sheet as parameters and uses these to create a presentation via the XSLT transformation. These parameters must be supplied on the final window of the wizard. If you do not yet have the requisite files, the wizard can use default sample xml and xsl files. The parameters can be adjusted in the portlet.xml or at run time.
There are eight fields required in the final window of the wizard, shown in Figure 6-6. By default, all fields have been completed for you. Most of these fields are used to complete the portlet.xml deployment descriptor. For more information on the portlet.xml and deployment descriptor see the previous chapter. The fields and their meanings are as follows:
- Portlet application name: This name is used in the portlet.xml to specify the abstract application name. This value will never be seen by the administrator of the portlet or the end-user. Generally, there is no need to change this value.
- Portlet name: This value is used to identify the abstract portlet. This name will never been seen by the administrator or the end user. There is typically no need to alter this value.
- Concrete portlet application name: This name is used in the portlet.xml to specify the concrete application. The administrator will see this value in the portal. If you intend to add more concrete applications to this portlet application, you may want to change this value. Otherwise, there is no need to adjust this value.
- Concrete portlet name: This name specifies this concrete portlet to be deployed. The end user will see this value when they add the portlet to a page. Generally, there is no need to adjust this value.
- Default locale: This value adds the default locale and the language block to the portlet.xml.
- Concrete portlet title: This will complete the language block with the title. The description, short-title and keywords elements are included in the language block but left empty.
- Portlet class name: This name will be used as the name of the portlet created for you. You should adjust this value to reflect the package name you would like to use. Type HelloWorldFromDominoServer in order to follow our sample. If you do not enter a package name, the wizard will place the portlet in the default portlet package.
- Markups: These checkboxes indicate which markup languages you intend to support. By selecting a value, a new folder will be created under the JSP folder containing JSPs specifically for the markup.
Figure 6-6: Third screen of the Portlet application project wizard
Finally, click Finish and the wizard will create the necessary folder structure, classes, JSPs, and deployment descriptors.

Developing the portlet

The wizard will create the skeleton of the portlet, which you can then use as a foundation for your portlet development. Figure 6-7 on page 319 shows the result of creating a basic portlet application with the wizard.

click to expand
Figure 6-7: Skeleton of the portlet

The generated project contains the following folders and files by default:

Java Source: This folder contains the Java files that make up the portlet application. By default, the wizard assumes you will follow an MVC approach and creates a simple Java bean for you. Whatever package name was specified in the final screen of the wizard will be created. If a simple class name was specified without a package, the wizard will place the portlet in a package name portlet. In our example we did not build JavaBeans.
Web Content: This folder contains everything needed to deploy the application to the portal. Essentially, this folder will become the war file. It contains two sub folders: jsp and WEB-INF.
jsp: This folder will contain all the JSPs used by the application to create the content of the portlet. For each markup you choose to support, a directory will be created containing JSPs for each of the four modes a portlet may support. It will also contain four JSP files for the modes under the root. In the event that the portal is unable to match a client to a markup folder, it will use the default JSPs contained in the root. To keep development simple and clean, you may choose to delete the default JSPs and work only with the HTML JSPs. In our example we did not build any JSPs.
WEB-INF: This folder contains the compiled code and deployment descriptors used by the Portal to install the application.
- classes: If your compiled portlet class files are not packaged into a jar file, they are included in this directory. The complete package structure is created in this folder.
- lib: This directory contains any jar files that your application makes use of and which are not normally available in the Portal environment via the classpath. Also, if you have packaged your compiled portlets into a jar, the jar file is placed in this directory. Typically you will import the ncso.jar file to here.
- tld: This is included to allow JSPs to compile and recognize the custom tags available in the portal environment. This folder and file are not required at deployment time since the tld is installed with Portal. To make maintenance easier and more reliable, you may choose to delete this file upon deployment.
- ibm-web-bnd.xmi: This file is not used by the portal environment but is included with all Web applications created in WebSphere Studio.
- ibm-web-ext.xmi: This file is not used by the portal environment but is included with all Web applications created in WebSphere Studio.
- portlet.xml: This is the deployment descriptor required by the Portal server to install the portlet application. It must be located under the WEB-INF folder or installation will fail.
- web.xml: This deployment descriptor is required by the application server to install the Web application. It must be located under the WEB-INF folder or installation will fail.
.classpath: This file is used by WebSphere Studio to locate the jar files containing the Portlet APIs. It is required for your portlets to compile but is not included in deployment.
Libraries: This folder contains Java files needed in portlet development.

Modifying the skeleton

After the portlet wizard builds the skeleton of your portlet, you need to make the following modifications to it.

Add the NCSO.jar file to portlet structure.

Choose the lib folder, then select File → Import → File Systems. Select ncso.jar, and click Finish. Your workspace will look like Figure 6-8 on page 321.

Figure 6-8: Added ncso.jar

Modify Java code in the HelloWorldFromDomino class file.

Select Java Source → portlet → HelloWorldFromDomino. The wizard generated a lot of code for basic use. Make the following modification to the code:

Replace doView() method with this:

    public void doView(PortletRequest request, PortletResponse response) throws PortletException,IOException{       // Calling method getSession in viewmode        getSession(request,response);       }

Create getSession() method and place it after doView() method. The code has been commented. Replace <servername>, <username> and <password> fields with those suitable for accessing your existing Domino server. The user should have required access rights to the Domino server as described in "Enabling Domino server for DIIOP connection" on page 251.

Example 6-1: getSession() method

    private Session getSession(PortletRequest request, PortletResponse response)throws  PortletException,IOException {       // Check first if session already exist       Session diiopsession = (Session)request.getSession().getAttribute("diiopsession");       // Creating writer for output       PrintWriter writer = response.getWriter();       // Check if diiopsession already exists, if it is, use it, if not, create one       if (diiopsession == null)          try{                 // Creating diiop session for Domino                    diiopsession = NotesFactory.createSession("<servername>","<username>","<password>");                   // Set session to attribute for reuse                  request.getSession().setAttribute("diiopsession", diiopsession);                  // Sending Hellos first time                 writer.println("<b>HelloWorldFromDominoServer!</b><br>You have just created diiop session to Domino through portlet!<br><br><br>ServerNotesVersion:" +                 (String)diiopsession.getNotesVersion() + "<br>ServerPlatform: " +                 (String)diiopsession.getPlatform() + "<br>ServerName: " +           (String)diiopsession.getServerName() + "<br>ServerURL: " +           (String)diiopsession.getURL());           }catch (NotesException e){              // Sending Hellos from exception                 writer.println("HelloFromDominoServer Portlet ran, but with exception" + e.id + " msg:" + e.text);       }else{          // Sending Hellos from reused session          writer.println("<b>HelloFromDominoServer!</b><br><br>You´ve successfully reused diiopsession, cool!");       }    return diiopsession;    } }

In the beginning of the code, declare the necessary imports like this:

Example 6-2: Add these imports in the beginning of the ACLBrowser.java file

 package portlet; //Domino Objects for JAVA API import lotus.domino.*; //Portlet API import org.apache.jetspeed.portlet.*; import org.apache.jetspeed.portlets.*; //Java stuff import java.io.*; import java.io.PrintWriter;

The code is now ready to run at the Portal.

Export the portlet file.

To deploy the portlet application, the webApplication directory must be packaged into a WAR file. To create a WAR file for deployment, select the application and right-click it. From the context menu, select Export WAR. You can also get this option from the menu by selecting File → Export and selecting WAR File from the list of options.

Figure 6-9: Exporting portlet from Application Developer

Export the WAR file. Name the file HelloWorldFromDomino.war. By default it will be stored to root main drive (for instance, in windows c:\) You can specify a more suitable folder if you wish.
Deploy the portlet and add it to the page.

HelloWorldFromDominoServer portlet in action

When you open the page for the first time, HelloWorldFromDominoServer portlet should give you information about your server (NotesVersion, Platform, server name, and server URL). Figure 6-10 illustrates this.

click to expand
Figure 6-10: HelloWorldFromDominoServer in action

Refresh the browser; the portlet is using session, and you will get a different message from the portlet, as illustrated in Figure 6-11.

click to expand
Figure 6-11: HelloWorldFromDominoServer in action reusing a session

Congratulations, you have just finished your first full Java portlet integration with Domino.

< Day Day Up >