Added: portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/j1-migration.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/j1-migration.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/j1-migration.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/j1-migration.xml Thu Jul 16 21:01:09 2015 @@ -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="[email protected]" /> + </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 <portlet-entry> to <portlet> entries, <parameter> to <preference> or <init-param> + </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, 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 derivatives, +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> + <tr><td>{mediatype}</td><td>_mediatype</td><td>Content per mime/mediatype</td></tr> + <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> +
Added: portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/j1-users.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/j1-users.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/j1-users.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/j1-users.xml Thu Jul 16 21:01:09 2015 @@ -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="[email protected]" /> + </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> + Added: portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/license.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/license.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/license.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/license.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,218 @@ +<?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>Apache License, version 2.0</title> + </properties> + <body> + <section name="Apache License, version 2.0"> + <pre> +Apache License +Version 2.0, January 2004 +http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + +"License" shall mean the terms and conditions for use, reproduction, +and distribution as defined by Sections 1 through 9 of this document. + +"Licensor" shall mean the copyright owner or entity authorized by +the copyright owner that is granting the License. + +"Legal Entity" shall mean the union of the acting entity and all +other entities that control, are controlled by, or are under common +control with that entity. For the purposes of this definition, +"control" means (i) the power, direct or indirect, to cause the +direction or management of such entity, whether by contract or +otherwise, or (ii) ownership of fifty percent (50%) or more of the +outstanding shares, or (iii) beneficial ownership of such entity. + +"You" (or "Your") shall mean an individual or Legal Entity +exercising permissions granted by this License. + +"Source" form shall mean the preferred form for making modifications, +including but not limited to software source code, documentation +source, and configuration files. + +"Object" form shall mean any form resulting from mechanical +transformation or translation of a Source form, including but +not limited to compiled object code, generated documentation, +and conversions to other media types. + +"Work" shall mean the work of authorship, whether in Source or +Object form, made available under the License, as indicated by a +copyright notice that is included in or attached to the work +(an example is provided in the Appendix below). + +"Derivative Works" shall mean any work, whether in Source or Object +form, that is based on (or derived from) the Work and for which the +editorial revisions, annotations, elaborations, or other modifications +represent, as a whole, an original work of authorship. For the purposes +of this License, Derivative Works shall not include works that remain +separable from, or merely link (or bind by name) to the interfaces of, +the Work and Derivative Works thereof. + +"Contribution" shall mean any work of authorship, including +the original version of the Work and any modifications or additions +to that Work or Derivative Works thereof, that is intentionally +submitted to Licensor for inclusion in the Work by the copyright owner +or by an individual or Legal Entity authorized to submit on behalf of +the copyright owner. For the purposes of this definition, "submitted" +means any form of electronic, verbal, or written communication sent +to the Licensor or its representatives, including but not limited to +communication on electronic mailing lists, source code control systems, +and issue tracking systems that are managed by, or on behalf of, the +Licensor for the purpose of discussing and improving the Work, but +excluding communication that is conspicuously marked or otherwise +designated in writing by the copyright owner as "Not a Contribution." + +"Contributor" shall mean Licensor and any individual or Legal Entity +on behalf of whom a Contribution has been received by Licensor and +subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of +this License, each Contributor hereby grants to You a perpetual, +worldwide, non-exclusive, no-charge, royalty-free, irrevocable +copyright license to reproduce, prepare Derivative Works of, +publicly display, publicly perform, sublicense, and distribute the +Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of +this License, each Contributor hereby grants to You a perpetual, +worldwide, non-exclusive, no-charge, royalty-free, irrevocable +(except as stated in this section) patent license to make, have made, +use, offer to sell, sell, import, and otherwise transfer the Work, +where such license applies only to those patent claims licensable +by such Contributor that are necessarily infringed by their +Contribution(s) alone or by combination of their Contribution(s) +with the Work to which such Contribution(s) was submitted. If You +institute patent litigation against any entity (including a +cross-claim or counterclaim in a lawsuit) alleging that the Work +or a Contribution incorporated within the Work constitutes direct +or contributory patent infringement, then any patent licenses +granted to You under this License for that Work shall terminate +as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the +Work or Derivative Works thereof in any medium, with or without +modifications, and in Source or Object form, provided that You +meet the following conditions: + +(a) You must give any other recipients of the Work or +Derivative Works a copy of this License; and + +(b) You must cause any modified files to carry prominent notices +stating that You changed the files; and + +(c) You must retain, in the Source form of any Derivative Works +that You distribute, all copyright, patent, trademark, and +attribution notices from the Source form of the Work, +excluding those notices that do not pertain to any part of +the Derivative Works; and + +(d) If the Work includes a "NOTICE" text file as part of its +distribution, then any Derivative Works that You distribute must +include a readable copy of the attribution notices contained +within such NOTICE file, excluding those notices that do not +pertain to any part of the Derivative Works, in at least one +of the following places: within a NOTICE text file distributed +as part of the Derivative Works; within the Source form or +documentation, if provided along with the Derivative Works; or, +within a display generated by the Derivative Works, if and +wherever such third-party notices normally appear. The contents +of the NOTICE file are for informational purposes only and +do not modify the License. You may add Your own attribution +notices within Derivative Works that You distribute, alongside +or as an addendum to the NOTICE text from the Work, provided +that such additional attribution notices cannot be construed +as modifying the License. + +You may add Your own copyright statement to Your modifications and +may provide additional or different license terms and conditions +for use, reproduction, or distribution of Your modifications, or +for any such Derivative Works as a whole, provided Your use, +reproduction, and distribution of the Work otherwise complies with +the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, +any Contribution intentionally submitted for inclusion in the Work +by You to the Licensor shall be under the terms and conditions of +this License, without any additional terms or conditions. +Notwithstanding the above, nothing herein shall supersede or modify +the terms of any separate license agreement you may have executed +with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade +names, trademarks, service marks, or product names of the Licensor, +except as required for reasonable and customary use in describing the +origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or +agreed to in writing, Licensor provides the Work (and each +Contributor provides its Contributions) on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +implied, including, without limitation, any warranties or conditions +of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A +PARTICULAR PURPOSE. You are solely responsible for determining the +appropriateness of using or redistributing the Work and assume any +risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, +whether in tort (including negligence), contract, or otherwise, +unless required by applicable law (such as deliberate and grossly +negligent acts) or agreed to in writing, shall any Contributor be +liable to You for damages, including any direct, indirect, special, +incidental, or consequential damages of any character arising as a +result of this License or out of the use or inability to use the +Work (including but not limited to damages for loss of goodwill, +work stoppage, computer failure or malfunction, or any and all +other commercial damages or losses), even if such Contributor +has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing +the Work or Derivative Works thereof, You may choose to offer, +and charge a fee for, acceptance of support, warranty, indemnity, +or other liability obligations and/or rights consistent with this +License. However, in accepting such obligations, You may act only +on Your own behalf and on Your sole responsibility, not on behalf +of any other Contributor, and only if You agree to indemnify, +defend, and hold each Contributor harmless for any liability +incurred by, or claims asserted against, such Contributor by reason +of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + +To apply the Apache License to your work, attach the following +boilerplate notice, with the fields enclosed by brackets "[]" +replaced with your own identifying information. (Don't include +the brackets!) The text should be enclosed in the appropriate +comment syntax for the file format. We also recommend that a +file or class name and description of purpose be included on the +same "printed page" as the copyright notice for easier +identification within third-party archives. + +Copyright 2004 The Apache Software Foundation + </pre> + </section> + </body> +</document> + Added: portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/portlets-community.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/portlets-community.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/portlets-community.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/src/site/xdoc/portlets-community.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,56 @@ +<?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>Portlets Community</title> + <subtitle>Portlets Community</subtitle> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Portlets Community"> + <table> + <tr> + <th>Project</th> + <th>Description</th> + </tr> + <tr> + <td><a href="https://gems.dev.java.net/";><img src="images/portlets/gems.gif" border="0" /></a></td> + <td><a href="https://gems.dev.java.net/";>Gems</a> provides a collection of JSR-168 portlets. The list of available portlets include: + <ul> + <li>E-Mail Portlet</li> + <li>Calendar Portlet</li> + <li>Blog Portlet</li> + <li>RSS Feed Portlet</li> + <li>Calculator Portlet</li> + <li>Image Viewer Portlet</li> + <li>Horoscope Portlet</li> + </ul></td> + </tr> + <tr> + <td><a href="http://sourceforge.jp/projects/pal/";><img src="http://pal.sourceforge.jp/images/pal-logo.png"; border="0" /></a></td> + <td> + <a href="http://sourceforge.jp/projects/pal/";>PAL</a> provides a useful JSR-168 portlets, such as File Manager, Blog, Yahoo! Japan Search portlets. + </td> + </tr> + </table> + </section> + </body> +</document> +
![http://banners.wunderground.com/banner/${weather_style}/language/www/${weather_city_info}.gif"](http://banners.wunderground.com/banner/${weather_style}/language/www/${weather_city_info}.gif"){kind=link}
![http://banners.wunderground.com/banner/$!weather_style/language/www/${weather_city_info}.gif"](http://banners.wunderground.com/banner/$!weather_style/language/www/${weather_city_info}.gif"){kind=link}
![http://pal.sourceforge.jp/images/pal-logo.png"](http://pal.sourceforge.jp/images/pal-logo.png"){kind=link}