[portal-commits] JBoss Portal SVN: r9307 - in docs/tags/JBoss_Portal_2_6_3/referenceGuide/en: modules and 1 other directory.

Author: chris.laprun(a)jboss.com Date: 2007-12-05 20:55:51 -0500 (Wed, 05 Dec 2007) New Revision: 9307 Added: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_blank.png docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_default.png docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_email.png docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_registration.png Modified: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/modules/wsrp.xml Log: - Added producer configuration content. - Removed the XML aspects of producer configuration as it's not needed anymore. Will re-add in an appendix at some point. Added: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_blank.png =================================================================== (Binary files differ) Property changes on: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_blank.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_default.png =================================================================== (Binary files differ) Property changes on: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_default.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_email.png =================================================================== (Binary files differ) Property changes on: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_email.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_registration.png =================================================================== (Binary files differ) Property changes on: docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/images/wsrp/producer_registration.png ___________________________________________________________________ Name: svn:mime-type + image/png 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 01:54:34 UTC (rev 9306) +++ docs/tags/JBoss_Portal_2_6_3/referenceGuide/en/modules/wsrp.xml 2007-12-06 01:55:51 UTC (rev 9307) @@ -722,8 +722,7 @@ It is therefore sometimes necessary to modify the registration that concretizes the service agreement between a consumer and a producer. An example of easily available producer offering different level of services is BEA's public producer. We configured access to that producer in - <xref linkend="consumer_gui"/> - . + <xref linkend="consumer_gui"/>. 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 @@ -784,7 +783,7 @@ </sect3> - <sect3> + <sect3 id="reg_mod_error"> <title>Registration modification on producer error</title> <para> @@ -909,83 +908,117 @@ 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<filename>portal-wsrp.sar</filename>. Several aspects can be modified with respects to whether + 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> </sect2> <sect2> - <title>Using the configuration portlet</title> - <para>TODO: ADD CONTENT</para> - </sect2> - <sect2> <title>Default configuration</title> <para> - Let's look at the default configuration: - <programlisting><![CDATA[ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE producer-configuration PUBLIC "-//JBoss Portal//DTD WSRP Local Producer Configuration 2.6//EN" - "http://www.jboss.org/portal/dtd/jboss-wsrp-producer_2_6.dtd"> - -<producer-configuration> - <registration-configuration fullServiceDescriptionRequiresRegistration="true"> - <registration-property-validator> - org.jboss.portal.registration.policies.DefaultRegistrationPropertyValidator - </registration-property-validator> - </registration-configuration> -</producer-configuration>]]></programlisting> - The top element - <literal>&lt;producer-configuration&gt;</literal> - contains a single - <literal>&lt;registration-configuration&gt;</literal> - element that defines a - <literal>fullServiceDescritpionRequiresRegistration</literal> - attribute with the value "true". This - configuration specifies that the WSRP producer requires registration to access its services but does not - require any specific registration properties (apart from what is mandated by the 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 - <literal>&lt;registration-configuration&gt;</literal> - element contains a - <literal>&lt;registration-property-validator&gt;</literal> - element. We will look into property + The default producer configuration is to require that consumers register with it before providing access its + services but does not require any specific registration properties (apart from what is mandated by the + 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>RegistrationPropertyValidator</classname>. We will look into property 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> - </sect2> - <sect2> - <title>Minimal producer configuration</title> <para> - Requiring registration is optional: if you don't need your producer to require consumer registration, the - only thing you need to do is to provide an empty - <literal>&lt;producer-configuration&gt;</literal> - element in<filename>portal-wsrp.sar/conf/config.xml</filename>. + JBoss Portal 2.6.3 introduces a web interface to configure the producer's behavior. You can access it + by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. Here's what you + should see with the default configuration: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/producer_default.png" format="png" align="center" valign="middle"/> + </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 + registration property description for which consumers must provide acceptable values to successfully + register. </para> </sect2> + <sect2 id="registration-configuration"> <title>Registration configuration</title> <para> In order to require consumers to register with Portal's producer before interacting with it, you need to - configure Portal's behavior with respect to registration. This is done via the - <literal>&lt;registration-configuration&gt;</literal> - element. This element is optional as + configure Portal's behavior with respect to registration. Registration is optional, as are registration + properties. The producer can require registration without requiring consumers to pass any registration + properties as is the case in the default configuration. Let's configure our producer starting with a blank + state: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/producer_blank.png" format="png" align="center" valign="middle"/> + </imageobject> + </mediaobject> + We will allow unregistered consumers to see the list of offered portlets so we leave the first checkbox + ("Access to full service description requires consumers to be registered.") unchecked. We will, however, + specify that consumers will need to be registered to be able to interact with our producer. Check the second + checkbox ("Requires registration. Modifying this information will trigger invalidation of consumer + registrations."). The screen should now refresh and display: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/producer_registration.png" format="png" align="center" + 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 + <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 + purpose: + <mediaobject> + <imageobject> + <imagedata fileref="images/wsrp/producer_email.png" format="png" align="center" valign="middle"/> + </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. + </note> + + <note> + If consumers are already registered with the producer, modifying the configuration of required + registration + information will trigger the invalidation of held registrations, requiring consumers to modify their + registration before being able to access the producer again. We saw the consumer side of that process + in<xref linkend="reg_mod_error"/>. + </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 "true" or "false", defaulting to "false" in which case the Producer will - always + 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. </para> - <sect3> + <sect3 id="custom_registration"> <title>Customization of Registration handling behavior</title> <para> Registration handling behavior can be customized by users to suit their Producer needs. This is accomplished by providing an implementation of the - <literal>RegistrationPolicy</literal> + <classname>RegistrationPolicy</classname> interface. This interface defines methods that are called by Portal's Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs. @@ -994,27 +1027,21 @@ While the default registration policy provides default behavior for most registration-related aspects, there is still one aspect that requires configuration: whether a given value for a registration property is acceptable by the WSRP Producer. This is accomplished by plugging a - <literal>RegistrationPropertyValidator</literal> - in the default registration policy. This - allows users to define their own validation mechanism. + <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 - <literal>org.jboss.portal.registration.RegistrationPolicy</literal> + <classname>org.jboss.portal.registration.RegistrationPolicy</classname> and - <literal>org.jboss.portal.Registration.policies.RegistrationPropertyValidator</literal> + <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 via the - <literal>&lt;registration-policy&gt;</literal> - element. Since we anticipate that most users - will use the default registration policy, it is possible to use the - <literal>&lt;registration-property-validator&gt;</literal> - element and provide the class - name of your custom property validator instead. Since specifying a property validator only makes sense in - the context of the default registration policy, both elements are mutually exclusive. + 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. <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 @@ -1023,63 +1050,7 @@ provide a default, no-argument constructor. </note> </para> - </sect3> - - <sect3> - <title>Registration properties</title> - <para>You can also specify that consumers wishing to register with your producer provide acceptable values - for one or several registration properties. This is accomplished by providing a - <literal>&lt;registration-property-description&gt;</literal> - element per required registration - property. This element lets provide information about a given registration property such as its name, its - type, - the hint and label that will be sent to remote consumers. - <note> - At this time, only String (xsd:string) properties are supported. If your application requires more - complex - properties, please let us know. - </note> - </para> - </sect3> - - </sect2> - <sect2> - <title>Example</title> - <para> - Here is an example of a producer configurations requiring registration, barring consumers from accessing its - complete service description until they are correctly registered and requires consumers to provide - acceptable - values for two String registration properties named "name1" and "name2" respectively. The registration - service will use the - <literal>com.example.portal.SomeCustomRegistrationPolicy</literal> - class for its - registration policy. - <example> - <programlisting><![CDATA[ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE producer-configuration PUBLIC "-//JBoss Portal//DTD WSRP Local Producer Configuration 2.6//EN" - "http://www.jboss.org/portal/dtd/jboss-wsrp-producer_2_6.dtd"> - -<producer-configuration> - <registration-configuration fullServiceDescriptionRequiresRegistration="true"> - <registration-policy>com.example.portal.SomeCustomRegistrationPolicy</registration-policy> - <registration-property-description> - <name>name1</name> - <type>xsd:string</type> - <hint xml:lang="en" resourceName="resource.hint1">hint1</hint> - <label xml:lang="en" resourceName="resource.label1">label1</label> - </registration-property-description> - <registration-property-description> - <name>name2</name> - <type>xsd:string</type> - <hint xml:lang="en" resourceName="resource.hint2">hint2</hint> - <label xml:lang="en" resourceName="resource.label2">label2</label> - </registration-property-description> - </registration-configuration> -</producer-configuration>]]></programlisting> - </example> - - </para> - </sect2> + </sect3> + </sect2> </sect1> </chapter>