Author: thomas.heute(a)jboss.com Date: 2010-03-22 13:00:57 -0400 (Mon, 22 Mar 2010) New Revision: 2343 Added: portal/trunk/docs/reference-guide/en/images/foundations/ portal/trunk/docs/reference-guide/en/images/foundations/PortalContainers.png Modified: portal/trunk/docs/reference-guide/en/modules/Development.xml portal/trunk/docs/reference-guide/en/modules/Foundations.xml portal/trunk/docs/reference-guide/en/modules/WSRP.xml portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml Log: - Fixed typos - Added image to Foundations Added: portal/trunk/docs/reference-guide/en/images/foundations/PortalContainers.png =================================================================== (Binary files differ) Property changes on: portal/trunk/docs/reference-guide/en/images/foundations/PortalContainers.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: portal/trunk/docs/reference-guide/en/modules/Development.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/Development.xml 2010-03-22 16:25:30 UTC (rev 2342) +++ portal/trunk/docs/reference-guide/en/modules/Development.xml 2010-03-22 17:00:57 UTC (rev 2343) @@ -9,7 +9,9 @@ <xi:include href="development/Right_To_Left_Framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="development/Internationalization_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="development/XML_Resource_Bundles.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- <xi:include href="development/Dynamic_Layouts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + --> <xi:include href="development/JavaScript_Inter_Application_Communication.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="development/Upload_Component.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="development/Ajax_Loading_Mask_Layer_Deactivation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> Modified: portal/trunk/docs/reference-guide/en/modules/Foundations.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/Foundations.xml 2010-03-22 16:25:30 UTC (rev 2342) +++ portal/trunk/docs/reference-guide/en/modules/Foundations.xml 2010-03-22 17:00:57 UTC (rev 2343) @@ -3,27 +3,31 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "../Reference_Guide.ent"> %BOOK_ENTITIES; ]> -<chapter id="chap-Reference_Guide-Foundations" xmlns:x="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"... +<chapter id="chap-Reference_Guide-Foundations"> <title>Foundations</title> <section id="sect-Reference_Guide-Foundations-Kernel"> <title>GateIn Kernel</title> <para> &PRODUCT; is built on top of a kernel, and a set of services that exist in two scopes. - First scope is represented by <emphasis role="bold">RootContainer</emphasis> - it contains services that exist independently of any portal, and can be accessed by all portals. + First scope is represented by <emphasis role="bold">RootContainer</emphasis> - it contains services that exist independently of any portal container, and can be accessed by all portals. </para> <para> - Second scope is portal-private in the form of <emphasis role="bold">PortalContainer</emphasis>. For each configured portal, an instance of PortalContainer is created. - This scope contains services that have portal specific configuration, and services which should not be shared by - multiple portals. + Second scope is portal-private in the form of <emphasis role="bold">PortalContainer</emphasis>. Each portal live in an instance of PortalContainer. + This scope contains services that are common for a set of portals, and services which should not be shared by all portals. </para> - <para> - RootContainer and PortalContainer classes are part of the same class hierarchy - they both inherit from <emphasis role="bold">ExoContainer</emphasis>, - and they also inherit methods for looking up registered services. + <mediaobject> + <imageobject role="html"> + <imagedata fileref="images/foundations/PortalContainers.png" format="PNG" align="center" scale="100" /> + </imageobject> + <imageobject role="fo"> + <imagedata fileref="images/foundations/PortalContainers.png" format="PNG" align="center" contentwidth="150mm" /> + </imageobject> + </mediaobject> </para> <para> - Whenever a specific service is looked up through PortalContainer, and service is not available, the lookup is + Whenever a specific service is looked up through PortalContainer, and the service is not available, the lookup is delegated further up to RootContainer. We can therefore have default instance of a certain component in RootContainer, and portal specific instances in some or all PortalContainers, that override the default instance. @@ -47,7 +51,7 @@ Additionally, <emphasis role="bold">portal extensions</emphasis> can contain configuration in <emphasis role="bold">WEB-INF/conf/configuration.xml</emphasis>, and will also have their services configured at PortalContainer scope. </para> <note> - Portal extensions are described later on. + <para>Portal extensions are described later on.</para> </note> </section> @@ -63,8 +67,8 @@ If key can be loaded as a class, a Class object is used as a key, otherwise a String is used.</para> <para>The usual approach is to specify an interface as a key.</para> - <note>Example of service component configuration:</note> - + <example> + <title>Example of service component configuration:</title> <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="ISO-8859-1"?> <configuration @@ -81,6 +85,7 @@ </component> </configuration> ]]></programlisting> + </example> </section> <section id="sect-Reference_Guide-Foundations-Configuration_syntax-External_plugins"> <title>External Plugins</title> @@ -92,7 +97,8 @@ to use for injection (<emphasis role="bold">&lt;set-method&gt;</emphasis>). </para> <para>A plugin implementation class has to implement <emphasis role="bold">org.exoplatform.container.component. ComponentPlugin</emphasis> interface.</para> <para>In the following example <emphasis role="bold">PortalContainerDefinitionPlugin</emphasis> implements ComponentPlugin:</para> - + <example> + <title>PortalContainerDefinitionPlugin</title> <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <configuration @@ -120,6 +126,7 @@ </external-component-plugins> </configuration> ]]></programlisting> + </example> </section> <section id="sect-Reference_Guide-Foundations-Configuration_syntax-Includes"> @@ -141,7 +148,9 @@ <para>We see a special URL being used to reference another configuration file. URL schema <emphasis role="bold">'war:'</emphasis> means, that the path that follows is resolved relative to current PortalContainer's servlet context resource path, starting at <emphasis role="bold">WEB-INF</emphasis> as a root.</para> - <note>Current PortalContainer is really a newly created PortalContainer, as war: URLs only make sense for PortalContainer scoped configuration.</note> + <note> + <para>Current PortalContainer is really a newly created PortalContainer, as war: URLs only make sense for PortalContainer scoped configuration.</para> + </note> <para>Also, thanks to extension mechanism, the servlet context used for resource loading is a <emphasis role="bold">unified servlet context</emphasis> (as explaned in a later section).</para> <para>To have include path resolved relative to current classpath (context classloader), use <emphasis role="bold">'jar:'</emphasis> URL schema.</para> </section> @@ -153,6 +162,8 @@ (i.e. JNDI names, Database / DataSource names, JCR repository names, etc ...).</para> <para>This variable is only defined when there is a current PortalContainer available - only for PortalContainer scoped services.</para> <para>A good example for this is <emphasis role="bold">HibernateService</emphasis>:</para> + <example> + <title>HibernateService using variables</title> <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="ISO-8859-1"?> <configuration @@ -187,19 +198,20 @@ </component> </configuration> ]]></programlisting> + </example> </section> </section> <section id="sect-Reference_Guide-Foundations-Configuring_portal"> - <title>Configuring a portal</title> + <title>Configuring a portal container</title> <para> - A <emphasis role="bold">portal</emphasis> is defined by several attributes. + A <emphasis role="bold">portal container</emphasis> is defined by several attributes. </para> <para> - First, there is a <emphasis role="bold">portal name</emphasis>, which is always equal to URL context to which the current portal is bound. + First, there is a <emphasis role="bold">portal container name</emphasis>, which is always equal to URL context to which the current portal is bound. </para> <para> @@ -217,6 +229,8 @@ portal (via extension mechanism described later), and are searched in the specified order. </para> + <example> + <title>Portal container declaration example</title> <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <configuration @@ -298,14 +312,15 @@ </configuration> ]]> </programlisting> + </example> <note> - Dependencies are part of the extension mechanism. + <para>Dependencies are part of the extension mechanism.</para> </note> <para> - Every <emphasis role="bold">portal</emphasis> is represented by <emphasis role="bold">PortalContainer instance</emphasis>, which contains: + Every <emphasis role="bold">portal container</emphasis> is represented by a <emphasis role="bold">PortalContainer instance</emphasis>, which contains: <itemizedlist> <listitem> <para>associated <emphasis role="bold">ExoContainerContext</emphasis>, which contains information about the portal</para> @@ -351,7 +366,7 @@ <para> First, declare <emphasis role="bold">PortalConfigOwner</emphasis> servlet context listener in web.xml of your web application. </para> - <para>An example of a portal extension called sample-ext:</para> + <example><title>Example of a portal extension called sample-ext:</title> <programlisting role="XML"><![CDATA[ <?xml version="1.0" encoding="ISO-8859-1" ?> @@ -369,6 +384,7 @@ </web-app> ]]></programlisting> + </example> <para> Then, add the servlet context name of this web application in proper place in the list of Dependencies of the PortalContainerDefinition of all the portal containers that you want to have access to its resources. @@ -379,7 +395,7 @@ </para> <note> - See 'Configuring a portal' section for example of PortalContainerDefinition, that has sample-ext at the end of its list of Dependencies. + <para>See 'Configuring a portal' section for example of PortalContainerDefinition, that has sample-ext at the end of its list of Dependencies.</para> </note> </section> @@ -436,13 +452,15 @@ HttpServletResponse res) throws ServletException, IOException; ]]></programlisting> <note> + <para> The reason is that AbstractHttpServlet implements service() to perform its interception, and you don't want to overwrite (by overriding) this functionality. + </para> </note> <para> You may also need to access portal information within your <emphasis role="bold">HttpSessionListener</emphasis>. Again, make sure to extend the provided abstract class - <emphasis role="bold">org.exoplatform.container.web. AbstractHttpSessionListener</emphasis>. - Also, modify your method signitures as follows:</para> + Also, modify your method signatures as follows:</para> <programlisting role="JAVA"><![CDATA[ /** * Use this method instead of HttpSessionListener.sessionCreated() Modified: portal/trunk/docs/reference-guide/en/modules/WSRP.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/WSRP.xml 2010-03-22 16:25:30 UTC (rev 2342) +++ portal/trunk/docs/reference-guide/en/modules/WSRP.xml 2010-03-22 17:00:57 UTC (rev 2343) @@ -16,11 +16,11 @@ <para>Scenarios that motivate WSRP functionality include: <itemizedlist> - <listitem>Content hosts, such as portal servers, providing Portlets as presentation-oriented web services - that can be used by aggregation engines. + <listitem><para>Content hosts, such as portal servers, providing Portlets as presentation-oriented web services + that can be used by aggregation engines.</para> </listitem> - <listitem>Aggregating frameworks, including portal servers, consuming presentation-oriented web services - offered by content providers and integrating them into the framework. + <listitem><para>Aggregating frameworks, including portal servers, consuming presentation-oriented web services + offered by content providers and integrating them into the framework.</para> </listitem> </itemizedlist> </para> @@ -136,6 +136,7 @@ element is optional. </para> <example> + <title>BasicPortlet</title> <programlisting><![CDATA[ <?xml version="1.0" standalone="yes"?> <!DOCTYPE portlet-app PUBLIC "-//&PRODUCT;//DTD JBoss Portlet 2.6//EN" @@ -158,6 +159,7 @@ several portlets without having to specify the status for all the declared portlets. Let's look at an example: </para> <example> + <title>All portlets set remotable</title> <programlisting><![CDATA[ <?xml version="1.0" standalone="yes"?> <!DOCTYPE portlet-app PUBLIC @@ -212,16 +214,16 @@ at: <itemizedlist> <listitem> - <filename>http://{hostname}:{port}/portal-wsrp/ServiceDescriptionService</filename> + <para><filename>http://{hostname}:{port}/portal-wsrp/ServiceDescriptionService</filename></para> </listitem> <listitem> - <filename>http://{hostname}:{port}/portal-wsrp/MarkupService</filename> + <para><filename>http://{hostname}:{port}/portal-wsrp/MarkupService</filename></para> </listitem> <listitem> - <filename>http://{hostname}:{port}/portal-wsrp/RegistrationService</filename> + <para><filename>http://{hostname}:{port}/portal-wsrp/RegistrationService</filename></para> </listitem> <listitem> - <filename>http://{hostname}:{port}/portal-wsrp/PortletManagementService</filename> + <para><filename>http://{hostname}:{port}/portal-wsrp/PortletManagementService</filename></para> </listitem> </itemizedlist> The default hostname is @@ -322,10 +324,10 @@ scalefit="1"/> </imageobject> </mediaobject> - <note>At this point, there is no automated way to learn about which possible values (if any) are + <note><para>At this point, there is no automated way to learn about which possible values (if any) are expected by the remote Producer. In the case of BEA's public producer, the possible values are indicated in the registration property description. This is not always the case... Please refer to - the specific Producer's documentation. + the specific Producer's documentation.</para> </note> Enter "<literal>public</literal>" as the value for the registration property and press "Save &amp; Refresh" once more. You should now @@ -390,10 +392,10 @@ (with &PRODUCT; and its WSRP service deployed). </para> <para> - <note>A DTD and an XML Schema for WSRP Producer XML descriptors are available in + <note><para>A DTD and an XML Schema for WSRP Producer XML descriptors are available in <filename>jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd</filename> and - <filename>jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-consumer_2_6.xsd</filename> + <filename>jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-consumer_2_6.xsd</filename></para> </note> </para> </sect3> @@ -458,7 +460,7 @@ <filename>jboss-portal.sar/portal-wsrp.sar/xsd/jboss-wsrp-consumer_2_6.xsd</filename>, while a (legacy) DTD can be found at<filename>jboss-portal.sar/portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd</filename>. - <note>It is important to note how WSRP Producer descriptors are processed. They are read the first time the + <note><para>It is important to note how WSRP Producer descriptors are processed. They are read the first time the WSRP service starts and the associated information is then put in the Portal database. Subsequent launch of the WSRP service will use the database-stored information for all producers which identifier is already known to Portal. More specifically, all the descriptors are scanned for producer identifiers. @@ -470,7 +472,7 @@ <emphasis>AND</emphasis> remove the associated information in any WSRP Producer descriptor (if such information exists) as the producer will be re-created the next time the WSRP is launched if that - information is not removed. + information is not removed.</para> </note> </para> @@ -495,7 +497,7 @@ <para> <itemizedlist> - <listitem>You can provide the URLs for each of the different WSRP interfaces offered by the remote + <listitem><para>You can provide the URLs for each of the different WSRP interfaces offered by the remote producer via the <literal>&lt;endpoint-config&gt;</literal> element and its @@ -507,19 +509,19 @@ children. These URLs are producer-specific so you will need to refer to your producer documentation or WSDL file to determine - the appropriate values. + the appropriate values.</para> </listitem> - <listitem>Alternatively, and this is the easiest way to configure your producer, you can provide a URL + <listitem><para>Alternatively, and this is the easiest way to configure your producer, you can provide a URL pointing to the WSDL description of the producer's WSRP services. This is accomplished via the <literal>&lt;endpoint-wsdl-url&gt;</literal> element. &PRODUCT; will then heuristically determine, from the information contained in the WSDL file, how to connect appropriately - to the remote WSRP services. - <note>It is important to note that, when using this method, &PRODUCT; will try to match a port + to the remote WSRP services.</para> + <note><para>It is important to note that, when using this method, &PRODUCT; will try to match a port name to an interface based solely on the provided name. There are no standard names for these ports so it is possible (though rare) that this matching process fails. In this case, you should - look at the WSDL file and provide the endpoint URLs manually, as per the previous method. + look at the WSDL file and provide the endpoint URLs manually, as per the previous method.</para> </note> </listitem> </itemizedlist> @@ -564,8 +566,9 @@ registration information in the producer configuration so that the Portal consumer can register with the remote producer when required. - <note>At this time, though, only simple String properties are supported and it is not possible to - configure complex registration data. This should however be sufficient for most cases. + <note> + <para>At this time, though, only simple String properties are supported and it is not possible to + configure complex registration data. This should however be sufficient for most cases.</para> </note> </para> @@ -601,6 +604,7 @@ </para> <example> + <title>self producer configuration</title> <programlisting><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//&PRODUCT;//DTD WSRP Remote Producer Configuration 2.6//EN" @@ -633,11 +637,12 @@ </programlisting> </example> - <para>Here is an example of a WSRP descriptor with a 2 minute caching time and manual definition of the + <para>Here is an example of a WSRP descriptor with a 2 minutes caching time and manual definition of the endpoint URLs: </para> <example> + <title>WSRP descriptor with 2 minutes caching time</title> <programlisting><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//&PRODUCT;//DTD WSRP Remote Producer Configuration 2.6//EN" @@ -670,6 +675,7 @@ </para> <example> + <title>WSRP descriptor</title> <programlisting><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//&PRODUCT;//DTD WSRP Remote Producer Configuration 2.6//EN" @@ -821,7 +827,7 @@ </imageobject> </mediaobject> - <note>As of WSRP 1, it is rather difficult to ascertain for sure what caused an + <note><para>As of WSRP 1, it is rather difficult to ascertain for sure what caused an <exceptionname>OperationFailedFault</exceptionname> as it is the generic exception returned by producers if something didn't quite happen as expected during a method invocation. This means that @@ -829,7 +835,7 @@ can be caused by several different reasons, one of them being a request to modify the registration data. Please take a look at the log files to see if you can gather more information as to what happened. WSRP 2 introduces an exception that is - specific to a request to modify registrations thus reducing the ambiguity that currently exists. + specific to a request to modify registrations thus reducing the ambiguity that currently exists.</para> </note> </para> </sect3> @@ -849,20 +855,20 @@ <para> The available operations are: <itemizedlist> - <listitem>Configure: displays the consumer details and allows user to edit them</listitem> + <listitem><para>Configure: displays the consumer details and allows user to edit them</para></listitem> <listitem> - Refresh: forces the consumer to retrieve the service description from the remote producer to refresh - the local information (offered portlets, registration information, etc.) + <para>Refresh: forces the consumer to retrieve the service description from the remote producer to refresh + the local information (offered portlets, registration information, etc.)</para> </listitem> <listitem> - Activate/Deactivate: activates/deactivates a consumer, governing whether it will be available to - provide portlets and receive portlet invocations + <para>Activate/Deactivate: activates/deactivates a consumer, governing whether it will be available to + provide portlets and receive portlet invocations</para> </listitem> <listitem> - Register/Deregister: registers/deregisters a consumer based on whether registration is required - and/or acquired + <para>Register/Deregister: registers/deregisters a consumer based on whether registration is required + and/or acquired</para> </listitem> - <listitem>Delete: destroys the consumer, after deregisterting it if it was registered</listitem> + <listitem><para>Delete: destroys the consumer, after deregisterting it if it was registered</para></listitem> </itemizedlist> </para> </sect2> @@ -992,16 +998,16 @@ Press "Save" to record your modifications. <note> - At this time, only String (xsd:string) properties are supported. If your application requires more - complex properties, please let us know. + <para>At this time, only String (xsd:string) properties are supported. If your application requires more + complex properties, please let us know.</para> </note> <note> - If consumers are already registered with the producer, modifying the configuration of required + <para>If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. We saw the consumer side of that process - in<xref linkend="reg_mod_error"/>. + in<xref linkend="reg_mod_error"/>.</para> </note> </para> @@ -1038,11 +1044,11 @@ name of your custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. - <note>Since the policy or the validator are defined via their class name and dynamically loaded, it is + <note><para>Since the policy or the validator are defined via their class name and dynamically loaded, it is important that you make sure that the identified class is available to the application server. One way to accomplish that is to deploy your policy implementation as JAR file in your AS instance deploy directory. Note also that, since both policies and validators are dynamically instantiated, they must - provide a default, no-argument constructor. + provide a default, no-argument constructor.</para> </note> </para> </sect3> Modified: portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml 2010-03-22 16:25:30 UTC (rev 2342) +++ portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml 2010-03-22 17:00:57 UTC (rev 2343) @@ -143,7 +143,7 @@ </callout> <callout arearefs="area-Reference_Guide-i18n.locales.configuration.orientation"> <para> - <emphasis>description</emphasis> The default orientation of text and images is Left-To-Right. &PRODUCT; supports <emphasis role="bold">Right-To-Left</emphasis> orientation. Modifying text orientation is explained in <xref linkend="sect-Reference_Guide-RTL_Right_To_Left_Framework" />. + <emphasis>orientation</emphasis> The default orientation of text and images is Left-To-Right. &PRODUCT; supports <emphasis role="bold">Right-To-Left</emphasis> orientation. Modifying text orientation is explained in <xref linkend="sect-Reference_Guide-RTL_Right_To_Left_Framework" />. </para> </callout> </calloutlist>