<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at
  
  http://www.apache.org/licenses/LICENSE-2.0
  
  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<document>
  <properties>
    <title>Jetspeed Service</title>
    <subtitle>Jetspeed Services</subtitle>
	<authors>
		<person name="David Sean Taylor" email="taylor@apache.org" />
	</authors>
  </properties>
  <body>
    <section name="Jetspeed Services">
    <p>
    This tutorial shows you how to use Jetspeed Services from the Express Demo Portlet Application. 
    Please note that all edits, unless explicity specified otherwise, are applied to the express-demo PA source tree.
    We will learn how to:
    <ul>
    <li>add new roles</li>
    <li>add new groups</li>
    <li>register new users</li>
    <li>manipulate pages</li>
    <li>get a filtered list of portlets</li>
    </ul>
    using the RoleManager, GroupManager, PortletAdministration, and Page Manager Jetspeed API interfaces.
    </p>
    <p>
    Lets get started by entering a new portlet in the portlet.xml:
    </p>
	 <source>	
	 <![CDATA[	
<portlet id="ServicesTutorialPortlet">    
    <description>Tutorial for using Jetspeed Services, such as PortalAdministration, PageManager, Registry.</description>
    <portlet-name>ServicesTutorialPortlet</portlet-name>
    <display-name>Jetspeed Services Tutorial Portlet</display-name>
    <portlet-class>com.bluesunrise.portal.portlets.services.ServicesTutorialPortlet</portlet-class>
    <init-param>
        <description>This parameter sets the template used in view mode.</description>
        <name>ViewPage</name>
        <value>/WEB-INF/view/services-tutorial.jsp</value>
    </init-param>
    <init-param>
        <description>Comma-separated list of roles to create via Role Manager</description>
        <name>roles</name>
        <value>role1,role2,role3</value>
    </init-param>    
    <init-param>
        <description>Comma-separated list of groups to create via Group Manager</description>
        <name>groups</name>
        <value>group1,group2,group3</value>
    </init-param>    
    <init-param>
        <description>Comma-separated list of Users to create and Register via PortalAdminstration service</description>
        <name>users</name>
        <value>user1,user2,user3</value>
    </init-param>        
    <init-param>
        <description>Comma-separated list of roles to assign to a new user</description>
        <name>registration-roles</name>
        <value>user,role1,role2</value>
    </init-param>
    <init-param>
        <description>Comma-separated list of groups to assign to a new user</description>
        <name>registration-groups</name>
        <value>group1,group2</value>
    </init-param>
    <init-param>
        <name>portlet-icon</name>
        <value>start-here.png</value>
    </init-param>    
    <supports>
        <mime-type>text/html</mime-type>
        <portlet-mode>VIEW</portlet-mode>
    </supports>
    <supported-locale>en</supported-locale>
    <portlet-info>
        <title>Services Tutorial</title>
        <short-title>Services</short-title>
        <keywords>tutorial,services,jetspeed-services</keywords>
    </portlet-info>
 </portlet>	 
	     ]]>
	</source> 			     
    <p>
    Jetspeed has an extended descriptor for defining extended portal features and services.
    Edit the <b>jetspeed-portlet.xml</b> found in <i>src/webapp/WEB-INF/</i>, and add the following
    services under the &lt;js:services&gt; element. This tells Jetspeed what services you require:
    </p>
	 <source>	
	 <![CDATA[	
        <js:service name='GroupManager'/>    
        <js:service name='PageManager'/>    
        <js:service name='PortalAdministration'/>        
        <js:service name='PortletRegistryComponent'/>
        <js:service name='RoleManager'/>	 
        <js:service name='UserManager'/>        
	     ]]>
	</source> 			     	
    <p>
    Create a new JSP page named <b>services-tutorial.jsp</b> in the <i>src/webapp/WEB-INF/view/</i> directory.
    Enter the following code:
	 <source>	
	 <![CDATA[	
<%@ page language="java" session="true" %>
<%@ page import="javax.portlet.*" %>

<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>
<%@ taglib uri="http://java.sun.com/jstl/core" prefix="c" %>
<%@ taglib uri="http://java.sun.com/jstl/fmt" prefix="fmt" %>

<portlet:defineObjects/>

<portlet:actionURL var="newRolesAction"/>
<br/>
<div class='portlet-section-header'>Services Tutorial Portlet</div>

<form name="servicesTutorialForm" action="<c:out value="${newRolesAction}"/>" method="post">
<input type="submit" name='action' value="createRoles" class="portlet-form-button" />
<input type="submit" name='action' value="createGroups" class="portlet-form-button" />
<input type="submit" name='action' value="registerUsers" class="portlet-form-button" />
<input type="submit" name='action' value="modifyPages" class="portlet-form-button" />
<input type="submit" name='action' value="createSharedPages" class="portlet-form-button" />
</form>
<c:if test="${message != null}">
<div class='portlet-msg-info'><c:out value="${message}"/></div>
</c:if>
<c:if test="${errorMessage != null}">
<div class='portlet-msg-error'><c:out value="${errorMessage}"/></div>
</c:if>    
	     ]]>
	</source> 			         
    </p>
    <p>
    <ul>
    <li>Create a new package using Eclipse: <b>com.bluesunrise.portal.portlets.services</b></li>
    <li>Create a portlet in the above package named <b>ServicesTutorialPortlet.java</b> extending 
    <b>GenericServletPortlet</b>.</li>
    <li>Override and implement the <b>init</b>, <b>doView</b> and <b>processAction</b> methods</li>
    </ul>
	</p> 
	<p>
	Add the following data members to the portlet class:
	</p>
	 <source>	
	 <![CDATA[	
    private PortalAdministration admin;
    private PageManager pageManager;
    private RoleManager roleManager;
    private UserManager userManager;
    private GroupManager groupManager;
    protected PortletRegistry registry;

    private List registrationRoles;
    private List registrationGroups;
    private List newRoles;
    private List newGroups;
    private List newUsers;    
    ]]>
	</source> 			 
	<p>
	Press <b>Ctrl-Shift-O</b> to resolve the two above class imports.	
	</p>
	<p>
	Enter the following code into the init(PortletConfig config) method, replacing whats there:
	</p>
	 <source>	
	 <![CDATA[
	    super.init();
        admin = (PortalAdministration) getPortletContext().getAttribute(
				CommonPortletServices.CPS_PORTAL_ADMINISTRATION);
		if (null == admin) {
			throw new PortletException(
					"Failed to find the Portal Administration on portlet initialization");
		}
		userManager = (UserManager) getPortletContext().getAttribute(
				CommonPortletServices.CPS_USER_MANAGER_COMPONENT);
		if (null == userManager) {
			throw new PortletException(
					"Failed to find the User Manager on portlet initialization");
		}
		roleManager = (RoleManager) getPortletContext().getAttribute(
				CommonPortletServices.CPS_ROLE_MANAGER_COMPONENT);
		if (null == roleManager) {
			throw new PortletException(
					"Failed to find the Role Manager on portlet initialization");
		}
		groupManager = (GroupManager) getPortletContext().getAttribute(
				CommonPortletServices.CPS_GROUP_MANAGER_COMPONENT);
		if (null == groupManager) {
			throw new PortletException(
					"Failed to find the Group Manager on portlet initialization");
		}
		pageManager = (PageManager) getPortletContext().getAttribute(
				CommonPortletServices.CPS_PAGE_MANAGER_COMPONENT);
		if (null == pageManager) {
			throw new PortletException(
					"Failed to find the Page Manager on portlet initialization");
		}
        registry = (PortletRegistry)getPortletContext().getAttribute(CommonPortletServices.CPS_REGISTRY_COMPONENT);
        if (null == registry) {
			throw new PortletException(
					"Failed to find the Portlet Registry on portlet initialization");
		}                
        this.newRoles = getInitParameterList(config, "roles");
        this.newGroups = getInitParameterList(config, "groups");
        this.newUsers = getInitParameterList(config, "users");        
        this.registrationRoles = getInitParameterList(config, "registration-roles");
        this.registrationGroups = getInitParameterList(config, "registration-groups");	 
	     ]]>
	</source>
	<p>
	Add this helper function to the class:
	</p>
	 <source>	
	 <![CDATA[	
    protected List getInitParameterList(PortletConfig config, String ipName)
    {
        String temp = config.getInitParameter(ipName);
        if (temp == null) return new ArrayList();

        String[] temps = temp.split("\\,");
        for (int ix = 0; ix < temps.length; ix++)
            temps[ix] = temps[ix].trim();

        return Arrays.asList(temps);
    }
	     ]]>
	</source>		 			 
	<p>
	Write the doView method:
	</p>
	 <source>	
	 <![CDATA[	
	public void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException 
	{
		request.setAttribute("message", request.getParameter("message"));
		request.setAttribute("errorMessage", request.getParameter("errorMessage"));
		super.doView(request, response);
	}	 
	     ]]>
	</source>		 			 	
	<p>
	Write the portletAction method:
	</p>
	 <source>	
	 <![CDATA[	
	public void processAction(ActionRequest request, ActionResponse response) throws PortletException, IOException 
	{
		String action = request.getParameter("action");
		try
		{
			if (action != null)
			{			
				if (action.equals("createRoles"))
				{
					String message = "Created " + createRoles() + " roles";
					response.setRenderParameter("message", message);
				}
				else if (action.equals("createGroups"))
				{
					String message = "Created " + createGroups() + " groups";
					response.setRenderParameter("message", message);
				}
				else if (action.equals("registerUsers"))
				{
					String message = "Registered " + registerUsers() + " users";
					response.setRenderParameter("message", message);
				}
				else if (action.equals("modifyPages"))
				{
					String message = "Modified " + modifyPages() + " pages";
					response.setRenderParameter("message", message);					
				}
				else if (action.equals("createSharedPages"))
				{
					String message = "Created " + createSharedPages() + " pages";
					response.setRenderParameter("message", message);										
				}
			}
		}
		catch (Exception e)
		{
			response.setRenderParameter("serviceError", e.getMessage());
			// TODO: proper logging
			e.printStackTrace();
		}
	}	 
	     ]]>
	</source>		 			 
	<p>
	Implement the undefined methods using the Jetspeed Services...
	<table>
	<tr>
	<th>method</th>
	<th>purpose</th>
	</tr>
	<tr>
	<td>createRoles</td>
	<td>using the roles init param, create new roles with the RoleManager service. If the role already exists, skip it.</td>
	</tr>
	<tr>
	<td>createGroups</td>
	<td>using the groups init param, create new groups with the GroupManager service. If the group already exists, skip it.</td>
	</tr>
	<tr>
	<td>registerUsers</td>
	<td>using the users init param, register new users with the PortalAdministration service. If the user already exists, skip it.</td>
	</tr>
	<tr>
	<td>modifyPages</td>
	<td>using the users init param, modify pages with the PageManager service. If the page doesnt exist, dont create it.
	    Modifications: for user1, create a 1 column collection of 1 portlet, for user2, create a 2 column collection of 2 portlets, for user3 create a 3 column collection of 3 portets</td>
	</tr>
	<tr>
	<td>createSharedPages</td>
	<td>create a folder named /shared, create a page name /friends.psml. add some portlets to the page. grant public-view security constraint to the folder</td>
	</tr>
	</table>
	</p>
	  <p>
	    <a href='../04/taglib.html'>Previous</a> 
	  </p>     	
    </section>
  </body>
</document>

