portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From woon...@apache.org
Subject svn commit: r722405 [13/17] - in /portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade: ./ src/ src/site/ src/site/resources/ src/site/resources/css/ src/site/resources/images/ src/site/resources/images/layouts/ src/site/resources/images/portle...
Date Tue, 02 Dec 2008 08:53:28 GMT
Added: portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-migration.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-migration.xml?rev=722405&view=auto
==============================================================================
--- portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-migration.xml (added)
+++ portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-migration.xml Tue Dec  2 00:53:22 2008
@@ -0,0 +1,1074 @@
+<?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-1 Migration Guideline</title>
+		<subtitle>Migration Guide from Jetspeed 1 to Jetspeed 2</subtitle>
+		<authors>
+			<person name="David Sean Taylor" email="taylor@apache.org" />
+		</authors>
+	</properties>
+	<body>
+		<section name="Overview">
+	    <p>This migration guide will help you migrate from Jetspeed version 1 to Jetspeed version 2.
+	    Note that there are currently no migration tools, nor are the plans to create a migration tool to convert 
+	    portal resources from version 1  to version 2. This document provides only guidelines for migration.
+	    </p>
+	    <p>
+		With the development of the new portal standard (The Portlet API), the common portlet metaphor 
+		has changed quite drastically from the Turbine-based origins in version 1.
+		The programming API is completely changed. There are no longer XREG files, but instead standard deployment descriptors.
+		The are also new concepts introduced by the portlet standard such as portlet applications, portlet preferences, 
+		user attributes and init parameters that have no direct mapping from version 1. Creating a migration tool would 
+		be a large undertaking. The Jetspeed development team is not prepared to make this investment.
+		By following the guidelines provided here, you can easily migrate your Jetspeed 1.x applications to Jetspeed 2.  
+		For an overview of architectural differences, see the document <a href='j1-users.html'>For Jetspeed-1 Users</a> 
+		 </p>
+		</section>
+	    <section name='Migration Table'>
+	    <p>The table below gives you an idea of how to migrate. We will cover each subject in more detail further on in this document.</p>
+	    <table>
+	    <tr><th>1.x Feature</th><th>2.x Feature</th><th>Description</th></tr>
+	    <tr><td>J1 Portlet Java Code</td>
+	        <td>Portlet API Standard Code</td>
+	         <td>Rewrite the java code to the new specification. 
+	            Involves replacing Turbine action with standard processAction, and replacing Rundata with PortletRequest/Response</td></tr>
+	    <tr><td>XREG Portlet Registry</td>
+	        <td>portlet.xml deployment descriptor</td>
+	        <td>There are pretty big differences here. Migrate &lt;portlet-entry&gt; to &lt;portlet&gt; entries, &lt;parameter&gt; to &lt;preference&gt; or &lt;init-param&gt;
+	        </td>
+	    </tr>
+	    <tr><td>J1 PSML</td>
+	        <td>J2 PSML</td>
+	        <td>Migrate Tabs to Folders and Pages, migrate to new tag syntax</td>
+	    </tr>
+	    <tr><td>XREG Security Registry</td>
+	        <td>Security Constraints</td>
+	        <td>Migrate J1 security constraint format to J2 security constraint format</td>
+	    </tr>
+	    <tr><td>J1 Controllers</td>
+	        <td>J2 Layouts</td>
+	        <td>Controllers are deprecated. Recommend using the new Jetspeed-2 Layout portlets. If porting necessary, HTML portions of VM code may port, but not context model variables</td>
+	    </tr>
+	    <tr><td>J1 Controls</td>
+	        <td>J2 Portlet Decorators</td>
+	        <td>Controls are deprecated. Recommend using the new Jetspeed-2 Portlet Decorators. If porting necessary, HTML portions of VM code will port, but not context model variables</td>
+	    </tr>
+	    <tr><td>J1 Layouts, Screens, Navigations</td>
+	        <td>J2 Page (Layout) Decorators</td>
+	        <td>All deprecated. Recommend using the new Jetspeed-2 Page (Layout) Decorators as a starting point to writing your own page decorators. HTML portions of VM code will port, but not context model variables</td>
+	    </tr>
+	    </table>
+	    </section>
+		<section name="Portlet Applications">
+		<p>One of the most important differences in writing Jetspeed-2/Portlet API portlets is that you must package your portlet code 
+		separate from the Jetspeed portal. In Jetspeed-1, all the user code, the portlet business logic, is packaged in one big war file
+		mixed in with the Jetspeed-1 implementation. The Portlet API clearly abolishes this practice of mixing the portal implementation with
+		your portlets. Jetspeed-2 is packaged as a single web application itself. When you write your portlets for Jetspeed-2, you will need to 
+		write and package your own portlets. The portlet classes and deployment descriptors must all be packaged into a single war file, known
+		as a portlet application. A portlet application contains one or more portlets, along with a deployment descriptor, the portlet.xml.
+		A portlet application is an extension of a web application. The portlet.xml holds the definitions of one or more portlets and is 
+		analogous to the xreg files used in Jetspeed-1.
+		</p>
+		</section>	    
+		<section name="Java Code">
+			<p>In this section we demonstrate how to convert a Jetspeed-1 portlet to a JSR-168 Java Standard Portlet.
+			This involves the following steps:
+			</p>
+			<ul>
+			<li>Converting the Portlet Init Java Code</li>
+			<li>Converting the Portlet getContent Java Code</li>
+			<li>Converting a Turbine Action</li>
+			</ul>
+			<p>
+			Jetspeed-1 portlet implementations are normally separated between two different Java source files.
+			</p>
+			<ul>
+			<li>The Portlet Source Code</li>
+			<li>The Turbine Action Source Code</li>
+			</ul>
+			<p>
+			The Portlet Source Code handles the <b>View</b> part of the MVC pattern. The <b>getContent</b> method
+			is the standard method in Jetspeed-1 to call to render the content of a portlet. The corresponding methods 
+			in Jetspeed-2 and in the Portlet API, the <b>doView, doEdit, doHelp</b>. In the Portlet API terminology,
+			this phase of portlet processing is known as the <b>render phase</b>. During the render phase, the portlet
+			should not perform any business logic or other manipulation on the <b>Model</b>. All model manipulation
+			should be left to the <b>action phase</b>
+			</p>
+			<p>The Turbine Action performs the <b>action phase</b> of the portlet processing. During the action phase of the Portlet API standard,
+			rendering of all other portlets is blocked until the action completes. This is also true in the Jetspeed-1/Turbine model.
+			</p>
+			<subsection name='Creating a new Portlet Class'>
+			<p>The best place to get started in migrated your portlet is to create a new JSR-168 standard portlet.
+			Simply create a new Java class inheriting from the GenericPortlet interface provided by the Portlet API.
+			You can also use one of the frameworks or bridges available from Apache Portals or Spring MVC.
+			The example below writes directly to the Portlet API. The code below can be used a skeleton for writing
+			a portlet.
+			</p>
+<source>
+<![CDATA[
+import java.io.IOException;
+import javax.portlet.GenericPortlet;
+import javax.portlet.PortletConfig;
+import javax.portlet.PortletException;
+import javax.portlet.RenderRequest;
+import javax.portlet.RenderResponse;
+import javax.portlet.ActionRequest;
+import javax.portlet.ActionResponse;
+
+public class HelloWorld extends GenericPortlet
+{    
+    public void init(PortletConfig config) 
+    throws PortletException 
+    {
+    }
+    public void doEdit(RenderRequest request, RenderResponse response)
+    throws PortletException, IOException
+    {
+    }    
+    public void doHelp(RenderRequest request, RenderResponse response)
+    throws PortletException, IOException
+    {
+    }
+    public void doView(RenderRequest request, RenderResponse response)
+    throws PortletException, IOException
+    {
+    }
+    public void processAction(ActionRequest request, ActionResponse actionResponse)
+    throws PortletException, IOException
+	{
+	}    
+}
+]]>		
+</source>	
+			<p>To find out more about Portals Bridges and other Frameworks, explore these links:
+			</p>
+			<ul>
+			<li><a href='http://portals.apache.org/bridges/'>Portals Bridges</a></li>
+			<li><a href='http://portals.apache.org/bridges/multiproject/portals-bridges-jsf/index.html'>JSF Bridge</a></li>
+			<li><a href='http://portals.apache.org/bridges/multiproject/portals-bridges-struts/index.html'>Struts Bridge</a></li>
+			<li><a href='http://portals.apache.org/bridges/multiproject/portals-bridges-velocity/index.html'>Velocity Bridge</a></li>
+			<li><a href='http://www.springframework.org/docs/reference/portlet.html'>Spring Portlet MVC</a></li>			
+			</ul>
+			</subsection>			
+			<subsection name='Converting the Portlet Init Java Code'>
+			<p>
+			The Portlet Source code handles the <b>Init</b> phase of a portlet lifecycle.
+			The init phase is very similar in both the Java Portlet API and in Jetspeed 1. 
+			Here we have an example of the init method of a  Jetspeed-1 portlet:
+			</p>
+			<source>
+<![CDATA[
+    public void init() throws PortletException
+    {
+    }
+]]>
+			</source>			
+			<p>
+			The equivalent method in the Portlet API (Jetspeed-2) would be, note the difference being the PortletConfig parameter
+			(although the exception classes are named the same, they are entirely different classes, one from Jetspeed-1, the other from the Portlet API):
+			</p>
+			<source>
+<![CDATA[
+    public void init(PortletConfig config) 
+    throws PortletException 
+    {
+    }
+]]>
+			</source>						
+			<p>In Jetspeed-1, you would normally access Turbine Services with static acccessors, for example:</p>
+<source>
+<![CDATA[
+            JetspeedSecurity.addUser(user);
+]]>
+</source>									
+			<p>In Jetspeed-2, Jetspeed Services the standard way to access Jetspeed Services is to get a handle in the init phase, for example:</p>
+<source>
+<![CDATA[
+    private UserManager userManager;
+...
+    public void init(PortletConfig config) 
+    throws PortletException 
+    {
+        userManager = (UserManager)getPortletContext().getAttribute(CommonPortletServices.CPS_USER_MANAGER_COMPONENT);
+        if (null == userManager)
+        {
+            throw new PortletException("Failed to find the User Manager on portlet initialization");
+        }    
+    }
+]]>
+</source>									
+			</subsection>			
+			<subsection name='Converting the Portlet getContent Java Code'>
+			<p>
+			In Jetspeed-1, the <b>getContent</b> method renders the content of your portlet. The render phase of Jetspeed-1 is implemented 
+			by the getContent method of your Portlet as defined by the Jetspeed-1 Portlet interface.
+			</p>
+<source>
+<![CDATA[
+public ConcreteElement getContent(RunData rundata);
+]]>
+</source>			
+<p>The only parameter passed in to the getContent method is a <b>RunData</b> parameter. RunData is a part of the <a href='http://jakarta.apache.org/turbine/'>Turbine web framework</a>.
+RunData is basically a wrapper around the Servlet request and response, along with other Turbine-specific information.
+When writing portlets for Jetspeed-2, you write to the Portlet API. 
+</p>
+<source>
+<![CDATA[
+public void doView(RenderRequest request, RenderResponse response)
+throws PortletException, IOException
+{
+    response.setContentType("text/html");
+    ...
+]]>
+</source>			
+<p>The <b>doView</b> method is the Portlet API equivalent of the <b>getContent</b> method of the Jetspeed-1 API.
+The Portlet API has the concept of <b>portlet modes</b>. There are three default portlet modes <b>view, edit, and help</b>.
+For each of these modes, there are three methods you can override in your portlet: <b>doView, doEdit and doHelp</b>.
+Notice that where the Jetspeed-1 API has one RunData parameter, the Portlet API is more like the Servlet API, with two parameters,
+the <b>RenderRequest</b> and <b>RenderResponse</b>. One of the biggest parts of migrating your app will be to convert RunData references
+to RenderRequests and RenderResponses. Before starting, we recommend taking a training course on the Portlet API, or learning the API
+yourself by reading the Portlet specification as well as any articles or books on the subject. A good book to get started on the Portlet API
+is <a href='http://www.manning.com/hepper/'>Portlets and Apache Portals</a>.
+</p>
+<p>When rendering content, Jetspeed 1 makes use of a HTML construction kit called <b>ECS</b>. All rendering goes through Turbine and ECS.
+The return type of the getContent method is a <b>ConcreteElement</b>, which is defined in the ECS API. Here is the typical way to 
+generate output from a portlet in Jetspeed-1:
+</p>
+<source>
+<![CDATA[
+...
+String helloString = "Hello World. This is the portlet output in view mode.";
+return new org.apache.jetspeed.util.JetspeedClearElement(helloString);        
+]]>
+</source>			
+<p>When rendering content in Jetspeed-2, the Portlet API uses a streaming interface:</p>
+<source>
+<![CDATA[
+response.setContentType("text/html");
+String helloString = "Hello World. This is the portlet output in view mode.";
+
+// using Java writers
+response.getWriter().println(helloString);
+
+.. OR ...
+
+// using Java streaming
+response.getPortletOutputStream().write(helloString.getBytes());
+]]>
+</source>	
+<p>Of course you can use JSPs or Velocity with either Jetspeed-1 or Jetspeed-2. 
+With Jetspeed-1, the common practice is to make use of the Jetspeed-1 <b>GenericMVCPortlet</b> or one of its derivitives,
+the <b>VelocityPortlet</b> or the <b>JspPortlet</b>. Both the VelocityPortlet and JspPortlet are really just GenericMVCPortlets.
+Here is the xreg example of a WeatherPortlet which extends the GenericMVCPortlet by setting its parent to Velocity
+</p>		
+<source>
+<![CDATA[
+    <portlet-entry name="WeatherPortlet" hidden="false" type="ref" parent="Velocity" application="false">
+        <parameter name="template" value="weather" hidden="true"/>
+    </portlet-entry>
+]]>
+</source>	
+<p>The template parameter is named <b>weather</b>. Since this is a Velocity MVC portlet, Jetspeed-1 knows to look under 
+the <b>WEB-INF/templates/vm/portlets/html</b> directory to find <b>weather.vm</b>. The MVC portlet will automatically handle 
+the details of dispatching to this Velocity template to render your portlet. Here is the actual contents of the velocity template.
+Note that we don't have to write any portlet Java code in this case, but only the actual template.
+</p>
+<source>
+<![CDATA[
+#if (!$weather_city_info)
+<BR>${l10n.WEATHER_PLEASE_CUSTOMIZE_YO_VM}<br><BR>
+#else
+<a href="http://www.wunderground.com/${weather_city_info}.html"
+target="_blank"><img src="http://banners.wunderground.com/banner/${weather_style}/language/www/${weather_city_info}.gif"
+alt="Click for ${weather_city_info} Forecast" border="0"></a>
+#end
+]]>
+</source>	
+<p>With Jetspeed-2 and the Portlet API, we can make use of the Velocity Bridge or the JSP Bridge to delegate to portlets.
+The simplest case is just dispatching the call yourself to the JSP or Velocity servlet. Here is an example of dispatching to a JSP from the doView:
+</p>
+<source>
+<![CDATA[
+protected void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException
+{
+    PortletContext context = getPortletContext();
+    ResourceBundle resource = getPortletConfig().getResourceBundle(request.getLocale());
+    request.setAttribute("viewMessage", resource.getString("preference.label.MyModeIsView"));
+    PortletRequestDispatcher rd = context.getRequestDispatcher("/WEB-INF/demo/preference/pref-view.jsp");
+    rd.include(request, response);
+}
+]]>
+</source>	
+<p>And here is an example of the WeatherPortlet extending the Velocity Bridge, and making use of the Portlet API User Preferences feature,
+note that we do not directly create a dispatcher here, but the framework will do that automatically:
+</p>
+<source>
+<![CDATA[
+import org.apache.portals.bridges.velocity.GenericVelocityPortlet;
+...
+
+public class WeatherPortlet extends GenericVelocityPortlet
+{
+...
+
+public void doView(RenderRequest request, RenderResponse response)
+        throws PortletException, IOException
+{
+    Context context = super.getContext(request);
+
+    String cityInfo = (String) request.getPortletSession().getAttribute(
+            WEATHER_CITY_INFO);
+
+    PortletPreferences prefs = request.getPreferences();
+    String city = prefs.getValue(WEATHER_CITY, "Bakersfield");
+    String state = prefs.getValue(WEATHER_STATE, "CA");
+    String station = prefs.getValue(WEATHER_STATION, null);
+    cityInfo = getCityInfo(city, state, station);
+    context.put(WEATHER_CITY_INFO, cityInfo);
+
+    String style = prefs.getValue(WEATHER_STYLE, "infobox");
+    context.put(WEATHER_STYLE, style);
+    response.setProperty("david", "taylor");
+    super.doView(request, response);
+}
+]]>
+</source>	
+<p>And here is the Velocity template to render the portlet content:</p>
+<source>
+<![CDATA[
+#if (!$weather_city_info)
+Please configure your Weather settings.
+#else
+<a href="http://www.wunderground.com/${weather_city_info}.html"  
+target="_blank"><img src="http://banners.wunderground.com/banner/$!weather_style/language/www/${weather_city_info}.gif"
+alt="Click for $weather_city_info Forecast" border="0"></a>
+#end
+]]>
+</source>	
+			</subsection>						
+			<subsection name='Converting a Turbine Action'>
+<p>The Portlet API defines several phases of execution during the processing of a portlet page. The action phase is designed to be executed
+before the render phase of a portlet. There can only be one action phase targeting only one portlet. Once the action phase completes, then
+the render phase for all portlets on a page can be executed. Thus the action phase is said to be a <i>blocking</i> phase, meaning that it must
+complete before the render phase for each portlet on the page can commence. Actions are usually some kind of user interaction that manipulates
+the <i>Model</i> of the MVC framework, such as a user submitting a form and updating the model, or adding or deleting a record. The concept
+of actions ports fairly well from Turbine and Jetspeed-1 to Jetspeed-2 and the Portlet API. Whereas Turbine has the concept of one class per 
+action, the Portlet API has an entry point for all actions to come through as a method on your portlet. Frameworks such as the Spring MVC
+framework provide better abstractions for modeling one method per action.
+</p>
+<p>Lets again look at the WeatherPortlet with Jetspeed-1. First the xreg defines the actions:</p>
+<source>
+<![CDATA[
+        <parameter name="action" value="portlets.WeatherAction" hidden="true"/>
+]]>
+</source>	
+<p>
+We must then implement the action class which are usually placed in the Jetspeed-1 webapp class loader space.
+Here is the code for the WeatherAction, which extends a Jetspeed-1 framework class VelocityPortletAction:
+</p>
+<source>
+<![CDATA[
+public class WeatherAction extends VelocityPortletAction
+{
+
+    protected void buildNormalContext( VelocityPortlet portlet,
+                                       Context context,
+                                       RunData rundata )
+    {
+
+        String cityInfo = PortletConfigState.getParameter(portlet, rundata, WEATHER_CITY_INFO, null);
+        //if (cityInfo == null)
+        //{
+            String city = portlet.getPortletConfig().getInitParameter(WEATHER_CITY);
+            String state = portlet.getPortletConfig().getInitParameter(WEATHER_STATE);
+            String station = portlet.getPortletConfig().getInitParameter(WEATHER_STATION);
+            cityInfo = getCityInfo(city, state, station);            
+        //}
+        context.put(WEATHER_CITY_INFO, cityInfo);
+        //PortletConfigState.setInstanceParameter(portlet, rundata, WEATHER_CITY_INFO, cityInfo);
+
+        String style = PortletConfigState.getParameter(portlet, rundata, WEATHER_STYLE, "infobox");
+        context.put(WEATHER_STYLE,style);
+    }
+]]>
+</source>	
+<p>
+In Jetspeed-1 there is some really bad architecture interfering with easily writing portlets.
+Here in our action, we are actually implementing the <b>View</b> portion of our code by populating the 
+Velocity context with <b>context.put</b> statements. Please beware that all code implemented in the 
+<b>buildNormalContext</b> method should be ported to the <b>doView</b> method of the Portlet API.
+Note how the actual portlet must be passed in as the first parameter to the buildNormalContext method.
+</p>
+<p>The actual action code implemented as <b>do..</b> methods on your action class will need to be ported
+to the <b>processAction</b> method on the Portlet API.
+</p>
+<source>
+<![CDATA[
+    public void doInsert(RunData rundata, Context context)
+        throws Exception
+    {
+]]>
+</source>	
+<p>The <b>doInsert</b> method is linked by Turbine to an action in the Velocity template with the <b>eventSubmit_</b> prefix:
+</p>
+<source>
+<![CDATA[
+<input type="submit" name="eventSubmit_doInsert" value="${l10n.USER_FORM_ADD_USER_VM}"/>
+]]>
+</source>	
+<p>Here is the equivalent in the Portlet API (Jetspeed-2):</p>
+<source>
+<![CDATA[
+    public void processAction(ActionRequest actionRequest, ActionResponse actionResponse) 
+        throws PortletException, IOException
+]]>
+</source>	
+<p>The Portlet API provides two parameters to the processAction method: the ActionRequest and ActionResponse.</p>
+			</subsection>
+			<subsection name='Request Parameters, Portlet Modes, Window States'>
+			<p>Request parameters are accessed via RunData in Jetspeed-1:</p>
+<source>
+<![CDATA[
+	String name = rundata.getParameters().getString("username");
+]]>
+</source>	
+			<p>With the Portlet API, portlet request parameters are accessed via the ActionRequest:</p>
+<source>
+<![CDATA[
+   String name = actionRequest.getParameter("username");
+]]>
+</source>	
+			<p>With the Portlet API, you can check the Portlet Mode or Window State:</p>
+<source>
+<![CDATA[
+        if (actionRequest.getPortletMode() == PortletMode.EDIT)
+        {
+        	if ( !request.getWindowState().equals(WindowState.MINIMIZED))
+        	{
+        	...        
+]]>
+</source>	
+			<p>The basic Portlet API does not have a way to map actions to methods as in Jetspeed-1.
+			If you would like this kind of behavior, we recommend using the <a href='http://www.springframework.org/docs/reference/portlet.html'>Spring MVC Portlet framework</a>
+			Here we demonstrate using portlet request parameters per form to map to specific actions:
+			</p>
+<source>
+<![CDATA[
+		String action = actionRequest.getParameter(SecurityResources.PORTLET_ACTION);
+        if (action != null && action.equals("remove.user"))
+        {
+            removeUser(actionRequest, actionResponse);
+        }
+        else if (action != null && action.equals("add.new.user"))
+        {
+            PortletMessaging.cancel(actionRequest, SecurityResources.TOPIC_USERS, SecurityResources.MESSAGE_SELECTED);
+        }
+        else if (action != null && action.equals("add.user"))
+        {
+            addUser(actionRequest);
+        }
+		...
+]]>
+</source>	
+			</subsection>
+			<subsection name='Persisting State: The Portlet Session'>
+			<p>The Portlet API provides built-in support for persistence of Portlet state in the session.
+			The Portlet Session is similar to the <b>setTemp</b> methods in Turbine/Jetspeed-1, or the session support built into the Servlet API.
+			The Session is for persisting state associated with the current user session. There are two kinds of session state supported by the Portlet API:			
+			</p>
+			<ul>
+			<li>Application Session State: the session variable is shared by all portlets in a portlet application</li>
+			<li>Portlet Session State: the session variable is specific to the one portlet instance window</li>
+			</ul>
+			<p>Here is how we would get and set session information in Jetspeed-1, using the Turbine RunData API. Note that for both Jetspeed-1 and Jetspeed-2, the
+			object put in the session must be serializable:</p>
+<source>
+<![CDATA[			
+             rundata.getUser().setTemp(ACCOUNT_INFO, accountInfo);
+             ...
+             AccountInfo accountInfo = (AccountInfo)rundata.getUser().getTemp(ACCOUNT_INFO);
+]]>
+</source>	
+			<p>In here is the equivalent in Jetspeed-2 using the Portlet API:</p>
+<source>
+<![CDATA[	
+        AccountInfo accountInfo = (AccountInfo)
+        	actionRequest.getPortletSession().getAttribute(ACCOUNT_INFO, PortletSession.PORTLET_SCOPE);
+        -- or --
+        AccountInfo accountInfo = (AccountInfo)        
+	        actionRequest.getPortletSession().getAttribute(ACCOUNT_INFO, PortletSession.APPLICATION_SCOPE);        
+		
+		-- the setters --
+		PortletSession session = actionRequest.getPortletSession();
+		session.setAttribute(ACCOUNT_INFO, accountInfo, PortletSession.PORTLET_SCOPE);
+		-- or --
+		session.setAttribute(ACCOUNT_INFO, accountInfo, PortletSession.APPLICATION_SCOPE);		
+]]>
+</source>				
+			</subsection>
+			<subsection name='Persisting State: User Preferences'>
+			<p>The Portlet API provides a second persistence mechanism: User Preferences. User Preferences are fields of information stored on a per user/per portlet window basis.
+			The equivalent in Jetspeed-1 is Portlet Instance data, which is stored in the Jetspeed-1 Portlet Registry as name/value pair <b>parameter</b> XML elements.
+			Looking at the XREG file in Jetspeed-1, we have:			
+			</p>
+<source>
+<![CDATA[	
+        <parameter name="weather_city_info" value="US/IN/Bloomington" hidden="true"/>
+]]>
+</source>				
+			<p>The Portlet API allows you to define default values for preferences in the portlet.xml deployment descriptor. The user-specific values are stored in the Jetspeed Preferences database.
+			Here is an example of the default value for a preference as it would be defined in the deployment descriptor:
+			</p>
+<source>
+<![CDATA[	
+            <preference>
+                <name>weather_city</name>
+                <value>Oakland</value>
+            </preference>
+]]>
+</source>				
+		<p>Jetspeed-1 provides the <b>PortletInstance</b> interface on every portlet for accessing preference-like information. Whereas the preference information is per-user and per-instance in 
+		Jetspeed-2, in Jetspeed-1 preference information accessed via the PortletInstance interface is only per-instance(per PortletWindow) specific. These values are stored in the PSML file associated
+		with the PortletWindow. Please note that the values can still be <i>user-specific</i> when you are using the default mechanism for locating pages, which is by user. This means that in Jetspeed-1
+		preferences (or parameters) are made user-specific by the nature of how pages are retrieved. Since a page is located under a user home directory, then the preference is naturally per user.
+		</p>
+		<p>With Jetspeed-1, here we can retrieve PortletInstance data:</p>
+<source>
+<![CDATA[
+        // where "this" is a Jetspeed-1 Portlet object
+    	PortletInstance instance = this.getInstance(rundata);
+    	String value = instance.getAttribute("favoriteColor", "blue");
+    	-- or --
+    	this.getAttribute("favoriteColor", "blue", rundata);
+    	
+    	-- we can set preference data the same way in Jetspeed-1    	
+    	PortletInstance instance = this.getInstance(rundata);
+    	instance.setAttribute("favoriteColor", "red");
+    	-- or --
+    	this.setAttribute("favoriteColor", "red", rundata);
+]]>
+</source>	
+		<p>With the Portlet API in Jetspeed-2, we can use the Portlet Preferences in a more direct manner. 
+		Remember that the store() method must always be called after all modifications to the prefs during a request:</p>		
+<source>
+<![CDATA[
+        PortletPreferences prefs = actionRequest.getPreferences();
+        String color = prefs.getAttribute("favoriteColor", "blue");
+        ...
+        prefs.setAttribute("favoriteColor", "red");        
+        prefs.store();        
+        
+        // note that you can also retrieve multivalues for prefs
+        String values[] = actionRequest.getPreferences().getValues("stocks", defaultValues);
+        
+        // or retrieve all preferences as a Map
+        Map allPrefs = actionRequest.getPreferences().getMap();        
+]]>
+</source>	
+		</subsection>			
+	    </section>
+		<section name='Registries'>
+			<p>The Jetspeed-1 Registries hold the following information:</p>
+			<ul>
+			<li>Portlet Definitions</li>
+			<li>Security Definitions</li>
+			<li>Web Clients and Media Type Registries</li>
+			<li>Skins Definitions</li>
+			<li>Controller Definitions</li>
+			<li>Control Definitions</li>
+			</ul>
+			<p>This section will guide you through how to migrate each of these registries from Jetspeed-1 to Jetspeed-2</p>
+		<subsection name='Portlet Definitions'>
+		<p>Jetpeed-1 requires that all portlets are defined in an XML file known as an XREG file (XML Registry). Jetspeed-2 stores its portlet registry in the database.
+		 In Jetspeed-1, the XML registry is on the file system under the jetspeed webapp under WEB-INF/conf.
+		There can be one or more portlet registry entries. All portlets are defined with the element type <b>portlet-entry</b>.
+		</p>
+		<p>Migrating your Jetspeed-1 portlet registries to Jetspeed-2 registries requires writing a new Portlet API standard <b>portlet.xml</b> definition file. We do not provide an XSLT transform to do this for you.
+		Whereas the portlet.xml is defined by the Java Standard Portlet API, Jetspeed allows for additional information to be defined specific to the Jetspeed portal: the <b>jetspeed-portlet.xml</b> can hold Jetspeed-specific
+		deployment configurations. Some of the XREG elements map to the portlet.xml, whereas others will map to the jetspeed-portlet.xml as noted in the tables below.
+		The table below describes how to map each XML attribute of the <b>portlet-entry</b> element to its equivalent in the Portlet API portlet.xml or jetspeed-portlet.xml.
+		Note that we are mapping in this table from XML attributes to XML elements in the portlet.xml or jetspeed-portlet.xml:
+		</p>
+		<table>
+		<tr>
+		<th>J1 Attribute</th>
+		<th>J2 Element</th>
+		<th></th>
+		</tr>
+		<tr>
+		<td>name</td>
+		<td>portlet-name</td>
+		<td>The name of the portlet. This name is unique to each portlet application, but not unique system-wide.</td>
+		</tr>
+		<tr>
+		<td>hidden</td>
+		<td></td>
+		<td>No equivalent in the Portlet API, not applicable.</td>
+		</tr>
+		<tr>
+		<td>type</td>
+		<td></td>
+		<td>No equivalent in the Portlet API, not applicable.</td>
+		</tr>
+		<tr>
+		<td>parent</td>
+		<td></td>
+		<td>No equivalent in the Portlet API, not applicable.</td>
+		</tr>		
+		<tr>		
+		<td>application</td>
+		<td></td>
+		<td>No equivalent in the Portlet API, not applicable.</td>
+		</tr>
+		</table>
+		<p>
+		Continuing with the Portlet XREG conversion, lets now look at how to convert the XML elements of the <b>portlet-entry</b> element.
+		The table below describes how to map each XML element to its equivalent in the Portlet API portlet.xml:
+		</p>		
+		<table>
+		<tr>
+		<th>J1 Element</th>
+		<th>J2 Element</th>
+		<th></th>
+		</tr>
+		<tr>
+		<td>classname</td>
+		<td>portlet-class</td>
+		<td>The implementing Java class. This class will need to be ported at the source level.</td>
+		</tr>
+		<tr>
+		<td>media-type</td>
+		<td>supports, supports/mime-type, supports/portlet-mode</td>
+		<td>Media types supported by the portlet must be mapped to one or more <i>supports</i> elements, with subelements of <i>mime-type</i> and <i>portlet-mode</i> pairs.</td>
+		</tr>
+		<tr>
+		<td>meta-info/title</td>
+		<td>title</td>
+		<td>The title of the Portlet.</td>
+		</tr>
+		<tr>
+		<td>meta-info/description</td>
+		<td>description</td>
+		<td>The description of the portlet</td>
+		</tr>
+		<tr>
+		<td>category</td>
+		<td>portlet-info/keywords</td>
+		<td>Where there are multiple categories elements, keywords are comma-separated. In Jetspeed-2, you can configure categories in the Portlet-Selector administrative portlet based on keywords.</td>
+		</tr>
+		<tr>
+		<td>security-ref</td>
+		<td>jetspeed-portlet.xml: js:security-constraint-ref</td>
+		<td>If you port your Security constraints definitions, you can keep the same security definition names. Just note that security constraint definitions are referenced from the jetspeed-portlet.xml, not portlet.xml</td>
+		</tr>
+		<tr>
+		<td>parameter</td>
+		<td>init-param</td>
+		<td>Parameters in Jetspeed-1 should normally map to <i>init-param</i>s in the Portlet API. These are read only values that can only be changed by the administrator</td>
+		</tr>
+		<tr>
+		<td>parameter@name</td>
+		<td>init-param/name</td>
+		<td>The name of the init parameter</td>
+		</tr>
+		<tr>
+		<td>parameter@value</td>
+		<td>init-param/value</td>
+		<td>The value of the init parameter</td>
+		</tr>
+		<tr>
+		<td>parameter/meta-info/description</td>
+		<td>init-param/description</td>
+		<td>The description of the init parameter</td>
+		</tr>
+		<tr>
+		<td>parameter</td>
+		<td>portlet-preferences/preference</td>
+		<td>As well as migrating to init-params, parameters may also be migrated as default preferences. Note that preferences can optionally be read-only.</td>
+		</tr>
+		<tr>
+		<td>parameter@name</td>
+		<td>portlet-preferences/preference/name</td>
+		<td>The name of the preference</td>
+		</tr>
+		<tr>
+		<td>parameter@value</td>
+		<td>portlet-preferences/preference/value</td>
+		<td>The value of the preference</td>
+		</tr>
+		<tr>
+		<td>parameter@hidden</td>
+		<td>portlet-preferences/preference/read-only</td>
+		<td>Optionally you map want to map hidden values to read-only (true/false)</td>
+		</tr>
+		</table>
+		</subsection>
+		<subsection name='Security Definitions'>
+		<p>Jetspeed-1 supports a Security Constraint XML definition language that is very similiar to the XML security constraint definitions in Jetspeed-2.
+		Jetpeed-1 requires that all security definitions are defined in an XML file known as an XREG file (XML Registry). Jetspeed-2 stores its security registry either in an XML file or in the database.
+		 In Jetspeed-1, the XML registry is on the file system under the jetspeed webapp under WEB-INF/conf.
+		There can be one or more security registry entries. All security constraints are defined with the element type <b>security-entry</b>.
+		</p>
+		<p>Migrating your Jetspeed-1 security constraints registries to Jetspeed-2 registries requires writing a new <b>page.security</b> XML definition file. We do not provide an XSLT transform to do this for you.
+		The table below describes how to map each XML attribute of the <b>security-entry</b> element to its equivalent in the Portlet API portlet.xml or jetspeed-portlet.xml.
+		Note that we are mapping in this table from XML attributes to XML elements in the portlet.xml or jetspeed-portlet.xml:
+		</p>
+		<table>
+		<tr>
+		<th>J1 Attribute</th>
+		<th>J2 Attribute</th>
+		<th></th>
+		</tr>
+		<tr>
+		<td>security-entry@name</td>
+		<td>security-constraints-def@name</td>
+		<td>The name of the security constraint definition. This name is unique to the entire page.security file.</td>
+		</tr>
+		<tr>
+		<td>meta-info/title</td>
+		<td></td>
+		<td>No equivalent in Jetspeed-2, not applicable.</td>
+		</tr>
+		<tr>
+		<td>meta-info/description</td>
+		<td></td>
+		<td>No equivalent in Jetspeed-2, not applicable.</td>
+		</tr>
+		<tr>
+		<td>access</td>
+		<td>security-constraint</td>
+		<td>Jetspeed-1 security-entries contain 0..n <i>access</i> elements, Jetspeed-2 security-constraint-defs contain 0..n <i>security-constraint</i> elements.</td>
+		</tr>		
+		<tr>		
+		<td>access@action</td>
+		<td>security-constraint/permissions</td>
+		<td>
+		Actions in Jetspeed-1 are called Permissions in Jetspeed-2.
+		Both versions support wildcarding with the * character.
+		<ul>
+			<li>Jetspeed-1 default actions are view, customize, maximize, minimize, info, close.</li>
+			<li>Jetspeed-2 default permissions are view, edit, help, print</li>
+		</ul>
+		</td>
+		</tr>
+		<tr>		
+		<td>access/allow-if@role</td>
+		<td>security-constraint/roles</td>
+		<td>Jetspeed-1 constrains by role through <i>allow-if</i> elements with a <i>role</i> attribute.
+		Jetspeed-2 constrains by role with the <i>roles</i> element and a comma-separated list of one or more roles</td>
+		</tr>
+		<tr>
+		<td>access/allow-if@group</td>
+		<td>security-constraint/groups</td>
+		<td>Jetspeed-1 constrains by group through <i>allow-if</i> elements with a <i>group</i> attribute.
+		Jetspeed-2 constrains by group with the <i>groups</i> element and a comma-separated list of one or more groups</td>
+		</tr>	
+		<tr>		
+		<td>access/allow-if@user</td>
+		<td>security-constraint/users</td>
+		<td>Jetspeed-1 constrains by user through <i>allow-if</i> elements with a <i>user</i> attribute.
+		Jetspeed-2 constrains by user with the <i>users</i> element and a comma-separated list of one or more users, or the wildcard * to specify all users.</td>
+		</tr>		
+		<tr>		
+		<td>access/allow-if-owner</td>
+		<td>security-constraints/owner</td>
+		<td>You can set the constraint to be only accessible by the owner of the page. In Jetspeed-1, this is implied by the location of the page.
+		With Jetspeed-2 you must explicity name the owner in the element text of the owner element.</td>
+		</tr>
+		</table>				
+		</subsection>	
+		<subsection name='Web Clients and Media Type Registries'>
+		<p>The Web Clients and Media Type registries are already ported to Jetspeed-2 and a part of the core system.
+		Jetspeed-2 stores these registries in the database. However these tables can be populated using seed data
+		as described in the section below on seed data.</p> 
+		</subsection>
+		<subsection name='Skins'>
+		<p>The Skin registries are not directly portable to Jetspeed-2. Jetspeed-2 has moved towards a more standard CSS based 
+		skinning approach. There are two basic skinning techniques which can be combined:
+		</p>
+		<ul>
+		<li>1. Portlet API Standard Skins - see PLT.C of the portlet specification. A standard set of CSS styles are defined for global skinning of portlet content.</li>
+		<li>2. Jetspeed Decorators - Decorators can define their own skins which can then be leveraged by portlets by accessing these styles. The default decorators in Jetspeed also define the PLT.C styles as well</li>
+		</ul> 
+		</subsection>					
+		<subsection name='Controllers'>
+		<p>Controllers are deprecated in Jetspeed-2. There is no direct mapping for converting the Java code. Instead you will need to rewrite a new Layout portlet, or more likely simply use
+		one of the existing Layout Portlets that come with Jetspeed, which are quite flexible. The default layout portlets in Jetspeed support multi-column grids, nesting portlets, and complete
+		customization using the Portlet Customizer.
+		</p>
+		</subsection>
+		<subsection name='Controls'>
+		<p>Controls are deprecated in Jetspeed-2. There is no direct mapping for converting the Java code. Instead you will need to rewrite a new Portlet decorator, or more likely simply use
+		one of the existing Portlet decorators that come with Jetspeed, which are quite flexible. 
+		</p>		
+		</subsection>			
+		</section>	    
+		<section name="PSML">
+			<subsection name="The Jetspeed Sitemap">
+				<p>The Jetspeed Sitemap defines the navigational space of all pages in the portal.
+				Both versions 1 and 2 have similiar hiearchical file system-like site maps.
+				Both contain a root folder /, which in turn contains a tree of subfolders, where each subfolder 
+				can contain pages or more subfolders.</p>
+			</subsection>
+			<subsection name="Site Resources">
+				<p>In Jetspeed-2, there is a well-defined portal resources that do not always have equivalents in Jetspeed-1:
+				<table>
+				<tr><th>2.x</th><th>1.x</th><th>File</th></tr>
+				<tr><td>Page</td><td>Page</td><td>A <b>.psml</b> file.</td></tr>
+				<tr><td>Folder</td><td>--</td><td>A <b>folder.metadata</b> file, one per folder, N/A in Jetspeed-1</td></tr>
+				<tr><td>Link</td><td>--</td><td>A <b>.link</b> file, N/A in Jetspeed-1</td></tr>
+				<tr><td>Menu</td><td>--</td><td>Menus are defined in folder.metadata, N/A in Jetspeed-1</td></tr>
+				</table>
+				</p>
+			</subsection>	
+			<subsection name="Reserved Directories">
+				<p>There are reserved directories available in both versions. The naming is a little different.
+				  Any directory starting with an underscore (_) in Jetspeed-2 is considered a control directory
+				  and can be used by the profiler (see below) to locate special directories based on runtime criteria
+				  such as the user name or the roles of the user. Jetspeed-1 has a hard-coded set of reserved (control) 
+				  directories that are hard-coded into the profiling rules.
+				  </p>
+				  <table>
+				  <tr><th>1.x</th><th>2.x</th><th></th></tr>
+				  <tr><td>user</td><td>_user</td><td>Holds all user folders</td></tr>
+				  <tr><td>role</td><td>_role</td><td>Holds all role folders</td></tr>
+				  <tr><td>group</td><td>_group</td><td>Holds all group folders</td></tr>
+				  <td><td>{mediatype}</td><td>_mediatype</td><td>Content per mime/mediatype</td></td>
+				  <tr><td>{language}</td><td>_lanaguage</td><td>Content per language</td></tr>
+				  <tr><td>{country}</td><td>_country</td><td>Content per country code</td></tr>
+				  </table>
+				  <p>
+				  Where the J1 directory names are actually the names of the reserved directory, such as 
+				  {mediatype} would be actually <b>html</b> or {language} would be <b>en</b>. J2 requires 
+				  specifing control directories (_) such as <b>_mediatype/html</b>, or <b>_language/en</b>
+				</p>
+			</subsection>	
+			<subsection name="Profiling">
+				<p>The Profiling algorithm discovers the correct page to display during a request.
+				J1 has only two hard-coded algorithm for finding pages:</p>
+				<ul>
+				  <li>J1 user/mediatype/language/country fallback</li>
+				  <li>J1 rollback</li>
+				</ul>
+				<p>Note that these settings are system wide and must be changed on a per portal basis.
+				J1 expects an explicit container order of mediatype / language / country
+				</p>
+				<p>
+				  J2 has a profiling rules engine that takes dynamic runtime user information, and using profiling rules
+				  discovers the rules based on the algorithm defined in the rules.
+				  In J2 profiling rules are defined on a per user basis, although there is a system-wide default profiling rule.
+				</p>
+			</subsection>	
+			<subsection name="Differences in PSML Page">
+	<p>Jetpeed-1 requires that all portlets are defined in an XML file known as an XREG file (XML Registry). Jetspeed-2 stores its portlet registry in the database.
+		 In Jetspeed-1, PSML files can be stored under the jetspeed webapp under WEB-INF/psml. Or, Jetspeed-1 supports storing PSML files in the database.
+		 In Jetspeed-2, PSML files can be stored under the jetspeed webapp under WEB-INF/pages or WEB-INF/min-pages. Or, Jetspeed-2 supports storing PSML files in the database.		 
+		</p>
+		<p>Migrating your Jetspeed-1 PSML files to Jetspeed-2 PSML files requires porting the files manually, or writing a database conversion utility or XSLT transform. We do not provide an XSLT transform to do this for you.
+		The table below describes how to map each XML element or attribute from Jetspeed-1 to Jetspeed-2:
+		</p>				
+		<table>
+		<tr>
+		<th>J1 Element</th>
+		<th>J2 Element</th>
+		<th></th>
+		</tr>
+		<tr>
+		<td>portlets</td>
+		<td>page</td>
+		<td>The outermost container of all content found on a PSML page.</td>
+		</tr>
+		<tr>
+		<td>portlets@id</td>
+		<td>page@id</td>
+		<td>System wide unique identifier for this page.</td>
+		</tr>
+		<tr>
+		<td>metainfo/title</td>
+		<td>title</td>
+		<td>The Page Title.</td>
+		</tr>
+		<tr>
+		<td>security-ref</td>
+		<td>security-constraints/security-constraints-ref</td>
+		<td>The security constraint reference (0..1 in Jetspeed-1, 0..n in Jetspeed-2)</td>
+		</tr>
+		<tr>
+		<td>control</td>
+		<td>defaults/portlet-decorator</td>
+		<td>Requires porting your controls to J2 portlet decorators, or at least mapping the names to existing decorators in Jetspeed-2. Or you can use a global portlet decorator and ignore this optional setting.</td>
+		</tr>
+		<tr>
+		<td>controller</td>
+		<td>defaults/layout-decorator</td>
+		<td>Requires porting your Turbine controllers, screens navigations to J2 layout(page) decorators, or at least mapping the names to existing page decorators in Jetspeed-2. 
+		Or you can use a global portlet decorator and ignore this optional setting.</td>
+		</tr>
+		<tr>
+		<td>portlets/portlets/...</td>
+		<td>page/fragment/..., type="layout"</td>
+		<td>Sub-containers of fragments or portlets. In Jetspeed-2, fragments can be either containers or portlet definitions. Only fragments with the type of <b>layout</b> can be a container holding more fragments and containers.</td>
+		</tr>
+		<tr>
+		<td>portlets/portlets/controller</td>
+		<td>page/fragment@type=layout@name={layout-name}</td>
+		<td>Controllers roughly map to fragments of type = layout, named by the name attribute. Note that layouts are implemented as portlets and must be specified as PA::portlet-name.</td>
+		</tr>
+		<tr>
+		<td>portlets/entry</td>
+		<td>page/fragment/fragment@type="portlet"</td>
+		<td>A portlet window on a page.</td>
+		</tr>
+		<tr>
+		<td>entry@id</td>
+		<td>fragment@id</td>
+		<td>The system-wide unique ID of the portlet window.</td>
+		</tr>
+		<tr>
+		<td>entry@parent</td>
+		<td>fragment@name</td>
+		<td>The portlet registry reference. In Jetspeed-2 the name of the portlet must be specified as PA::portlet-name</td>
+		</tr>
+		<tr>
+		<td>entry/layout/property@name="column"@value={column}</td>
+		<td>fragment/property@name="column"@value={column}</td>
+		<td>The property containing the column position</td>
+		</tr>
+		<tr>
+		<td>entry/layout/property@name="row"@value={row}</td>
+		<td>fragment/property@name="row"@value={row}</td>
+		<td>The property containing the row position</td>
+		</tr>
+		</table>								
+		</subsection>	
+		<subsection name="Menus vs Tabs">
+		<p>There is a big difference with the navigational aspects, or menus, between Jetspeed-1 and Jetspeed-2.
+		Jetspeed-1 restricts menus navigation to navigation amongst <i>tabs</i>. Tabs are defined within a PSML page. 
+		Tabs are simply subcontainers in the PSML page, defined by the <b>portlets</b> element.
+		Whereas Jetspeed-1 does support navigation to other pages, the Tabbing Menus do not directly support it without
+		writing a specific  portlet to act as an external link.</p>
+		<p>Jetspeed-2 menu navigations map directly onto the Portal Site. Thus menu tabs represent portal resources.
+		Menus in Jetspeed-2 can point to folders, pages or links. This more naturally allows the user to navigate
+		over the entire portal site. 
+		</p>
+		<p>When migrating PSML files from Jetspeed-1 to Jetspeed-2, depending on whether you use advanced Jetspeed-1 controllers such as 
+		Card or Tab controllers, you may find that the pages do not port to Jetspeed-2 very well. In consideration of the lack of migration tools,
+		this leaves two immediate options:
+		</p>
+		<ul>
+		<li>Rewrite your PSML files to better map to the Jetspeed-2 site constructs, folders and multiple pages.</li>
+		<li>Enhance Jetspeed-2 to support card and tab controller behavior</li>
+		</ul>
+		</subsection>	
+		</section>	
+		<section name="XML API - Seed Data">
+		<p>Jetspeed-2 defines an XML API for populating the initial "Seed" data for your portal.  
+		Populating your seed data via the XML API provides an alternative to populating database data with database-specific and hard to read SQL scripts.
+		Additionally, the XML API can be used for importing and exporting data, or backing up and restoring from your Jetspeed-2 database. 
+		</p>
+		<p>
+		The XML API also provides a migration path over the maintenance cycle of your Jetspeed portal. 
+		The XML API was first implemented in version 2.1. To migrate your data from version 2.1 to 2.2, (if there are any database schema changes), 
+		the XML API can be used to migrate (by exporting and importing) across versions.		
+		</p>
+		<p>As of 2.1, the Jetspeed API supports the following elements:</p>
+		<table>
+		<tr>
+		<th>Element</th>
+		<th>Description</th>
+		</tr>
+		<tr>
+		<td>MimeTypes</td>
+		<td>Mime Types supported by the portal such as text/html, text/xhtml....</td>
+		</tr>
+		<tr>
+		<td>MediaTypes</td>
+		<td>Mediat Types supported by the portal such as html, xml, wml...</td>
+		</tr>
+		<tr>
+		<td>Capabilities</td>
+		<td>General capabilities of web clients that access the portal</td>
+		</tr>
+		<tr>
+		<td>Clients</td>
+		<td>Supported Web Clients by the portal</td>
+		</tr>
+		<tr>
+		<td>Roles</td>
+		<td>Define all roles defined to the initial configuration of the portal</td>
+		</tr>
+		<tr>
+		<td>Groups</td>
+		<td>Define all groups defined to the initial configuration of the portal</td>
+		</tr>
+		<tr>
+		<td>Users</td>
+		<td>Define all initial users defined to the initial configuration of the portal, minimally admin and guest(anon) users</td>
+		</tr>
+		<tr>
+		<td>Permissions</td>
+		<td>Define initial J2EE security policy for this portal. Note that permissions are turned off by default.</td>
+		</tr>
+		<tr>
+		<td>ProfilingRules</td>
+		<td>Define all the profiling rules in the initial portal such as role fallback, user-role-fallback, j1-emulation, default-j2, subsites and more</td>
+		</tr>
+		<tr>
+		<td></td>
+		<td></td>
+		</tr>
+
+		</table>
+		</section>
+		<section name='XML Schemas'>
+		<p>Reference for Jetspeed-2 XML schemas:</p>
+		<table>
+		<tr>
+		<td>Jetspeed-2 PSML</td>
+		<td><a href='http://portals.apache.org/jetspeed-2/2.1/schemas/psml.xsd'>http://portals.apache.org/jetspeed-2/2.1/schemas/psml.xsd</a></td>
+		</tr>
+		<tr>
+		<td>Jetspeed-2 Folder Metadata</td>
+		<td><a href='http://portals.apache.org/jetspeed-2/2.1/schemas/folder-metadata.xsd'>http://portals.apache.org/jetspeed-2/2.1/schemas/folder-metadata.xsd</a></td>
+		</tr>
+		<tr>
+		<td>Jetspeed-2 Seed Data</td>
+		<td><a href='http://portals.apache.org/jetspeed-2/2.1/schemas/j2-seed.xsd'>http://portals.apache.org/jetspeed-2/2.1/schemas/j2-seed.xsd</a></td>
+		</tr>
+		<tr>
+		<td>Jetspeed-2 Security Constraints</td>
+		<td><a href='http://portals.apache.org/jetspeed-2/2.1/schemas/page-security.xsd'>http://portals.apache.org/jetspeed-2/2.1/schemas/page-security.xsd</a></td>
+		</tr>
+		<tr>
+		<td>Jetspeed-2 Links</td>
+		<td><a href='http://portals.apache.org/jetspeed-2/2.1/schemas/link.xsd'>http://portals.apache.org/jetspeed-2/2.1/schemas/link.xsd</a></td>
+		</tr>
+		<tr>
+		<td>Jetspeed-2 Extended Portlet Descriptor</td>
+		<td><a href='http://portals.apache.org/jetspeed-2/2.1/schemas/jetspeed-portlet.xsd'>http://portals.apache.org/jetspeed-2/2.1/schemas/jetspeed-portlet.xsd</a></td>
+		</tr>
+		</table>
+		</section>
+		<section name="Where to Get Started?">
+		<p>The best place to get started is to create your own custom portal. This process is defined online at Apache. The <a href='http://portals.apache.org/tutorials/jetspeed-2/'>Jetspeed Tutorial</a> will take you through 
+		the initial steps of setting up your own (custom) Jetspeed portal, including setting up XML seed data, PSML, custom decorations and portlet applications.</p>
+		</section>
+	</body>
+</document>
+

Propchange: portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-migration.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-migration.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-users.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-users.xml?rev=722405&view=auto
==============================================================================
--- portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-users.xml (added)
+++ portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-users.xml Tue Dec  2 00:53:22 2008
@@ -0,0 +1,217 @@
+<?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>For Jetspeed-1 Users</title>
+		<subtitle>For Jetspeed-1 Users</subtitle>
+		<authors>
+			<person name="David Le Strat" email="dlestrat@apache.org" />
+		</authors>
+	</properties>
+	<body>
+		<section name="For Jetspeed-1 Users">
+	    <p>Jetspeed-2 is a new project, written from groundup and does not have any dependencies on Jetspeed-1.		   
+		   Jetspeed-2 is based on industry standards, designed for high-volume enterprise portals applications.
+		   The foremost difference is Jetspeeds Component Oriented Architecture, all assembled together with Spring.
+		   Components replace Turbine services with a standardized component model. 
+		   Deployment of new portlet applications, which was completely missing in Jetspeed-1, 
+		   is implemented to the Portlet API specification. Turbines file-based configuration 
+		   for properties are replaced managed components. Jetspeed-2 is fully decoupled from 
+		   the legacy projects that were intertwined in the Jetspeed-1 architecture.
+		   </p>
+		</section>
+		<section name="Whats New in Jetspeed-2">
+			<ul>
+			<li>1.	Fully Compliant with Java Portlet API Standard</li>
+			<li>2.	Separation of Portlet Applications From Portal</li>
+			<li>3.	Live Deployment Model for Portlet Applications and Portal Layouts</li>
+			<li>4.	Spring Component Based Architecture</li>
+			<li>5.	Multi-threaded Portlet Aggregation Engine</li>
+			<li>6.	Scalable Architecture</li>
+			<li>7.	Pipeline-based Request Processing</li>
+			<li>8.	JAAS Security</li>
+			<li>9.	Bridges Integration with Struts, JSF, PHP, Perl, Velocity</li>
+			<li>19.	CMS-based Site Navigations</li>	
+		</ul>				
+		</section>
+		<section name="Whats the same in Jetspeed-2">		
+			<p>Not much.</p>
+			<p>
+			In fact Jetspeed-2 does not re-use any of the code in Jetspeed-1. 
+			Some concepts are continued in Jetspeed-2, but with new design and implementations. 
+			The table below shows some of the concepts continued in Jetspeed-2 from Jetspeed-1. 
+			Note that even though the concepts are continued, they are have changed, 
+			in some cases significantly:
+				</p>
+			<ul>
+			<li>1.	PSML  -  Portlet Structured Markup Language. 
+				    Defines the layout of portlets on a page. 
+				    While the purpose is still the same, the XML format has changed. 
+				    Porting is possible, requires a migration tool. 
+				    PSML now fits into an overall Jetspeed Navigation Site as a page-type resource.
+				    No PSML porting tool is currently available. However, an XSLT transform could be a good choice.
+			</li>	
+			<li>2.	Portal Wide Security Policy and Constraints  -  Jetspeed-2 has two kinds of security 
+				    mechanisms: JAAS-based security policies, and declarative security constraints 
+				    much like Jetspeed-1 constraints. Where as Jetspeed-1 constraints were limited
+				    to PSML, Jetspeed-2 declarative security constraints are also applied to folders
+				    and links.</li>
+			<li>3.	Portlets  -  Portlets now must adhere to the new Portlet API. 
+				    No porting tool is currently available. 
+				    The Jetspeed-1 Portlet API will not be continued in Jetspeed-2.
+				    </li>
+			<li>4.  Turbine Services are out (Fulcrum). Jetspeed-2 is based on Spring components.</li>	
+			<li>5.  Registries  -  The Jetspeed-1 Registries are discontinued in Jetspeed-2. 
+				    All portlets are now stored in a Registry database in Jetspeed-2. 
+				    No porting tool is available. 
+				    Recommend converting your portlets to JSR-168 portlets, 
+				   packaging all portlets in a portlet application, 
+				   and deploying as standard WAR file. 
+				   Other registries are all deprecated.</li>
+			<li>6. JSP and Velocity Templates  -  Templates can be re-used to some extend. 
+				   Any references to Rundata or any other Turbine or Jetspeed-1 tools or 
+				   tags must be converted.</li>				
+			<li>7. Controls and Controllers  -  These concepts have changed, and are now called 
+				   decorators and layouts. The Turbine module concept, which backed controls 
+				   and controllers, is no longer supported. Layouts and decorators are now 
+				   only implemented as portlets, or as just plain markup. Layouts and templates 
+				   can be deployed to the portal as a deployable unit.</li>
+			<li>8. Jetspeed Configurations and Jetspeed Component Assemblies replace Property Files. 
+				   Component (services) should be assembled, not defined in property files. 
+				   Many of the features in Jetspeed-1 were represented as read-only properties in 
+				   the Jetspeed-1 static property files. Jetspeed-2 components can be configured with JMX.</li>
+			</ul>
+			</section>
+			<section name='Turbine Gone'>
+				<p>
+				Jetspeed-1 is tightly coupled to the Turbine MVC-2 framework, and this coupling permeates 
+				many areas of the Jetspeed API.  Jetspeed-2 does not rely on Turbine as the MVC-2 controller. 
+				Instead, we follow the separation of concerns pattern, and concentrates on doing one thing and doing it well. 
+				That is, implementing a portal. Where as Jetspeed-1 coupled MVC Controller, portal engine, and portlet container 
+				all into one deeply coupled servlet, Jetspeed-2 separates these concerns clearly in its architecture. 
+				The portal engine is Jetspeed-2. It is the MVC for page aggregation, leveraging the dispatching nature 
+				of the servlet architecture, and delegating the actual rendering of portlets to portlet application frameworks.  
+				These portlet applications can in turn have their own MVC frameworks, such as Struts portlet applications, 
+				JSF portlet applications, or Turbine portlet application frameworks.				
+				</p>
+			</section>
+		    <section name='RunData No More'>
+				<p>
+				Most notably missing from Portlet API portlets is the RunData class. 
+				The Jetspeed-1 API uses the RunData class ubiquitously, serving as a wrapper for both the servlet request and response. 
+				Other dependencies on Turbine include Portlet Actions, Portlet Aggregation Engine (ECS), 
+				the Service Architecture, Configuration and Turbine Modules. None of these exist in the newer version.
+				</p>					
+				<table>
+					<tr>
+					<th>Jetspeed-1</th>
+					<th>Jetspeed-2</th>
+					</tr>	
+					<tr>
+						<td>Run Data</td>
+						<td>Portlet API: Portlet Request and Portlet Response</td>						
+					</tr>
+					<tr>
+						<td>Portlet Aggregation Engine (ECS)</td>
+						<td>Jetspeed-2 Multi-threaded Portlet Container Engine</td>						
+					</tr>
+					<tr>
+						<td>Turbine Service Architecture</td>
+						<td>Jetspeed-2 Components</td>						
+					</tr>
+					<tr>
+						<td>Property Configuration Files</td>
+						<td>Spring Configurations, JMX</td>						
+					</tr>
+					<tr>
+						<td>Turbine Modules (Actions)</td>
+						<td>Portlet API Actions </td>						
+					</tr>
+					
+				</table>
+			</section>
+			<section name='Pluto is the Portlet Container'>
+				<p>The Jetspeed-2 portal does not implement the Portlet container. 
+					<a href='http://portals.apache.org/pluto'>Pluto</a> implements the JSR 168 interface 
+					contract for portlets running inside our portal.
+					The Pluto container handles all communication with portlets for the portal. 														
+				</p>					
+			</section>
+		    <section name='Aggregating, Isnt It?'>
+				<p>The aggregation engine and the Jetspeed-1 Portlet API are both coupled to a deprecated Jakarta package ECS 
+					(Element Construction Set). ECS generates HTML with Java code, storing the content in temporary 
+					Java objects before sending the HTML out to the servlet output stream. This wasteful use of Java objects 
+					leads to fragmentation on memory, accelerated garbage collection, and paging in high volume sites. 
+					The servlet API clearly provides a content stream for streaming out portlet content.  Jetspeed-2 models 
+					its aggregation engine upon the Portlet APIs streams and readers, analogous to the stream-based Servlet 
+					API for rendering content.</p>
+			</section>
+		    <section name='State and Life Cycle'>
+				<p>The Portlet API clearly defines the lifecycle of a portlet, the event sequences for actions, 
+				   and how the container can cache content from a portlet. The Portlet Lifecycle was not clearly 
+				   defined in Jetspeed-1. The portlet API clearly states that only one instance of a portlet will 
+				   reside in memory inside a container. The state of the portlet is directly related to the servlet state 
+				   for the current user session. While this may seem obvious, portlet state and lifetime was not clearly 
+				   defined in Jetspeed-1.					
+				</p>
+			</section>
+			<section name='Actions'>
+				<p>In version 1, actions were coupled to Turbine and not properly integrated into the Portlet class. 
+					In fact, actions were separate objects from portlets. In the Portlet API, actions are methods on the portlet. 
+					Action event handling and sequencing is clearly defined in the specification.</p>
+			</section>
+		    <section name='Standard Deployment'>
+				<p>Jetspeed-1 does not have a standardized method of deploying portlets and their supporting files, 
+					commonly referred to as portlet applications. In order to import an application, one must package 
+					registry files, class and jar files, PSML and templates so that they match the Jetspeed web application format.</p>
+				<p>In Jetspeed-2, the Portlet API defines a standard deployment descriptor for deploying Portal Applications into Jetspeed. 
+					Portal applications must be deployed to the portal. Analogous to the servlets packaged in a web-application (WAR)
+					 deployment model, portals support portlets packaged in a portal-application deployment model. 
+					The Portal Application archive follows the same format as the WAR format defined in the Servlet specification 
+					with an additional Portlet deployment descriptor file. The clear advantage in Jetspeed-2 is the ability to deploy 
+					live portlet applications to the server in a standardized format.</p>
+			</section>
+		    <section name='Resources and Deployment'>
+				<p>Jetspeed-1 resources such as portal templates, images, skins, controllers, controls, are all merged into the single 
+				   Jetspeed web application with no deployment model. For example, to override the default skin or top banner, the 
+				   resource files are copied into the portal directory, property files updated to point to the new resources, and the 
+				   server must be restarted. This made for the process of tailoring Jetspeed-1 portals to real production portals 
+				   a process of property and file merging. In fact Jetspeed-1 now has a Maven plug-in to manage production portals 
+				   separately from the core Jetspeed-1 portal. The need for this kind of tool covers up the fact that Jetspeed-1 
+					is missing a good deployment model for portal resources, requiring difficult portal maintenance procedures.</p>
+				<p>For a Jetspeed-2 production portal, portal resources are packaged in a Jetspeed-specific archive format. 
+					Thus portal resources (top banners, skins, images, style sheets) can all be deployed to dynamically tailor 
+					the portal at runtime.</p>
+			</section>
+		    <section name='the Standard'>
+				<p>JSR168 is the Portlet specification enables interoperability between Portlets and Portals. 
+					The specification defines a set of APIs that addresses standardization of portlet aggregation, 
+					personalization, presentation and security.  The goals of JSR168 are to: </p>
+				<ul>
+					<li>Define common Portal metaphor </li>
+					<li>Define a standard Portlet Java API </li>
+					<li>Ensure interoperability and portability</li>
+					<li>Enable multiple markups support </li>
+					<li>Ensure compatibility with other technologies </li>					
+				</ul>
+				<p>The Jetspeed-2 Portlet Server supports the JSR 168 standard. 
+				   This is an important initiative, introducing true portlet portability.</p>
+			</section>
+	</body>
+</document>
+

Propchange: portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-users.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/j1-users.xml
------------------------------------------------------------------------------
    svn:keywords = Id

Added: portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/jetspeed-eclipse.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/jetspeed-eclipse.xml?rev=722405&view=auto
==============================================================================
--- portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/jetspeed-eclipse.xml (added)
+++ portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/jetspeed-eclipse.xml Tue Dec  2 00:53:22 2008
@@ -0,0 +1,79 @@
+<?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>
+			Developing Jetspeed with Eclipse
+		</title>
+		<subtitle>How-to for Building and Debugging Jetspeed with Eclipse</subtitle>
+		<authors>
+			<person name="David Sean Taylor" email="taylor@apache.org" />
+		</authors>
+	</properties>
+	<body>
+		<section name="Developing with Eclipse">
+			<subsection name="The Eclipse Classpath">
+            <p>
+                Compiling, debugging, external dependencies, source code completion, searching, auto imports, all rely on a properly configured classpath. 
+                When you first create a project, a .classpath file is created in the projects root directory. 
+                With the Jetspeed source, we provide you with a ready-to-use Eclipse .classpath file.
+                We have already configured the relative source directories for you.
+                Eclipse provides a .classpath GUI editor from the Project->Properties menu option. 
+            </p>
+			</subsection>
+			<subsection name="JAR files and the Maven-2 repository">
+				<p>
+                  Jetspeed requires quite a few JAR files to be able to compile.
+                  The .classpath file that comes with Jetspeed is setup to get its JAR files out of a local Maven-2 repository.
+                  You can see all the JAR file dependencies from Eclipse. Go to Project->Properties->Java Build Path->Libraries.
+                  Notice all the JAR files are configured as VARIABLE library entries.
+                  Take one example: 
+					<source>
+                    M2_REPO/commons-lang/jars/commons-lang-2.0.jar                            
+					</source>                    
+                  The Variable is portion is M2_REPO.
+                  The Extension portion is /commons-lang/jars/commons-lang-2.0.jar
+                  Eclipse locates the JAR dependency from a Variable location root.
+                  In order for this classpath to work correctly, the variable root is dependent on a Maven-2 local repository file structure.                  
+				</p>
+				<p>
+                    To configure the M2_REPO variable, go to Window->Preferences->Java->Build Path->Classpath Variables,
+                    click on New, and define a new variable named MAVEN_REPO, pointing it out the root of your local Maven-2 repository,
+                    usually someplace like your $HOME/.m2/repository. 
+				</p>
+			</subsection>
+		</section>
+		<section name="Debugging with Eclipse and Tomcat">
+		<p>Remote debugging of the Jetspeed Portal running on Tomcat requires that you start Tomcat up with debugging enabled.
+		Here is a shell script that can be used to debug:
+		</p>
+<source><![CDATA[
+export JPDA_TRANSPORT=dt_socket
+export JPDA_ADDRESS=8000
+./catalina.sh jpda start
+]]></source>
+<source><![CDATA[
+<p>A DOS script:</p>
+set JPDA_TRANSPORT=dt_socket
+set JPDA_ADDRESS=8000
+catalina jpda start
+]]></source>		
+<p>From there, just follow the Eclipse documentation on how to remotely debug.</p>
+        </section>
+	</body>
+</document>

Propchange: portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/jetspeed-eclipse.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: portals/jetspeed-2/portal/branches/JS2-871-pluto-2.0-upgrade/src/site/xdoc/jetspeed-eclipse.xml
------------------------------------------------------------------------------
    svn:keywords = Id



---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org


Mime
View raw message