Author: thomas.heute(a)jboss.com
Date: 2007-08-29 04:41:42 -0400 (Wed, 29 Aug 2007)
New Revision: 8091
Added:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/package_42x.png
Removed:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/buildexplode.gif
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/building.gif
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsp_portlet/buildexplode.gif
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsp_portlet/building.gif
Modified:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml
docs/trunk/referenceGuide/en/master.xml
docs/trunk/referenceGuide/en/modules/installation.xml
docs/trunk/referenceGuide/en/modules/migration.xml
docs/trunk/referenceGuide/en/modules/portalapi.xml
Log:
Merge docs in trunk and 2_6 branch
Deleted:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/buildexplode.gif
===================================================================
(Binary files differ)
Deleted:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/building.gif
===================================================================
(Binary files differ)
Added:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/package_42x.png
===================================================================
(Binary files differ)
Property changes on:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsf_portlet/package_42x.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Deleted:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsp_portlet/buildexplode.gif
===================================================================
(Binary files differ)
Deleted:
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/images/tutorials/jsp_portlet/building.gif
===================================================================
(Binary files differ)
Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml 2007-08-28 23:44:23
UTC (rev 8090)
+++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml 2007-08-29 08:41:42
UTC (rev 8091)
@@ -32,10 +32,10 @@
]>
<book lang="en">
<bookinfo>
- <title>JBoss Portal 2.6.1-CR1</title>
+ <title>JBoss Portal 2.6.2</title>
<subtitle>Reference Guide</subtitle>
- <releaseinfo>Release 2.6.1-CR1 "Ninja"</releaseinfo>
- <releaseinfo>June 2007</releaseinfo>
+ <releaseinfo>Release 2.6.2 "Ninja"</releaseinfo>
+ <releaseinfo>October 2007</releaseinfo>
<author>
<firstname>Thomas</firstname>
<surname>Heute</surname>
Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml 2007-08-28
23:44:23 UTC (rev 8090)
+++
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/tutorials.xml 2007-08-29
08:41:42 UTC (rev 8091)
@@ -5,6 +5,11 @@
<surname>Russo</surname>
<email>roy(a)jboss.org</email>
</author>
+ <author>
+ <firstname>Chris</firstname>
+ <surname>Laprun</surname>
+ <email>chris.laprun(a)jboss.com</email>
+ </author>
</chapterinfo>
<title>Portlet Primer</title>
<sect1 id="portlet_primer">
@@ -68,11 +73,9 @@
<para>
The tutorials contained in this chapter are targetted toward portlet developers.
Although they are a good
starting and reference point, we do heavily recommend that portlet developers
read and understand the
- <ulink
url="http://www.jcp.org/en/jsr/detail?id=168">Portlet
- Specification (JSR-168)</ulink>
- . We also recommend, using our
- <ulink
url="http://jboss.org/index.html?module=bb&op=viewforum&...
Portal User Forums</ulink>
- for user-to-user help, when needed.
+ <ulink
url="http://www.jcp.org/en/jsr/detail?id=168">Portlet
Specification (JSR-168)</ulink>. We also recommend
+ using our <ulink
url="http://jboss.org/index.html?module=bb&op=viewforum&...
Portal User
+ Forums</ulink> for user-to-user help, when needed.
</para>
<sect2>
<title>Deploying your first portlet</title>
@@ -81,18 +84,15 @@
<para>This section will introduce the reader to deploying his first
portlet in JBoss Portal. It requires you
download the HelloWorldPortlet from
PortletSwap.com, using this
<ulink
-
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
- link</ulink>
- .
+
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...;.
</para>
</sect3>
<sect3>
<title>Package Structure</title>
<para>
- Portlets are packaged in war files, just like other JEE applications. A
typical portlet war file can also
- include servlets, resource bundles, images, html, jsps, and other static
or dynamic files you would
- commonly
- include.
+ Portlets are packaged in WAR files, just like other JEE applications. A
typical portlet WAR file can also
+ include servlets, resource bundles, images, HTML, JSPs, and other static
or dynamic files you would
+ commonly include.
</para>
<para>
<mediaobject>
@@ -103,15 +103,13 @@
</para>
</sect3>
<sect3>
- <title>The Portlet Class</title>
+ <title>Portlet Class</title>
<para>
Included in the
- <ulink
-
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
- download bundle</ulink>
- you should have one java source file:
-
<emphasis>HelloWorldPortlet\src\main\org\jboss\portlet\hello\HelloWorldPortlet.java</emphasis>
- , and it should contain the following:
+ <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
+ download bundle</ulink> you should have one java source file:
+
<literal>HelloWorldPortlet\src\main\org\jboss\portlet\hello\HelloWorldPortlet.java</literal>,
and it
+ should contain the following:
<programlisting><![CDATA[package org.jboss.portlet.hello;
import javax.portlet.GenericPortlet;
@@ -134,28 +132,37 @@
}
}]]>
</programlisting>
- Now lets dissect our simplest of portlets:
+ Now let's dissect our simplest of portlets:
<itemizedlist>
<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
+ <literal>VIEW</literal> 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 <literal>VIEW</literal> 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>
@@ -165,11 +172,12 @@
writer.write("Hello World!");
writer.close();]]></programlisting>
Here we output the text
- <emphasis>Hello World!</emphasis>
+ <literal>Hello World!</literal>
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>
@@ -177,21 +185,20 @@
</para>
</sect3>
<sect3 id="first_portlet_descriptors">
- <title>The Application Descriptors</title>
+ <title>Application Descriptors</title>
<para>
- JBoss Portal requires certain descriptors be included in your portlet war,
for different reasons. Some of
- these descriptors are defined by the Portlet Specification, and some are
specific to JBoss Portal.
+ JBoss Portal requires certain descriptors be included in your portlet WAR,
for different reasons. Some of
+ these descriptors are defined by the Portlet Specification, some are
specific to JBoss Portal.
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/first_portlet/package.gif"
valign="middle"/>
</imageobject>
</mediaobject>
- Now lets explain what each of these does:
+ Now let's explain what each of these does:
<itemizedlist>
<listitem>
- <para>
- portlet.xml
- <programlisting><![CDATA[<?xml
version="1.0" encoding="UTF-8"?>
+ <para><literal>portlet.xml</literal>
+<programlisting><![CDATA[<?xml version="1.0"
encoding="UTF-8"?>
<portlet-app
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1...
@@ -221,7 +228,7 @@
<listitem>
<para>
<programlisting><![CDATA[<portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class>]]></programlisting>
- The FQN of your portlet class must be declared here.
+ The Fully Qualified Name (FQN) of your portlet class
must be declared here.
</para>
</listitem>
<listitem>
@@ -230,15 +237,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>
@@ -255,8 +264,8 @@
</para>
</listitem>
<listitem>
- <para>portlet-instances.xml
- <programlisting><![CDATA[<?xml
version="1.0" standalone="yes"?>
+ <para><literal>portlet-instances.xml</literal>
+<programlisting><![CDATA[<?xml version="1.0"
standalone="yes"?>
<!DOCTYPE deployments PUBLIC
"-//JBoss Portal//DTD Portlet Instances 2.6//EN"
"http://www.jboss.org/portal/dtd/portlet-instances_2_6.dtd">
@@ -269,23 +278,15 @@
</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>
- <para>helloworld-object.xml
- <programlisting><![CDATA[<?xml
version="1.0" encoding="UTF-8"?>
+ <para><literal>helloworld-object.xml</literal>
+<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">
@@ -302,56 +303,30 @@
</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>
<programlisting><![CDATA[<parent-ref>default.default</parent-ref>]]></programlisting>
Tells the portal where this portlet should appear. In
this case,
- <emphasis>default.default</emphasis>
- specifies that this portlet should appear in the portal
instance named
- <emphasis>default</emphasis>
- and the
- page named
- <emphasis>default</emphasis>
- .
+ <literal>default.default</literal> specifies
that this portlet should appear in the
+ portal instance named
<literal>default</literal> and the page named
+ <literal>default</literal>.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<if-exists>overwrite</if-exists>]]></programlisting>
Instructs the portal to overwrite or keep this object if
it already exists.
- Possible values are
- <emphasis>overwrite</emphasis>
- or
- <emphasis>keep</emphasis>
- .
- <emphasis>Overwrite</emphasis>
- will destroy the existing object and create a new one
- based on the content of the deployment.
- <emphasis>Keep</emphasis>
- will maintain the
- existing objct deployment or create a new one if it does
not yet exist.
+ Possible values are
<literal>overwrite</literal> or <literal>keep</literal>.
+ <literal>overwrite</literal> will destroy
the existing object and create a new one
+ based on the content of the deployment.
<literal>keep</literal> will maintain the
+ existing object deployment or create a new one if it
does not yet exist.
</para>
</listitem>
<listitem>
@@ -363,13 +338,8 @@
<listitem>
<para>
<programlisting><![CDATA[<instance-ref>HelloWorldPortletInstance</instance-ref>]]></programlisting>
- The value of
- <emphasis>instance-ref</emphasis>
- must match the value of
- <emphasis>instance-id</emphasis>
- found in the
- <emphasis>portlet-instances.xml</emphasis>
- .
+ The value of <literal>instance-ref</literal>
must match the value of
+ <literal>instance-id</literal> found in the
<literal>portlet-instances.xml</literal>.
</para>
</listitem>
<listitem>
@@ -385,8 +355,7 @@
</itemizedlist>
</para>
<para>
- To illustrate the relationship between the descriptors
- , we have provided this simple diagram
+ To illustrate the relationship between the descriptors, we have provided
this simple diagram
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/first_portlet/desc_relationship.gif"
@@ -394,16 +363,46 @@
</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 to take advantage of the new
content framework, resulting in
+ the following deployment descriptor:
+ <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>
+ <sect3 id="first_portlet_build">
<title>Building your portlet</title>
- <para>If you have downloaded the sample, you can execute the build.xml
with ANT or inside your IDE.
- Executing the
- <emphasis>deploy</emphasis>
- target
- will compile all src files and produce a helloworldportlet.war under
- <emphasis>HelloWorldPortlet\helloworldportlet.war.</emphasis>
-
+ <para>If you have downloaded the sample, you can execute the build.xml
with ant or inside your IDE.
+ Executing the <literal>deploy</literal> target will compile
all the source files and produce a
+ <literal>helloworldportlet.war</literal> file under
+ <literal>HelloWorldPortlet\helloworldportlet.war.</literal>
</para>
<para>
<mediaobject>
@@ -413,10 +412,8 @@
</mediaobject>
</para>
<para>
- If you want to create an expanded war directory, after executing the above
deploy target, you should
- execute the
- <emphasis>explode</emphasis>
- target.
+ If you want to create an expanded WAR directory, after executing the above
deploy target, you should
+ execute the <literal>explode</literal> target.
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/first_portlet/buildexplode.gif"
@@ -431,33 +428,25 @@
<imagedata align="center"
fileref="images/tutorials/first_portlet/exploded.gif"
valign="middle"/>
</imageobject>
</mediaobject>
- This will deflate the helloworldportlet.war, and allow you to deploy it as
an expanded directory. It will
- work just the same, with some additional benefits noted below:
- </para>
- <para>
- The advantage to expanded war deployments is that you can modify xml
descriptors, resource files
- jsp/jsf pages easily during development. Simply
- <emphasis>touch</emphasis>
- the web.xml to have JBoss Application Server hot-deploy the web
appllication on a live-running server
- instance
- </para>
+ This will deflate <literal>helloworldportlet.war</literal>,
and allow you to deploy it as an
+ expanded directory. It will work just the same but is easier to work with
during development as you can
+ easily modify the XML descriptors, resources files, JSF/JSP pages. A
simple <literal>touch</literal>
+ operation (or equivalent) on the <literal>web.xml</literal>
file will let any live JBoss Application
+ Server instance know that it needs to hot-redeploy your web application.
+ </para>
</sect3>
<sect3>
<title>Deploying your portlet</title>
<para>
- Deploying a portlet is as simple as copying/moving the
- <emphasis>helloworldportlet.war</emphasis>
- in to the server deploy directory. Doing this on a running instance of the
portal and application server,
- will trigger a
- <emphasis>hot-deploy</emphasis>
- :
+ Deploying a portlet is as simple as copying/moving
<literal>helloworldportlet.war</literal>
+ to your server <literal>deploy</literal> directory. Doing this
on a running instance of JBoss Portal and
+ application server, will trigger a
<emphasis>hot-deploy</emphasis> of your portlet:
<programlisting><![CDATA[18:25:56,366 INFO [Server] JBoss (MX
MicroKernel) [4.0.5.GA (build:
CVSTag=JBoss_4_0_5_GA date=2006000000)] Started in 1m:3s:688ms
18:26:21,147 INFO [TomcatDeployer] deploy, ctxPath=/helloworldportlet,
warUrl=.../tmp/deploy/tmp35219helloworldportlet-exp.war/]]></programlisting>
- Pointing your browser to
- <ulink
url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink>
- , should yield a view of our HelloWorldPortlet:
+ Pointing your browser to <ulink
url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink>,
+ should yield a view of our HelloWorldPortlet, added to the default page of
Portal:
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/first_portlet/output.png"
valign="middle"/>
@@ -471,12 +460,9 @@
<sect3>
<title>Introduction</title>
<para>This section will introduce the reader to deploying a simple JSP
portlet in JBoss Portal. It requires
- you
- download the HelloWorldJSPPortlet from
PortletSwap.com, using this
- <ulink
-
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
- link</ulink>
- .
+ you download the HelloWorldJSPPortlet from
PortletSwap.com, using this
+ <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
+ link</ulink>.
</para>
<para>
This portlet will introduce you to using JSPs for view rendering and the
portlet taglib for generating
@@ -484,31 +470,28 @@
</para>
</sect3>
<sect3>
- <title>Package Structure</title>
+ <title>Package content</title>
<para>
- Portlets are packaged in war files, just like other JEE applications. A
typical portlet war file can also
- include servlets, resource bundles, images, html, jsps, and other static
or dynamic files you would
- commonly
- include.
- </para>
- <para>
+ The application descriptors for this portlet are similar to the ones we
saw in
+ <xref linkend="first_portlet_descriptors"/>. See the
<xref linkend="descriptors_portlet"/> chapter on
+ descriptors for more details.
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/jsp_portlet/package.gif"
valign="middle"/>
</imageobject>
</mediaobject>
+ As you can see in the figure above, the package content is what you'd
expect from a traditional web
+ application augmented with the portlet- and JBoss Portal-specific
application descriptors.
</para>
</sect3>
<sect3>
- <title>The Portlet Class</title>
+ <title>Portlet Class</title>
<para>
- Included in the
- <ulink
-
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
- download bundle</ulink>
- you should have one java source file:
-
<emphasis>HelloWorldPortlet\src\main\org\jboss\portlet\hello\HelloWorldJSPPortlet.java</emphasis>
- , and it should contain the following:
+ Included in the <ulink
+
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
+ download bundle</ulink> you should have one java source file:
+
<literal>HelloWorldJSPPortlet\src\main\org\jboss\portlet\hello\HelloWorldJSPPortlet.java</literal>,
+ containing the following:
<programlisting><![CDATA[package org.jboss.portlet.hello;
import javax.portlet.ActionRequest;
@@ -573,7 +556,7 @@
prd.include(rRequest, rResponse);
}
}]]></programlisting>
- Now lets look at some of our methods:
+ Now let's look at some of our methods:
<itemizedlist>
<listitem>
<para>
@@ -598,16 +581,17 @@
aResponse.setRenderParameter("yourname", sYourname);
}]]></programlisting>
- This method will be triggered upon clicking on an ActionURL from
our view.jsp. It will retrieve
- <emphasis>yourname</emphasis>
- from the HTML form, and pass it along as a renderParameter to the
doView().
+ This method will be triggered upon clicking on an
<literal>ActionURL</literal> from our
+ <literal>view.jsp</literal>. It will retrieve
<literal>yourname</literal> from the HTML form,
+ and pass it along as a
<literal>renderParameter</literal> to the
<literal>doView()</literal>
+ method.
</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.
+ Just like in the servlet world, you must declare which kind of
MIME type of the content the
+ portlet will be generating.
</para>
</listitem>
<listitem>
@@ -615,100 +599,29 @@
<programlisting><![CDATA[protected void
doView(RenderRequest rRequest, RenderResponse rResponse)
throws PortletException, IOException, UnavailableException
]]></programlisting>
- In this case, our doView, is responsible for dispatching to the
appropriate jsp
- <emphasis>view.jsp</emphasis>
- or
- <emphasis>view2.jsp</emphasis>
- , depending on the existence of the
- <emphasis>yourname</emphasis>
- parameter passed in from the
- <emphasis>processAction</emphasis>
- .
+ In this case, our <literal>doView</literal>
implementation is responsible for dispatching to
+ the appropriate JSP <literal>view.jsp</literal> or
<literal>view2.jsp</literal>, depending on
+ the existence of the <literal>yourname</literal>
parameter passed in from
+ <literal>processAction</literal>.
</para>
</listitem>
</itemizedlist>
</para>
- </sect3>
+ </sect3>
<sect3>
- <title>The Application Descriptors</title>
- <para>
- JBoss Portal requires certain descriptors be included in your portlet war,
for different reasons. Some of
- these descriptors are defined by the Portlet Specification, and some are
specific to JBoss Portal. For
- brevity, we only discuss the
- <emphasis>portlet.xml</emphasis>
- descriptor here. For discussion on the other descriptors, please view
- <xref linkend="first_portlet_descriptors"/>
- or the
- chapter on descriptors:
- <xref linkend="descriptors_portlet"/>
- .
- <mediaobject>
- <imageobject>
- <imagedata align="center"
fileref="images/tutorials/jsp_portlet/package.gif"
valign="middle"/>
- </imageobject>
- </mediaobject>
- <itemizedlist>
- <listitem>
- <para>
- portlet.xml
- <programlisting><![CDATA[<?xml
version="1.0" encoding="UTF-8"?>
-<portlet-app
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1...
-
http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
- version="1.0">
- <portlet>
- <portlet-name>HelloWorldJSPPortlet</portlet-name>
-
<portlet-class>org.jboss.portlet.hello.HelloWorldJSPPortlet</portlet-class>
- <supports>
- <mime-type>text/html</mime-type>
- <portlet-mode>VIEW</portlet-mode>
- <portlet-mode>EDIT</portlet-mode>
- <portlet-mode>HELP</portlet-mode>
- </supports>
- <portlet-info>
- <title>HelloWorld JSP Portlet</title>
- </portlet-info>
- </portlet>
-</portlet-app>]]></programlisting>
- This file must adhere to its definition in the Portlet
Specification. You may define more than
- one portlet application in this file.
- <note>
- This sample portlet supports 3 view modes: VIEW, EDIT, and
HELP. The supported modes must be
- declared in the
- <emphasis>portlet.xml</emphasis>
- using the
- <emphasis>portlet-mode</emphasis>
- tag.
- .
- </note>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect3>
- <sect3>
<title>JSP files and the portlet taglib</title>
<para>
- Of importance in this tutorial are the two view jsps. The first, allows
the user to input his name, which
- is then posted to the
- <emphasis>processAction</emphasis>
- method in our portlet class, set as a
- <emphasis>renderParameter</emphasis>
- , then the render method is invoked (in our case its the
- <emphasis>doView</emphasis>
- , which then dispatches to our
- <emphasis>view2.jsp</emphasis>
- .
+ Of importance in this tutorial are the two view JSPs. The first,
<literal>view.jsp</literal>, allows the
+ user to input his name, which is then posted to the
<literal>processAction</literal> method in our
+ portlet class, set as a <literal>renderParameter</literal>,
then the <literal>render</literal> method is
+ invoked (in our case, <literal>doView</literal>, which then
dispatches to our
+ <literal>view2.jsp</literal>).
<mediaobject>
<imageobject>
- <imagedata align="center"
fileref="images/tutorials/jsp_portlet/process.gif"
- valign="middle"/>
+ <imagedata align="center"
fileref="images/tutorials/jsp_portlet/process.gif"
valign="middle"/>
</imageobject>
</mediaobject>
- Now lets have a look at our
- <emphasis>view.jsp</emphasis>
- :
+ Now let's have a look at our <literal>view.jsp</literal>:
</para>
<para>
<programlisting><![CDATA[<%@ taglib
uri="http://java.sun.com/portlet" prefix="portlet" %>
@@ -734,42 +647,32 @@
<listitem>
<para>
<programlisting><![CDATA[<%@ taglib
uri="http://java.sun.com/portlet" prefix="portlet"
%>]]></programlisting>
- Define the portlet taglib. You do not need to bundle the portlet
taglib, JBoss Portal will
- handle that for you.
+ Define the portlet taglib. You do
<emphasis>NOT</emphasis> need to bundle the portlet taglib,
+ JBoss Portal will handle that for you.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<portlet:defineObjects/>]]></programlisting>
- Calling
- <emphasis>defineObjects</emphasis>
- creates implicit objects in this jsp, that you can access, like:
- <emphasis>renderRequest, actionRequest,
portletConfig</emphasis>
- .
+ Calling <literal>defineObjects</literal> makes
available implicit objects, such as
+ <literal>renderRequest, actionRequest,
portletConfig</literal>, in this JSP.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<form
action="<portlet:actionURL><portlet:param name="page"
value="mainview"/>
</portlet:actionURL>"
method="POST">]]></programlisting>
- We create an HTML form, but generate the URL it will post to,
using the portlet tag library. In
- this case, notice how we are creating an
- <emphasis>actionURL</emphasis>
- , which will activate out
- <emphasis>processAction</emphasis>
- method, passing in any input parameters in the form.
+ We create an HTML form, but generate the URL it will post to
using the portlet tag library. In
+ this case, notice how we are creating an
<literal>actionURL</literal>, which will activate our
+ <literal>processAction</literal> method, passing in
any input parameters in the form.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<a
href="<portlet:renderURL><portlet:param name="yourname"
value="Roy Russo">
</portlet:param></portlet:renderURL>">]]></programlisting>
- Likewise, we are able to create a link to our
- <emphasis>doView</emphasis>
- , by simply creating it with a
- <emphasis>renderURL</emphasis>
- , that passes in our
- <emphasis>yourname</emphasis>
+ Likewise, we are able to create a link to our
<literal>doView</literal> method, by simply
+ creating it with a <literal>renderURL</literal>, that
passes in our <literal>yourname</literal>
parameter.
</para>
</listitem>
@@ -777,103 +680,45 @@
</para>
</sect3>
<sect3>
- <title>Building your portlet</title>
- <para>If you have downloaded the sample, you can execute the build.xml
with ANT or inside your IDE.
- Executing the
- <emphasis>deploy</emphasis>
- target
- will compile all src files and produce a helloworldportlet.war under
-
<emphasis>HelloWorldPortlet\helloworldjspportlet.war.</emphasis>
-
+ <title>Building and deploying your portlet</title>
+ <para>If you have downloaded the sample, you can execute the build.xml
with ant or inside your IDE.
+ Executing the <literal>deploy</literal> target will compile
all source files and produce a
+ <literal>helloworldjspportlet.war</literal> file in a way
similar to what we saw in
+ <xref linkend="first_portlet_build"/>.
</para>
<para>
+ The <literal>explode</literal> target will produce the
following:
<mediaobject>
<imageobject>
- <imagedata align="center"
fileref="images/tutorials/jsp_portlet/building.gif"
valign="middle"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>
- If you want to create an expanded war directory, after executing the above
deploy target, you should
- execute the
- <emphasis>explode</emphasis>
- target.
- <mediaobject>
- <imageobject>
- <imagedata align="center"
fileref="images/tutorials/jsp_portlet/buildexplode.gif"
- valign="middle"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>
- The above target will produce the following:
- <mediaobject>
- <imageobject>
<imagedata align="center"
fileref="images/tutorials/jsp_portlet/exploded.gif"
valign="middle"/>
</imageobject>
</mediaobject>
- This will deflate the helloworldjspportlet.war, and allow you to deploy it
as an expanded directory. It
- will
- work just the same, with some additional benefits noted below:
</para>
<para>
- The advantage to expanded war deployments is that you can modify xml
descriptors, resource files
- jsp/jsf pages easily during development. Simply
- <emphasis>touch</emphasis>
- the web.xml to have JBoss Application Server hot-deploy the web
appllication on a live-running server
- instance
- </para>
- </sect3>
- <sect3>
- <title>Deploying your portlet</title>
- <para>
- Deploying a portlet is as simple as copying/moving the
- <emphasis>helloworldjspportlet.war</emphasis>
- in to the server deploy directory. Doing this on a running instance of the
portal and application server,
- will trigger a
- <emphasis>hot-deploy</emphasis>
- :
- <programlisting><![CDATA[15:54:34,234 INFO [Server] JBoss (MX
MicroKernel) [4.0.5.GA (build:
- CVSTag=JBoss_4_0_5_GA date=2006000000)]
- Started in 1m:9s:766ms
-15:55:04,062 INFO [TomcatDeployer] deploy, ctxPath=/helloworldjspportlet,
-
warUrl=.../tmp/deploy/tmp57782helloworldjspportlet-exp.war/]]></programlisting>
- Pointing your browser to
- <ulink
url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink>
- , should yield a view of our HelloWorldPortlet:
+ Deploying the portlet is as easy as copying/moving the
<literal>helloworldjspportlet.war</literal> file
+ to the server <literal>deploy</literal> directory. We can then
see our portlet on the Portal default
+ page (<ulink
url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink>):
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/jsp_portlet/output.png"
valign="middle"/>
</imageobject>
</mediaobject>
</para>
- </sect3>
+ </sect3>
</sect2>
- <sect2>
- <title>A Simple JSF Portlet</title>
+ <sect2 id="myfaces_40x">
+ <title>A Simple MyFaces JSF Portlet on JBoss AS 4.0.x</title>
<sect3>
<title>Introduction</title>
- <para>This section will introduce the reader to deploying a simple JSF
portlet in JBoss Portal. It requires
- you
- download the HelloWorldJSFPortlet from
PortletSwap.com, using this
- <ulink
-
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
- link</ulink>
- .
+ <para>This section will introduce the reader to deploying a simple JSF
portlet in JBoss Portal, using
+ Apache's MyFaces JSF implementation on JBoss AS 4.0.x. It requires you
download the HelloWorldJSFPortlet
+ from
PortletSwap.com, using this
+ <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...;.
</para>
- <para>
- This portlet will introduce you to leveraging the JSF framework in portlet
development.
- </para>
- </sect3>
+ </sect3>
<sect3>
- <title>Package Structure</title>
+ <title>Package Content</title>
<para>
- Portlets are packaged in war files, just like other JEE applications. A
typical portlet war file can also
- include servlets, resource bundles, images, html, jsps, and other static
or dynamic files you would
- commonly
- include.
- </para>
- <para>
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/jsf_portlet/package.gif"
valign="middle"/>
@@ -881,29 +726,15 @@
</mediaobject>
Like a typical JSF application, we also package our faces-config.xml that
defines our
managed-beans, converters, validators, navigation rules, etc...
- </para>
- <para>
- <note>When deploying on JBoss Application Seever, you do not need to
package the myfaces libraries with
- your portlet application. JBoss AS already bundles these libraries by
default under
-
<emphasis>JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/jsf-libs/</emphasis>
+ <note>JBoss Application Server version 4.0.x bundles Apache's
MyFaces JSF implementation in
+
<literal>JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/jsf-libs/</literal>.
As a result,
+ you do not need to package MyFaces' libraries with your portlet
application.
</note>
</para>
- </sect3>
- <sect3>
- <title>The Application Descriptors</title>
- <para>
- JBoss Portal requires certain descriptors be included in your portlet war,
for different reasons. Some of
- these descriptors are defined by the Portlet Specification, and some are
specific to JBoss Portal. For
- brevity, we only discuss the
- <emphasis>portlet.xml</emphasis>
- and
- <emphasis>faces-config.xml</emphasis>
- descriptors here. For discussion on the other descriptors, please view
- <xref linkend="first_portlet_descriptors"/>
- or the
- chapter on descriptors:
- <xref linkend="descriptors_portlet"/>
- .
+ <para>For the sake of brevity, we only discuss the
<literal>portlet.xml</literal> and
+ <literal>faces-config.xml</literal> descriptors here. For
discussion on the other descriptors, please
+ view <xref linkend="first_portlet_descriptors"/> or the
chapter on descriptors:
+ <xref linkend="descriptors_portlet"/>.
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/jsf_portlet/package.gif"
valign="middle"/>
@@ -911,9 +742,8 @@
</mediaobject>
<itemizedlist>
<listitem>
- <para>
- portlet.xml
- <programlisting><![CDATA[<?xml
version="1.0" encoding="UTF-8"?>
+ <para><literal>portlet.xml</literal>
+<programlisting><![CDATA[<?xml version="1.0"
encoding="UTF-8"?>
<portlet-app
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1...
@@ -936,15 +766,15 @@
</portlet>
</portlet-app>]]></programlisting>
This file must adhere to its definition in the Portlet
Specification. You may define more than
- one portlet application in this file. Now lets look at the
portions that deal with our use of
+ one portlet application in this file. Now let's look at the
portions that deal with our use of
JSF:
<itemizedlist>
<listitem>
<para>
- Here we define our portlet class, as we normally would.
However, note the use of the
- MyFacesGenericPortlet. In this case, we will allow the
MyFacesGenericPortlet to handle
- all requests/responses from our users:
<programlisting><![CDATA[<portlet-class>org.apache.myfaces.portlet.MyFacesGenericPortlet</portlet-class>]]></programlisting>
+ Here we specify that MyFacesGenericPortlet will handle
all requests/responses from our
+ users. There is therefore no need to develop a specific
portlet class, MyFaces
+ providing a generic implementation bridging the JSF and
portlet worlds.
<note>If you wanted to add more functionality to
your JSF portlet, not included in the
MyFacesGenericPortlet, you could sublass it and
create your own Class.</note>
</para>
@@ -963,8 +793,8 @@
</para>
</listitem>
<listitem>
- <para>faces-config.xml
- <programlisting><![CDATA[<?xml
version="1.0"?>
+ <para><literal>faces-config.xml</literal>
+<programlisting><![CDATA[<?xml version="1.0"?>
<!DOCTYPE faces-config PUBLIC
"-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
"http://java.sun.com/dtd/web-facesconfig_1_0.dtd">
@@ -982,101 +812,80 @@
</navigation-case>
</navigation-rule>
</faces-config>]]></programlisting>
- There is nothing special about the faces-config.xml included
here. This application would work
- just as well outside of a portlet as it would inside a portlet
container. In the above lines, we
- define a basic User Bean and a navigation rule to handle the
submittal of the original form on
- the index.jsp.
+ There is nothing special about the
<literal>faces-config.xml</literal> file included here. This
+ application would work just as well outside of a portlet as it
would inside a portlet container.
+ In the above lines, we define a basic
<literal>User</literal> Bean and a navigation rule to
+ handle the submittal of the original form on
<literal>index.jsp</literal>.
</para>
</listitem>
</itemizedlist>
</para>
</sect3>
<sect3>
- <title>The JSP files</title>
+ <title>JSP files</title>
+ <para>TODO!!</para>
</sect3>
<sect3>
- <title>Building your portlet</title>
- <para>If you have downloaded the sample, you can execute the build.xml
with ANT or inside your IDE.
- Executing the
- <emphasis>deploy</emphasis>
- target
- will compile all src files and produce a helloworldjsfportlet.war under
-
<emphasis>HelloWorldJSFPortlet\helloworldjsfportlet.war.</emphasis>
-
+ <title>Building and deploying your portlet</title>
+ <para>If you have downloaded the sample, you can execute the build.xml
with ant or inside your IDE.
+ Executing the <literal>deploy</literal> target will compile
all source files and produce a
+ <literal>helloworldjspportlet.war</literal> file in a way
similar to what we saw in
+ <xref linkend="first_portlet_build"/>.
</para>
<para>
+ The <literal>explode</literal> target will produce the
following:
<mediaobject>
<imageobject>
- <imagedata align="center"
fileref="images/tutorials/jsf_portlet/building.gif"
valign="middle"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>
- If you want to create an expanded war directory, after executing the above
deploy target, you should
- execute the
- <emphasis>explode</emphasis>
- target.
- <mediaobject>
- <imageobject>
- <imagedata align="center"
fileref="images/tutorials/jsf_portlet/buildexplode.gif"
- valign="middle"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>
- The above target will produce the following:
- <mediaobject>
- <imageobject>
<imagedata align="center"
fileref="images/tutorials/jsf_portlet/exploded.gif"
valign="middle"/>
</imageobject>
</mediaobject>
- This will deflate the helloworldjsfportlet.war, and allow you to deploy it
as an expanded directory. It
- will
- work just the same, with some additional benefits noted below:
</para>
<para>
- The advantage to expanded war deployments is that you can modify xml
descriptors, resource files
- jsp/jsf pages easily during development. Simply
- <emphasis>touch</emphasis>
- the web.xml to have JBoss Application Server hot-deploy the web
application on a live-running server
- instance
- </para>
- </sect3>
- <sect3>
- <title>Deploying your portlet</title>
- <para>
- Deploying a portlet is as simple as copying/moving the
- <emphasis>helloworldjsfportlet.war</emphasis>
- in to the server deploy directory. Doing this on a running instance of the
portal and application server,
- will trigger a
- <emphasis>hot-deploy</emphasis>
- :
- <programlisting><![CDATA[22:30:03,093 INFO [TomcatDeployer]
deploy, ctxPath=/helloworldjsfportlet,
- warUrl=.../tmp/deploy/tmp5571helloworldjsfportlet-exp.war/
-22:30:03,312 INFO [FacesConfigurator] Reading standard config
- org/apache/myfaces/resource/standard-faces-config.xml
-22:30:03,390 INFO [FacesConfigurator] Reading config
- jar:file:/C:/jboss-4.0.5.GA/server/default/tmp/deploy/
- tmp5504jboss-portal.sar-contents/lib/jsf-facelets.jar!/
- META-INF/faces-config.xml
-22:30:03,406 INFO [FacesConfigurator] Reading config jar:file:/C:/jboss-4.0.5.GA/
- server/default/tmp/deploy/tmp5504jboss-portal.sar-contents/
- lib/tomahawk.jar!/META-INF/faces-config.xml
-22:30:03,468 INFO [FacesConfigurator] Reading config /WEB-INF/faces-config.xml
-22:30:03,484 ERROR [LocaleUtils] Locale name null or empty, ignoring
-22:30:03,640 INFO [MyFacesGenericPortlet] PortletContext 'C:\jboss-4.0.5.GA\server\
- default\.\tmp\deploy\tmp5571helloworldjsfportlet-exp.war\'
- initialized.]]></programlisting>
- Pointing your browser to
- <ulink
url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink>
- , should yield a view of our HelloWorldJSFPortlet:
+ Deploying the portlet is as easy as copying/moving the
<literal>helloworldjspportlet.war</literal> file
+ to the server <literal>deploy</literal> directory. We can then
see our portlet on the Portal default
+ page (<ulink
url="http://localhost:8080/portal/">http://localhost:8080/portal/</ulink>):
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/jsf_portlet/output.png"
valign="middle"/>
</imageobject>
</mediaobject>
</para>
- </sect3>
+ </sect3>
</sect2>
+ <sect2>
+ <title>Adapting MyFaces JSF Portlet to work on JBoss AS
4.2.x</title>
+ <para>We saw in <xref linkend="myfaces_40x"/> how to
create a JSF-based portlet using Apache's MyFaces
+ JSF implementation on JBoss Application Server 4.0.x. Starting with version
4.2.0 of JBoss Application
+ Server, the default bundled JSF implementation is Sun's Reference
Implementation (RI). We thus need to
+ adapt our MyFaces portlet sightly so that it works in this new environment.
+ </para>
+ <para>The first step is to provide access to MyFaces as it's not
bundled anymore in JBoss AS. This is
+ accomplished by adding <literal>myfaces-api.jar</literal> and
<literal>myfaces-impl.jar</literal> in
+ our portlet <literal>WEB-INF/lib</literal> directory. This can be
done automatically via a modification of
+ the ant script and is left as an exercise to the reader.
+ </para>
+ <para>
+ We also need to need to tell JBoss AS not to use its bundled JSF
implementation for our portlet. This
+ is accomplished by adding the following to our portlet's
<literal>web.xml</literal>:
+ <programlisting><![CDATA[<context-param>
+ <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name>
+ <param-value>true</param-value>
+</context-param>]]></programlisting>
+ More details on this procedure can be found at <ulink
+
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossFaces">ht...;.
+ </para>
+ <para>
+ We should get the following package content for our portlet:
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/tutorials/jsf_portlet/package_42x.png"
valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ </sect2>
+ <sect2>
+ <title>JSF Portlet using Sun's JSF Reference Implementation
(RI)</title>
+ <para>TODO</para>
+ </sect2>
</sect1>
</chapter>
\ No newline at end of file
Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml 2007-08-28
23:44:23 UTC (rev 8090)
+++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml 2007-08-29
08:41:42 UTC (rev 8091)
@@ -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>
Modified: docs/trunk/referenceGuide/en/master.xml
===================================================================
--- docs/trunk/referenceGuide/en/master.xml 2007-08-28 23:44:23 UTC (rev 8090)
+++ docs/trunk/referenceGuide/en/master.xml 2007-08-29 08:41:42 UTC (rev 8091)
@@ -32,9 +32,9 @@
]>
<book lang="en">
<bookinfo>
- <title>JBoss Portal 2.6.0-GA</title>
+ <title>JBoss Portal 2.8.0</title>
<subtitle>Reference Guide</subtitle>
- <releaseinfo>Release 2.6.0-GA "Ninja"</releaseinfo>
+ <releaseinfo>Release 2.8.0</releaseinfo>
<releaseinfo>June 2007</releaseinfo>
<author>
<firstname>Thomas</firstname>
Modified: docs/trunk/referenceGuide/en/modules/installation.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/installation.xml 2007-08-28 23:44:23 UTC (rev
8090)
+++ docs/trunk/referenceGuide/en/modules/installation.xml 2007-08-29 08:41:42 UTC (rev
8091)
@@ -110,7 +110,8 @@
<sect3>
<title>Application Server Setup</title>
<para>Of course you will need to install JBoss Application Server prior
to installing JBoss
- portal, if you didn't do so yet, please install JBoss 4.0.5+ from
+ portal, if you didn't do so yet, please install JBoss EAP 4.2, JBoss
AS 4.2.1 or JBoss AS 4.0.5 if
+ you have to. You can have access to the EAP version from the support
portal or the other versions
<ulink
url="http://labs.jboss.com/portal/jbossas/download/index.html"
here
@@ -126,7 +127,7 @@
</sect3>
<sect3>
<title>Database Setup</title>
- <para>You will need a database for JBoss Portal to function, you can
use any database
+ <para>You will need a database for JBoss Portal to run, you can use any
database
supported by Hibernate.
<orderedlist>
<listitem>
@@ -271,7 +272,8 @@
<sect3>
<title>Application Server Setup</title>
<para>Of course you will need to install JBoss Application Server prior
to installing JBoss
- portal, if you didn't do so yet, please install JBoss 4.0.5+ from
+ portal, if you didn't do so yet, please install JBoss EAP 4.2, JBoss
AS 4.2.1 or JBoss AS 4.0.5 if
+ you have to. You can have access to the EAP version from the support
portal or the other versions
<ulink
url="http://labs.jboss.com/portal/jbossas/download/index.html"
here
Modified: docs/trunk/referenceGuide/en/modules/migration.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/migration.xml 2007-08-28 23:44:23 UTC (rev 8090)
+++ docs/trunk/referenceGuide/en/modules/migration.xml 2007-08-29 08:41:42 UTC (rev 8091)
@@ -53,7 +53,7 @@
are visable. If you use default theme like "renaissance" that is
present in 2.6, you shouldn't need to do anything. To update your custom themes
please
refer to those bundled with portal as an example.
</para>
- <note>If you stay with old theme files you may find JBP 2.6 unusable by
not even be able to log in.</note>
+ <note>If you stay with old theme files you may find JBP 2.6 unusable to
the point that you may not even be able to log in</note>
</sect2>
<sect2>
<title>Database</title>
Modified: docs/trunk/referenceGuide/en/modules/portalapi.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-08-28 23:44:23 UTC (rev 8090)
+++ docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-08-29 08:41:42 UTC (rev 8091)
@@ -20,10 +20,10 @@
that no changes should be required when code is written against the API provided
by the JBoss Portal
2.x versions and used in a later version of JBoss Portal 2.x.</para>
- <para>The Portal API package prefix is
<emphasis>org.jboss.portal.api</emphasis> and all the classes
- part of the API are prefixed with that package except for two of them which are
the <emphasis>org.jboss.portal.Mode</emphasis>
- and <emphasis>org.jboss.portal.WindowState</emphasis> classes, the
main reason being that twose two classes were defined
- very early before the official Portal API framework was created.</para>
+ <para>The Portal API package prefix is
<emphasis>org.jboss.portal.api</emphasis>. All of the classes that are part
+ of this API are prefixed with this package name except for the
<emphasis>org.jboss.portal.Mode</emphasis>
+ and <emphasis>org.jboss.portal.WindowState</emphasis> classes. These
two classes were defined before the official
+ Portal API framework was created and so the names have been maintained for
backward compatibility.</para>
<para>The Portlet API defines two classes that represents a portion of the
visual state of a Portlet which
are <emphasis>javax.portlet.PortletMode</emphasis> and
<emphasis>javax.portlet.WindowState</emphasis>. Likewise
the Portal API defines similar classes named
<emphasis>org.jboss.portal.Mode</emphasis> and
@@ -104,8 +104,8 @@
</caption>
</mediaobject>
<para>The
<emphasis>org.jboss.portal.api.PortalRuntimeContext</emphasis> gives access to
state or operations
- associated at runtime with the current user of the portal. It allows to retrieve
the user id when the method
- <emphasis>String getUserId()</emphasis> returns a non null string. It
also gives access to the
+ associated at runtime with the current user of the portal. The
<emphasis>String getUserId()</emphasis> retrieve
+ the user id and can return null if no user is associated with the context. It also
gives access to the
<emphasis>PortalSession</emphasis> instance associated with the current
user. Finally it gives access to the
<emphasis>NavigationalStateContext</emphasis> associated with the
current user.</para>
</sect1>
@@ -210,8 +210,8 @@
</mediaobject>
<para>
The
<emphasis>org.jboss.portal.api.event.PortalEventContext</emphasis> interface
defines the context in which
- an event is created and propagated. It allows to retrieve the
<emphasis>PortalRuntimeContext</emphasis> in
- order to obtain the portal context. Note that this method may return null if no
context is available.
+ an event is created and propagated. It allows retrieval of the
<emphasis>PortalRuntimeContext</emphasis> which
+ can in turn be used to obtain the portal context.
</para>
<mediaobject>
<imageobject>
@@ -292,9 +292,9 @@
interface semantic allows only traditional event delivering. The
<emphasis>PortalNodeEventListener</emphasis>
interface is designed to match the bubbling effect during an event
delivery.</para>
<para>The <emphasis>PortalNodeEvent
onEvent(PortalNodeEventContext context, PortalNodeEvent event)</emphasis>
- declare a <emphasis>PortalNodeEvent</emphasis> as return type. In
normal circumstances it will return the
- null value, however if the method call returns an event then this event
should be considered by the portal
- as behavior replacing the current one.
+ method declares a <emphasis>PortalNodeEvent</emphasis> as return
type. Commonly the method returns null;
+ however, a returned PortalNodeEvent replaces the event in the listeners
subsequently called during
+ the event bubbling process.
</para>
</sect3>
<sect3>
@@ -459,7 +459,7 @@
<para>The first version of the Portlet Specification (JSR 168),
regretfully, did not cover interaction between
portlets. The side-effect of diverting the issue to the subsequent release of
the specification, has
forced portal vendors to each craft their own proprietary API to achieve
interportlet communication. Here we will
- see how we can use the event mechanism to pass parameters from one portlet to
the other.</para>
+ see how we can use the event mechanism to pass parameters from one portlet to
the other (and only to the other portlet).</para>
<para>The overall scenario will be that Portlet B will need to be updated
based on some parameter set on Portlet A.
To achieve that we will use a portal node event.</para>
<para>Portlet A is a simple Generic portlet that has a form that sends a
color name:
@@ -539,6 +539,12 @@
// We can redirect
newEvent = new WindowActionEvent(windowB);
newEvent.setParameters(wae.getParameters());
+
+ // Due to a bug those 2 following lines are required but have no meaning for now
+ // See:
http://jira.jboss.com/jira/browse/JBPORTAL-1604
+ newEvent.setMode(wae.getMode());
+ newEvent.setWindowState(WindowState.MAXIMIZED);
+
// Redirect to the new event
return newEvent;
}
@@ -570,6 +576,41 @@
newEvent.setWindowState(wae.getWindowState()); //
WindowState.MAXIMIZED</programlisting>
</para>
-->
+ <para>
+ We still need to register our listener as an mbean:
+ <programlisting>
+<![CDATA[<mbean
+ code="org.jboss.portal.core.event.PortalEventListenerServiceImpl"
+ name="portal:service=ListenerService,type=test_listener"
+ xmbean-dd=""
+ xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
+ <xmbean/>
+ <depends
+ optional-attribute-name="Registry"
+
proxy-type="attribute">portal:service=ListenerRegistry</depends>
+ <attribute name="RegistryId">test_listener</attribute>
+ <attribute
name="ListenerClassName">org.jboss.portal.core.samples.basic.event.PortletB$Listener</attribute>
+</mbean>]]></programlisting>
+ For node events, we also need to declare on which node we want to listen,
this is done by modifying
+ the <literal>*-object.xml</literal> that defines your portal
nodes. In this example we want to trigger
+ the listener each time the window containing the portlet A is actioned. We
can add the <literal>listener</literal>
+ tag to specify that out listener with
<literal>RegistryId</literal>=test_listener should be triggered
+ on events on the embedding object.
+ <programlisting>
+<![CDATA[...
+ <window>
+ <window-name>PortletAWindow</window-name>
+ <instance-ref>PortletAInstance</instance-ref>
+ <region>center</region>
+ <height>0</height>
+ <listener>test_listener</listener>
+ </window>
+...]]>
+ </programlisting>
+ Of course we could have added it at the page level instead of the window
level. Note that a unique listener
+ can be specified, the event mechanism is primarily done to let the developer
change the navigation state of the
+ portal, this example being a nice side-effect of this feature.
+ </para>
<note>The portlet 2.0 specification (JSR 286) will cover Inter Portlet
Communication so that portlets using it
can work with different portal vendors.</note>
</sect2>