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.


-----------------------------------
Page Aggregation Redesign Overview
------------------------------------
Authors: Raphael Luta, David Sean Taylor

** Goals **

1. Refactor PSML Model and introduce a new Page model, fixing defects in old model
2. To reimplement the page aggregation features 
3. Simplify storage and manipulation of all aggregation data strucures
   Clean separation of profiling information from page storage
4. Support storing page information in a relational database
5. Single threaded and multiple threaded aggregation
6. Provide simple and clear 'hooks' for other components to manipulate Page components
   such as Page Selection, Layout Customization, and Content Caching)

** Defects in J1 Page Aggregation **

1. PSML couples preferences and user info with layout.
2. PSML has confusing terminology 'controls' 'controllers'
3. Aggregation process in Jetspeed-1 model was tied to Turbine framework via modules

** Solution Summary **

1. Seperation of Layout from Preferences and User Information
   The new model removes all preferences and user information from the design
   Preferences and User Information are specified in the Java Portlet Spec
   J2 stores preferences separately from layout

2. New Model Terminology Introduced
        'Controls' are now called 'Decorators'
        'Controllers' are now called 'Layouts'
        'Portlets' collections are now called 'Fragments'
        'Desktop' describes the entire Page layout comparable with Turbine layout+navigation

3. Jetspeed-2 no longer relies on Turbine.
   Turbine modules and all Turbine dependencies are not in Jetspeed-2.
   We now have the concept of a Desktop which has a layout component, a theme, and a current page.
   A page is the aggregated content of portlets.


-----------------------------------
Page Aggregation Model
------------------------------------
The new aggregation code is composed of the following elements:

1. pipeline stages in the main Jetspeed pipeline: 

    Profiler --> Layout -->  Aggregator

2. New OM model under tentatively (org.apache.jetspeed.om.page) 

3. New service for storing and retrieving pages (PageManager)
   with two implementation (database/file system)

4. a PortletRenderer component


------------------------
Pipeline in more Detail
------------------------

1.    Profiler valve
       |
       |-- find Desktop 
       |-- find Page

The Profiler finds a desktop and page dependent on the associated profiling rule associated with the current principal. A principal can have one profiling rule associated with it. Two rules are currently identified:

a. Standard Profiling Rule - applies J1 profiling rules based on the         standard J1 profiling criteria (user, mediatype, language, country, pagename, role, group)

b. Role-based Fallback - applies J1 role-based fallback algorithm

Design goals for Profiling Rules:
aa. pluggable algorithms
bb. generic engine based on Profiling Rule and Criteria model 
cc. Support Profiling Types to generically map request parameters without programming
    - standard
    - request parameters, attributes, properties
    - CCPP properties
    - User properties

c. The profiler finds both Desktops and Pages which are then put into the request context to be used by the next pipeline valve

2.    Layout valve
       |
       |-- compile and build the layout for the Desktop
       |-- compile and build the layout for the Desktop

The layout valve is the first pass of a two pass aggregation (layout, render)
Layout algorithm (Raphael Luta):

lStack = new Stack();
push page root layout element on lStack
while lStack is not empty
do
   cElement = pop lStack
   if cElement is hidden
     do nothing
   else
     put cElement in request attributes
     find Portlet registered under cElement name
     invoke Portlet in LAYOUT mode (through a sub-request to Portlet)
     retrieve from portlet response attributes a list of portlet and 
layout
elements to display
     discard any other output from portlet
     put only layout elements retrieved from response in lStack
     for all retrieved portlet elements
     do
        if portlet element is visible
          invoke PortletRenderer for retrieved portlet element with 
current
request (asynchronous mode)
        end if
     done
   end if
done

The goal of this algorithm is to launch the rendering process in asynchronous mode but only for those elements that are going to actually be displayed in the aggregated page. The idea is thus to allow the layout elements that
actually control the rendering to have a look at the page structure and
return what elements they will actually render when they are invoked in RENDER mode. Using a Jetspeed specific LAYOUT Portlet mode is a way to avoid defining Jetspeed specific Layout interfaces at the price of handling a sub-request within the main RENDER phase. It's also simply possible to define a PortletLayout interface that Portlet that want to be recognized as Layout elements need to implement and inovke a doLayout() method through this interface (this avoids having to manipulate the PortletRequest portletMode)
This is an important performance optimization in multi-threaded parallel
aggregation mode to avoid rendering some components for nothing because they are not visible in the final page. 

