Author: chris.laprun(a)jboss.com
Date: 2007-07-31 10:16:32 -0400 (Tue, 31 Jul 2007)
New Revision: 7849
Modified:
docs/trunk/referenceGuide/en/modules/tutorials.xml
docs/trunk/referenceGuide/en/modules/wsrp.xml
Log:
- Started fixing tutorials problems.
- Improved content.
Modified: docs/trunk/referenceGuide/en/modules/tutorials.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/tutorials.xml 2007-07-31 14:07:17 UTC (rev 7848)
+++ docs/trunk/referenceGuide/en/modules/tutorials.xml 2007-07-31 14:16:32 UTC (rev 7849)
@@ -139,23 +139,32 @@
<listitem>
<para>
<programlisting>public class HelloWorldPortlet extends
GenericPortlet</programlisting>
- All Portlets MUST implement the javax.portlet.GenericPortlet
Interface.
+ All Portlets MUST implement the
<literal>javax.portlet.Portlet</literal> interface. The Portlet
+ API also provides a convenience implementation of this interface
in the form of the
+ <literal>javax.portlet.GenericPortlet</literal> class
which, among other things, implements
+ the <literal>Portlet render</literal> method to
dispatch to abstract mode-specific methods to
+ make it easier to support the standard portlet modes. It also
provides
+ a default implementation for
<literal>processAction</literal>, <literal>init</literal> and
+ <literal>destory</literal> methods. It is recommended
to extend <literal>GenericPortlet</literal>
+ for most cases.
</para>
</listitem>
<listitem>
<para>
<programlisting>protected void doView(RenderRequest
rRequest, RenderResponse rResponse) throws
PortletException, IOException,
UnavailableException</programlisting>
- In this case, our
- <emphasis>doView</emphasis>
- will be called when the portlet is asked to render output in VIEW
Mode.
+ As we extend from <literal>GenericPortlet</literal>
and we are only interested in supported the
+ <emphasis>VIEW</emphasis> mode, we only need to
implement the <literal>doView</literal> method,
+ and <literal>GenericPortlet</literal>'s
<literal>render</literal> implementation will call our
+ implementation when the <emphasis>VIEW</emphasis>
mode is requested.
</para>
</listitem>
<listitem>
<para>
<programlisting>rResponse.setContentType("text/html");</programlisting>
Just like in the servlet-world, you must declare what
content-type the portlet will be
- responding in.
+ responding in. You need to do this before starting to write
content or the portlet will throw
+ an exception.
</para>
</listitem>
<listitem>
@@ -169,7 +178,8 @@
in our portlet window.
<note>
Portlets are responsible for generating markup fragments, as
they are included on a page and
- surrounded by other portlets.
+ surrounded by other portlets. In particular, this means that a
portlet outputting HTML MUST
+ not output any markup that cannot be found in a
<literal>body</literal> element.
</note>
</para>
</listitem>
@@ -230,15 +240,17 @@
<mime-type>text/html</mime-type>
<portlet-mode>VIEW</portlet-mode>
</supports>]]></programlisting>
- The supports attributes allow you to declare extra vital
information about the portlet.
- In this case, we are letting the portal know that it
will be outputting text/html and
+ The <literal>supports</literal> element
allows you to declare all the markup types your
+ portlet supports in the
<literal>render</literal> method. This is accomplish via the
+ <literal>mime-type</literal> element, which
is <emphasis>required</emphasis> for every
+ portlet. Of course, the declared MIME types must match
the capability of the portlet.
+
+ It also allows you to pair
+ which modes and window states are supported for each
markup type. In out case, as all
+ portlets must support the VIEW portlet mode, we
didn't have to declare it. We did need
+ to declare that our portlet supports the
<literal>text/html</literal> markup type.
+ Hence, we are letting the portal know that it will be
outputting text/html and
only support a VIEW mode.
- <note>
- A content-type must be declared here for every
portlet, and it must match with how
- the portlet is programmatically responding. Likewise,
a portlet mode must be
- declared here and have a corresponding method in its
class. In our case, the VIEW
- mode will map to the doView() in our class.
- </note>
</para>
</listitem>
<listitem>
@@ -269,18 +281,10 @@
</deployment>
</deployments>]]></programlisting>
This is a JBoss Portal specific descriptor that allows you create
an instance of a portlet. The
- <emphasis>portlet-ref</emphasis>
- value must match the
- <emphasis>portlet-name</emphasis>
- value given in the packaged
- <emphasis>portlet.xml</emphasis>
- . The
- <emphasis>instance-id</emphasis>
- value can be named anything, but it must match the
- <emphasis>instance-ref</emphasis>
- value given in the
- <emphasis>*-object.xml</emphasis>
- file we will explore below.
+ <literal>portlet-ref</literal> value must match the
<literal>portlet-name</literal> value
+ given in the packaged <literal>portlet.xml</literal>.
The <literal>instance-id</literal>
+ value can be named anything, but it must match the
<literal>instance-ref</literal> value given
+ in the <literal>*-object.xml</literal> file we will
explore below.
</para>
</listitem>
<listitem>
@@ -302,27 +306,12 @@
</deployment>
</deployments>]]></programlisting>
- The *-object.xml is responsible for creating/configuring windows,
pages, and even portal
- objects. In our example, we are creating a portlet window,
assigning it to a page, and
- specifying where it should appear on that page. This is a
specific descriptor to JBoss Portal.
- Since 2.6 we can replace also the window section by the following
which will do exactly the same.
-
- <programlisting><![CDATA[<window>
- <window-name>HelloWorldPortletWindow</window-name>
- <content>
- <content-type>portlet</content-type>
- <content-uri>HelloWorldPortletInstance</content-uri>
- </content>
- <region>center</region>
- <height>1</height>
-</window>
-]]></programlisting>
- The kind of declaration allows to declare for a window different
kind of content types. You can see
- that as a generic way to declare content for a window. In our
case the type of content is portlet
- and the content uri declares the HelloWorldPortletInstance. The
content uri value is the identifier of
- the content. It is possible to declare windows with content type
cms and use directly the path
- to the file in the CMS to make the window show cms content. That
behavior is pluggable and it
- is virtually possible to plug in any kind of content.
+ <literal>*-object.xml</literal> files are JBoss
Portal specific descriptors and allow users to
+ define the structure of their portal instances as well as
create/configure thier windows and
+ pages. In our example, we create a portlet window, specify that
it will display the markup
+ generated by the
<literal>HelloWorldPortletInstance</literal> portlet instance, assign it to
the
+ <literal>default.default</literal> page, and specify
where it should appear on that page.
+
<itemizedlist>
<listitem>
<para>
@@ -394,6 +383,38 @@
</imageobject>
</mediaobject>
</para>
+
+ <para>
+ Portal 2.6 introduces the notion of <emphasis>content
type</emphasis>, which is a generic mechanism to
+ specify which content will be displayed by a given portlet window. The
<literal>window</literal> section
+ of the previous example can be re-written as follows to take advantage of
the new content framework:
+ <programlisting><![CDATA[<?xml version="1.0"
encoding="UTF-8"?>
+<!DOCTYPE deployments PUBLIC
+ "-//JBoss Portal//DTD Portal Object 2.6//EN"
+ "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
+<deployments>
+ <deployment>
+ <parent-ref>default.default</parent-ref>
+ <if-exists>overwrite</if-exists>
+ <window>
+ <window-name>HelloWorldPortletWindow</window-name>
+ <content>
+ <content-type>portlet</content-type>
+ <content-uri>HelloWorldPortletInstance</content-uri>
+ </content>
+ <region>center</region>
+ <height>1</height>
+ </window>
+ </deployment>
+</deployments>]]></programlisting>
+
+ This declaration is equivalent to the previous example. We specify that
the content being displayed by
+ the <literal>HelloWorldPortletWindow</literal> is a
<literal>portlet</literal> content. The content URI
+ identifies which content to be displayed, in this case, the
<literal>HelloWorldPortletInstance</literal>.
+ It is possible to declare windows with a
<literal>cms</literal> content type and use directly the path to
+ the file in the CMS to make the window show the content of the associated
file. That behavior is
+ pluggable and it is possible to plug virtually any kind of content.
+ </para>
</sect3>
<sect3>
<title>Building your portlet</title>
Modified: docs/trunk/referenceGuide/en/modules/wsrp.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/wsrp.xml 2007-07-31 14:07:17 UTC (rev 7848)
+++ docs/trunk/referenceGuide/en/modules/wsrp.xml 2007-07-31 14:16:32 UTC (rev 7849)
@@ -53,26 +53,27 @@
HTML markup (as Portal itself doesn't handle other markup types). We do
support explicit portlet cloning and
we fully support the PortletManagement interface.</para>
- <para>As far as caching goes, we have Level 1 Producer and Consumer. We
support Cookie handling properly on the
- Consumer and our Producer requires initialization of cookies (as we have found
that it improved
- interoperabilty with some consumers). We don't support custom window states
or modes, as Portal doesn't either.
- We do, however, support CSS on both the Producer (though it's more a
function of the portlets than
- inherent Producer capability) and Consumer.</para>
+ <para>As far as caching goes, we have Level 1 Producer and Consumer. We
support Cookie handling properly on the
+ Consumer and our Producer requires initialization of cookies (as we have found
that it improved interoperabilty
+ with some consumers). We don't support custom window states or modes, as
Portal doesn't either. We do, however,
+ support CSS on both the Producer (though it's more a function of the
portlets than inherent Producer
+ capability) and Consumer.</para>
- <para>While we provide a complete implementation of WSRP 1.0, we do need
to go through the
- <ulink
url="http://www.oasis-open.org/committees/download.php/6018">...
statements</ulink> and
- perform more interoperability testing (an area that needs to be better
supported by the WSRP Technical
- Committee and Community at large).</para>
+ <para>While we provide a complete implementation of WSRP 1.0, we do need to
go through the
+ <ulink
url="http://www.oasis-open.org/committees/download.php/6018">...
statements</ulink> and
+ perform more interoperability testing (an area that needs to be better supported
by the WSRP Technical
+ Committee and Community at large).</para>
</sect1>
<sect1>
<title>Deploying JBoss Portal's WSRP services</title>
- <para>JBoss Portal provides a complete support of WSRP 1.0 standard
interfaces and offers
- both consumer and producer services. WSRP support is provided by the
<emphasis>portal-wsrp.sar</emphasis>
- service archive, included in the main
<emphasis>jboss-portal.sar</emphasis> service archive, if
- you've obtained JBoss Portal from a binary distribution. If you don't intend on
using WSRP, we
- recommend that you remove the <emphasis>portal-wspr.sar</emphasis> from the
main
- <emphasis>jboss-portal.sar</emphasis> service archive.</para>
+ <para>
+ JBoss Portal provides a complete support of WSRP 1.0 standard interfaces and
offers
+ both consumer and producer services. WSRP support is provided by the
<emphasis>portal-wsrp.sar</emphasis>
+ service archive, included in the main
<emphasis>jboss-portal.sar</emphasis> service archive, if you've
+ obtained JBoss Portal from a binary distribution. If you don't intend on
using WSRP, we recommend that you
+ remove the <emphasis>portal-wspr.sar</emphasis> from the main
<emphasis>jboss-portal.sar</emphasis> service
+ archive.</para>
<para>If you've obtained the source distribution of JBoss Portal, you
need to build and deploy the WSRP service
separately. Please follow the instructions on how to install
<ulink
url="http://docs.jboss.com/jbportal/v2.6/reference-guide/en/html/ins...
Portal
@@ -186,7 +187,7 @@
refer to <xref linkend="consumer_configuration"/>.
</para>
<para>
- JBoss Portal's Producer is automatically set up when you deploy a portal
instance with the WSRP service.
+ JBoss Portal's Producer is automatically set up when you deploy a portal
instance with the WSRP service.
You can access the WSDL file at
<literal>http://{hostname}:{port}/portal-wsrp/MarkupService?wsdl</literal>.
You can access the endpoint URLs at:
<itemizedlist>
@@ -491,7 +492,7 @@
<deployment>
<wsrp-producer id="self" expiration-cache="300">
<!--
- we need to use the individual endpoint configuration because the configuration
via
+ we need to use the individual endpoint configuration because the configuration
via
wsdl forces an immediate attempt to access the web service description which is
not
available yet at this point of deployment
-->
@@ -582,7 +583,7 @@
<title>Default configuration</title>
<para>
Let's look at the default configuration:
- <programlisting><![CDATA[<!DOCTYPE producer-configuration PUBLIC
+ <programlisting><![CDATA[<!DOCTYPE producer-configuration PUBLIC
"-//JBoss Portal//DTD WSRP Local Producer Configuration 2.6//EN"
"http://www.jboss.org/portal/dtd/jboss-wsrp-producer_2_6.dtd">
<?xml version="1.0" encoding="UTF-8"?>
@@ -648,7 +649,7 @@
</para>
<para>Please refer to the Javadoc for
<literal>org.jboss.portal.registration.RegistrationPolicy</literal>
and
<literal>org.jboss.portal.Registration.policies.RegistrationPropertyValidator</literal>
for more details
- on what is expected of each method.
+ on what is expected of each method.
</para>
<para>Defining a registration policy is required for the producer to be
correctly configured. This is accomplished
by specifying the qualified class name of the registration policy via the
@@ -688,11 +689,11 @@
complete service description until they are correctly registered and requires
consumers to provide acceptable
values for two String registration properties named "name1" and
"name2" respectively. The registration
service will use the
<literal>com.example.portal.SomeCustomRegistrationPolicy</literal> class for
its
- registration policy.
+ registration policy.
<programlisting><![CDATA[<!DOCTYPE producer-configuration PUBLIC
"-//JBoss Portal//DTD WSRP Local Producer Configuration 2.6//EN"
"http://www.jboss.org/portal/dtd/jboss-wsrp-producer_2_6.dtd">
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
<producer-configuration>
<registration-configuration
fullServiceDescriptionRequiresRegistration="true">
<registration-policy>com.example.portal.SomeCustomRegistrationPolicy</registration-policy>