You are viewing a plain text version of this content. The canonical link for it is here.
Posted to pluto-scm@portals.apache.org by dd...@apache.org on 2005/11/02 00:49:41 UTC
svn commit: r330154 - in /portals/pluto/trunk/pluto-site/src/site/xdoc/v101:
./ developer/ userguide/
Author: ddewolf
Date: Tue Nov 1 15:49:35 2005
New Revision: 330154
URL: http://svn.apache.org/viewcvs?rev=330154&view=rev
Log:
combining 1.0.1 and 1.1 sites into more organized docs
Added:
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/arch.xml
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/build_source.xml
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/index.xml
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/integrate.xml
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/subversion.xml
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/install.xml
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/resources.xml
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/index.xml
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/portal.xml
portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/testsuite.xml
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/arch.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/arch.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/arch.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/arch.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,177 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed 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>
+ <author email="unknown">Jean-Baptiste Joret</author>
+ <author email="david.AT.daviddewolf.DOT.com">David H. DeWolf</author>
+ <title>Pluto Project</title>
+ </properties>
+
+<body>
+ <section name="Architecture Overview">
+
+<p>
+ Let's begin by examining Pluto's architecture and underlying concepts.
+ First, we briefly explain the portal that runs the RI, and see where
+ to find a portlet container inside a portal architecture. Next, we
+ investigate Pluto's architecture in detail. Last, we look at how it
+ solves one challenging item of the portlet container: portlet deployment.
+</p>
+
+<p><strong>The Portal</strong>
+ <blockquote>
+ Pluto normally serves to show how the Portlet API works and
+ offers developers a working example platform from which they can test
+ their portlets. However, it's cumbersome to execute and test the portlet
+ container without a driver, in this case, the portal. Pluto's simple
+ portal component is built only on the portlet container's and the JSR
+ 168's requirements. (In contrast, the more sophisticated, open source
+ Apache Jetspeed project concentrates on the portal itself rather than
+ the portlet container, and considers requirements from other groups.)
+ </blockquote>
+
+ <blockquote>
+ Figure 1 depicts the portal's basic architecture. The portal Web
+ application processes the client request, retrieves the portlets on
+ the user's current page, and then calls the portlet container to
+ retrieve each portlet's content. The portal accesses the portlet
+ container with the Portlet Container Invoker API, representing the
+ portlet container's main interface supporting request-based methods
+ to call portlets from a portal's viewpoint. The container's user must
+ implement the portlet container's Container Provider SPI (Service
+ Provider Interface) callback interface to get portal-related
+ information. Finally, the portlet container calls all portlets
+ via the Portlet API.
+ </blockquote>
+
+ <blockquote>
+ <div align="center">
+ <p><a href="../images/jw-0801-portal_arch.jpg"><img src="../images/jw-0801-portal_arch-thumb.jpg" alt="Portal Architecture" height="160" width="250" border="0"/></a></p>
+ <p><b><i><font size="-1">Figure 1. The simple portal included with Pluto. Click on the picture to enlarge it</font></i></b></p>
+ </div>
+ </blockquote>
+</p>
+
+<p><strong>The Portlet Container</strong>
+ <blockquote>
+ The portlet container, the portlets' runtime environment and a core
+ component of each portal, requires knowledge about the portal itself
+ and must reuse common code from it. Consequently, the portlet
+ container remains completely separated from every other portal component.
+ That said, you can embed the standalone portlet container in any portal
+ by complying with the portlet container's requirements, such as
+ implementing all SPIs.
+ </blockquote>
+
+ <blockquote>
+ The Portlet Container Invoker API, also called an entrance point, acts
+ as the portlet container's main calling interface. The API combines a
+ portlet container's lifecycle (init, destroy) with request-based
+ calling methods (initPage(), performTitle(), portletService(), and so
+ on). Because the portlet container calls a portlet in the end, the
+ method signature resembles the Portlet API's main portlet interface,
+ except that a portlet identifier must be passed. With this additional
+ portlet identifier, the container can determine the portlet and call
+ it accordingly.
+ </blockquote>
+
+ <blockquote>
+ Besides using the APIs to access the portlet container, the portal
+ must implement SPIs defined for the portlet container. Therefore,
+ the RI introduces container services: pluggable components that can
+ be registered at the container to either extend or provide basic
+ functionality. The RI includes the following built-in container services
+ (the first four must be implemented to run the portlet container, while
+ the fifth is optional):
+ </blockquote>
+
+ <blockquote>
+ <ul>
+ <li> Information provider: Gives the portlet container information about
+ the portal and its framework. Only known information or information
+ that should be stored within the portal is present through this
+ interface. Such information includes URL generation with navigational
+ state, portlet context, portlet mode, and window-state handling</li>
+ <li> Factory manager: Defines how to get an implementation through a
+ factory. (A normal portal should already own such an implementation.)</li>
+ <li> Log service: Defines a logging facility. (A normal portal should
+ already own such an implementation.)</li>
+ <li> Config service: Defines how to get configuration values. (A normal portal
+ should already own such an implementation.)</li>
+ <li> Property manager (optional): A property manager interface implementation
+ lets a portal handle properties as defined in the JSR 168 specification.</li>
+ </ul>
+ </blockquote>
+
+ <blockquote>
+ Strictly speaking, the Portlet Object Model also acts as an SPI, but has an
+ exceptional position among the SPIs. Therefore, don't consider it part of the
+ container services as it deals with all portlet objects and comprises a collection
+ of interwoven interfaces.
+ </blockquote>
+
+ <blockquote>
+ <div align="center">
+ <p><a href="../images/jw-0801-pluto_arch.jpg"><img src="../images/jw-0801-pluto_arch-thumb.jpg" alt="Pluto Architecture" height="144" width="250" border="0"/></a></p>
+ <p><b><i><font size="-1">Figure 2. The portlet container's architecture. Click on the picture to enlarge it</font></i></b></p>
+ </div>
+ </blockquote>
+</p>
+<p><strong>Portlet Deployment</strong>
+ <blockquote>
+ The portlet container can leverage the servlet container's functionality, upon
+ which the portlet container is built. To accomplish that, the portlet container
+ must inject servlet artifacts into each portlet-application war file, as Figure
+ 3 shows. The portlet component, Deployment, takes the original war file, then
+ injects a new or modified web.xml and a servlet to wrap each portlet and uses
+ it as a calling point. Then the portlet deployment passes the modified war
+ file to the application server deployment, which deploys it into the
+ application server's system. During the portlet's invocation, the portlet
+ container calls the injected servlet as an entrance point into the deployed
+ portlet war file.
+ </blockquote>
+
+ <blockquote>
+ <div align="center">
+ <p><a href="../images/jw-0801-RI_deploy.jpg"><img src="../images/jw-0801-RI_deploy-thumb.jpg" alt="Deployment" height="170" width="250" border="0"/></a></p>
+ <p><b><i><font size="-1">Figure 3. Portlet deployment in the RI. Click on thumbnail to view full-size image.</font></i></b></p>
+ </div>
+ </blockquote>
+</p>
+
+
+<p><strong>Pluto and the WSRP standard</strong>
+ <blockquote>
+ The JSR 168 aligns closely with the Web Services for Remote Portlets (WSRP) standard.
+ Both standards, which emerged at the same time, released open source implementations
+ capable of all necessary functions described in the respective specifications.
+ As a mutual goal, both standards strive to work well together. As a result,
+ the portlet container can run WSRP portlets as a consumer as well as a producer.
+ </blockquote>
+
+ <blockquote>
+ Pluto must be able to run multiple portlet containers in one portal. Consequently,
+ Pluto's portlet container can be instantiated multiple times and, more importantly,
+ it can be instrumented in different ways. Each portlet container, therefore, can
+ use different implementations for SPIs.
+ </blockquote>
+</p>
+</section>
+</body>
+</document>
+
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/build_source.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/build_source.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/build_source.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/build_source.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,124 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed 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>
+ <author email="unknown">Jean-Baptiste Joret</author>
+ <author email="david.AT.daviddewolf.DOT.com">David H. DeWolf</author>
+ <author email="nl.AT.essential.DOT.com.DOT.au">Nick Lothian</author>
+ <title>Pluto Project</title>
+ </properties>
+
+<body>
+<section name="Installation">
+<subsection name="Prerequisites">
+<p>It is expected that the user is familiar with the <a href="http://maven.apache.org">Apache
+ Maven</a> project tool.</p>
+</subsection>
+<subsection name="Requirements">
+<ul>
+ <li><a href="http://maven.apache.org/start/download.html">Maven 1.0.2</a></li>
+ <li>Java 1.4 or higher (If using JDK 1.4 in Tomcat 5.5, see Running.txt in Tomcat's home directory for modification instructions)</li>
+ <li>Servlet 2.3 compatible container: Tomcat 5.5 is suggested</li>
+</ul>
+</subsection>
+<subsection name="Get Maven Ready">
+<p>If you have not already done so, download and install Maven.</p>
+<p>2. build.properties settings:</p>
+<p>Please set these values in your <code>build.properties</code>
+ file:</p>
+<table width="650" border="1" cellspacing="0" cellpadding="3">
+ <tr>
+ <th width="134">property</th>
+ <th width="229">example</th>
+ <th width="261">what is it?</th>
+ </tr>
+ <tr>
+ <td width="134">maven.tomcat.home</td>
+ <td width="229">/tomcat</td>
+ <td width="261">location of the Tomcat install where you want to deploy Pluto</td>
+ </tr>
+ <tr>
+ <td width="134">maven.tomcat.version.major</td>
+ <td width="229">5</td>
+ <td width="261">Major version of Tomcat</td>
+ </tr>
+</table>
+<p>You can copy the <code>build.properties.sample</code> file and name it
+ <code>build.properties</code> and use this is a starting point.</p>
+</subsection>
+<subsection name="Building and deploying">
+
+<ul>
+ <li>change your directory to root of the Pluto project.</li>
+ <li>maven fullDeployment</li>
+ <li>This will take care of everything for you including copying shared jars,
+ and deploy the base Pluto portal along with the Portlet Test Suite</li>
+</ul>
+</subsection>
+<subsection name="Start Tomcat">
+<p>Run Tomcat, go to http://localhost:8080/pluto/portal.</p>
+</subsection>
+</section>
+
+<section name="What if I just want the Pluto container jar (like for Jetspeed 2)?">
+<ol>
+ <li>cd to /container directory</li>
+ <li>maven jar:install</li>
+</ol>
+<p>This will create the container jar in /container/target and also copy into
+ you maven repository.</p>
+ </section>
+
+<section name="What if I just want to deploy the Pluto portal without the test suite?">
+<ol>
+ <li>Follow all the steps from "<i>What if I just want the Pluto container
+ jar (like for Jetspeed 2)?</i>"</li>
+ <li>cd to the /portal directory.</li>
+ <li>maven (with no goal)</li>
+</ol>
+<p>This will invoke the default maven goal for the /portal sub-project, tomcat:deploy.
+ This will build and deploy the Pluto portal minus the test suite into
+ tomcat.</p>
+</section>
+
+<section name="What if I decide I want to deploy the test suite portlets after I deploy the Pluto portal by itself?">
+<ol>
+ <li>Follow all the steps from "<i>What if I decide I want to deploy the
+ test suite portlets after I deploy JUST the Pluto portal?</i>"</li>
+ <li>cd to the /testsuite directory.</li>
+ <li>maven (with no goal)</li>
+</ol>
+<p>This will invoke the default maven goal for the /testsute sub-project, deployTestsuite.
+ This will build and deploy the test suite portlets into your already deployed
+ Pluto portal.</p>
+</section>
+
+<section name="Install Portlets">
+ <p>
+ <ul>To install portlets after you successfully installed Pluto,
+ invoke Maven from the deploy subdirectory of the base install directory to deploy the portlet's war by executing:<br/>
+ <code>maven deploy -Ddeploy=FULL_PATH_TO_YOUR_PORTLET_WAR</code><br/>
+ Alternatively, you could use the <a href="../install.html#Admin_Portlet_Application">Admin Portlet Application</a>
+ to install custom portlets.
+ </ul>
+ </p>
+</section>
+
+</body>
+</document>
+
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/index.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/index.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/index.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/index.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,28 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed 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>
+ <author email="ddewolf@apache.org">David DeWolf</author>
+ <title>User Guide: Developing with Pluto</title>
+ </properties>
+<body>
+ <section name="Pluto Developer Guide">
+
+ </section>
+</body>
+</document>
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/integrate.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/integrate.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/integrate.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/integrate.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,224 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed 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>
+ <author email="sthepper@apache.org">Stefan Hepper</author>
+ <author email="shesmer@apache.org">Stephan Hesmer</author>
+ <title/>
+ </properties>
+ <body>
+ <section name="Integrating Pluto Into Your Container">
+ <p align="center">Stefan Hepper (sthepper@apache.org)</p>
+ <p align="center">Stephan Hesmer (shesmer@apache.org)</p>
+ <subsection name="1 Introduction">
+ <p>
+ <a href="http://jakarta.apache.org/pluto">Pluto.</a> is a project at Apache Jakarta (http://jakarta.apache.org/pluto) that provides the reference implementation of the Java⢠Portlet Specification. The first version of this specification is available as <a href="http://jcp.org/en/jsr/detail?id=168">JSR 168</a>. The pluto project contains two parts: the portlet container and a simple test portal driver. This document is about how to use the pluto portlet container and replace the sample portal driver with your own portal.
+</p>
+ <div align="center">
+ <p>
+ <a href="../images/jw-0801-portal_arch.jpg">
+ <img src="../images/jw-0801-portal_arch-thumb.jpg" alt="Portal Architecture" border="0"/>
+ </a>
+ </p>
+ <p>
+ <b>
+ <i>
+ <font size="-1">Figure 1. Basic portal architecture. Click on the picture to enlarge it</font>
+ </i>
+ </b>
+ </p>
+ </div>
+ <p>
+Figure 1 depicts a portal's basic architecture. The portalâs web application processes the client request, retrieves the portlets on the user's current page, and then calls the portlet container to retrieve each portletâs content. The portal accesses the Portlet Container by using the Portlet Container Invoker API. This interface represents the main interface of the portlet container supporting request-base methods to call portlets from a portal's point of view. The Container Provider SPI (Service Provider Interface) is a callback interface of the Portlet Container which needs to be implemented by the portal to get portal related information, the container cannot know about, like URL creation. Finally, the portlet container calls all portlets via the Portlet API.
+</p>
+ </subsection>
+ <subsection name="2 Portlet container pluto">
+ <p>The portlet container provides the runtime environment for the portlets. It is a core component of each portal, requires knowledge about the portal itself and has a need to reuse common code of the portal. Due to these requirements the pluto portlet container is built in a manner that completely separates the container from every other portal component. Said that, the portlet container is a standalone component that can be embedded in any portal by complying with the requirements of the portlet container, such as implementing all SPIs. The interfaces of the portlet container and its internal components are described in more detail in the next paragraphs.</p>
+ <div align="center">
+ <p>
+ <a href="../images/jw-0801-pluto_arch.jpg">
+ <img src="../images/jw-0801-pluto_arch-thumb.jpg" alt="Pluto Architecture" height="144" width="250" border="0"/>
+ </a>
+ </p>
+ <p>
+ <b>
+ <i>
+ <font size="-1">Figure 2. The portlet container's architecture. Click on the picture to enlarge it</font>
+ </i>
+ </b>
+ </p>
+ </div>
+ <p>The Portlet Container Invoker API, also called entrance point, is the main calling interface of a portlet container. It combines the lifecycle (init, destroy) of a portlet container as well as the request based calling methods (processAction, render). Due to its nature of calling a portlet in the end, the method signature looks similar to the main portlet interface of the Portlet API except that a portlet identifier needs to be passed additionally. With this additional parameter the container is able to determine the portlet and call it accordingly.</p>
+ <p/>
+ <p>Besides of the application programming interfaces the portlet container can be instrumented by providing different implementations through service provider interfaces. Therefore, the reference implementation introduces a concept called Container Services. This concept will be described in more detail in a later chapter.</p>
+ </subsection>
+ <subsection name="3 How to integrate pluto with a portal framework">
+ <p>This section covers in detail how the portal can call the container and which SPIs needs to be implemented by the portal in order to re-use pluto. The portal calls the pluto container via the portlet container entrance point and needs to provide implementations for the SPIs container services and the portlet object model.</p>
+ <subsection name="3.1 Portlet Container Entrance Point">
+ <p>The portlet container entrance point org.apache.pluto.PortletContainer, is the main interface between the portalâs framework / aggregation and the portlet environment. This interface is used to call the portlet environment and execute portlets. It doesnât match exactly to the Portlet API methods (init, processAction, render, destroy) but generalizes the interface wherever possible. </p>
+ <p/>
+ <p>The entrance point has methods with different scopes:</p>
+ <ul>
+ <li>
+ <p>Lifecycle methods are called only <strong>once</strong> (init/shutdown).</p>
+ <p>These methods are normally called directly from the service interfaces.</p>
+ </li>
+ <li>
+ <p>Request-based methods are called for each request, but only once for all portlets (portletLoad).</p>
+ <p>These methods must be called before the page aggregation actually starts and after aggregating the page, affecting all portlets being rendered on the page. Currently the only method in this category is portletLoad that ensures that the portlet is loaded and initialized before the request processing starts.</p>
+ </li>
+ <li>
+ <p>Request-based methods are called for each request and for each portlet (processPortletAction, renderPortlet).</p>
+ <p>These methods are normally called during the page aggregation as each portlet is being rendered.</p>
+ </li>
+ </ul>
+ <p>The contract defined by this interface must be fulfilled by the calling party to guarantee that the portlet environment will work correctly. </p>
+ </subsection>
+ <subsection name="3.2 Container Services">
+ <p>ContainerServices are a generic plug-in concept for extending the core portlet container with additional functionality. A ContainerService is defined by an interface, accessed by the portlet container and provided by the calling party (mostly portal / framework). In some cases the flow goes in the other direction, from container to portal. The nature of a service can be viewed as a service made available for the portlet container: The container needs it to run, but cannot implement the service itself.</p>
+ <p/>
+ <p>The Container Service concept makes the portlet container independent of portal functions so that it can be used by different portals and furthermore new services can be plugged in to get a richer portlet container experience. A ContainerServiceEnvironment describing all services must be created and passed to the portlet environment during initialization.</p>
+ <p/>
+ <p>Container Services can be split into two different categories:</p>
+ <ul>
+ <li>
+ <p>
+ <strong>Mandatory Base Services</strong>
+ </p>
+ <p>ContainerServices that must be provided by the calling party so that the portlet container is able to run.</p>
+ <ul>
+ <li>
+ <p>Information Provider Service</p>
+ <p>described in the next sub section</p>
+ </li>
+ <li>
+ <p>Factory Manager Service</p>
+ <p>Factory Service enables the portlet container to get implementation objects through a factory concept.</p>
+ </li>
+ <li>
+ <p>Log Service</p>
+ <p>This interface defines a logging facility.</p>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <p>
+ <strong>Optional Base Services</strong>
+ </p>
+ <p>ContainerServices that can be provided by the calling party, but the container can run without it.</p>
+ <ul>
+ <li>
+ <p>Property Manager Service</p>
+ <p>The implementation of the Property Service interface enables a portal to deal with properties as defined in the JSR 168 specification.</p>
+ </li>
+ <li>
+ <p>DynamicTitleService</p>
+ <p>Allows to support dynamic titles.</p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <subsection name="3.2.1 Information Provider Service">
+ <p>The Information Provider is a callback mechanism for the portlet environment into the calling party (mostly framework), to get hold of necessary information that can only be known by the portal, like hostname and URL generation. To differentiate between the scopes of the requested information, the portlet environment defines two interfaces: the DynamicInformationProvider and the StaticInformationProvider.</p>
+ <p>The DynamicInformationProvider provides request-based information, which changes for each request. Consequently a new DynamicInformationProvider needs to be passed to the portlet environment for each request. Typical information provided by this Information Provider is a URL to a portlet. Additional provider interfaces retrieved via getter methods of the DynamicInformationProvider are PortletURLProvider and PortletActionProvider.</p>
+ <p/>
+ <p>The StaticInformationProvider on the other hand provides non-request-based information, which is constant across all requests. Therefore only one StaticInformationProvider needs to be provided to the portlet environment (singleton). Typical information provided by this Information Provider is the root context of the portal. An additional provider interface retrieved via a getter method of the StaticInformationProvider is the PortalContextProvider that contains further information about the portal, which need to be provided to the portlet.</p>
+ <p/>
+ <p>Both Information Providers are not actively passed by the calling party to the environment. Instead they are made available to the portlet environment through the Container Service mechanism described in the next section. Basically, the portlet environment asks the calling party for an instance of one of the Information Providers and the calling party returns the correct Information Provider.</p>
+ </subsection>
+ <subsection name="3.3 Portlet Object Model">
+ <p>The Portlet Object Model interfaces are defined in the package org.apache.pluto.om. These interfaces should be seen as an internal interface that can be used by other components of the portal. The portlet environment only defines the interfaces that are necessary to execute the object model the portal that uses the portlet environment must implement the object model. </p>
+ <p>The object model represents the information available on different levels about portlets and the portlet application, like the deployment descriptors and customization data. </p>
+ <p>The following definitions are used to represent the different levels of information:</p>
+ <ul>
+ <li>
+ <p>
+ <strong>WebApplicationDefinition</strong> represents the context for the Portlet Application defined in the web.xml deployment descriptor.</p>
+ </li>
+ <li>
+ <p>
+ <strong>PortletApplicationDefinition</strong> describes a set (either all or a subset) of portlets that participate all in the same WebApplicationDefinition.</p>
+ </li>
+ <li>
+ <p>
+ <strong>PortletApplicationEntity</strong> is an instantiation of a PortletApplicationDefinition that is bound to a portal resource. It contains a set (either all or a subset) of portlets that participate all in the same PortletApplicationDefinition.</p>
+ </li>
+ <li>
+ <p>
+ <strong>ServletDefinition</strong> describes the portlet and its initial read-only properties that is not bound to any portal resource.</p>
+ </li>
+ <li>
+ <p>
+ <strong>Portlet Definition</strong> basic settings defined in the portlet.xml or set by administrators (read-only for users).</p>
+ </li>
+ <li>
+ <p>
+ <strong>Portlet Entity</strong> is a parameterized portlet definition, belonging to a user. </p>
+ </li>
+ <li>
+ <p>
+ <strong>Portlet Window</strong> is part of an aggregation tree that contains the portlet markup. The portlet window has navigational state attached to it.<!---->
+ </p>
+ </li>
+ </ul>
+ <p>Figure 3 depicts the relation between the different definitions and their hierarchical structure. The servlet definitions are embedded in the web application definition. From a web application definition several portlet application definitions can be created that may consist of portlet definitions based on the servlet definitions defined in the web application definition. Using the portlet application definition several portlet application entities can be created that include portlet entities that are based on the corresponding portlet definitions. Finally the portlet windows of a portlet entity are linked to their corresponding portlet entity.</p>
+ <div align="center">
+ <p>
+ <a href="../images/Relations.jpg">
+ <img src="../images/Relations.jpg" alt="Portal Architecture" height="144" width="250" border="0"/>
+ </a>
+ </p>
+ <p>
+ <b>
+ <i>
+ <font size="-1">Figure 3. Relations between the different application and portlet representations</font>
+ </i>
+ </b>
+ </p>
+ </div>
+ <p>The portlet object model represents these different layers allowing the portlet container to access the information layer-based.</p>
+ <p>The object model is split into four different sub-packages:</p>
+ <ul>
+ <li>
+ <p>common</p>
+ <p>contains generic interfaces that can be reused</p>
+ </li>
+ <li>
+ <p>window</p>
+ <p>contains all interfaces handling with portlet windows</p>
+ </li>
+ <li>
+ <p>entity</p>
+ <p>contains all interfaces handling with portlet application entities and portlet entities</p>
+ </li>
+ <li>
+ <p>portlet</p>
+ <p>contains all interfaces handling with portlet application definitions and portlet definitions</p>
+ </li>
+ <li>
+ <p>servlet</p>
+ <p>contains all interfaces representing the web application definitions and servlet definitions</p>
+ </li>
+ </ul>
+ <p>For the implementation of the different artifacts in the object model the model-view-controller pattern is used and for each artifact a read-only interface exists, and if required an interface with the setter methods and the ending Ctrl is provided.</p>
+ </subsection>
+ </subsection>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/subversion.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/subversion.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/subversion.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/developer/subversion.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,103 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed 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>
+ <author email="ddewolf@apache.org">David DeWolf</author>
+ <title>Developer Guide: Obtaining the Source Code</title>
+</properties>
+
+<body>
+ <section name="Developer Guide: Obtaining the Source Code">
+ <p>
+ There are several reasons why you may want to have access to
+ the pluto source code. Some may want to participate in
+ the development of Pluto by submiting patches. Others may want
+ to utilize Pluto as a reference implementation to clarify
+ the Portlet Specification. Whatever the reason, there are two
+ ways to access the source code.
+ </p>
+
+ <p>
+ <A href="#Downloading_the_Source_Distribution">Downloading the
+ most recent Source Distribution</A> is the easiest
+ way to access the source. Of course, because this method is
+ reliant on releases, you may not have the most recent source.
+ That said, you do have a better chance at recieving a more
+ stable codebase if you are using a distiribution.
+ </p>
+
+ <p>
+ <A href="#Using_Subversion">Using Subversion</A> to checkout the
+ absolute up-to-date version of the code is the best way to
+ retrieve the source code. If you plan to submit patches,
+ we ask that you use the Subversion Trunk to create your
+ diffs.
+ </p>
+
+ <subsection name="Downloading the Source Distribution">
+ <p>See the <a href="../mirrors.cgi">download instructions</a></p>
+ </subsection>
+
+ <subsection name="Using Subversion">
+ <p>The Pluto project uses the
+ <a href="http://subversion.tigris.org/">Subversion</a> version control
+ system. If you're new to Subversion, you can check out the
+ <a href="http://svnbook.red-bean.com/">online book</a> about Subversion.
+ Note that we are currently using Subversion 1.1.x (there are separate
+ versions of the book covering 1.0 and 1.1).</p>
+
+ <h2>Web Access to Subversion</h2>
+ <p>
+ If you just want to browse the source code, you can use the
+ <a
+ href="http://svn.apache.org/viewcvs.cgi/portals/pluto/trunk/?root=Apache-SVN">ViewCVS
+ web interface</a> to Subversion. This is current at all times.
+ </p>
+
+ <h2>Normal Subversion Access</h2>
+ <p>Anyone can check code out of Subversion. You only need to specify a
+ username and password in order to update the Subversion repository, and only
+ Pluto committers have the permissions to do that. We run Subversion
+ over standard HTTPS, so hopefully you won't have problems with intervening
+ firewalls.</p>
+
+ <h3>Check out from Subversion</h3>
+ <p>Again, anyone can do this. Use a command like:</p>
+ <pre>svn checkout https://svn.apache.org/repos/asf/portals/pluto/trunk/ pluto</pre>
+
+ <h3>Commit Changes to Subversion</h3>
+ <p>Any Pluto committer should have a shell account on
+ <tt>svn.apache.org</tt>. Before you can commit, you'll need to set a
+ Subversion password for yourself. To do that, log in to
+ <tt>svn.apache.org</tt> and run the command <strong>svnpasswd</strong>.</p>
+
+ <p>Once your password is set, you can use a command like this to commit:</p>
+ <pre>svn commit</pre>
+ <p>If Subversion can't figure out your username, you can tell it
+ explicitly:</p>
+ <pre>svn --username you commit</pre>
+ <p>Subversion will prompt you for a password, and once you enter it once, it
+ will remember it for you. Note this is the password you configured with
+ <tt>svnpasswd</tt>, not your shell or other password.</p>
+
+ <p>Thanks to <a href="http://geronimo.apache.org/">The Geronimo group</a> for these docs.</p>
+ </subsection>
+
+ </section>
+</body>
+</document>
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/install.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/install.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/install.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/install.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,232 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004, 2005 The Apache Software Foundation
+Licensed 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>
+ <author email="unknown">Jean-Baptiste Joret</author>
+ <author email="ddewolf.AT.apache.DOT.org">David H. DeWolf</author>
+ <author email="nl.AT.essential.DOT.com.DOT.au">Nick Lothian</author>
+ <author email="cdoremus.AT.apache.DOT.org">Craig Doremus</author>
+ <title>Pluto Project</title>
+ </properties>
+
+<body>
+
+<section name="Installation Guide">
+<p>This install guide covers the following types of installations:
+<ul><li><A href="#Installing_Distributions">Installing Distributions</A></li>
+<li><A href="#Installing_Portlets">Installing Portlets</A></li>
+ <ul>
+ <li><A href="#Installing_With_Maven">Using Maven to Install Portlets</A></li>
+ <li><A href="#Using_the_Admin_Portlet_Application">Using the Admin Portlet App to Install Portlets</A></li>
+ </ul>
+</ul>
+</p>
+</section>
+
+<section name="Installing Distributions">
+
+<subsection name="Binary Distribution">
+<p>The binary distribution of Pluto is packaged with Tomcat
+ (currently version 5.5.9). Pluto leverages Tomcat to
+ provide the web container in which the Pluto portlet
+ container executes. The binary distribution includes
+ the Pluto Portlet Container, The Portal Driver, the
+ Pluto Testsuite and the Admin Portlet application.</p>
+<p>To install the binary distribution:
+ <ul>
+ <li><A href="mirrors.cgi">Download</A>
+ the current binary distribution of Pluto</li>
+ <li>Extract the binary distribution to a directory
+ from here forward refered to as "<PLUTO_HOME>".</li>
+ <li>Startup the server by using the appropriate tomcat
+ startup script located at <PLUTO_HOME>/bin.
+ For *nix use startup.sh; for windows use startup.bat.</li>
+ <li>By default Tomcat 5.5 uses JDK 1.5 (J2SE 5.0). In order to run it with
+ JDK 1.4, a compatibility package needs to be downloaded and installed.
+ See the Running.txt file in the root directory for details.
+ </li>
+ <li>Point your browser to
+ <A href="http://localhost:8080/pluto/portal">The Pluto Driver</A>
+ and your ready to go!</li>
+ </ul>
+</p>
+</subsection>
+
+<subsection name="Library Distributions">
+<p>The pluto library distributions are packaged to allow
+ integration with an external portal server.</p>
+<p>To install the library distributions to your portal server:
+ <ul>Ensure that the pluto-x.x.x.jar is loaded by a classloader
+ to which both the portal and portlet application web apps
+ have access.</ul></p>
+
+</subsection>
+
+<subsection name="Source Distribution">
+<p>Installing the source distribution requires the most effort,
+ and is recomended only for those individuals who are interested
+ in modifying the container. The source distribution is
+ basically a snapshot of the source code repository at a given
+ time. Because of this, please see the build instructions, which
+ will provide information about how to build Pluto from scratch.
+ </p>
+<p>To install the source distribution into tomcat:
+ <ul>
+ <li>Install Java 1.4 or greater</li>
+ <li>Install Maven 1.0 or greater</li>
+ <li>Install Tomcat 4.x or Tomcat 5.x to
+ a directory from here forward refered to as
+ <TOMCAT_HOME></li>
+ <li>Edit your <PLUTO_HOME>/build.properties to include
+ the following properties:
+ <table><tr><th>Property</th><th>Value</th><th>Example(s)</th></tr>
+ <tr><td>maven.tomcat.home</td>
+ <td>Tomcat Installation Directory</td>
+ <td><code>\\usr\\local\\jakarta-tomcat.5.0.27</code>,
+ <code>c:\\jakarta-tomcat.5.0.27</code></td></tr>
+ <tr><td>maven.tomcat.version.major</td>
+ <td>Tomcat Major Version Number</td>
+ <td>5</td></tr>
+ </table></li>
+ <li>From <PLUTO_HOME> issue the command:
+ <code>'maven fullDeployment'</code></li>
+ <li>Startup the server by using the appropriate tomcat
+ startup script located at <PLUTO_HOME>/bin.
+ For *nix use startup.sh; for windows use startup.bat.</li>
+ <li>Point your browser to
+ <A href="http://localhost:8080/pluto/portal">The Pluto Driver</A>
+ and your ready to go!</li>
+ </ul>
+</p>
+</subsection>
+</section>
+
+<section name="Installing Portlets">
+<subsection name="Installing With Maven">
+<p><FONT color="red">
+ Currently, to automate the deployment/installation of portlets
+ you must utilize the source distribution of pluto.
+Alternatively, you could use the <a href="#Using_the_Admin_Portlet_Application">Admin Portlet Application</a>
+to install custom portlets.
+ </FONT></p>
+
+<p>In order to deploy a portlet application to pluto, you must
+ follow the steps below:
+</p>
+ <ul>
+ <li>Assemble your portlet application into a valid war.</li>
+ <li><p>Run the maven deploy goal on your war</p>
+ <p>This can be done by running this command line in the deploy subdirectory:<br/>
+ <pre>maven deploy -Ddeploy=/MyPathToMyPortlet/target/MyPortlet.war</pre>
+ </p>
+ <p>See the <a href="developer/build_source.html">Building From Source</a> document for detailed instructions.</p></li>
+
+ <p>Alternatively, there is an interactive ant script in the <tt>portlet-deploy</tt> directory
+ that will perform the same task as the Maven deployment goal.</p>
+
+ <li>Modify the Portlet Entity Registry and the Page Registry and Portlet Contexts files. These
+ configuration files are located at:
+<pre>
+ [portal-home]/WEB-INF/data/portletentityregistry.xml
+
+ [portal-home]/WEB-INF/data/pageregistry.xml
+
+ [portal-home]/WEB-INF/data/portletcontexts.txt
+</pre>
+
+<p>
+The Portlet Entity Registry file requires that you specify an application and
+a Portlet ID for your new Portlet. The Application ID must be unique. It also
+needs to know the name of the Portlet so that it can go out and find it in
+the webapps path. Furthermore, this information is used to map the Portlet
+name to the appropriate class path for loading the class. The following is an
+example of some additions you can make to the entity registry file:
+</p>
+
+<pre>
+<application id="6">
+ <definition-id>MyPortlet</definition-id>
+ <portlet id="1">
+ <definition-id>MyPortlet.MyPortlet</definition-id>
+ </portlet>
+</application>
+</pre>
+
+<p>
+The Page Registry provides Pluto with the layout information for your Portlet.
+The names used in the fragments must be unique as done in the following example:
+</p>
+
+<pre>
+<fragment name="MyPortlet" type="page">
+ <navigation>
+ <title>My First Portlet</title>
+ <description>...</description>
+ </navigation>
+
+ <fragment name="row3" type="row">
+ <fragment name="col3" type="column">
+ <fragment name="p4" type="portlet">
+ <property name="portlet" value="6.1"/>
+ </fragment>
+ </fragment>
+ </fragment>
+</pre>
+
+
+<p>
+The Portlet Contexts file (portletcontexts.txt) lists the webapp contexts for each portlet application
+that runs in Pluto. Each portlet app has a line in this file corresponding to a path and starting with
+a slash ('/'). In Tomcat, this path is the value of the 'path' attribute of the 'Context' element in
+a context XML descriptor in $TOMCAT_HOME/conf/Catalina/localhost (or another 'conf' subdirectory).
+</p>
+
+
+</li>
+</ul>
+</subsection>
+
+<subsection name="Using the Admin Portlet Application">
+<p>The Admin Portlet Application allows you to deploy custom portlets using an
+interface in Pluto's portal. This application automatically places the custom
+portlets to their proper place and updates the registries.
+</p>
+<p>Deploying a custom portlet application to Pluto using the Admin Portlet App
+ requires the following steps:
+</p>
+ <ul>
+ <li>Assemble your portlet application into a valid war.</li>
+ <li>Start Pluto and navigate to the <a href="http://localhost:8080/pluto/portal">local Pluto home page</a></li>
+ <li>Click on the Admin navigation link. The Admin Portlet App should appear.</li>
+ <li>In the Deploy War Portlet, click on the Browse button and select your war file</li>
+ <li>Click on the Submit button of the Deploy War Portlet</li>
+ <li>In the resulting page, fill in the Title, Description (optional), and the number
+ of rows and columns you desire for laying out the portlets. Click on Submit</li>
+ <li>In the resulting page, select from the drop downs which portlet will be deployed
+ in a particular row and column. Click on Submit.</li>
+ <li>After returning to the Deploy War Portlet 'home page', click on the blue 'Hot deploy . . .'
+ link to hot deploy the new portlet app and get redirected to its page.</li>
+ </ul>
+ <p>Check out the Deploy War Portlet's help mode (help link) for information
+ on redeploying and undeploying portlets and troubleshooting problems.</p>
+</subsection>
+</section>
+
+</body>
+</document>
+
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/resources.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/resources.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/resources.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/resources.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,47 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed 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>
+ <author email="unknown">Jean-Baptiste Joret</author>
+ <author email="david.AT.daviddewolf.DOT.com">David H. DeWolf</author>
+ <title>Pluto Project</title>
+ </properties>
+
+<body>
+<section name="Resources">
+ <p>
+ <table>
+ <tr><th>Resource</th><th>Type</th></tr>
+ <tr><td><a href="http://jcp.org/en/jsr/detail?id=168">JSR 168</a></td>
+ <td>JCP Request Info</td></tr>
+ <tr><td><a href="http://jcp.org/aboutJava/communityprocess/final/jsr168/index.html">Portlet Specification</a></td>
+ <td>Specification</td></tr>
+ <tr><td><a href="multiproject/pluto/dependencies.html">Pluto Container Dependencies</a></td>
+ <td>Dependecy Info</td></tr>
+ <tr><td><a href="multiproject/pluto-portal/dependencies.html">Portal Driver Dependencies</a></td>
+ <td>Dependecy Info</td></tr>
+ <tr><td><a href="multiproject/testsuite/dependencies.html">Test Suite Dependencies</a></td>
+ <td>Dependecy Info</td></tr>
+ <tr><td><a href="http://heavyz.sourceforge.net/pluto_zh">Chinese translation of Pluto documentation</a></td>
+ <td>Documentation</td></tr>
+</table>
+ </p>
+</section>
+</body>
+</document>
+
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/index.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/index.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/index.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/index.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,87 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed 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>
+ <author email="ddewolf.AT.apache.D0T.org">David DeWolf</author>
+ <title>Pluto User Guide</title>
+</properties>
+
+<body>
+<section name="User Guide">
+<subsection name="Prerequisites">
+ <p>It is expected that the reader of the user guide documentation
+ should has an understanding of Java Web Application development, and
+ Java Portlet Development.</p>
+</subsection>
+
+<subsection name="Pluto - The Pluto Container">
+<p>
+ Pluto is the reference implementation of the Portlet Specification.
+ It is a portlet container which manages the lifecycle and request
+ processing of portlets which adhere to the specification.
+</p>
+
+<p>
+ In an of itself, Pluto is not very usefull to the end user.
+ As a container, it does not have any understanding of portlet
+ invocation, portlet aggregation or other portal specific features.
+</p>
+
+<p>
+ For more information on how to integrate Pluto into your portal,
+ please see the <A href="../developer/integration.html">developer guides</A>.
+</p>
+
+</subsection>
+
+<subsection name="Pluto Portal Driver - The Test Portal">
+<p>
+ The Pluto Portal Driver is a simple portal implementation that
+ is provided for convenience sake. It's purpose is to provide
+ aggregation support so that Pluto may be easily tested, and
+ portlets may be easily developed.
+</p>
+
+<p>
+ For information on how to use, configure, and customize the
+ Portal Driver, please see the
+ <A href="portal.html">Portal Driver User Guide</A>.
+</p>
+
+</subsection>
+
+<subsection name="Pluto TestSuite - The Test Portlet Application">
+<p>
+ The Pluto TestSuite is a Portlet Application which can be used to test
+ Portlet Implementations. The TestSuite tests several basic portlet
+ functions and is a quick and dirty way to test for Portlet Specification
+ compliance. While a quick test of a portal using the testsuite won't
+ garuntee compliance, it will help flag any notable incompliance.
+</p>
+
+<p>
+ For information on how to use and configure the TestSuite, please see
+ the <A href="testsuite.html">TestSuite User Guide</A>
+</p>
+</subsection>
+
+</section>
+
+</body>
+</document>
+
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/portal.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/portal.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/portal.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/portal.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,440 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed 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>
+ <author email="nlothian.AT.apache.DOT.org">Nick Lothian</author>
+ <author email="ddewolf.AT.apache.DOT.org">David DeWolf</author>
+ <title>User Guide: Pluto Portal Driver</title>
+</properties>
+
+<body>
+<section name="User Guide: Pluto Portal Driver">
+ <p>
+ <ul>
+ <li><A href="#Limitations">Limitations</A></li>
+ <li><A href="#Configuration">Configuration</A></li>
+ <li><A href="#Defining_the_Portal_Layout">Defining the Portal Layout</A></li>
+ <li><A href="#Advanced_Customization">Advanced Customization</A></li>
+ <li><A href="#Internationalization">Internationalization</A></li>
+ <li><A href="#Further_Information">Further Information</A></li>
+ </ul>
+ </p>
+</section>
+
+
+<section name="Limitations">
+ <p>
+ The Pluto Portal is intended to provide an example implementation of
+ how to integrate Pluto into a portal. Additionally, it may be used for
+ the development of compliant portlets. In some places it lacks the
+ flexibility a true portal supplies. The portal is not designed for
+ maximum performance, but rather simplicity.
+ </p>
+
+ <p>
+ To learn how to embed Pluto in your own portal, see the
+ "<a href="../developer/integrate.html">Integration Guide</a>" document.</p>
+</section>
+
+<section name="Configuration">
+ <subsection name="Default Configuration">
+ <p>
+ Upon installation of the binary distribution of Pluto, the portal
+ driver is made available at <code>http://localhost/pluto/portal</code>.
+ The default installation is configured with a single portal page which
+ contains two instances of the testsuite portlet. This configuration
+ is also the default for installations completed from the source distribution
+ (or Subversion repository) and deployed using the Pluto deploy tool.
+ </p>
+ <p>
+ <table>
+ <caption><B>Default Configuration for Binary Distributions:</B></caption>
+ <tr><th>Configuration</th>
+ <th>Platform</th>
+ <th>Value</th><th>Description</th></tr>
+ <tr><td>Installation Directory</td>
+ <td>All</td>
+ <td><PLUTO_HOME></td>
+ <td>The directory to which you unarchived the distribution</td></tr>
+ <tr><td>Startup Scripts</td>
+ <td>*nix</td>
+ <td><PLUTO_HOME>/bin/startup.sh</td>
+ <td>The script used to startup the portal driver</td></tr>
+ <tr><td>Startup Scripts</td>
+ <td>Windows</td>
+ <td><PLUTO_HOME>/bin/startup.bat</td>
+ <td>The script used to startup the portal driver</td></tr>
+ <tr><td>Context Configuration</td>
+ <td>All</td>
+ <td><PLUTO_HOME>/conf/Catalina/localhost/pluto.xml</td>
+ <td>The Tomcat Context Configuration file</td></tr>
+ </table>
+ </p>
+
+ <p>
+ <table>
+ <caption><B>Default Configuration for Source Distributions:</B></caption>
+ <tr><th>Configuration</th>
+ <th>Platform</th>
+ <th>Value</th><th>Description</th></tr>
+ <tr><td>Installation Directory</td>
+ <td>All</td>
+ <td>${maven.tomcat.home}</td>
+ <td>The tomcat installation directory to which pluto has been installed</td></tr>
+ <tr><td>Startup Scipts</td>
+ <td>*nix</td>
+ <td>${maven.tomcat.home}/bin/startup.sh</td>
+ <td>The script used to startup the portal driver</td></tr>
+ <tr><td>Startup Scipts</td>
+ <td>Windows</td>
+ <td>${maven.tomcat.home}/bin/startup.bat</td>
+ <td>The script used to startup the portal driver</td></tr>
+ <tr><td>Context Configuration</td>
+ <td>Tomcat 5</td>
+ <td>${maven.tomcat.home}/conf/Catalina/localhost/pluto.xml</td>
+ <td>The Tomcat Context Configuration file</td></tr>
+ <tr><td>Context Configuration</td>
+ <td>Tomcat 4</td>
+ <td>${maven.tomcat.home}/webapps/pluto.xml</td>
+ <td>The Tomcat Context Configuration file</td></tr>
+ </table>
+ </p>
+
+ <p>When the Pluto Portal is first installed, it is made available at
+ the address http://localhost/pluto/portal/.</p>
+
+ <p>This location can be customized, using standard Tomcat functionality. To modify the <i>pluto</i> part of the
+ location, alter the path mapping in pluto's context configuration file <i>pluto.xml</i></p>
+
+ <p>Under Tomcat 4.1, pluto.xml will be created in the ${TOMCAT_HOME}/webapps/ directory. Under Tomcat 5, pluto.xml will be created
+ in the ${TOMCAT_HOME}/conf/Catalina/ directory. </p>
+
+ <p>In order to modify the context Pluto is running under, modify the <i>path</i> attribute:</p>
+ <p>
+ <b>Before:</b>
+ <source>
+ <Context path="/pluto" docBase="pluto" crossContext="true">
+ </Context>
+ </source>
+ </p>
+ <p><b>After:</b>
+ <source>
+ <Context path="/newlocation" docBase="pluto" crossContext="true">
+ </Context>
+ </source>
+ </p>
+
+ <p>After this modification (and restarting Tomcat),
+ the Pluto Portal will be available at the address http://servername/newlocation/portal/.
+ Further information on customizing the context configuration is available for
+ <a href="http://jakarta.apache.org/tomcat/tomcat-4.1-doc/config/context.html">Tomcat 4.1</a>
+ and <a href="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/config/context.html">Tomcat 5</a>.
+ </p>
+
+ <p>To modify the <i>portal</i> part of the location, alter the <i>url-pattern</i> for the
+ <i>pluto</i> servlet. This mapping can be found in the <i>web.xml</i> configuration file
+ for the Pluto web application.</p>
+ <p>
+ <b>Before:</b>
+ <source>
+ <servlet-mapping>
+ <servlet-name>pluto</servlet-name>
+ <url-pattern>/portal/*</url-pattern>
+ </servlet-mapping>
+ </source>
+ </p>
+ <p>
+ <b>After:</b>
+ <source>
+ <servlet-mapping>
+ <servlet-name>pluto</servlet-name>
+ <url-pattern>/app/*</url-pattern>
+ </servlet-mapping>
+ </source>
+ </p>
+ <p>After this modification (and restarting Tomcat),
+ the Pluto Portal will be available at the address http://servername/newlocation/app/
+ (assuming that the previous modification was also applied).
+ </p>
+ </subsection>
+
+ <subsection name="Registering Portlets for use">
+ <p>In order to use a Portlet in the Pluto Portal it needs to be registered. The Pluto Portal
+ keeps page registrations in a file named <i>portletentityregistry.xml</i> in the directory
+ ${TOMCAT_HOME}/webapps/pluto/data.</p>
+
+ <p>By default, this file looks like this:
+ <source>
+<?xml version="1.0" encoding="UTF-8"?>
+<portlet-entity-registry>
+ <application id="3">
+ <definition-id>testsuite</definition-id>
+ <portlet id="1">
+ <definition-id>testsuite.TestPortlet1</definition-id>
+ <preferences>
+ <pref-name>TestName4</pref-name>
+ <pref-value>TestValue4</pref-value>
+ <read-only>true</read-only>
+ </preferences>
+ </portlet>
+ </application>
+ <application id="4">
+ <definition-id>testsuite</definition-id>
+ <portlet id="1">
+ <definition-id>testsuite.TestPortlet2</definition-id>
+ <preferences>
+ <pref-name>TestName4</pref-name>
+ <pref-value>TestValue4</pref-value>
+ <read-only>true</read-only>
+ </preferences>
+ </portlet>
+ </application>
+</portlet-entity-registry>
+ </source>
+ </p>
+ <p>Each <application> tag defines one application (corresponding to one web-app on the
+ portal container), which can contain multiple <portlet> tags.
+ The "id" attribute in this tag identifies the application, and it does not need to be numeric.</p>
+
+ <p>The <definition-id> tag within the <application> refers to the name of the
+ web-app that contains the portlets in this application.</p>
+
+ <p>Each <portlet> tag defines one portlet. The "id"
+ attribute in this tag identifies the portlet. Note that the application id concatenated with the portlet
+ id will be mapped to the "value" attribute in the <proprety> tag in pageregistry.xml
+ (which is explained later).</p>
+
+ <p>Each <preferences> tag within the <portlet> tag defines name/value pairs for
+ the PorletPreferences.</p>
+
+ <p>In the example above two Portlet applications are made available to the portal with the
+ ids of "3" and "4". Both happen to point to the same webapp (<tt><definition-id>testsuite</definition-id></tt>).
+ Both applications define a single Portlet each. Application id 3 uses the Portlet <i>TestPortlet1</i>
+ (<tt><definition-id>testsuite.TestPortlet1</definition-id></tt>), while Application id 4 uses
+ the Portlet <i>TestPortlet2</i> (<tt><definition-id>testsuite.TestPortlet2</definition-id></tt>).
+ Note that prefixing the name of the Portlet with the name of web application (<i><b>testsuite</b>.TestPortlet1</i>)
+ is required.
+ </p>
+
+ <p>
+ Since Pluto 1.0.1-rc2, another configuration file, portletcontexts.txt, has been
+ included in the Pluto portal. The Portlet Contexts file ($PLUTO_HOME/WEB-INF/data/portletcontexts.txt)
+ lists the webapp
+ contexts for each portlet application that runs in Pluto. Each portlet app has a line in this
+ file corresponding to a path and starting with a slash ('/'). In Tomcat, this path is the value
+ of the 'path' attribute of the 'Context' element in a context XML descriptor in
+ $TOMCAT_HOME/conf/Catalina/localhost (or another 'conf' subdirectory).
+
+ </p>
+
+ <p>The Portlets themselves are defined in the portlet.xml configuration file within the
+ testsuite web application. In that file there are two Portlets defined,
+ <i>TestPortlet1</i> and <i>TestPortlet2</i>, both of which point to the same
+ portlet class (<tt>org.apache.pluto.portalImpl.portlet.TestPortlet</tt>).
+ See the javax.portlet specification (JSR-168) for futher details on using the portlet.xml file.
+ </p>
+ </subsection>
+
+ <subsection name="Defining the Portal Layout">
+ <p>Once the Portlets available have been defined the Portal layout needs to be defined. In the
+ Pluto Portal the file <i>pageregistry.xml</i> in the directory ${TOMCAT_HOME}/webapps/pluto/data defines this layout.</p>
+
+ <p>When Pluto is first installed, pageregistry.xml looks like this:
+ <source>
+<?xml version="1.0"?>
+<portal>
+ <fragment name="navigation" class="org.apache.pluto.portalImpl.aggregation.navigation.TabNavigation">
+ </fragment>
+
+ <fragment name="test" type="page">
+ <navigation>
+ <title>Test</title>
+ <description>...</description>
+ </navigation>
+
+ <fragment name="row" type="row">
+ <fragment name="col1" type="column">
+
+ <fragment name="p1" type="portlet">
+ <property name="portlet" value="3.1"/>
+ </fragment>
+ <fragment name="p2" type="portlet">
+ <property name="portlet" value="4.1"/>
+ </fragment>
+
+ </fragment>
+ </fragment>
+ </fragment>
+</portal>
+ </source>
+ </p>
+
+ <p>This configuration results in the Portal being displayed
+ (from the url http://servername/pluto/portal/test/) as Figure 1 shows.</p>
+
+ <div align="center">
+ <p>
+ <a href="images/defaultPortalLayout.gif"><img src="images/defaultPortalLayoutThumb.gif" alt="Default Portal Layout" border="0"/></a>
+ </p>
+ <p>
+ <i><b><font size="-1">Figure 1. Default Portal Layout. Click on the picture to enlarge it</font></b></i>
+ </p>
+ </div>
+
+ <p>Working from the top of pageregistry.xml down, the first important section we come to is:
+ <source>
+<fragment name="navigation" class="org.apache.pluto.portalImpl.aggregation.navigation.TabNavigation">
+</fragment>
+ </source>
+ </p>
+ <p>This section tells the Portal to add a navigation menu to the user interface. Each fragment of
+ type <i>page</i> will be displayed in the navigation menu, provided the fragment has a <navigation>
+ sub-element. Removing the <tt><fragment name="navigation" ...></fragment></tt> section
+ will result in no navigation menu being displayed.
+ </p>
+
+ <p>
+ The next section is:
+ <source>
+ <fragment name="test" type="page">
+ <navigation>
+ <title>Test</title>
+ <description>...</description>
+ </navigation>
+ ...
+ ...
+ </fragment>
+ </source>
+ </p>
+ <p>
+ This section defines a Portal "page", which is simply a container for one or more Portlets. The <i>name</i>
+ attribute must be unique within the pageregistry.xml file (if this constraint is not met an error
+ message <i>Fragment with this name <duplicated name> already exists in the pageregistry.xml.</i> will be written to your
+ log and your Pluto web application will fail to load).
+ </p>
+ <p>
+ The navigation subsection is used by the navigation menu (discussed previously). The <title>...</title>
+ defines the label that will be shown in the navigation menu. The <description>...</description>element
+ is not used.
+ </p>
+
+ <p>Inside the <tt><fragment type="page" .... ></fragment></tt> elements we find
+ <source>
+ <fragment name="row" type="row">
+ <fragment name="col1" type="column">
+
+ <fragment name="p1" type="portlet">
+ <property name="portlet" value="3.1"/>
+ </fragment>
+ <fragment name="p2" type="portlet">
+ <property name="portlet" value="4.1"/>
+ </fragment>
+
+ </fragment>
+ </fragment>
+ </source>
+ </p>
+ <p>This defines the layout of the Portal "page". In this case two Portlets will be laid out in two columns,
+ nested inside a single row.
+ </p>
+ <p>The configuration below will give the page a layout of two rows, with a Portlet in each. Note that the names of all fragments
+ need to be unique.
+ <source>
+ <fragment name="row1" type="row">
+ <fragment name="col1" type="column">
+ <fragment name="p1" type="portlet">
+ <property name="portlet" value="3.1"/>
+ </fragment>
+ </fragment>
+ </fragment>
+ <fragment name="row2" type="row">
+ <fragment name="col2" type="column">
+ <fragment name="p2" type="portlet">
+ <property name="portlet" value="4.1"/>
+ </fragment>
+ </fragment>
+ </fragment>
+ </source>
+ </p>
+ <p>The section
+ <source>
+ <fragment name="p1" type="portlet">
+ <property name="portlet" value="3.1"/>
+ </fragment>
+ </source>
+ </p>
+ <p>defines which portlet to display. <tt><property name="portlet" value="3.1"/></tt> tells the Portal
+ to lookup the Portlet "3.1" and display it in this location. The value "3.1" means refers to the ids given
+ in <i>portletentityregistry.xml</i> (discussed previously). In this case, it mean application id "3",
+ portlet id "1".
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Advanced Customization">
+ <subsection name="JSP Templates">
+ <p>It is possible to customize the JSP templates Pluto uses. This is beyond the scope of this document,
+ but a brief outline follows to get you started.</p>
+
+ <p>By default, Pluto uses JSP templates from the directory
+ ${TOMCAT_HOME}/webapps/pluto/WEB-INF/aggregation directory. This can be overridden by
+ adding a line like
+ <source>
+aggregation.base.dir=/WEB-INF/templates/
+ </source>
+ to the file ${TOMCAT_HOME}/webapps/pluto/WEB-INF/config/services/ConfigService.properties.
+ </p>
+ <p>The following JSP files are used by the Portal:
+ <ul>
+ <li>Banner.jsp - The blue title bar which says "Pluto - Reference Implementation". Only called from RootFragment.jsp</li>
+ <li>ColumnFragment.jsp - Called for each column fragment.</li>
+ <li>Head.jsp - The HTML header. Only called from RootFragment.jsp</li>
+ <li>PageFragment.jsp - Called for each Portal page displayed.</li>
+ <li>PortletFragmentFooter.jsp - The footer of each Portlet.</li>
+ <li>PortletFragmentHeader.jsp - The header of each Portlet.</li>
+ <li>RootFragment.jsp - Defines the layout of the Portal. This is the file to modify if you need
+ to modify the width of the navigation bar, for instance.</li>
+ <li>RowFragment.jsp - Called for each row fragment.</li>
+ <li>TabNavigation.jsp - Displays the navigation menu.</li>
+ </ul>
+ </p>
+ <p>
+ Most customization of the Portal can be done in RootFragment.jsp,
+ PortletFragmentHeader.jsp and PortletFragmentFooter.jsp.
+ </p>
+ </subsection>
+ <subsection name="Internationalization">
+ <p>The Pluto portal supports non latin-1 character-sets in its output. To enable this, uncomment the section
+ <source>
+ <init-param>
+ <param-name>charset</param-name>
+ <param-value>utf-8</param-value>
+ </init-param>
+ </source>
+ from the "pluto" Servlet section in the file ${TOMCAT_HOME}/webapps/pluto/WEB-INF/web.xml.</p>
+ </subsection>
+ <subsection name="Further Information">
+ <p>
+ Further information can be found in the <a href="../faq.html">FAQ</a>, on the <a href="../mail-lists.html">Mailing Lists</a>
+ and on the <a href="../wiki.html">Wiki</a>
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
+
Added: portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/testsuite.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/testsuite.xml?rev=330154&view=auto
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/testsuite.xml (added)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v101/userguide/testsuite.xml Tue Nov 1 15:49:35 2005
@@ -0,0 +1,34 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+Licensed 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>
+ <author email="ddewolf@apache.org">David DeWolf</author>
+ <title>User Guide: Testsuite</title>
+</properties>
+
+<body>
+<section name="Testsuite Overview">
+<p>
+
+</p>
+</section>
+
+
+</body>
+</document>
+