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 --> &target; 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[ ->./run.sh -c ports-01 +>sh run.sh -c ports-01 ]]></programlisting> <programlisting><![CDATA[ ->./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&gt;julien.viet(a)jboss.com&lt;/email&gt; </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=&lt;<replaceable>proxy-hostname</replaceable>&gt; -Dhttp.proxyPort=&lt;<replaceable>proxy-port</replaceable>&gt; +JAVA_OPTS=-Dhttp.proxyHost=&lt;<replaceable>proxy-hostname</replaceable>&gt; +-Dhttp.proxyPort=&lt;<replaceable>proxy-port</replaceable>&gt; </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=&lt;<replaceable>proxy-hostname</replaceable>&gt; -Dhttp.proxyPort=&lt;<replaceable>proxy-port</replaceable>&gt; -</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&gt; 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>&lt;supports&gt;</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>&lt;mime-type&gt;</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>&lt;mime-type&gt;</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>&lt;supports&gt;</computeroutput> element declares all of the markup types that a portlet supports in the <literal>render</literal> method. This is accomplished via the + <computeroutput>&lt;mime-type&gt;</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>&lt;mime-type&gt;</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>&lt;portlet-ref&gt;</computeroutput> value must match the <computeroutput>&lt;portlet-name&gt;</computeroutput> value given in the <filename>HelloWorldPortlet/WEB-INF/portlet.xml</filename> file. The <computeroutput>&lt;instance-id&gt;</computeroutput> value can be named anything, but it must match the <computeroutput>&lt;instance-ref&gt;</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>&lt;region&gt;</computeroutput> element specifies where the window will appear on the page. + the <computeroutput>&lt;region&gt;</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>&lt;supports&gt;</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>&lt;mime-type&gt;</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>&lt;mime-type&gt;</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>&lt;supports&gt;</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>&lt;mime-type&gt;</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>&lt;mime-type&gt;</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>&lt;supports&gt;</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>&lt;mime-type&gt;</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>&lt;mime-type&gt;</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>&lt;supports&gt;</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>&lt;mime-type&gt;</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>&lt;mime-type&gt;</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&gt;roy(a)jboss.org&lt;/email&gt; </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>&lt;mime-type&gt;</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>&lt;remotable&gt;</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>&lt;service&gt;</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>&lt;service&gt;</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>&lt;portlet-name&gt;</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>&lt;portlet-name&gt;</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>&lt;remotable&gt;</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>&lt;trans-attribute&gt;</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>&lt;portlet-name&gt;</computeroutput>, <computeroutput>&lt;remotable&gt;</computeroutput>, and <computeroutput>&lt;trans-attribute&gt;</computeroutput> elements: @@ -148,7 +149,7 @@ </screen> </para> <para> - If a portlet uses the <computeroutput>true</computeroutput> value for the <computeroutput>&lt;partial-refresh&gt;</computeroutput> element, the portal uses partial-page refreshing and only renders the portlet. If the <computeroutput>&lt;partial-refresh&gt;</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>&lt;partial-refresh&gt;</computeroutput> element, the portal uses partial-page refreshing and only renders that portlet. If the <computeroutput>&lt;partial-refresh&gt;</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>&lt;session-config&gt;</computeroutput> element configures the portlet session of the portlet. The <computeroutput>&lt;distributed&gt;</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>&lt;session-config&gt;</computeroutput> element configures the portlet session for the portlet. The <computeroutput>&lt;distributed&gt;</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>&lt;session-config&gt;</computeroutput> and <computeroutput>&lt;distributed&gt;</computeroutput> elements: @@ -184,10 +185,10 @@ </screen></term> <listitem> <para> - Define how the portlet behaves with the transactional context. The <computeroutput>&lt;trans-attribute&gt;</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>&lt;transaction&gt;</computeroutput> element defines how the portlet behaves with regards to the transactional context. The <computeroutput>&lt;trans-attribute&gt;</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>&lt;trans-attribute&gt;</computeroutput> element: + The following is an example of the <computeroutput>&lt;transaction&gt;</computeroutput> and <computeroutput>&lt;trans-attribute&gt;</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>&lt;service-ref&gt;</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>&lt;service-ref&gt;</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>&lt;deployments&gt;</computeroutput> element is a container for <computeroutput>&lt;deployment&gt;</computeroutput> elements. + </para> + <para> +<screen><![CDATA[ +<!ELEMENT deployment (if-exists?,instance)>]]> +</screen> + </para> + <para> + The <computeroutput>&lt;deployment&gt;</computeroutput> element is a container for the <computeroutput>&lt;instance&gt;</computeroutput> element. + </para> + <para> +<screen><![CDATA[ +<!ELEMENT if-exists (#PCDATA)>]]> +</screen> +</para> + <para> + The <computeroutput>&lt;if-exists&gt;</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>&lt;instance&gt;</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>&lt;instance&gt;</computeroutput> element, which also contains the <computeroutput>&lt;security-constraint&gt;</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>&lt;instance-id&gt;</computeroutput> value can be named anything, but it must match the <computeroutput>&lt;instance-ref&gt;</computeroutput>value given in the <filename>*-object.xml</filename> file. + </para> + <para> +<screen><![CDATA[ +<!ELEMENT portlet-ref (#PCDATA)>]]> +</screen> + </para> + <para> + The <computeroutput>&lt;portlet-ref&gt;</computeroutput> element defines the portlet that an instance represents. The <computeroutput>&lt;portlet-ref&gt;</computeroutput> value must match the <computeroutput>&lt;portlet-name&gt;</computeroutput> given in the <filename>WEB-INF/portlet.xml</filename> file. + </para> + <para> +<screen><![CDATA[ +<!ELEMENT preferences (preference+)>]]> +</screen> + </para> + <para> + The <computeroutput>&lt;preferences&gt;</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>&lt;preference&gt;</computeroutput> element configures one preference, which is part of a set of preferences. Use the <computeroutput>&lt;preferences&gt;</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>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. The following is an example of the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</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>&lt;policy-permission&gt;</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>&lt;action-name&gt;</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>&lt;unchecked&gt;</computeroutput> element defines anyone can view the instance. + </para> + <para> +<screen><![CDATA[ +<!ELEMENT role-name (#PCDATA)>]]> +</screen> + </para> + <para> + The <computeroutput>&lt;role-name&gt;</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>&lt;deployments&gt;</computeroutput> element is a container for <computeroutput>&lt;deployment&gt;</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>&lt;deployment&gt;</computeroutput> element is a generic container for portal object elements. The <computeroutput>&lt;parent-ref&gt;</computeroutput> child element gives the name of the parent object that the current object will use as parent. The optional <computeroutput>&lt;if-exists&gt;</computeroutput> element defines the action to take if an instance with the same name already exists. The default behavior of the <computeroutput>&lt;if-exists&gt;</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>&lt;deployment&gt;</computeroutput> and <computeroutput>&lt;parent-ref&gt;</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>&lt;parent-ref&gt;</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>&lt;parent-ref&gt;</computeroutput> element tells the portal where the portlet appears. The syntax for the <computeroutput>&lt;parent-ref&gt;</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> +&lt;parent-ref/&gt; +</screen> + </para> + <para> + The following specifies that the portlet appears in the portal instance named <computeroutput>default</computeroutput>: + </para> + <para> +<screen> +&lt;parent-ref&gt;default&lt;/parent-ref&gt; +</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> +&lt;parent-ref&gt;default.default&lt;/parent-ref&gt; +</screen> + </para> + <para> +<screen><![CDATA[ +<!ELEMENT if-exists (#PCDATA)>]]> +</screen> + </para> + <para> + The <computeroutput>&lt;if-exists&gt;</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>&lt;supported-modes&gt;</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>&lt;supported-mode&gt;</computeroutput> and <computeroutput>&lt;mode&gt;</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>&lt;supported-window-states&gt;</computeroutput> element to define the supported window states of the portal. The following is an example of the <computeroutput>&lt;supported-window-states&gt;</computeroutput> and <computeroutput>&lt;window-state&gt;</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>&lt;window-state&gt;</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>&lt;instance-ref&gt;</computeroutput> and <computeroutput>&lt;content&gt;</computeroutput> elements, configured in the <filename>WEB-INF/*-object.xml</filename> files, define the content of a window. The <computeroutput>&lt;content&gt;</computeroutput> element is generic, and describes any kind of content. The <computeroutput>&lt;instance-ref&gt;</computeroutput> element is a shortcut to define the content-type of the portlet, which points to a portlet instance. The value of <computeroutput>&lt;instance-ref&gt;</computeroutput> must match the value of one of the <computeroutput>&lt;instance-id&gt;</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>&lt;instance-id&gt;</computeroutput> elements in the <filename>WEB-INF/portlet-instances.xml</filename> file. The following is an example of the <computeroutput>&lt;instance-ref&gt;</computeroutput> element: + </para> + <para> +<screen> +&lt;instance-ref&gt;MyPortletInstance&lt;/instance-ref&gt; +</screen> + </para> + <para> +<screen><![CDATA[ +<!ELEMENT region (#PCDATA)>]]> +</screen> + </para> + <para> + The region the window belongs to. The <computeroutput>&lt;region&gt;</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>&lt;content&gt;</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>&lt;content-type&gt;</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>&lt;content-uri&gt;</computeroutput> element specifies which content to display, for example, a portlet instance. To display a file from the CMS, use the <computeroutput>&lt;content-uri&gt;</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>&lt;properties&gt;</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>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. The following is an example of the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</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>&lt;policy-permission&gt;</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>&lt;action-name&gt;</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>&lt;unchecked&gt;</computeroutput> element defines that anyone can view the instance. + </para> + <para> +<screen><![CDATA[ +<!ELEMENT role-name (#PCDATA)>]]> +</screen> + </para> + <para> + The <computeroutput>&lt;role-name&gt;</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>&lt;app-name&gt;</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>&lt;app-name&gt;</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>&lt;deployments&gt;</computeroutput> element encapsulates the entire document, and is a container for <computeroutput>&lt;deployment&gt;</computeroutput> elements. Multiple deployments can be specified within the <computeroutput>&lt;deployments&gt;</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>&lt;deployment&gt;</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>&lt;if-exists&gt;</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>&lt;parent-ref&gt;</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>&lt;parent-ref&gt;</computeroutput> element tells the portal where the portlet appears. The syntax for the <computeroutput>&lt;parent-ref&gt;</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>&lt;window&gt;</computeroutput> element defines a portlet window. The <computeroutput>&lt;window&gt;</computeroutput> element requires an <computeroutput>&lt;instance-ref&gt;</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>&lt;window-name&gt;</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>&lt;instance-ref&gt;</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>&lt;instance-id&gt;</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>&lt;region&gt;</computeroutput> and <computeroutput>&lt;height&gt;</computeroutput> elements define where the window appears within the page layout. The <computeroutput>&lt;region&gt;</computeroutput> element specifies where the window appears on the page. The <computeroutput>&lt;region&gt;</computeroutput> element often depends on other regions defined in the portal layout. The <computeroutput>&lt;height&gt;</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>&lt;deployments&gt;</computeroutput> element encapsulates the entire document, and is a container for <computeroutput>&lt;deployment&gt;</computeroutput> elements. Multiple deployments can be specified within the <computeroutput>&lt;deployments&gt;</computeroutput> element. + </para> + </listitem> + <listitem> + <para> +<programlisting><![CDATA[ +<deployment> + <instance>...</instance> +</deployment>]]></programlisting> + </para> + <para> + The <computeroutput>&lt;deployment&gt;</computeroutput> element, and the embedded <computeroutput>&lt;instance&gt;</computeroutput> element, specify a portlet instance. The <computeroutput>&lt;deployment&gt;</computeroutput> element specifies object deployments, such as portals, pages, windows, and so on. The <computeroutput>&lt;instance&gt;</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>&lt;instance-id&gt;</computeroutput> elements defines a <emphasis role="bold">unique name</emphasis> given to an instance of a portlet. The <computeroutput>&lt;instance-id&gt;</computeroutput> value can be named anything, but it must match the value of one of the <computeroutput>&lt;instance-ref&gt;</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>&lt;portlet-ref&gt;</computeroutput> element defines the portlet that an instance represents. The <computeroutput>&lt;portlet-ref&gt;</computeroutput> value must match the <computeroutput>&lt;portlet-name&gt;</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>&lt;preference&gt;</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>&lt;preference&gt;</computeroutput> element configures one preference, which is part of a set of preferences. Use the <computeroutput>&lt;preferences&gt;</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">&lt;unchecked/&gt;</emphasis> - Anyone can view this page. - </listitem> - <listitem> - <emphasis role="bold">&lt;role-name&gt;SOMEROLE&lt;/role-name&gt;</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>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. This example demonstrates the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. + </para> + <para> + The <computeroutput>&lt;action-name&gt;</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>&lt;role-name&gt;EXAMPLEROLE&lt;/role-name&gt;</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>&lt;header-content&gt;</computeroutput> and <computeroutput>&lt;link&gt;</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>&lt;icon&gt;</computeroutput>, <computeroutput>&lt;small-icon&gt;</computeroutput>, and <computeroutput>&lt;large-icon&gt;</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>&lt;portlet-app&gt;</computeroutput> element encapsulates the entire document. Multiple portlets can be specified using the <computeroutput>&lt;portlet-app&gt;</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>&lt;portlet&gt;</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>&lt;description&gt;</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>&lt;portlet-name&gt;</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>&lt;portlet-class&gt;</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>&lt;init-param&gt;</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>&lt;init-param&gt;</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>&lt;supports&gt;</computeroutput> element declares all of the markup types that a portlet supports. Use the <computeroutput>&lt;mime-type&gt;</computeroutput> element to declare supported capabilities, for example, if the only outputs are text and HTML, use <computeroutput>&lt;mime-type&gt;text/html&lt;/mime-type&gt;</computeroutput>. Use the <computeroutput>&lt;portlet-mode&gt;</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>&lt;portlet-mode&gt;view&lt;/portlet-mode&gt;</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>&lt;supported-locale&gt;</computeroutput> elements advertise the supported locales for the portlet. Use multiple <computeroutput>&lt;supported-locale&gt;</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>&lt;resource-bundle&gt;</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>&lt;title&gt;</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 &lt;deployments&gt;. 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>&lt;deployments&gt;</computeroutput> element, which is a container for <computeroutput>&lt;deployment&gt;</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> +&lt;if-exists&gt; +</screen> + <para> + The <computeroutput>&lt;if-exists&gt;</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> +&lt;parent-ref&gt; +</screen> + <para> + The <computeroutput>&lt;parent-ref&gt;</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>&lt;parent-ref&gt;</computeroutput> element tells the portal where the portlet appears. The syntax for the <computeroutput>&lt;parent-ref&gt;</computeroutput> element is <computeroutput><replaceable>portal-instance</replaceable>.<replaceable>portal-page</replaceable></computeroutput>. + </para> + </listitem> + <listitem> +<screen> +&lt;properties&gt; +</screen> + <para> + A set of generic properties for the portal object. The <computeroutput>&lt;properties&gt;</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">&lt;if-exists&gt;</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> +&lt;page&gt; +</screen> + <para> + The start of a page definition. Among others, the <computeroutput>&lt;page&gt;</computeroutput> element is a container for the <computeroutput>&lt;page-name&gt;</computeroutput>, <computeroutput>&lt;window&gt;</computeroutput>, and <computeroutput>&lt;security-constraint&gt;</computeroutput> elements. + </para> + </listitem> <listitem> - <emphasis role="bold">&lt;parent-ref&gt;</emphasis> - Indicates whether the - object should be hooked in to the portal tree. - </listitem> +<screen> +&lt;page-name&gt; +</screen> + <para> + The page name. + </para> + </listitem> + <listitem> +<screen> +&lt;window&gt; +</screen> + <para> + The <computeroutput>&lt;window&gt;</computeroutput> element defines a portlet window. The <computeroutput>&lt;window&gt;</computeroutput> element requires an <computeroutput>&lt;instance-ref&gt;</computeroutput> element, which assigns a portal instance to a window. + </para> + </listitem> + <listitem> +<screen> +&lt;window-name&gt; +</screen> + <para> + The <computeroutput>&lt;window-name&gt;</computeroutput> element defines the <emphasis role="bold">unique name</emphasis> given to a portlet window. This can be named anything. + </para> + </listitem> + <listitem> +<screen> +&lt;instance-ref&gt; +</screen> + <para> + The <computeroutput>&lt;instance-ref&gt;</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>&lt;instance-id&gt;</computeroutput> elements in the <filename>WEB-INF/portlet-instances.xml</filename> file. + </para> + </listitem> <listitem> - <emphasis role="bold">&lt;properties&gt;</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">&lt;page&gt;</emphasis> - The start of a page - definition. - </listitem> - <listitem> - <emphasis role="bold">&lt;page-name&gt;</emphasis> - The name of the page. - </listitem> - <listitem> - <emphasis role="bold">&lt;window&gt;</emphasis> - The start of a window - definition. - </listitem> - <listitem> - <emphasis role="bold">&lt;window-name&gt;</emphasis> - The name of the - window. - </listitem> - <listitem> - <emphasis role="bold">&lt;instance-ref&gt;</emphasis> - The instance - reference used by this window. Should correspond with the - &lt;instance-name&gt; variable. - </listitem> - <listitem> - <emphasis role="bold">&lt;height&gt;</emphasis> - The vertical position of - this window within the region defined in the layout. - </listitem> - <listitem> - <emphasis role="bold">&lt;instance&gt;</emphasis> - The start of an instance - definition. page. - </listitem> - <listitem> - <emphasis role="bold">&lt;instance-name&gt;</emphasis> - Maps to the above - &lt;instance-ref&gt; variable. - </listitem> - <listitem> - <emphasis role="bold">&lt;component-ref&gt;</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">&lt;unchecked/&gt;</emphasis> - Anyone can view this page. - </listitem> - <listitem> - <emphasis role="bold">&lt;role-name&gt;SOMEROLE&lt;/role-name&gt;</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> +&lt;region&gt;...&lt;/region&gt; +&lt;height&gt;...&lt;/height&gt; +</screen> + <para> + The <computeroutput>&lt;region&gt;</computeroutput> and <computeroutput>&lt;height&gt;</computeroutput> elements define where the window appears within the page layout. The <computeroutput>&lt;region&gt;</computeroutput> element specifies where the window appears on the page. The <computeroutput>&lt;region&gt;</computeroutput> element often depends on other regions defined in the portal layout. The <computeroutput>&lt;height&gt;</computeroutput> element can be assigned a value between one and <replaceable>X</replaceable>. + </para> + </listitem> + <listitem> +<screen> +&lt;instance&gt; +</screen> + <para> + The <computeroutput>&lt;instance&gt;</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> +&lt;instance-name&gt; +</screen> + <para> + The <computeroutput>&lt;instance-name&gt;</computeroutput> element maps to the <computeroutput>&lt;instance-ref&gt;</computeroutput> element. + </para> + </listitem> + <listitem> +<screen> +&lt;component-ref&gt; +</screen> + <para> + The <computeroutput>&lt;component-ref&gt;</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>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. The following is an example of the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</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> +&lt;action-name&gt; +</screen> + </para> + <para> + The <computeroutput>&lt;action-name&gt;</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> +&lt;unchecked/&gt; +</screen> + </para> + <para> + If present, the <computeroutput>&lt;unchecked&gt;</computeroutput> element defines that anyone can view the instance. + </para> + <para> +<screen> +&lt;role-name&gt; +</screen> + </para> + <para> + The <computeroutput>&lt;role-name&gt;</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> +&lt;role-name&gt;EXAMPLEROLE&lt;/role-name&gt; +</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>