[gatein-commits] gatein SVN: r8119 - in portal/trunk/docs/reference-guide/en-US: modules and 1 other directory.
do-not-reply at jboss.org
do-not-reply at jboss.org
Tue Nov 22 12:09:45 EST 2011
Author: chris.laprun at 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&username=root&password=gtn">
+ http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfigurationp&username=root&password=gtn
+ </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&username=root&password=gtn">
- http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2FwsrpConfigurationp&username=root&password=gtn
+ url="http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=root&password=gtn">
+ http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=root&password=gtn
</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 & 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 & 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&username=root&password=gtn">
- http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=root&password=gtn
- </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 & 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 "<literal>example at example.com</literal>" as the value for the registration property and
- press "Save &
- 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_consumer_1_0 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>example at example.com</value>
- </property>
- </registration-data>
- </wsrp-producer>
- </deployment>
- <deployment>
- <wsrp-producer id="oracle" expiration-cache="300">
- <endpoint-wsdl-url>http://portalstandards.oracle.com/portletapp/portlets?WSDL</endpoint-wsdl-url>
- <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 & 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
More information about the gatein-commits
mailing list