JSR 168 Tutorial

1. JSR 168 Tutorial A General Review of JSR 168 with uPortal Examples

2. What is JSR 168? (Indulge me if you know material in the next few slides--I need to make some arguable points). From the portlet development point of view, it is really very simple: You write a java class that extends GenericPortlet. You override/implement several methods inherited from GenericPortlet. You use some supporting classes/interfaces Many are analogous to their servlet equivalents Some (portletsession) actually seem to be trivial wrappers around servlet equivalents in Pluto.

3. Some Terminology

4. The Big Picture As a portlet developer, the previous set of classes are all you normally touch. The portlet container (Pluto) is responsible for running your portlets. Init, invoke methods, destroy. Portlets have a very limited way of interacting with the container. It is a black box->black hole. The API is basically one-way.

5. Some Generic Portlet Methods

6. Some Supporting Classes/Interfaces

7. In Action: Get started. public class JunkPortlet extends GenericPortlet { public void init(){ //Do any initialization. } //Rest of the methods on following slides go here. � }

8. Override doView() protected void doView( RenderRequest req, RenderResponse res) throws PortletException, IOException { //Include the desired JSP or HTML page. //We could also use out to write directly to the response. WindowState state=req.getWindowState(); if(!state.equals(WindowState.MINIMIZED)) { res.setContentType("text/html"); PortletRequestDispatcher rd= getPortletContext().getRequestDispatcher(�MyJSP.jsp�); rd.include(req,res); } }

9. The JSP Page <portlet:defineObjects/> <% PortletSession portletSession=renderRequest.getPortletSession(); portletSession.setAttribute("localattname","localattval"); PortletURL url=renderResponse.createActionURL(); String theActionString=url.toString(); %> HTML Content is here. A form is below. <form method=post action="<%=theActionString%>"> <input type=�> </form>

10. Some Notes Include the <%portlet:definedObjects/%> tag, which will instantiate renderRequest, renderResponse, and portletConfig objects. You can then just use them, as with request, response, and other JSP implicit objects. The renderRequest gives you access to the PortletSession, if you want to store session variables. One of the trouble points. The renderResponse gives you access to the PortletURL object. Use the PortletURL to generate a URL for the <form action> So that it points to portlet container and gets handled by the processAction() method, rather than going of into space. Handle href URLs similarly. This is one of the sticking points.

11. Lastly, Override processAction() When you invoke the form on the previous JSP, the portlet container will pass the action handling to the processAction method. The ActionRequest can be used to get any of the <input> parameters in a way similar to the usual HttpServletRequest. When the processAction method returns, the container then invokes the appropriate do method (usually doView). If you need to pass <form> parameters on to doView, add them to the ActionResponse. This will give them to the RenderRequest. The example shows how to add ALL parameters. public void processAction (ActionRequest request, ActionResponse actionResponse) throws PortletException, java.io.IOException { //Process request parameters � //Add any other request params // to the renderRequest actionResponse.setRenderParameters(request.getParameterMap()); }

12. A Final Comment on Portlet Coding The above example makes some important and dubious assumptions Developers would want to write a GenericPortlet extension for every single portlet they develop. And write really complicated processAction() and doView() methods. Developers will like the specific JSR 168 portlet-style MVC that it forces on them. Developers will gladly ignore other development methodologies/frameworks like Velocity, Struts, and JSF. Fortunately, we can develop bridges that allow you to develop with other frameworks and avoid lots of specialized portlet code. We have targeted Velocity for reasons discussed later. Java Server Faces may be the way of the future.

13. Deploying Portlet Applications The portlet container (i.e. uPortal) runs as a distinct web application. That is, it has its own directory in tomcat. Moreover, it runs as a separate context, with its own classloader, session management, etc. Portlet applications are deployed as distinct war files/web applications. You go through the container webapp to get to the portlet webapp. Portlets in the same application share jars, classes, and runtime stuff like request and session variables. Portlets in different portlet apps do not share anything. JSR 168 containers vary in the specifics of their deployment procedures. We�ll look at uPortal and GridSphere

14. The Maven Way Maven is a very powerful build/deploy tool. Compared to Apache Ant, it has many more built-in functions (�goals�) Essentially, you avoid writing a lot of Ant build.xml boilerplate for common tasks like compiling code, making javadocs, and creating wars. Also helps you manage jar dependencies. Just use a common directory structure. If you need to do custom things, create Maven scripts that just call Ant or Jelly.

15. Using Maven in Portlet Development First, create a standard directory structure. See right Project.xml is a maven file that defines your project. Put all your application under src. Put all java code under src/java. Use package dir structure Images, HTML, JSP, etc. go under the webapp directory. Put unit tests under the tests directory. MyProject/project.xml MyProject/src/java/ MyProject/src/webapp/jsp MyProject/src/webapp/WEB-INF/web.xml MyProject/src/webapp/WEB-INF/portlet.xml MyProject/tests

16. Maven War If you use the previous structure, all you need to do to compile everything and create a war file is type �maven war� in the MyProject directory. This will also run any unit tests that you have placed in MyProject/tests. The resulting war file is placed in MyProject/target/

17. project.xml and project.properties project.xml allows you to specify jar dependencies and build characteristics. project.properties defines any variables that you want to set in project.xml. It also defines maven properties like the maven remote repository values. You can also script maven using maven.xml. You can also beef maven goals up with Ant and/or Jelly scripts. Not used in the example but used extensively in the OGCE download.

18. Portlet.xml This file is used to configure your portlet properties. The example code includes a minimal portlet.xml file for inspection.

19. Web.xml Web.xml is the standard place to put webapp configuration for servlets/jsp. JSR 168 containers need a special servlet that can handle cross-webapp communication. This is typically configured in each portlet app�s web.xml file. This is portal vendor-specific. For uPortal installation, you don�t have to worry about these details. uPortal has a tool to read the web.xml you give it and add in the additional required XML tags. You can examine the changes in the OGCESamplePortlets webapp.