[portal-commits] JBoss Portal SVN: r9869 - docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules.

Author: thomas.heute(a)jboss.com Date: 2008-02-08 05:56:20 -0500 (Fri, 08 Feb 2008) New Revision: 9869 Modified: docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/configuration.xml docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/installation.xml docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/migration.xml docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/tutorials.xml Log: Merge with Branch_2_6 Modified: docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/configuration.xml =================================================================== --- docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/configuration.xml 2008-02-08 10:45:01 UTC (rev 9868) +++ docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/configuration.xml 2008-02-08 10:56:20 UTC (rev 9869) @@ -46,44 +46,22 @@ </para> </sect1> <sect1 id="configuration-contextroot"> - <title>Changing the context path</title> - <para>By default, the "main" page of JBoss portal will be accessible at - <literal>http://localhost:8080/portal/index.html</literal> - . You may want to change that - either to a different name or to - <literal>http://localhost:8080/index.html</literal> - . - </para> - <note> - By default, Tomcat holds on to the root context '/'. You may need to either remove - <literal>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROOT.war</literal> - or add a <literal>jboss-web.xml</literal> file (declaring another context-root other than '/') under - <literal>ROOT.war/WEB-INF</literal> directory for the below changes to take effect on restart. - <programlisting><![CDATA[ -<?xml version="1.0"?> -<jboss-web> - <context-root>/tomcat-root</context-root> -</jboss-web>]]></programlisting> - </note> - <para>You can accomplish this, with either a deployed jboss-portal.sar or before you build from source: - <itemizedlist> - <listitem> - <para> - <emphasis role="bold">Binary method:</emphasis> - <orderedlist> - <listitem> - <para>Open - <emphasis> - JBOSS_INSTALL_DIRECTORY/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/jboss-web.xml - </emphasis> + <title>Changing the Context Path</title> + <para>By default, the main JBoss Portal page is accessible by navigating to <emphasis>http://localhost:8080/portal/index.html</emphasis>. This +can be changed to a different path, for example, +<emphasis>http://localhost:8080/index.html</emphasis>. The context path can be changed when using the deployed <filename>jboss-portal.sar/</filename>, or before building from source. To change the context path when using the JBoss Portal binary package: +</para> +<para> + <orderedlist> + <listitem> + <para>Open the <emphasis>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/portal-server.war/WEB-INF/jboss-web.xml</emphasis> file. If this file does not exist, copy and save the following example: <programlisting><![CDATA[ <?xml version="1.0"?> <jboss-web> <security-domain>java:jaas/portal</security-domain> <context-root>/portal</context-root> <replication-config> - <replication-trigger>SET_AND_GET</replication-trigger> - <replication-type>SYNC</replication-type> + <replication-trigger>SET</replication-trigger> </replication-config> <resource-ref> <res-ref-name>jdbc/PortalDS</res-ref-name> @@ -94,121 +72,185 @@ </listitem> <listitem> <para>Edit the - <emphasis>context-root</emphasis> - element to whatever you desire. - <programlisting><![CDATA[<context-root>/</context-root>]]></programlisting> - </para> + <computeroutput>&lt;context-root&gt;</computeroutput> element with the desired context path: + </para> + <para> +<screen> +<![CDATA[<context-root>/testing</context-root>]]> +</screen> + </para> + <para> + Using this example, the main JBoss Portal page would be reached by navigating to <emphasis>http://localhost:8080/testing</emphasis>. + </para> </listitem> </orderedlist> </para> - </listitem> + <para> + To change the context path when building from source: + </para> + <para> + <orderedlist> <listitem> <para> - <emphasis role="bold">Source method:</emphasis> - Edit the file - <literal>$PORTAL_HOME/build/local.properties</literal> - (You can copy the file - <literal>$PORTAL_HOME/build/etc/local.properties-example</literal> - and modify it for your - own settings.) and change - <literal>portal.web.context-root</literal> - to anything you want. - <para>Now clean the project (ant clean) then build JBoss portal (ant) and redeploy it for the context - path changes to take - effect. For build instructions, please see: - <xref linkend="install_source"/> - </para> - </para> - </listitem> - </itemizedlist> - </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>. + </para> + </listitem> + <listitem> + <para> + Open the <filename>build/local.properties</filename> file and edit the <computeroutput>portal.web.context-root</computeroutput> option with the desired context path: + </para> + <para> +<screen> +# Context root for the portal main servlet +portal.web.context-root=/testing +</screen> + </para> + <para> + Using this example, the main JBoss Portal page would be reached by navigating to <emphasis>http://localhost:8080/testing</emphasis>. + </para> + </listitem> + <listitem> + + <para> + To clean the project, make sure you are connected to the Internet, and change into the <filename>build/</filename> directory. Run the <command>ant clean</command> command. + </para> + </listitem> + <listitem> + <para> + Re-build and re-deploy JBoss Portal. See <xref linkend="install_source"/> for build instructions. + </para> + </listitem> + </orderedlist> +</para> + <para> + <note> + <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 + context-root other than <emphasis>/</emphasis>, under the <filename>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/ROOT.war/WEB-INF/</filename> directory, for the above changes to take affect. The following is an example <filename>jboss-web.xml</filename> file, which changes the Tomcat context path to <computeroutput>/tomcat-root</computeroutput>: + </para> + <para> +<screen><![CDATA[ +<?xml version="1.0"?> +<jboss-web> + <context-root>/tomcat-root</context-root> +</jboss-web>]]></screen> + </para> + </note> +</para> </sect1> <sect1 id="configuration-hibdialect"> - <title>Forcing the DB dialect</title> - <para>If you encounter that the Hibernate dialect is not working properly and would like to - override the default behavior, follow the instructions contained in this section: - <note>Under most common circumstances, the auto-detect feature should work fine.</note> + <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. </para> <sect2> - <title>DB Dialect settings for Portal</title> - <para>You will need to modify all the <literal>hibernate.cfg.xml</literal> files in all the Portal modules you - intend to use by uncommenting the following line in these files and using the appropriate dialect (see - <ulink url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-... - </ulink> for a list of supported dialects in Hibernate 3): - <programlisting><![CDATA[ + <title>Database Dialect Settings for JBoss Portal</title> + <para> + All <filename>hibernate.cfg.xml</filename> files in all JBoss Portal modules you intend to use need to be modified. The <filename>hibernate.cfg.xml</filename> files are found in the <filename>jboss-portal.sar/<replaceable>module</replaceable>/conf/hibernate/<replaceable>directory</replaceable>/</filename> directory, where <replaceable>module</replaceable> is the module name, and <replaceable>directory</replaceable> is a directory that, depending on the module, may or may not exist. + </para> + <para> + To modify these files to force the DB dialect, un-comment the following line from each <filename>hibernate.cfg.xml</filename> file in each JBoss Portal module you intend to use, so that it looks like the following: + </para> + <para> +<screen><![CDATA[ <!-- Force the dialect instead of using autodetection --> -<!-- <property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property> --->]]></programlisting> - </para> - <para>These files are found in <literal>jboss-portal.sar/[module]/conf/hibernate/[directory]/hibernate.cfg.xml</literal> - where <literal>[module]</literal> is a module name and <literal>[directory]</literal> is a directory that - may or may not be present. - </para> +]]></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>. + </para> </sect2> <sect2> - <title>DB Dialect settings for the CMS component</title> - <para>Modify <literal>jboss-portal.sar/portal-cms.sar/conf/hibernate/cms/hibernate.cfg.xml</literal> by - uncommenting the following line in these files and using the appropriate dialect (see - <ulink url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-... - </ulink> for a list of supported dialects in Hibernate 3): - <programlisting><![CDATA[ + <title>DB Dialect Settings for the CMS Component</title> + <para> + To modify the DB dialect setting for the JBoss Portal CMS component: + </para> + <para> + <orderedlist> + <listitem> + <para> + Open the <filename>jboss-portal.sar/portal-cms.sar/conf/hibernate/cms/hibernate.cfg.xml</filename> file. + </para> + </listitem> + <listitem> + <para> + Un-comment the following line, so that it looks like the following: + </para> + <para> +<screen><![CDATA[ <!-- Force the dialect instead of using autodetection --> -<!-- <property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property> --->]]></programlisting> - </para> +]]></screen> + </para> + </listitem> + </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>. + </para> </sect2> </sect1> <sect1 id="emailConfiguration"> - <title>Setting up the email service</title> - <para>To be able to use the email service (for example to verify user emails when someone subscribes or for CMS - workflow notifications) it has to be configured correctly. To configure it, go to - <literal>jboss-portal.sar/portal-core.sar/META-INF/jboss-service.xml</literal>. - In this file, the mail module is configured like this: - <programlisting><![CDATA[<mbean - code="org.jboss.portal.core.impl.mail.MailModuleImpl" - name="portal:service=Module,type=Mail" - xmbean-dd="" - xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> - <xmbean/> - <depends>jboss:service=Mail</depends> - <depends>portal:service=Module,type=IdentityServiceController</depends> - <attribute name="QueueCapacity">-1</attribute> - <attribute name="Gateway">localhost</attribute> - <attribute name="SmtpUser"></attribute> - <attribute name="SmtpPassword"></attribute> - <attribute name="JavaMailDebugEnabled">false</attribute> - <attribute name="SMTPConnectionTimeout">100000</attribute> - <attribute name="SMTPTimeout">10000</attribute> - <attribute name="JNDIName">java:portal/MailModule</attribute> -</mbean>]]></programlisting> - Here you can specify a different SMTP server than localhost, then precise the SMTP username and SMTP password to - use to send emails.</para> - <para>For example, to use GMail's SMTP server: - <programlisting><![CDATA[<mbean - code="org.jboss.portal.core.impl.mail.MailModuleImpl" - name="portal:service=Module,type=Mail" - xmbean-dd="" - xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> - <xmbean/> - <depends>jboss:service=Mail</depends> - <depends>portal:service=Module,type=IdentityServiceController</depends> - <attribute name="QueueCapacity">-1</attribute> - <attribute name="Gateway">smtp.gmail.com</attribute> - <attribute name=&quot;SmtpUser&quot;&gt;username(a)gmail.com&lt;/attribute&gt; - <attribute name="SmtpPassword">myPassword</attribute> - <attribute name="JavaMailDebugEnabled">false</attribute> - <attribute name="SMTPConnectionTimeout">100000</attribute> - <attribute name="SMTPTimeout">10000</attribute> - <attribute name="JNDIName">java:portal/MailModule</attribute> -</mbean>]]></programlisting> + <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. </para> - <note><para>If you have a 'standard' setup and a mail server installed - (That's the case on most Linux distribution out of the box), it will work out of the box.</para></note> - </sect1> + <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: + </para> + <para> +<screen><![CDATA[ +<mbean +code="org.jboss.portal.core.impl.mail.MailModuleImpl" +name="portal:service=Module,type=Mail" +xmbean-dd="" +xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> +<xmbean/> +<depends>jboss:service=Mail</depends> +<depends>portal:service=Module,type=IdentityServiceController</depends> +<attribute name="QueueCapacity">-1</attribute> +<attribute name="Gateway">localhost</attribute> +<attribute name="SmtpUser"></attribute> +<attribute name="SmtpPassword"></attribute> +<attribute name="JavaMailDebugEnabled">false</attribute> +<attribute name="SMTPConnectionTimeout">100000</attribute> +<attribute name="SMTPTimeout">10000</attribute> +<attribute name="JNDIName">java:portal/MailModule</attribute> +</mbean>]]> +</screen> + </para> + <para> + A different SMTP server (other than localhost) can be configured, along with a SMTP username and an SMTP password. The following is an example configuration that uses the Gmail SMTP server: + </para> + <para> +<screen><![CDATA[ +<mbean +code="org.jboss.portal.core.impl.mail.MailModuleImpl" +name="portal:service=Module,type=Mail" +xmbean-dd="" +xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean"> +<xmbean/> +<depends>jboss:service=Mail</depends> +<depends>portal:service=Module,type=IdentityServiceController</depends> +<attribute name="QueueCapacity">-1</attribute> +<attribute name="Gateway">smtp.gmail.com</attribute> +<attribute name=&quot;SmtpUser&quot;&gt;username(a)gmail.com&lt;/attribute&gt; +<attribute name="SmtpPassword">myPassword</attribute> +<attribute name="JavaMailDebugEnabled">false</attribute> +<attribute name="SMTPConnectionTimeout">100000</attribute> +<attribute name="SMTPTimeout">10000</attribute> +<attribute name="JNDIName">java:portal/MailModule</attribute> +</mbean>]]> +</screen> + </para> + <para> + Using this example, replace <computeroutput&gt;username(a)gmail.com&lt;/computeroutput&gt; and <computeroutput>myPassword</computeroutput> with your correct Gmail username and password. + </para> +</sect1> <sect1> - <title>Setting up proxy settings</title> + <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 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 @@ -219,19 +261,24 @@ is enough.</para> </sect1> <sect1> - <title>Disabling dynamic proxy unwrapping</title> - <para>JBoss Portal use the JBoss Microkernel for the service infrastructure. The JBoss Microkernel provides - injection of services into other services, also known as wiring. Unfortunately it is only possible to inject - dynamic proxies that talks to the MBeanServer due to the fact the Microkernel is JMX based. The overhead - at runtime is minimal since the Microkernel implementation is highly optimized, however when it is used - with Java 5 a noticeable bottleneck appears due to the fact that the implementation - of the JMX API classes <emphasis>javax.management.*</emphasis> provided by the Java Platform performs synchronization. This does - not happen 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 JBossServiceModelMBean which allows to - unwrap the injected dynamic proxies and replace them by the real POJO services. This allows to remove the - bottleneck with Java 5 and provide an extra boost of performances on JDK 1.4. By default that feature - is enabled but it is possible to disabled it using command line arguments.</para> - <programlisting><![CDATA[ ->run.sh -Dportal.kernel.no_proxies=false]]></programlisting> + <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> + <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: + </para> + <para> +<screen> +./run.sh -Dportal.kernel.no_proxies=false +</screen> +</para> +<para> + On Microsoft Windows systems, run the following command: +</para> +<para> +<screen> +run.bat -Dportal.kernel.no_proxies=false +</screen> +</para> </sect1> </chapter> Modified: docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/installation.xml =================================================================== --- docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/installation.xml 2008-02-08 10:45:01 UTC (rev 9868) +++ docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/installation.xml 2008-02-08 10:56:20 UTC (rev 9869) @@ -25,7 +25,7 @@ </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. + <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. </para> </listitem> <listitem> @@ -125,7 +125,7 @@ </imageobject> </mediaobject> <para> - 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 or minimal. For example, if you are using the all configuration, copy the Datasource descriptor into the <filename>$JBOSS_HOME/server/all/deploy/</filename> directory. + 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: @@ -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. + <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. </para> </listitem> <listitem> @@ -348,7 +348,7 @@ <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_HOME_DIRECTORY/build/</filename> directory. 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, 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> <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: @@ -375,7 +375,7 @@ <orderedlist> <listitem> <para> - Change into the <filename>JBOSS_PORTAL_HOME_DIRECTORY/build/</filename> directory, and run the following command: + Change into the <filename>JBOSS_PORTAL_SOURCE_DIRECTORY/build/</filename> directory, and run the following command: </para> <para> <screen> @@ -385,7 +385,7 @@ </listitem> <listitem> <para> - Change into the <filename>JBOSS_PORTAL_HOME_DIRECTORY/core/</filename> directory, and run the following command: + Change into the <filename>JBOSS_PORTAL_SOURCE_DIRECTORY/core/</filename> directory, and run the following command: </para> <para> <screen> @@ -441,7 +441,7 @@ </imageobject> </mediaobject> <para> - 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. + 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: @@ -477,7 +477,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. + <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. </para> </listitem> <listitem> Modified: docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/migration.xml =================================================================== --- docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/migration.xml 2008-02-08 10:45:01 UTC (rev 9868) +++ docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/migration.xml 2008-02-08 10:56:20 UTC (rev 9869) @@ -11,124 +11,134 @@ <email>boleslaw dot dawidowicz at redhat dot com</email> </author> </chapterinfo> - <title>Upgrading 2.4 - 2.6</title> + <title>Upgrading JBoss Portal 2.4 to 2.6</title> + <para> <warning> - Before performing any instructions or operations mentioned below remember to backup your database content and - the whole application server directory! + <para> + Before performing any instructions or operations in this chapter, back up your database content and + the entire JBoss EAP or JBoss AS directory! + </para> </warning> + </para> <sect1 id="manual_migration"> - <title>Manual upgrade</title> + <title>Manual Upgrade</title> <para> - Although database schema remains the same in JBoss Portal 2.6 there are several differences that prevent from simple deployment - of newest portal version using JBoss Portal 2.4 database. In this chapter we will list major ones and give - instructions on how to manually update proper data. + 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. </para> <para> - Upgrading procedure can be quite straightforward: - <itemizedlist> + The upgrade procedure can be straightforward: + </para> + <para> + <orderedlist> <listitem> - Remove <emphasis role="bold">$JBOSS_HOME/server/default/deploy/jboss-portal.sar</emphasis> file. + <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> - Update data in portal database like described in following sections of this chapter + <para> + Update the data in the JBoss Portal database, as described in <xref linkend="upgrade_portal_database"/>. + </para> </listitem> <listitem> - Deploy JBoss Portal 2.6 + <para> + Deploy JBoss Portal 2.6. + </para> </listitem> - </itemizedlist> + </orderedlist> </para> <sect2> - <title>Theme</title> + <title>Themes</title> + <para> + Themes in JBoss Portal 2.6 have changed since the Portal pages now contain additional areas, such as the <guiicon>Login</guiicon>, <guiicon>Admin</guiicon>, and <guiicon>Dashboard</guiicon> links, on the top right-hand corner: + </para> + <para> <mediaobject> <imageobject> <imagedata align="center" valign="middle" fileref="images/migration/theme.png"/> </imageobject> </mediaobject> + </para> <para> - Themes in 2.6 version changed as now they - contain additional areas - the best example is upper right corner where links like "Login", "Admin", "My Dashboard" - are visable. If you use default theme like "renaissance" that is present in 2.6, you shouldn't need to do anything. To update your custom themes please - refer to those bundled with portal as an example. - </para> - <note>If you stay with old theme files you may find JBP 2.6 unusable to the point that you may not even be able to log in</note> + If you use a default theme that exists in JBoss Portal 2.6, 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, please refer to those bundled with JBoss Portal as an example. + </para> </sect2> - <sect2> - <title>Database</title> - <note>All things described in this section can be done using AdminPortlet. Treat this directions more as guideline - if you need to automate migration for big portal deployment.</note> + <sect2 id="upgrade_portal_database"> + <title>Updating the Database</title> <para> - Database schema wasn't changed between 2.4 and 2.6 releases, but still content that is kept in it - changed slightly in few areas. You can easily update the data manually by using tools proper for your - RDBMS. If you use <emphasis>MySQL</emphasis> you can use <emphasis>MySQL Query Browser</emphasis> that can - be downloaded from <emphasis>MySQL</emphasis> website. + All procedures described in the following sections can performed using the AdminPortlet. Treat the directions as guidelines if you need to automate the migration of a large JBoss Portal deployment. + </para> + <para> + 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> - <note> - Instructions below refer to standard JBoss Portal 2.4 deployment. If you named core portlets, portlet instances - or portlet windows differently you will need to make proper modifications in those steps. - </note> + <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: + </para> + <para> <mediaobject> <imageobject> <imagedata align="center" valign="middle" fileref="images/migration/querybrowser1.png"/> </imageobject> </mediaobject> - <sect3> - <title>Portlet names</title> - <para>Names of few core bundled portlets changed. To update them you need to:</para> + </para> +</sect2> + <sect2> + <title>Portlet Names</title> <para> - In <emphasis role="bold">JBP_INSTANCES</emphasis> table: - <itemizedlist> - <listitem>Change "<emphasis>local.portal.CMSPorlet</emphasis>" in <emphasis>PORTLET_REF</emphasis> column to - "<emphasis>local./portal-cms.CMSPortlet</emphasis>" - </listitem> - <listitem>Change "<emphasis>local.portal.CMSAdminPorlet</emphasis>" in <emphasis>PORTLET_REF</emphasis> column to - "<emphasis>local./portal-cms.CMSAdminPortlet</emphasis>" - </listitem> - <listitem>Change "<emphasis>local.portal.ManagementPorlet</emphasis>" in <emphasis>PORTLET_REF</emphasis> column to - "<emphasis>local./portal-admin.AdminPortlet</emphasis>" - </listitem> - </itemizedlist> - </para> - <note>Instead of editing database you can destroy those instances in AdminPortlet and recreate them.</note> + 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: + </para> + <para> + <orderedlist> + <listitem> + <para> + Change <emphasis>local.portal.CMSPorlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column to <emphasis>local./portal-cms.CMSPortlet</emphasis>. + </para> + </listitem> + <listitem> + <para> + Change <emphasis>local.portal.CMSAdminPorlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column to <emphasis>local./portal-cms.CMSAdminPortlet</emphasis>. + </para> + </listitem> + <listitem> + <para> + Change <emphasis>local.portal.ManagementPorlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column to <emphasis>local./portal-admin.AdminPortlet</emphasis>. + </para> + </listitem> + </orderedlist> + </para> <para> - <emphasis>NavigationPortlet</emphasis> from JBP 2.4 is not present anymore. Its functionality is now realized by - <emphasis>PageCustomizerInterceptor</emphasis> so all references to <emphasis>NavigationPortlet</emphasis> should - be removed from all portal pages. You can do it either by cleaning up database content or by using - <emphasis>AdminPortlet</emphasis> in Portal interface. In database you should remove: - <itemizedlist> - <listitem> - Rows containing "<emphasis>local.portal.NavigationPortlet</emphasis>" in - "<emphasis>PORTLET_REF</emphasis>" column in - "<emphasis>JBP_INSTANCES</emphasis>" table. - </listitem> - <listitem> - Rows containing "<emphasis>NavigationPortletInstance</emphasis>" in - "<emphasis>INSTANCE_REF</emphasis>" column in - "<emphasis>JBP_WINDOW</emphasis>" table. - </listitem> - <listitem> - Rows containing "<emphasis>NavigationPortletWindow</emphasis>" in - "<emphasis>NAME</emphasis>" column in - "<emphasis>JBP_OBJECT</emphasis>" table. - </listitem> - </itemizedlist> - </para> - <note>Instead of editing database you can just remove NavigationPortletInstance using AdminPortlet.</note> - </sect3> - <sect3> + 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: + </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. + </para> + </listitem> + <listitem> + <para> + In the <emphasis>JBP_WINDOW</emphasis> table, rows containing <emphasis>NavigationPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + In the <emphasis>JBP_OBJECT</emphasis> table, rows containing <emphasis>NavigationPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + </orderedlist> + </para> + </sect2> + <sect2> <title>CMS</title> <para> - This is probably the less trival part to do directly in database. In JBP 2.6 version the way that CMS - content is being displayed changed significantly. Please refer to - <link linkend="contentintegration">Content Integration</link> and <link linkend="cmsPortlet">CMS Portlet</link> - chapters for more information. Basically currently there is no need to have more than one instance of - <emphasis>CMSPortlet</emphasis> and the portlet window displays CMS content not by referring to that portlet instance - but by having proper <emphasis>content-type</emphasis> defined. In "<emphasis>default-object.xml</emphasis> - you will find following configuration: - <programlisting> - <![CDATA[ + In JBoss Portal 2.6 versions, the way the CMS content is displayed changed significantly. For further information, please 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> @@ -137,53 +147,53 @@ </content> <region>center</region> <height>0</height> -</window> - ]]> - </programlisting> +</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 CMS in your JBoss Portal deployment. Identify any row referring to <emphasis>CMSPortletWindow</emphasis>, and remember the number in <emphasis role="bold">PK</emphasis> column. The <emphasis role="bold">PK</emphasis> number is needed in the following steps: </para> <para> - Open <emphasis role="bold">JBP_OBJECT_NODE</emphasis> table in your database schema. By looking at - <emphasis role="bold">PATH</emphasis> column you will easily find any occurances of CMS in your portal - deployment - </para> <mediaobject> <imageobject> <imagedata align="center" valign="middle" fileref="images/migration/querybrowser2.png"/> </imageobject> </mediaobject> + </para> <para> - For any row you will identify as referring to <emphasis>CMSPortletWindow</emphasis> in your system remember - the number in <emphasis role="bold">PK</emphasis> column. It will be needed in next steps + 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> Go to <emphasis role="bold">JBP_WINDOW</emphasis> table and find row with the same - <emphasis role="bold">PK</emphasis> value like the one from - <emphasis role="bold">JBP_OBJECT_NODE</emphasis> table. In such row replace - "<emphasis>CMSPortletInstance</emphasis>" with a path to your CMS resource. For example by default - portal is displaying "<emphasis>/default/index.html</emphasis>". - </para> - <para> Go to <emphasis role="bold">JBP_PORTAL_OBJECT_PROPS</emphasis> table and add a row containing: + <para> Go to the <emphasis role="bold">JBP_PORTAL_OBJECT_PROPS</emphasis> table and add a row containing: <itemizedlist> <listitem> - The number you remembered in "<emphasis>OBJECT_KEY</emphasis>" column. - </listitem> - <listitem> - "<emphasis>portal.windowContentType</emphasis>" in "<emphasis>NAME</emphasis>" column. - </listitem> - <listitem> - "<emphasis>cms</emphasis>" in "<emphasis>jbp_VALUE</emphasis>" column. - </listitem> - </itemizedlist> - </para> + <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> - <note>Remember that you can also change portlet window content type and configure path to CMS resource - using AdminPortlet</note> + <note> + <title>Portlet Content Type and Path to the CMS Resource</title> + <para> + You can change the portlet window content type and configure the path to the CMS resource + using the AdminPortlet. + </para> + </note> </para> - </sect3> - </sect2> - - - - </sect1> + </sect2> +</sect1> <!-- <para>This chapter addresses migration issues from version 2.2 to 2.4 of JBoss Portal.</para> <sect1 id="migrating_database"> Modified: docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/tutorials.xml =================================================================== --- docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/tutorials.xml 2008-02-08 10:45:01 UTC (rev 9868) +++ docs/tags/JBoss_Portal_2_6_4/referenceGuide/en/modules/tutorials.xml 2008-02-08 10:56:20 UTC (rev 9869) @@ -19,39 +19,47 @@ <title>Portlet Primer</title> <sect1 id="portlet_primer"> <title>JSR-168 Overview</title> - <para>The JSR-168 specification aims at defining porlets that can be used by any JSR-168 portlet container also - called portals. There are different portals out there with commercial and non-commercial licences. In this - chapter we will briefly describe such portlets but for more details you should read the specifications - available on the web.</para> + <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> - <note>This section is a brief overview of the - <ulink url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet Specification</ulink> - , and it does not cover the topics in great detail. We strongly encourage portlet developers to read the - Specification that can be found - <ulink url="http://www.jcp.org/en/jsr/detail?id=168">here</ulink... - . - </note> + JBoss Portal is fully JSR-168 compliant, which means any JSR-168 portlet will behave as it should inside the portal. </para> - <para>As of today, JBoss portal is fully JSR-168 compliant, that means that any JSR-168 portlet will behave - as it should inside the portal.</para> <sect2> <title>Portal Pages</title> - <para>A portal can be seen as pages with different areas and inside areas, different windows and each window - having one portlet.</para> + <para> + A portal can be seen as pages with different areas, and inside areas, different windows, and each window + having one portlet: + </para> + <para> <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/SpecPortalDef.png" valign="middle"/> </imageobject> </mediaobject> + </para> </sect2> <sect2> <title>Rendering Modes</title> - <para>A porlet can have different view modes, three modes are defined by the specification but a portal can - extend those modes. The 3 modes are: + <para>A portlet can have different view modes. Three modes are defined by the JSR-168 specification, but a portal can + extend those modes. The three modes are: + </para> + <para> <itemizedlist> - <listitem>VIEW - Generates markup reflecting the current state of the portlet.</listitem> - <listitem>EDIT - Should allow a user to customize the behavior of the portlet.</listitem> - <listitem>HELP - Should provide some information to the user as to how to use the portlet.</listitem> + <listitem> + <para> + VIEW - generates markup reflecting the current state of the portlet. + </para> + </listitem> + <listitem> + <para> + EDIT - 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. + </para> + </listitem> </itemizedlist> </para> </sect2> @@ -59,28 +67,41 @@ <title>Window States</title> <para> Window states are an indicator of how much page real-estate a portlet should consume on any given page. - There are 3 states defined by the specification: + The three states defined by the JSR-168 specification are: + </para> + <para> <itemizedlist> - <listitem>NORMAL - A portlet shares this page with other portlets.</listitem> - <listitem>MINIMIZED - A portlet may show very little information or none at all.</listitem> - <listitem>MAXIMIZED - A portlet may be the only portlet displayed on this page.</listitem> + <listitem> + <para> + NORMAL - a portlet shares this page with other portlets. + </para> + </listitem> + <listitem> + <para> + MINIMIZED -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. + </para> + </listitem> </itemizedlist> </para> </sect2> <sect2> <title>Section Status</title> - This overview of the portlet specification, is a work in progress. Check back for more in-depth analsis of the - specification, but please read on for real-world cases of how to leverage the specification. + <para> + This overview of the JSR-168 Portlet Specification is a work in progress. Check back for more in-depth analsis of the specification. The sections following here after contain real-world cases for how to leverage the specification. + </para> </sect2> </sect1> <sect1 id="tutorials_tutorials"> <title>Tutorials</title> <para> The tutorials contained in this chapter are targetted toward portlet developers. Although they are a good - starting and reference point, we do heavily recommend that portlet developers read and understand the - <ulink url="http://www.jcp.org/en/jsr/detail?id=168">Portlet Specification (JSR-168)</ulink>. We also recommend - using our <ulink url="http://jboss.org/index.html?module=bb&amp;op=viewforum&... Portal User - Forums</ulink> for user-to-user help, when needed. + starting and reference point, it is highly recommend that portlet developers read and understand the + <ulink url="http://www.jcp.org/en/jsr/detail?id=168">JSR-168 Portlet Specification</ulink>. Use the <ulink url="http://jboss.org/index.html?module=bb&amp;op=viewforum&... Portal User Forums</ulink> for user-to-user help. </para> <!--<sect2 id="build_instructions"> <title> @@ -116,21 +137,18 @@ </sect2>--> <sect2> - <title>Deploying your first portlet</title> + <title>Deploying your First Portlet</title> <sect3> <title>Introduction</title> - <para>This section will introduce the reader to deploying his first portlet in JBoss Portal. It requires you - download the HelloWorldPortlet from PortletSwap.com, using this - <ulink - url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...;. - </para> + <para> + This section details deploying your first portlet in JBoss Portal. 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> </sect3> <sect3> <title>Package Structure</title> <para> - Portlets are packaged in WAR files, just like other JEE applications. A typical portlet WAR file can also - include servlets, resource bundles, images, HTML, JSPs, and other static or dynamic files you would - commonly include. + 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: </para> <para> <mediaobject> @@ -141,15 +159,16 @@ </para> </sect3> <sect3> - <title>Portlet Class</title> + <title>Portlet Classes</title> <para> - Included in the - <ulink url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_4/bundles... - download bundle</ulink> you should have one java source file: - <literal>HelloWorldPortlet\src\main\org\jboss\portlet\hello\HelloWorldPortlet.java</literal>, and it - should contain the following: - <programlisting><![CDATA[package org.jboss.portlet.hello; + The following is the <filename>HelloWorldPortlet/src/main/org/jboss/portlet/hello/HelloWorldPortlet.java</filename> java source file, which comes bundled with the <ulink + url="http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles...;: + </para> + <para> +<screen><![CDATA[ +package org.jboss.portlet.hello; + import javax.portlet.GenericPortlet; import javax.portlet.PortletException; import javax.portlet.RenderRequest; @@ -159,84 +178,97 @@ import java.io.PrintWriter; public class HelloWorldPortlet extends GenericPortlet + { - protected void doView(RenderRequest rRequest, RenderResponse rResponse) - throws PortletException, IOException, UnavailableException - { - rResponse.setContentType("text/html"); - PrintWriter writer = rResponse.getWriter(); - writer.write("Hello World!"); - writer.close(); - } -}]]> - </programlisting> - Now let's dissect our simplest of portlets: - <itemizedlist> - <listitem> - <para> - <programlisting>public class HelloWorldPortlet extends GenericPortlet</programlisting> - All Portlets MUST implement the <literal>javax.portlet.Portlet</literal> interface. The Portlet - API also provides a convenience implementation of this interface in the form of the - <literal>javax.portlet.GenericPortlet</literal> class which, among other things, implements + protected void doView(RenderRequest rRequest, RenderResponse rResponse) + throws PortletException, IOException, UnavailableException + + { + rResponse.setContentType("text/html"); + PrintWriter writer = rResponse.getWriter(); + writer.write("Hello World!"); + writer.close(); + } + +} ]]> +</screen> + </para> + <para> + <variablelist> + <varlistentry><term><screen> +public class HelloWorldPortlet extends GenericPortlet</screen></term> + <listitem> + <para> + All portlets must implement the <literal>javax.portlet.Portlet</literal> interface. The portlet + API provides a convenient implementation of this interface, in the form of the + <literal>javax.portlet.GenericPortlet</literal> class, which among other things, implements the <literal>Portlet render</literal> method to dispatch to abstract mode-specific methods to - make it easier to support the standard portlet modes. It also provides - a default implementation for <literal>processAction</literal>, <literal>init</literal> and - <literal>destory</literal> methods. It is recommended to extend <literal>GenericPortlet</literal> + make it easier to support the standard portlet modes. As well, it provides + a default implementation for the <literal>processAction</literal>, <literal>init</literal> and + <literal>destroy</literal> methods. It is recommended to extend <literal>GenericPortlet</literal> for most cases. - </para> - </listitem> - <listitem> - <para> - <programlisting>protected void doView(RenderRequest rRequest, RenderResponse rResponse) throws - PortletException, IOException, UnavailableException</programlisting> - As we extend from <literal>GenericPortlet</literal> and we are only interested in supported the - <literal>VIEW</literal> mode, we only need to implement the <literal>doView</literal> method, - and <literal>GenericPortlet</literal>'s <literal>render</literal> implementation will call our - implementation when the <literal>VIEW</literal> mode is requested. - </para> - </listitem> - <listitem> - <para> - <programlisting>rResponse.setContentType("text/html");</programlisting> - Just like in the servlet-world, you must declare what content-type the portlet will be - responding in. You need to do this before starting to write content or the portlet will throw - an exception. - </para> - </listitem> - <listitem> - <para> - <programlisting><![CDATA[ -PrintWriter writer = rResponse.getWriter(); -writer.write("Hello World!"); -writer.close();]]></programlisting> - Here we output the text - <literal>Hello World!</literal> - in our portlet window. - <note> - Portlets are responsible for generating markup fragments, as they are included on a page and - surrounded by other portlets. In particular, this means that a portlet outputting HTML MUST - not output any markup that cannot be found in a <literal>body</literal> element. - </note> - </para> - </listitem> - </itemizedlist> - </para> + </para> + </listitem> + </varlistentry> + <varlistentry><term><screen> +protected void doView(RenderRequest rRequest, RenderResponse rResponse) +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. + </para> + </listitem> + </varlistentry> + <varlistentry><term><screen> +rResponse.setContentType("text/html");</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. + </para> + </listitem> + </varlistentry> + <varlistentry><term><screen> +PrintWriter writer = rResponse.getWriter(); +writer.write("Hello World!"); +writer.close();</screen></term> + <listitem> + <para> + This produces the <literal>Hello World!</literal> text in our portlet window. + </para> + </listitem> + </varlistentry> + </variablelist> +</para> +<para> + <note> + <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 + not output any markup that cannot be found in a <literal>&lt;body&gt;</literal> element. + </para> + </note> +</para> </sect3> <sect3 id="first_portlet_descriptors"> <title>Application Descriptors</title> <para> - JBoss Portal requires certain descriptors be included in your portlet WAR, for different reasons. Some of - these descriptors are defined by the Portlet Specification, some are specific to JBoss Portal. + JBoss Portal requires certain descriptors to be included in a portlet WAR file. Some of + these descriptors are defined by the JSR-168 Portlet Specification, and others are specific to JBoss Portal. The following is an example of the directory structure of the HelloWorldPortlet portlet: + </para> + <para> <mediaobject> <imageobject> <imagedata align="center" fileref="images/tutorials/first_portlet/package.gif" valign="middle"/> </imageobject> </mediaobject> - Now let's explain what each of these does: - <itemizedlist> - <listitem> - <para><literal>portlet.xml</literal> -<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + </para> + <para> + The following is an example of the <filename>HelloWorldPortlet/WEB-INF/portlet.xml</filename> file. Note: in order to create the <filename>WEB-INF</filename> and <filename>META-INF</filename> directories, extract the <filename>helloworldportlet.war</filename> file: + </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" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1... @@ -253,57 +285,64 @@ <title>HelloWorld Portlet</title> </portlet-info> </portlet> -</portlet-app>]]></programlisting> - This file must adhere to its definition in the Portlet Specification. You may define more than - one portlet application in this file. - <itemizedlist> - <listitem> - <para> - <programlisting><![CDATA[<portlet-name>HelloWorldPortlet</portlet-name>]]></programlisting> - Define your portlet name. It does not have to be the Class name. - </para> - </listitem> - <listitem> - <para> - <programlisting><![CDATA[<portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class>]]></programlisting> - The Fully Qualified Name (FQN) of your portlet class must be declared here. - </para> - </listitem> - <listitem> - <para> - <programlisting><![CDATA[<supports> - <mime-type>text/html</mime-type> - <portlet-mode>VIEW</portlet-mode> -</supports>]]></programlisting> - The <literal>supports</literal> element allows you to declare all the markup types your - portlet supports in the <literal>render</literal> method. This is accomplish via the - <literal>mime-type</literal> element, which is <emphasis>required</emphasis> for every - portlet. Of course, the declared MIME types must match the capability of the portlet. - - It also allows you to pair - which modes and window states are supported for each markup type. In out case, as all - portlets must support the VIEW portlet mode, we didn't have to declare it. We did need - to declare that our portlet supports the <literal>text/html</literal> markup type. - Hence, we are letting the portal know that it will be outputting text/html and - only support a VIEW mode. - </para> - </listitem> - <listitem> - <para> - <programlisting><![CDATA[<portlet-info> - <title>HelloWorld Portlet</title> -</portlet-info> -]]></programlisting> - The portlet's title will be displayed as the header in the portlet window, when - rendered, unless it is overridden programmatically. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - <listitem> - <para><literal>portlet-instances.xml</literal> -<programlisting><![CDATA[<?xml version="1.0" standalone="yes"?> +</portlet-app>]]> +</screen> + </para> + <para> + This file must adhere to its definition in the JSR-168 Portlet Specification. You may define more than one portlet application in this file. + </para> + <para> + <variablelist> + <varlistentry><term><screen><![CDATA[ +<portlet-name>HelloWorldPortlet</portlet-name>]]></screen></term> +<listitem> + <para> + Define the portlet name. It does not have to be the Class name. + </para> +</listitem> +</varlistentry> +<varlistentry><term><screen><![CDATA[ +<portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class>]]></screen></term> +<listitem> + <para> + The Fully Qualified Name (FQN) of your portlet class must be declared here. + </para> +</listitem> +</varlistentry> +<varlistentry><term><screen><![CDATA[ +<supports> + <mime-type>text/html</mime-type> + <portlet-mode>VIEW</portlet-mode> +</supports>]]></screen></term> +<listitem> + <para> + The <literal>&lt;supports&gt;</literal> element allows you to declare all the markup types your + portlet supports in the <literal>render</literal> method. This is accomplished via the + <literal>&lt;mime-type&gt;</literal> element, which is required for every portlet. The declared MIME types must match the capability of the portlet. + </para> + <para> + 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 decared. Define which markup type your porlet supports, which in this examepl is <literal>text/html</literal>. This section tells the portal that it will only output text and HTML, and that it only supports the VIEW mode. + </para> +</listitem> +</varlistentry> +<varlistentry><term><screen><![CDATA[ +<portlet-info> + <title>HelloWorld Portlet</title> +</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>. + </para> +</listitem> +</varlistentry> +</variablelist> +</para> +<para> + The following is an example of the <filename>HelloWorldPortlet/WEB-INF/portlet-instances.xml</filename> file: +</para> +<para> +<screen><![CDATA[ +<?xml version="1.0" standalone="yes"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD Portlet Instances 2.6//EN" "http://www.jboss.org/portal/dtd/portlet-instances_2_6.dtd"> @@ -314,17 +353,21 @@ <portlet-ref>HelloWorldPortlet</portlet-ref> </instance> </deployment> -</deployments>]]></programlisting> - This is a JBoss Portal specific descriptor that allows you to create instances of portlets. The - <literal>portlet-ref</literal> value must match the <literal>portlet-name</literal> value - given in the packaged <literal>portlet.xml</literal>. The <literal>instance-id</literal> - value can be named anything, but it must match <literal>instance-ref</literal> values given - in <literal>*-object.xml</literal> files as we shall below. - </para> - </listitem> - <listitem> - <para><literal>helloworld-object.xml</literal> -<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +</deployments>]]> +</screen> +</para> +<para> + This is a JBoss Portal specific descriptor that allows you to create instances of portlets. The + <literal>&lt;portlet-ref&gt;</literal> value must match the <literal>&lt;portlet-name&gt;</literal> value + given in the <filename>HelloWorldPortlet/WEB-INF/portlet.xml</filename> file. The <literal>&lt;instance-id&gt;</literal> + value can be named anything, but it must match the <literal>instance-ref</literal> values given + in <literal>*-object.xml</literal> files as we shall below. +</para> +<para> + The following is an example <filename>helloworld-object.xml</filename> file: +</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"> @@ -339,14 +382,18 @@ <height>1</height> </window> </deployment> -</deployments>]]></programlisting> +</deployments>]]> +</screen> +</para> +<para> +<literal>*-object.xml</literal> files are JBoss Portal specific descriptors and allow users to +define the structure of their portal instances as well as create/configure their windows and +pages. In our example, we create a portlet window, specify that it will display the markup +generated by the <literal>HelloWorldPortletInstance</literal> portlet instance, assign it to the +<literal>default.default</literal> page, and specify where it should appear on that page. +</para> +<para> - <literal>*-object.xml</literal> files are JBoss Portal specific descriptors and allow users to - define the structure of their portal instances as well as create/configure their windows and - pages. In our example, we create a portlet window, specify that it will display the markup - generated by the <literal>HelloWorldPortletInstance</literal> portlet instance, assign it to the - <literal>default.default</literal> page, and specify where it should appear on that page. - <itemizedlist> <listitem> <para> @@ -389,9 +436,7 @@ </listitem> </itemizedlist> </para> - </listitem> - </itemizedlist> - </para> + <para> To illustrate the relationship between the descriptors, we have provided this simple diagram <mediaobject> @@ -426,6 +471,8 @@ </window> </deployment> </deployments>]]></programlisting> +</para> +<para> This declaration is equivalent to the previous example. We specify that the content being displayed by the <literal>HelloWorldPortletWindow</literal> is a <literal>portlet</literal> content. The content URI @@ -433,7 +480,7 @@ It is possible to declare windows with a <literal>cms</literal> content type and use directly the path to the file in the CMS to make the window show the content of the associated file. That behavior is pluggable and it is possible to plug virtually any kind of content. - </para> + </para> </sect3> <sect3 id="first_portlet_build"> <title>Building your portlet</title>