[gatein-commits] gatein SVN: r5364 - in epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US: images/WSRP and 1 other directories.

Author: smumford Date: 2010-11-29 22:11:48 -0500 (Mon, 29 Nov 2010) New Revision: 5364 Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default255.xml epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default257.xml epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default258.xml epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default259.xml epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_end.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_init.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_missing.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_refresh.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_self.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_wsdl.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/consumer_operations.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/modify_reg_end.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/modify_reg_self.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/modify_reg_self_end.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/producer_blank.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/producer_default.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/producer_email.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/producer_registration.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/remote_portlets.png epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/modules/WSRP.xml Log: JBEPP-517: Updated WSRP section to align more with community doc Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default255.xml =================================================================== --- epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default255.xml 2010-11-30 01:51:11 UTC (rev 5363) +++ epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default255.xml 2010-11-30 03:11:48 UTC (rev 5364) @@ -14,4 +14,4 @@ <value>true</value> </container-runtime-option> </portlet> -</portlet-app> +</portlet-app> \ No newline at end of file Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default257.xml =================================================================== --- epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default257.xml 2010-11-30 01:51:11 UTC (rev 5363) +++ epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default257.xml 2010-11-30 03:11:48 UTC (rev 5364) @@ -4,7 +4,7 @@ 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/MarkupService?wsdl</endpoint-wsdl-url> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v2/MarkupService?wsdl</endpoint-wsdl-url> <registration-data> <property> <name>email</name> @@ -20,4 +20,4 @@ <registration-data/> </wsrp-producer> </deployment> -</deployments> +</deployments> \ No newline at end of file Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default258.xml =================================================================== --- epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default258.xml 2010-11-30 01:51:11 UTC (rev 5363) +++ epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default258.xml 2010-11-30 03:11:48 UTC (rev 5364) @@ -3,9 +3,15 @@ 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/MarkupService?wsdl</endpoint-wsdl-url> + <wsrp-producer id="selfv1" expiration-cache="500" ws-timeout="50000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v1/MarkupService?wsdl</endpoint-wsdl-url> <registration-data/> </wsrp-producer> </deployment> -</deployments> + <deployment> + <wsrp-producer id="selfv2" expiration-cache="500" ws-timeout="50000"> + <endpoint-wsdl-url>http://localhost:8080/wsrp-producer/v2/MarkupService?wsdl</endpoint-wsdl-url> + <registration-data/> + </wsrp-producer> + </deployment> +</deployments> \ No newline at end of file Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default259.xml =================================================================== --- epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default259.xml 2010-11-30 01:51:11 UTC (rev 5363) +++ epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/extras/WSRP/default259.xml 2010-11-30 03:11:48 UTC (rev 5364) @@ -15,4 +15,4 @@ </registration-data> </wsrp-producer> </deployment> -</deployments> +</deployments> \ No newline at end of file Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_end.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_init.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_missing.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_refresh.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_self.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/config_wsdl.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/consumer_operations.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/modify_reg_end.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/modify_reg_self.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/modify_reg_self_end.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/producer_blank.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/producer_default.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/producer_email.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/producer_registration.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/images/WSRP/remote_portlets.png =================================================================== (Binary files differ) Modified: epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/modules/WSRP.xml 2010-11-30 01:51:11 UTC (rev 5363) +++ epp/docs/branches/EPP_5_1_Branch/Reference_Guide/en-US/modules/WSRP.xml 2010-11-30 03:11:48 UTC (rev 5364) @@ -331,8 +331,13 @@ <important> <title>Chunked Encoding</title> <para> - Some WSRP producers, such as Oracle, do not support chunked encoding. Using an Oracle WSRP producer will therefore produce an error. + Some WSRP producers, such as Oracle, do not support chunked encoding. If your producer does not support chunked encoding, it will not be able to properly connect to the producer. </para> + <para> + This will manifest itself with the following error: + </para> +<screen>Caused by: org.jboss.ws.WSException: Invalid HTTP server response [503] - Service Unavailable. +</screen> <para> A workaround for this issue involves editing the <parameter>chunksize</parameter> setting in the <filename>standard-jaxws-client-config.xml</filename> file. </para> @@ -464,7 +469,7 @@ This will retrieve the service description associated with the Producer which WSRP interface is described by the WSDL file found at the URL entered. </para> <para> - In this case, querying the service description will suggest that the Producer requires registration but did not request any registration property: + In this case, querying the service description will show that the Producer requires registration but did not request any registration property: </para> <mediaobject> <imageobject role="html"> @@ -528,9 +533,9 @@ </para> </note> </section> - - <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-Configuring_Access_to_a_Remote_Portlet"> - <title>Configuring Access to a Remote Portlet</title> +<!--MARK--> + <section id="sect-Reference_Guide-Configuring_a_Remote_Producer-Adding_remote_portlets_to_categories"> + <title>Adding remote portlets to categories</title> <para> Clicking on the Portlet link in the Application Registry will now show the remote potlets in the <emphasis role="bold">REMOTE</emphasis> tab in the left column: </para> @@ -631,14 +636,19 @@ <para> Since, in most instances, the information provided by the producer does not change often, use of this caching facility to minimize bandwidth usage is recommended. </para> - <para> - It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, as it waits on a service that does not answer. - </para> - <para> - Use the <literal>ws-timeout</literal> attribute of the <literal>&#60;wsrp-producer&#62;</literal> element to specify how many milliseconds the WSRP service will wait for a response from the remote producer before timing out. - </para> </listitem> </varlistentry> + <varlistentry> + <term>WS Timeout</term> + <listitem> + <para> + It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, as it waits on a service that does not answer. + </para> + <para> + Use the <literal>ws-timeout</literal> attribute of the <literal>&#60;wsrp-producer&#62;</literal> element to specify how many milliseconds the WSRP service will wait for a response from the remote producer before timing out. + </para> + </listitem> + </varlistentry> <varlistentry> <term>Pre-registration information</term> <listitem> @@ -647,7 +657,7 @@ </para> <note> <para> - As at this release only simple String properties are supported and it is not possible to configure complex registration data. However, this should be sufficient for most cases. + Only simple String properties are supported. It is not possible to configure complex registration data. However, this should be sufficient for most cases. </para> </note> <para> @@ -740,7 +750,7 @@ </step> <step> <para> - Click on this new button and, if the updated registration details have been been accepted by the remote producer the following should appear: + Click on <emphasis role="bold">Modify registration</emphasis> and, if the updated registration details have been been accepted by the remote producer the following should appear: </para> <mediaobject> <imageobject role="html"> @@ -758,7 +768,7 @@ <section id="sect-Reference_Guide-Modifying_a_Currently_Held_Registration-Registration_Modification_on_Producer_Error"> <title>Registration Modification on Producer Error</title> <para> - Invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname> if the producer administrator has changed its requirement for registered consumers. &PRODUCT; will attempt to assist in these cases. + If a Producer administrator changes the requirements for registered consumers, invoking operations on the producer may fail with an <exceptionname>OperationFailedFault</exceptionname>. &PRODUCT; will attempt to assist in these cases. </para> <para> This section will discuss an example using the <literal>self</literal> producer. @@ -952,7 +962,7 @@ The portlets can be re-imported directly by pressing the "<guilabel>Use for import</guilabel>" button or, on the Consumers list page, using the "<guilabel>Import</guilabel>" action for a given consumer. </para> <para> - The example below assumes that the second option has been used and that several sets of previously exported portlets are available to import from. After clicking the action link, a screen similar to the one below shoould appear: + The example below assumes that the second option has been used and that several sets of previously exported portlets are available to import from. After clicking the action link, a screen similar to the one below should appear: </para> <mediaobject> <imageobject role="html"> @@ -1025,7 +1035,7 @@ </imageobject> </mediaobject> <para> - In this example, we want to replace the content of the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> with the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet that we previously exported. + In this example, we want to replace the content of the <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> with the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> portlet that was previously exported. </para> <procedure> <title></title> @@ -1036,7 +1046,7 @@ </step> <step> <para> - Select <literal>page1</literal> in the list of available pages. The screen will then refresh to display the list of available windows on that page, similar to the one seen below: + Select <literal>page1</literal> in the list of available pages. The screen will then refresh to display the list of available windows on that page, similar to the image below: </para> <mediaobject> <imageobject role="html"> @@ -1049,7 +1059,7 @@ <note> <title></title> <para> - At this point, you still need to select the window which content we want to replace before being able to complete the import operation + At this point, you still need to select which window content we want to replace before being able to complete the import operation </para> </note> </step> @@ -1075,20 +1085,8 @@ </step> <step> <para> - The <literal>page1</literal> page should now show: + The <literal>page1</literal> page should now show that the content of <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window has been replaced by the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> imported portlet and that the window has been renamed appropriately. </para> - <itemizedlist> - <listitem> - <para> - That the content of <literal>/samples-remotecontroller-portlet.RemoteControl (remote)</literal> window has been replaced by the content of the <literal>/ajaxPortlet.JSFAJAXPortlet</literal> imported portlet. - </para> - </listitem> - <listitem> - <para> - The window has been renamed appropriately: - </para> - </listitem> - </itemizedlist> <mediaobject> <imageobject role="html"> <imagedata fileref="images/WSRP/import_modified_page.png" format="PNG" align="center" scale="95" /> @@ -1111,7 +1109,7 @@ This can occur when a consumer is registered with a producer that has been modified by its administrator to not require registration any longer. </para> <para> - In this unlikely scenario, local registration information can be erased from the consumer to allow it to resume interacting with the remote producer. + In this scenario, local registration information can be erased from the consumer to allow it to resume interacting with the remote producer. </para> <para> To do this click on the "<emphasis role="bold">Erase local registration</emphasis>" button next to the registration context information on the consumer configuration screen: @@ -1153,7 +1151,6 @@ Several aspects can be modified with respect to whether registration is required for consumers to access the Producer's services. An XML Schema for the configuration format is available at <filename> <replaceable>PORTAL_HOME</replaceable>/lib/wsrp-integration-api-<replaceable>WSRP_VERSION</replaceable>.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename>. </para> </section> - <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-Default_Configuration"> <title>Default Configuration</title> @@ -1184,11 +1181,8 @@ </imageobject> </mediaobject> <para> - Administrators can specify whether or not a producer which requires registration will send the full service description to unregistered consumers. + You can specify whether or not the producer will send the full service description to unregistered consumers, and, if it requires registration, which <literal>RegistrationPolicy</literal> to use (and, if needed, which <literal>RegistrationPropertyValidator</literal>), along with required registration property description for which consumers must provide acceptable values to successfully register. </para> - <para> - The full service description includes which <classname>RegistrationPolicy</classname> (and <classname>RegistrationPropertyValidator</classname> if needed) to use, as well as required registration property descriptions for which consumers must provide acceptable values to successfully register. - </para> <para> WSDL URLs to access &PRODUCT;'s WSRP producer are now displayed in either in WSRP 1 or WSRP 2 mode.</para> </section> @@ -1262,7 +1256,7 @@ <note> <para> - At this time, only String (xsd:string) properties are supported. + At this time, only String (<literal>xsd:string</literal>) properties are supported. </para> </note> <note> @@ -1285,14 +1279,23 @@ This is done by plugging a <classname>RegistrationPropertyValidator</classname> into the default registration policy. This allows users to define their own validation mechanism. </para> <para> - Refer to the <trademark class="trade">Javadoc</trademark> for <classname>org.jboss.portal.registration.RegistrationPolicy</classname> and <classname>org.jboss.portal.Registration.policies.RegistrationPropertyValidator</classname> for more details on what is expected of each method. + Refer to the <trademark class="trade">Javadoc</trademark> for <classname>org.gatein.registration.RegistrationPolicy</classname> and <classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname> for more details on what is expected of each method. </para> <para> - A defined registration policy is required for the producer to be correctly configured. Do this by specifying the qualified class name of the registration policy. As it is anticipated that most users will use the default registration policy, it is possible to provide the class name of a custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. + A defined registration policy is required for the producer to be correctly configured. Do this by specifying the qualified class name of the registration policy. + </para> + <para> + As it is anticipated that most users will use the default registration policy, it is possible to provide the class name of a custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. </para> <note> <para> - Since the policy or the validator are defined via their class name and dynamically loaded, it is important to ensure that the identified class is available to the application server. One way to accomplish that is to deploy the policy implementation as a JAR file in the AS instance deploy directory. Note also that, since both policies and validators are dynamically instantiated, they must provide a default, no-argument constructor. + Since the policy or the validator are defined via their class name and dynamically loaded, it is important to ensure that the identified class is available to the application server. + </para> + <para> + One way to accomplish that is to deploy the policy implementation as a JAR file in the AS instance deploy directory. + </para> + <para> + Note also that, since both policies and validators are dynamically instantiated, they must provide a default, no-argument constructor. </para> </note> </section> @@ -1303,10 +1306,16 @@ <section id="sect-Reference_Guide-Configuring_the_WSRP_Producer-WSRP_Validation_Mode"> <title>WSRP Validation Mode</title> <para> - The lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. Experience from these issues has produced a way to relax the validation that the WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. Note that the our validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. + The lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. + </para> + <para> + Experience of these issues has produced a way to relax the validation that the WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. + </para> + <para> + Note that the our validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. </para> <para> - By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you might want to try to relax the validation mode. This is accomplished by unchecking the "Use strict WSRP compliance" checkbox on the Producer configuration screen. + By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you may attempt to relax the validation mode. Unchecking the "Use strict WSRP compliance" checkbox on the Producer configuration screen to do this. </para> </section>