Author: thomas.heute(a)jboss.com
Date: 2008-06-12 09:28:43 -0400 (Thu, 12 Jun 2008)
New Revision: 10999
Added:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/errorhandling/errorHandling_management.png
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/trademarks.xml
Modified:
docs/branches/JBoss_Portal_Branch_2_6/pom.xml
docs/branches/JBoss_Portal_Branch_2_6/quickstartuser/en/master.xml
docs/branches/JBoss_Portal_Branch_2_6/quickstartuser/pom.xml
docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-bin.README
docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-ha-bin.README
docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-src.README
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml
docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/pom.xml
docs/branches/JBoss_Portal_Branch_2_6/userGuide/pom.xml
docs/branches/JBoss_Portal_Branch_2_7/pom.xml
docs/branches/JBoss_Portal_Branch_2_7/quickstartuser/en/master.xml
docs/branches/JBoss_Portal_Branch_2_7/quickstartuser/pom.xml
docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-bin.README
docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-ha-bin.README
docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-src.README
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/master.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/ajax.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/authentication.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/clustering.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/configuration.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/errorhandling.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/identity.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/identityportlets.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/installation.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/ldap.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/migration.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/portalapi.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/security.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/supported.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/themeandlayouts.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/urls.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/wsrp.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/pom.xml
docs/branches/JBoss_Portal_Branch_2_7/userGuide/pom.xml
Log:
Merging docs, and changed versions
Modified: docs/branches/JBoss_Portal_Branch_2_6/pom.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/pom.xml 2008-06-12 12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_6/pom.xml 2008-06-12 13:28:43 UTC (rev 10999)
@@ -5,7 +5,7 @@
<artifactId>docs-aggregator</artifactId>
<packaging>pom</packaging>
<name>JBoss Portal Docs Aggregator</name>
- <version>2.6.5</version>
+ <version>2.6.6</version>
<modules>
<module>userGuide</module>
Modified: docs/branches/JBoss_Portal_Branch_2_6/quickstartuser/en/master.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/quickstartuser/en/master.xml 2008-06-12 12:45:42
UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_6/quickstartuser/en/master.xml 2008-06-12 13:28:43
UTC (rev 10999)
@@ -11,9 +11,9 @@
]>
<book lang="en">
<bookinfo>
- <title>JBoss Portal 2.6.5</title>
+ <title>JBoss Portal 2.6.6</title>
<subtitle>Quickstart User Guide</subtitle>
- <releaseinfo>Release 2.6.5</releaseinfo>
+ <releaseinfo>Release 2.6.6</releaseinfo>
<author>
<firstname>Kevin</firstname>
Modified: docs/branches/JBoss_Portal_Branch_2_6/quickstartuser/pom.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/quickstartuser/pom.xml 2008-06-12 12:45:42 UTC
(rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_6/quickstartuser/pom.xml 2008-06-12 13:28:43 UTC
(rev 10999)
@@ -60,7 +60,7 @@
<groupId>org.jboss.portal</groupId>
<artifactId>quickstartuser-${translation}</artifactId>
- <version>2.6.5</version>
+ <version>2.6.6</version>
<packaging>jdocbook</packaging>
<name>Quick_Start_User_(${translation})</name>
Modified: docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-bin.README
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-bin.README 2008-06-12
12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-bin.README 2008-06-12
13:28:43 UTC (rev 10999)
@@ -1,5 +1,5 @@
- JBoss Portal 2.6.5
+ JBoss Portal 2.6.6
LGPL Licensed (See
http://www.gnu.org/copyleft/lesser.html for details on the product
usage)
JBoss Portal is the next generation open source content management system (CMS) and
portal
Modified: docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-ha-bin.README
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-ha-bin.README 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-ha-bin.README 2008-06-12
13:28:43 UTC (rev 10999)
@@ -1,5 +1,5 @@
- JBoss Portal 2.6.5
+ JBoss Portal 2.6.6
LGPL Licensed (See
http://www.gnu.org/copyleft/lesser.html for details on the product
usage)
JBoss Portal is the next generation open source content management system (CMS) and
portal
Modified: docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-src.README
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-src.README 2008-06-12
12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_6/readmeFiles/jboss-portal-src.README 2008-06-12
13:28:43 UTC (rev 10999)
@@ -1,5 +1,5 @@
- JBoss Portal 2.6.5
+ JBoss Portal 2.6.6
LGPL Licensed (See
http://www.gnu.org/copyleft/lesser.html for details on the product
usage)
JBoss Portal is the next generation open source content management system (CMS) and
portal
Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml 2008-06-12 12:45:42
UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/master.xml 2008-06-12 13:28:43
UTC (rev 10999)
@@ -38,10 +38,10 @@
]>
<book lang="en">
<bookinfo>
- <title>JBoss Portal 2.6.5</title>
+ <title>JBoss Portal 2.6.6</title>
<subtitle>Reference Guide</subtitle>
- <releaseinfo>Release 2.6.5</releaseinfo>
- <releaseinfo>May 2008</releaseinfo>
+ <releaseinfo>Release 2.6.6</releaseinfo>
+ <releaseinfo>July 2008</releaseinfo>
<author>
<firstname>Thomas</firstname>
<surname>Heute</surname>
Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/pom.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/pom.xml 2008-06-12 12:45:42 UTC
(rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/pom.xml 2008-06-12 13:28:43 UTC
(rev 10999)
@@ -60,7 +60,7 @@
<groupId>org.jboss.portal</groupId>
<artifactId>referenceGuide-${translation}</artifactId>
- <version>2.6.5</version>
+ <version>2.6.6</version>
<packaging>jdocbook</packaging>
<name>Reference_Guide_(${translation})</name>
Modified: docs/branches/JBoss_Portal_Branch_2_6/userGuide/pom.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_6/userGuide/pom.xml 2008-06-12 12:45:42 UTC (rev
10998)
+++ docs/branches/JBoss_Portal_Branch_2_6/userGuide/pom.xml 2008-06-12 13:28:43 UTC (rev
10999)
@@ -60,7 +60,7 @@
<groupId>org.jboss.portal</groupId>
<artifactId>user-guide-${translation}</artifactId>
- <version>2.6.5</version>
+ <version>2.6.6</version>
<packaging>jdocbook</packaging>
<name>User_Guide_(${translation})</name>
Modified: docs/branches/JBoss_Portal_Branch_2_7/pom.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/pom.xml 2008-06-12 12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/pom.xml 2008-06-12 13:28:43 UTC (rev 10999)
@@ -5,7 +5,7 @@
<artifactId>docs-aggregator</artifactId>
<packaging>pom</packaging>
<name>JBoss Portal Docs Aggregator</name>
- <version>2.6.4-</version>
+ <version>2.7.0</version>
<modules>
<module>userGuide</module>
Modified: docs/branches/JBoss_Portal_Branch_2_7/quickstartuser/en/master.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/quickstartuser/en/master.xml 2008-06-12 12:45:42
UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/quickstartuser/en/master.xml 2008-06-12 13:28:43
UTC (rev 10999)
@@ -11,9 +11,9 @@
]>
<book lang="en">
<bookinfo>
- <title>JBoss Portal 2.6.4</title>
+ <title>JBoss Portal 2.7.0</title>
<subtitle>Quickstart User Guide</subtitle>
- <releaseinfo>Release 2.6.4</releaseinfo>
+ <releaseinfo>Release 2.7.0</releaseinfo>
<author>
<firstname>Kevin</firstname>
Modified: docs/branches/JBoss_Portal_Branch_2_7/quickstartuser/pom.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/quickstartuser/pom.xml 2008-06-12 12:45:42 UTC
(rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/quickstartuser/pom.xml 2008-06-12 13:28:43 UTC
(rev 10999)
@@ -60,7 +60,7 @@
<groupId>org.jboss.portal</groupId>
<artifactId>quickstartuser-${translation}</artifactId>
- <version>2.6.4</version>
+ <version>2.7.0</version>
<packaging>jdocbook</packaging>
<name>Quick_Start_User_(${translation})</name>
Modified: docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-bin.README
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-bin.README 2008-06-12
12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-bin.README 2008-06-12
13:28:43 UTC (rev 10999)
@@ -1,5 +1,5 @@
- JBoss Portal 2.6.4
+ JBoss Portal 2.7.0
LGPL Licensed (See
http://www.gnu.org/copyleft/lesser.html for details on the product
usage)
JBoss Portal is the next generation open source content management system (CMS) and
portal
Modified: docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-ha-bin.README
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-ha-bin.README 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-ha-bin.README 2008-06-12
13:28:43 UTC (rev 10999)
@@ -1,5 +1,5 @@
- JBoss Portal 2.6.4
+ JBoss Portal 2.7.0
LGPL Licensed (See
http://www.gnu.org/copyleft/lesser.html for details on the product
usage)
JBoss Portal is the next generation open source content management system (CMS) and
portal
Modified: docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-src.README
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-src.README 2008-06-12
12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/readmeFiles/jboss-portal-src.README 2008-06-12
13:28:43 UTC (rev 10999)
@@ -1,5 +1,5 @@
- JBoss Portal 2.6.4
+ JBoss Portal 2.7.0
LGPL Licensed (See
http://www.gnu.org/copyleft/lesser.html for details on the product
usage)
JBoss Portal is the next generation open source content management system (CMS) and
portal
Added:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/errorhandling/errorHandling_management.png
===================================================================
(Binary files differ)
Property changes on:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/errorhandling/errorHandling_management.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/master.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/master.xml 2008-06-12 12:45:42
UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/master.xml 2008-06-12 13:28:43
UTC (rev 10999)
@@ -1,6 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
"../../docbook-support/support/docbook-dtd/docbookx.dtd" [
+ <!ENTITY trademarks SYSTEM "modules/trademarks.xml">
<!ENTITY overview SYSTEM "../../common/en/modules/overview.xml">
<!ENTITY featurelist SYSTEM
"../../common/en/modules/featurelist.xml">
<!ENTITY target SYSTEM "modules/target.xml">
@@ -37,10 +38,10 @@
]>
<book lang="en">
<bookinfo>
- <title>JBoss Portal 2.6.4</title>
+ <title>JBoss Portal 2.7.0</title>
<subtitle>Reference Guide</subtitle>
- <releaseinfo>Release 2.6.4</releaseinfo>
- <releaseinfo>February 2008</releaseinfo>
+ <releaseinfo>Release 2.7.0</releaseinfo>
+ <releaseinfo>July 2008</releaseinfo>
<author>
<firstname>Thomas</firstname>
<surname>Heute</surname>
@@ -68,6 +69,7 @@
</author>
</bookinfo>
<toc/>
+ <!-- Trademark - Trying to make all vendor legal teams happy -->
&trademarks;
<!-- Portal overview - marketing stuff --> &overview;
<!-- Comprehensive list of included features --> &featurelist;
<!-- Target audience of this document --> ⌖
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/ajax.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/ajax.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/ajax.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -209,7 +209,7 @@
<listitem>
<para>Form GET are not handled, however it should not be an
issue as this situation is discouraged
by the Portlet specification. It however taken in account, just in
case of. Here is an example
- of a Java Server Page that would do one:</para>
+ of a JavaServer Page that would do one:</para>
<programlisting><![CDATA[
<form action="<%= renderResponse.createActionURL() %>"
method="get">
...
Modified:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/authentication.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/authentication.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/authentication.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -16,7 +16,7 @@
To better understand authentication mechanisms in JBoss Portal please refer to
<link
linkend="security.security_authentication">Security</link> chapter.
To learn more about JAAS look for proper documentation on
- <ulink
url="http://java.sun.com/javase/6/docs/technotes/guides/security/&qu...
security</ulink> website.
+ <ulink
url="http://java.sun.com/javase/6/docs/technotes/guides/security/&qu...
Security</ulink> website.
To learn more about security in JBoss Application Server please read
<ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossSX">JBoss...
documentation.
</para>
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/clustering.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/clustering.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/clustering.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -313,11 +313,11 @@
<para>Finally we can start both servers, open two shells and execute :
<programlisting><![CDATA[
cd $JBOSS_HOME/bin
->./run.sh -c ports-01
+>sh run.sh -c ports-01
]]></programlisting>
<programlisting><![CDATA[
cd $JBOSS_HOME/bin
->./run.sh -c ports-02
+>sh run.sh -c ports-02
]]></programlisting>
</para>
</sect1>
Modified:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/configuration.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/configuration.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/configuration.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -14,12 +14,12 @@
</chapterinfo>
<title>Customizing your Installation</title>
<para>
- This chapter describes how to customize the default installation. This includes the
JBoss EAP or JBoss AS listening port, email and proxy settings, and database dialect
settings. For further configuration details, please see <xref
linkend="portaldescriptors"/> and <xref
linkend="troubleshooting"/>.
+ This chapter describes how to customize the default installation. This includes the
JBoss EAP or JBoss AS listening port, email and proxy settings, and database dialect
settings. For further configuration details, refer to <xref
linkend="portaldescriptors"/> and <xref
linkend="troubleshooting"/>.
</para>
<sect1>
<title>Changing the Port</title>
<para>
- It is common for web services to run on port 80. By default, JBoss EAP and JBoss
AS use port 8080. If you can not use <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=UsingPortForwardingWit...
forwarding</ulink>, it is recommended to change the port JBoss EAP or JBoss AS
listens on. To change the default port, open the
<filename>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml</filename>
file, and edit the <computeroutput>Connector port</computeroutput> value for
the <computeroutput>jboss.web</computeroutput> service:
+ It is common for web services to run on port 80. By default, JBoss EAP and JBoss
AS use port 8080. If you can not use <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=UsingPortForwardingWit...
forwarding</ulink>, it is recommended to change the port JBoss EAP or JBoss AS
listens on. To change the default port, open the
<filename>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml</filename>
file, and edit the <computeroutput>Connector port</computeroutput> value for
the <computeroutput>jboss.web</computeroutput> service; however, this
configuration only applies to Tomcat:
</para>
<para>
<screen>
@@ -28,10 +28,10 @@
</screen>
</para>
<para>
- This example changes the default port to port 8088. The JBoss EAP or JBoss AS server
must be restarted before the new port settings will take affect.
+ This example changes the default port to port 8088. The JBoss EAP or JBoss AS server
must be restarted before the new port settings take affect.
</para>
<para>
- The default SSL port is 8843. To enable HTTPS support, refer to the <ulink
url="http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch9.chapt.htm...
AS Guide</ulink>. For further information, please see the <ulink
url="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html">... SSL
configuration how-to</ulink>.
+ The default SSL port is 8843. To enable HTTPS support, refer to the <ulink
url="http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch9.chapt.htm...
AS Guide</ulink>. For further information, refer to <ulink
url="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html">... SSL
configuration how-to</ulink>.
</para>
<para>
Please refer to <xref linkend="wsrp-ports"/> to update the WSRP service
after having changed the port.
@@ -40,7 +40,7 @@
<warning>
<title>Root User Privileges</title>
<para>
- Linux systems require root user privileges to run a service on a port less than
1024. Starting JBoss EAP or JBoss AS on port 80 as a non-privileged user will not work.
Running JBoss EAP or JBoss AS as the root user could lead to security breaches.
+ <trademark class="registered">Linux</trademark> systems
require root user privileges to run a service on a port less than 1024. Starting JBoss EAP
or JBoss AS on port 80 as a non-privileged user will not work. Running JBoss EAP or JBoss
AS as the root user could lead to security breaches.
</para>
</warning>
</para>
@@ -92,7 +92,7 @@
<orderedlist>
<listitem>
<para>
- Change into the directory where the <filename>JBoss Portal Source
Code</filename> zip file was extracted to, or where the source from SVN was checked
out to. Copy the <filename>build/etc/local.properties-example</filename> file
and save it as <filename>build/local.properties</filename>.
+ Change into the directory where the <filename>JBoss Portal Source
Code</filename> ZIP file was extracted to, or where the source from SVN was checked
out to. Copy the <filename>build/etc/local.properties-example</filename> file
and save it as <filename>build/local.properties</filename>.
</para>
</listitem>
<listitem>
@@ -117,13 +117,14 @@
</listitem>
<listitem>
<para>
- Re-build and re-deploy JBoss Portal. See <xref
linkend="install_source"/> for build instructions.
+ Rebuild and redeploy JBoss Portal. Refer to <xref
linkend="install_source"/> for build instructions.
</para>
</listitem>
</orderedlist>
</para>
<para>
<note>
+ <title>Changing the context-root</title>
<para>
By default, Tomcat holds on to the root context,
<emphasis>/</emphasis>. You may need to remove the
<filename>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROOT.war/</filename>
directory,
or add a <filename>jboss-web.xml</filename> file, which declares
another
@@ -142,7 +143,7 @@
<sect1 id="configuration-hibdialect">
<title>Forcing the Database Dialect</title>
<para>
- This sections describes how to override the Database (DB) dialect settings. Under
most circumstances, the auto-detect feature will work. If the Hibernate dialect is not
working correctly, override the default behavior by following the instructions in this
section.
+ This sections describes how to override the Database (DB) dialect settings. Under
most circumstances, the auto-detect feature works. If the Hibernate dialect is not working
correctly, override the default behavior by following the instructions in this section.
</para>
<sect2>
<title>Database Dialect Settings for JBoss Portal</title>
@@ -159,7 +160,7 @@
]]></screen>
</para>
<para>
- Note: this example is for a PostgreSQL database. If you use another database, you will
need to modify
<computeroutput>org.hibernate.dialect.PostgreSQLDialect</computeroutput> to
reflect the correct database. For a list of supported dialects, refer to the <ulink
url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-...
list on the Hibernate website</ulink>.
+ Note: this example is for a PostgreSQL database. If you use another database, you need
to modify
<computeroutput>org.hibernate.dialect.PostgreSQLDialect</computeroutput> to
reflect the correct database. For a list of supported dialects, refer to the <ulink
url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-...
list on the Hibernate website</ulink>.
</para>
</sect2>
<sect2>
@@ -188,14 +189,14 @@
</orderedlist>
</para>
<para>
- Note: this example is for a PostgreSQL database. If you use another database, you will
need to modify
<computeroutput>org.hibernate.dialect.PostgreSQLDialect</computeroutput> to
reflect the correct database. For a list of supported dialects, refer to the <ulink
url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-...
list on the Hibernate website</ulink>.
+ Note: this example is for a PostgreSQL database. If you use another database, you need
to modify
<computeroutput>org.hibernate.dialect.PostgreSQLDialect</computeroutput> to
reflect the correct database. For a list of supported dialects, refer to the <ulink
url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-...
list on the Hibernate website</ulink>.
</para>
</sect2>
</sect1>
<sect1 id="emailConfiguration">
<title>Setting up the Email Service</title>
<para>
- If you have a standard setup and a mail server installed, the email service should
work without any extra configuration. Most Linux distributions have a mail server
installed by default. The email service, for example, can be used to verify a user's
email address when a user subscribes, or for CMS workflow notifications.
+ If you have a standard setup and a mail server installed, the email service should
work without any extra configuration. Most <trademark
class="registered">Linux</trademark> distributions have a mail server
installed by default. The email service, for example, can be used to verify a user's
email address when a user subscribes, or for CMS workflow notifications.
</para>
<para>
The email service is configured using the
<filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml</filename>
file. The following is an example of the section which is used to configure the email
service:
@@ -251,29 +252,29 @@
</sect1>
<sect1>
<title>Configuring proxy settings</title>
- <para>There are a couple of scenarios where you will need your proxy to be
correctly defined at the JVM
+ <para>There are a couple of scenarios where you need your proxy to be
correctly defined at the JVM
level so that you can access documents from Internet. It could be to get the
thirdparty libraries if you
decided to build JBoss Portal from the sources, to access RSS feeds or weather
information in the samples
portlet we provide or for your own needs.</para>
- <para>To set up the proxy settings you will need to know the proxy host and
the port to use then
- add them when starting java.</para>
+ <para>To configure the proxy settings, you need to know the proxy host and
the port to use. Then,
+ add them when starting <trademark
class="trade">Java</trademark>.</para>
<para>Usually setting up JAVA_OPTS environment variable to
<literal>-Dhttp.proxyHost=YOUR_PROXY_HOST
-Dhttp.proxyPort=YOUR_PROXY_PORT</literal>
is enough.</para>
</sect1>
<sect1>
<title>Disabling Dynamic Proxy Un-wrapping</title>
- <para>JBoss Portal uses the JBoss Microkernel for the service infrastructure.
The JBoss Microkernel provides injection of services into other services, otherwise known
as wiring. Due to the Microkernel being JMX based, it is only possible to inject dynamic
proxies that talk to the MBeanServer. The overhead at runtime is minimal since the
Microkernel implementation is highly optimized; however, when it is used with Java 5, a
noticeable bottleneck occurs due to the fact that the implementation of the JMX API
classes, <emphasis>javax.management.*</emphasis>, provided by the Java
Platform, perform synchronization. This does not occur under JDK 1.4, since those classes
are implemented by JBoss MX.
+ <para>JBoss Portal uses the JBoss Microkernel for the service infrastructure.
The JBoss Microkernel provides injection of services into other services, otherwise known
as wiring. Due to the Microkernel being JMX based, it is only possible to inject dynamic
proxies that talk to the MBeanServer. The overhead at runtime is minimal since the
Microkernel implementation is highly optimized; however, when it is used with
<trademark class="trade">Java</trademark> 5, a noticeable bottleneck
occurs due to the fact that the implementation of the JMX API classes,
<emphasis>javax.management.*</emphasis>, provided by the Java Platform,
perform synchronization. This does not occur under JDK 1.4, since those classes are
implemented by JBoss MX.
</para>
<para>
- JBoss Portal services use a special kind of Model MBean called
<emphasis>JBossServiceModelMBean</emphasis>, which allows the un-wrapping of
injected dynamic proxies, and replaces them with plain old java object (POJO) services.
This removes the bottleneck when using Java 5, and also provides a performance boost on
JDK 1.4. By default this feature is enabled, but it is possible to disable. To do this on
Linux systems, change into the <filename>$JBOSS_HOME/bin/</filename> directory
and run the following command:
+ JBoss Portal services use a special kind of Model MBean called
<emphasis>JBossServiceModelMBean</emphasis>, which allows the un-wrapping of
injected dynamic proxies, and replaces them with Plain Old Java Object (POJO) services.
This removes the bottleneck when using Java 5, and also provides a performance boost on
JDK 1.4. By default this feature is enabled, but it is possible to disable. To do this on
<trademark class="registered">Linux</trademark> systems, change into
the <filename>$JBOSS_HOME/bin/</filename> directory and run the following
command:
</para>
<para>
<screen>
-./run.sh -Dportal.kernel.no_proxies=false
+sh run.sh -Dportal.kernel.no_proxies=false
</screen>
</para>
<para>
- On Microsoft Windows systems, run the following command:
+ On <trademark class="registered">Windows</trademark>, run the
following command:
</para>
<para>
<screen>
Modified:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/errorhandling.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/errorhandling.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/errorhandling.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -7,133 +7,204 @@
<email>julien.viet(a)jboss.com</email>
</author>
</chapterinfo>
- <title>Error handling configuration</title>
- <para>JBoss Portal's request pipeline allows for fine-grained, dynamic
configuration of how Portal will behave when
- an error occurs at runtime.</para>
+ <title>Error Handling Configuration</title>
+ <para>
+ The JBoss Portal request pipeline allows fine-grained, dynamic configuration of how
JBoss Portal behaves when errors occur during runtime.
+ </para>
<sect1>
- <title>Error types</title>
- <para>There are several kind of errors that can happen during a request:
+ <title>Error Types</title>
+ <para>There are several types of errors that can occur during a request:
<itemizedlist>
- <listitem>Access denied: the user does not have the security rights to
access a resource</listitem>
- <listitem>Error: an anticipated error as when a portlet throws an
exception</listitem>
- <listitem>Internal error: an unexpected error</listitem>
- <listitem>Resource not found: a resource is not found</listitem>
- <listitem>Resource not available: a resource is found but is not
serviceable</listitem>
+ <listitem>
+ <para>
+ <emphasis>Access denied</emphasis>: the user does not have the
security permissions to access the resource.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Error</emphasis>: an anticipated error, such as when a
portlet throws an exception.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Internal error</emphasis>: an unexpected error.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Resource not found</emphasis>: the resource was not found.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Resource unavailable</emphasis>: the resource was found, but
was not serviceable.
+ </para>
+ </listitem>
</itemizedlist>
</para>
</sect1>
<sect1>
- <title>Control policies</title>
- <para>When an error occurs, the request control flow changes according to the
configuration. The configuration
- is also called <emphasis>control policy</emphasis>.</para>
+ <title>Control Policies</title>
+ <para>If an error occurs, the request control-flow changes according to the
configuration. This configuration is known as the <emphasis>control
policy</emphasis>.
+ </para>
<sect2>
- <title>Policy delegation and cascading</title>
- <para>Whenever a control policy is invoked it is possible to change the
response sent
- by the control flow. If the control policy ignores the error then the next
policy will handle the error
- at this turn. However if the control policy decides to provide a new response
then the next policy
- will not be invoked since the new response will not be of type error. For
instance, if a portlet part of a
- page produces an exception, the following reactions are possible:
+ <title>Policy Delegation and Cascading</title>
+ <para>
+ When a control policy is invoked, the response sent by the control flow can be
changed. If the control policy ignores the error, the error is handled by the next policy.
If the control policy provides a new response, the next policy is not invoked, since the
new response will not be an error.
+ </para>
+ <para>
+ If a portlet in a page produces an exception, the following reactions are possible:
+ </para>
+ <para>
<itemizedlist>
- <listitem>The error is displayed in the window</listitem>
- <listitem>The window is removed from the
aggregation</listitem>
- <listitem>An portal error page is displayed</listitem>
- <listitem>An HTTP 500 error response is sent to the
browser</listitem>
+ <listitem>
+ <para>
+ the error is displayed in the window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the window is removed from the aggregation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a portal error page is displayed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a HTTP 500 error response is sent to the Web browser.
+ </para>
+ </listitem>
</itemizedlist>
</para>
</sect2>
<sect2>
- <title>Default policy</title>
- <para>The default policy applies when errors are not handled at other
level. By default errors are translated
+ <title>Default Policy</title>
+ <para>The default policy applies when errors are not handled by another
level. By default, errors are translated
into the most appropriate HTTP response:
+ </para>
+ <para>
<itemizedlist>
- <listitem>Access denied: HTTP 403 Forbidden
response</listitem>
- <listitem>Error: HTTP 500 Internal Server Error
response</listitem>
- <listitem>Internal error: HTTP 500 Internal Server Error
response</listitem>
- <listitem>Resource not found: HTTP 404 Not Found
response</listitem>
- <listitem>Resource not available: HTTP 404 Not Found
response</listitem>
+ <listitem>
+ <para>
+ Access denied: <computeroutput>HTTP 403 Forbidden</computeroutput>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Error: <computeroutput>HTTP 500 Internal Server
Error</computeroutput>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Internal error: <computeroutput>HTTP 500 Internal Server
Error</computeroutput>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Resource not found: <computeroutput>HTTP 404 Not
Found</computeroutput>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Resource unavailable: <computeroutput>HTTP 404 Not
Found</computeroutput>
+ </para>
+ </listitem>
</itemizedlist>
</para>
</sect2>
<sect2>
- <title>Portal policy</title>
- <para>The portal error policy controls the response that will be sent to
the browser when an error occurs. There is a default
- configuration and it is reconfigurable per portal. Whenever an error occurs, the
policy can either handle a redirect to
- a JSP page or ignore the error. If the error is ignored it will be handled by
the default policy, otherwise a JSP page
- will be invoked with appropriate request attributes to allow page
customization.</para>
+ <title>Portal Policy</title>
+ <para>
+ The portal error-policy controls the response sent to the Web browser when an error
occurs. A default error policy exists, which can be configured per portal. If an error
occurs, the policy can either handle a redirect to a JSP page, or ignore it. If the error
is ignored, it is handled by the default policy, otherwise a JSP page is invoked with the
appropriate request attributes, allowing page customization.
+ </para>
</sect2>
<sect2>
- <title>Page policy</title>
- <para>The window error policy controls how the page reacts to aggregation
errors. Indeed the page is most of the
- time an aggregation of several portlet windows and the action to take when an
error occurs is different than
- the other policies. Whenever an error occurs, the policy can either handle it
or ignore it. If the error is
- ignored then it will be treated by the portal policy. The different actions
that are possible upon an error are:
+ <title>Page Policy</title>
+ <para>
+ The window error-policy controls how pages react to aggregation errors. Most of the
time pages are an aggregation of several portlet windows, and the action to take when an
error occurs differs from other policies. When an error occurs, the policy can either
handle it, or ignore it. If the error is ignored, it is handled by the portal policy.
Possible actions taken after such errors are:
+ </para>
+ <para>
<itemizedlist>
- <listitem>Remove the window from the aggregation</listitem>
- <listitem>Replace the markup of the window by a redirection to a JSP
page</listitem>
+ <listitem>
+ <para>
+ remove the window from the aggregation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ replace the markup of the window using a redirection to a JSP page.
+ </para>
+ </listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
<sect1>
- <title>Configuration using the XML descriptors</title>
- <para>Since the different policies are configured using portal object
properties it is possible to configure
- the error handling policy in the XML descriptors of those objects (the
<literal>*-object.xml</literal> files for
- your Portal deployment).</para>
+ <title>Configuration using XML Descriptors</title>
+ <para>
+ Different policies are configured using portal object properties, allowing the
error-handling policy for objects to be configured in XML descriptors -- the
<filename>*-object.xml</filename> files -- for a portal deployment.
+ </para>
<sect2>
- <title>Portal policy properties</title>
- <para>A set of properties configure the the behavior of the portal policy.
Those properties will only be
- taken in account for objects of type portal.</para>
+ <title>Portal Policy Properties</title>
<para>
+ A set of properties configure the the behavior of the portal policy. These properties
are only taken into account for objects that use the
<emphasis>portal</emphasis> type. The following table represents possible
portal-policy properties:
+ </para>
+ <para>
<table frame="all">
- <title>Portal policy properties</title>
<tgroup cols="3" align="left" colsep="1"
rowset="1">
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<thead>
<row>
- <entry align="center">Property
name</entry>
+ <entry align="center">Property
Name</entry>
<entry align="center">Description</entry>
- <entry align="center">Possible
values</entry>
+ <entry align="center">Possible
Values</entry>
</row>
</thead>
<tbody>
<row>
- <entry
align="center">control.portal.access_denied</entry>
- <entry align="center">On access
denied</entry>
- <entry
align="center"><emphasis>ignore</emphasis> and
<emphasis>jsp</emphasis></entry>
- </row>
+ <entry
align="center"><computeroutput>control.portal.access_denied</computeroutput></entry>
+ <entry align="center">when access is
denied</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput> and
<computeroutput>jsp</computeroutput></entry>
+ </row>
<row>
- <entry
align="center">control.portal.unavailable</entry>
- <entry align="center">On resource not
available</entry>
- <entry
align="center"><emphasis>ignore</emphasis> and
<emphasis>jsp</emphasis></entry>
+ <entry
align="center"><computeroutput>control.portal.unavailable</computeroutput></entry>
+ <entry align="center">when a resource is
unavailable</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput> and
<computeroutput>jsp</computeroutput></entry>
</row>
<row>
- <entry
align="center">control.portal.error</entry>
- <entry align="center">On an expected
error</entry>
- <entry
align="center"><emphasis>ignore</emphasis> and
<emphasis>jsp</emphasis></entry>
+ <entry
align="center"><computeroutput>control.portal.error</computeroutput></entry>
+ <entry align="center">when an expected error
occurs</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput> and
<computeroutput>jsp</computeroutput></entry>
</row>
<row>
- <entry
align="center">control.portal.internal_error</entry>
- <entry align="center">On an unexpected
error</entry>
- <entry
align="center"><emphasis>ignore</emphasis> and
<emphasis>jsp</emphasis></entry>
+ <entry
align="center"><computeroutput>control.portal.internal_error</computeroutput></entry>
+ <entry align="center">when an unexpected error
occurs</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput> and
<computeroutput>jsp</computeroutput></entry>
</row>
<row>
- <entry
align="center">control.portal.not_found</entry>
- <entry align="center">On resource not
found</entry>
- <entry
align="center"><emphasis>ignore</emphasis> and
<emphasis>jsp</emphasis></entry>
+ <entry
align="center"><computeroutput>control.portal.not_found</computeroutput></entry>
+ <entry align="center">when a resource is not
found</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput> and
<computeroutput>jsp</computeroutput></entry>
</row>
<row>
- <entry
align="center">control.portal.resource_uri</entry>
- <entry align="center">The path of the JSP used
for redirections</entry>
- <entry align="center">A valid path to a JSP
located in the portal-core.war file</entry>
+ <entry
align="center"><computeroutput>control.portal.resource_uri</computeroutput></entry>
+ <entry align="center">the path of the JSP used
for redirections</entry>
+ <entry align="center">a valid path to a JSP
located in the <filename>portal-core.war/</filename> directory</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
- <para>An example of portal configuration:
- <programlisting><![CDATA[
+ <para>
+ The following portal configuration details the use of portal-policy properties:
+ </para>
+ <para>
+<programlisting><![CDATA[
<portal>
<portal-name>MyPortal</portal-name>
...
@@ -170,12 +241,12 @@
</para>
</sect2>
<sect2>
- <title>Page policy properties</title>
- <para>A set of properties configure the the behavior of the page policy.
Those properties will only be
- taken in account for objects of type portal and page.</para>
+ <title>Page Policy Properties</title>
+ <para>
+ A set of properties configure the the behavior of the page policy. These properties
are only taken into account for objects that use the
<emphasis>portal</emphasis> type. The following table represents possible
page-policy properties:
+ </para>
<para>
<table frame="all">
- <title>Page policy properties</title>
<tgroup cols="3" align="left" colsep="1"
rowset="1">
<colspec colname='c1'/>
<colspec colname='c2'/>
@@ -189,41 +260,44 @@
</thead>
<tbody>
<row>
- <entry
align="center">control.page.access_denied</entry>
- <entry align="center">On access
denied</entry>
- <entry
align="center"><emphasis>ignore</emphasis>,
<emphasis>jsp</emphasis> and
<emphasis>hide</emphasis></entry>
+ <entry
align="center"><computeroutput>control.page.access_denied</computeroutput></entry>
+ <entry align="center">when access is
denied</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput>,
<computeroutput>jsp</computeroutput> and
<computeroutput>hide</computeroutput></entry>
</row>
<row>
- <entry
align="center">control.page.unavailable</entry>
- <entry align="center">On resource not
available</entry>
- <entry
align="center"><emphasis>ignore</emphasis>,
<emphasis>jsp</emphasis> and
<emphasis>hide</emphasis></entry>
+ <entry
align="center"><computeroutput>control.page.unavailable</computeroutput></entry>
+ <entry align="center">when a resource is
unavailable</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput>,
<computeroutput>jsp</computeroutput> and
<computeroutput>hide</computeroutput></entry>
</row>
<row>
- <entry
align="center">control.page.error</entry>
- <entry align="center">On an expected
error</entry>
- <entry
align="center"><emphasis>ignore</emphasis>,
<emphasis>jsp</emphasis> and
<emphasis>hide</emphasis></entry>
+ <entry
align="center"><computeroutput>control.page.error</computeroutput></entry>
+ <entry align="center">when an expected error
occurs</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput>,
<computeroutput>jsp</computeroutput> and
<computeroutput>hide</computeroutput></entry>
</row>
<row>
- <entry
align="center">control.page.internal_error</entry>
- <entry align="center">On an unexpected
error</entry>
- <entry
align="center"><emphasis>ignore</emphasis>,
<emphasis>jsp</emphasis> and
<emphasis>hide</emphasis></entry>
+ <entry
align="center"><computeroutput>control.page.internal_error</computeroutput></entry>
+ <entry align="center">when an unexpected error
occurs</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput>,
<computeroutput>jsp</computeroutput> and
<computeroutput>hide</computeroutput></entry>
</row>
<row>
- <entry
align="center">control.page.not_found</entry>
- <entry align="center">On resource not
found</entry>
- <entry
align="center"><emphasis>ignore</emphasis>,
<emphasis>jsp</emphasis> and
<emphasis>hide</emphasis></entry>
+ <entry
align="center"><computeroutput>control.page.not_found</computeroutput></entry>
+ <entry align="center">when a resource is not
found</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput>,
<computeroutput>jsp</computeroutput> and
<computeroutput>hide</computeroutput></entry>
</row>
<row>
- <entry
align="center">control.page.resource_uri</entry>
- <entry align="center">The path of the JSP used
for redirections</entry>
- <entry
align="center"><emphasis>ignore</emphasis>,
<emphasis>jsp</emphasis> and
<emphasis>hide</emphasis></entry>
+ <entry
align="center"><computeroutput>control.page.resource_uri</computeroutput></entry>
+ <entry align="center">the path of the JSP used for
redirections</entry>
+ <entry
align="center"><computeroutput>ignore</computeroutput>,
<computeroutput>jsp</computeroutput> and
<computeroutput>hide</computeroutput></entry>
</row>
</tbody>
</tgroup>
</table>
- </para>
- <para>An example of page configuration:
- <programlisting><![CDATA[
+ </para>
+ <para>
+ The following page configuration details the use of page-policy properties:
+ </para>
+ <para>
+<programlisting><![CDATA[
<page>
<page-name>MyPortal</page-name>
...
@@ -258,62 +332,99 @@
</page>
]]></programlisting>
</para>
- <note>You can configure the page properties also on objects of type
portal, in that case they will be inherited by the pages
- which are located in the portal.</note>
- </sect2>
+ <para>
+ <note>
+ <title>Page property inheritance for objects</title>
+ <para>
+ When page properties are configured for objects that use the
<emphasis>portal</emphasis> type, the properties are inherited by pages in
that portal.
+ </para>
+ </note>
+ </para>
+</sect2>
</sect1>
<sect1>
- <title>Handling errors with JSP</title>
- <para>As described above it is possible to redirect error handling to a
JavaServer Page. Two pages can be created
- to handle errors at portal and page level. Portal level error handling requires a
page that will produce a full
- page and the page level error handling requires a page that will produce markup for
a window only. When the page
- is invoked a set of request attributes will be passed.</para>
+ <title>Handling Errors with <trademark
class="trade">JavaServer</trademark> Pages (<trademark
class="trade">JSP</trademark>)</title>
<para>
+ As described in previous sections, error handling can be redirected to a
<trademark class="trade">JSP</trademark>. Two pages can be created
to handle errors, one for the portal level, and the other for the page level. Portal level
error-handling requires a page that produces a full page, and page-level handling requires
a page that produces markup, but only for a window. When the page is invoked, a set of
request attributes are passed. The following table represents possible request
attributes:
+ </para>
+ <para>
<table frame="all">
- <title>Request attributes</title>
<tgroup cols="3" align="left" colsep="1"
rowset="1">
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<thead>
<row>
- <entry align="center">Attribute name</entry>
+ <entry align="center">Attribute Name</entry>
<entry align="center">Attribute
Description</entry>
- <entry align="center">Attribute value</entry>
+ <entry align="center">Attribute Value</entry>
</row>
</thead>
<tbody>
<row>
- <entry
align="center">org.jboss.portal.control.ERROR_TYPE</entry>
- <entry align="center">The error type</entry>
- <entry align="center">The possible values are
<emphasis>ACCESS_DENIED</emphasis>,
<emphasis>UNAVAILABLE</emphasis>, <emphasis>ERROR</emphasis>,
<emphasis>INTERNAL_ERROR</emphasis>,
<emphasis>NOT_FOUND</emphasis></entry>
+ <entry
align="center"><computeroutput>org.jboss.portal.control.ERROR_TYPE</computeroutput></entry>
+ <entry align="center">the error type</entry>
+ <entry align="center">possible values are
<computeroutput>ACCESS_DENIED</computeroutput>,
<computeroutput>UNAVAILABLE</computeroutput>,
<computeroutput>ERROR</computeroutput>,
<computeroutput>INTERNAL_ERROR</computeroutput>, and
<computeroutput>NOT_FOUND</computeroutput></entry>
</row>
<row>
- <entry
align="center">org.jboss.portal.control.CAUSE</entry>
- <entry align="center">The throwable cause that can
be null</entry>
- <entry align="center">The object is a subclass of
java.lang.Throwable</entry>
+ <entry
align="center"><computeroutput>org.jboss.portal.control.CAUSE</computeroutput></entry>
+ <entry align="center">a cause which is thrown, that
can be null</entry>
+ <entry align="center">the object is a subclass of
<computeroutput>java.lang.Throwable</computeroutput></entry>
</row>
<row>
- <entry
align="center">org.jboss.portal.control.MESSAGE</entry>
- <entry align="center">An error message that can be
null</entry>
- <entry align="center">Text</entry>
+ <entry
align="center"><computeroutput>org.jboss.portal.control.MESSAGE</computeroutput></entry>
+ <entry align="center">an error message that can be
null</entry>
+ <entry align="center">text</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
- <note>The JavaServer Pages have to be located in the
jboss-portal.sar/portal-core.war Web Application.</note>
+ <para>
+ <note>
+ <title><trademark class="trade">JSP</trademark>
Location</title>
+ The JavaServer Pages must be located in the
<filename>jboss-portal.sar/portal-core.war/</filename> web application.
+ </note>
+ </para>
</sect1>
<sect1>
<title>Configuration using the Portal Management Application</title>
<para>
- The Error handling policy can also be configured via the portal management
application. The functionality is
- available as part of the properties for each configuration level where it makes
sense: you can specify the
- default error handling policy (at the root of the portal object hierachy), for
each portal or each page by
- clicking on the Properties link on each of these pages. You can also specify how
dashboards should behave with
- respect to error handling by clicking on the Dashboards tab of the Portal
management application.
+ The error handling policy can be configured via the portal management
application. To access the portal management application:
</para>
- <para>Screenshot:
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Use a Web browser to navigate to <ulink
url="http://localhost:8080/portal" />.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Click the <guibutton>Login</guibutton> button on the top right-hand
of the welcome page, and log in as the <option>admin</option> user.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Click the <guibutton>Admin</guibutton> button on the top right-hand
of the welcome page. Four tabs will appear on the left-hand side of the page. Click on the
<guibutton>Admin</guibutton> tab to open the portal management application.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ The functionality is available as part of the properties for each configuration
level. You can specify the default error handling policy (at the root of the portal object
hierarchy) for each portal, or each page, by clicking on the
<guibutton>Properties</guibutton> button for each page or portal:
+ </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/errorhandling/errorHandling_management.png" />
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>
+ As well, you can specify how dashboards should behave with respect to error
handling, by clicking on the <guibutton>Dashboards</guibutton> tab of the
portal management application:
+ </para>
+ <para>
<imageobject>
<imagedata fileref="images/errorhandling/errorHandlingUI.png"
format="png" align="center"/>
</imageobject>
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/identity.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/identity.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/identity.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -146,36 +146,6 @@
throws IdentityException;
/** Get all the roles */
-Set findRoles()
- throws IdentityException;/** Retrieves a role by its name*/
-Role findRoleByName(String name)
- throws IdentityException, IllegalArgumentException;
-
-/**Retrieve a collection of role from the role names.*/
-Set findRolesByNames(String[] names)
- throws IdentityException, IllegalArgumentException;
-
-/** Retrieves a role by its id.*/
-Role findRoleById(Object id)
- throws IdentityException, IllegalArgumentException;
-
-/** Retrieves a role by its id.*/
-Role findRoleById(String id)
- throws IdentityException, IllegalArgumentException;
-
-/** Create a new role with the specified name.*/
-Role createRole(String name, String displayName)
- throws IdentityException, IllegalArgumentException;
-
-/** Remove a role.*/
-void removeRole(Object id)
- throws IdentityException, IllegalArgumentException;
-
-/** Returns the number of roles. */
-int getRolesCount()
- throws IdentityException;
-
-/** Get all the roles */
Set findRoles() throws IdentityException;
]]></programlisting>
</listitem>
@@ -416,8 +386,8 @@
<sect1>
<title>Identity configuration</title>
<para>In order to understand identity configuration you need to understand
its architecture.
- Different identity services like UserModule, RoleModule and etc are just plain
java classes that are instantiated and exposed
- by the portal. So an *example* of UserModule service could be a plain java bean
object that would be:
+ Different identity services like UserModule, RoleModule and etc are just plain
<trademark class="trade">Java</trademark> classes that are
instantiated and exposed
+ by the portal. So an *example* of UserModule service could be a plain Java bean
object that would be:
<itemizedlist>
<listitem><emphasis
role="bold">Instantiated</emphasis> using reflection</listitem>
<listitem><emphasis
role="bold">Initialized/Started</emphasis> by invoking some
methods</listitem>
@@ -426,7 +396,7 @@
<listitem><emphasis
role="bold">Managed</emphasis> in the matter of lifecycle - so
it'll be stopped and unregistered during
portal shutdown</listitem>
</itemizedlist>
- As you see from this point of view, configuration just specifies what java class
will be used and how it should be used by portal as a service.
+ As you see from this point of view, configuration just specifies what Java class
will be used and how it should be used by portal as a service.
<note>We use JBoss Microcontainer internally to manage the sub system made
of those components so if you are interested in implementing
custom services - look on the methods that are used by this
framework.</note>
</para>
@@ -596,7 +566,7 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">class</emphasis> - java
class that will be use to instantiate the module.
+ <emphasis role="bold">class</emphasis> -
<trademark class="trade">Java</trademark> class that will be use to
instantiate the module.
</para>
</listitem>
<listitem>
@@ -784,7 +754,7 @@
<emphasis role="bold">name</emphasis> - property
name. This value will be used to refer to the property in
<emphasis>UserProfileModule</emphasis>
</listitem>
<listitem>
- <emphasis role="bold">type</emphasis> - java type of
property. This type will be checked when in
<emphasis>UserProfileModule</emphasis>
+ <emphasis role="bold">type</emphasis> -
<trademark class="trade">Java</trademark> type of property. This
type will be checked when in <emphasis>UserProfileModule</emphasis>
methods invocation.
</listitem>
<listitem>
Modified:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/identityportlets.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/identityportlets.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/identityportlets.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -818,7 +818,7 @@
<title>Enabling the Identity Portlets</title>
<para>
When migrating from former versions of JBoss Portal the Identity User Portlets
won't be displayed by default,
- but Windows can be created on basis of the existing Portlet Instances which are
deployed by default. (The instances
+ but windows can be created on basis of the existing Portlet Instances which are
deployed by default. (The instances
names being <literal>IdentityUserPortletInstance</literal> and
<literal>IdentityAdminPortletInstance</literal>.)
</para>
</sect2>
Modified:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/installation.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/installation.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/installation.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -2,7 +2,7 @@
<chapter id="installation">
<title>Installation</title>
<para>Depending on your needs, there are several different methods to install
JBoss Portal. Pre-configured clustered versions (<computeroutput>JBoss Portal Binary
(Clustered)</computeroutput>) are available from the
- <ulink
url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu...
Portal Downloads</ulink> page. Clustered versions of JBoss Portal must be deployed
in the <filename>JBOSS_INSTALLATION_DIRECTORY/server/all/deploy/</filename>
directory. All JBoss AS instances must reference the same datasource. See <xref
linkend="install_source_env"/> for details on how to configure JBoss Portal
for clustering.
+ <ulink
url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu...
Portal Downloads</ulink> page. Clustered versions of JBoss Portal must be deployed
in the <filename>JBOSS_INSTALLATION_DIRECTORY/server/all/deploy/</filename>
directory. All JBoss AS instances must reference the same datasource. Refer to <xref
linkend="install_source_env"/> for details on how to configure JBoss Portal
for clustering.
</para>
<para>
An environment variable, <computeroutput>JBOSS_HOME</computeroutput>, is
configured in <xref linkend="install_source_env"/>. References to
<computeroutput>$JBOSS_HOME</computeroutput> assume this to be your
<replaceable>JBOSS_INSTALLATION_DIRECTORY</replaceable>.
@@ -20,12 +20,12 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">Extract the bundle:</emphasis>
extract the zip archive. It does not matter which directory is used. On Microsoft Windows,
the recommended directory is
<filename>C:\jboss-<replaceable>version-number</replaceable></filename>.
+ <emphasis role="bold">Extract the bundle:</emphasis>
extract the ZIP archive. It does not matter which directory is used. On <trademark
class="registered">Windows</trademark>, the recommended directory is
<filename>C:\jboss-<replaceable>version-number</replaceable></filename>.
</para>
</listitem>
<listitem>
<para>
- <emphasis role="bold">Start the server:</emphasis> change
into the <filename>JBOSS_PORTAL_INSTALLATION_DIRECTORY/bin/</filename>
directory. On Microsoft Windows, execute <command>run.bat</command>. On Linux,
run the <command>./run.sh</command> command. To specify a configuration to
use, for example, the default configuration, append the <command> -c
default</command> option to the <command>run.bat</command> or
<command>./run.sh</command> commands.
+ <emphasis role="bold">Start the server:</emphasis> change
into the <filename>JBOSS_PORTAL_INSTALLATION_DIRECTORY/bin/</filename>
directory. On <trademark class="registered">Windows</trademark>,
execute <command>run.bat</command>. On <trademark
class="registered">Linux</trademark>, run the <command>sh
run.sh</command> command. To specify a configuration to use, for example, the
default configuration, append the <command> -c default</command> option to the
<command>run.bat</command> or <command>sh run.sh</command>
commands.
</para>
</listitem>
<listitem>
@@ -62,7 +62,7 @@
<sect3 id="install_binarydownload">
<title>Getting the Binary</title>
<para>
- The binary download is available from the <ulink
url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu...
Portal Downloads</ulink> page. Look for the <computeroutput>JBoss Portal
Binary</computeroutput> package. Once the binary zip file has been downloaded and
extracted, the folder hierarchy will look similar to the following:
+ The binary download is available from the <ulink
url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu...
Portal Downloads</ulink> page. Look for the <computeroutput>JBoss Portal
Binary</computeroutput> package. Once the binary ZIP file has been downloaded and
extracted, the folder hierarchy will look similar to the following:
</para>
<para>
<mediaobject>
@@ -72,24 +72,24 @@
</mediaobject>
</para>
<para>
- Files contained in this download will be used in later sections. Download and
extract the JBoss Portal binary zip file before proceeding.
+ Files contained in this download are used in later sections. Download and
extract the JBoss Portal binary ZIP file before proceeding.
</para>
</sect3>
<sect3>
<title>JBoss EAP and JBoss AS Setup</title>
- <para>Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS
installed. Customers who have access to the <ulink
url="https://support.redhat.com/portal/login.html">JBoss Customer Support
Portal (CSP)</ulink> should download and install JBoss EAP 4.2. Customers who do not
have access to the JBoss CSP are advised to use <ulink
url="http://labs.jboss.com/jbossas/downloads/">JBoss AS</ulink>. For
JBoss AS installation instructions, please refer to the <ulink
url="http://labs.jboss.com/jbossas/docs/index.html">JBoss AS Installation
Guide</ulink>.
+ <para>Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS
installed. Customers who have access to the <ulink
url="https://support.redhat.com/portal/login.html">JBoss Customer Support
Portal (CSP)</ulink> are advised to download and install JBoss EAP 4.3. Customers
who do not have access to the JBoss CSP are advised to use <ulink
url="http://labs.jboss.com/jbossas/downloads/">JBoss AS</ulink>. For
JBoss AS installation instructions, please refer to the <ulink
url="http://labs.jboss.com/jbossas/docs/index.html">JBoss AS Installation
Guide</ulink>.
</para>
<warning>
- <title>Use the JBoss EAP and JBoss AS zip file</title>
+ <title>Use the JBoss EAP and JBoss AS ZIP file</title>
<para>
- Only use the JBoss EAP and JBoss AS zip file versions. <emphasis
role="bold">DO NOT ATTEMPT to deploy JBoss Portal on the installer version of
JBoss EAP or JBoss AS.</emphasis>
+ Only use the JBoss EAP and JBoss AS ZIP file versions. <emphasis
role="bold">DO NOT ATTEMPT to deploy JBoss Portal on the installer version of
JBoss EAP or JBoss AS.</emphasis>
</para>
</warning>
</sect3>
<sect3>
<title>Database Setup</title>
<para>
- A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include an
embedded Hypersonic SQL database that JBoss Portal can use; however, this is only
recommended for developer use. The following databases are recommended for production use,
and have had test suites run against them: MySQL 4, MySQL 5, Microsoft SQL Server,
PostgreSQL 8, Oracle 9, and Oracle 10. JBoss Portal can use any database that is supported
by Hibernate.
+ A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include an
embedded Hypersonic SQL database that JBoss Portal can use; however, this is only
recommended for developer use. The following databases are recommended for production use,
and have had test suites run against them: <trademark
class="registered">MySQL</trademark> 4 and 5, <trademark
class="registered">Microsoft</trademark> <trademark
class="registered">SQL Server</trademark>, PostgreSQL 8, <trademark
class="registered">Oracle</trademark> Database 9, and <trademark
class="registered">Oracle</trademark> Database 10. JBoss Portal can use
any database that is supported by Hibernate.
</para>
<para>
To configure a database to use with JBoss Portal:
@@ -98,7 +98,7 @@
<orderedlist>
<listitem>
<para>
- <emphasis role="bold">Create a new database:</emphasis>
this guide assumes that the new database will be called
<emphasis>jbossportal</emphasis>.
+ <emphasis role="bold">Create a new database:</emphasis>
this guide assumes that the new database is called
<emphasis>jbossportal</emphasis>.
</para>
</listitem>
<listitem>
@@ -115,9 +115,9 @@
</para>
</sect3>
<sect3>
- <title>Datasource Configuration</title>
+ <title>Datasource Descriptors</title>
<para>
- The JBoss Portal binary download that was extracted in <xref
linkend="install_binarydownload"/>, contains pre-configured Datasource
descriptors for the more popular databases. Datasource descriptors are provided for the
MySQL 4, MySQL 5, PostgreSQL, Microsoft SQL Server, and Oracle databases, and can be found
in the <filename>setup</filename> subdirectory where the JBoss Portal binary
was extracted to:
+ The JBoss Portal binary download that was extracted in <xref
linkend="install_binarydownload"/>, contains pre-configured Datasource
descriptors for the more popular databases. Datasource descriptors are provided for the
<trademark class="registered">MySQL</trademark> 4 and 5, PostgreSQL,
<trademark class="registered">Microsoft</trademark> <trademark
class="registered">SQL Server</trademark>, and <trademark
class="registered">Oracle</trademark> databases, and can be found in
the <filename>setup</filename> subdirectory where the JBoss Portal binary was
extracted to:
</para>
<mediaobject>
<imageobject>
@@ -128,7 +128,7 @@
Copy the Datasource descriptor that matches your database into the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/</filename>
directory, where <replaceable>configuration</replaceable> is either all,
default, minimal or production. The production configuration only exists on JBoss EAP, and
not JBoss AS. For example, if you are using the all configuration, copy the Datasource
descriptor into the <filename>$JBOSS_HOME/server/all/deploy/</filename>
directory.
</para>
<para>
- After the Datasource descriptor has been copied into the
<filename>deploy</filename> directory, make sure the username, password,
connection-url, and driver-class are correct for your chosen database. Datasource
descriptor files can be deployed to test before being used in production. The following is
an example Datasource descriptor for the PostgreSQL database:
+ After the Datasource descriptor has been copied into the
<filename>deploy</filename> directory, make sure the
<computeroutput>user-name</computeroutput>,
<computeroutput>password</computeroutput>,
<computeroutput>connection-url</computeroutput>, and
<computeroutput>driver-class</computeroutput>, are correct for your chosen
database. Datasource descriptor files can be deployed to test before being used in
production. The following is an example Datasource descriptor for a PostgreSQL database:
</para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
@@ -143,7 +143,7 @@
</datasources>
]]></programlisting>
<para>
- For further details about Datasource descriptors, please refer to the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=CreateAJDBCDataSource&...
JDBC Datasource wiki page</ulink>.
+ For further details about Datasource descriptors, please refer to the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=CreateAJDBCDataSource&...
JDBC Datasource Wiki page</ulink>.
</para>
</sect3>
</sect2>
@@ -161,7 +161,7 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">Start the server:</emphasis> change into
the <filename>$JBOSS_HOME/bin/</filename> directory. On Microsoft Windows,
execute <command>run.bat</command>. On Linux, run the
<command>./run.sh</command> command. To specify a configuration to use, for
example, the default configuration, append the <command> -c default</command>
option to the <command>run.bat</command> or
<command>./run.sh</command> commands.
+ <emphasis role="bold">Start the server:</emphasis> change into
the <filename>$JBOSS_HOME/bin/</filename> directory. On <trademark
class="registered">Windows</trademark>, execute
<command>run.bat</command>. On <trademark
class="registered">Linux</trademark>, run the <command>sh
run.sh</command> command. To specify a configuration to use, for example, the
default configuration, append the <command> -c default</command> option to the
<command>run.bat</command> or <command>sh run.sh</command>
commands.
</para>
</listitem>
<listitem>
@@ -202,30 +202,16 @@
<title>Getting the Sources</title>
<para>
The JBoss Portal source files can be obtained from the
- <ulink
url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu...
Portal Downloads</ulink> page. The source files download uses a
<filename>JBoss Portal Source Code</filename> naming convention. As well, the
sources can be obtained from SVN:
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- the latest source files of the 2.6 branch:
<
emphasis>http://anonsvn.jboss.org/repos/portal/branches/JBoss_Portal_B...
- </para>
- </listitem>
- <listitem>
- <para>
- the latest sources:
<
emphasis>http://anonsvn.jboss.org/repos/portal/trunk/</emphasis>
- </para>
- </listitem>
- </itemizedlist>
+ <ulink
url="http://labs.jboss.com/portal/jbossportal/download/index.html&qu...
Portal Downloads</ulink> page. The source files download uses a
<filename>JBoss Portal Source Code</filename> naming convention. As well, the
sources can be obtained from SVN. The latest sources for the
2.6.<replaceable>x</replaceable> versions are located at <ulink
url="http://anonsvn.jboss.org/repos/portal/branches/JBoss_Portal_Bra...
/>.
</para>
<para>
- Several modules have been extracted from the JBoss Portal SVN repository. These
modules have a different lifecycle and a different version scheme. The following is a list
of modules used in JBoss Portal 2.6.4, and the locations of their source code:
+ Several modules have been extracted from the JBoss Portal SVN repository. These
modules have a different lifecycle and a different version scheme. The following is a list
of modules used in JBoss Portal 2.6.5, and the locations of their source code:
</para>
<para>
<itemizedlist>
<listitem>
<para>
- JBoss Portal Common 1.1.0:
<
emphasis>http://anonsvn.jboss.org/repos/portal/modules/common/tags/JBP...
+ JBoss Portal Common 1.1.1:
<
emphasis>http://anonsvn.jboss.org/repos/portal/modules/common/tags/JBP...
</para>
</listitem>
<listitem>
@@ -240,18 +226,18 @@
</listitem>
<listitem>
<para>
- JBoss Portal Portlet 1.0.2:
<
emphasis>http://anonsvn.jboss.org/repos/portal/modules/portlet/tags/JB...
+ JBoss Portal Portlet 1.0.3:
<
emphasis>http://anonsvn.jboss.org/repos/portal/modules/portlet/tags/JB...
</para>
</listitem>
<listitem>
<para>
- JBoss Portal Identity 1.0.2:
<
emphasis>http://anonsvn.jboss.org/repos/portal/modules/identity/tags/J...
+ JBoss Portal Identity 1.0.3:
<
emphasis>http://anonsvn.jboss.org/repos/portal/modules/identity/tags/J...
</para>
</listitem>
</itemizedlist>
</para>
<para>
- After checking out the source from SVN, or after extracting the <filename>JBoss
Portal Source Code</filename> zip file, a directory structure similar to the
following will be created:
+ After checking out the source from SVN, or after extracting the <filename>JBoss
Portal Source Code</filename> ZIP file, a directory structure similar to the
following will be created:
</para>
<mediaobject>
<imageobject>
@@ -259,19 +245,19 @@
</imageobject>
</mediaobject>
<para>
- If the source files were obtained from SVN, change into the
<filename>trunk/src/</filename> directory to see the directories from the
above image. As well, there will be an empty <filename>thirdparty</filename>
directory. This directory will contain files after building the JBoss Portal source code
(see <xref linkend="building_deploying_from_source" />). For more
information about the JBoss Portal SVN repository, and accessing different versions of the
JBoss Portal codebase, please visit the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=PortalSVNRepo">... Portal SVN
Repo</ulink> page on the JBoss Wiki.
+ If the source files were obtained from SVN, change into the
<filename>trunk/src/</filename> directory to see the directories from the
above image. As well, there is an empty <filename>thirdparty</filename>
directory. This directory contains files after building the JBoss Portal source code
(refer to <xref linkend="building_deploying_from_source" />). For more
information about the JBoss Portal SVN repository, and accessing different versions of the
JBoss Portal codebase, refer to the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=PortalSVNRepo">... Portal SVN
Repo</ulink> page on the JBoss Wiki.
</para>
</sect2>
<sect2>
<title>JBoss EAP and JBoss AS Setup</title>
<sect3>
<title>JBoss Application Server Setup</title>
- <para>Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS
installed. Customers who have access to the <ulink
url="https://support.redhat.com/portal/login.html">JBoss Customer Support
Portal (CSP)</ulink> should download and install JBoss EAP 4.2. Customers who do not
have access to the JBoss CSP are advised to use <ulink
url="http://labs.jboss.com/jbossas/downloads/">JBoss AS</ulink>. For
JBoss AS installation instructions, please refer to the <ulink
url="http://labs.jboss.com/jbossas/docs/index.html">JBoss AS Installation
Guide</ulink>.
+ <para>Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS
installed. Customers who have access to the <ulink
url="https://support.redhat.com/portal/login.html">JBoss Customer Support
Portal (CSP)</ulink> are advised to download and install JBoss EAP 4.3. Customers
who do not have access to the JBoss CSP are advised to use <ulink
url="http://labs.jboss.com/jbossas/downloads/">JBoss AS</ulink>. For
JBoss AS installation instructions, please refer to the <ulink
url="http://labs.jboss.com/jbossas/docs/index.html">JBoss AS Installation
Guide</ulink>.
</para>
<warning>
- <title>Use the JBoss EAP and JBoss AS zip file</title>
+ <title>Use the JBoss EAP and JBoss AS ZIP file</title>
<para>
- Only use the JBoss EAP and JBoss AS zip file versions. <emphasis
role="bold">DO NOT ATTEMPT to deploy JBoss Portal on the installer version of
JBoss EAP or JBoss AS.</emphasis> We are currently working on aligning the
Application installer with JBoss Portal.
+ Only use the JBoss EAP and JBoss AS ZIP file versions. <emphasis
role="bold">DO NOT ATTEMPT to deploy JBoss Portal on the installer version of
JBoss EAP or JBoss AS.</emphasis> We are currently working on aligning the
Application installer with JBoss Portal.
</para>
</warning>
</sect3>
@@ -279,7 +265,7 @@
<title>Operating System Environment Settings</title>
<para>For build targets to work, you must configure a
<filename>JBOSS_HOME</filename> environment variable. This environment
variable must point to the root directory of the JBoss EAP or JBoss AS installation
directory, which is the directory where the JBoss EAP or JBoss AS files were extracted
to.
</para>
- <para>When using Microsoft Windows, this is accomplished by going to
+ <para>On <trademark
class="registered">Windows</trademark>, this is accomplished by going
to
<emphasis>Start > Settings > Control Panel > System >
Advanced > Environment Variables</emphasis>. Under the
<emphasis>System Variables</emphasis>
section, click
@@ -292,13 +278,13 @@
</mediaobject>
</para>
<para>
- To configure the <filename>JBOSS_HOME</filename> environment variable
on Linux:
+ To configure the <filename>JBOSS_HOME</filename> environment variable
on <trademark class="registered">Linux</trademark>:
</para>
<para>
<orderedlist>
<listitem>
<para>
- Add the following line to the <filename>~/.bashrc</filename> file.
Note: this must be configured while logged in as the user who will run JBoss EAP or JBoss
AS:
+ Add the following line to the <filename>~/.bashrc</filename> file.
Note: this must be configured while logged in as the user who runs JBoss EAP or JBoss AS:
</para>
<para>
<screen>
@@ -329,26 +315,19 @@
<sect2 id="building_deploying_from_source">
<title>Building and Deploying from the Sources</title>
<para>
- During the first build, third-party libraries will be obtained from an online
- repository, so you must be connected to the Internet, and if you are behind a proxy
server, you need to define your proxy server address and proxy server port number. If you
are running Linux, add the following line to the
<filename>$JBOSS_HOME/bin/run.sh</filename> file:
+ During the first build, third-party libraries are obtained from an online
+ repository, so you must be connected to the Internet, and if you are behind a proxy
server, you need to define your proxy server address and proxy server port number. To
define a proxy server, add the following line to the
<filename>$JBOSS_HOME/bin/run.conf</filename> file:
</para>
<para>
<screen>
-JAVA_OPTS=-Dhttp.proxyHost=<<replaceable>proxy-hostname</replaceable>>
-Dhttp.proxyPort=<<replaceable>proxy-port</replaceable>>
+JAVA_OPTS=-Dhttp.proxyHost=<<replaceable>proxy-hostname</replaceable>>
+-Dhttp.proxyPort=<<replaceable>proxy-port</replaceable>>
</screen>
</para>
<para>
- Replace <replaceable>proxy-hostname</replaceable> with the proxy
server's hostname, and <replaceable>proxy-port</replaceable> with the
correct proxy server port number. If you are running Microsoft Windows, add the following
line to the <filename>$JBOSS_HOME/bin/run.bat</filename> file:
- </para>
- <para>
-<screen>
-set
JAVA_OPTS=-Dhttp.proxyHost=<<replaceable>proxy-hostname</replaceable>>
-Dhttp.proxyPort=<<replaceable>proxy-port</replaceable>>
-</screen>
- </para>
- <para>
Replace <replaceable>proxy-hostname</replaceable> with the proxy
server's hostname, and <replaceable>proxy-port</replaceable> with the
correct proxy server port number.
</para>
- <para>To build and deploy JBoss Portal from the sources, change into the
<filename>JBOSS_PORTAL_SOURCE_DIRECTORY/build/</filename> directory, where
<filename>JBOSS_PORTAL_SOURCE_DIRECTORY</filename> is the directory where the
JBoss Portal source code was downloaded to. Then, Microsoft Windows users need to run the
<command>build.bat deploy</command> command, and Linux users need to run the
<command>./build.sh deploy</command> command.
+ <para>To build and deploy JBoss Portal from the sources, change into the
<filename>JBOSS_PORTAL_SOURCE_DIRECTORY/build/</filename> directory, where
<filename>JBOSS_PORTAL_SOURCE_DIRECTORY</filename> is the directory where the
JBoss Portal source code was downloaded to. Then, <trademark
class="registered">Windows</trademark>, users need to run the
<command>build.bat deploy</command> command, and <trademark
class="registered">Linux</trademark> users need to run the
<command>sh build.sh deploy</command> command.
</para>
<para>
At the end of the build process, the <filename>jboss-portal.sar</filename>
file is copied into the
<filename>$JBOSS_HOME/server/default/deploy/</filename> directory:
@@ -364,12 +343,12 @@
<note>
<title>Portal Modules</title>
<para>
- The previous steps install a bare version of JBoss Portal. In previous versions,
several additional modules were deployed as well, but this has since been modularized to
provide greater flexibility. To deploy additional modules, see the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=PortalModules">...
module list</ulink> for more information. To deploy all modules at once, change into
the <filename>build</filename> directory. If you are running Linux, run the
<command>./build.sh deploy-all</command> command. If you are running Microsoft
Windows, run the <command>build.bat deploy-all</command> command.
+ The previous steps install a bare version of JBoss Portal. In previous versions,
several additional modules were deployed as well, but this has since been modularized to
provide greater flexibility. To deploy additional modules, refer to the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=PortalModules">...
module list</ulink> for more information. To deploy all modules at once, change into
the <filename>build</filename> directory. If you are running <trademark
class="registered">Linux</trademark>, run the <command>sh
build.sh deploy-all</command> command. On <trademark
class="registered">Windows</trademark>, run the
<command>build.bat deploy-all</command> command.
</para>
</note>
</para>
<para>
- To build the clustered version on Linux Operating Systems:
+ To build the clustered version on <trademark
class="registered">Linux</trademark> operating systems:
</para>
<para>
<orderedlist>
@@ -379,7 +358,7 @@
</para>
<para>
<screen>
-./build.sh main
+sh build.sh main
</screen>
</para>
</listitem>
@@ -389,23 +368,23 @@
</para>
<para>
<screen>
-./build.sh deploy-ha
+sh build.sh deploy-ha
</screen>
</para>
<para>
- After the <command>./build.sh deploy-ha</command> command completes, the
<filename>jboss-portal-ha.sar</filename> file is copied into the
<filename>$JBOSS_HOME/server/all/deploy/</filename> directory.
+ After the <command>sh build.sh deploy-ha</command> command completes,
the <filename>jboss-portal-ha.sar</filename> file is copied into the
<filename>$JBOSS_HOME/server/all/deploy/</filename> directory.
</para>
</listitem>
</orderedlist>
</para>
<para>
- To build the clustered version on Microsoft Windows, repeat the previous steps,
replacing <command>./build.sh</command> with
<command>build.bat</command>.
+ To build the clustered version on <trademark
class="registered">Windows</trademark>, repeat the previous steps,
replacing <command>sh build.sh</command> with
<command>build.bat</command>.
</para>
</sect2>
<sect2>
<title>Database Setup</title>
<para>
- A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include an
embedded Hypersonic SQL database that JBoss Portal can use; however, this is only
recommended for developer use. The following databases are recommended for production use,
and have had test suites run against them: MySQL 4, MySQL 5, Microsoft SQL Server,
PostgreSQL 8, Oracle 9, and Oracle 10. JBoss Portal can use any database that is supported
by Hibernate.
+ A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include an
embedded Hypersonic SQL database that JBoss Portal can use; however, this is only
recommended for developer use. The following databases are recommended for production use,
and have had test suites run against them: <trademark
class="registered">MySQL</trademark> 4 and 5, <trademark
class="registered">Microsoft</trademark> <trademark
class="registered">SQL Server</trademark>, PostgreSQL 8, <trademark
class="registered">Oracle</trademark> Database 9, and <trademark
class="registered">Oracle</trademark> Database 10. JBoss Portal can use
any database that is supported by Hibernate.
</para>
<para>
To configure a database to use with JBoss Portal:
@@ -414,7 +393,7 @@
<orderedlist>
<listitem>
<para>
- <emphasis role="bold">Create a new database:</emphasis>
this guide assumes that the new database will be called
<emphasis>jbossportal</emphasis>.
+ <emphasis role="bold">Create a new database:</emphasis>
this guide assumes that the new database is called
<emphasis>jbossportal</emphasis>.
</para>
</listitem>
<listitem>
@@ -433,7 +412,7 @@
<sect2>
<title>Datasource Configuration</title>
<para>
- The JBoss Portal binary download that was extracted in <xref
linkend="install_binarydownload"/>, contains pre-configured Datasource
descriptors for the more popular databases. Datasource descriptors are provided for the
MySQL 4, MySQL 5, PostgreSQL, Microsoft SQL Server, and Oracle databases, and can be found
in the <filename>setup</filename> subdirectory where the JBoss Portal binary
was extracted to:
+ The JBoss Portal binary download that was extracted in <xref
linkend="install_binarydownload"/>, contains pre-configured Datasource
descriptors for the more popular databases. Datasource descriptors are provided for the
<trademark class="registered">MySQL</trademark> 4 and 5, PostgreSQL,
<trademark class="registered">Microsoft</trademark> <trademark
class="registered">SQL Server</trademark>, and <trademark
class="registered">Oracle</trademark> databases, and can be found in
the <filename>setup</filename> subdirectory where the JBoss Portal binary was
extracted to:
</para>
<mediaobject>
<imageobject>
@@ -444,7 +423,7 @@
Copy the Datasource descriptor that matches your database into the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/</filename>
directory, where <replaceable>configuration</replaceable> is either all,
default, minimal, or production. For example, if you are using the production
configuration, copy the Datasource descriptor into the
<filename>$JBOSS_HOME/server/production/deploy/</filename> directory. The
production configuration only exists on JBoss EAP installations, and not JBoss AS.
</para>
<para>
- After the Datasource descriptor has been copied into the
<filename>deploy</filename> directory, make sure the username, password,
connection-url, and driver-class are correct for your chosen database. Datasource
descriptor files can be deployed to test before being used in production. The following is
an example Datasource descriptor for the PostgreSQL database:
+ After the Datasource descriptor has been copied into the
<filename>deploy</filename> directory, make sure the
<computeroutput>user-name</computeroutput>,
<computeroutput>password</computeroutput>,
<computeroutput>connection-url</computeroutput>, and
<computeroutput>driver-class</computeroutput>, are correct for your chosen
database. Datasource descriptor files can be deployed to test before being used in
production. The following is an example Datasource descriptor for a PostgreSQL database:
</para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
@@ -459,7 +438,7 @@
</datasources>
]]></programlisting>
<para>
- For further details about Datasource descriptors, please refer to the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=CreateAJDBCDataSource&...
JDBC Datasource wiki page</ulink>.
+ For further details about Datasource descriptors, please refer to the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=CreateAJDBCDataSource&...
JDBC Datasource Wiki page</ulink>.
</para>
</sect2>
</sect1>
@@ -477,7 +456,7 @@
</listitem>
<listitem>
<para>
- <emphasis role="bold">Start the server:</emphasis>
change into the <filename>$JBOSS_HOME/bin/</filename> directory. On Microsoft
Windows, execute <command>run.bat</command>. On Linux, run the
<command>./run.sh</command> command. To specify a configuration to use, for
example, the default configuration, append the <command> -c default</command>
option to the <command>run.bat</command> or
<command>./run.sh</command> commands.
+ <emphasis role="bold">Start the server:</emphasis>
change into the <filename>$JBOSS_HOME/bin/</filename> directory. On
<trademark class="registered">Windows</trademark>, execute
<command>run.bat</command>. On <trademark
class="registered">Linux</trademark>, run the <command>sh
run.sh</command> command. To specify a configuration to use, for example, the
default configuration, append the <command> -c default</command> option to the
<command>run.bat</command> or <command>sh run.sh</command>
commands.
</para>
</listitem>
<listitem>
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/ldap.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/ldap.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/ldap.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -102,8 +102,7 @@
<title>Configuration of LDAP connection</title>
<sect2>
<title>Connection Pooling</title>
- <para>Portal uses connection pooling provided by <ulink
url="http://java.sun.com/products/jndi/tutorial/ldap/connect/pool.ht...;.
- It is enabled by default. You can configure connection pooling settings using
following options:</para>
+ <para>JBoss Portal uses <ulink
url="http://java.sun.com/products/jndi/tutorial/ldap/connect/pool.ht...
pooling</ulink> provided by <ulink
url="http://java.sun.com/products/jndi/">JNDI</ulink>, and is enabled
by default. Use the following options to configure connection pooling
settings:</para>
<programlisting><![CDATA[
<datasource>
<name>LDAP</name>
@@ -155,7 +154,7 @@
</config>
</datasource>]]></programlisting>
<para>
- Please refer to the <ulink
url="http://java.sun.com/products/jndi/tutorial/ldap/connect/config....
Documentation</ulink> to learn about option values.
+ Remember, as it is described in the <ulink
url="http://java.sun.com/products/jndi/tutorial/ldap/connect/config....
documentation</ulink>, these options are system properties, not environment
properties, and as such, they affect all connection pooling requests in the <trademark
class="trade">Java runtime environment</trademark>.
</para>
</sect2>
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/migration.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/migration.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/migration.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -15,12 +15,521 @@
<para>
<warning>
<para>
- Before performing any instructions or operations in this chapter, back up your database
content and
- the entire JBoss EAP or JBoss AS directory!
+ Before performing any instructions or operations in this chapter, back up your database
and the entire JBoss EAP or JBoss AS directory!
</para>
</warning>
</para>
<sect1 id="manual_migration">
+ <title>Manual Upgrade</title>
+ <para>
+ The database schema has not changed since JBoss Portal 2.4; however, there are
several differences when using a database created by JBoss Portal 2.4, that prevent simply
deploying the latest version of JBoss Portal. For example, some portlets are no longer
present in JBoss Portal 2.6, and certain existing portlets are now packaged differently.
This chapter describes updating a <trademark
class="registered">MySQL</trademark> database created by JBoss Portal
2.4, for use with JBoss Portal 2.6.
+ </para>
+ <para>
+ Users, roles, and pages created in JBoss Portal 2.4 should be accessible in JBoss
Portal 2.6 deployments.
+ </para>
+ <para>
+ The upgrade procedure can be straightforward:
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ If you are using the JBoss Portal binary, remove the
<filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/</filename>
directory. If JBoss Portal was built from source, remove the
<filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar</filename> file.
+ </para>
+ </listitem>
+ <!--<listitem>
+ Remove <emphasis
role="bold">$JBOSS_HOME/server/default/data</emphasis> directory.
+ </listitem>-->
+ <listitem>
+ <para>
+ Update the data in the JBoss Portal database, as described in <xref
linkend="upgrade_portal_database"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Deploy JBoss Portal 2.6.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <sect2>
+ <title>Themes</title>
+ <para>
+ In JBoss Portal 2.6, portal pages contain additional areas, such as the
<guiicon>Login</guiicon>, <guiicon>Admin</guiicon>, and
<guiicon>Dashboard</guiicon> links, on the top right-hand corner of portal
pages:
+ </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" valign="middle"
fileref="images/migration/theme.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>
+ Since portal pages now contain additional areas, certain themes have changed. If a
default theme that exists in JBoss Portal 2.6 is used, such as renaissance, no
configuration should be necessary. Using old themes from JBoss Portal 2.4 may make JBoss
Portal 2.6 unusable, for example, not being able to log in. To update custom themes, refer
to the bundled JBoss Portal 2.6 themes as an example.
+ </para>
+ </sect2>
+ <sect2 id="upgrade_portal_database">
+ <title>Updating the Database</title>
+ <para>
+ The following tables contain all references to portlets:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>JBP_INSTANCE</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>JBP_WINDOW</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>JBP_OBJECT_NODE</emphasis>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ All procedures described in the following sections can performed using the JBoss
Portal 2.4 <guiicon>Admin</guiicon> portlet. Treat these directions as
guidelines when migrating a large JBoss Portal deployment. Database data can be updated
manually using the correct tools for your RDBMS. For example, if you are using a
<trademark class="registered">MySQL</trademark> database, you can
use the <ulink
url="http://www.mysql.com/products/tools/query-browser/">MySQL Query
Browser</ulink>.
+ </para>
+ <para>
+ During the upgrade process, legacy references have to be cleaned up, to either
remove them, or to allow JBoss Portal 2.6 to recreate them correctly. Remove all
references (instances and windows) to the portlets listed below, as they are not present
in JBoss Portal 2.6. This can be done using the JBoss Portal 2.4
<guiicon>Admin</guiicon> portlet:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>HeaderContentPortlet</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>URLPortlet</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>TestPortlet</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>PortletA</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>PortletB</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>SecuredTestPortlet</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>CharsetPortlet</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>CounterPortlet</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>CachedCounterPortlet</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>ExceptionPortlet</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>PortletSessionPortlet</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>EncodingPortlet</emphasis>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The following instructions refer to a standard JBoss Portal 2.4 deployment. If core
portlets, portlet instances, or portlet windows were renamed, make the appropriate
modifications. The following is an example of the MySQL Query Browser:
+ </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" valign="middle"
fileref="images/migration/querybrowser1.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>
+ <note>
+ <title>Requested Resource Error</title>
+ <para>
+ When running JBoss Portal 2.6 with a database created by JBoss Portal 2.4, a
non-existing portlet will try to be displayed, resulting in a
<computeroutput>404</computeroutput>, <computeroutput>The requested
resource() is not available</computeroutput> error.
+ </para>
+ </note>
+ </para>
+ </sect2>
+ <sect2>
+ <title>Portlet Names</title>
+ <para>
+ Names of certain core bundled-portlets have changed. Destroy the following
instances and use the <guiicon>Admin</guiicon> portlet to recreate them, or
edit the <emphasis role="bold">JBP_INSTANCE</emphasis> table as
follows:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Change <emphasis>local.samples.JSPPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column to
<emphasis>local./portal-jsp-samples.JSPPortlet</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Change <emphasis>local.portal.CMSPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column to
<emphasis>local./portal-cms.CMSPortlet</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Change <emphasis>local.portal.CMSAdminPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column to
<emphasis>local./portal-cms.CMSAdminPortlet</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Change <emphasis>local.portal.ManagementPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column to
<emphasis>local./portal-admin.AdminPortlet</emphasis>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Some portlets are no longer present in JBoss Portal 2.6, and certain existing
portlets are now packaged differently. Remove the following entries in the <emphasis
role="bold">JBP_INSTANCE</emphasis> table, so that JBoss Portal 2.6 can
recreate them:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ rows containing <emphasis>NewsPortletInstance2</emphasis> in the
<emphasis>ID</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.portal.NavigationPortlet</emphasis>
in the <emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing
<emphasis>local.samples.HeaderContentPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.WeatherPortlet</emphasis> in
the <emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.NewsPortlet</emphasis> in
the <emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.URLPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.TestPortlet</emphasis> in
the <emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.PortletA</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.PortletB</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing
<emphasis>local.samples.SecuredTestPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.CharsetPortlet</emphasis> in
the <emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.CounterPortlet</emphasis> in
the <emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing
<emphasis>local.samples.CachedCounterPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.ExceptionPortlet</emphasis>
in the <emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing
<emphasis>local.samples.PortletSessionPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>local.samples.EncodingPortlet</emphasis>
in the <emphasis>PORTLET_REF</emphasis> column.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Remove the following entries in the <emphasis
role="bold">JBP_WINDOW</emphasis> table, so that JBoss Portal 2.6 can
recreate them:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ rows containing <emphasis>NavigationPortletInstance</emphasis> in
the <emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>URLPortletInstance</emphasis> in the
<emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>PortletAInstance</emphasis> in the
<emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>PortletBInstance</emphasis> in the
<emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>EncodingPortletInstance</emphasis> in the
<emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>PortletSessionPortletInstance</emphasis>
in the <emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>CachedCounterPortletInstance</emphasis> in
the <emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>CounterPortletInstance</emphasis> in the
<emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>CharsetPortletInstance</emphasis> in the
<emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>SecuredTestPortletInstance</emphasis> in
the <emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>SecuredTestPortletInstance</emphasis> in
the <emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>ExceptionPortletInstance</emphasis> in the
<emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>HeaderContentPortletInstance</emphasis> in
the <emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>TestPortletInstance</emphasis> in the
<emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>MissingPortletInstance</emphasis> in the
<emphasis>INSTANCE_REF</emphasis> column.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Remove the following entries in the <emphasis
role="bold">JBP_OBJECT_NODE</emphasis> table, so that JBoss Portal 2.6
can recreate them:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ rows containing <emphasis>NavigationPortletWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>URLPortletWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>PortletAWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>PortletBWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>MissingInstanceWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>EncodingPortletWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>PortletSessionPortletWindow</emphasis> in
the <emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>CachedCounterPortletWindow</emphasis> in
the <emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>CounterPortletWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>CharsetPortletWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>SecuredTestPortletWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>ExceptionPortletWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>MissingPortletWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>HeaderContentPortletWindow</emphasis> in
the <emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rows containing <emphasis>TestPortletWindow</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2>
+ <title>CMS</title>
+ <para>
+ In JBoss Portal 2.6 versions, the way the CMS content is displayed changed
significantly. For further information, refer to <xref
linkend="contentintegration"/> and <xref
linkend="cmsPortlet"/>. Currently there is no need to have more than one
instance of the <emphasis>CMSPortlet</emphasis>. The portlet window displays
CMS content, not by referring to that portlet instance, but by having the proper
<emphasis>content-type</emphasis> defined. The following configuration is in
the <filename>jboss-portal.sar/conf/data/default-object.xml</filename> file:
+ </para>
+ <para>
+<screen><![CDATA[
+<window>
+ <window-name>CMSWindow</window-name>
+ <content>
+ <content-type>cms</content-type>
+ <content-uri>/default/index.html</content-uri>
+ </content>
+ <region>center</region>
+ <height>1</height>
+</window>]]>
+</screen>
+ </para>
+ <para>
+ The following example uses the MySQL Query Browser. Open the <emphasis
role="bold">JBP_OBJECT_NODE</emphasis> table in your database schema.
Look at the <emphasis role="bold">PATH</emphasis> column to identify
any occurrences of <emphasis>CMS</emphasis> in your JBoss Portal deployment.
Identify any row referring to <emphasis>CMSPortletWindow</emphasis>, and
remember the number in the <emphasis role="bold">PK</emphasis>
column. The <emphasis role="bold">PK</emphasis> number is needed in
the following steps:
+ </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" valign="middle"
fileref="images/migration/querybrowser2.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>
+ Go to the <emphasis role="bold">JBP_WINDOW</emphasis> table
and find a row with the same
+ <emphasis role="bold">PK</emphasis> value from the
<emphasis role="bold">JBP_OBJECT_NODE</emphasis> table. In such a
row, replace <emphasis>CMSPortletInstance</emphasis> with a path to your CMS
resource. For example, by default, JBoss Portal displays
<filename>/default/index.html</filename>.
+ </para>
+ <para>
+ Add a row containing the following to the <emphasis
role="bold">JBP_PORTAL_OBJECT_PROPS</emphasis> table:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <emphasis role="bold">PK</emphasis> number
remembered from the <emphasis>OBJECT_KEY</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>portal.windowContentType</emphasis> in the
<emphasis>NAME</emphasis> column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>cms</emphasis> in the
<emphasis>jbp_VALUE</emphasis> column.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ As well, the CMS can be migrated by backing up the
<computeroutput>jbp_cms_*</computeroutput> tables, and recreating them in a
JBoss Portal 2.6 database. There were no schema changes for the CMS between JBoss Portal
2.4 and JBoss Portal 2.6.
+ </para>
+ <para>
+ <note>
+ <title>Portlet Content-type and the path to the CMS
Resource</title>
+ <para>
+ The <guiicon>Admin</guiicon> portlet can be used to change the
portlet window content-type, and configure the path to the CMS resource.
+ </para>
+ </note>
+ </para>
+ </sect2>
+</sect1>
+ <!--<sect1 id="manual_migration">
<title>Manual Upgrade</title>
<para>
Although the database schema remains the same in JBoss Portal 2.6, there are
several differences that prevent simply deploying the latest version of JBoss Portal, when
using a database created for JBoss Portal 2.4. This chapter describes updating a JBoss
Portal 2.4 MySQL database for use with JBoss Portal 2.6.
@@ -34,11 +543,11 @@
<para>
If you are using the JBoss Portal binary, remove the
<filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/</filename>
directory. If JBoss Portal was built from source, remove the
<filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar</filename> file.
</para>
- </listitem>
+ </listitem> -->
<!--<listitem>
Remove <emphasis
role="bold">$JBOSS_HOME/server/default/data</emphasis> directory.
</listitem>-->
- <listitem>
+ <!-- <listitem>
<para>
Update the data in the JBoss Portal database, as described in <xref
linkend="upgrade_portal_database"/>.
</para>
@@ -75,7 +584,7 @@
Database schema has not changed between the JBoss Portal 2.4 and 2.6 releases, but
certain content that is kept in the databases has changed. Data can be updated manually by
using the correct tools for your RDBMS. For example, if you are using a MySQL database,
you can use the <ulink
url="http://www.mysql.com/products/tools/query-browser/">MySQL Query
Browser</ulink>.
</para>
<para>
- The following instructions refer to a standard JBoss Portal 2.4 deployment. If you
named core portlets, portlet instances, or portlet windows differently, you will need to
make the appropriate modifications. The following is an example of using the MySQL Query
Browser:
+ The following instructions refer to a standard JBoss Portal 2.4 deployment. If you
named core portlets, portlet instances, or portlet windows differently, you need to make
the appropriate modifications. The following is an example of using the MySQL Query
Browser:
</para>
<para>
<mediaobject>
@@ -88,7 +597,7 @@
<sect2>
<title>Portlet Names</title>
<para>
- Names of certain core bundled portlets have changed. Destroy the following
instances and use the AdminPortlet to recreate them, or, edit the <emphasis
role="bold">JBP_INSTANCES</emphasis> table as follows:
+ Names of certain core bundled portlets have changed. Destroy the following
instances and use the AdminPortlet to recreate them, or, edit the <emphasis
role="bold">JBP_INSTANCE</emphasis> table as follows:
</para>
<para>
<orderedlist>
@@ -110,13 +619,13 @@
</orderedlist>
</para>
<para>
- The <emphasis>NavigationPortlet</emphasis> from JBoss Portal 2.4 has
been removed, and its functionality is now replaced by
<emphasis>PageCustomizerInterceptor</emphasis>. All references to the
<emphasis>NavigationPortlet</emphasis> should be removed from all portal
pages. Remove <emphasis>NavigationPortletInstance</emphasis> using the
AdminPortlet, or edit the database as follows:
+ The <emphasis>NavigationPortlet</emphasis> from JBoss Portal 2.4 has
been removed, and its functionality is now replaced by
<emphasis>PageCustomizerInterceptor</emphasis>. Remove all references to the
<emphasis>NavigationPortlet</emphasis> from all portal pages. Remove
<emphasis>NavigationPortletInstance</emphasis> using the AdminPortlet, or edit
the database as follows:
</para>
<para>
<orderedlist>
<listitem>
<para>
- In the <emphasis>JBP_INSTANCES</emphasis> table, rows containing
<emphasis>local.portal.NavigationPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column.
+ In the <emphasis>JBP_INSTANCE</emphasis> table, rows containing
<emphasis>local.portal.NavigationPortlet</emphasis> in the
<emphasis>PORTLET_REF</emphasis> column.
</para>
</listitem>
<listitem>
@@ -193,7 +702,7 @@
</note>
</para>
</sect2>
-</sect1>
+</sect1> -->
<!--
<para>This chapter addresses migration issues from version 2.2 to 2.4 of JBoss
Portal.</para>
<sect1 id="migrating_database">
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/portalapi.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/portalapi.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/portalapi.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -416,7 +416,7 @@
On this method we simply filter down to UserAuthenticationEvent then depending
on the type of authentication event we update the
counters. <emphasis>counter</emphasis> keeps track of the registered
and logged-in users, while counterEver only counts the number of
times people logged-in the portal.</para>
- <para>Now that the Java class has been written we need to register it so
that it can be called when the events are triggered. To do
+ <para>Now that the <trademark
class="trade">Java</trademark> class has been written we need to
register it so that it can be called when the events are triggered. To do
so we need to register it as an MBean. It can be done by editing the sar
descriptor file:
<emphasis>YourService.sar/META-INF/jboss-service.xml</emphasis> so
that it looks like the following:
<programlisting><![CDATA[
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/security.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/security.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/security.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -206,7 +206,7 @@
<xmbean/>
<!--
NOTE: cmsRootUserName denotes a single Portal user that has access to
everything in the CMS. Denote this user
- carefully and should be synonymous to the 'root' user in a Unix system.
By default: this value is the built-in
+ carefully and should be synonymous to the 'root' user in UNIX® operating
systems. By default: this value is the built-in
'admin' user account. This can be changed to any other user account
registered in your Portal
-->
<attribute name="CmsRootUserName">admin</attribute>
@@ -268,7 +268,7 @@
<title>CMS Super User</title>
<para>
A CMS Super User is a designated Portal User Account that has access to all
resources/functions in the CMS. It is a concept similar to the
- super user concept in a Linux/Unix security system. This account should be
carefully used and properly protected. By default, JBoss Portal designates the
+ super user concept in a <trademark
class="registered">Linux</trademark> and <trademark
class="registered">UNIX</trademark> security systems. This account
should be carefully used and properly protected. By default, JBoss Portal designates the
built-in 'admin' user account as a CMS Super User. This can be changed
by modifying the <emphasis>cmsRootUserName</emphasis> value in the
<literal>jboss-portal.sar/portal-cms.sar/META-INF/jboss-service.xml</literal>
configuration.
<programlisting>
@@ -281,7 +281,7 @@
<xmbean/>
<!--
NOTE: cmsRootUserName denotes a single Portal user that has access to
everything in the CMS. Denote this user
- carefully and should be synonymous to the 'root' user in a Unix system.
By default: this value is the built-in
+ carefully and should be synonymous to the 'root' user in UNIX® operating
systems. By default: this value is the built-in
'admin' user account. This can be changed to any other user account
registered in your Portal
-->
<attribute name="CmsRootUserName">admin</attribute>
@@ -305,13 +305,7 @@
<sect1 id="security.security_authentication">
<title>Authentication with JBoss Portal</title>
- <para>JBoss Portal relies on Java EE for the authentication of users. The
Java EE authentication has its advantages
- and drawbacks. The main motivation for using Java EE security is the integration
with the application server and the
- operational environment in which the portal is deployed. The servlet layer provides
already the authentication functionality
- and obviously it is not a responsibility of the portal. Whenever a user is
authenticated by the servlet layer
- its security identity is propagated throughout the call stack in the different
layers of the Java EE stack. The weaknesses
- are the lack of an explicit logout mechanism and the lack of dynamicity in the
mapping of URL as security resources. However
- JBoss Portal improves that behavior when it is possible to do so.</para>
+ <para>JBoss Portal relies on Java Platform, Enterprise Edition (Java EE) for
the authentication of users. The Java EE authentication has its advantages and drawbacks.
The main motivation for using Java EE security is the integration with the application
server and the operational environment in which the portal is deployed. The servlet layer
provides already the authentication functionality and obviously it is not a responsibility
of the portal. Whenever a user is authenticated by the servlet layer its security identity
is propagated throughout the call stack in the different layers of the Java EE stack. The
weaknesses are the lack of an explicit logout mechanism and the lack of dynamicity in the
mapping of URL as security resources. However JBoss Portal improves that behavior when it
is possible to do so.</para>
<sect2>
<title>Authentication configuration</title>
<para>JBoss Portal can be seen before all as a web application and
therefore inherits all the configuration mechanisms
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/supported.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/supported.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/supported.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -31,13 +31,13 @@
</sect1>
<sect1>
<title>Supported Operating Systems</title>
- <para>JBoss Portal is 100% pure Java, and therefore it is interoperable with
most Operating Systems
- capable of running a Java Virtual Machine (JVM). These Operating Systems include
but are not limited to: Linux, Microsoft Windows, UNIX, and Mac OS X.
+ <para>JBoss Portal is 100% pure <trademark
class="trade">Java</trademark>, and therefore it is interoperable with
most operating systems
+ capable of running a Java Virtual Machine (<trademark
class="trade">JVM</trademark>), including <trademark
class="registered">Linux</trademark>, <trademark
class="registered">Windows</trademark>, <trademark
class="registered">UNIX</trademark> operating systems, and Mac OS X.
</para>
</sect1>
<sect1>
<title>JBoss Application Server</title>
- <para>JBoss Portal 2.6.4 is tested with JBoss Application Server (AS) 4.2.1,
JBoss AS 4.2.2, JBoss Enterprise Application Platform (EAP) 4.2 and JBoss EAP 4.3. It is
highly recommended that customers who have access to the <ulink
url="https://support.redhat.com/portal/login.html">JBoss Customer Support
Portal (CSP)</ulink> use JBoss EAP 4.3. Customers who do not have access to the
JBoss CSP should use <ulink
url="http://labs.jboss.com/jbossas/">JBoss
AS</ulink>.
+ <para>JBoss Portal 2.6.5 is tested with JBoss Application Server (AS) 4.2.1,
JBoss AS 4.2.2, JBoss Enterprise Application Platform (EAP) 4.2 and JBoss EAP 4.3. It is
highly recommended that customers who have access to the <ulink
url="https://support.redhat.com/portal/login.html">JBoss Customer Support
Portal (CSP)</ulink> use JBoss EAP 4.3 (It is mandatory to get access to
professional support). Customers who do not have access to the JBoss CSP should use
<ulink
url="http://labs.jboss.com/jbossas/">JBoss AS</ulink>.
</para>
<warning>
<para>JBoss AS versions 4.0.<replaceable>x</replaceable> are
not supported.</para>
@@ -47,14 +47,12 @@
<title>Databases</title>
<para>JBoss Portal is database-agnostic. The following list outlines
known-to-be-working database vendor and version combinations:</para>
<itemizedlist>
- <listitem>MySQL
4.<replaceable>x</replaceable>.<replaceable>x</replaceable> (use
<ulink
url="http://dev.mysql.com/downloads/connector/j/3.1.html">Co...
3.1</ulink>)</listitem>
- <listitem>MySQL 5 (<ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=AvoidMySQL5DataTruncat...
issue</ulink>)
- </listitem>
+ <listitem><trademark
class="registered">MySQL</trademark>
4.<replaceable>x</replaceable>.<replaceable>x</replaceable> (use
<ulink
url="http://dev.mysql.com/downloads/connector/j/3.1.html">Co...
3.1</ulink>) and 5 (<ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=AvoidMySQL5DataTruncat...
issue</ulink>)</listitem>
<listitem>PostgreSQL
8.<replaceable>x</replaceable></listitem>
<listitem>Hypersonic SQL</listitem>
- <listitem>Derby</listitem>
- <listitem>Oracle 9 and 10g (use the <ulink
url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/i...
driver from the Oracle 10 branch</ulink> even if you are running Oracle
9)</listitem>
- <listitem>Microsoft SQL Server</listitem>
+ <listitem>Apache Derby</listitem>
+ <listitem><trademark class="registered">Oracle</trademark>
Database 9 and 10g (use the <ulink
url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/i...
driver from the Oracle 10 branch</ulink> even if you are running Oracle
9)</listitem>
+ <listitem><trademark
class="registered">Microsoft</trademark><trademark
class="registered"> SQL Server</trademark></listitem>
<listitem>MaxDB</listitem>
</itemizedlist>
<note>
@@ -63,6 +61,6 @@
</sect1>
<sect1>
<title>Source building</title>
- <para>The source building mechanism works on Linux, Microsoft Windows, Mac OS
X, and any UNIX-like Operating System.</para>
+ <para>The source building mechanism works on <trademark
class="registered">Linux</trademark>, <trademark
class="registered">Windows</trademark>, Mac OS X, and <trademark
class="registered">UNIX</trademark> operating systems.</para>
</sect1>
</chapter>
Modified:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/themeandlayouts.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/themeandlayouts.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/themeandlayouts.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -31,9 +31,7 @@
responsible to render markup that will wrap the markup fragments produced by the
individual
portlets. Themes, on the other hand, are responsible to style and enhance this
markup.
</para>
- <para>In JBoss Portal, layouts are implemented as a JSP or a Servlet. Themes
are implemented
- using CSS Style sheets, javascript and images. The binding element between
layouts and
- themes are the class and id attributes of the rendered markup.
+ <para>In JBoss Portal, layouts are implemented as a JSP or a Servlet. Themes
are implemented using CSS Style sheets, javascript and images. The binding element between
layouts and themes are the class and id attributes of the rendered markup.
</para>
<para>JBoss Portal has the concept of regions on a page. When a page is
defined, and portlet
windows are assigned to the page, the region, and order inside the region, has
to be
@@ -49,7 +47,7 @@
own entity.
<itemizedlist>
<para>To implement this encapsulation there are several
ways:</para>
- <listitem>JSPs that get included from the layout JSP for each
region/portlet</listitem>
+ <listitem>JSP pages that get included from the layout JSP for each
region/portlet</listitem>
<listitem>a taglib that allows to place region, window, and decoration
tags into the
layout JSP
</listitem>
@@ -131,7 +129,7 @@
<listitem>The first option would simply require to modify
the theme CSS, by doing this you could change the fonts, the way tabs
are rendered, colors and many
other things but not change the content.</listitem>
- <listitem>The second option is to modify the provided JSPs,
<literal>header.jsp</literal> and
+ <listitem>The second option is to modify the provided JSP files,
<literal>header.jsp</literal> and
<literal>tabs.jsp</literal>. It gives you more flexibility
than the previous solution on modifying
the content. Links to legacy application could easily be added, URLs
could be arranged differently, the CSS
approach could be replaced by good old HTML, CSS style names could be
changed... The drawback of
@@ -141,14 +139,14 @@
</itemizedlist>
</para>
<sect3>
- <title>Writing his own JSPs</title>
- <para>The content of those two parts are displayed thanks to two
different JSP pages. By default
+ <title>Writing his own <trademark
class="trade">JSP</trademark> pages</title>
+ <para>The content of those two parts are displayed thanks to two
different <trademark class="trade">JSP</trademark> pages. By
default
you would find those pages in the directory
<literal>portal-core.war/WEB-INF/jsp/header/</literal>.
The file <literal>header.jsp</literal> is used to display the
links that are displayed on the upper
right of the default theme. The file
<literal>tabs.jsp</literal> is used to display the pages tabs
appearing on the left.
</para>
- <para> Again, you have several choices, either to edit the included
JSPs directly or create your own,
+ <para> Again, you have several choices, either to edit the included JSP
files directly or create your own,
store them in a web application then edit the following file:
<literal>jboss-portal.sar/META-INF/jboss-service.xml</literal>.
The interesting part in that file is the following:
<programlisting><![CDATA[<mbean
@@ -166,7 +164,7 @@
</mbean>]]></programlisting>
The three attributes are:
<itemizedlist>
- <listitem>TargetContextPath: Defines the web application context
where the JSPs are located</listitem>
+ <listitem>TargetContextPath: Defines the web application context
where the JSP files are located</listitem>
<listitem>HeaderPath: Defines the location (in the web
application previously defined) of the JSP in charge of writing the header
links</listitem>
<listitem>TabsPath: Defines the location (in the web application
previously defined) of the JSP in charge of writing the pages links (note that it
doesn't have to be renderer as tabs)</listitem>
</itemizedlist>
@@ -367,8 +365,8 @@
</sect2>
-->
<sect2>
- <title>Layout JSP-tags</title>
- <para>The portal comes with a set of JSP tags that allow the layout
developer faster
+ <title>Layout <trademark
class="trade">JSP</trademark> tags</title>
+ <para>The portal comes with a set of <trademark
class="trade">JSP</trademark> tags that allow the layout developer
faster
development.
<itemizedlist>
<para>There are currently two taglibs, containing tags for different
approaches to
@@ -803,7 +801,7 @@
swap, or change individual items of it. No compile or redeploy is necessary.
Themes
can be added or removed while the portal is active. Themes can be deployed in
separate
web applications furthering even more the flexibility of this approach. Web
developers
- don't have to work with JSPs. They can stay in their favorite design tool
and simple
+ don't have to work with JSP pages. They can stay in their favorite design
tool and simple
work against the exploded war content that is deployed into the portal. The
results can
be validated life in the portal.
</para>
Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/trademarks.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/trademarks.xml
(rev 0)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/trademarks.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -0,0 +1,56 @@
+<preface id="trademarks">
+ <title>Please Read: Important Trademark Information</title>
+ <para>
+ JavaServer, JSP, Java, JMX, JDK, Java runtime environment, JRE, J2EE, JVM, Javadoc,
JavaScript, and J2SE are trademarks or registered trademarks of Sun Microsystems, Inc. in
the United States and other countries.
+ </para>
+ <para>
+ JBoss is a registered trademark of Red Hat, Inc. in the U.S. and other countries.
+ </para>
+ <para>
+ Oracle is a registered trademark of Oracle International Corporation.
+ </para>
+ <para>
+ Microsoft, Windows, and SQL Server are either registered trademarks or trademarks of
Microsoft Corporation in the United States and/or other countries.
+ </para>
+ <para>
+ Linux® is the registered trademark of Linus Torvalds in the U.S. and other
countries.
+ </para>
+ <para>
+ UNIX is a registered trademark of The Open Group.
+ </para>
+ <para>
+ MySQL is a trademark or registered trademark of MySQL AB in the U.S. and other
countries.
+ </para>
+ <para>
+ Apache is a trademark of The Apache Software Foundation.
+ </para>
+ <para>
+ Mac and Mac OS are trademarks of Apple Inc., registered in the U.S. and other
countries.
+ </para>
+ <para>
+ All other trademarks referenced herein are the property of their respective owners.
+ </para>
+</preface>
+
+
+<!--To do:
+
+Apache?
+
+Linux?
+
+
+All the sun stuff
+
+
+
+Microsoft?
+
+
+Mail them first (see Apache Jackrabbit)
+
+
+
+
+
+'Apache is a trademark of The Apache Software Foundation, and is used with
permission.' This is not necessary in the case of all-inclusive attribution language
such as, 'All marks are the properties of their respective owners.' Contact the
ASF Public Relations Committee <prc(a)apache.org> with all inquiries regarding
trademark issues -->
\ No newline at end of file
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorials.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -22,7 +22,7 @@
<para>The JSR-168 Portlet Specification aims at defining portlets that can be
used by any JSR-168 portlet container, also known as a portal. There are different portals
with commercial and non-commercial licenses. This chapter gives a brief overview of the
<ulink
url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet
Specification</ulink>. Portlet developers are strongly encouraged to read the
<ulink
url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet
Specification</ulink>.
</para>
<para>
- JBoss Portal is fully JSR-168 compliant, which means any JSR-168 portlet will
behave as it should inside the portal.
+ JBoss Portal is fully JSR-168 compliant, which means any JSR-168 portlet behaves
as it should inside the portal.
</para>
<sect2>
<title>Portal Pages</title>
@@ -47,17 +47,17 @@
<itemizedlist>
<listitem>
<para>
- VIEW - generates markup reflecting the current state of the portlet.
+ <computeroutput>view</computeroutput> - generates markup reflecting
the current state of the portlet.
</para>
</listitem>
<listitem>
<para>
- EDIT - allows a user to customize the behavior of the portlet.
+ <computeroutput>edit</computeroutput> - allows a user to customize
the behavior of the portlet.
</para>
</listitem>
<listitem>
<para>
- HELP - provides information to the user as to how to use the portlet.
+ <computeroutput>help</computeroutput> - provides information to the
user as to how to use the portlet.
</para>
</listitem>
</itemizedlist>
@@ -66,24 +66,24 @@
<sect2>
<title>Window States</title>
<para>
- Window states are an indicator of how much page real-estate a portlet should
consume on any given page.
+ Window states are an indicator of how much page real-estate a portlet
consumes on any given page.
The three states defined by the JSR-168 specification are:
</para>
<para>
<itemizedlist>
<listitem>
<para>
- NORMAL - a portlet shares this page with other portlets.
+ <computeroutput>normal</computeroutput> - a portlet shares this
page with other portlets.
</para>
</listitem>
<listitem>
<para>
- MINIMIZED -a portlet may show very little information, or none at all.
+ <computeroutput>minimized</computeroutput> -a portlet may show very
little information, or none at all.
</para>
</listitem>
<listitem>
<para>
- MAXIMIZED - a portlet may be the only portlet displayed on this page.
+ <computeroutput>maximized</computeroutput> - a portlet may be the
only portlet displayed on this page.
</para>
</listitem>
</itemizedlist>
@@ -148,7 +148,7 @@
<sect3>
<title>Package Structure</title>
<para>
- Like other Java EE applications, portlets are packaged in WAR files. A
typical portlet WAR file can include servlets, resource bundles, images, HTML, JSPs, and
other static or dynamic files. The following is an example of the directory structure of
the HelloWorldPortlet portlet:
+ Like other Java Platform, Enterprise Edition (Java EE) applications, portlets are
packaged in WAR files. A typical portlet WAR file can include servlets, resource bundles,
images, HTML, <trademark class="trade">JavaServer</trademark> Pages
(<trademark class="trade">JSP</trademark>), and other static or
dynamic files. The following is an example of the directory structure of the
HelloWorldPortlet portlet:
</para>
<para>
<mediaobject>
@@ -161,7 +161,7 @@
<sect3>
<title>Portlet Classes</title>
<para>
- The following is the
<filename>HelloWorldPortlet/src/main/org/jboss/portlet/hello/HelloWorldPortlet.java</filename>
java source file, which comes bundled with the <ulink
+ The following is the
<filename>HelloWorldPortlet/src/main/org/jboss/portlet/hello/HelloWorldPortlet.java</filename>
<trademark class="trade">Java</trademark> source file, which comes
bundled with the <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...;:
</para>
<para>
@@ -215,7 +215,7 @@
throws PortletException, IOException, UnavailableException</screen></term>
<listitem>
<para>
- As we extend from <literal>GenericPortlet</literal>, and are only
interested in supporting the <literal>VIEW</literal> mode, only the
<literal>doView</literal> method needs to be implemented, and the
<literal>GenericPortlet</literal> <literal>render</literal>
implemention calls our implementation when the <literal>VIEW</literal> mode is
requested.
+ As we extend from <literal>GenericPortlet</literal>, and are only
interested in supporting the <literal>view</literal> mode, only the
<literal>doView</literal> method needs to be implemented, and the
<literal>GenericPortlet</literal> <literal>render</literal>
implemention calls our implementation when the <literal>view</literal> mode is
requested.
</para>
</listitem>
</varlistentry>
@@ -223,7 +223,7 @@
rResponse.setContentType("text/html");</screen></term>
<listitem>
<para>
- As in the servlet-world, you must declare what content-type the portlet will be
+ As in the servlet world, you must declare what content-type the portlet will be
responding in. Do this before starting to write content, or the portlet will throw
an exception.
</para>
</listitem>
@@ -242,6 +242,7 @@
</para>
<para>
<note>
+ <title>Markup Fragments</title>
<para>
Portlets are responsible for generating markup fragments, as they are included on a
page and are
surrounded by other portlets. In particular, this means that a portlet outputting HTML
must
@@ -282,7 +283,7 @@
<portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class>
<supports>
<mime-type>text/html</mime-type>
- <portlet-mode>VIEW</portlet-mode>
+ <portlet-mode>view</portlet-mode>
</supports>
<portlet-info>
<title>HelloWorld Portlet</title>
@@ -312,12 +313,12 @@
<varlistentry><term><screen><![CDATA[
<supports>
<mime-type>text/html</mime-type>
- <portlet-mode>VIEW</portlet-mode>
+ <portlet-mode>view</portlet-mode>
</supports>]]></screen></term>
<listitem>
<para>
- The <computeroutput><supports></computeroutput> element
allows you to declare all of the markup types that your portlet supports in the
<literal>render</literal> method. This is accomplished via the
- <computeroutput><mime-type></computeroutput> element, which
is required for every portlet. The declared MIME types must match the capability of the
portlet. As well, it allows you to pair which modes and window states are supported for
each markup type. All portlets must support the VIEW portlet mode, so this does not have
to be declared. Use the
<computeroutput><mime-type></computeroutput> element to define
which markup type your portlet supports, which in this example, is
<computeroutput>text/html</computeroutput>. This section tells the portal that
it will only output text and HTML, and that it only supports the
<computeroutput>VIEW</computeroutput> mode.
+ The <computeroutput><supports></computeroutput> element
declares all of the markup types that a portlet supports in the
<literal>render</literal> method. This is accomplished via the
+ <computeroutput><mime-type></computeroutput> element, which
is required for every portlet. The declared MIME types must match the capability of the
portlet. As well, it allows you to pair which modes and window states are supported for
each markup type. All portlets must support the
<computeroutput>view</computeroutput> portlet mode, so this does not have to
be declared. Use the
<computeroutput><mime-type></computeroutput> element to define
which markup type your portlet supports, which in this example, is
<computeroutput>text/html</computeroutput>. This section tells the portal that
it only outputs text and HTML, and that it only supports the
<computeroutput>view</computeroutput> mode.
</para>
</listitem>
</varlistentry>
@@ -327,7 +328,7 @@
</portlet-info>]]></screen></term>
<listitem>
<para>
- When rendered, the portlet's title will be displayed as the header in the portlet
window, unless it is overridden programmatically. In this example, the title would be
<computeroutput>HelloWorld Portlet</computeroutput>.
+ When rendered, the portlet's title is displayed as the header in the portlet
window, unless it is overridden programmatically. In this example, the title would be
<computeroutput>HelloWorld Portlet</computeroutput>.
</para>
</listitem>
</varlistentry>
@@ -338,7 +339,7 @@
<computeroutput><portlet-ref></computeroutput> value must
match the <computeroutput><portlet-name></computeroutput> value
given in the <filename>HelloWorldPortlet/WEB-INF/portlet.xml</filename>
file. The <computeroutput><instance-id></computeroutput>
value can be named anything, but it must match the
<computeroutput><instance-ref></computeroutput> value given
- in the <filename>*-object.xml</filename> files, which in this example,
would be the
<filename>HelloWorldPortlet/WEB-INF/helloworld-object.xml</filename> file.
+ in the <filename>*-object.xml</filename> file, which in this example, would
be the <filename>HelloWorldPortlet/WEB-INF/helloworld-object.xml</filename>
file.
</para>
<para>
The following is an example of the
<filename>HelloWorldPortlet/WEB-INF/portlet-instances.xml</filename> file:
@@ -360,7 +361,7 @@
</screen>
</para>
<para>
- The <filename>*-object.xml</filename> files are JBoss Portal specific
descriptors that allow users to
+ The <filename>*-object.xml</filename> file is a JBoss Portal specific
descriptor that allow users to
define the structure of their portal instances, and create and configure their windows
and
pages. In the following example:
</para>
@@ -373,7 +374,7 @@
</listitem>
<listitem>
<para>
- specifies that the window will display the markup generated by the
<computeroutput>HelloWorldPortletInstance</computeroutput> portlet instance.
+ specifies that the window displays the markup generated by the
<computeroutput>HelloWorldPortletInstance</computeroutput> portlet instance.
</para>
</listitem>
<listitem>
@@ -383,7 +384,7 @@
</listitem>
<listitem>
<para>
- the <computeroutput><region></computeroutput> element
specifies where the window will appear on the page.
+ the <computeroutput><region></computeroutput> element
specifies where the window appears on the page.
</para>
</listitem>
</itemizedlist>
@@ -418,7 +419,7 @@
</screen></term>
<listitem>
<para>
- Tells the portal where this portlet should appear. In this case,
<computeroutput>default.default</computeroutput> specifies that the portlet
will appear in the portal instance named
<computeroutput>default</computeroutput>, and on the page named
<computeroutput>default</computeroutput>.
+ Tells the portal where this portlet appears. In this case,
<computeroutput>default.default</computeroutput> specifies that the portlet
appears in the portal instance named <computeroutput>default</computeroutput>,
and on the page named <computeroutput>default</computeroutput>.
</para>
</listitem>
</varlistentry>
@@ -427,7 +428,7 @@
</screen></term>
<listitem>
<para>
- Instructs the portal to overwrite or keep this object if it already exists. Possible
values are <literal>overwrite</literal> or
<literal>keep</literal>. The <literal>overwrite</literal> value
will destroy the existing object and create a new one based on the content of the
deployment. The <literal>keep</literal> option will maintain the existing
object deployment or create a new one if it does not exist.
+ Instructs the portal to overwrite or keep this object if it already exists. Accepted
values are <computeroutput>overwrite</computeroutput> and
<computeroutput>keep</computeroutput>. The
<computeroutput>overwrite</computeroutput> option destroys the existing
object, and creates a new one based on the content of the deployment. The
<computeroutput>keep</computeroutput> option maintains the existing object
deployment, or creates a new one if it does not exist.
</para>
</listitem>
</varlistentry>
@@ -436,7 +437,7 @@
</screen></term>
<listitem>
<para>
- This can be named anything.
+ A <emphasis role="bold">unique name</emphasis> given to the
portlet window. This can be named anything.
</para>
</listitem>
</varlistentry>
@@ -456,7 +457,7 @@
</screen></term>
<listitem>
<para>
- Specifies the layout region and the order this window will be found on the portal
page.
+ Specifies where the window appears within the page layout.
</para>
</listitem>
</varlistentry>
@@ -475,8 +476,8 @@
</para>
<para>
- JBoss Portal 2.6 introduces the notion of <emphasis>content
type</emphasis>, which is a generic mechanism to
- specify what content will be displayed by a given portlet window. The
<computeroutput>window</computeroutput> section
+ JBoss Portal 2.6 introduces the notion of
<emphasis>content-type</emphasis>, which is a generic mechanism to
+ specify what content displayed by a given portlet window. The
<computeroutput>window</computeroutput> section
of the previous example,
<filename>HelloWorldPortlet/WEB-INF/helloworld-object.xml</filename>, can be
re-written to take advantage of the new content framework. The following is an example
deployment descriptor that uses the new content framework:
</para>
<para>
@@ -537,7 +538,7 @@
</listitem>
<listitem>
<para>
- Change into <filename>HelloWorldPortlet/</filename> directory, and
run the <command>ant deploy</command> command. On Microsoft Windows, the
output will be similar to the following:
+ Change into <filename>HelloWorldPortlet/</filename> directory, and
run the <command>ant deploy</command> command. On <trademark
class="registered">Windows</trademark>, the output will be similar to
the following:
</para>
<para>
<mediaobject>
@@ -564,7 +565,7 @@
</listitem>
<listitem>
<para>
- To expand the WAR file, change into the
<filename>HelloWorldPortlet/</filename> directory, and run the
<command>ant explode</command> command. On Microsoft Windows, the output will
be similar to the following:
+ To expand the WAR file, change into the
<filename>HelloWorldPortlet/</filename> directory, and run the
<command>ant explode</command> command. On <trademark
class="registered">Windows</trademark>, the output will be similar to
the following:
</para>
<para>
<mediaobject>
@@ -596,10 +597,10 @@
<sect3>
<title>Deploying your Portlet</title>
<para>
- If you did not expand the <filename>helloworldportlet.war</filename>
file, copy the <filename>HelloWorldPortlet/helloworldportlet.war</filename>
file into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. If you expanded the <filename>helloworldportlet.war</filename>
file, copy the
<filename>HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using JBoss AS, copy the WAR file or the expanded
directory into the <filename>$JBOSS_HOME/server/default/deploy/</filename>
directory.
+ If you did not expand the <filename>helloworldportlet.war</filename>
file, copy the <filename>HelloWorldPortlet/helloworldportlet.war</filename>
file into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. If you expanded the <filename>helloworldportlet.war</filename>
file, copy the
<filename>HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using the
<computeroutput>default</computeroutput> JBoss AS profile, copy the WAR file
or the expanded directory into the
<filename>$JBOSS_HOME/server/default/deploy/</filename> directory.
</para>
<para>
- Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss
Portal, will trigger a hot-deploy of the portlet:
+ Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss
Portal, triggers a hot-deploy of the portlet:
</para>
<para>
<screen><![CDATA[
@@ -618,7 +619,7 @@
</mediaobject>
</para>
<para>
- To re-deploy the portlet, for example, if you have made changes to any of the
application descriptors, touch the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldportlet.war/WEB-INF/web.xml</filename>
file. This will only work if you copied the
<filename>HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/</filename>
directory into the JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. On Linux, run the following command to re-deploy the HelloWorldPortlet:
+ To re-deploy the portlet, for example, if you have made changes to any of the
application descriptors, touch the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldportlet.war/WEB-INF/web.xml</filename>
file. This only works if you copied the
<filename>HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/</filename>
directory into the JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. On <trademark class="registered">Linux</trademark>, run
the following command to re-deploy the HelloWorldPortlet:
</para>
<para>
<screen>
@@ -626,7 +627,7 @@
</screen>
</para>
<para>
- Re-deploying the HelloWorldPortlet will produce output to the JBoss AS or JBoss EAP
console, similar to the following:
+ Re-deploying the HelloWorldPortlet produces output to the JBoss AS or JBoss EAP
console, similar to the following:
</para>
<para>
<screen><![CDATA[
@@ -639,17 +640,17 @@
</sect3>
</sect2>
<sect2>
- <title>An example JSP Portlet</title>
+ <title>An example <trademark
class="trade">JSP</trademark> portlet</title>
<sect3>
<title>Introduction</title>
<para>
- This section describes how to deploy a JSP portlet in JBoss Portal. Before
proceeding, download the <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
from <ulink
url="http://labs.jboss.com/portletswap/">JBoss
PortletSwap</ulink>. The HelloWorldJSPPortlet demonstrates how to use JSPs for view
rendering, and the portlet tag library (taglib) for generating links.
+ This section describes how to deploy a <trademark
class="trade">JSP</trademark> portlet in JBoss Portal. Before
proceeding, download the <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
from <ulink
url="http://labs.jboss.com/portletswap/">JBoss
PortletSwap</ulink>. The HelloWorldJSPPortlet demonstrates how to use JSP pages for
view rendering, and the portlet tag library (taglib) for generating links.
</para>
</sect3>
<sect3>
<title>Package Structure</title>
<para>
- The application descriptors for the HelloWorldJSPPortlet portlet are similar to
those from the HelloWorldPortlet (<xref
linkend="first_portlet_descriptors"/>). See <xref
linkend="descriptors_portlet"/> for further information about application
descriptors.
+ The application descriptors for the HelloWorldJSPPortlet portlet are similar to
those from the HelloWorldPortlet (<xref
linkend="first_portlet_descriptors"/>). Refer to <xref
linkend="descriptors_portlet"/> for further information about application
descriptors.
</para>
<para>
The HelloWorldJSPPortlet portlet contains the traditional portlet and JBoss Portal
specific application descriptors. The following is an example of the directory structure
of the HelloWorldJSPPortlet portlet:
@@ -749,7 +750,7 @@
</screen></term>
<listitem>
<para>
- Support for these modes must be declared in the
<filename>HelloWorldJSPPortlet/WEB-INF/portlet.xml</filename> file. They will
be triggered when a user clicks on the respective icons in the portlet window titlebar, or
through generated links within the portlet.
+ Support for these modes must be declared in the
<filename>HelloWorldJSPPortlet/WEB-INF/portlet.xml</filename> file. They are
triggered when a user clicks on the respective icons in the portlet window titlebar, or
through generated links within the portlet.
</para>
</listitem>
</varlistentry>
@@ -775,7 +776,7 @@
</screen></term>
<listitem>
<para>
- As in the servlet-world, you must declare what content-type the portlet will be
responding in. Do this before starting to write content, or the portlet will throw an
exception.
+ As in the servlet world, you must declare what content-type the portlet will be
responding in. Do this before starting to write content, or the portlet throws an
exception.
</para>
</listitem>
</varlistentry>
@@ -793,9 +794,9 @@
</para>
</sect3>
<sect3>
- <title>JSP Files and the Portlet Tag Library</title>
+ <title><trademark class="trade">JSP</trademark>
files and the Portlet Tag Library</title>
<para>
- The <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp</filename> and
<filename>HelloWorldJSPPortlet/WEB-INF/jsp/view2.jsp</filename> JSP files are
included in the HelloWorldJSPPortlet portlet. The
<filename>view.jsp</filename> file allows a user to input their name. This is
then posted to the <computeroutput>processAction</computeroutput> method in
the portlet class, which is set as a
<computeroutput>aResponse.setRenderParameter</computeroutput>. The
<computeroutput>doView</computeroutput> <literal>render</literal>
method is invoked, which dispatches to the <filename>view2.jsp</filename>
JSP:
+ The <filename>HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp</filename> and
<filename>HelloWorldJSPPortlet/WEB-INF/jsp/view2.jsp</filename> <trademark
class="trade">JSP</trademark> files are included in the
HelloWorldJSPPortlet portlet. The <filename>view.jsp</filename> file allows a
user to input their name. This is then posted to the
<computeroutput>processAction</computeroutput> method in the portlet class,
which is set as a
<computeroutput>aResponse.setRenderParameter</computeroutput>. The
<computeroutput>doView</computeroutput> <literal>render</literal>
method is invoked, which dispatches to the <filename>view2.jsp</filename>
JSP:
</para>
<para>
<mediaobject>
@@ -875,7 +876,7 @@
</para>
</sect3>
<sect3>
- <title>Building your JSP Portlet</title>
+ <title>Building your <trademark
class="trade">JSP</trademark> portlet</title>
<para>
The <filename>HelloWorldJSPPortlet.zip</filename> file contains a
pre-compiled <filename>helloworldjspportlet.war</filename> file; however, to
manually build the <filename>helloworldjspportlet.war</filename> file:
</para>
@@ -893,7 +894,7 @@
</listitem>
<listitem>
<para>
- Change into <filename>HelloWorldJSPPortlet/</filename> directory,
and run the <command>ant deploy</command> command. On Linux, the output will
be similar to the following:
+ Change into <filename>HelloWorldJSPPortlet/</filename> directory,
and run the <command>ant deploy</command> command. On <trademark
class="registered">Linux</trademark>, the output will be similar to the
following:
</para>
<para>
<mediaobject>
@@ -909,7 +910,7 @@
Note: the directory names will be different for your system.
</para>
<para>
- Expanding the <filename>helloworldjspportlet.war</filename> file allows
you to deploy the portlet as an expanded directory, which makes development easier. As
well, it gives you access to the application descriptors, resource files, JSF, and JSP
pages. To expand the <filename>helloworldjspportlet.war</filename> file:
+ Expanding the <filename>helloworldjspportlet.war</filename> file allows
you to deploy the portlet as an expanded directory, which makes development easier. As
well, it gives you access to the application descriptors, resource files, JSF, and
<trademark class="trade">JSP</trademark> pages. To expand the
<filename>helloworldjspportlet.war</filename> file:
</para>
<para>
<orderedlist>
@@ -920,7 +921,7 @@
</listitem>
<listitem>
<para>
- To expand the WAR file, change into the
<filename>HelloWorldJSPPortlet/</filename> directory, and run the
<command>ant explode</command> command. On Linux, the output will be similar
to the following:
+ To expand the WAR file, change into the
<filename>HelloWorldJSPPortlet/</filename> directory, and run the
<command>ant explode</command> command. On <trademark
class="registered">Linux</trademark>, the output will be similar to the
following:
</para>
<para>
<mediaobject>
@@ -950,12 +951,12 @@
</para>
</sect3>
<sect3>
- <title>Deploying your JSP Portlet</title>
+ <title>Deploying your <trademark
class="trade">JSP</trademark> portlet</title>
<para>
- If you did not expand the <filename>helloworldjspportlet.war</filename>
file, copy the
<filename>HelloWorldJSPPortlet/helloworldjspportlet.war</filename> file into
the correct JBoss AS or JBoss EAP <filename>deploy/</filename> directory. If
you expanded the <filename>helloworldjspportlet.war</filename> file, copy the
<filename>HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using JBoss AS, copy the WAR file or the expanded
directory into the <filename>$JBOSS_HOME/server/default/deploy/</filename>
directory.
+ If you did not expand the <filename>helloworldjspportlet.war</filename>
file, copy the
<filename>HelloWorldJSPPortlet/helloworldjspportlet.war</filename> file into
the correct JBoss AS or JBoss EAP <filename>deploy/</filename> directory. If
you expanded the <filename>helloworldjspportlet.war</filename> file, copy the
<filename>HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using the
<computeroutput>default</computeroutput> JBoss AS profile, copy the WAR file
or the expanded directory into the
<filename>$JBOSS_HOME/server/default/deploy/</filename> directory.
</para>
<para>
- Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss
Portal, will trigger a hot-deploy of the portlet:
+ Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss
Portal, triggers a hot-deploy of the portlet:
</para>
<para>
<screen><![CDATA[
@@ -974,7 +975,7 @@
</mediaobject>
</para>
<para>
- To re-deploy the portlet, for example, if you have made changes to any of the
application descriptors, touch the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjspportlet.war/WEB-INF/web.xml</filename>
file. This will only work if you copied the
<filename>HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/</filename>
directory into the JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. On Linux, run the following command to re-deploy the HelloWorldJSPPortlet:
+ To re-deploy the portlet, for example, if you have made changes to any of the
application descriptors, touch the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjspportlet.war/WEB-INF/web.xml</filename>
file. This only works if you copied the
<filename>HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/</filename>
directory into the JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. On <trademark class="registered">Linux</trademark>, run
the following command to re-deploy the HelloWorldJSPPortlet:
</para>
<para>
<screen>
@@ -982,7 +983,7 @@
</screen>
</para>
<para>
- Re-deploying the HelloWorldJSPPortlet will produce output to the JBoss AS or JBoss EAP
console, similar to the following:
+ Re-deploying the HelloWorldJSPPortlet produces output to the JBoss AS or JBoss EAP
console, similar to the following:
</para>
<para>
<screen><![CDATA[
@@ -1052,7 +1053,7 @@
</init-param>
<supports>
<mime-type>text/html</mime-type>
- <portlet-mode>VIEW</portlet-mode>
+ <portlet-mode>view</portlet-mode>
</supports>
<portlet-info>
<title>HelloWorld JSF Portlet</title>
@@ -1087,12 +1088,12 @@
<varlistentry><term><screen><![CDATA[
<supports>
<mime-type>text/html</mime-type>
- <portlet-mode>VIEW</portlet-mode>
+ <portlet-mode>view</portlet-mode>
</supports>]]></screen></term>
<listitem>
<para>
- The <computeroutput><supports></computeroutput>
element allows you to declare all of the markup types that your portlet supports in the
<literal>render</literal> method. This is accomplished via the
- <computeroutput><mime-type></computeroutput> element,
which is required for every portlet. The declared MIME types must match the capability of
the portlet. As well, it allows you to pair which modes and window states are supported
for each markup type. All portlets must support the VIEW portlet mode, so this does not
have to be declared. Use the
<computeroutput><mime-type></computeroutput> element to define
which markup type your portlet supports, which in this example, is
<computeroutput>text/html</computeroutput>. This section tells the portal that
it will only output text and HTML, and that it only supports the
<computeroutput>VIEW</computeroutput> mode.
+ The <computeroutput><supports></computeroutput>
element allows you to declare all of the markup types that a portlet supports in the
<literal>render</literal> method. This is accomplished via the
+ <computeroutput><mime-type></computeroutput> element,
which is required for every portlet. The declared MIME types must match the capability of
the portlet. As well, it allows you to pair which modes and window states are supported
for each markup type. All portlets must support the
<computeroutput>view</computeroutput> portlet mode, so this does not have to
be declared. Use the
<computeroutput><mime-type></computeroutput> element to define
which markup type your portlet supports, which in this example, is
<computeroutput>text/html</computeroutput>. This section tells the portal that
it only outputs text and HTML, and that it only supports the
<computeroutput>view</computeroutput> mode.
</para>
</listitem>
</varlistentry>
@@ -1186,7 +1187,7 @@
</listitem>
<listitem>
<para>
- Change into <filename>HelloWorldJSFSunRIPortlet/</filename> directory,
and run the <command>ant deploy</command> command. On Linux, the output will
be similar to the following:
+ Change into <filename>HelloWorldJSFSunRIPortlet/</filename> directory,
and run the <command>ant deploy</command> command. On <trademark
class="registered">Linux</trademark>, the output will be similar to the
following:
</para>
<para>
<mediaobject>
@@ -1213,7 +1214,7 @@
</listitem>
<listitem>
<para>
- To expand the WAR file, change into the
<filename>HelloWorldJSFSunRIPortlet/</filename> directory, and run the
<command>ant explode</command> command. On Linux, the output will be similar
to the following:
+ To expand the WAR file, change into the
<filename>HelloWorldJSFSunRIPortlet/</filename> directory, and run the
<command>ant explode</command> command. On <trademark
class="registered">Linux</trademark>, the output will be similar to the
following:
</para>
<para>
<mediaobject>
@@ -1235,10 +1236,10 @@
<sect3>
<title>Deploying your JSF Portlet</title>
<para>
- If you did not expand the
<filename>helloworldjsfsunriportlet.war</filename> file, copy the
<filename>HelloWorldJSFSunRIPortlet/helloworldjsfsunriportlet.war</filename>
file into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. If you expanded the
<filename>helloworldjsfsunriportlet.war</filename> file, copy the
<filename>HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using JBoss AS, copy the WAR file or the expanded
directory into the <filename>$JBOSS_HOME/server/default/deploy/</filename>
directory.
+ If you did not expand the
<filename>helloworldjsfsunriportlet.war</filename> file, copy the
<filename>HelloWorldJSFSunRIPortlet/helloworldjsfsunriportlet.war</filename>
file into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. If you expanded the
<filename>helloworldjsfsunriportlet.war</filename> file, copy the
<filename>HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using
<computeroutput>default</computeroutput> JBoss AS profile, copy the WAR file
or the expanded directory into the
<filename>$JBOSS_HOME/server/default/deploy/</filename> directory.
</para>
<para>
- Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss
Portal, will trigger a hot-deploy of the portlet:
+ Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss
Portal, triggers a hot-deploy of the portlet:
</para>
<para>
<screen><![CDATA[
@@ -1257,7 +1258,7 @@
</mediaobject>
</para>
<para>
- To re-deploy the portlet, for example, if you have made changes to any of the
application descriptors, touch the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml</filename>
file. This will only work if you copied the
<filename>HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/</filename>
directory into the JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. On Linux, run the following command to re-deploy the
HelloWorldJSFSunRIPortlet:
+ To re-deploy the portlet, for example, if you have made changes to any of the
application descriptors, touch the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml</filename>
file. This only works if you copied the
<filename>HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/</filename>
directory into the JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. On <trademark class="registered">Linux</trademark>, run
the following command to re-deploy the HelloWorldJSFSunRIPortlet:
</para>
<para>
<screen>
@@ -1265,7 +1266,7 @@
</screen>
</para>
<para>
- Re-deploying the HelloWorldJSFSunRIPortlet will produce output to the JBoss AS or
JBoss EAP console, similar to the following:
+ Re-deploying the HelloWorldJSFSunRIPortlet produces output to the JBoss AS or JBoss
EAP console, similar to the following:
</para>
<para>
<screen><![CDATA[
@@ -1330,7 +1331,7 @@
This section describes how to deploy a JSF portlet in JBoss Portal, using the
Apache MyFaces JSF implementation in JBoss AS and JBoss EAP. Before proceeding, download
the <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...
from <ulink
url="http://labs.jboss.com/portletswap/">JBoss
PortletSwap</ulink>.
</para>
<para>
- Apache MyFaces can be used globally for the entire server, replacing the Sun JSF RI
libraries, but the HelloWorldJSFMyFaces42Portlet uses its own libraries, and will not
affect the application server.
+ Apache MyFaces can be used globally for the entire server, replacing the Sun JSF RI
libraries, but the HelloWorldJSFMyFaces42Portlet uses its own libraries, but does not
affect the application server.
</para>
</sect3>
<sect3>
@@ -1374,7 +1375,7 @@
</init-param>
<supports>
<mime-type>text/html</mime-type>
- <portlet-mode>VIEW</portlet-mode>
+ <portlet-mode>view</portlet-mode>
</supports>
<portlet-info>
<title>HelloWorld JSF Portlet</title>
@@ -1409,12 +1410,12 @@
<varlistentry><term><screen><![CDATA[
<supports>
<mime-type>text/html</mime-type>
- <portlet-mode>VIEW</portlet-mode>
+ <portlet-mode>view</portlet-mode>
</supports>]]></screen></term>
<listitem>
<para>
- The <computeroutput><supports></computeroutput>
element allows you to declare all of the markup types that your portlet supports in the
<literal>render</literal> method. This is accomplished via the
- <computeroutput><mime-type></computeroutput> element,
which is required for every portlet. The declared MIME types must match the capability of
the portlet. As well, it allows you to pair which modes and window states are supported
for each markup type. All portlets must support the VIEW portlet mode, so this does not
have to be declared. Use the
<computeroutput><mime-type></computeroutput> element to define
which markup type your portlet supports, which in this example, is
<computeroutput>text/html</computeroutput>. This section tells the portal that
it will only output text and HTML, and that it only supports the
<computeroutput>VIEW</computeroutput> mode.
+ The <computeroutput><supports></computeroutput>
element allows you to declare all of the markup types that a portlet supports in the
<literal>render</literal> method. This is accomplished via the
+ <computeroutput><mime-type></computeroutput> element,
which is required for every portlet. The declared MIME types must match the capability of
the portlet. As well, it allows you to pair which modes and window states are supported
for each markup type. All portlets must support the
<computeroutput>view</computeroutput> portlet mode, so this does not have to
be declared. Use the
<computeroutput><mime-type></computeroutput> element to define
which markup type your portlet supports, which in this example, is
<computeroutput>text/html</computeroutput>. This section tells the portal that
it only outputs text and HTML, and that it only supports the
<computeroutput>view</computeroutput> mode.
</para>
</listitem>
</varlistentry>
@@ -1491,7 +1492,7 @@
</listitem>
<listitem>
<para>
- Change into <filename>HelloWorldJSFMyFaces42Portlet/</filename>
directory, and run the <command>ant deploy</command> command. On Linux, the
output will be similar to the following:
+ Change into <filename>HelloWorldJSFMyFaces42Portlet/</filename>
directory, and run the <command>ant deploy</command> command. On <trademark
class="registered">Linux</trademark>, the output will be similar to the
following:
</para>
<para>
<mediaobject>
@@ -1518,7 +1519,7 @@
</listitem>
<listitem>
<para>
- To expand the WAR file, change into the
<filename>HelloWorldJSFMyFaces42Portlet/</filename> directory, and run the
<command>ant explode</command> command. On Linux, the output will be similar
to the following:
+ To expand the WAR file, change into the
<filename>HelloWorldJSFMyFaces42Portlet/</filename> directory, and run the
<command>ant explode</command> command. On <trademark
class="registered">Linux</trademark>, the output will be similar to the
following:
</para>
<para>
<mediaobject>
@@ -1540,10 +1541,10 @@
<sect3>
<title>Deploying your Apache MyFaces JSF Portlet</title>
<para>
- If you did not expand the
<filename>helloworldjsfmyfacesportlet.war</filename> file, copy the
<filename>HelloWorldJSFMyFaces42Portlet/helloworldjsfmyfacesportlet.war</filename>
file into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. If you expanded the
<filename>helloworldjsfmyfacesportlet.war</filename> file, copy the
<filename>HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using JBoss AS, copy the WAR file or the expanded
directory into the <filename>$JBOSS_HOME/server/default/deploy/</filename>
directory.
+ If you did not expand the
<filename>helloworldjsfmyfacesportlet.war</filename> file, copy the
<filename>HelloWorldJSFMyFaces42Portlet/helloworldjsfmyfacesportlet.war</filename>
file into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. If you expanded the
<filename>helloworldjsfmyfacesportlet.war</filename> file, copy the
<filename>HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using the
<computeroutput>default</computeroutput> JBoss AS profile, copy the WAR file
or the expanded directory into the
<filename>$JBOSS_HOME/server/default/deploy/</filename> directory.
</para>
<para>
- Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss
Portal, will trigger a hot-deploy of the portlet.
+ Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss
Portal, triggers a hot-deploy of the portlet.
</para><para>
To see the HelloWorldJSFMyFaces42Portlet, navigate to <ulink
url="http://localhost:8080/portal/"></ulink>, or, if the default JBoss
Portal page is already open, refresh the page. The HelloWorldJSFMyFaces42Portlet is added
to the bottom of the default JBoss Portal page:
</para>
@@ -1555,7 +1556,7 @@
</mediaobject>
</para>
<para>
- To re-deploy the portlet, for example, if you have made changes to any of the
application descriptors, touch the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml</filename>
file. This will only work if you copied the
<filename>HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/</filename>
directory into the JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. On Linux, run the following command to re-deploy the
HelloWorldJSFMyFaces42Portlet:
+ To re-deploy the portlet, for example, if you have made changes to any of the
application descriptors, touch the
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml</filename>
file. This only works if you copied the
<filename>HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/</filename>
directory into the JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. On <trademark class="registered">Linux</trademark>, run
the following command to re-deploy the HelloWorldJSFMyFaces42Portlet:
</para>
<para>
<screen>
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/urls.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/urls.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/urls.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -16,57 +16,63 @@
<email>roy(a)jboss.org</email>
</author>
</chapterinfo>
- <title>Portal urls</title>
+ <title>Portal URLs</title>
<sect1>
- <title>Introduction</title>
- <para>Most of the time portals use very complicated urls, however it is
possible to setup
- entry points in the portal that follow simple patterns.</para>
- <para>Each portal container can contain multiple portals and within a given
portal, windows
- are organized in pages, a page simply being a collection of windows
associated to a
- name.</para>
- <para>Before reading this chapter you must know how to define a page and a
portal, you can
- refer to the chapter about XML descriptors to have a better understanding of
those
- notions.</para>
+ <title>Introduction to Portals</title>
+ <para>
+ Portal URLs are often very complicated; however, it is possible to setup entry points
in portals that follow simple patterns.
+ </para>
+ <para>
+ Each portal container can contain multiple portals. Within a given portal, windows are
organized into pages, with a page being a collection of windows associated to a name:
+ </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/tutorials/SpecPortalDef.png" valign="middle"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ <para>
+ Before reading the following sections, be familiar with how to define pages and
portal. Refer to <xref linkend="desc_example_page" /> for details.
+ </para>
</sect1>
<sect1>
- <title>Accessing a portal</title>
- <para>Each portal container can contains multiple portals, also there is
one special portal
- which is the default portal, i.e the one used when no portal is specified in
particular.
- <itemizedlist> The following examples show you how the selection is
done.
- <listitem>"/portal", will point to the default page of the
default portal.</listitem>
- <listitem>"/portal/portalname/" will point to the default
page of the portal
- <literal>portalname</literal>
- </listitem>
- </itemizedlist>
- </para>
+ <title>Accessing a Portal</title>
+ <para>
+ The <computeroutput>default</computeroutput> portal is used when no portal
is specified. How selection is done:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <computeroutput>/portal/</computeroutput> points to the default page of
the default portal.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>/portal/<replaceable>portal-name</replaceable>/</computeroutput>
points to the default page of the <replaceable>portal-name</replaceable>
portal.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
</sect1>
<sect1>
- <title>Accessing a page</title>
- <para>It is possible to have multiple pages per portal. As for portal there
is a default
- page for a given portal. Once the portal has been selected, then a page must
be used and
- all the windows present in that page will be rendered. The page selection
mechanism is
- the following.
- <itemizedlist>
- <listitem>"/portal/default/pageName" will render the
<literal>pageName</literal>
- page.</listitem>
- </itemizedlist>
- </para>
+ <title>Accessing a Page</title>
+ <para>
+ Each portal can have multiple pages, with each portal having a default page. When a
portal is selected, a page must be used, and all windows in that page are rendered. The
page selection mechanism is as follows:
+ </para>
+ <para>
+ <computeroutput>/portal/default/<replaceable>page-name</replaceable></computeroutput>
renders the <replaceable>page-name</replaceable> page.
+ </para>
</sect1>
<sect1>
<title>Accessing CMS Content</title>
- <para>The CMSPortlet delivers content transparently, without modifying the
url displayed.
- However, if you wish to deliver binary content (gif, jpeg, pdf, zip, etc...),
it is
- desirable to display this content outside of the confines of the portal.
- <itemizedlist>
- <listitem>
-
<literal>"/content/default/images/jboss_logo.gif"</literal> will
display the
- <literal>jboss_logo.gif</literal> outside of the portal.
This is accomplished as
- the portal interprets any path beginning with
<literal>/content</literal> as a
- request for CMS content. As long as the mime-type is not
<literal>text/html</literal>
- or <literal>text/text</literal>, it will be rendered
independently of the portal.
- </listitem>
- </itemizedlist>
- </para>
+ <para>
+ The <emphasis>CMSPortlet</emphasis> delivers content transparently, without
modifying the displayed URL. It is desirable to display binary content, such as GIF, JPEG,
PDF, ZIP, and so on, outside of the confines of the portal. For example,
<computeroutput>/content/default/images/jboss_logo.gif</computeroutput>
displays the <computeroutput>jboss_logo.gif</computeroutput> file outside of
the portal.
+ </para>
+ <para>
+ To display content outside of the portal, the portal interprets any path beginning with
<computeroutput>/content</computeroutput> as a request for CMS content. As
long as the <computeroutput><mime-type></computeroutput> is not
<computeroutput>text/html</computeroutput>, or
<computeroutput>text/text</computeroutput>, and the path to the content begins
with <computeroutput>/content</computeroutput>, the content is rendered
independently, outside of the portal.
+ </para>
</sect1>
<!--
<sect1>
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/wsrp.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/wsrp.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/wsrp.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -937,7 +937,7 @@
in the default registration policy. This allows users to define their own
validation mechanism.
</para>
<para>
- Please refer to the Javadoc for
<classname>org.jboss.portal.registration.RegistrationPolicy</classname>
+ Please refer to the <trademark
class="trade">Javadoc</trademark> for
<classname>org.jboss.portal.registration.RegistrationPolicy</classname>
and
<classname>org.jboss.portal.Registration.policies.RegistrationPropertyValidator</classname>
for more
details on what is expected of each method.
</para>
Modified:
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml
===================================================================
---
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml 2008-06-12
12:45:42 UTC (rev 10998)
+++
docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml 2008-06-12
13:28:43 UTC (rev 10999)
@@ -10,7 +10,7 @@
<title>XML Descriptors</title>
<sect1>
<title>Changes from previous releases</title>
- <para>The previous releases of JBoss Portal did not have an external schema
to validate the various XML descriptors; however, it was internally validated by the
portal. Since JBoss Portal 2.6, a Document Type Definition (DTD) has been provided to
validate descriptors.
+ <para>The previous releases of JBoss Portal did not have an external schema
to validate XML descriptors; however, they were internally validated by the portal. Since
JBoss Portal 2.6, a Document Type Definition (DTD) has been provided to validate
descriptors.
</para>
<para>
To use the DTD, add the following declaration to the start of the desired
descriptors:
@@ -24,7 +24,7 @@
</screen>
</para>
<para>
- If you do not use the DTD declaration, the previous mechanism for XML validation will
be used. The DTD is more strict, specifically with the order of XML elements. The
following is an example from a <filename>*-object.xml</filename> descriptor,
which will be valid if you are not using the DTD, but will be rejected if you are:
+ If you do not use the DTD declaration, the previous mechanism for XML validation is
used. The DTD is more strict, specifically with the order of XML elements. The following
is an example from a <filename>*-object.xml</filename> descriptor, which is
valid if you are not using the DTD, but is rejected if you are:
</para>
<para>
<screen><![CDATA[
@@ -33,7 +33,7 @@
</screen>
</para>
<para>
- The correct element order, and one which would be valid against the DTD, would be
as follows:
+ The correct element order, and one which is valid against the DTD, is as
follows:
</para>
<para>
<screen><![CDATA[
@@ -74,7 +74,7 @@
<sect2>
<title>The JBoss Portlet DTD</title>
<para>
- The following list refers to elements found in the JBoss Portlet DTD,
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/jboss-portlet_<replaceable>version_number</replaceable>.dtd</filename>:
+ The following items refer to elements found in the JBoss Portlet DTD,
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/jboss-portlet_<replaceable>version_number</replaceable>.dtd</filename>:
</para>
<para>
<variablelist>
@@ -86,23 +86,24 @@
Use the <computeroutput><remotable></computeroutput> element
to configure the default behavior of portlets with respect to WSRP exposure: if no value
is given, the value is either the value globally defined at the portlet application level,
or <computeroutput>false</computeroutput>. Accepted values are
<computeroutput>true</computeroutput> and
<computeroutput>false</computeroutput>.
</para>
<para>
- You can configure specific settings for the portlet container for each portlet defined
in the <filename>WEB-INF/portlet.xml</filename> file. Use the
<computeroutput><service></computeroutput> element to inject
services into the portlet context of applications.
+ You can configure specific settings of the portlet container for each portlet defined
in the <filename>WEB-INF/portlet.xml</filename> file. Use the
<computeroutput><service></computeroutput> element to inject
services into the portlet context of applications.
</para>
</listitem>
</varlistentry>
<varlistentry><term><screen><![CDATA[
-<!ELEMENT portlet
(portlet-name,remotable?,ajax?,session-config?,transaction?,header-content?,portlet-info?)>]]>
+<!ELEMENT portlet (portlet-name,remotable?,ajax?,session-config?,transaction?,
+header-content?,portlet-info?)>]]>
</screen></term>
<listitem>
<para>
- Additional configuration for the portlet. The
<computeroutput><portlet-name></computeroutput> element defines
the portlet name. It must match a portlet defined in the
<filename>WEB-INF/portlet.xml</filename> file for that application.
+ Additional configuration of the portlet. The
<computeroutput><portlet-name></computeroutput> element defines
the portlet name. It must match a portlet defined in the
<filename>WEB-INF/portlet.xml</filename> file for that application.
</para>
<para>
Use the <computeroutput><remotable></computeroutput> element
to configure the default behavior of portlets with respect to WSRP exposure: if no value
is given, the value is either the value globally defined at the portlet application level,
or <computeroutput>false</computeroutput>.
</para>
<para>
The <computeroutput><trans-attribute></computeroutput>
element specifies the behavior of the portlet when it is invoked at runtime with respect
to the transactional context. Depending on how the portlet is
- invoked, a transaction may or may not exist before the portlet is invoked. The portal
transaction is usually present in the local context. The default value is
<computeroutput>NotSupported</computeroutput>, which means that the portal
transaction will be suspended for the duration of the session. Accepted values are
<computeroutput>Required</computeroutput>,
<computeroutput>Mandatory</computeroutput>,
<computeroutput>Never</computeroutput>,
<computeroutput>Supports</computeroutput>,
<computeroutput>NotSupported</computeroutput>, and
<computeroutput>RequiresNew</computeroutput>.
+ invoked, a transaction may or may not exist before the portlet is invoked. The portal
transaction is usually present in the local context. The default value is
<computeroutput>NotSupported</computeroutput>, which means that the portal
transaction is suspended for the duration of the portlet's invocation. Accepted values
are <computeroutput>Required</computeroutput>,
<computeroutput>Mandatory</computeroutput>,
<computeroutput>Never</computeroutput>,
<computeroutput>Supports</computeroutput>,
<computeroutput>NotSupported</computeroutput>, and
<computeroutput>RequiresNew</computeroutput>.
</para>
<para>
The following is an example section from a
<filename>WEB-INF/portlet.xml</filename> file, which uses the
<computeroutput><portlet-name></computeroutput>,
<computeroutput><remotable></computeroutput>, and
<computeroutput><trans-attribute></computeroutput> elements:
@@ -148,7 +149,7 @@
</screen>
</para>
<para>
- If a portlet uses the <computeroutput>true</computeroutput> value for the
<computeroutput><partial-refresh></computeroutput> element, the
portal uses partial-page refreshing and only renders the portlet. If the
<computeroutput><partial-refresh></computeroutput> element uses
a <computeroutput>false</computeroutput> value, the portal uses a full-page
refresh when the portlet is refreshed.
+ If a portlet uses the <computeroutput>true</computeroutput> value for the
<computeroutput><partial-refresh></computeroutput> element, the
portal uses partial-page refreshing and only renders that portlet. If the
<computeroutput><partial-refresh></computeroutput> element uses
a <computeroutput>false</computeroutput> value, the portal uses a full-page
refresh when the portlet is refreshed.
</para>
</listitem>
</varlistentry>
@@ -157,7 +158,7 @@
</screen></term>
<listitem>
<para>
- The <computeroutput><session-config></computeroutput> element
configures the portlet session of the portlet. The
<computeroutput><distributed></computeroutput> element instructs
the container to distribute the session attributes using portal session replication. This
only applies to local portlets, not remote portlets.
+ The <computeroutput><session-config></computeroutput> element
configures the portlet session for the portlet. The
<computeroutput><distributed></computeroutput> element instructs
the container to distribute the session attributes using portal session replication. This
only applies to local portlets, not remote portlets.
</para>
<para>
The following is an example of the
<computeroutput><session-config></computeroutput> and
<computeroutput><distributed></computeroutput> elements:
@@ -184,10 +185,10 @@
</screen></term>
<listitem>
<para>
- Define how the portlet behaves with the transactional context. The
<computeroutput><trans-attribute></computeroutput> element
specifies the behavior of the portlet when it is invoked at runtime, with respect to the
transactional context. Depending on how the portlet is invoked, a transaction may or may
not exist before the portlet is invoked. The portal transaction is usually present in the
local context.
+ The <computeroutput><transaction></computeroutput> element
defines how the portlet behaves with regards to the transactional context. The
<computeroutput><trans-attribute></computeroutput> element
specifies the behavior of the portlet when it is invoked at runtime, with respect to the
transactional context. Depending on how the portlet is invoked, a transaction may or may
not exist before the portlet is invoked. The portal transaction is usually present in the
local context.
</para>
<para>
- The following is an example of the
<computeroutput><trans-attribute></computeroutput> element:
+ The following is an example of the
<computeroutput><transaction></computeroutput> and
<computeroutput><trans-attribute></computeroutput> elements:
</para>
<para>
<screen><![CDATA[
@@ -202,16 +203,16 @@
</screen>
</para>
<para>
- The default value is <computeroutput>NotSupported</computeroutput>, which
means that the portal transaction will be suspended for the duration of the portlet
invocation. Accepted values are <computeroutput>Required</computeroutput>,
<computeroutput>Mandatory</computeroutput>,
<computeroutput>Never</computeroutput>,
<computeroutput>Supports</computeroutput>,
<computeroutput>NotSupported</computeroutput>, and
<computeroutput>RequiresNew</computeroutput>.
+ The default value is <computeroutput>NotSupported</computeroutput>, which
means that the portal transaction is suspended for the duration of the portlet's
invocation. Accepted values are <computeroutput>Required</computeroutput>,
<computeroutput>Mandatory</computeroutput>,
<computeroutput>Never</computeroutput>,
<computeroutput>Supports</computeroutput>,
<computeroutput>NotSupported</computeroutput>, and
<computeroutput>RequiresNew</computeroutput>.
</para>
</listitem>
</varlistentry>
<varlistentry><term><screen><![CDATA[
-<!ELEMENT header-content (link | script | meta)*>]]>
+<!ELEMENT header-content (link|script|meta)*>]]>
</screen></term>
<listitem>
<para>
- Specify content to be included in the portal aggregated page when the portlet is
present on that page. This setting only applies when the portlet is used in the local
mode.
+ Specify the content to be included in the portal aggregated page when the portlet is
present on that page. This setting only applies when the portlet is used in the local
mode.
</para>
<para>
<screen><![CDATA[
@@ -291,7 +292,7 @@
</screen>
</para>
<para>
- The <computeroutput><service-ref></computeroutput> defines
the reference to the service. In the JMX Microkernel environment, this consist of the JMX
name of the service MBean. For an MBean reference, if the domain is left out, then the
current domain of the portal is used.
+ The <computeroutput><service-ref></computeroutput> element
defines the reference to the service. In the JMX Microkernel environment, this consist of
the JMX name of the service MBean. For an MBean reference, if the domain is left out, the
current domain of the portal is used.
</para>
</listitem>
</varlistentry>
@@ -299,38 +300,50 @@
</para>
</sect2>
<sect2>
- <title>Portlet Instance DTD</title>
- <para>
-<itemizedlist>
+ <title>The JBoss Portlet Instance DTD</title>
+ <para>
+ The following items refer to elements found in the JBoss Portlet Instance DTD,
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/portlet-instances_<replaceable>version_number</replaceable>.dtd</filename>:
+ </para>
+ <para>
+ <variablelist>
+ <varlistentry><term><screen><![CDATA[
+<!ELEMENT deployments (deployment*)>]]>
+</screen></term>
<listitem>
-<para>
-Element <![CDATA[<!ELEMENT deployments (deployment*)>]]>
-</para><para><programlisting><![CDATA[
-The deployements element is a container for deployment
elements.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT deployment (if-exists?,instance)>
-
-]]>
-</para><para><programlisting><![CDATA[The deployment is a container
for an instance element.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT if-exists (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The if-exists element is used
to define action to take if instance with such name is
-already present. Possible values are overwrite or keep . Overwrite will destroy the
-existing object in the database and create a new one, based on the content of the
-deployment. Keep will maintain the existing object deployment or create a new one if
-it does not yet exist.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT instance
(instance-id,portlet-ref,preferences?,security-constraint?)>]]>
-</para><para><programlisting><![CDATA[The instance element is used
to create an instance of a portlet from the portlet
-application of the same war file containing the portlet-instances.xml file. The portlet
-will be created and configured only if the portlet is present and an instance with
-such a name does not already exist.
-
-Example :
-
+ <para>
+ The <computeroutput><deployments></computeroutput> element is
a container for <computeroutput><deployment></computeroutput>
elements.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT deployment (if-exists?,instance)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><deployment></computeroutput> element is
a container for the <computeroutput><instance></computeroutput>
element.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT if-exists (#PCDATA)>]]>
+</screen>
+</para>
+ <para>
+ The <computeroutput><if-exists></computeroutput> element
defines the action to take if an instance with the same name already exists. Accepted
values are <computeroutput>overwrite</computeroutput> and
<computeroutput>keep</computeroutput>. The
<computeroutput>overwrite</computeroutput> option destroys the existing
object, and creates a new one based on the content of the deployment. The
<computeroutput>keep</computeroutput> option maintains the existing object
deployment, or creates a new one if it does not exist.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT instance (instance-id,portlet-ref,display-name*,preferences?,
+security-constraint?, (display-name* | (resource-bundle, supported-locale+)))>]]>
+</screen></term>
+<listitem>
+ <para>
+ The <computeroutput><instance></computeroutput> element is
used in the <filename>WEB-INF/portlet-instances.xml</filename> file, which
creates instances of portlets. The portlet will only be created and configured if the
portlet is present, and if an instance with the same name does not already exist.
+ </para>
+ <para>
+ The following is an example of the
<computeroutput><instance></computeroutput> element, which also
contains the
<computeroutput><security-constraint></computeroutput> element.
Descriptions of each element follow afterwards:
+ </para>
+ <para>
+<screen><![CDATA[
<instance>
<instance-id>MyPortletInstance</instance-id>
<portlet-ref>MyPortlet</portlet-ref>
@@ -346,38 +359,69 @@
<action-name>view</action-name>
</policy-permission>
</security-constraint>
-</instance>]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT instance-id (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The identifier of the
instance.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT portlet-ref (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The reference to the portlet
which is its portlet name.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT preferences (preference)>]]>
-</para><para><programlisting><![CDATA[The preferences element
configures the instance with a specific set of
preferences.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT preference (name,value)>]]>
-</para><para><programlisting><![CDATA[The preference configure one
preference of a set of preferences.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[A
name.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT value (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[A string
value.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT security-constraint (policy-permission*)>]]>
-</para><para><programlisting><![CDATA[The security-constraint
element is a container for policy-permission elements
-
-Examples:
-
+</instance>]]>
+</screen>
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT instance-id (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The instance identifier. The
<computeroutput><instance-id></computeroutput> value can be
named anything, but it must match the
<computeroutput><instance-ref></computeroutput>value given in
the <filename>*-object.xml</filename> file.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT portlet-ref (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><portlet-ref></computeroutput> element
defines the portlet that an instance represents. The
<computeroutput><portlet-ref></computeroutput> value must match
the <computeroutput><portlet-name></computeroutput> given in the
<filename>WEB-INF/portlet.xml</filename> file.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT preferences (preference+)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><preferences></computeroutput> element
configures an instance with a set of preferences.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT preference (name,value)>]]>
+</screen></term>
+<listitem>
+ <para>
+ The <computeroutput><preference></computeroutput> element
configures one preference, which is part of a set of preferences. Use the
<computeroutput><preferences></computeroutput> element to define
a set of preferences.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ A name.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT value (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ A string value.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT security-constraint (policy-permission*)>]]>
+</screen></term>
+<listitem>
+ <para>
+ The <computeroutput><security-constraint></computeroutput>
element is a container for
<computeroutput><policy-permission></computeroutput> elements.
The following is an example of the
<computeroutput><security-constraint></computeroutput> and
<computeroutput><policy-permission></computeroutput> elements:
+ </para>
+ <para>
+<screen><![CDATA[
<security-constraint>
<policy-permission>
<role-name>User</role-name>
@@ -390,194 +434,352 @@
<unchecked/>
<action-name>view</action-name>
</policy-permission>
-</security-constraint>]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT policy-permission
(action-name*,unchecked?,role-name*)>]]>
-</para><para><programlisting><![CDATA[The policy-permission element
is used to secure a specific portlet instance based on a user's
role.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT action-name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The action-name element is
used to define the access rights given to the role defined.
-Possible values are:
-
- * view - Users can view the page.
- * viewrecursive - Users can view the page and child pages.
- * personalize - Users are able personalize the page's theme.
- * personalizerecursive - Users are able personalize the page AND its children's
themes.
- pages.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT unchecked EMPTY>]]>
-</para><para><programlisting><![CDATA[The unchecked element is used
to define (if present) that anyone can view this
instance]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT role-name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The role-name element is used
to define a role that this security constraint will apply to
-
- * <role-name>SOMEROLE</role-name> Access to this instance is limited to
the defined role.]]></programlisting></para>
-</listitem></itemizedlist>
- </para>
+</security-constraint>]]>
+</screen>
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)>]]>
+</screen></term>
+<listitem>
+ <para>
+ The <computeroutput><policy-permission></computeroutput>
element secures a specific portlet instance based on a user's role.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT action-name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><action-name></computeroutput> element
defines the access rights given to the role defined. Accepted values are:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <computeroutput>view</computeroutput>: users can view the page.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>viewrecursive</computeroutput>: users can view the page
and child pages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>personalize</computeroutput>: users are able personalize
the page's theme.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>personalizerecursive</computeroutput>: users are able
personalize the page and child pages themes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT unchecked EMPTY>]]>
+</screen>
+ </para>
+ <para>
+ If present, the <computeroutput><unchecked></computeroutput>
element defines anyone can view the instance.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT role-name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><role-name></computeroutput> element
defines a role that the security constraint will apply to. The following example only
allows users that are part of the <computeroutput>EXAMPLEROLE</computeroutput>
role to access the instance:
+ </para>
+ <para>
+<screen><![CDATA[
+<role-name>EXAMPLEROLE</role-name>]]>
+</screen>
+ </para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
</sect2>
<sect2>
- <title>Portal Object DTD</title>
+ <title>The JBoss Portal Object DTD</title>
<para>
-<itemizedlist>
+ The following items refer to elements found in the JBoss Portal Object DTD,
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/portal-object_<replaceable>version_number</replaceable>.dtd</filename>:
+ </para>
+ <para>
+ <variablelist>
+ <varlistentry><term><screen><![CDATA[
+<!ELEMENT deployments (deployment*)>]]>
+</screen></term>
<listitem>
-<para>
-Element <![CDATA[<!ELEMENT deployments (deployment*)>]]>
-</para><para><programlisting><![CDATA[The deployements element is a
generic container for deployment elements.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT deployment (parent-ref,if-exists?,(context | portal |
page | window))>]]>
-</para><para><programlisting><![CDATA[The deployment is a generic
container for portal object elements. The parent-ref
-child gives the name of the parent object that the current object will use as parent.
-The optional if-exists element define the behavior when a portal object which
-an identical name is already child of the parent element. The default behavior of
-the if-exist tag is to keep the existing object and not create a new object. The
-last element is the portal object itself.
-
-Example:
-
+ <para>
+ The <computeroutput><deployments></computeroutput> element is
a container for <computeroutput><deployment></computeroutput>
elements.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT deployment (parent-ref?,if-exists?,(context|portal|page|window))>]]>
+</screen></term>
+<listitem>
+ <para>
+ The <computeroutput><deployment></computeroutput> element is
a generic container for portal object elements. The
<computeroutput><parent-ref></computeroutput> child element
gives the name of the parent object that the current object will use as parent. The
optional <computeroutput><if-exists></computeroutput> element
defines the action to take if an instance with the same name already exists. The default
behavior of the <computeroutput><if-exists></computeroutput>
element is to keep the existing object, and not to create a new object.
+ </para>
+ <para>
+ The following is an example of the
<computeroutput><deployment></computeroutput> and
<computeroutput><parent-ref></computeroutput> elements:
+ </para>
+ <para>
+<screen><![CDATA[
<deployment>
<parent-ref>default</parent-ref>
<page>
...
</page>
-</deployment>
-
-All portal objects have a common configuration which can be :
-
-1/ a listener : specifies the id of a listener is the listener registry. A listener
-object is able to listen portal events which apply to the portal node hierarchy.
-
-2/ properties : a set of generic properties owned by the portal object. Some
-properties can drive the behavior of the object.
-
-3/ security-constraint : defines security configuration of the portal
object.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT parent-ref (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[Contains a reference to the
parent object. The naming convention for naming object
-is to concatenate the names of the path to the object and separate the names by a dot.
-If the path is empty then the empty string must be used.
-
-Example:
-
-<parent-ref/> the root having an empty path
-
-<parent-ref>default</parent-ref> the object with the name default under the
root
-having the path (default)
-
-<parent-ref>default.default</parent-ref> the object with the path
(default,default)]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT if-exists (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The authorized values are
overwrite and keep. Overwrite means that the existing
-object will be destroyed and the current declaration will be used. Keep means that
-the existing object will not be destroyed and no creation hence will be
done.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT context
(context-name,properties?,listener?,security-constraint?,portal*)>]]>
-</para><para><programlisting><![CDATA[A portal object of type
context. A context type represent a node in the tree which
-does not have a visual representation. It can exist only under the root. A context can
-only have children with the portal type.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT context-name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The context name
value.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT portal
(portal-name,supported-modes,supported-window-states?,properties?,listener?,security-constraint?,page*)>]]>
-</para><para><programlisting><![CDATA[
-A portal object of type portal. A portal type represents a virtual portal and can
-have children of type page. In addition of the common portal object elements it support
-also the declaration of the modes and the window states it supports. If no declaration
-of modes or window states is done then the default value will be respectively
-(view,edit,help) and
(normal,minimized,maximized).]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT portal-name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The portal name
value.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT supported-modes (mode*)>]]>
-</para><para><programlisting><![CDATA[The supported modes of a
portal.
-
-Example:
-
+</deployment>]]>
+</screen>
+ </para>
+ <para>
+ All portal objects have a common configuration which can include:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ a listener: specifies the ID of a listener in the listener registry. A listener
object is able to listen to portal events, which apply to the portal node hierarchy.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ properties: a set of generic properties owned by the portal object. Certain
properties drive the behavior of the portal object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ security-constraint: defines the security configuration for the portal object.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT parent-ref (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><parent-ref></computeroutput> element
contains a reference to the parent object. The naming convention for naming objects is to
concatenate the names of the path to the object, and separate the names using a period. If
the path is empty, the empty string must be used. The
<computeroutput><parent-ref></computeroutput> element tells the
portal where the portlet appears. The syntax for the
<computeroutput><parent-ref></computeroutput> element is
<computeroutput><replaceable>portal-instance</replaceable>.<replaceable>portal-page</replaceable></computeroutput>.
+ </para>
+ <para>
+ The following is an example of the root having an empty path:
+ </para>
+ <para>
+<screen>
+<parent-ref/>
+</screen>
+ </para>
+ <para>
+ The following specifies that the portlet appears in the portal instance named
<computeroutput>default</computeroutput>:
+ </para>
+ <para>
+<screen>
+<parent-ref>default</parent-ref>
+</screen>
+ </para>
+ <para>
+ The following specifies that the portlet appear in the portal instance named
<computeroutput>default</computeroutput>, and on the page named
<computeroutput>default</computeroutput>:
+ </para>
+ <para>
+<screen>
+<parent-ref>default.default</parent-ref>
+</screen>
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT if-exists (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><if-exists></computeroutput> element
defines the action to take if an instance with the same name already exists. Accepted
values are <computeroutput>overwrite</computeroutput> and
<computeroutput>keep</computeroutput>. The
<computeroutput>overwrite</computeroutput> option destroys the existing
object, and creates a new one based on the content of the deployment. The
<computeroutput>keep</computeroutput> option matains the existing object
deployment, or creates a new one if it does not exist.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT context (context-name,properties?,listener?,security-constraint?,portal*,
+(display-name* | (resource-bundle, supported-locale+)))>]]>
+</screen></term>
+<listitem>
+ <para>
+ The context type of the portal object. A context type represent a node in a tree, which
does not have a visual representation, and only exists under the root. A context can only
have children that use the <emphasis>portal</emphasis> type.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT context-name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The context name.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT portal
(portal-name,supported-modes,supported-window-states?,properties?,listener?,
+security-constraint?,page*, (display-name* | (resource-bundle,
supported-locale+)))>]]>
+</screen></term>
+<listitem>
+ <para>
+ A portal object that uses the <emphasis>portal</emphasis> type. A portal
type represents a virtual portal, and can only have children that use the
<emphasis>page</emphasis> type. In addition to the common portal object
elements, it also allows you to declare modes and window states that are supported.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT portal-name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The portal name.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT supported-modes (mode*)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><supported-modes></computeroutput>
elements defines the supported modes of the portal. Accepted values are
<computeroutput>view</computeroutput>,
<computeroutput>edit</computeroutput>, and
<computeroutput>help</computeroutput>.
+ </para>
+ <para>
+ The following is an example of the
<computeroutput><supported-mode></computeroutput> and
<computeroutput><mode></computeroutput> elements:
+ </para>
+ <para>
+<screen><![CDATA[
<supported-mode>
<mode>view</mode>
<mode>edit</mode>
<mode>help</mode>
-</supported-mode>]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT mode (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[
-A portlet mode value.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT supported-window-states (window-state*)>]]>
-</para><para><programlisting><![CDATA[
-The supported window states of a portal.
-
-Example:
-
+</supported-mode>]]>
+</screen>
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT mode (#PCDATA)>]]>
+</screen></term>
+<listitem>
+ <para>
+ The portlet mode value. If there are no declarations of modes or window states, the
default values are <computeroutput>view</computeroutput>,
<computeroutput>edit</computeroutput>,
<computeroutput>help</computeroutput>, and
<computeroutput>normal</computeroutput>,
<computeroutput>minimized</computeroutput>,
<computeroutput>maximized</computeroutput>, respectively.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT supported-window-states (window-state*)>]]>
+</screen></term>
+<listitem>
+ <para>
+ Use the
<computeroutput><supported-window-states></computeroutput>
element to define the supported window states of the portal. The following is an example
of the
<computeroutput><supported-window-states></computeroutput> and
<computeroutput><window-state></computeroutput> elements:
+ </para>
+ <para>
+<screen><![CDATA[
<supported-window-states>
<window-state>normal</window-state>
<window-state>minimized</window-state>
<window-state>maximized</window-state>
-</supported-window-states>]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT window-state (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[A window state
value.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT page
(page-name,properties?,listener?,security-constraint?,(page | window)*)>]]>
-</para><para><programlisting><![CDATA[A portal object of type page.
A page type represents a page which can have children of
-type page and window. The children windows are the windows of the page and the children
-pages are the subpages of this page.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT page-name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The page name
value.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT window (window-name,(instance-ref |
content),region,height,properties?,listener?)>
-
-]]>
-</para><para><programlisting><![CDATA[A portal object of type
window. A window type represents a window. Beside the common
-properties a window has a content and belong to a region on the page.
-
-The instance-ref or content tags are used to define the content of the window. The
-usage of the content tag is generic and can be used to describe any kind of content.
-The instance-ref is a shortcut to define a content type of portlet which points to a
-portlet instance.
-
-The region and height defines how the window is placed in the
page.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT window-name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The window name
value.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT instance-ref (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[Define the content of the
window as a reference to a portlet instance. The value
-is the id of the instance.
-
-Example:
-
-<instance-ref>MyPortletInstance</instance-ref>]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT content (content-type,content-uri)>]]>
-</para><para><programlisting><![CDATA[Define the content of the
window in a generic manner. The content is define by
-the type of the content and an URI which acts as an identificator for the content.
-
-Example:
-
+</supported-window-states>]]>
+</screen>
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT window-state (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ Use the <computeroutput><window-state></computeroutput>
element to define a window states. Accepted values are
<computeroutput>normal</computeroutput>,
<computeroutput>minimized</computeroutput>, and
<computeroutput>maximized</computeroutput>.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT page (page-name,properties?,listener?,security-constraint?,(page |
window)*,
+(display-name* | (resource-bundle, supported-locale+)))>]]>
+</screen></term>
+<listitem>
+ <para>
+ A portal object that uses the <emphasis>page</emphasis> type. A page type
represents a page, and can only have children that use the
<emphasis>page</emphasis> and <emphasis>window</emphasis> types.
The children windows are the windows of the page, and the children pages are the subpages
of the page.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT page-name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The page name.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT window
(window-name,(instance-ref|content),region,height,initial-window-state?,
+initial-mode?,properties?,listener?, (display-name* | (resource-bundle,
supported-locale+)))>]]>
+</screen></term>
+<listitem>
+ <para>
+ A portal object that uses the <emphasis>window</emphasis> type. A window
type represents a window. Besides the common properties, a window has content, and belongs
to a region on the page.
+ </para>
+ <para>
+ The <computeroutput><instance-ref></computeroutput> and
<computeroutput><content></computeroutput> elements, configured
in the <filename>WEB-INF/*-object.xml</filename> files, define the content of
a window. The <computeroutput><content></computeroutput> element
is generic, and describes any kind of content. The
<computeroutput><instance-ref></computeroutput> element is a
shortcut to define the content-type of the portlet, which points to a portlet instance.
The value of <computeroutput><instance-ref></computeroutput>
must match the value of one of the
<computeroutput><instance-id></computeroutput> elements in the
<filename>WEB-INF/portlet-instances.xml</filename> file.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT window-name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The window name value.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT instance-ref (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ Define the content of the window as a reference to a portlet instance. This value is
the ID of a portlet instance, and must much the value of one of the
<computeroutput><instance-id></computeroutput> elements in the
<filename>WEB-INF/portlet-instances.xml</filename> file. The following is an
example of the <computeroutput><instance-ref></computeroutput>
element:
+ </para>
+ <para>
+<screen>
+<instance-ref>MyPortletInstance</instance-ref>
+</screen>
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT region (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The region the window belongs to. The
<computeroutput><region></computeroutput> element specifies
where the window appears on the page.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT height (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The height of the window in a particular region.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT listener (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ Define a listener for a portal object. This value is the ID of the listener.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT content (content-type,content-uri)>]]>
+</screen></term>
+<listitem>
+ <para>
+ Define the content of a window in a generic manner. The content is defined by the type
of content, and a URI, which acts as an identifier for the content. The following is an
example of the <computeroutput><content></computeroutput>
element, which is configured in the <filename>WEB-INF/*-object.xml</filename>
files:
+ </para>
+ <para>
+<screen><![CDATA[
<content>
<content-type>portlet</content-type>
<content-uri>MyPortletInstance</content-uri>
@@ -586,50 +788,71 @@
<content>
<content-type>cms</content-type>
<content-uri>/default/index.html</content-uri>
-</content>]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT content-type (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The content type of the
window.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT content-uri (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The content URI of the
window.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT region (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The region the window belongs
to.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT height (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The height of the window in
the particular region.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT listener (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[Define a listener for a portal
object. The value is the id of the listener.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT properties (property*)>]]>
-</para><para><programlisting><![CDATA[A set of generic properties
for the portal object.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT property (name,value)>]]>
-</para><para><programlisting><![CDATA[A generic string
property.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[A name
value.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT value (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[A
value.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT security-constraint (policy-permission*)>]]>
-</para><para><programlisting><![CDATA[The security-constraint
element is a container for policy-permission elements
-
-Examples:
-
+</content>]]>
+</screen>
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT content-type (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The content type of the window. The
<computeroutput><content-type></computeroutput> element
specifies the content to display, for example, a
<computeroutput>portlet</computeroutput>.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT content-uri (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The content URI of the window. The
<computeroutput><content-uri></computeroutput> element specifies
which content to display, for example, a portlet instance. To display a file from the CMS,
use the <computeroutput><content-uri></computeroutput> element
to define the full path to that file in the CMS.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT properties (property*)>]]>
+</screen></term>
+<listitem>
+ <para>
+ A set of generic properties for the portal object. The
<computeroutput><properties></computeroutput> elements contains
definitions specific to a page. This is commonly used to define the specific theme and
layout to use. If not defined, the default portal theme and layout are used.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT property (name,value)>]]>
+</screen>
+ </para>
+ <para>
+ A generic string property.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT name (#PCDATA)>]]>
+</screen></term>
+<listitem>
+ <para>
+ A name value.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT value (#PCDATA)>]]>
+</screen></term>
+<listitem>
+ <para>
+ A value.
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT security-constraint (policy-permission*)>]]>
+</screen></term>
+<listitem>
+ <para>
+ The <computeroutput><security-constraint></computeroutput>
element is a container for
<computeroutput><policy-permission></computeroutput> elements.
The following is an example of the
<computeroutput><security-constraint></computeroutput> and
<computeroutput><policy-permission></computeroutput> elements:
+ </para>
+ <para>
+<screen><![CDATA[
<security-constraint>
<policy-permission>
<role-name>User</role-name>
@@ -642,79 +865,121 @@
<unchecked/>
<action-name>view</action-name>
</policy-permission>
-</security-constraint>]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT policy-permission
(action-name*,unchecked?,role-name*)>]]>
-</para><para><programlisting><![CDATA[The policy-permission element
is used to secure a specific portal page based on a user's
role.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT action-name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The role-name element is used
to define a role that this security constraint will apply to
-
- * <role-name>SOMEROLE</role-name> Access to this portal page is limited
to the defined role.]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT unchecked EMPTY>]]>
-</para><para><programlisting><![CDATA[The unchecked element is used
to define (if present) that anyone can view this portal
page]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT role-name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[The action-name element is
used to define the access rights given to the role defined.
-Possible values are:
-
- * view - Users can view the page.]]></programlisting></para>
-</listitem></itemizedlist>
-
- </para>
- </sect2>
+</security-constraint>]]>
+</screen>
+ </para>
+</listitem>
+</varlistentry>
+<varlistentry><term><screen><![CDATA[
+<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)>]]>
+</screen></term>
+ <listitem>
+ <para>
+ The <computeroutput><policy-permission></computeroutput>
element is secures a specific portlet instance based on a user's role.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT action-name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><action-name></computeroutput> element
defines the access rights given to the role defined. Accepted values are:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <computeroutput>view</computeroutput>: users can view the page.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>viewrecursive</computeroutput>: users can view the page
and child pages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>personalize</computeroutput>: users are able personalize
the page's theme.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>personalizerecursive</computeroutput>: users are able
personalize the page and child pages themes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT unchecked EMPTY>]]>
+</screen>
+ </para>
+ <para>
+ If present, the <computeroutput><unchecked></computeroutput>
element defines that anyone can view the instance.
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT role-name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><role-name></computeroutput> element
defines a role that the security constraint applies to. The following example only allows
users that are part of the <computeroutput>EXAMPLEROLE</computeroutput> role
to access the instance:
+ </para>
+ <para>
+<screen><![CDATA[
+<role-name>EXAMPLEROLE</role-name>]]>
+</screen>
+ </para>
+ </listitem>
+</varlistentry>
+</variablelist>
+</para>
+ </sect2>
<sect2>
- <title>JBoss App DTD</title>
+ <title>The JBoss Portal App DTD</title>
<para>
-<itemizedlist>
+ The following items refer to elements found in the JBoss Portal App DTD,
<filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/jboss-portal.sar/dtd/jboss-app_<replaceable>version_number</replaceable>.dtd</filename>:
+ </para>
+ <para>
+ <variablelist>
+ <varlistentry><term><screen><![CDATA[
+<Element <![CDATA[<!ELEMENT jboss-app (app-name?)>]]>
+</screen></term>
<listitem>
-<para>
-Element <![CDATA[<!ELEMENT jboss-app (app-name?)>]]>
-</para><para><programlisting><![CDATA[<!DOCTYPE jboss-app PUBLIC
+ <para>
+<screen><![CDATA[
+<!DOCTYPE jboss-app PUBLIC
"-//JBoss Portal//DTD JBoss Web Application 2.6//EN"
-
"http://www.jboss.org/portal/dtd/jboss-app_2_6.dtd">]]></programlisting></para>
-</listitem><listitem>
-<para>
-Element <![CDATA[<!ELEMENT app-name (#PCDATA)>]]>
-</para><para><programlisting><![CDATA[When a web application is
deployed, the context path under wich it is deployed
-is taken as application name. The application name value in this descriptor is
-used to override it. When a component references a references a portlet, it needs to
-reference the application too and if the portlet application war file is renammed
-the reference is not valid anymore. Therefore this tag is used to have an application
-name that does not depend upon the context path under which the application is
deployed.]]></programlisting></para>
-</listitem></itemizedlist>
-
+ "http://www.jboss.org/portal/dtd/jboss-app_2_6.dtd">]]>
+</screen>
+ </para>
+ <para>
+<screen><![CDATA[
+<!ELEMENT app-name (#PCDATA)>]]>
+</screen>
+ </para>
+ <para>
+ When a web application is deployed, the context path under which it is deployed
+ is taken as the application name. The application name value in the
<computeroutput><app-name></computeroutput> element overrides
it. When a component references a portlet, it needs to reference the application too, and
if the portlet application WAR file is renamed,
+ the reference is no longer valid; therefore, the
<computeroutput><app-name></computeroutput> element is used to
have an application name that does not depend upon the context path, under which the
application is deployed.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
</para>
</sect2>
</sect1>
<sect1 id="descriptors_portlet">
<title>Portlet Descriptors</title>
- <para>To define your portal objects (portals, pages, portlet instances,
windows, and portlets), you will be using
- the descriptors found in this section. This section seeks to describe these
descriptors. It is recommended you
- also look at
- <xref linkend="tutorials_tutorials"/>
- and
- <xref linkend="desc_examples"/>
- for samples on how they are used within a portlet application.
+ <para>
+ The following sections describe the descriptors that define portal objects, such
as portals, pages, portlet instances, windows, and portlets. Refer to <xref
linkend="tutorials_tutorials"/> and <xref
linkend="desc_examples"/> for examples on using these descriptors within a
portlet application.
</para>
<sect2 id="desc_objectxml">
- <title>*-object.xml</title>
+ <title><filename>*-object.xml</filename>
Descriptors</title>
<para>
- The *-object.xml file is used to define: portal instances, pages, windows,
window layout. Additionally,
- you can also specify the themes and layouts used for specific portal
instances, pages, and windows. The
- description below, only defines a portlet window being added to the default
page in the default portal. For
- advanced functionality, using this descriptor, please read <xref
linkend="desc_examples"/>.
-
- <note>
- <emphasis>Is this descriptor mandatory?</emphasis>
- Technically, no, as you can define your portal object hierarchy (create
portals, pages, instances and
- organize them as you see fit) from the management portlet accessible to
Portal administrators.
- </note>
+ The <filename>*-object.xml</filename> descriptors define portal
instances, pages, windows, and the window layout. As well, themes and layouts for specific
portal instances, pages, and windows, can be defined. The following example defines a
portlet window being added to the <computeroutput>default</computeroutput>
page, in the <computeroutput>default</computeroutput> portal. For advanced
functionality using these descriptors, refer to <xref
linkend="desc_examples"/>:
+ </para>
+ <para>
<programlisting><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
@@ -736,85 +1001,77 @@
<listitem>
<para>
<programlisting><![CDATA[<deployments>...</deployments>]]></programlisting>
- The
- <emphasis>deployments</emphasis>
- tag, encapsulates the entire document. You may specify more than one
deployment within this tag.
+ </para>
+ <para>
+ The <computeroutput><deployments></computeroutput>
element encapsulates the entire document, and is a container for
<computeroutput><deployment></computeroutput> elements. Multiple
deployments can be specified within the
<computeroutput><deployments></computeroutput> element.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<deployment>...</deployment>]]></programlisting>
- The
- <emphasis>deployment</emphasis>
- tag is used to specify object deployments: portals, pages, windows,
etc...
+ </para>
+ <para>
+ The
<computeroutput><deployment></computeroutput> element specifies
object deployments, such as portals, pages, windows, and so on.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<if-exists>...</if-exists>]]></programlisting>
- Possible values are
- <emphasis>overwrite</emphasis>
- or
- <emphasis>keep</emphasis>
- .
- <emphasis>Overwrite</emphasis>
- will destroy the existing object in the database and create a new
one, based on the
- content of the deployment.
- <emphasis>Keep</emphasis>
- will maintain the existing object deployment or create a new one if
- it does not yet exist.
- </para>
+ </para>
+ <para>
+ The <computeroutput><if-exists></computeroutput> element
defines the action to take if an instance with the same name already exists. Accepted
values are <computeroutput>overwrite</computeroutput> and
<computeroutput>keep</computeroutput>. The
<computeroutput>overwrite</computeroutput> option destroys the existing
object, and creates a new one based on the content of the deployment. The
<computeroutput>keep</computeroutput> option maintains the existing object
deployment, or creates a new one if it does not exist.
+ </para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<parent-ref>...</parent-ref>]]></programlisting>
- The
- <emphasis>parent-ref</emphasis>
- tag specifies where a particulare object will exist within the
portal object tree. In our example,
- above, we are defining a window and assigning it to
- <emphasis>default.default</emphasis>
- , interpreted, this means the window will appear in the default
portal and the default page within
- it.
+ </para>
+ <para>
+ The <computeroutput><parent-ref></computeroutput> element
contains a reference to the parent object. The naming convention for naming objects is to
concatenate the names of the path to the object, and separate the names using a period. If
the path is empty, the empty string must be used. The
<computeroutput><parent-ref></computeroutput> element tells the
portal where the portlet appears. The syntax for the
<computeroutput><parent-ref></computeroutput> element is
<computeroutput><replaceable>portal-instance</replaceable>.<replaceable>portal-page</replaceable></computeroutput>.
+ </para>
+ <para>
+ In the example above, a window is defined, and assigned to
<computeroutput>default.default</computeroutput>. This means the window
appears on the <computeroutput>default</computeroutput> page, in the
<computeroutput>default</computeroutput> portal.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<window>...</window>]]></programlisting>
- Used to define a portlet window. You will then need to assign to
this window, a portlet instance
- and assign it to a layout region.
+ </para>
+ <para>
+ The <computeroutput><window></computeroutput> element
defines a portlet window. The
<computeroutput><window></computeroutput> element requires an
<computeroutput><instance-ref></computeroutput> element, which
assigns a portal instance to a window.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<window-name>...</window-name>]]></programlisting>
- A
- <emphasis role="bold">unique name</emphasis>
- given to this portlet window.
+ </para>
+ <para>
+ The <computeroutput><window-name></computeroutput>
element defines the <emphasis role="bold">unique name</emphasis>
given to a portlet window. This can be named anything.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<instance-ref>...</instance-ref>]]></programlisting>
- The portlet instance that this window will represent. It must
correspond to the value of
- <emphasis>instance-id</emphasis>
- , assigned in your
- <emphasis>portlet-instances.xml</emphasis>
- </para>
+ </para>
+ <para>
+ The <computeroutput><instance-ref></computeroutput>
elements define the portlet instances that windows represent. This value is the ID of a
portlet instance, and must match the value of one of the
<computeroutput><instance-id></computeroutput> elements in the
<filename>WEB-INF/portlet-instances.xml</filename> file.
+ </para>
</listitem>
<listitem>
<para>
-
<programlisting><![CDATA[<region>...</region><height>...</height>]]></programlisting>
- The values are used to specify where this window will appear within
the page layout.
- <emphasis>Region</emphasis>
- often depends on regions defined in your layout.
- <emphasis>Height</emphasis>
- can be any number between 0-X.
+<programlisting><![CDATA[
+<region>...</region>
+<height>...</height>]]></programlisting>
+ </para>
+ <para>
+ The <computeroutput><region></computeroutput> and
<computeroutput><height></computeroutput> elements define where
the window appears within the page layout. The
<computeroutput><region></computeroutput> element specifies
where the window appears on the page. The
<computeroutput><region></computeroutput> element often depends
on other regions defined in the portal layout. The
<computeroutput><height></computeroutput> element can be
assigned a value between one and <replaceable>X</replaceable>.
</para>
</listitem>
</itemizedlist>
</para>
- <para>The example *-object.xml, above, makes reference to items found in
other descriptor files. To
- help with this topic, we have included a sample image that depicts the
relationship:
+ <para>The previous <filename>*-object.xml</filename> example makes
reference to items found in other descriptor files. The following diagram illustrates the
relationship between the <filename>portlet.xml</filename>,
<filename>portlet-instances.xml</filename>, and
<filename>*-object.xml</filename> descriptors:
+ </para>
+ <para>
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/first_portlet/desc_relationship.gif"
@@ -822,22 +1079,22 @@
</imageobject>
</mediaobject>
</para>
+ <para>
+ <note>
+ <title>Are <filename>*-object.xml</filename> descriptors
required?</title>
+ <para>
+ Technically, they are not. The portal object hierarchy, such as creating portals,
pages, instances, and organizing them on the page, can be defined using the management
portlet, which is accessible to JBoss Portal administrators.
+ </para>
+ </note>
+ </para>
</sect2>
<sect2 id="desc_instancesxml">
- <title>portlet-instances.xml</title>
- <para>This is a JBoss Portal specific descriptor that allows a developer
to instantiate one-or-many instances
- of one-or-many portlets. The benefit of using this technique, is to allow one
portlet to be instantiated
- several times with different preference parameters.
- <note>
- <emphasis>Is this descriptor mandatory?</emphasis>
- Technically, no, as you can define your portal object hierarchy (create
portals, pages, instances and
- organize them as you see fit) from the management portlet accessible to
Portal administrators.
- </note>
- Our example, below, has us instantiating two separate instances of the
- <emphasis>NewsPortlet</emphasis>
- with different preference parameters, one instance will draw a feed for
RedHat announcements and the other
- from McDonalds announcements.
- <programlisting><![CDATA[
+ <title>The <filename>portlet-instances.xml</filename>
Descriptor</title>
+ <para>
+ The <filename>portlet-instances.xml</filename> descriptor is JBoss Portal
specific, and allows developers to instantiate one-or-many instances of one-or-many
portlets. The benefit of this allows one portlet to be instantiated several times, with
different preference parameters. The following example instantiates two separate instances
of the <computeroutput>NewsPortlet</computeroutput>, both using different
parameters. One instance draws feeds from Red Hat announcements, and the other from
McDonalds announcements:
+ </para>
+ <para>
+<screen><![CDATA[
<?xml version="1.0" standalone="yes"?>
<!DOCTYPE deployments PUBLIC
"-//JBoss Portal//DTD Portlet Instances 2.6//EN"
@@ -845,7 +1102,7 @@
<deployments>
<deployment>
<instance>
- <instance-id>NewsPortletInstance2</instance-id>
+ <instance-id>NewsPortletInstance1</instance-id>
<portlet-ref>NewsPortlet</portlet-ref>
<preferences>
<preference>
@@ -888,116 +1145,134 @@
</instance>
</deployment>
</deployments>
-]]></programlisting>
+]]></screen>
+ </para>
+ <para>
<itemizedlist>
- <listitem>
+ <listitem>
+ <para>
+
<programlisting><![CDATA[<deployments>...</deployments>]]></programlisting>
+ </para>
+ <para>
+ The <computeroutput><deployments></computeroutput>
element encapsulates the entire document, and is a container for
<computeroutput><deployment></computeroutput> elements. Multiple
deployments can be specified within the
<computeroutput><deployments></computeroutput> element.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<programlisting><![CDATA[
+<deployment>
+ <instance>...</instance>
+</deployment>]]></programlisting>
+ </para>
+ <para>
+ The <computeroutput><deployment></computeroutput> element,
and the embedded <computeroutput><instance></computeroutput>
element, specify a portlet instance. The
<computeroutput><deployment></computeroutput> element specifies
object deployments, such as portals, pages, windows, and so on. The
<computeroutput><instance></computeroutput> element creates
instances of portlets. The portlet will only be created and configured if the portlet is
present, and if an instance with the same name does not already exist.
+ </para>
+ </listitem>
+ <listitem>
<para>
-
<programlisting><![CDATA[<deployments>...</deployments>]]></programlisting>
- The
- <emphasis>deployments</emphasis>
- tag, encapsulates the entire document. You may specify more than one
portlet instance deployment,
- within this tag.
- </para>
- </listitem>
- <listitem>
- <para>
-
<programlisting><![CDATA[<deployment><instance>...</instance></deployment>]]></programlisting>
- The
- <emphasis>deployment</emphasis>
- , and embedded
- <emphasis>instance</emphasis>
- tags are used to specify one portlet instance.
- </para>
- </listitem>
- <listitem>
- <para>
<programlisting><![CDATA[<instance-id>...</instance-id>]]></programlisting>
- A
- <emphasis role="bold">unique name</emphasis>
- given to this instance of the portlet. It must correspond to the
value of
- <emphasis>instance-ref</emphasis>
- , assigned to the window in your
- <emphasis>*-object.xml</emphasis>
- .
+ </para>
+ <para>
+ The <computeroutput><instance-id></computeroutput>
elements defines a <emphasis role="bold">unique name</emphasis>
given to an instance of a portlet. The
<computeroutput><instance-id></computeroutput> value can be
named anything, but it must match the value of one of the
<computeroutput><instance-ref></computeroutput> elements in the
<filename>WEB-INF/*-object.xml</filename> file.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<portlet-ref>...</portlet-ref>]]></programlisting>
- The portlet that this instance will represent. It must correspond to
the value of
- <emphasis>portlet-name</emphasis>
- , assigned in your
- <emphasis>portlet.xml</emphasis>
- .
- </para>
+ </para>
+ <para>
+ The <computeroutput><portlet-ref></computeroutput> element
defines the portlet that an instance represents. The
<computeroutput><portlet-ref></computeroutput> value must match
the <computeroutput><portlet-name></computeroutput> given in the
<filename>WEB-INF/portlet.xml</filename> file.
+ </para>
</listitem>
<listitem>
<para>
-
<programlisting><![CDATA[<preferences><preference>...</preference></preferences>]]></programlisting>
- Preferences for this portlet instance are defined here, as type
String, in a key-value pair style.
- It is also possible to specify preferences as type String[], as in:
- <programlisting><![CDATA[
+<programlisting><![CDATA[
<preferences>
+ <preference>...</preference>
+</preferences>]]></programlisting>
+ </para>
+ <para>
+ The <computeroutput><preference></computeroutput> element
configures a preference as a key-value pair. This value can be composed of a single string
value, for example, the preference <emphasis>fruit</emphasis> can have the
<emphasis>apple</emphasis> value. As well, this value can be composed of
multiple strings, for example, the preference <emphasis>fruits</emphasis> can
have values of <emphasis>apple</emphasis>,
<emphasis>orange</emphasis>, and <emphasis>kiwi</emphasis>:
+ </para>
+ <para>
+<screen><![CDATA[
+<preferences>
<preference>
- <name>fruit</name>
+ <name>fruits</name>
<value>apple</value>
<value>orange</value>
<value>kiwi</value>
</preference>
</preferences>
-]]></programlisting>
- </para>
+]]></screen>
+ </para>
+ <para>
+ The <computeroutput><preference></computeroutput> element
configures one preference, which is part of a set of preferences. Use the
<computeroutput><preferences></computeroutput> element to define
a set of preferences.
+ </para>
</listitem>
<listitem>
<para>
- <programlisting><![CDATA[<security-constraint>
+<screen><![CDATA[<security-constraint>
<policy-permission>
<action-name>viewrecursive</action-name>
<unchecked/>
</policy-permission>
-</security-constraint>]]></programlisting>
- The security contraint portion is worth taking a look at, in an
isolated fashion. It allows you to
- secure a specific portlet instance based on a user's role.
- </para>
- <para>
- <emphasis role="bold">Role
definition:</emphasis>
- You must define a role that this security constraint will apply to.
Possible values are:
- <itemizedlist>
- <listitem>
- <emphasis
role="bold"><unchecked/></emphasis>
- Anyone can view this page.
- </listitem>
- <listitem>
- <emphasis
role="bold"><role-name>SOMEROLE</role-name></emphasis>
- Access to this page is limited to the defined role.
- </listitem>
- </itemizedlist>
- <emphasis role="bold">Access
Rights:</emphasis>
- You must define the access rights given to the role defined.
Possible values are:
- <itemizedlist>
- <listitem>
- <emphasis role="bold">view</emphasis>
- Users can view the page.
- </listitem>
- <listitem>
- <emphasis
role="bold">viewrecursive</emphasis>
- Users can view the page and child pages.
- </listitem>
- <listitem>
- <emphasis
role="bold">personalize</emphasis>
- Users are able to personalize the page's theme.
- </listitem>
- <listitem>
- <emphasis
role="bold">personalizerecursive</emphasis>
- Users are able to personalize the page AND its children's
themes.
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>The example portlet-instances.xml, above, makes reference to items
found in other descriptor files. To
- help with this topic, we have included a sample image that depicts the
relationship:
+</security-constraint>]]></screen>
+ </para>
+ <para>
+ The <computeroutput><security-constraint></computeroutput>
element is a container for
<computeroutput><policy-permission></computeroutput> elements.
This example demonstrates the
<computeroutput><security-constraint></computeroutput> and
<computeroutput><policy-permission></computeroutput> elements.
+ </para>
+ <para>
+ The <computeroutput><action-name></computeroutput> element
defines the access rights given to the role defined. Accepted values are:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem override="bullet">
+ <para>
+ <computeroutput>view</computeroutput>: users can view the page.
+ </para>
+ </listitem>
+ <listitem override="bullet">
+ <para>
+ <computeroutput>viewrecursive</computeroutput>: users can view the
page and child pages.
+ </para>
+ </listitem>
+ <listitem override="bullet">
+ <para>
+ <computeroutput>personalize</computeroutput>: users are able
personalize the page's theme.
+ </para>
+ </listitem>
+ <listitem override="bullet">
+ <para>
+ <computeroutput>personalizerecursive</computeroutput>: users are able
personalize the page and child pages themes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ You must define a role that the security constraint will apply to:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem override="bullet">
+ <para>
+ <computeroutput>unchecked</computeroutput>: anyone can view the page.
+ </para>
+ </listitem>
+ <listitem override="bullet">
+ <para>
+ <computeroutput><role-name>EXAMPLEROLE</role-name></computeroutput>:
only allow users that are part of the
<computeroutput>EXAMPLEROLE</computeroutput> role to access the instance.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+</itemizedlist>
+</para>
+ <para>
+ The previous <filename>portlet-instances.xml</filename> example makes
reference to items found in other descriptor files. The following diagram illustrates the
relationship between the <filename>portlet.xml</filename>,
<filename>portlet-instances.xml</filename>, and
<filename>*-object.xml</filename> descriptors:
+ </para>
+ <para>
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/tutorials/first_portlet/desc_relationship.gif"
@@ -1005,21 +1280,25 @@
</imageobject>
</mediaobject>
</para>
+ <note>
+ <title>Is the <filename>portlet-instances.xml</filename> descriptor
required?</title>
+ <para>
+ Technically, it is not. The portal object hierarchy, such as creating portals,
pages, instances, and organizing them on the page, can be defined using the management
portlet, which is accessible to JBoss Portal administrators.
+ </para>
+ </note>
</sect2>
<sect2>
- <title>jboss-portlet.xml</title>
- <note>
- <emphasis>Is this descriptor mandatory?</emphasis>
- Technically, no, but might be required to access JBoss-specific functionality
that is not covered by the
- Portlet specification.
- </note>
- <para>This descriptor is useful when you need to access JBoss-specific
functionality within your portlet
- application. It would normally be packaged inside your portlet war, alongside
the other descriptors
- in this section.</para>
+ <title>The <filename>jboss-portlet.xml</filename>
Descriptor</title>
+ <para>
+ The <filename>jboss-portlet.xml</filename> descriptor allows you to use
JBoss-specific functionality within your portlet application. This descriptor is covered
by the <ulink
url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168
Portlet Specification</ulink>, and is normally packaged inside your portlet WAR
file, alongside the other descriptors in these sections.
+ </para>
<sect3>
<title>Injecting Header Content</title>
<para>
- <programlisting><![CDATA[
+ The following example injects a specific style sheet,
<computeroutput>/images/management/management.css</computeroutput>, allowing
the portlet to leverage a specific style:
+ </para>
+ <para>
+<screen><![CDATA[
<?xml version="1.0" standalone="yes"?>
<!DOCTYPE portlet-app PUBLIC
"-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
@@ -1032,15 +1311,20 @@
media="screen"/>
</header-content>
</portlet>
-</portlet-app>]]></programlisting>
- The above example will inject a specific style sheet link in the top of
the portal page, allowing this
- portlet to leverage its specific style selectors.
+</portlet-app>]]>
+</screen>
+ </para>
+ <para>
+ Use the <computeroutput><header-content></computeroutput>
and <computeroutput><link></computeroutput> elements to specify
a style sheet.
</para>
</sect3>
<sect3>
- <title>Injecting Services in the portlet context</title>
+ <title>Injecting Services in the Portlet Context</title>
+ <para>
+ The following example injects the
<computeroutput>UserModule</computeroutput> service as an attribute to the
portlet context:
+ </para>
<para>
- <programlisting><![CDATA[
+<screen><![CDATA[
<?xml version="1.0" standalone="yes"?>
<!DOCTYPE portlet-app PUBLIC
"-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
@@ -1051,20 +1335,27 @@
<service-class>org.jboss.portal.identity.UserModule</service-class>
<service-ref>:service=Module,type=User</service-ref>
</service>
-</portlet-app>]]></programlisting>
- Injects the UserModule service as an attribute to the portlet context,
allowing a portlet to then leverage the
- service. For example:
- <programlisting><![CDATA[
+</portlet-app>]]>
+</screen>
+ </para>
+ <para>
+ This allows the portlet to leverage the service, for example:
+ </para>
+ <para>
+<screen><![CDATA[
UserModule userModule = (UserModule)
getPortletContext().getAttribute("UserModule");
String userId = request.getParameters().getParameter("userid");
-User user = userModule.findUserById(userId);
-]]></programlisting>
+User user = userModule.findUserById(userId);]]>
+</screen>
</para>
</sect3>
<sect3>
- <title>Defining extra portlet information</title>
- <para>Since JBoss Portal 2.6.3, icons can be defined for a portlet.
- <programlisting><![CDATA[
+ <title>Defining Extra Portlet Information</title>
+ <para>
+ As of JBoss Portal 2.6.3, icons can be defined for a portlet by using the
<computeroutput><icon></computeroutput>,
<computeroutput><small-icon></computeroutput>, and
<computeroutput><large-icon></computeroutput> elements:
+ </para>
+ <para>
+<screen><![CDATA[
<?xml version="1.0" standalone="yes"?>
<!DOCTYPE portlet-app PUBLIC
"-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
@@ -1079,23 +1370,35 @@
</icon>
</portlet-info>
</portlet>
-</portlet-app>]]></programlisting>
- The reference can be absolute
(
http://www.example.com/images/smallIcon.png) or relative to the webapp
- context if starting with a '/'. Those icons can be used by
different parts of the portal User Interface.
- </para>
+</portlet-app>]]>
+</screen>
+ </para>
+ <para>
+ References to icons can be absolute, for example,
<
emphasis>http://www.example.com/images/smallIcon.png</emphasis>, or relative
to the web application context, for example,
<computeroutput>/images/smallIcon.png</computeroutput>. Icons can be used by
different parts of the portlet user interface.
+ </para>
</sect3>
<sect3>
<title>Portlet Session Replication in a Clustered
Environment</title>
</sect3>
- <para>See <xref
linkend="portlet_session_replication"/>.</para>
+ <para>
+ For information about portlet session replication in clustered environments, refer to
<xref linkend="portlet_session_replication"/>.
+ </para>
+ <para>
+ <note>
+ <title>Is the <filename>jboss-portlet.xml</filename> descriptor
required?</title>
+ <para>
+ Technically, it is not; however, it may be required to access JBoss-specific
functionality that is not covered by the Portlet specification.
+ </para>
+ </note>
+ </para>
</sect2>
<sect2>
- <title>portlet.xml</title>
- <para>This is the standard portlet descriptor covered by the JSR-168
Specification. It is
- advisable that developers read the specification items covering proper use of
this descriptor, as it is only
- covered here briefly. For example purposes, we use an edited version of our
JBoss Portal UserPortlet
- definition. Normally, you would package this descriptor in your portlet WAR
file.
- <programlisting><![CDATA[
+ <title>The <filename>portlet.xml</filename>
Descriptor</title>
+ <para>
+ The <filename>portlet.xml</filename> descriptor is the standard portlet
descriptor covered by the <ulink
url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet
Specification</ulink>. Developers are strongly encouraged to read the <ulink
url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet
Specification</ulink> items covering the correct use of this descriptor, as it is
only covered briefly in these sections. Normally the
<filename>portlet.xml</filename> descriptor is packaged inside your portlet
WAR file, alongside the other descriptors in these sections. The following example is a
modified version of the JBoss Portal UserPortlet definition:
+ </para>
+ <para>
+<screen><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<portlet-app
xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
@@ -1109,10 +1412,9 @@
<display-name>User Portlet</display-name>
<portlet-class>org.jboss.portal.core.portlet.user.UserPortlet</portlet-class>
<init-param>
- <description>Whether we should use ssl on login and throughout the
Portal.
- 1=yes;0=no</description>
- <name>useSSL</name>
- <value>0</value>
+ <description>Initialize the portlet with a default page to
render</description>
+ <name>>default-view</name>
+ <value>/WEB-INF/jsf/objects.xhtml</value>
</init-param>
<supports>
<mime-type>text/html</mime-type>
@@ -1126,114 +1428,140 @@
<title>User portlet</title>
</portlet-info>
</portlet>
-</portlet-app>
-]]></programlisting>
+</portlet-app>]]>
+</screen>
+ </para>
+ <para>
<itemizedlist>
<listitem>
<para>
<programlisting><![CDATA[<portlet-app>...</portlet-app>]]></programlisting>
- The <emphasis>portlet-app</emphasis> tag, encapsulates
the entire document. You may specify more
- than one portlet, within this tag.
+ </para>
+ <para>
+ The <computeroutput><portlet-app></computeroutput>
element encapsulates the entire document. Multiple portlets can be specified using the
<computeroutput><portlet-app></computeroutput> element.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<portlet>...</portlet>]]></programlisting>
- The <emphasis>portlet</emphasis> tag is used to define
one portlet that is deployed within
- this archive.
+ </para>
+ <para>
+ The
<computeroutput><portlet></computeroutput> element defines one
portlet that is deployed within this archive.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<description>...</description>]]></programlisting>
- A verbal description of this portlet's function.
+ </para>
+ <para>
+ The <computeroutput><description></computeroutput> element
is a verbal description of the portlet's function.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<portlet-name>...</portlet-name>]]></programlisting>
- The name of this portlet, usually the class name, though it
doesn't have to be.
+ </para>
+ <para>
+ The <computeroutput><portlet-name></computeroutput>
element defines the portlet name. It does not have to be the class name.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<portlet-class>...</portlet-class>]]></programlisting>
- The fully-qualified name of this portlet class.
+ </para>
+ <para>
+ The <computeroutput><portlet-class></computeroutput>
element defines the Fully Qualified Name (FQN) of the portlet class.
</para>
</listitem>
<listitem>
<para>
-
<programlisting><![CDATA[<init-param><name>...</name><value>...</value></init-param>]]></programlisting>
- Using the <emphasis>init-param</emphasis> tag, you can
specify initialization parameters to create
- initial state inside your portlet class. Normally, they would be
used in the portlet's
- <emphasis>init()</emphasis> method. You can specify more
than one init-param.
+ <programlisting><![CDATA[
+<init-param>
+ <name>...</name>
+ <value>...</value>
+</init-param>]]></programlisting>
+ </para>
+ <para>
+ The <computeroutput><init-param></computeroutput> element
specifies initialization parameters to create an initial state inside your portlet class.
This is usually used in the portlet's <emphasis>init()</emphasis> method,
but not necessarily. Unlike a preference, an init-parameter is data that does not change
at runtime and does not go into a database. If the value is changed in the descriptor, the
change takes immediate effect after re-deploying the portlet. Multiple
<computeroutput><init-param></computeroutput> elements can be
used.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<supports>...</supports>]]></programlisting>
- Here, you would advertise the supported
<emphasis>mime-type</emphasis> and supported
- <emphasis>portlet-modes</emphasis> for this portlet.
+ </para>
+ <para>
+ The <computeroutput><supports></computeroutput> element
declares all of the markup types that a portlet supports. Use the
<computeroutput><mime-type></computeroutput> element to declare
supported capabilities, for example, if the only outputs are text and HTML, use
<computeroutput><mime-type>text/html</mime-type></computeroutput>.
Use the <computeroutput><portlet-mode></computeroutput> element
to define the supported portlet modes for the portlet. For example, all portlets must
support the <computeroutput>view</computeroutput> portlet mode, which is
defined using
<computeroutput><portlet-mode>view</portlet-mode></computeroutput>.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<supported-locale>...</supported-locale>]]></programlisting>
- Here, you would advertise the supported locales for this portlet.
Several locales can be specified.
+ </para>
+ <para>
+ The <computeroutput><supported-locale></computeroutput>
elements advertise the supported locales for the portlet. Use multiple
<computeroutput><supported-locale></computeroutput> elements to
specify multiple locales.
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[<resource-bundle>...</resource-bundle>]]></programlisting>
- The resource bundle that will containing the localized information
for the specified locales.
+ </para>
+ <para>
+ The <computeroutput><resource-bundle></computeroutput>
element specifies the resource bundle that contains the localized information for the
specified locales.
</para>
</listitem>
<listitem>
<para>
-
<programlisting><![CDATA[<portlet-info><title>...</title></portlet-info>]]></programlisting>
- The portlet title that will be displayed in the portlet window's
title bar.
+ <programlisting><![CDATA[
+<portlet-info>
+ <title>...</title>
+</portlet-info>]]></programlisting>
</para>
+ <para>
+ The <computeroutput><title></computeroutput> element
defines the portlet's title, which is displayed in the portlet window's title
bar.
+ </para>
</listitem>
</itemizedlist>
- <note>This is a simple portlet.xml primer, and is not meant as a
replacement for what is covered in the
- actual Portlet specification.</note>
+ </para>
+ <para>
+ <warning>
+ <title>The <filename>portlet.xml</filename>
Example</title>
+ <para>
+ This <filename>portlet.xml</filename> example is not a replacement for
what is covered in the <ulink
url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet
Specification</ulink>.
+ </para>
+ </warning>
</para>
</sect2>
</sect1>
<sect1 id="portaldescriptors">
<title>JBoss Portal Descriptors</title>
+ <para>
+ This section describes Datasource descriptors, which are required for JBoss Portal
to communicate with a database, and briefly covers the
<filename>jboss-portal.sar/conf/config.xml</filename> descriptor, which can be
used for configuring logging, and configuring which page a user goes to when they log in.
+ </para>
<sect2 id="descriptor_ds">
- <title>Datasource Descriptor (portal-*-ds.xml)</title>
- <para>JBoss Portal requires a Datasource descriptor to be deployed
alongside the
- <emphasis>jboss-portal.sar</emphasis>
- for access to a database. This section does not explain what a Datasource
Descriptor is, but does explain
- where to obtain some templates that you can configure for your own
installation.
- <note>
- For an in-depth introduction to datasources, you can view the JBoss AS
documentation online
- <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfigDataSources"...
- .
- </note>
+ <title>Datasource Descriptors
(<filename>portal-*-ds.xml</filename>)</title>
+ <para>
+ JBoss Portal requires a Datasource descriptor to be deployed alongside the
<filename>jboss-portal.sar</filename>, in order to communicate with a
database. This section explains where to obtain template Datasource descriptors, how to
compile them from source, and how to configure them for your installation. For an in-depth
introduction to datasources, refer to the JBoss AS documentation online on the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfigDataSources"...
Datasource Wiki page</ulink>.
</para>
<sect3>
- <title>Obtaining Datasource Descriptors Binary releases</title>
+ <title>Datasource Descriptors included in Binary
releases</title>
<para>
- Several template datasource descriptors can be found in the binary and
bundle distributions. They are
- commonly located under the
- <emphasis>setup</emphasis>
- directory:
+ Several template Datasource descriptors are included in the binary and bundled
distributions of JBoss Portal. They are commonly located in the
<filename>jboss-portal-<replaceable>version</replaceable>/setup/</filename>
directory:
+ </para>
+ <para>
<mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/setup/package.png"
valign="middle"/>
</imageobject>
</mediaobject>
- The directory
- <emphasis>setup</emphasis>
- should contain the following files, that you can customize for your own
Database/Connector:
+ </para>
+ <para>
+ The
<filename>jboss-portal-<replaceable>version</replaceable>/setup/</filename>
directory contains sample Datasource descriptors for the <trademark
class="registered">MySQL</trademark>, <trademark
class="registered">Microsoft</trademark> <trademark
class="registered">SQL Server</trademark>, PostgreSQL, and
<trademark class="registered">Oracle</trademark> databases, which
can be customized for your own database:
+ </para>
+ <para>
<mediaobject>
<imageobject>
- <imagedata align="center"
fileref="images/setup/dsfiles.png"
- valign="middle"/>
+ <imagedata align="center"
fileref="images/setup/dsfiles.png" valign="middle"/>
</imageobject>
</mediaobject>
</para>
@@ -1241,33 +1569,64 @@
<sect3>
<title>Building Datasource Descriptors from Source</title>
<para>
- You will need a valid datasource descriptor, for JBoss Portal to
communicate with your database. Having
- obtained the sources and having set your JBOSS_HOME environment variable
(
- <xref linkend="install_source_env"/>
- ), you can now have the JBoss Portal build system generate preconfigured
datasources for you.
- </para>
- <para>
- Navigate to
- <emphasis>JBOSS_PORTAL_HOME_DIRECTORY/core</emphasis>
- and type:
- <programlisting>build datasource</programlisting>
+ To build the Datasource descriptors from source:
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Obtain the JBoss Portal source code: <xref linkend="install_source"
/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Configure the <computeroutput>JBOSS_HOME</computeroutput>
environment variable: <xref linkend="install_source_env"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Change into the
<filename>JBOSS_PORTAL_SOURCE_DIRECTORY/build/</filename> directory. To build
the JBoss Portal source code on <trademark
class="registered">Linux</trademark>, run the <command>sh
build.sh deploy</command> command, or, if you are running <trademark
class="registered">Windows</trademark>, run the
<command>build.bat deploy</command> command. If this is the first build,
third-party libraries are obtained from an online repository, so you must be connected to
the Internet. After building, if the
<filename>JBOSS_PORTAL_SOURCE_DIRECTORY/thirdparty/</filename> directory does
not exist, it is created, and populated with the files required for later steps. For
further details, refer to <xref linkend="building_deploying_from_source"
/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Change into the
<filename>JBOSS_PORTAL_SOURCE_DIRECTORY/core/</filename> directory, and run
the <command>sh build.sh datasource</command> command, or, if you are running
<trademark class="registered">Windows</trademark>, run the
<command>build.bat datasource</command> command:
+ </para>
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" valign="middle"
fileref="images/setup/build_ds.png"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ Note: if the JBoss Portal source was not built as per step 3, the <command>sh
build.sh datasource</command> and <command>build.bat
datasource</command> commands fail with an error, such as the following:
+ </para>
+ <para>
+<screen><![CDATA[
+BUILD FAILED
+java.io.FileNotFoundException:
/jboss-portal-2.6.3.GA-src/core/../thirdparty/libraries.ent
+(No such file or directory)]]>
+</screen>
+ </para>
+ <para>
+ The datasource build process produces the following directory and file structure,
with the Datasource descriptors in the
<filename>JBOSS_PORTAL_SOURCE_DIRECTORY/core/output/resources/setup</filename>
directory:
+ </para>
+ <para>
<mediaobject>
<imageobject>
- <imagedata align="center" valign="middle"
fileref="images/setup/build_ds.png"/>
+ <imagedata align="center" valign="middle"
fileref="images/setup/build_ds_dir.png"/>
</imageobject>
</mediaobject>
</para>
<para>
- Once complete, the datasource build should produce the following directory
and file structure:
- <mediaobject>
- <imageobject>
- <imagedata align="center" valign="middle"
fileref="images/setup/build_ds_dir.png"/>
- </imageobject>
- </mediaobject>
- </para>
- <para>At this point, you should configure the one that suits you best
with your Database and JDBC
- driver.
- <programlisting><![CDATA[
+ The following is an example Datasource descriptor for a PostgreSQL database:
+ </para>
+ <para>
+<screen><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
@@ -1277,20 +1636,21 @@
<user-name>portal</user-name>
<password>portalpassword</password>
</local-tx-datasource>
-</datasources>]]></programlisting>
- Please verify that the username, password, url, and driver-class are
correct for
- your flavor of DB.
+</datasources>]]>
+</screen>
+ </para>
+ <para>
+ Make sure the <computeroutput>user-name</computeroutput>,
<computeroutput>password</computeroutput>,
<computeroutput>connection-url</computeroutput>, and
<computeroutput>driver-class</computeroutput>, are correct for your chosen
database.
</para>
</sect3>
</sect2>
<sect2 id="descriptor_debug">
- <title>Portlet Debugging (jboss-portal.sar/conf/config.xml)</title>
+ <title>Portlet Debugging
(<filename>jboss-portal.sar/conf/config.xml</filename>)</title>
<para>
- By default, JBoss Portal ships with all errors set to display. You can
fine-tune this behavior by modifying
- some properties in the file,
- <emphasis>jboss-portal.sar/conf/config.xml</emphasis>
- :
- <programlisting><![CDATA[
+ By default, JBoss Portal is configured to display all errors. This behavior can be
configured by modifying the
<filename>jboss-portal.sar/conf/config.xml</filename> file:
+ </para>
+ <para>
+<screen><![CDATA[
<!-- When a window has restrictedaccess : show or hide values are permitted -->
<entry key="core.render.window_access_denied">show</entry>
<!-- When a window is unavailable : show or hide values are permitted -->
@@ -1300,231 +1660,307 @@
<!-- When a window produces an internal error : show, hide are permitted -->
<entry key="core.render.window_internal_error">show</entry>
<!-- When a window is not found : show or hide values are permitted -->
-<entry key="core.render.window_not_found">show</entry>
-]]></programlisting>
- Either
- <emphasis>show</emphasis>
- or
- <emphasis>hide</emphasis>
- are allowed as flags in these elements. Depending on the setting and actual
error, either an error message
- is deployed or a full stack trace within the portlet window.
- Additionally, the
- <emphasis>core.render.window_error</emphasis>
- property supports the
- <emphasis>message_only</emphasis>
- value. This value will only display the error message whereas
- <emphasis>show</emphasis>
- will display the full stack trace if it is available.
- </para>
+<entry key="core.render.window_not_found">show</entry>]]>
+</screen>
+ </para>
+ <para>
+ For these parameters, accepted values are
<computeroutput>show</computeroutput> and
<computeroutput>hide</computeroutput>. Depending on the setting, and the
actual error, either an error message is displayed, or a full stack trace within the
portlet window occurs. Additionally, the
<computeroutput>core.render.window_error</computeroutput> property supports
the <computeroutput>message_only</computeroutput> value. The
<computeroutput>message_only</computeroutput> value will only display an error
message, whereas the <computeroutput>show</computeroutput> value will, if
available, display the full stack trace.
+ </para>
</sect2>
<sect2>
- <title>Login to dashboard</title>
+ <title>Log in to Dashboard</title>
<para>
- By default, when a user logs in, she is forwarded to the default page of the
default portal. In order to
- forward her to her dashboard, it is possible to set in the file
<emphasis>jboss-portal.sar/conf/config.xml</emphasis>:
- <programlisting><![CDATA[<!-- Namespace to use when logging-in,
use "dashboard" to directly
- log-in the dashboard otherwise use "default" -->
+ By default, when a user logs in they are forwarded to the default page of the
default portal. In order to
+ forward a user to their Dashboard, set the
<computeroutput>core.login.namespace</computeroutput> value to
<computeroutput>dashboard</computeroutput> in the
<filename>jboss-portal.sar/conf/config.xml</filename> file:
+ </para>
+ <para>
+<screen><![CDATA[
+<!-- Namespace to use when logging-in, use "dashboard" to directly
+log-in the dashboard otherwise use "default" -->
<entry key="core.login.namespace">dashboard</entry>
-]]></programlisting>
+]]></screen>
</para>
</sect2>
</sect1>
<sect1 id="desc_examples">
<title>Descriptor Examples</title>
<sect2 id="desc_example_page">
- <title>Defining a new portal page</title>
- <para>This sample application and descriptor will create a new page,
named
- <emphasis>MyPage</emphasis>
- in your portal. To illustrate our example, we have made available a portlet
with a page descriptor that you
- can download
- here:
- <ulink
-
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
- >HelloWorld Page</ulink>
- .
- </para>
- <note>
- To use this example, simply extract the zip, and deploy the
- <emphasis>helloworldportalpage.war</emphasis>
- where your portal is running (hot-deployment supported).
- </note>
- <para>Our sample includes a descriptor to define this new portal page,
- <emphasis>helloworld-object.xml</emphasis>
- , located under
- <emphasis>helloworldportalpage.war/WEB-INF/</emphasis>
- , and it looks like this:
- <programlisting><![CDATA[<?xml version="1.0"
encoding="UTF-8"?>
+ <title>Defining a new Portal Page</title>
+ <para>
+ The sample application descriptor in this section creates a new page,
<computeroutput>MyPage</computeroutput>, in a portal. To illustrate this
example, download the <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
portlet. To use the HelloWorldPortalPage portlet:
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Download the <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
portlet.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Unzip the <filename>HelloWorldPortalPage</filename> ZIP file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ To expand the WAR file, which gives you access to the XML descriptors, change into
the <filename>HelloWorldPortalPage/</filename> directory, and run the
<command>ant explode</command> command.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you did not expand the <filename>helloworldportalpage.war</filename>
file, copy the <filename>helloworldportalpage.war</filename> file into the
correct JBoss AS or JBoss EAP <filename>deploy/</filename> directory. If you
expanded the <filename>helloworldportalpage.war</filename> file, copy the
<filename>HelloWorldPortalPage/output/lib/exploded/helloworldportalpage.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using the
<computeroutput>default</computeroutput> JBoss AS profile, copy the WAR file
or the expanded directory into the
<filename>$JBOSS_HOME/server/default/deploy/</filename> directory.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ The HelloWorldPortalPage portlet is hot-deployable, so the JBoss EAP or JBoss AS
server does not have to be restarted after deploying the HelloWorldPortalPage portlet. The
following is an example of the
<filename>HelloWorldPortalPage/WEB-INF/helloworld-object.xml</filename>
descriptor:
+ </para>
+ <para>
+<screen><![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>
+ <if-exists>overwrite</if-exists>
<parent-ref>default</parent-ref>
- <if-exists>overwrite</if-exists>
<properties/>
<page>
<page-name>MyPage</page-name>
- <security-constraint>
- <policy-permission>
- <action-name>viewrecursive</action-name>
- <unchecked/>
- </policy-permission>
- </security-constraint>
<window>
<window-name>HelloWorldPortletPageWindow</window-name>
<instance-ref>HelloWorldPortletPageInstance</instance-ref>
<region>center</region>
<height>0</height>
</window>
+ <security-constraint>
+ <policy-permission>
+ <unchecked/>
+ <action-name>viewrecursive</action-name>
+ </policy-permission>
+ </security-constraint>
</page>
</deployment>
</deployments>]]>
- </programlisting>
+</screen>
</para>
- <para>A deployment file can be composed of a set of
<deployments>. In our
- example file, above, we are defining a page, placing the portlet as a window
- on that page, and creating an instance of that portlet. You can then use the
Management
- Portlet (bundled with JBoss Portal) to modify the instances of this portlet,
reposition
- it, and so on...</para>
<para>
- <itemizedlist>
+ A depoloyment is composed of a
<computeroutput><deployments></computeroutput> element, which is
a container for <computeroutput><deployment></computeroutput>
elements. In the previous example, a page is defined, the portlet is placed as a window on
a page, and an instance of the portlet is created. The Mangement portlet (bundled with
JBoss Portal) can modify portal instances, page position, and so on.
+ </para>
+ <para>
+ The following list describes elements in a
<filename>*-object.xml</filename> file:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+<screen>
+<if-exists>
+</screen>
+ <para>
+ The <computeroutput><if-exists></computeroutput> element
defines the action to take if an instance with the same name already exists. Accepted
values are <computeroutput>overwrite</computeroutput> and
<computeroutput>keep</computeroutput>. The
<computeroutput>overwrite</computeroutput> option destroys the existing
object, and creates a new one based on the content of the deployment. The
<computeroutput>keep</computeroutput> option matains the existing object
deployment, or creates a new one if it does not exist.
+ </para>
+ </listitem>
+ <listitem>
+<screen>
+<parent-ref>
+</screen>
+ <para>
+ The <computeroutput><parent-ref></computeroutput> element
contains a reference to the parent object. The naming convention for naming objects is to
concatenate the names of the path to the object, and separate the names using a period. If
the path is empty, the empty string must be used. The
<computeroutput><parent-ref></computeroutput> element tells the
portal where the portlet appears. The syntax for the
<computeroutput><parent-ref></computeroutput> element is
<computeroutput><replaceable>portal-instance</replaceable>.<replaceable>portal-page</replaceable></computeroutput>.
+ </para>
+ </listitem>
+ <listitem>
+<screen>
+<properties>
+</screen>
+ <para>
+ A set of generic properties for the portal object. The
<computeroutput><properties></computeroutput> elements contains
definitions specific to a page. This is commonly used to define the specific theme and
layout to use. If not defined, the default portal theme and layout are used.
+ </para>
+ </listitem>
<listitem>
- <emphasis
role="bold"><if-exists></emphasis>
- 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.
- </listitem>
+<screen>
+<page>
+</screen>
+ <para>
+ The start of a page definition. Among others, the
<computeroutput><page></computeroutput> element is a container
for the <computeroutput><page-name></computeroutput>,
<computeroutput><window></computeroutput>, and
<computeroutput><security-constraint></computeroutput>
elements.
+ </para>
+ </listitem>
<listitem>
- <emphasis
role="bold"><parent-ref></emphasis>
- Indicates whether the
- object should be hooked in to the portal tree.
- </listitem>
+<screen>
+<page-name>
+</screen>
+ <para>
+ The page name.
+ </para>
+ </listitem>
+ <listitem>
+<screen>
+<window>
+</screen>
+ <para>
+ The <computeroutput><window></computeroutput> element
defines a portlet window. The
<computeroutput><window></computeroutput> element requires an
<computeroutput><instance-ref></computeroutput> element, which
assigns a portal instance to a window.
+ </para>
+ </listitem>
+ <listitem>
+<screen>
+<window-name>
+</screen>
+ <para>
+ The <computeroutput><window-name></computeroutput> element
defines the <emphasis role="bold">unique name</emphasis> given to a
portlet window. This can be named anything.
+ </para>
+ </listitem>
+ <listitem>
+<screen>
+<instance-ref>
+</screen>
+ <para>
+ The <computeroutput><instance-ref></computeroutput>
elements define the portlet instances that windows represent. This value is the ID of a
portlet instance, and must match the value of one of the
<computeroutput><instance-id></computeroutput> elements in the
<filename>WEB-INF/portlet-instances.xml</filename> file.
+ </para>
+ </listitem>
<listitem>
- <emphasis
role="bold"><properties></emphasis>
- Properties definition
- specific to this page, commonly used to define the specific theme and
layout to
- use. If not defined, the default portal layouts/theme combination will
be used.
- </listitem>
- <listitem>
- <emphasis
role="bold"><page></emphasis>
- The start of a page
- definition.
- </listitem>
- <listitem>
- <emphasis
role="bold"><page-name></emphasis>
- The name of the page.
- </listitem>
- <listitem>
- <emphasis
role="bold"><window></emphasis>
- The start of a window
- definition.
- </listitem>
- <listitem>
- <emphasis
role="bold"><window-name></emphasis>
- The name of the
- window.
- </listitem>
- <listitem>
- <emphasis
role="bold"><instance-ref></emphasis>
- The instance
- reference used by this window. Should correspond with the
- <instance-name> variable.
- </listitem>
- <listitem>
- <emphasis
role="bold"><height></emphasis>
- The vertical position of
- this window within the region defined in the layout.
- </listitem>
- <listitem>
- <emphasis
role="bold"><instance></emphasis>
- The start of an instance
- definition. page.
- </listitem>
- <listitem>
- <emphasis
role="bold"><instance-name></emphasis>
- Maps to the above
- <instance-ref> variable.
- </listitem>
- <listitem>
- <emphasis
role="bold"><component-ref></emphasis>
- Takes the name of
- the application followed by the name of the portlet, as defined in the
- <emphasis>portlet.xml</emphasis>
- </listitem>
- <listitem>
- <para>
- <programlisting><![CDATA[<security-constraint>
- <policy-permission>
- <action-name>viewrecursive</action-name>
- <unchecked/>
- </policy-permission>
-</security-constraint>]]></programlisting>
- The security contraint portion is worth taking a look at, in an
isolated fashion. It allows you to
- secure a specific page/portal based on a user's role.
- </para>
- <para>
- <emphasis role="bold">Role
definition:</emphasis>
- You must define a role that this security constraint will apply to.
Possible values are:
- <itemizedlist>
- <listitem>
- <emphasis
role="bold"><unchecked/></emphasis>
- Anyone can view this page.
- </listitem>
- <listitem>
- <emphasis
role="bold"><role-name>SOMEROLE</role-name></emphasis>
- Access to this page is limited to the defined role.
- </listitem>
- </itemizedlist>
- <emphasis role="bold">Access
Rights:</emphasis>
- You must define the access rights given to the role defined.
Possible values are:
- <itemizedlist>
- <listitem>
- <emphasis role="bold">view</emphasis>
- Users can view the page.
- </listitem>
- <listitem>
- <emphasis
role="bold">viewrecursive</emphasis>
- Users can view the page and child pages.
- </listitem>
- <listitem>
- <emphasis
role="bold">personalize</emphasis>
- Users are able to personalize the page's theme.
- </listitem>
- <listitem>
- <emphasis
role="bold">personalizerecursive</emphasis>
- Users are able to personalize the page AND its children's
themes.
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
- </para>
+<screen>
+<region>...</region>
+<height>...</height>
+</screen>
+ <para>
+ The <computeroutput><region></computeroutput> and
<computeroutput><height></computeroutput> elements define where
the window appears within the page layout. The
<computeroutput><region></computeroutput> element specifies
where the window appears on the page. The
<computeroutput><region></computeroutput> element often depends
on other regions defined in the portal layout. The
<computeroutput><height></computeroutput> element can be
assigned a value between one and <replaceable>X</replaceable>.
+ </para>
+ </listitem>
+ <listitem>
+<screen>
+<instance>
+</screen>
+ <para>
+ The <computeroutput><instance></computeroutput> element
creates instances of portlets. The portlet will only be created and configured if the
portlet is present, and if an instance with the same name does not already exist.
+ </para>
+ </listitem>
+ <listitem>
+<screen>
+<instance-name>
+</screen>
+ <para>
+ The <computeroutput><instance-name></computeroutput>
element maps to the
<computeroutput><instance-ref></computeroutput> element.
+ </para>
+ </listitem>
+ <listitem>
+<screen>
+<component-ref>
+</screen>
+ <para>
+ The <computeroutput><component-ref></computeroutput>
element takes the name of the application, followed by the name of the portlet, as defined
in the <filename>WEB-INF/portlet.xml</filename> file.
+ </para>
+ </listitem>
+ </itemizedlist>
+</para>
+<para>
+ The <computeroutput><security-constraint></computeroutput>
element is a container for
<computeroutput><policy-permission></computeroutput> elements.
The following is an example of the
<computeroutput><security-constraint></computeroutput> and
<computeroutput><policy-permission></computeroutput> elements:
+</para>
+<para>
+<screen><![CDATA[
+<security-constraint>
+ <policy-permission>
+ <role-name>User</role-name>
+ <action-name>view</action-name>
+ </policy-permission>
+</security-constraint>
+
+<security-constraint>
+ <policy-permission>
+ <unchecked/>
+ <action-name>view</action-name>
+ </policy-permission>
+</security-constraint>]]>
+</screen>
+</para>
+<para>
+<screen>
+<action-name>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><action-name></computeroutput> element
defines the access rights given to the role defined. Accepted values are:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <computeroutput>view</computeroutput>: users can view the page.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>viewrecursive</computeroutput>: users can view the page
and child pages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>personalize</computeroutput>: users are able
personalize the page's theme.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <computeroutput>personalizerecursive</computeroutput>: users are able
personalize the page and child pages themes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+<screen>
+<unchecked/>
+</screen>
+ </para>
+ <para>
+ If present, the
<computeroutput><unchecked></computeroutput> element defines
that anyone can view the instance.
+ </para>
+ <para>
+<screen>
+<role-name>
+</screen>
+ </para>
+ <para>
+ The <computeroutput><role-name></computeroutput> element
defines a role that the security constraint will apply to. The following example only
allows users that are part of the <computeroutput>EXAMPLEROLE</computeroutput>
role to access the instance:
+ </para>
+ <para>
+<screen>
+<role-name>EXAMPLEROLE</role-name>
+</screen>
+ </para>
</sect2>
<sect2 id="desc_example_portal">
- <title>Defining a new portal instance</title>
- <para>To illustrate our example, we have made available a portlet that you
can download
- here:
- <ulink
-
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
- >HelloPortal</ulink>
- .
- </para>
- <para>For our example we make available
- <emphasis>helloworld-object.xml</emphasis>
- located
- under
- <emphasis>helloworldportal.war/WEB-INF/</emphasis>
- , and it looks like this:
- <programlisting><![CDATA[
+ <title>Defining a new Portal Instance</title>
+ <para>
+ The sample application descriptor in this section creates a new portal instance,
<computeroutput>HelloPortal</computeroutput>, that contains two pages. To
illustrate this example, download the <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
portlet. To use the HelloWorldPortal portlet:
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Download the <ulink
url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles...
portlet.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Unzip the <filename>HelloWorldPortal</filename> ZIP file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ To expand the WAR file, which gives you access to the XML descriptors, change into
the <filename>HelloWorldPortal/</filename> directory, and run the
<command>ant explode</command> command.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you did not expand the <filename>helloworldportal.war</filename>
file, copy the <filename>helloworldportal.war</filename> file into the correct
JBoss AS or JBoss EAP <filename>deploy/</filename> directory. If you expanded
the <filename>helloworldportal.war</filename> file, copy the
<filename>HelloWorldPortal/output/lib/exploded/helloworldportal.war/</filename>
directory into the correct JBoss AS or JBoss EAP <filename>deploy/</filename>
directory. For example, if you are using the
<computeroutput>default</computeroutput> JBoss AS profile, copy the WAR file
or the expanded directory into the
<filename>$JBOSS_HOME/server/default/deploy/</filename> directory.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ The HelloWorldPortal portlet is hot-deployable, so the JBoss EAP or JBoss AS server
does not have to be restarted after deploying the HelloWorldPortal portlet. The following
is an example of the
<filename>HelloWorldPortal/WEB-INF/helloworld-object.xml</filename>
descriptor:
+ </para>
+ <para>
+<screen><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
"-//JBoss Portal//DTD Portal Object 2.6//EN"
@@ -1608,25 +2044,19 @@
</page>
</deployment>
</deployments>]]>
- </programlisting>
+</screen>
</para>
- <para>This example, when deployed, will register a new portal instance
named
- <literal>HelloPortal</literal>
- with two pages in it. The portal instance can be
- accessed by navigating to:
- <ulink url="http://localhost:8080/portal/portal/HelloPortal"
- >http://localhost:8080/portal/portal/HelloPortal</ulink>
- for the default page, and
- <ulink
url="http://localhost:8080/portal/portal/HelloPortal/foobar"
-
>http://localhost:8080/portal/portal/HelloPortal/foobar</ulink>
- , for the second page
- created.
- </para>
- <note>You must define a page named
- <literal>default</literal>
- for any new portal instance
- to be accessible via a web browser.
- </note>
+ <para>
+ When deployed, this example registers a new portal instance,
<computeroutput>HelloPortal</computeroutput>, that contains two pages. To view
the default page in the <computeroutput>HelloPortal</computeroutput> instance,
navigate to <ulink url="http://localhost:8080/portal/portal/HelloPortal"
/>, and for the second page, <ulink
url="http://localhost:8080/portal/portal/HelloPortal/foobar" />.
+ </para>
+ <para>
+ <note>
+ <title>Portal Instance <computerouput>default</computerouput>
Page</title>
+ <para>
+ For a portal instance to be accessible via a Web browser, you must define a page
named <computeroutput>default</computeroutput>.
+ </para>
+ </note>
+ </para>
</sect2>
</sect1>
</chapter>
Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/pom.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/pom.xml 2008-06-12 12:45:42 UTC
(rev 10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/pom.xml 2008-06-12 13:28:43 UTC
(rev 10999)
@@ -60,7 +60,7 @@
<groupId>org.jboss.portal</groupId>
<artifactId>referenceGuide-${translation}</artifactId>
- <version>2.6.4</version>
+ <version>2.7.0</version>
<packaging>jdocbook</packaging>
<name>Reference_Guide_(${translation})</name>
Modified: docs/branches/JBoss_Portal_Branch_2_7/userGuide/pom.xml
===================================================================
--- docs/branches/JBoss_Portal_Branch_2_7/userGuide/pom.xml 2008-06-12 12:45:42 UTC (rev
10998)
+++ docs/branches/JBoss_Portal_Branch_2_7/userGuide/pom.xml 2008-06-12 13:28:43 UTC (rev
10999)
@@ -60,7 +60,7 @@
<groupId>org.jboss.portal</groupId>
<artifactId>user-guide-${translation}</artifactId>
- <version>2.6.4</version>
+ <version>2.7.0</version>
<packaging>jdocbook</packaging>
<name>User_Guide_(${translation})</name>