Author: msnicklous Date: Fri Dec 2 14:25:30 2016 New Revision: 1772352 URL: http://svn.apache.org/viewvc?rev=1772352&view=rev Log: Added additional menu items and version 3 description.
Added: portals/site/pluto/src/site/resources/images/async.png (with props) portals/site/pluto/src/site/resources/images/hubaction.png (with props) portals/site/pluto/src/site/resources/images/lifecycleMethods.png (with props) portals/site/pluto/src/site/resources/images/phaseModel.png (with props) portals/site/pluto/src/site/xdoc/v30/v3Features.xml Modified: portals/site/pluto/src/site/site.xml portals/site/pluto/src/site/xdoc/subprojects/subprojects.xml portals/site/pluto/src/site/xdoc/v30/deploying.xml portals/site/pluto/src/site/xdoc/v30/getting-started.xml portals/site/pluto/src/site/xdoc/v30/portlet-api.xml portals/site/pluto/src/site/xdoc/v30/release-notes.xml portals/site/pluto/src/site/xdoc/v30/tck.xml Added: portals/site/pluto/src/site/resources/images/async.png URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/resources/images/async.png?rev=1772352&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/site/pluto/src/site/resources/images/async.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: portals/site/pluto/src/site/resources/images/hubaction.png URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/resources/images/hubaction.png?rev=1772352&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/site/pluto/src/site/resources/images/hubaction.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: portals/site/pluto/src/site/resources/images/lifecycleMethods.png URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/resources/images/lifecycleMethods.png?rev=1772352&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/site/pluto/src/site/resources/images/lifecycleMethods.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: portals/site/pluto/src/site/resources/images/phaseModel.png URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/resources/images/phaseModel.png?rev=1772352&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/site/pluto/src/site/resources/images/phaseModel.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Modified: portals/site/pluto/src/site/site.xml URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/site.xml?rev=1772352&r1=1772351&r2=1772352&view=diff ============================================================================== --- portals/site/pluto/src/site/site.xml (original) +++ portals/site/pluto/src/site/site.xml Fri Dec 2 14:25:30 2016 @@ -70,7 +70,8 @@ limitations under the License. <menu name="Pluto 3.0"> <item name="Getting Started" href="/v30/getting-started.html"/> <item name="Deploying Portlets" href="/v30/deploying.html"/> - <item name="Portlet API 3.0" href="/v30/portlet-api.html"/> + <item name="Portlet Concepts" href="/v30/portlet-api.html"/> + <item name="Version 3 Features" href="/v30/v3Features.html"/> <item name="Using the TCK" href="/v30/tck.html"/> <item name="Release Notes" href="/v30/release-notes.html"/> </menu> Modified: portals/site/pluto/src/site/xdoc/subprojects/subprojects.xml URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/xdoc/subprojects/subprojects.xml?rev=1772352&r1=1772351&r2=1772352&view=diff ============================================================================== --- portals/site/pluto/src/site/xdoc/subprojects/subprojects.xml (original) +++ portals/site/pluto/src/site/xdoc/subprojects/subprojects.xml Fri Dec 2 14:25:30 2016 @@ -28,8 +28,8 @@ limitations under the License. <section name="Pluto Subprojects"> <p> - Pluto 2.0 utilizes Maven 2 as it's project management and build - automation tool. Pluto follows maven's best practices and is organized + Pluto 3.0 uses Maven 3 as project management and build + automation tool. Pluto follows maven best practices and is organized into modules or subprojects. </p> @@ -37,14 +37,22 @@ limitations under the License. <p> <ul> <li> - <b>Pluto Container:</b> + <b><code>portlet-api</code>:</b> + Contains the code defining the portlet API. + </li> + <li> + <b><code>pluto-container</code>:</b> The Pluto Container is the core compontent of the Apache Pluto - project. All other modules either support the development. The + project. The Pluto Container is the reference implementation of the Portlet Specification. </li> <li> - <b>Pluto Tags:</b> + <b><code>pluto-container-api</code>:</b> + The Pluto container programming interface. + </li> + <li> + <b><code>pluto-taglib</code>:</b> The Java Portlet Tag Library implementation which is provided with the container. </li> @@ -56,13 +64,25 @@ limitations under the License. <p> <ul> <li> - <b>Pluto Portal Driver:</b> + <b><code>pluto-portal-driver</code>:</b> + The programming interface for the Pluto portal driver library. + </li> + <li> + <b><code>pluto-portal-driver-impl</code>:</b> A driver library for the Pluto Portlet Container. Provides service implementations and utilities for implementing a portal which utilizes the container. </li> <li> - <b>Pluto Portal:</b> + <b><code>pluto-container-driver-api</code>:</b> + Code that allows the Pluto portal driver to access the Pluto + portlet container. + Also contains code for container and driver initialization along + with the portlet servlet code that is dynamically deployed + for each configured portlet. + </li> + <li> + <b><code>pluto-portal</code>:</b> The user interface components (web application) of the Pluto Portal. The pluto portal is a simple portal application which embeds the portal. The portal is not meant to be a full enterprise @@ -71,28 +91,14 @@ limitations under the License. portlets. </li> <li> - <b>Pluto Testsuite:</b> - A test portlet which can be used to exercise and test any portlet + <b><code>pluto-testsuite</code>:</b> + JSR 286 Test portlets that can be used to exercise and test any portlet container. </li> - </ul> - </p> - </subsection> - - <subsection name="Libraries and Supporting Subprojects"> - <p> - <ul> - <li> - <b>Pluto Descriptor API:</b> - A domain model which represents the deployment descriptors read - by the portlet container. Contains service interfaces for reading - and writing portlet.xml and web.xml. - </li> <li> - <b>Pluto Descriptor Impl:</b> - The default implementation of the Pluto Descriptor API Subproject. - The default implementation utilzes castor for reading and writing - portlet and web application descriptors. + <b><code>portlet-tck_3.0</code>:</b> + Contains additional modules implementing the JSR 362 Technology Compliance Kit (TCK). + See <a href="../v30/tck.html">Using the JSR 362 TCK</a>. </li> </ul> </p> @@ -102,24 +108,61 @@ limitations under the License. <p> <ul> <li> - <b>Pluto Util:</b> + <b><code>portlet-util</code>:</b> Utilities for working with the Pluto Portal. Includes libraries for installing pluto, assembling portlet applications for deployment in pluto, deploying to pluto, and publishing portlets to pluto. </li> <li> - <b>Maven Plugin:</b> + <b><code>maven-pluto-plugin</code>:</b> Provides Maven goals for utilizing the Pluto utilities. Install the portal within a servlet container, assemble portlets, deploy portlets, and publish portlets to th Pluto Portal. </li> <li> - <b>Ant Tasks:</b> + <b><code>pluto-ant-tasks</code>:</b> Ant tasks which allow developers to utilize the Pluto utilities within ant. Currently supports assembling wars for deployment within pluto. </li> + <li> + <b><code>pluto-common</code>:</b> + An aggregator for Pluto code that must be placed in an application server or servlet + container shared library. + While not required for deployment on Apache Tomcat, the jar file + produced by this module may be useful for deployment on other platforms. + </li> + </ul> + </p> + </subsection> + + <subsection name="Demo Portlets"> + <p> + The Pluto distribution contains four version 3.0 portlet applications that + illustrate the use of all aspects of JSR 362 portlet programming. + <ul> + <li> + <b><code>PortletV3Demo</code>:</b> + Contains portlets that illustrate miscellaneous aspects + of the API. + </li> + <li> + <b><code>PortletV3AnnotatedDemo</code>:</b> + Contains portlets that illustrate the use of + the version 3.0 Extended Method Annotations feature. + </li> + <li> + <b><code>PortletHubDemo</code>:</b> + Contains portlets that show how you can use the + Portlet Hub JavaScript API to create portal-based single-page applications. + </li> + <li> + <b><code>chatRoomDemo</code>:</b> + Contains portlets that implement a simple chat room demo + based on the Portlet Hub JavaScript API and the portlet asynchronous + processing feature. + </li> </ul> </p> </subsection> Modified: portals/site/pluto/src/site/xdoc/v30/deploying.xml URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/xdoc/v30/deploying.xml?rev=1772352&r1=1772351&r2=1772352&view=diff ============================================================================== --- portals/site/pluto/src/site/xdoc/v30/deploying.xml (original) +++ portals/site/pluto/src/site/xdoc/v30/deploying.xml Fri Dec 2 14:25:30 2016 @@ -101,10 +101,8 @@ limitations under the License. <render-config default="Test Page"> ... ... <page name="Your Portal Page Name" uri="/WEB-INF/themes/pluto-default-theme.jsp"> - <portlet context="/your_portlet_app_context_path" - name="your_portlet_1"/> - <portlet context="/your_portlet_app_context_path" - name="your_portlet_2"/> + <portlet context="/your_portlet_app_context_path" name="your_portlet_1"/> + <portlet context="/your_portlet_app_context_path" name="your_portlet_2"/> </page> </render-config> ]]></source> Modified: portals/site/pluto/src/site/xdoc/v30/getting-started.xml URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/xdoc/v30/getting-started.xml?rev=1772352&r1=1772351&r2=1772352&view=diff ============================================================================== --- portals/site/pluto/src/site/xdoc/v30/getting-started.xml (original) +++ portals/site/pluto/src/site/xdoc/v30/getting-started.xml Fri Dec 2 14:25:30 2016 @@ -116,7 +116,7 @@ limitations under the License. the build process in order to access maven repositories and other information. </p> - <h4>Obtaining Pluto 3.0 Source Code"</h4> + <h4>Obtaining Pluto 3.0 Source Code</h4> <p> To browse the Pluto source code online, access Modified: portals/site/pluto/src/site/xdoc/v30/portlet-api.xml URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/xdoc/v30/portlet-api.xml?rev=1772352&r1=1772351&r2=1772352&view=diff ============================================================================== --- portals/site/pluto/src/site/xdoc/v30/portlet-api.xml (original) +++ portals/site/pluto/src/site/xdoc/v30/portlet-api.xml Fri Dec 2 14:25:30 2016 @@ -21,27 +21,119 @@ limitations under the License. <document> <properties> - <title>Portlet API version 3.0 Overview</title> + <title>Portlet Concepts</title> </properties> <body> - <section name="Portlet API version 3.0 Overview"> - <p> - JSR 362 Portlet Specification 3.0 introduces many improvements to the - portlet programming model. It adds configuration through annotation, - asynchronous support similar to the servlet asynchronous support, - multipart form support, support for CDI beans, method annotation support - allowing portlet methods to reside in different classes, and a JavaScript - API that allows portal pages to function as single-page applications. The - Pluto 3.0 portlet container implements all JSR 362 features and passes the - TCK. While doing so, Pluto 3.0 remains fully compliant to the 2.0 Portlet - Specification, meaning that version 2.0 portlets can run on the version - 3.0 portlet container. - </p> - <p> - To be continued ... - </p> + <section name="Portlet Concepts"> + <subsection name="The Portlet Phase Model"> + <p> + When a request arrives at a portal targeted to a portlet, the portlet container + executes portlet code according to a phase model. + </p> + <img src="../images/phaseModel.png"/> + <p> + There are three processing stages containing five processing phases, defined as follows: + </p> + <p> + The portlet API allows creation of URLs that can be included into portlet + markup in order to activate the portlet processing stages. + </p> + <ul> + <li> + The Action URL, or Partial Action URL triggers preparation stage processing. + </li> + <li> + The Render URL triggers aggregation stage processing. + </li> + <li> + The Resource URL triggers resourec stage processing. + </li> + </ul> + <p> + When a stage is triggered, the processing phases within that stage are executed. + </p> + <dl> + <dt> + Action Phase + </dt><dd> + The portlet can perform updates and set up render state for the Aggregation Stage. + The action phase is initiated thru form post targeting the portlet. + During action phase processing, the portlet can fire events, resulting in event phase processing. + </dd><dt> + Event Phase + </dt><dd> + During event phase processing, the portlet container routes any fired events to + the portlets subscribed to the events. + Portlets define the events they can fire and receive through configuration. + </dd><dt> + Header Phase (new with V3): + </dt><dd> + Called for all portlets before the overall portal response is committed. + Portlets can contribute header values, cookies, and markup for the HEAD section + and can declare page resource dependencies. + </dd><dt> + Render Phase: + </dt><dd> + Called after the header phase for all portlets has been executed. + The portlet generates its markup for aggregation into the portal page. + During the render phase, the portlet may only generate markup that the portal + is able to integrate into the portal page. + </dd><dt> + Resource Stage + </dt><dd> + Initiated by an Ajax request from portlet JavaScript code using a resource URL. + During the resource phase, the portlet has nearly complete control over + the response returned to the client. + It may produce markup, JSON data, or binary data, for example. + </dd> + </dl> + <p> + The portlet container drives portlet phase execution + by setting up the execution environment for each portlet and phase and + calling the corresponding portlet lifecycle methods. + </p> + <p> + The portlet participates in the phase model + by implementing the corresponding lifecycle methods + and by using the portlet API to carry out the appropriate tasks. + </p> + </subsection> + + <subsection name="The Portlet Lifecyce Methods"> + <img src="../images/lifecycleMethods.png"/> + <p> + Each portlet phase has a corresponding lifecycle method. + The portlet container executes the prrocessing phase by calling the portlet lifecycle method. + Each phase is provided with specific request and response objects. + Methods can implemented using the interfaces + <code>Portlet, ResourceServingPortlet, EventPortlet</code> and <code>HeaderPortlet</code>. + Portlets can be configured through annotation or using the portlet deployment descriptor. + </p><p> + Portlets can implement the lifecycle methods by extending the GenericPortlet class + or by using the extended method annotations. + </p><p> + When the extended method annotations are used, portlet lifecycle methods can be arbitrary methods in java classes. + The methods are identified by the portlet lifecycle method annotations and have + relaxed method signature requirements as compared to interface methods. + When the method annotations are used, portlets are implicitly configured if no + data beyond that provided in the annotation is required. + Additional configuration is possible through annotation or portlet deployment descriptor. + </p> + <ul> + <li> + Set up / tear down: @InitMethod, @DestroyMethod + </li><li> + Preparation stage: @ActionMethod, @EventMethod, + </li><li> + Aggregation stage: @HeaderMethod, @RenderMethod, + </li><li> + Resource stage: @ServeResourceMethod + </li> + </ul> + </subsection> + </section> </body> Modified: portals/site/pluto/src/site/xdoc/v30/release-notes.xml URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/xdoc/v30/release-notes.xml?rev=1772352&r1=1772351&r2=1772352&view=diff ============================================================================== --- portals/site/pluto/src/site/xdoc/v30/release-notes.xml (original) +++ portals/site/pluto/src/site/xdoc/v30/release-notes.xml Fri Dec 2 14:25:30 2016 @@ -28,6 +28,7 @@ </p> <p> </p> +<!-- <subsection name="Bug"> <ul> <li> @@ -37,7 +38,7 @@ <subsection name="Improvement"> </subsection> - +--> </section> </body> </document> \ No newline at end of file Modified: portals/site/pluto/src/site/xdoc/v30/tck.xml URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/xdoc/v30/tck.xml?rev=1772352&r1=1772351&r2=1772352&view=diff ============================================================================== --- portals/site/pluto/src/site/xdoc/v30/tck.xml (original) +++ portals/site/pluto/src/site/xdoc/v30/tck.xml Fri Dec 2 14:25:30 2016 @@ -104,6 +104,228 @@ limitations under the License. success or failure. </p> </subsection> + + <subsection name="Project Structure"> + <p> + The TCK source code is located in the subdirectory <code>./pluto/portlet-tck_3.0</code>. + The project consists of the following modules: + </p> + <dl> + <dt> + common + </dt><dd> + Common code used by the test portlets and the test driver. This + module also contains the XSL stylesheets used during the test + portlet module build to generate the test case list and page + configuration for the module. + </dd><dt> + deploy + </dt><dd> + The directory <code>deploy/target/deploy-files</code> contains the portlet war + files and the page file to be deployed on the system under test. + </dd><dt> + driver + </dt><dd> + The maven-based test driver. When this module is built, it + generates a consolidated test case list and page file for the test + cases and pages defined by all test case portlet modules. + </dd><dt> + TestModule1 + </dt><dd> + Intended to be a sample for writing TCK portlets. + Defines several portlets, each of which is placed on its own page. + </dd><dt> + TestModule2 + </dt><dd> + Intended to be a sample for writing TCK portlets. + Defines several portlets, all of which are placed on the same + portal page. Some tests produce links that are clicked by the test + driver when the test is run. Some tests set public render + parameters that are used by another test portlet. + </dd><dt> + TestModule3 + </dt><dd> + Intended to be a sample for writing TCK portlets. + Defines two portlets in separate portlet applications for public + render parameter testing. Both portlets are placed on the same + page. When the test driver clicks a test link in one portlet, the + test results are displayed in the second portlet. + </dd><dt> + V2*Tests + </dt><dd> + Modules with this naming scheme contain test cases to demostrate + backward compatibilty with the Portlet Specification version 2.0. + Portlets whose class names contain the string "_SIG_" contain + generated code for verifying the method signatures. These portlets + should not be changed by hand. The remaining portlets contain + additional V2 verification code. + </dd><dt> + V3*Tests + </dt><dd> + Modules with this naming scheme test v3.0 specific funtionality. + </dd> + </dl> + </subsection> + + <subsection name="The Page File"> + <p> + The page file defines the page names for the TCK and the portlets expected to + be on each page. This is an XML file in the form of a Pluto driver configuration + file. The schema for this file is located in the Pluto project at the following + location: + </p><p> + <code>./pluto/pluto-portal-driver/src/main/resources/pluto-portal-driver-config.xsd</code> + </p><p> + After the TCK has been built, complete page file for the TCK pages is contained + in the following file: + </p><p> + <code>./pluto/portlet-tck_3.0/deploy/target/deploy-files/pluto-portal-driver-config.xml</code> + </p><p> + It is expected that vendors will extract the portlet-to-page mapping information + from the page file in order to create the necessary configuration files for + the portal under test. + </p><p> + When creating pages for your system, note that the test driver expects links + to all test case pages to be available. + The test driver searches for the page links by link text, so it is important that + the links have the names defined in the page file. + </p> + </subsection> + + <subsection name="Building the TCK"> + <p> + Building the TCK produces the test portlets, a list of test cases in XML format, + an XML-based page file containing the page configuration expected by the test + cases, and the test driver itself. + </p><p> + To build portlet war files that do not contain any special configuration, use + the command: + </p><p> + <code>mvn clean install</code> + </p><p> + To build portlet war files that are configured for deployment on Pluto, use the + command: + </p><p> + <code>mvn clean install -Ppluto</code> + </p><p> + These commands can be executed either from the Pluto project base directory or + from the <code>./pluto/portlet-tck_3.0</code> directory. + </p> + </subsection> + + <subsection name="Deploying the TCK"> + <p> + Use the page file which has the default + name of <code>deploy/target/deploy-files/pluto-portal-driver-config.xml</code> to create + pages for your system. + The WAR files in the <code>deploy/target/deploy-files</code> + contain the test portlet code. Deploy these files on your system. + </p><p> + If you are testing with Apache Pluto, you can simply copy + the page file into the Pluto <code>webapps/pluto/WEB-INF</code> directory in order to set up the + pages. To deploy the WAR files on Pluto, copy them into the Pluto webapps directory. + </p> + </subsection> + + <subsection name="Running the TCK"> + <p> + Configure the parent POM file <code>./pluto/portlet-tck_3.0/pom.xml</code> to + address your system under test. See the properties section in the pom.xml file. + You can set the host name and port for the system under test, and can + also select the browser to be used by the Selenium WebDriver code. Note, + however, that if you use a browser other than "firefox" or "HTMLUnit" you will + have to download and install additional WebDriver software manually, and you may + need to add additional configuration properties (See the test.browser.webDriver + property in the parent POM). + </p><p> + At the time of this writing, the HTMLUnit driver does not support JavaScript + adequately for JSR 362 TCK purposes. You may need to try different drivers to + find the appropriate WebDriver driver for your environment. + </p><p> + All TCK tests were successfully executed through the test driver against Pluto + using the ChromeDriver web driver. See the portlet-tck_3.0/POM.xml file for + a configuration example. + </p><p> + Run the TCK by switching to the driver subdirectory and execute the command: + </p><p> + <code>mvn test -Prun-tck</code> + </p><p> + If you want to run a subset of the tests, use the "-Dtest.module=" option. The + driver will then only execute those tests whose test case name contains the + specified string. For example, if you want to run the signature verification + tests, use the command: + </p><p> + <code>mvn test -Prun-tck -Dtest.module=SIG</code> + </p><p> + You can also exclude specific tests by placing an exclamation point before the + text to be matched. For example, if you want to exclude the signature verification + tests, use the command: + </p><p> + <code>mvn test -Prun-tck -Dtest.module=!SIG</code> + </p><p> + The 'test.dryrun' flag will cause the test cases to be listed without executing them. + For example, the following command will list all of the test cases whose test + case name contains 'ResourceResponse', but will not execute them: + </p><p> + <code>mvn test -Prun-tck -Dtest.module=ResourceResponse -Dtest.dryrun=true</code> + </p><p> + The test driver will wait for a response for a default time of 3 seconds. If this + value proves to be too short, you can change it in the portlet-tck_3.0/POM.xml + file, or you can specify a timeout value using the 'test-timeout' command line + option. The timeout value is specified in seconds, as follows: + </p><p> + <code>mvn test -Prun-tck -Dtest.module=ResourceResponse -Dtest.timeout=5</code> + </p><p> + The test driver has an ignore list containing test case names that are not + required to pass in order for a portal product to be JSR 362 compliant. The + ignore list is an XML file in properties file format located at: + </p><p> + <code>portlet-tck_3.0/driver/src/main/resources/xml-resources/ignoredTestCases.xml</code> + </p><p> + By default, the test driver will ignore and will not execute all test cases + in the ignore list. If you wish to execute all test cases including those in + the ignore list, set the command line flag 'test.ignore' to false: + </p><p> + <code>mvn test -Prun-tck -Dtest.ignore=false</code> + </p> + </subsection> + + <subsection name="Passing the TCK"> + <p> + TCK execution is self-policing. If you are a portal vendor and wish to claim + JSR 362 compatibility for your product, you should be able to demonstrate that + this TCK can be executed against your product with no errors. + </p> + </subsection> + + <subsection name="Contesting a Test Case"> + <p> + When defining and implementing the TCK test cases, care was taken to assure + proper implementation and to test only required functionality. + </p><p> + However, mistakes may have occurred. If you feel that a test case is incorrectly + implemented or is invalid as defined, please proceed as follows. + </p><p> + In either case, please open an issue at the Pluto Jira: + </p><p> + <code>https://issues.apache.org/jira/browse/PLUTO/</code> + </p><p> + Prefix the summary with 'TCK:' in order to allow TCK issues to be readily + identified. Please be sure to specify the exact name(s) of the test case(s) in + question. + </p><p> + If you feel that the test case was implemented incorrectly, you may correct the + implementation and issue a pull request through github here: + </p><p> + <code>https://github.com/apache/portals-pluto/pulls</code> + </p><p> + If you feel that the test case is invalid as defined, you may update the ignore + list and issue a pull request. + </p><p> + If we agree that the test case is invalid or incorrectly implemented, we will + fix it or integrate your fix into the Pluto master and version 3.0 branches. + </p> + </subsection> </section> </body> Added: portals/site/pluto/src/site/xdoc/v30/v3Features.xml URL: http://svn.apache.org/viewvc/portals/site/pluto/src/site/xdoc/v30/v3Features.xml?rev=1772352&view=auto ============================================================================== --- portals/site/pluto/src/site/xdoc/v30/v3Features.xml (added) +++ portals/site/pluto/src/site/xdoc/v30/v3Features.xml Fri Dec 2 14:25:30 2016 @@ -0,0 +1,264 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- +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>Portlet API version 3.0 Overview</title> + </properties> + + <body> + + <section name="Portlet API version 3.0 Overview"> + <p> + This section presents some of the main new features introduced by JSR 362. + JSR 362 Portlet Specification 3.0 introduces many improvements to the + portlet programming model. It adds configuration through annotation, + asynchronous support similar to the servlet asynchronous support, + multipart form support, support for CDI beans, method annotation support + allowing portlet methods to reside in different classes, and a JavaScript + API that allows portal pages to function as single-page applications. The + Pluto 3.0 portlet container implements all JSR 362 features and passes the + TCK. While doing so, Pluto 3.0 remains fully compliant to the 2.0 Portlet + Specification, meaning that version 2.0 portlets can run on the version + 3.0 portlet container. + </p> + <p> + Additional Resources: + </p> + <ul> + <li> + The + <a href="http://jcp.org/en/jsr/detail?id=362">Java Community Process JSR 362 page</a> + will allow you to access the complete specification for full details. + </li> + <li> + The JavaOne 2016 presentation + <a href="https://static.rainfocus.com/oracle/oow16/sess/1462801563632001pOv8/ppt/JSR362-JavaOne-2016a.pdf">"Portlet Specification 3.0 Is Here!"</a> + provides a version 3.0 overview. + </li> + <li> + The <a href="../portlet-3.0-apidocs/index.html">Portlet API Version 3.0</a> + page documents the portlet programming interface. + </li> + </ul> + + <subsection name="Configuration by Annotation"> + <p> + The version 3.0 portlet API introduces the <code>@PortletApplication</code> + and <code>@PortletConfiguration</code> annotations to allow portlets to + be configured without using the deployment descriptor. + Note that the deployment descriptor can still be used. When both + configuration annotations and a portlet deployment descriptor are present, + values from the deployment descriptor override those provided + by annotation. + </p> + <pre> +@PortletApplication( + defaultNamespaceURI="https://www.java.net/", + events = { + @EventDefinition(qname=@PortletQName(namespaceURI="http://www.apache.org/", + localPart="event1") , payloadType = String.class), + @EventDefinition(qname=@PortletQName(namespaceURI="", + localPart="event4")) + } +) + + +@PortletConfiguration(portletName="Portlet1", + initParams = { + @InitParameter(name="color", value="#cafeba"), + }, + title={ + @LocaleString(locale = "EN", value="Annotated Portlet"), + } +) + </pre> + </subsection> + + <subsection name="Extended Method Annotations"> + <p> + Version 3 extends the idea of method annotations introduced with version 2. + Portlet methods may now be located in classes that do not implement portlet + interfaces. + Also, lifecycle methods belonging to a single portlet need not be in the same + class. + </p> + <p> + The extended method annotations <code>@HeaderMethod</code>, <code>@RenderMethod</code>, + and <code>@ServeResourceMethod</code> have relaxed method signature requirements + as compared to the methods defined by the portlet interfaces. + See the portlet API documentation for details. + </p><p> + Use of the extended method annotation <code>@RenderMethod</code> implicitly + configures a portlet. No additional configuration is required. + The following example defines a simple portlet render method. + If this method were located in a class with a default constructor within + a web application deployed on a version 3 portal, it would define and automatically + configure a portlet by the name of "BeanPortletDemo". + </p> + <pre> +@RenderMethod(portletNames = "BeanPortletDemo") +public String simpleRender() { + return "Hello, World!"; +} + </pre> + </subsection> + + <subsection name="CDI Support"> + <p> + Version 3 provides support for CDI in several ways. + Portlet classes are instantiated through the CDI container + to enable dependency injection while respecting + scope annotations on the portlet classes. + Dependency injection supported in portlet filters and listeners as well as + in asynchronous threads started through the <code>PortletAsyncContext</code> + object. + Many portlet artifacts have been made injectable - the + request and response objects, parameter objects, the portlet configuration + object, etc. + </p><p> + Custom CDI scopes for portlets have also been introduced. + <ul> + <li> + The portlet session scope - @PortletSessionScoped + </li> + <li> + The portlet request scope - @PortletRequestScoped + </li> + <li> + The render state scope - @RenderStateScoped + </li> + </ul> + </p> + </subsection> + + <subsection name="Asynchronous support"> + <p> + The portlet programming model provides asynchronous support similar to + that provided by servlets. + Using asynchronous support, long-running requests can run in separate thread + in order to free up application server resources. + Asynchronous support is provided for resource requests only. + </p><p> + Asynchronous processing must be started within original resource request. + The asynchronous thread runs in context of original resource request, + providing that it is started through the <code>PortletAsyncContext#start(Runnable)</code> + method. + This means that CDI injection can be used within async thread + in the same manner as for the original request. + The asynchronous listener and any portlet filters also run in context of original request. + </p><p> + The asynchronous thread can dispatch directly to JSP or servlet for producing output + and can also dispatch back to the resource method, if desired. + </p><p> + The following diagram illustrates a sample asynchronous processing sequence. + Note that this shows only one of many possible scenarios. + When the portal receives a resource request targeted to the asnychronous + portlet, the portlet container invokes the portlet resource method. + The portlet starts asynchronous processing, adds an asynchronous listener, + uses the portlet asynchronous context object to start a thread, and + returns to the container. + The asynchronous thread does its long-running work and dispatches back to the + original resource method. + The resource method then includes a JSP to produce output and completes + asynchronous processing. + </p> + <img src="../images/async.png"/> + </subsection> + + <subsection name="The Portlet Hub JavaScript API"> + <p> + The portlet specification defines a JavaScript API that can be used by portlet + code running on the browser to read and set render parameters, carry out portlet + actions, and generate resource URLs while remaining in an Ajax paradigm. + Updating parameters and executing actions through the portlet hub does not + cause a page refresh. + Instead, the portlet hub communicates with the portal, causing the portal + to carry out any required portlet processing. + The portlet hub then informs the portlet client code running on the browser about + any new parameters. + The portlet client can then create a resource URL to obtain any data or + markup required to update the page. + The portal implementation is responsible for making the portlet hub + module available on the portal page. + </p> + <p> + The following diagram illustrates portlet action processing initiated through + the portlet hub. + In this scenario, the portal page contains three portlets that make use of + the portlet hub. + Portlet B initiates an Ajax action through the portlet hub. + The portlet hub transmits the action request along with any form data and action + parameters to the portal server. + On the server, action processing is executed for portlet B. + During action processing, portlet B fires an event that portlet A can process. + The server executes the event phase for the event and transmits the new render + state information to the portlet hub running on the browser. + The portlet hub fires onStateChange events to portlets A and B to inform them + of the updated render state information. + The portlets can now use the portlet hub API to create resource URLs in order + to retrieve information corresponding to the new render state. + </p> + <img src="../images/hubaction.png"/> + <p> + The main JavaScript functions provided by the portlet hub are listed below. + </p> + <dl> + <dt><code> + Promise(PortletInit) register(<Portlet ID>) + </code></dt><dd> + Registers a portlet client designated by portlet ID with the Portlet Hub and returns object that provides access to remaining Portlet Hub functions. + </dd><dt><code> + ListenerID addEventListener(<listener type>, <listener method>) + </code></dt><dd> + The Portlet Hub informs Portlet Client of state changes by calling the event listener function and passing the updated portlet state. + </dd><dt><code> + Promise(url) createResourceUrl(<resource parameters>, <cacheability>, <resource ID>) + </code></dt><dd> + Creates a resource URL containing the current page / portlet state. + The URL can be used with the framework of choice to retrieve the resource. + </dd><dt><code> + setPortletState(<new portlet state>) + </code></dt><dd> + Allows portlet client to set private and public parameters, portlet mode, window state + </dd><dt><code> + action(<action parameters>, <form element>) + </code></dt><dd> + Carries out a portlet action in Ajax mode (Ajax action) + </dd></dl> + <pre> + </pre> + </subsection> + +<!-- + <subsection name="The Portlet Phase Model"> + <p> + </p> + <pre> + </pre> + </subsection> +--> + + </section> + </body> + +</document> +