[gatein-commits] gatein SVN: r8119 - in portal/trunk/docs/reference-guide/en-US: modules and 1 other directory.

Author: chris.laprun(a)jboss.com Date: 2011-11-22 12:09:45 -0500 (Tue, 22 Nov 2011) New Revision: 8119 Modified: portal/trunk/docs/reference-guide/en-US/images/WSRP/config_create.png portal/trunk/docs/reference-guide/en-US/images/WSRP/config_end.png portal/trunk/docs/reference-guide/en-US/images/WSRP/config_init.png portal/trunk/docs/reference-guide/en-US/images/WSRP/config_missing.png portal/trunk/docs/reference-guide/en-US/images/WSRP/config_refresh.png portal/trunk/docs/reference-guide/en-US/images/WSRP/config_wsdl.png portal/trunk/docs/reference-guide/en-US/modules/WSRP.xml Log: - GTNWSRP-267: changed structure of consumer configuration procedure, changed example to use NetUnity's public producer instead of (now defunct) Oracle's public producer. Modified: portal/trunk/docs/reference-guide/en-US/images/WSRP/config_create.png =================================================================== (Binary files differ) Modified: portal/trunk/docs/reference-guide/en-US/images/WSRP/config_end.png =================================================================== (Binary files differ) Modified: portal/trunk/docs/reference-guide/en-US/images/WSRP/config_init.png =================================================================== (Binary files differ) Modified: portal/trunk/docs/reference-guide/en-US/images/WSRP/config_missing.png =================================================================== (Binary files differ) Modified: portal/trunk/docs/reference-guide/en-US/images/WSRP/config_refresh.png =================================================================== (Binary files differ) Modified: portal/trunk/docs/reference-guide/en-US/images/WSRP/config_wsdl.png =================================================================== (Binary files differ) Modified: portal/trunk/docs/reference-guide/en-US/modules/WSRP.xml =================================================================== --- portal/trunk/docs/reference-guide/en-US/modules/WSRP.xml 2011-11-22 12:21:19 UTC (rev 8118) +++ portal/trunk/docs/reference-guide/en-US/modules/WSRP.xml 2011-11-22 17:09:45 UTC (rev 8119) @@ -91,9 +91,7 @@ directory of your JBoss Application Server configuration directory. </para> <para> - The extension itself is composed of the following components, , assuming - <code>$GATEIN_HOME</code> - is where &PRODUCT_NAME; has been installed, + The extension itself is composed of the following components, assuming <code>$WSRP_VERSION</code> (at the time of the writing, it was &WSRP_VERSION;) is the version of the WSRP component and <code>$PORTAL_VERSION</code> @@ -328,8 +326,9 @@ <title>Overview</title> <para> To be able to consume WSRP portlets exposed by a remote producer, &PRODUCT_NAME;'s WSRP consumer needs to - know how to access that remote producer. One can configure access to a remote producer using WSRP Producer - descriptors. Alternatively, a portlet is provided to configure remote producers. + know how to access that remote producer. One can configure access to a remote producer using the provided + configuration portlet. Alternatively, it is also possible to configure access to remote producers using an + XML descriptor, though it is recommended (and easier) to do so via the configuration portlet. </para> <para> Once a remote producer has been configured, the portlets that it exposes are then available in the @@ -337,13 +336,11 @@ </para> </sect2> - <sect2> - <title>Configuring a remote producer walk-through</title> + <sect2 id="consumer_gui"> + <title>Configuring a remote producer using the configuration portlet</title> <para> - Let's work through the steps of defining access to a remote producer so that its portlets can be - consumed within &PRODUCT_NAME;. We will configure access to Oracle's public WSRP producer. We will first - examine how to do so using the configuration portlet. We will then show how the same result can be - accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. + Let's work through the steps of defining access to a remote producer using the configuration portlet so that its portlets can be + consumed within &PRODUCT_NAME;. We will configure access to NetUnity's public WSRP producer. </para> <note> @@ -360,220 +357,142 @@ </para> </note> - <sect3 id="consumer_gui"> - <title>Using the configuration portlet</title> + <para> + &PRODUCT_NAME; provides a portlet to configure access (among other functions) to remote WSRP Producers + grahically. Starting with &PRODUCT_VERSION;, the WSRP configuration portlet is installed by default. You + can find it at + <ulink + url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&amp;username=root&amp;password=gtn"> + http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... + </ulink> + </para> + + <para> + You should see a screen similar to: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_init.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + This screen presents all the configured Consumers associated with their status and possible actions on + them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a + portlet provider. Note also that a Consumer can be marked as requiring refresh meaning that the + information held about it might not be up to date and refreshing it from the remote Producer might be a + good idea. This can happen for several reasons: the service description for that remote Producer has not + been fetched yet, the cached version has expired or modifications have been made to the configuration + that could potentially invalidate it, thus requiring re-validation of the information. + </para> + + <note> <para> - &PRODUCT_NAME; provides a portlet to configure access (among other functions) to remote WSRP Producers - grahically. Starting with &PRODUCT_VERSION;, the WSRP configuration portlet is installed by default. You - can find it at + The WSRP configuration didn't use to be installed by default in previous versions of &PRODUCT_NAME;. + We include here the legacy instructions on how to install this portlet in case you ever need to + re-install it. + </para> + <para> + Use the usual procedure to log in as a Portal administrator and go to the Application + Registry. With the default install, you can just go to <ulink - url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfiguration&amp;username=root&amp;password=gtn"> - http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... + url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&amp;username=root&amp;password=gtn"> + http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... </ulink> + Add the WSRP Configuration portlet to the Administration category. If you use the Import Applications + functionality, the WSRP Configuration portlet will be automatically added to the Administration + category. </para> - <para> - You should see a screen similar to: - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_init.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - This screen presents all the configured Consumers associated with their status and possible actions on - them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a - portlet provider. Note also that a Consumer can be marked as requiring refresh meaning that the - information held about it might not be up to date and refreshing it from the remote Producer might be a - good idea. This can happen for several reasons: the service description for that remote Producer has not - been fetched yet, the cached version has expired or modifications have been made to the configuration - that could potentially invalidate it, thus requiring re-validation of the information. + Now that the portlet is added to a category, it can be added to a page and used. We recommend adding + it to the same page as the Application Registry as operations relating to WSRP and adding portlets to + categories are somewhat related as we will see. Go ahead and add the WSRP Configuration portlet to the + page using the standard procedure. </para> + </note> + <para> + Next, we create a new Consumer which we will call <literal>netunity</literal>. Type + "<literal>netunity</literal>" in + the "Create a consumer named:" field then click on "Create consumer": + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_create.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + You should now see a form allowing you to enter/modify the information about the Consumer. + Set the cache expiration value to 300 seconds, leave the default timeout value for web services (WS) + operations and enter the WSDL URL for the producer in the text field + and press the "Refresh &amp; Save" button: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_wsdl.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + This will retrieve the service description associated with the Producer which WSRP interface is described + by the WSDL file found at the URL you just entered. In our case, querying the service description will + allow us to learn that the Producer requires registration, requested three registration properties and that + we are missing values for these properties: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_missing.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + This particular producer requests simple + <literal>Yes</literal> + or + <literal>No</literal> + values for the three registration properties. Entering <literal>No</literal>, + <literal>Yes</literal> + and + <literal>No</literal> + (in that order) for the values and then pressing the "Refresh &amp; Save" button should result in: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_end.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + <note> - <para> - The WSRP configuration didn't use to be installed by default in previous versions of &PRODUCT_NAME;. - We include here the legacy instructions on how to install this portlet in case you ever need to - re-install it. + <para>At this point, there is no automated way to learn about which possible values (if any) are + expected by the remote Producer. Sometimes, the possible values will be indicated in the + registration + property description but this is not always the case... Please refer to the specific Producer's + documentation. </para> - <para> - Use the usual procedure to log in as a Portal administrator and go to the Application - Registry. With the default install, you can just go to - <ulink - url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&amp;username=root&amp;password=gtn"> - http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclass... - </ulink> - Add the WSRP Configuration portlet to the Administration category. If you use the Import Applications - functionality, the WSRP Configuration portlet will be automatically added to the Administration - category. - </para> - <para> - Now that the portlet is added to a category, it can be added to a page and used. We recommend adding - it to the same page as the Application Registry as operations relating to WSRP and adding portlets to - categories are somewhat related as we will see. Go ahead and add the WSRP Configuration portlet to the - page using the standard procedure. - </para> </note> + </para> - <para> - Next, we create a new Consumer which we will call<literal>oracle</literal>. Type - "<literal>oracle</literal>" in - the "Create a consumer named:" field then click on "Create consumer": - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_create.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - You should now see a form allowing you to enter/modify the information about the Consumer. - Set the cache expiration value to 300 seconds, leave the default timeout value for web services (WS) - operations and enter the WSDL URL for the producer in the text field - and press the "Refresh &amp; Save" button: - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_wsdl.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - This will retrieve the service description associated with the Producer which WSRP interface is described - by the WSDL file found at the URL you just entered. In our case, querying the service description will - allow us to learn that the Producer requires registration but didn't request any registration property: - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_refresh.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - The Consumer for the - <literal>oracle</literal> - Producer should now be available as a portlet provider and be ready to be used. - </para> - <para> - Now, assuming that the producer required a value for an - <literal>email</literal> - registration property, &PRODUCT_NAME;'s WSRP consumer would have informed you that you were missing some - information: - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_missing.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - <note> - <para>At this point, there is no automated way to learn about which possible values (if any) are - expected by the remote Producer. Sometimes, the possible values will be indicated in the - registration - property description but this is not always the case... Please refer to the specific Producer's - documentation. - </para> - - </note> - If you entered &quot;&lt;literal&gt;example(a)example.com&lt;/literal&gt;&quot; as the value for the registration property and - press "Save &amp; - Refresh" once more, you would have seen something similar to: - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/config_end.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - </para> - </sect3> - - <sect3> - <title>Using XML</title> - - <para>While we recommend you use the WSRP Configuration portlet to configure Consumers, we provide an - alternative way to configure consumers by editing the XML file located at - - !!! TODO claprun: finish updating from here. - - <filename>extension-component-$PORTAL_VERSION.jar/conf/wsrp-consumers-config.xml</filename> - in your - JBoss AS deploy directory. - </para> - <programlisting role="XML"><![CDATA[ -<?xml version='1.0' encoding='UTF-8' ?> -<deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_wsrp_consume... http://www.jboss.org/portal/xsd/gatein_wsrp_consumer_1_0.xsd"> - <deployment> - <wsrp-producer id="self" expiration-cache="300" ws-timeout="30000"> - <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v2/MarkupService?wsdl</endpoint-wsdl-url> - <registration-data> - <property> - <name>email</name> - <lang>en</lang> - <value&gt;example(a)example.com&lt;/value&gt; - </property> - </registration-data> - </wsrp-producer> - </deployment> - <deployment> - <wsrp-producer id="oracle" expiration-cache="300"> - <endpoint-wsdl-url>http://portalstandards.oracle.com/portletapp/portlet... - <registration-data/> - </wsrp-producer> - </deployment> -</deployments>]]></programlisting> - <para> - The file as shown above specifies access to two producers: - <literal>self</literal>, which consumes &PRODUCT_NAME;'s own WSRP producer albeit in a version that - assumes that the producer requires a value for an - <literal>email</literal> - registration property, and - <literal>oracle</literal>, which consumes Oracle's public producer, both in configurations as shown in - the walk-through above. - </para> - <para>We will look at the details of the meaning of elements later on.</para> - </sect3> - - <sect3> - <title>Adding remote portlets to categories</title> - <para> - If we go back to the Application Registry and examine the available portlets by clicking on the - Portlet link, you will now be able to see the remote portlets if you click on the REMOTE tab in the left - column: - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/remote_portlets.png" format="PNG" align="center" valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - </para> - - <para> - These portlets are, of course, available to be used such as regular portlets: they can be used in - categories and added to pages. If you use the Import Applications functionality, they will also be - automatically imported in categories based on the keywords they define. - </para> - - <para> - More specifically, if you want to add a WSRP portlet to a category, you can access these portlets by - selecting - <literal>wsrp</literal> - in the Application Type drop-down menu: - <mediaobject> - <imageobject> - <imagedata fileref="images/WSRP/remote_portlets_category.png" format="PNG" align="center" - valign="middle" - scalefit="1"/> - </imageobject> - </mediaobject> - </para> - </sect3> + <para> + If we had been dealing with a producer which required registration but didn't require any registration + properties, as is the case for the + <literal>selfv2</literal> + consumer (the consumer that accesses the portlets made remotely available by &PRODUCT_NAME;'s producer via + WSRP 2), we'd have seen something similar to, after pressing the "Refresh &amp; Save" button: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/config_refresh.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + </para> </sect2> - <sect2> + <sect2 id="consumer_xml"> <title>Configuring access to remote producers via XML</title> <para>While we recommend you use the WSRP Configuration portlet to configure Consumers, we provide an - alternative way to configure consumers by editing the XML file located at - <filename>$GATEIN_HOME/lib/wsrp-consumer-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename>. + alternative way to configure consumers by adding an XML file called + <filename>wsrp-consumers-config.xml</filename> in the + <filename>$JBOSS_PROFILE_HOME/conf/gatein/</filename> directory + where <code>$JBOSS_PROFILE_HOME</code> refers to your JBoss AS profile directory (<code>default</code>, for instance). <note> <para>An XML Schema defining which elements are available to configure Consumers via XML can be found in <filename> - $GATEIN_HOME/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd + gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd </filename> </para> </note> @@ -685,24 +604,30 @@ your consumer. </para> </sect3> - </sect2> - <sect2> - <title>Examples</title> + <sect3> + <title>Examples</title> - <para> - Here is the configuration of the - <literal>selfv1</literal> - and - <literal>selfv2</literal> - consumers as found in - <filename>$GATEIN_HOME/lib/wsrp-consumer-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename> - with a cache expiring every 500 seconds and with a 50 second timeout for web service operations. - </para> - - <example> <para> - <programlisting><![CDATA[ + Here is the configuration of the + <literal>selfv1</literal> + and + <literal>selfv2</literal> + consumers as found in + <filename>gatein-wsrp-integration.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-consumers-config.xml</filename> + with a cache expiring every 500 seconds and with a 50 second timeout for web service operations. + <note> + <para> + This file contains the default configuration and you shouldn't need to edit it. If you want to make + modifications to it, we recommend that you follow the procedure detailed in + <xref linkend="consumer_gui"/>. + </para> + </note> + </para> + + <example> + <para> + <programlisting><![CDATA[ <?xml version='1.0' encoding='UTF-8' ?> <deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -720,17 +645,17 @@ </wsrp-producer> </deployment> </deployments>]]> - </programlisting> - </para> + </programlisting> + </para> - </example> + </example> - <para>Here is an example of a WSRP descriptor with registration data and cache expiring every minute: - </para> + <para>Here is an example of a WSRP descriptor with registration data and cache expiring every minute: + </para> - <example> - <para> - <programlisting><![CDATA[ + <example> + <para> + <programlisting><![CDATA[ <?xml version='1.0' encoding='UTF-8' ?> <deployments xmlns="http://www.gatein.org/xml/ns/gatein_wsrp_consumer_1_0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -749,9 +674,45 @@ </wsrp-producer> </deployment> </deployments>]]></programlisting> - </para> - </example> + </para> + </example> + </sect3> </sect2> + + <sect2> + <title>Adding remote portlets to categories</title> + <para> + If we go to the Application Registry and examine the available portlets by clicking on the + Portlet link, you will now be able to see remote portlets if you click on the REMOTE tab in the left + column: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/remote_portlets.png" format="PNG" align="center" valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + </para> + + <para> + These portlets are, of course, available to be used such as regular portlets: they can be used in + categories and added to pages. If you use the Import Applications functionality, they will also be + automatically imported in categories based on the keywords they define. + </para> + + <para> + More specifically, if you want to add a WSRP portlet to a category, you can access these portlets by + selecting + <literal>wsrp</literal> + in the Application Type drop-down menu: + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/remote_portlets_category.png" format="PNG" align="center" + valign="middle" + scalefit="1"/> + </imageobject> + </mediaobject> + </para> + </sect2> </sect1> <sect1> @@ -763,6 +724,8 @@ <sect3> <title>Registration modification for service upgrade</title> <para> + !!! TODO claprun continue update from here !!! + Producers often offer several levels of service depending on consumers' subscription levels (for example). This is implemented at the WSRP level with the registration concept: producers can assert which level of service to provide to consumers based on the values of given registration properties. @@ -823,7 +786,7 @@ <title>Registration modification on producer error</title> <para> - It can also happen that a producer administrator decided to change its requirement forregistered + It can also happen that a producer administrator decided to change its requirement for registered consumers. In this case, invoking operations on the producer will fail with an <exceptionname>OperationFailedFault</exceptionname>. &PRODUCT_NAME; will attempt to help you in this situation. Let's walk through an example using the