Author: chris.laprun(a)jboss.com Date: 2007-12-06 00:16:19 -0500 (Thu, 06 Dec 2007) New Revision: 9309 Modified: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/modules/wsrp.xml Log: - Removed some leftover content from previous versions. - IDEA messed up the layout: fixed some tags being attached to previous word (need to go through the document again). Modified: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/modules/wsrp.xml =================================================================== --- docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/modules/wsrp.xml 2007-12-06 05:15:49 UTC (rev 9308) +++ docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/modules/wsrp.xml 2007-12-06 05:16:19 UTC (rev 9309) @@ -35,20 +35,15 @@ <para>More information on WSRP can be found on the <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... website for WSRP</ulink>. - We suggest reading the - <ulink - url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... - </ulink> - for a good, albeit technical, overview of WSRP. + We suggest reading the <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp... + </ulink> for a good, albeit technical, overview of WSRP. </para> </sect1> <sect1 id="wsrp_support"> <title>Level of support in JBoss Portal</title> <para>The WSRP Technical Committee defined - <ulink url="http://www.oasis-open.org/committees/download.php/3073">... - Use Profiles - </ulink> + <ulink url="http://www.oasis-open.org/committees/download.php/3073">... Use Profiles</ulink> to help with WSRP interoperability. We will refer to terms defined in that document in this section. </para> @@ -72,8 +67,7 @@ <para>While we provide a complete implementation of WSRP 1.0, we do need to go through the <ulink url="http://www.oasis-open.org/committees/download.php/6018">... statements</ulink> - and - perform more interoperability testing (an area that needs to be better supported by the WSRP Technical + and perform more interoperability testing (an area that needs to be better supported by the WSRP Technical Committee and Community at large). </para> </sect1> @@ -81,19 +75,11 @@ <sect1> <title>Deploying JBoss Portal's WSRP services</title> <para> - JBoss Portal provides a complete support of WSRP 1.0 standard interfaces and offers - both consumer and producer services. WSRP support is provided by the - <filename>portal-wsrp.sar</filename> - service archive, included in the main - <filename>jboss-portal.sar</filename> - service archive, if you've - obtained JBoss Portal from a binary distribution. If you don't intend on using WSRP, we recommend that you - remove - <filename>portal-wspr.sar</filename> - from the main - <filename>jboss-portal.sar</filename> - service - archive. + JBoss Portal provides a complete support of WSRP 1.0 standard interfaces and offers both consumer and producer + services. WSRP support is provided by the <filename>portal-wsrp.sar</filename> service archive, included in + the main <filename>jboss-portal.sar</filename> service archive, if you've obtained JBoss Portal from a binary + distribution. If you don't intend on using WSRP, we recommend that you remove <filename>portal-wspr.sar</filename> + from the main <filename>jboss-portal.sar</filename> service archive. </para> <para>If you've obtained the source distribution of JBoss Portal, you need to build and deploy the WSRP service separately. Please follow the instructions on how to install @@ -133,7 +119,7 @@ <sect1> <title>Making a portlet remotable</title> - <para>JBoss Portal does<emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption by + <para>JBoss Portal does <emphasis role="bold">NOT</emphasis>, by default, expose local portlets for consumption by remote WSRP consumers. In order to make a portlet remotely available, it must be made "remotable" by adding a <literal>remotable</literal> @@ -196,19 +182,12 @@ <para> In the example above, we defined two portlets with a default "remotable" status set to true. This means that all portlets defined in this descriptor are, by default, exposed remotely by JBoss Portal's WSRP producer. - Note, however, that it is possible to override the default behavior by adding a - <literal>remotable</literal> + Note, however, that it is possible to override the default behavior by adding a <literal>remotable</literal> element to a portlet description. In that case, the "remotable" status defined by the portlet takes precedence - over the default. In the example above, the - <varname>RemotelyExposedPortlet</varname> - inherits the "remotable" - status defined by default since it does not specify a - <literal>remotable</literal> - element in its description. - The<varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely - exposed. Note that in the absence of a top-level - <literal>remotable</literal> - element, portlets are NOT + over the default. In the example above, the <varname>RemotelyExposedPortlet</varname> inherits the "remotable" + status defined by default since it does not specify a <literal>remotable</literal> element in its description. + The <varname>NotRemotelyExposedPortlet</varname>, however, overrides the default behavior and is not remotely + exposed. Note that in the absence of a top-level <literal>remotable</literal> element, portlets are NOT remotely exposed. </para> </sect1> @@ -218,7 +197,7 @@ <para>WSRP Consumers vary a lot as far as how they are configured. Most of them require that you either specify the URL for the Producer's WSDL definition or the URLs for the individual endpoints. Please refer to your Consumer's documentation for specific instructions. For instructions on how to do so in JBoss Portal, please - refer to<xref linkend="consumer_configuration"/>. + refer to <xref linkend="consumer_configuration"/>. </para> <para> JBoss Portal's Producer is automatically set up when you deploy a portal instance with the WSRP service. @@ -239,9 +218,7 @@ <filename>http://{hostname}:{port}/portal-wsrp/PortletManagementService</filename> </listitem> </itemizedlist> - The default hostname is - <literal>localhost</literal> - and the default port is 8080. + The default hostname is <literal>localhost</literal> and the default port is 8080. </para> </sect1> @@ -305,8 +282,7 @@ 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. + invalidate it, thus requiring re-validation of the information. </para> <para> @@ -320,7 +296,7 @@ </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 and enter the WSDL URL for the producer in the text field - and press the "Save &amp; Refresh" button: + and press the "Refresh &amp; Save" button: <mediaobject> <imageobject> <imagedata fileref="images/wsrp/config_usewsdl.png" format="png" align="center" valign="middle"/> @@ -329,7 +305,7 @@ This will retrieve the service description associated with the Producer which WSRP 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 and that it expects a value for the registration - property named<literal>registration/consumerRole</literal>: + property named <literal>registration/consumerRole</literal>: <mediaobject> <imageobject> <imagedata fileref="images/wsrp/config_refresh.png" format="png" align="center" valign="middle"/> @@ -348,16 +324,13 @@ <imagedata fileref="images/wsrp/config_end.png" format="png" align="center" valign="middle"/> </imageobject> </mediaobject> - The Consumer for the - <literal>bea</literal> - Producer should now be available as a portlet provider and + The Consumer for the <literal>bea</literal> Producer should now be available as a portlet provider and is ready to be used. </para> <para> A producer is configured, by default, by retrieving the producer's information via a WSDL URL. There are rare cases, however, where URLs need to be provided for each of the producer's end points. You can do - exactly that by unchecking the "Use WSDL?" checkbox, as is the case for the - <literal>self</literal> + exactly that by unchecking the "Use WSDL?" checkbox, as is the case for the <literal>self</literal> producer: <mediaobject> <imageobject> @@ -370,9 +343,7 @@ <sect3> <title>Using a WSRP Producer XML descriptor</title> - <para>We will create a - <filename>public-bea-wsrp.xml</filename> - descriptor. Note that the actual name does not + <para>We will create a <filename>public-bea-wsrp.xml</filename> descriptor. Note that the actual name does not matter as long as it ends with<filename>-wsrp.xml</filename>: <example> <programlisting><![CDATA[ @@ -396,9 +367,7 @@ </example> This producer descriptor gives access to BEA's public WSRP producer. We will look at the details of the - different elements later. Note for now the - <literal>producer-id</literal> - element with a + different elements later. Note for now the <literal>producer-id</literal> element with a "<literal>bea</literal>" value. Put this file in the deploy directory and start the server (with JBoss Portal and its WSRP service deployed). </para> @@ -440,8 +409,7 @@ From there on out, you should be able to configure WSRP portlets just as any other. In particular, you can create an instance of one of the remote portlets offered by BEA's public producer just like you would create an instance of a local portlet and then assign it to a window in a page. If you go to that page, - you - should see something similar to below for this portlet: + you should see something similar to below for this portlet: <mediaobject> <imageobject> <imagedata fileref="images/wsrp/result.png" format="png" align="center" valign="middle"/> @@ -455,15 +423,13 @@ <title>WSRP Producer descriptors</title> <para> - A WSRP Producer descriptor is an XML file which name ends in - <filename>-wsrp.xml</filename> - and + A WSRP Producer descriptor is an XML file which name ends in <filename>-wsrp.xml</filename> and which can be dropped in the deploy directory of the JBoss application server or nested in .sar files. It is possible to configure access to several different producers within a single descriptor or use one file per producer, depending on your needs. The DTD for the WSRP Producer descriptor format can be found at <filename>portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd</filename>. - TODO: REPLACE WITH REFERENCE TO SCHEMA INSTEAD. + <!--TODO: REPLACE WITH REFERENCE TO SCHEMA INSTEAD.--> <note>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 @@ -473,11 +439,10 @@ producer in the database will be used. If a producer identifier is found that wasn't already in the database, that producer information will be processed and recorded in the database. Therefore, if you wish to delete a producer configuration, you need to delete the associated information in the database - (this can be accomplished using the configuration portlet as we saw in<xref linkend="consumer_gui"/>) - <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. + (this can be accomplished using the configuration portlet as we saw in <xref linkend="consumer_gui"/>) + <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. </note> </para> @@ -525,10 +490,8 @@ to the remote WSRP services. <note>It is important to note that, when using this method, JBoss Portal 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. + 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. </note> </listitem> </itemizedlist> @@ -569,13 +532,11 @@ </para> <para>Additionally, some producers require consumers to register with them before authorizing them to access - their offered portlets. If you know that information beforehand, you can provide the required - registration + their offered portlets. If you know that information beforehand, you can provide the required 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. + configure complex registration data. This should however be sufficient for most cases. </note> </para> @@ -603,11 +564,8 @@ <title>Examples</title> <para> - Here is the configuration of the - <literal>self</literal> - producer as found in - <filename>default-wsrp.xml</filename> - with a cache expiring every five minutes: + Here is the configuration of the <literal>self</literal> producer as found in + <filename>default-wsrp.xml</filename> with a cache expiring every five minutes: </para> <example> @@ -644,8 +602,7 @@ </example> <para>Here is an example of a WSRP descriptor with a 2 minute caching time and manual definition of the - endpoint - URLs: + endpoint URLs: </para> <example> @@ -726,13 +683,9 @@ If you recall, the producer was requiring registration and required a value to be provided for the <literal>registration/consumerRole</literal> property. The description of that property indicated that - three values were possible:<literal>public</literal>, - <literal>partner</literal> - or - <literal>insider</literal> - each corresponding to a different service level. We registered using the - <literal>public</literal> - service level. This gave us access to three portlets as shown here: + three values were possible: <literal>public</literal>, <literal>partner</literal> or + <literal>insider</literal> each corresponding to a different service level. We registered using the + <literal>public</literal> service level. This gave us access to three portlets as shown here: <mediaobject> <imageobject> <imagedata fileref="images/wsrp/bea.png" format="png" align="center" valign="middle"/> @@ -743,13 +696,8 @@ Suppose now that we would like to upgrade our service level to the "insider" level. We will need to tell BEA's producer that our registration data has been modified. Let's see how to do this. Assuming you have configured access to the producer as previously described, please go to the configuration screen for - the - <literal>bea</literal> - producer and modify the value of the - <literal>registration/consumerRole</literal> - to - <literal>insider</literal> - instead of<literal>public</literal>: + the <literal>bea</literal> producer and modify the value of the <literal>registration/consumerRole</literal> + to <literal>insider</literal> instead of <literal>public</literal>: <mediaobject> <imageobject> <imagedata fileref="images/wsrp/modify_reg_start.png" format="png" align="center" valign="middle"/> @@ -770,9 +718,7 @@ <imagedata fileref="images/wsrp/modify_reg_end.png" format="png" align="center" valign="middle"/> </imageobject> </mediaobject> - You can now check the list of available portlets from the - <literal>bea</literal> - provider and verify that + You can now check the list of available portlets from the <literal>bea</literal> provider and verify that new portlets are now available: <mediaobject> <imageobject> @@ -790,9 +736,7 @@ It can also happen that a producer administrator decided to require more information from registered consumers. In this case, invoking operations on the producer will fail with an <exceptionname>OperationFailedFault</exceptionname>. JBoss Portal will attempt to help you in this - situation. Let's walk through an example using the - <literal>self</literal> - producer. Let's assume that + situation. Let's walk through an example using the <literal>self</literal> producer. Let's assume that registration is required without any registration properties (as is the case by default). If you go to the configuration screen for this producer, you should see: <mediaobject> @@ -802,9 +746,8 @@ </mediaobject> Now suppose that the administrator of the producer now requires a value to be provided for an - <literal>email</literal> - registration property. We will actually see how to do perform this operation - in JBoss Portal when we examine how to configure Portal's producer in<xref linkend="producer_config"/>. + <literal>email</literal> registration property. We will actually see how to do perform this operation + in JBoss Portal when we examine how to configure Portal's producer in <xref linkend="producer_config"/>. Operations with this producer will now fail. If you suspect that a registration modification is required, you should go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "Refresh &amp; Save": @@ -815,9 +758,7 @@ </mediaobject> As you can see, the configuration screen now shows the currently held registration information and - the expected information from the producer. Enter a value for the - <literal>email</literal> - property + the expected information from the producer. Enter a value for the <literal>email</literal> property and then click on "Modify registration". If all went well and the producer accepted your new registration data, you should see something similar to: <mediaobject> @@ -828,11 +769,9 @@ </mediaobject> <note>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 + <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 - <exceptionname>OperationFailedFault</exceptionname> - can be caused by several different reasons, one + <exceptionname>OperationFailedFault</exceptionname> 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. @@ -906,9 +845,7 @@ <title>Overview</title> <para> You can configure the behavior of Portal's WSRP Producer by using the WSRP administration interface, which - is the preferred way, or by editing the - <filename>conf/config.xml</filename> - file found in + is the preferred way, or by editing the <filename>conf/config.xml</filename> file found in <filename>portal-wsrp.sar</filename>. Several aspects can be modified with respects to whether registration is required for consumers to access the Producer's services. </para> @@ -921,10 +858,9 @@ WSRP standard). It does, however, require consumers to be registered before sending them a full service description. This means that our WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. The producer also uses the default - <classname>RegistrationPolicy</classname> - paired with the default + <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. We will look into property - validators in greater detail later in<xref linkend="registration-configuration"/>. Suffice to say for now + validators in greater detail later in <xref linkend="registration-configuration"/>. Suffice to say for now that this allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not. </para> @@ -938,10 +874,8 @@ </imageobject> </mediaobject> As would be expected, you can specify whether or not the producer will send the full service description to - unregistered consumers, and, if it requires registration, which - <classname>RegistrationPolicy</classname> - to - use (and, if needed, which<classname>RegistrationPropertyValidator</classname>), along with required + unregistered consumers, and, if it requires registration, which <classname>RegistrationPolicy</classname> to + use (and, if needed, which <classname>RegistrationPropertyValidator</classname>), along with required registration property description for which consumers must provide acceptable values to successfully register. </para> @@ -971,15 +905,11 @@ valign="middle"/> </imageobject> </mediaobject> - You can specify the fully-qualified name for your - <classname>RegistrationPolicy</classname> - and - <classname>RegistrationPropertyValidator</classname> - there. We will keep the default value. See - <xref linkend="custom_registration"/> - for more details. Let's add, however, a registration property called + You can specify the fully-qualified name for your <classname>RegistrationPolicy</classname> and + <classname>RegistrationPropertyValidator</classname> there. We will keep the default value. See + <xref linkend="custom_registration"/> for more details. Let's add, however, a registration property called <literal>email</literal>. Click "Add property" and enter the appropriate information in the fields, - providing a description for the registration property that can be used by consumers to figure out its + providing a description for the registration property that can be used by consumers to figure out its purpose: <mediaobject> <imageobject> @@ -987,7 +917,7 @@ </imageobject> </mediaobject> 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. @@ -998,19 +928,8 @@ 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"/>. - </note> - previously noted. It can be empty if you don't require registration properties. You can also specify - whether or not registration is required in order for consumers to access the Producer's full service - description, as noted in our discussion of the default configuration, above. This is done via the - <literal>fullServiceDescriptionRequiresRegistration</literal> - attribute, which is optional. Acceptable - values for this attribute are - <literal>true</literal> - or<literal>false</literal>, defaulting to - <literal>false</literal> - in which case the Producer will always - return the full service description, whether the consumer asking for it is registered or not. + in <xref linkend="reg_mod_error"/>. + </note> </para> <sect3 id="custom_registration"> @@ -1030,18 +949,16 @@ <classname>RegistrationPropertyValidator</classname> in the default registration policy. This allows users to define their own validation mechanism. </para> - <para>Please refer to the Javadoc 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. + <para> + Please refer to the Javadoc 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. </para> <para>Defining a registration policy is required for the producer to be correctly configured. This is accomplished by specifying the qualified class name of the registration policy. Since we anticipate that most users will use the default registration policy, it is possible to provide the class - 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. + 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 important that you make sure that the identified class is available to the application server. One way @@ -1050,7 +967,7 @@ provide a default, no-argument constructor. </note> </para> - </sect3> - </sect2> + </sect3> + </sect2> </sect1> </chapter>