Also note that layout elements themselves are not sent to the Renderer 
in the layout phase because they will most likely not be able to output meaningful content without access the  actual portlet content and should not cause a major performance issue if ther rendering is serialized.

In summary:
- layout elements are never parallelized or cached
- visible portlet elements are sent to the rendering process in the  Layout pipeline valve


3. Portlet Render valve

The next valve in the process is the Aggregate valve that simply retrieves the root element of the page and invoke the PortletRenderer sevice in synchronous mode with this element
and request. This is enough to trigger the cascaded rendering all all elements that need to be displayed and aggregated. Exactly how
a Layout Portlet is expected to access the other rendered elements is
explained in more details in the PortletRenderer service description.


---------------------------------
PortletRenderer service
----------------------------------
This is the core of aggregation engine. It's responsible for rendering the
Portlet themselves and make the rendered content available to other portlets for inclusion.

This service only provides 3 public methods:

/** Render the specified Page fragment using pInstance as the portlet to
invoke and PortletRequest as the request to pass to pInstance. Result is returned in the PortletResponse.
  */


public void renderNow(Fragment fragment, 
                      PortletInstance pInstance,
                      RenderRequest request, 
                      RenderResponse rsp)

/** Render the specified Page fragment using pInstance and PortletRequest.
    The method returns before rendering is complete, rendered content can be   accessed through the
ContentDispatcher
*/

public void render(Fragment fragment, 
                   PortletInstance pInstance,
                   RenderRequest request)

/** Retrieve the ContentDispatcher for the specified request
*/
public ContentDispatcher getDispatcher(PortletRequest request)

 From an implementation perspective, the renderNow() method is pretty
straightforward but the multi-threaded
rendering is more involved.
Here are my current impelmentation thoughts (I've not yet fully 
explored the
problem though because it would
probably require some working code running to check for all possible
bottlenecks and deadlocks):

The RendererService implementation needs to have:
- a rendering queue rQueue where are queued all the pending rendering
requests. This queue needs to provided
   a thread-safe element retrieval method like Stack.pop() and push() (in
fact I was planning to use the default
   Stack implementation even though it's not FIFO as this queue should 
be)
- a pool of Worker threads that can render synchronously portlets
- a WorkerMonitor for controlling the worker threads and recycling them 
into
the pool
- a ContentDispatcher that gives access to generated content. A
ContentDispatcher is basically a wrapper around
   a Hashtable of PortletResponses keyed to fragment Ids.

Each time render() is invoked it would create a new RenderingRequest 
that
contains:
- a reference to the Fragment to render
- a reference to the Portlet Instance
- a thead-safe wrapper to the PortletRequest
- a simple PortletResponse implementation that writes to a buffer
It then adds the PortletResponse to the current session 
ContentDispatcher
(creating the ContentDispatcher if no
dispatcher is found within the current session), keyed to the Fragment 
ID.
It the puts the RenderingRequest in the rQueue and returns

The WorkerMonitor would continuously monitor the rQueue for new 
elements to
render and whenever a new element
is added to the queue, it dispatches it to an idle worker if any. When 
the
Worker is done rendering, it explicitely commits the
PortletResponse to signal to the ContentDispatcher that the content is
available and complete.

Finally the ContentDispatcher simply provides an include(Fragment ID,
PortletRequest, PortletResponse) method that copies its
stored buffered content into the provided PortletResponse output 
stream. If
content is not available when include() is
called, the ContentDispatcher either pauses until the content is 
availale
(for example, by periodically polling the
PortletResponse keyed to the ID is committed) or triggers a synchronous
rendering of the Fragment (for example if
no PortletResponse is currently keyed to this ID)

Layout portlets
---------------------
The Layout portlets are simple JSR 168 portlets that implement 2 
Jetspeed specific features:
- the LAYOUT mode and its associated raquest and response attribute 
names (or the LayoutPortlet interface if you think a custom mode is too cumbersome)
- they need to know how to get hold of the ContentDispatcher, either through
a request attribute (possibly the simplest way) or through the RendererService.

