[gatein-commits] gatein SVN: r9056 - in epp/docs/branches/6.0/Reference_Guide/en-US: modules and 1 other directories.

Author: jaredmorgs Date: 2013-01-16 23:33:07 -0500 (Wed, 16 Jan 2013) New Revision: 9056 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml Log: Completed changes for WSRP and Internationalization Config Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-01-16 05:12:37 UTC (rev 9055) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-01-17 04:33:07 UTC (rev 9056) @@ -8,6 +8,21 @@ <simpara> <revhistory> <revision> + <revnumber>6.0.0-30</revnumber> + <date>Thu Jan 17 2013</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Final comments done for https://docs.jboss.org/author/display/GTNPORTAL35/Internationalization+Co.... Section ready for QA.</member> + <member/> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.0.0-29</revnumber> <date>Wed Jan 16 2013</date> <author> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml 2013-01-16 05:12:37 UTC (rev 9055) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/InternationalizationConfiguration.xml 2013-01-17 04:33:07 UTC (rev 9056) @@ -5,6 +5,7 @@ ]> <chapter id="chap-Reference_Guide-Internationalization_Configuration"> <title>Internationalization Configuration</title> + <remark>Source docs are located at https://docs.jboss.org/author/display/GTNPORTAL35/Internationalization+Co... <section id="sect-Reference_Guide-Internationalization_Configuration-Overview"> <title>Overview</title> <note> @@ -163,46 +164,25 @@ <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_InternationalizationConfiguration/default154.java" parse="text"/></programlisting> </section> <section id="sect-Reference_Guide-_Portlets_-Debugging_Resource_Bundle_Usage"> - <title><remark>NEEDINFO </remark>Debugging Resource Bundle Usage</title> - <remark>NEEDINFO - jmorgan - from https://docs.jboss.org/author/display/GTNPORTAL35/Internationalization+Co... there is mention of enabling debug mode, and using the Magic Locale. This was commented out in the XML here, but I have reinstated it and tried to add some more info to it. It needs to be verified for correctness. </remark> + <title>Debugging Resource Bundle Usage</title> + <remark>Taken from https://docs.jboss.org/author/display/GTNPORTAL35/Internationalization+Co.... Check here for revision incorporation status. </remark> <para> When translating an application it can sometimes be difficult to find the right key for a given property. </para> <para> You can start the Portal in <emphasis>debug mode</emphasis> and use the <emphasis role="bold">Magic locale</emphasis> from the list of available portal languages to assist in finding the correct translated key value. -This special locale translates a key to the same value.</para> - <para>For example, the translated value for the &quot;organization.title&quot; key is the value &quot;organization.title&quot;. Selecting Magic locale allows use of the portal and its applications with all the keys visible. This makes it easier to discover the correct key for a given label in the portal page.</para> - <remark>NEEDINFO - jmorgan - 20130116 - I have added these procedures based on commented out material written for EPP 5. I have updated it to what I think is required, but can&apos;t seem to get the Magic locale to display.</remark> +</para> + <para>This special locale translates a key to the same value. For example, the translated value for the &quot;organization.title&quot; key is the value &quot;organization.title&quot;. Selecting Magic locale allows use of the portal and its applications with all the keys visible. This makes it easier to discover the correct key for a given label in the portal page.</para> <procedure> - <title>Executing the portal in debug mode</title> + <title>Accessing the Magic Locale</title> <step> <para> -Open the <replaceable>JBOSS_HOME/bin/standalone.conf</replaceable> file in a text editor. +Start the portal in debug mode by executing the following command-line argument: </para> + <programlisting><command>[<replaceable>USER</replaceable>@<replaceable>HOST</replaceable> jboss-jpp-6.0]$ ./bin/standalone.sh -Dexo.product.developing=true</command></programlisting> </step> <step> - <para>Add the <literal>-Xdebug</literal> parameter to the JVM <emphasis role="bold">JAVA_OPTS</emphasis> listed on (or near, if you have made previous configuration changes) line 49. -</para> - <programlisting>if [ &quot;x$JAVA_OPTS&quot; = &quot;x&quot; ]; then - JAVA_OPTS=&quot;-Xms1303m -Xmx1303m <parameter>-Xdebug</parameter> -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000&quot; - JAVA_OPTS=&quot;$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true&quot; - JAVA_OPTS=&quot;$JAVA_OPTS -Djboss.server.default.config=standalone.xml&quot; -else - echo &quot;JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS&quot; -fi</programlisting> - </step> - <step> <para> -Start the portal as normal by executing the following command: -</para> - <programlisting><command>[<replaceable>USER</replaceable>@<replaceable>HOST</replaceable> jboss-jpp-6.0]$ ./bin/standalone.sh </command> -</programlisting> - </step> - </procedure> - <procedure> - <title>Setting the Magic Locale</title> - <step> - <para> Open <ulink url="http://localhost:8080/portal/classic"/> to display the Portal Platform landing page. </para> </step> @@ -210,11 +190,11 @@ <para>Click <guibutton>Change Language</guibutton>.</para> </step> <step> - <para>Select <guimenuitem>Magic locale</guimenuitem> from the list of available languages.</para> + <para>Select <guimenuitem>ma</guimenuitem> from the list of available languages to activate the Magic locale.</para> </step> </procedure> </section> - <section> + <section id="Translate_Language_Selection_Form"> <title>Translate the Language Selection Form</title> <figure> <title>Language Selection Screen</title> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml 2013-01-16 05:12:37 UTC (rev 9055) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/WSRP.xml 2013-01-17 04:33:07 UTC (rev 9056) @@ -1660,6 +1660,7 @@ </section> <section id="producer_config"> <title>Configuring JBoss Portal Platform&apos;s WSRP Producer</title> + <remark>Source content taken from https://docs.jboss.org/author/display/GTNPORTAL35/Configuring+GateIn%27s+... . Review this page for revision incorporation history.</remark> <section> <title>Overview</title> <para> @@ -1667,53 +1668,45 @@ Alternatively, it is possible to add an XML file called <filename>wsrp-producer-config.xml</filename> in the - <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/gatein/</filename> + <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/wsrp</filename> directory. - Several aspects can be modified with respects to whether registration is required for consumers to access + Several aspects can be modified with respect to whether registration is required for consumers to access the Producer&apos;s services. </para> <note> <title>Note</title> <para>An XML Schema defining which elements are available to configure Consumers via XML can be found in - <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-&WSRP_VERSION;.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename> + <filename><replaceable>JPP_HOME</replaceable>/modules/org/gatein/wsrp/main/wsrp-integration-api-&WSRP_VERSION;.jar/xsd/gatein_wsrp_producer_1_0.xsd </filename> </para> </note> <important> <title>Important</title> <para> It is important to note that once the XML configuration file for the producer has been read upon - the WSRP service first start, the associated information is put under control of JCR (Java Content + the WSRP service first start, the associated information is put under control of the JCR (Java Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information and ignore the content of the XML configuration file. </para> </important> - <note> - <title>Note</title> - <para> - The default configuration file for the producer can be found at - <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein-wsrp-integration.ear/lib/extension-component-&WSRP_VERSION;.jar/conf/wsrp-producer-config.xml</filename> - </para> - </note> </section> <section> <title>Default configuration</title> <para> - 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 + The default producer configuration requires 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 the WSRP producer will not provide the list of offered portlets and other - capabilities to unregistered consumers. The producer also uses the default + capabilities to unregistered consumers. </para> + <para>The producer also uses the default <classname>RegistrationPolicy</classname> paired with the default <classname>RegistrationPropertyValidator</classname>. Property - validators will be discussed in greater detail later in <xref linkend="registration-configuration"/>. Suffice to say for now - that this allows users to customize how Portal&apos;s WSRP Producer decides whether a given registration property + validators will be discussed in greater detail later in <xref linkend="registration-configuration"/>. This allows users to customize how the Portal&apos;s WSRP Producer determines whether a given registration property is valid or not. </para> <para> -JBoss Portal Platform provides a web interface to configure the producer&apos;s behavior. You can access it - by clicking on the &quot;Producer Configuration&quot; tab of the &quot;WSRP&quot; page of the &quot;admin&quot; portal. The image below is what you +JBoss Portal Platform provides a web interface to configure the producer&apos;s behavior. It is accessed by clicking on the &quot;Producer Configuration&quot; tab of the &quot;WSRP&quot; page of the &quot;admin&quot; portal. The image below is what you should see with the default configuration: </para> <mediaobject> @@ -1721,14 +1714,14 @@ <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_default.png" format="PNG"/> </imageobject> </mediaobject> - <para>As would be expected, you can specify whether or not the producer will send the full service description to + <para>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> - <para>New in JBoss Portal Platform, the WSDL URLs to access the Portal&apos;s WSRP producer are now displayed either in WSRP 1 + <para>The WSDL URLs to access the Portal&apos;s WSRP producer are displayed either in WSRP 1 or WSRP 2 mode. </para> </section> @@ -1738,7 +1731,8 @@ In order to require consumers to register with Portal&apos;s producer before interacting with it, you need to configure Portal&apos;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. To configure the producer starting with a blank + properties as is the case in the default configuration. </para> + <para>To configure the producer starting with a blank state: </para> <mediaobject> @@ -1764,7 +1758,8 @@ <classname>RegistrationPropertyValidator</classname> there. Keep the default value. See <xref linkend="custom_registration"/> - for more details. Add, however, a registration property called + for further information about other available values. </para> + <para>Add a registration property called <literal>email</literal>. Click &quot;Add property&quot; 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: @@ -1774,7 +1769,7 @@ <imagedata align="center" valign="middle" scalefit="1" fileref="images/WSRP/producer_email.png" format="PNG"/> </imageobject> </mediaobject> - <para>Press &quot;Save&quot; to record your modifications. + <para>Click &quot;Save&quot; to record the modifications. </para> <note> <title>Note</title> @@ -1807,43 +1802,70 @@ 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 <classname>RegistrationPropertyValidator</classname> - in the default registration policy. This allows users to define their own validation mechanism. + in the default registration policy. This allows users to define their own validation mechanism for registration properties that are passed by a consumer to a producer. </para> <para> Please 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 + +<ulink url="https://github.com/gatein/gatein-wsrp/blob/master/producer/src/... + <classname>org.gatein.registration.RegistrationPolicy</classname> + </ulink> and + +<ulink url="https://github.com/gatein/gatein-wsrp/blob/master/producer/src/... + <classname>org.gatein.registration.policies.RegistrationPropertyValidator</classname> + </ulink> 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 it is anticipated 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> - <title>Note</title> - <para>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 - to accomplish that is to deploy your policy implementation as JAR file in your AS instance deploy - directory. Note also that, since both policies and validators are dynamically instantiated, they - must - provide a default, no-argument constructor. - </para> - </note> + <para>Defining a registration policy is required for the producer to be correctly configured. If you don&apos;t provide one, the <literal>DefaultRegistrationPolicy</literal> associated to the <literal>DefaultRegistrationPropertyBehavior</literal> is used. </para> + <figure> + <title>DefaultRegistrationPolicy</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/WSRP/producer_default.png" width="666"/> + </imageobject> + </mediaobject> + </figure> + <para>JBoss Portal Platform can automatically detect deployed implementations of <literal>RegistrationPolicy</literal> and <literal>RegistrationPropertyValidator</literal>, assuming they conform to the following rules:</para> + <itemizedlist> + <listitem> + <para>The implementations must follow the Java <ulink url=".oracle.com/javase/7/docs/api/java/util/ServiceLoader.html"... architecture:</para> + <itemizedlist> + <listitem> + <para>They must be packaged as JARs</para> + </listitem> + <listitem> + <para>For <literal>RegistrationPolicy</literal> implementations, they must contain a special <filename>META-INF/services/org.gatein.registration.RegistrationPolicy</filename> file.</para> + </listitem> + <listitem> + <para>For <literal>RegistrationPropertyValidator</literal> implementations they must contain<filename>META-INF/services/org.gatein.registration.policies.RegistrationPropertyValidator</filename> and include a line with the fully qualified name of the implementation class.</para> + </listitem> + </itemizedlist> + <note> + <para>It is possible to package several implementations in the same JAR file, provided that each implementation class is referenced on its own line in the appropriate service definition file. To make things easier, we provide an example project of a RegistrationPolicy implementation and packaging at <ulink url="https://github.com/gatein/gatein-wsrp/tree/master/examples/poli... + </note> + </listitem> + <listitem> + <para>The implementation classes must provide a default, no-argument constructor for dynamic instantiation.</para> + </listitem> + <listitem> + <para>The implementation JARs must be deployed in <filename><replaceable>JPP_HOME</replaceable>/gatein/extensions</filename>.</para> + </listitem> + <listitem> + <para>The implementation JARs should use the <filename>.wsrp.jar</filename> extension. This is not mandatory but helps process the file faster by marking it as a WSRP extension.</para> + </listitem> + </itemizedlist> + <para>If you deployed the example <literal>RegistrationPolicy</literal> provided from the github repository (<filename>registration-policy-example.wsrp.jar</filename>) to the <filename>JPP_HOME/gatein/extensions</filename> directory, it will appear in the list of available policies in the producer configuration screen.</para> </section> </section> <section id="strict-mode"> <title>WSRP validation mode</title> - <para>The lack of conformance kit and the wording of the WSRP specification leaves room for differing + <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. A way to relax + using consumers from different vendors. </para> + <para>A way to relax the validation that the WSRP producer performs on the data provided by consumers has been introduced to help with interoperability by accepting data that would normally be invalid. Note that this validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes.