Specification goals
------------------
This specification defines a standard development and deployment
environment for java server components, called "portlets".
Those portlets will be run by a specification compliant server
container called a "portal".
A portal typically aggregates several portlets output for building
its response to a user request.
A portlet developped according to these specifications will be
deployable on any compliant portal.
Deliverables
------------
This specification has 3 deliverables :
- a java API
- a portlet deployment specification
- a set of markup specific specifications for portlet writers
Java API
--------
The java is the same that the one currently found in the
/proposals/portletAPI/api in the Jetspeed CVS repository with
the following exception:
public interface PortletResponse
{
// These 2 methods allow the the portlet to output
// its markup to the portal as a SAX/JAXP event stream
public ContentHandler getContentHandler();
public LexicalHandler getLexicalHandler();
/* These methods are the same as the one proposed in CVS
*/
public PortletURI createURI(Portlet.Mode mode);
public String encodeURI(String path);
public void addActionListener(ActionListener listener);
}
Additionnally a sub-package is created (org.apache.portlet.stream)
that defines the following interfaces
public interface StreamPortlet extends Portlet
{
public void service( StreamPortletRequest req, StreamPortletResponse rsp );
}
public interface StreamPortletRequest extends PortletRequest
{
//unspecified currently
}
public interface StreamPortletResponse extends PortletResponse
{
public PrintWriter getWriter() throws IOException;
}
Deployment specification
------------------------
A compliant portlet package must be deployed on a portal with a portlet
descriptor file.
This descriptor file will at least specify:
- the portlet class name
- the portlet default operational parameters
- the customizer class name, if any
- the supported markups and content models
Such a descriptor file may be:
<portlet version="1.0">
<!-- the portlet name which will be mapped to the classname -->
<name>MyPortlet</name>
<!-- the portlet classname -->
<classname>org.apache.portlets.SamplePortlet</classname>
<!-- the portlet is its own customizer -->
<!-- if customizer is not specified, the portal will use its default
built-in customizer interface -->
<customizer>org.apache.portlets.SamplePortlet</customizer>
<markup-support>
<!-- this element defines what are the supported output format
produced by this portlet and what content model do they
adhere to for this markup.
The content models are normalized and defined in the current
specification. -->
<markup uri="http://www.w3c.org/2000/XHTML" model="table-fragment" />
<!-- if no model is specified, the portal must assume that the portlet
will output complete, well-formed valid documents -->
<markup uri="http://www.wap.org/WML1.1"/>
</markup-support>
<!-- override means that a user may use a personalized setting for
this parameter -->
<parameter override="yes">
<param-name>myValue</param-name>
<param-value>1</param-value>
<param-description xml:lang="en">This description is useful if
the default portal customizer is used</param-description>
</parameter>
<parameter override="no">
<param-name>myValue1</param-name>
<param-value>3</param-value>
</parameter>
</portlet>
(this is not yet finalized)
If a portal does support the markup uri defined for a portlet but
does not support the associated content model, it will not register
this portlet as available for this markup.
Content models
--------------
The default content model constraint for all markups is that portlet
must output a well-formed, valid document for the specified markup.
The specification also defines the specific content model for the
following markups:
XHTML
* table-fragment:
The portlet output is contained inside a relative width <table> element.
No inside element specifies absolute width.
(Other Oracle-like guidelines)
XSL:FO
* block-fragment
Output is within a block
WML
* multi-card-fragment
Output is a collection of one or more cards. The output may not contain
template elements and the card ids are prefixed by the portlet name.
...
* card-element-fragment
Output is suitable for inclusion within a card element but does not
contain the card element itself.
Portal implementations are recommended to implement and support most of
these models.
[Design notes/Comments:
* The default output mode for the portlet API (SAX/well formed, valid
documents) is the most restrictive. This place an important burden
on the portal implementors (who must support this mode) but it
guarantees content model portability and enforce well-formedness at the
API level. Portlets written against this model will be the most portable
but may suffer performance hits on some implementations.
* The stream sub-interface is useful for supporting existing stream-based
development tools like JSPs. Portal implementations may chose to handle
directly the byte streams and bypass completely the SAX processing by
providing a StreamPortletResponse implementation that does not parse
the portlet stream but outputs it directly to the main response stream.
This is only useful when used in conjonction with a specific content
model like XHTML-table-fragment since the default mode always requires
output filtering.
Using these sub-interfaces and specific content models, a portlet writer
can achieve maximum performance on stream-based portal systems.
* This proposed API is XML friendly, designed for efficiently allowing
intelligent portal post-processing; Such as API and default content
model makes the portal implementation completely responsible for the
robustness and validity of the generated aggregated response. This
impose a fixed high-level functionality in all compliant portals and
thus creates additionnal implementation difficulties.
* If the SAX/stream API is reversed, ie the base PortletResponse has
a getWriter() method and a org.apache.portlet.sax.SAXPortletResponse
define the SAX specific handlers, the general properties of the API
will be reversed:
- portlets using the base API will have to use specific content
models in order to be efficiently used (post-processing of a
char stream is more costly than post-processing of a SAX stream)
which means that they'll only be supported on the subset of
implementing portals that handle the specified content model.
- portlets using the sub-API will be portable on all portals
implementing this sub-API.
The conclusion of these statements is that there won't be a definite
markup independant API/content model configuration that will
guarantee portability across all implementing portals.
Such portability may be achieved if support for some specific content
models is mandatory (the most likely example being XHTML/table-fragment).
]
--
Raphaël Luta - [EMAIL PROTECTED]
Vivendi Universal Networks - Services Manager / Paris
--
--------------------------------------------------------------
To subscribe: [EMAIL PROTECTED]
To unsubscribe: [EMAIL PROTECTED]
Search: <http://www.mail-archive.com/[email protected]/>
List Help?: [EMAIL PROTECTED]
