Author: chris.laprun(a)jboss.com Date: 2007-12-04 13:56:09 -0500 (Tue, 04 Dec 2007) New Revision: 9287 Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml Log: - Replaced use of emphasis with more semantically appropriate tags. - Enclose examples in example tags. - Added structure for upcoming content update. - Note that this update also fixes the chapter taking the whole width of the page. Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml 2007-12-04 17:32:48 UTC (rev 9286) +++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/wsrp.xml 2007-12-04 18:56:09 UTC (rev 9287) @@ -69,19 +69,19 @@ <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 <emphasis>portal-wsrp.sar</emphasis> - service archive, included in the main <emphasis>jboss-portal.sar</emphasis> service archive, if you've + 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 the <emphasis>portal-wspr.sar</emphasis> from the main <emphasis>jboss-portal.sar</emphasis> service + 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 <ulink url="http://docs.jboss.com/jbportal/v2.6/reference-guide/en/html/ins... Portal - from the sources</ulink>. Once this is done, navigate to <emphasis>JBOSS_PORTAL_HOME_DIRECTORY/wsrp</emphasis> + from the sources</ulink>. Once this is done, navigate to <filename>JBOSS_PORTAL_HOME_DIRECTORY/wsrp</filename> and type: - <programlisting>build deploy</programlisting> - At the end of the build process, <emphasis>portal-wsrp.sar</emphasis> is copied to - <emphasis>JBOSS_HOME/server/default/deploy</emphasis>. + <command>build deploy</command> + At the end of the build process, <filename>portal-wsrp.sar</filename> is copied to + <filename>JBOSS_HOME/server/default/deploy</filename>. </para> <sect2 id="wsrp-ports"> @@ -107,14 +107,14 @@ <title>Making a portlet remotable</title> <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 - <emphasis>remotable</emphasis> element to the <emphasis>jboss-portlet.xml</emphasis> deployment descriptor for - that portlet. If a <emphasis>jboss-portlet.xml</emphasis> file does not exist, one must be added to the - <emphasis>WEB-INF</emphasis> folder of the web application containing the portlet. + <literal>remotable</literal> element to the <filename>jboss-portlet.xml</filename> deployment descriptor for + that portlet. If a <filename>jboss-portlet.xml</filename> file does not exist, one must be added to the + <filename>WEB-INF</filename> folder of the web application containing the portlet. </para> <para>In the following example, the "BasicPortlet" portlet is specified as being remotable. The - <emphasis>remotable</emphasis> element is optional. + <literal>remotable</literal> element is optional. </para> - <para> + <example> <programlisting><![CDATA[ <?xml version="1.0" standalone="yes"?> <!DOCTYPE portlet-app PUBLIC "-//JBoss Portal//DTD JBoss Portlet 2.6//EN" @@ -125,14 +125,14 @@ <remotable>true</remotable> </portlet> </portlet-app>]]></programlisting> - </para> + </example> <para> - It is also possible to specify that all the portlets declared within a given <emphasis>jboss-portlet.xml</emphasis> - file have a specific "remotable" status by default. This is done by adding a single <emphasis>remotable</emphasis> - element to the root <emphasis>portlet-app</emphasis> element. Usually, this feature will be used to remotely expose + It is also possible to specify that all the portlets declared within a given <filename>jboss-portlet.xml</filename> + file have a specific "remotable" status by default. This is done by adding a single <literal>remotable</literal> + element to the root <literal>portlet-app</literal> element. Usually, this feature will be used to remotely expose several portlets without having to specify the status for all the declared portlets. Let's look at an example: </para> - <para> + <example> <programlisting><![CDATA[ <?xml version="1.0" standalone="yes"?> <!DOCTYPE portlet-app PUBLIC @@ -151,17 +151,17 @@ </portlet> </portlet-app>]]> </programlisting> - </para> + </example> <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 <emphasis>remotable</emphasis> + 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 <emphasis>RemotelyExposedPortlet</emphasis> inherits the "remotable" - status defined by default since it does not specify a <emphasis>remotable</emphasis> element in its description. - The <emphasis>NotRemotelyExposedPortlet</emphasis>, however, overrides the default behavior and is not remotely - exposed. Note that in the absence of a top-level <emphasis>remotable</emphasis> 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> @@ -176,12 +176,12 @@ <para> JBoss Portal's Producer is automatically set up when you deploy a portal instance with the WSRP service. You can access the WSDL file at - <literal>http://{hostname}:{port}/portal-wsrp/MarkupService?wsdl</literal>. You can access the endpoint URLs at: + <filename>http://{hostname}:{port}/portal-wsrp/MarkupService?wsdl</filename>. You can access the endpoint URLs at: <itemizedlist> - <listitem><literal>http://{hostname}:{port}/portal-wsrp/ServiceDescriptionService</literal></listitem> - <listitem><literal>http://{hostname}:{port}/portal-wsrp/MarkupService</literal></listitem> - <listitem><literal>http://{hostname}:{port}/portal-wsrp/RegistrationService</literal></listitem> - <listitem><literal>http://{hostname}:{port}/portal-wsrp/PortletManagementService</literal></listitem> + <listitem><filename>http://{hostname}:{port}/portal-wsrp/ServiceDescriptionService</filename></listitem> + <listitem><filename>http://{hostname}:{port}/portal-wsrp/MarkupService</filename></listitem> + <listitem><filename>http://{hostname}:{port}/portal-wsrp/RegistrationService</filename></listitem> + <listitem><filename>http://{hostname}:{port}/portal-wsrp/PortletManagementService</filename></listitem> </itemizedlist> The default hostname is <literal>localhost</literal> and the default port is 8080. </para> @@ -205,11 +205,11 @@ <para> JBoss Portal's default configuration exposes some of the sample portlets for remote consumption. As a way to test the WSRP service, a default consumer has been configured to consume these portlets. To make sure that - the service indeed works, check that there is a portlet provider with the <emphasis>self</emphasis> + the service indeed works, check that there is a portlet provider with the <literal>self</literal> identifier in the portlet providers list in the Management portlet of the Admin page. All local portlets - marked as remotable are exposed as remote portlets via the <emphasis>self</emphasis> portlet - provider so that you can check that they work as expected with WSRP. The <emphasis>portal-wsrp.sar</emphasis> - file contains a WSRP Producer descriptor (<emphasis>default-wsrp.xml</emphasis>) that configures this + marked as remotable are exposed as remote portlets via the <literal>self</literal> portlet + provider so that you can check that they work as expected with WSRP. The <filename>portal-wsrp.sar</filename> + file contains a WSRP Producer descriptor (<filename>default-wsrp.xml</filename>) that configures this default producer. This file can be edited or removed if needed. </para> </sect2> @@ -227,7 +227,7 @@ <title>Using the configuration portlet</title> <para> As of Portal 2.6, a configuration portlet is provided to configure access to remote WSRP Producers - grahically. You can access it at <literal>http://{hostname}:{port}/portal/auth/portal/admin/WSRP</literal> + grahically. You can access it at <filename>http://{hostname}:{port}/portal/auth/portal/admin/WSRP</filename> or by logging in as a Portal administrator and clicking on the WSRP tab in the Admin portal. If all went well, you should see something similar to this: <mediaobject> @@ -246,8 +246,8 @@ </para> <para> - Next, we create a new Consumer which we will call "bea". Type "bea" in the "Create a consumer named:" - field then click on "Create consumer": + Next, we create a new Consumer which we will call <literal>bea</literal>. Type "<literal>bea</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"/> @@ -264,7 +264,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 "registration/consumerRole": + property named "<literal>registration/consumerRole</literal>": <mediaobject> <imageobject> <imagedata fileref="images/wsrp/config_refresh.png" format="png" align="center" valign="middle"/> @@ -274,14 +274,15 @@ expected by the remote Producer. In the case of BEA's public producer, the possible values are indicated in the registration property description. This is not always the case... Please refer to the specific Producer's documentation.</note> - Enter "public" as the value for the registration property and press "Save &amp; Refresh" once more. You should now + Enter "<literal>public</literal>" as the value for the registration property and press "Save &amp; Refresh" once more. You should now see something similar to: <mediaobject> <imageobject> <imagedata fileref="images/wsrp/config_end.png" format="png" align="center" valign="middle"/> </imageobject> </mediaobject> - The Consumer for the "bea" Producer should now be available as a portlet provider and is ready to be used. + 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 @@ -299,9 +300,10 @@ <sect3> <title>Using a WSRP Producer XML descriptor</title> - <para>We will create a <emphasis>public-bea-wsrp.xml</emphasis> descriptor. Note that the actual name does not - matter as long as it ends with <emphasis>-wsrp.xml</emphasis>. - <programlisting><![CDATA[ + <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[ <?xml version='1.0' encoding='UTF-8' ?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN" "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd"> @@ -319,11 +321,15 @@ </wsrp-producer> </deployment> </deployments>]]></programlisting> - 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 <emphasis>producer-id</emphasis> element with a "bea" value. Put - this file in the deploy directory and start the server (with JBoss Portal and its WSRP service deployed). - </para></sect3> + </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 + "<literal>bea</literal>" value. Put this file in the deploy directory and start the server (with JBoss + Portal and its WSRP service deployed). + </para> + </sect3> + <sect3> <title>Configuring access to a remote portlet</title> <para> @@ -337,11 +343,11 @@ </mediaobject> </para> <para> - We have 3 available portlet providers: <emphasis>local, self</emphasis> and <emphasis>bea</emphasis>. The - "local" portlet provider exposes all the portlets deployed in this particular instance of Portal. As - explained above, the "self" provider refers to the default WSRP consumer bundled with Portal that consumes - the portlets exposed by the default WSRP producer. The "bea" provider corresponds to BEA's public producer - we just configured. Select it and click on "Change". You should now see something similar to: + We have 3 available portlet providers: <literal>local, self</literal> and <literal>bea</literal>. The + <literal>local</literal> portlet provider exposes all the portlets deployed in this particular instance of Portal. As + explained above, the <literal>self</literal> provider refers to the default WSRP consumer bundled with Portal that consumes + the portlets exposed by the default WSRP producer. The <literal>bea</literal> provider corresponds to BEA's public producer + we just configured. Select it and click on "View portlets". You should now see something similar to: <mediaobject> <imageobject> <imagedata fileref="images/wsrp/bea.png" format="png" align="center" valign="middle"/> @@ -360,17 +366,20 @@ </mediaobject> </para> </sect3> - </sect2> + </sect2> <sect2> <title>WSRP Producer descriptors</title> <para> - A WSRP Producer descriptor is an XML file which name ends in <emphasis>-wsrp.xml</emphasis> 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 - <emphasis>portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd</emphasis>. + <filename>portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd</filename>. + + 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 of the WSRP service will use the database-stored information for all producers which identifier is @@ -392,8 +401,8 @@ <para>Let's now look at which information needs to be provided to configure access to a remote producer.</para> <para>First, we need to provide an identifier for the producer we are configuring so that we can refer to it - afterwards. This is accomplished via the mandatory <emphasis role="bold">id</emphasis> attribute of the - <emphasis role="bold">&lt;wsrp-producer&gt;</emphasis> element.</para> + afterwards. This is accomplished via the mandatory <literal>id</literal> attribute of the + <literal>&lt;wsrp-producer&gt;</literal> element.</para> <para>JBoss Portal also needs to learn about the remote producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. Two options are currently supported to provide this @@ -403,17 +412,16 @@ <para> <itemizedlist> <listitem>You can provide the URLs for each of the different WSRP interfaces offered by the remote - producer via the <emphasis role="bold">&lt;endpoint-config&gt;</emphasis> element and its - <emphasis role="bold">&lt;service-description-url&gt;</emphasis>, - <emphasis role="bold">&lt;markup-url&gt;</emphasis>, <emphasis - role="bold">&lt;registration-url&gt;</emphasis> - and <emphasis role="bold">&lt;portlet-management-url&gt;</emphasis> children. These URLs are + producer via the <literal>&lt;endpoint-config&gt;</literal> element and its + <literal>&lt;service-description-url&gt;</literal>, + <literal>&lt;markup-url&gt;</literal>, <literal>&lt;registration-url&gt;</literal> + and <literal>&lt;portlet-management-url&gt;</literal> children. These URLs are producer-specific so you will need to refer to your producer documentation or WSDL file to determine the appropriate values. </listitem> <listitem>Alternatively, and this is the easiest way to configure your producer, you can provide a URL pointing to the WSDL description of the producer's WSRP services. This is accomplished via the - <emphasis role="bold">&lt;endpoint-wsdl-url&gt;</emphasis> element. JBoss Portal will then + <literal>&lt;endpoint-wsdl-url&gt;</literal> element. JBoss Portal will then heuristically determine, from the information contained in the WSDL file, how to connect appropriately to the remote WSRP services. <note>It is important to note that, when using this method, JBoss Portal will try to match a port @@ -424,9 +432,9 @@ </itemizedlist> </para> - <para>Both the <emphasis role="bold">id</emphasis> attribute and either - <emphasis role="bold">&lt;endpoint-config&gt;</emphasis> or - <emphasis role="bold">&lt;endpoint-wsdl-url&gt;</emphasis> elements + <para>Both the <literal>id</literal> attribute and either + <literal>&lt;endpoint-config&gt;</literal> or + <literal>&lt;endpoint-wsdl-url&gt;</literal> elements are required for a functional remote producer configuration. </para> </sect3> @@ -440,8 +448,8 @@ <para>One such optional configuration concerns caching. To prevent useless roundtrips between the local consumer and the remote producer, it is possible to cache some of the information sent by the producer (such as the list of offered portlets) for a given duration. The rate at which the information is refreshed is - defined by the <emphasis role="bold">expiration-cache</emphasis> attribute of the - <emphasis role="bold">&lt;wsrp-producer&gt;</emphasis> element which specifies the + defined by the <literal>expiration-cache</literal> attribute of the + <literal>&lt;wsrp-producer&gt;</literal> element which specifies the refreshing period in seconds. For example, providing a value of 120 for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been somehow accessed. If no value is provided, JBoss Portal will always access the remote producer regardless of whether the remote @@ -457,13 +465,13 @@ complex registration data. This should however be sufficient for most cases.</note> </para> - <para>Registration configuration is done via the <emphasis role="bold">&lt;registration-data&gt;</emphasis> + <para>Registration configuration is done via the <literal>&lt;registration-data&gt;</literal> element. Since JBoss Portal can generate the mandatory information for you, if the remote producer does not require any registration properties, you only need to provide an empty - <emphasis role="bold">&lt;registration-data&gt;</emphasis> element. Values for the registration properties - required by the remote producer can be provided via <emphasis role="bold">&lt;property&gt;</emphasis> + <literal>&lt;registration-data&gt;</literal> element. Values for the registration properties + required by the remote producer can be provided via <literal>&lt;property&gt;</literal> elements. See the example below for more details. Additionally, you can override the default consumer name - automatically provided by JBoss Portal via the <emphasis role="bold">&lt;consumer-name&gt;</emphasis> + automatically provided by JBoss Portal via the <literal>&lt;consumer-name&gt;</literal> element. If you choose to provide a consumer name, please remember that this should uniquely identify your consumer. </para> @@ -474,11 +482,11 @@ <title>Examples</title> <para> - Here is the configuration of the "self" producer as found in <emphasis>default-wsrp.xml</emphasis> 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> - <para> + <example> <programlisting><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN" @@ -509,12 +517,12 @@ </deployment> </deployments>]]> </programlisting> - </para> + </example> <para>Here is an example of a WSRP descriptor with a 2 minute caching time and manual definition of the endpoint URLs:</para> - <para> + <example> <programlisting><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN" @@ -540,12 +548,12 @@ </wsrp-producer> </deployment> </deployments>]]></programlisting> - </para> + </example> <para>Here is an example of a WSRP descriptor with endpoint definition via remote WSDL file, registration data and cache expiring every minute:</para> - <para> + <example> <programlisting><![CDATA[ <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN" @@ -565,23 +573,47 @@ </wsrp-producer> </deployment> </deployments>]]></programlisting> - </para> + </example> </sect2> </sect1> - <sect1> + <sect1> + <title>Consumers maintenance</title> + + <sect2> + <title>Modifying a currently held registration</title> + + <sect3> + <title>Registration modification for service upgrade</title> + </sect3> + + <sect3> + <title>Registration modification on producer error</title> + </sect3> + </sect2> + + <sect2> + <title>Deregistration</title> + </sect2> + + <sect2> + <title>Consumer deletion</title> + </sect2> + </sect1> + + <sect1> <title>Configuring JBoss Portal's WSRP Producer</title> <sect2> <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 <emphasis>conf/config.xml</emphasis> - file found in <emphasis>portal-wsrp.sar</emphasis>. Several aspects can be modified with respects to whether + 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> </sect2> <sect2> - <para>Using the configuration portlet</para> + <title>Using the configuration portlet</title> <para>TODO: ADD CONTENT</para> </sect2> <sect2> @@ -600,15 +632,15 @@ </registration-property-validator> </registration-configuration> </producer-configuration>]]></programlisting> - The top element <emphasis role="bold">&lt;producer-configuration&gt;</emphasis> contains a single - <emphasis role="bold">&lt;registration-configuration&gt;</emphasis> element that defines a - <emphasis>fullServiceDescritpionRequiresRegistration</emphasis> attribute with the value "true". This + 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 <emphasis role="bold">&lt;registration-configuration&gt;</emphasis> element contains a - <emphasis role="bold">&lt;registration-property-validator&gt;</emphasis> element. We will look into property + consumers. The <literal>&lt;registration-configuration&gt;</literal> element contains a + <literal>&lt;registration-property-validator&gt;</literal> element. 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. @@ -618,9 +650,8 @@ <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 <emphasis - role="bold">&lt;producer-configuration&gt;</emphasis> - element in <emphasis>portal-wsrp.sar/conf/config.xml</emphasis>. + 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>. </para> </sect2> <sect2 id="registration-configuration"> @@ -628,11 +659,11 @@ <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 - <emphasis role="bold">&lt;registration-configuration&gt;</emphasis> element. This element is optional as + <literal>&lt;registration-configuration&gt;</literal> element. This element is optional as 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 - <emphasis>fullServiceDescriptionRequiresRegistration</emphasis> attribute, which is optional. Acceptable + <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 return the full service description, whether the consumer asking for it is registered or not. </para> @@ -641,7 +672,7 @@ <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 <emphasis role="bold">RegistrationPolicy</emphasis> + accomplished by providing an implementation of the <literal>RegistrationPolicy</literal> 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. @@ -650,7 +681,7 @@ 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 - <emphasis role="bold">RegistrationPropertyValidator</emphasis> in the default registration policy. This + <literal>RegistrationPropertyValidator</literal> 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> @@ -659,9 +690,9 @@ </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 - <emphasis role="bold">&lt;registration-policy&gt;</emphasis> element. Since we anticipate that most users + <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 - <emphasis role="bold">&lt;registration-property-validator&gt;</emphasis> element and provide the class + <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. @@ -677,7 +708,7 @@ <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 - <emphasis role="bold">&lt;registration-property-description&gt;</emphasis> element per required registration + <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> @@ -696,7 +727,8 @@ 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. - <programlisting><![CDATA[ + <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"> @@ -718,7 +750,9 @@ </registration-property-description> </registration-configuration> </producer-configuration>]]></programlisting> - </para> + </example> + + </para> </sect2> </sect1> </chapter>