Added: portals/site-live/pluto/v30/v3Features.html URL: http://svn.apache.org/viewvc/portals/site-live/pluto/v30/v3Features.html?rev=1772349&view=auto ============================================================================== --- portals/site-live/pluto/v30/v3Features.html (added) +++ portals/site-live/pluto/v30/v3Features.html Fri Dec 2 14:16:01 2016 @@ -0,0 +1,501 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml";> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <title>Pluto - Portlet API version 3.0 Overview</title> + <style type="text/css" media="all"> + @import url("../css/maven-base.css"); + @import url("../css/maven-theme.css"); + @import url("../css/site.css"); + </style> + <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> + </head> + <body class="composite"> + <div id="banner"> + <a href="http://portals.apache.org/pluto/"; id="bannerLeft"> + + <img src="http://portals.apache.org/pluto/images/apache-portals.gif"; alt="" /> + + </a> + <span id="bannerRight"> + + <img src="http://portals.apache.org/pluto/images/banner.png"; alt="" /> + + </span> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xleft"> + Last Published: 2016-12-02 + | + <a href="http://portals.apache.org/pluto"; class="externalLink">Home</a> + </div> + <div class="xright"> <a href="../portlet-3.0-apidocs/index.html">Portlet 3.0 API</a> + | + <a href="../portlet-2.0-apidocs/index.html">Portlet 2.0 API</a> + | + <a href="../portlet-1.0-apidocs/index.html">Portlet 1.0 API</a> + | + <a href="http://jcp.org/en/jsr/detail?id=362"; class="externalLink">JSR 362 JCP Page</a> + | + <a href="http://jcp.org/en/jsr/detail?id=286"; class="externalLink">JSR 286 JCP Page</a> + | + <a href="http://jcp.org/en/jsr/detail?id=168"; class="externalLink">JSR 168 JCP Page</a> + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>The Pluto Project</h5> + <ul> + + <li class="none"> + <a href="../index.html">About Pluto</a> + </li> + + <li class="none"> + <a href="../mission.html">Mission</a> + </li> + + <li class="none"> + <a href="../download.html">Download</a> + </li> + + <li class="none"> + <a href="../news.html">News</a> + </li> + + <li class="none"> + <a href="../status.html">Status</a> + </li> + + <li class="none"> + <a href="../architecture.html">Architecture</a> + </li> + + <li class="none"> + <a href="../resources.html">Resources</a> + </li> + + <li class="none"> + <a href="../faq.html">FAQ</a> + </li> + + <li class="none"> + <a href="http://wiki.apache.org/portals/Pluto"; class="externalLink">Wiki</a> + </li> + + <li class="none"> + <a href="https://issues.apache.org/jira/browse/PLUTO"; class="externalLink">Issue Tracker (JIRA)</a> + </li> + + <li class="none"> + <a href="../helping.html">Get Involved</a> + </li> + </ul> + <h5>Pluto 3.0</h5> + <ul> + + <li class="none"> + <a href="../v30/getting-started.html">Getting Started</a> + </li> + + <li class="none"> + <a href="../v30/deploying.html">Deploying Portlets</a> + </li> + + <li class="none"> + <a href="../v30/portlet-api.html">Portlet Concepts</a> + </li> + + <li class="none"> + <strong>Version 3 Features</strong> + </li> + + <li class="none"> + <a href="../v30/tck.html">Using the TCK</a> + </li> + + <li class="none"> + <a href="../v30/release-notes.html">Release Notes</a> + </li> + </ul> + <h5>Pluto 2.0</h5> + <ul> + + <li class="none"> + <a href="../v20/getting-started.html">Getting Started</a> + </li> + + <li class="none"> + <a href="../v20/deploying.html">Deploying</a> + </li> + + <li class="none"> + <a href="../v20/embedding.html">Embedding</a> + </li> + + <li class="none"> + <a href="../v20/release-notes.html">Release Notes</a> + </li> + + <li class="none"> + <a href="../v20/app-servers.html">App Servers</a> + </li> + + <li class="none"> + <a href="../v20/powered.html">Powered By Pluto</a> + </li> + </ul> + <h5>Pluto 1.1</h5> + <ul> + + <li class="none"> + <a href="../v11/getting-started.html">Getting Started</a> + </li> + + <li class="none"> + <a href="../v11/deploying.html">Deploying</a> + </li> + + <li class="none"> + <a href="../v11/release-notes.html">Release Notes</a> + </li> + </ul> + <h5>Subprojects</h5> + <ul> + + <li class="none"> + <a href="../subprojects/subprojects.html">Overview</a> + </li> + </ul> + <h5>Project Info</h5> + <ul> + + <li class="none"> + <a href="../project-summary.html">Project Summary</a> + </li> + + <li class="none"> + <a href="../team-list.html">Project Team</a> + </li> + + <li class="none"> + <a href="../license.html">Project License</a> + </li> + + <li class="none"> + <a href="../mail-lists.html">Mailing Lists</a> + </li> + + <li class="none"> + <a href="../source-repository.html">Source Repository</a> + </li> + + <li class="none"> + <a href="../issue-tracking.html">Issue Tracking</a> + </li> + </ul> + <a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="Portlet_API_version_3.0_Overview"></a>Portlet API version 3.0 Overview</h2> +<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 class="externalLink" 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 class="externalLink" 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> +<div class="section"><h3><a name="Configuration_by_Annotation"></a>Configuration by Annotation</h3> +<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></div> +<div class="section"><h3><a name="Extended_Method_Annotations"></a>Extended Method Annotations</h3> +<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></div> +<div class="section"><h3><a name="CDI_Support"></a>CDI Support</h3> +<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> +</div> +<div class="section"><h3><a name="Asynchronous_support"></a>Asynchronous support</h3> +<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" /></div> +<div class="section"><h3><a name="The_Portlet_Hub_JavaScript_API"></a>The Portlet Hub JavaScript API</h3> +<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></div> +</div> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2004-2016 + + Apache Software Foundation + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
![http://portals.apache.org/pluto/images/apache-portals.gif"](http://portals.apache.org/pluto/images/apache-portals.gif"){kind=link}
![http://portals.apache.org/pluto/images/banner.png"](http://portals.apache.org/pluto/images/banner.png"){kind=link}
