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><context-root></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="SmtpUser">username(a)gmail.com</attribute>
- <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="SmtpUser">username(a)gmail.com</attribute>
+<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>username(a)gmail.com</computeroutput> 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&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&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><body></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><supports></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><mime-type></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><portlet-ref></literal> value must match the
<literal><portlet-name></literal> value
+ given in the <filename>HelloWorldPortlet/WEB-INF/portlet.xml</filename>
file. The <literal><instance-id></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>