From do-not-reply at jboss.org Wed Nov 30 18:16:45 2011 Content-Type: multipart/mixed; boundary="===============1796793735539059307==" MIME-Version: 1.0 From: do-not-reply at jboss.org To: gatein-commits at lists.jboss.org Subject: [gatein-commits] gatein SVN: r8169 - epp/docs/branches/5.2/Reference_Guide/en-US/modules. Date: Wed, 30 Nov 2011 18:16:45 -0500 Message-ID: <201111302316.pAUNGjGw005036@svn01.web.mwc.hst.phx2.redhat.com> --===============1796793735539059307== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: smumford Date: 2011-11-30 18:16:45 -0500 (Wed, 30 Nov 2011) New Revision: 8169 Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml Log: Ported GateIn WSRP changes (r8166) Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml 2011-11-30= 18:05:57 UTC (rev 8168) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/WSRP.xml 2011-11-30= 23:16:45 UTC (rev 8169) @@ -3,271 +3,237 @@ %BOOK_ENTITIES; ]> - - Web Services for Remote Portlets (WSRP) - -
- Introduction - The Web Services for Remote Portlets specification defines a w= eb service interface for accessing and - interacting with interactive presentation-oriented web services. = It has been produced through the efforts of - the Web Services for Remote Portlets (WSRP) OASIS Technical Commi= ttee. It is based on the requirements - gathered and on the concrete proposals made to the committee. - - - Scenarios that motivate WSRP functionality include: - - - Content hosts, such as portal servers, providing Port= lets as presentation-oriented web services - that can be used by aggregation engines. + + Web Services for Remote Portlets (WSRP) + = +
+ Introduction + = + + The Web Services for Remote Portlets specification defines a w= eb service interface for accessing and interacting with interactive present= ation-oriented web services. It has been produced through the efforts of th= e Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is = based on the requirements gathered and on the concrete proposals made to th= e committee. + + = + + Scenarios that motivate WSRP functionality include: = + + + + Content hosts, such as portal servers, providing Port= lets as presentation-oriented web services that can be used by aggregation = engines. + + + = + + + Aggregating frameworks, including portal servers, con= suming presentation-oriented web services offered by content providers and = integrating them into the framework. + + + + + = + + More information on WSRP can be found on the official we= bsite for WSRP. We suggest reading the primer for a good, albeit technical, overview of WSRP. + +
+ = +
+ Level of support in JBoss Enterprise Portal Platform</titl= e> + = + <para> + The WSRP Technical Committee defined <ulink url=3D"http://www.= oasis-open.org/committees/download.php/3073">WSRP Use Profiles</ulink> to h= elp with WSRP interoperability. We will refer to terms defined in that docu= ment in this section. + </para> + = + <para> + JBoss Enterprise Portal Platform provides a Simple level of su= pport for our WSRP Producer except that out-of-band registration is not cur= rently handled. We support in-band registration and persistent local state = (which are defined at the Complex level). + </para> + = + <para> + On the Consumer side, JBoss Enterprise Portal Platform provide= s a Medium level of support for WSRP, except that we only handle HTML marku= p (as JBoss Enterprise Portal Platform itself doesn't handle other markup t= ypes). We do support explicit portlet cloning and we fully support the Port= letManagement interface. + </para> + = + <para> + As far as caching goes, we have Level 1 Producer and Consumer.= We support Cookie handling properly on the Consumer and our Producer requi= res initialization of cookies (as we have found that it improved interopera= bilty with some consumers). We don't support custom window states or modes,= as JBoss Enterprise Portal Platform doesn't either. We do, however, suppor= t CSS on both the Producer (though it's more a function of the portlets tha= n inherent Producer capability) and Consumer. + </para> + = + <para> + While we provide a complete implementation of WSRP 1.0, we do = need to go through the <ulink url=3D"http://www.oasis-open.org/committees/d= ownload.php/6018">Conformance statements</ulink> and perform more interoper= ability testing (an area that needs to be better supported by the WSRP Tech= nical Committee and Community at large). + </para> + = + <para> + JBoss Enterprise Portal Platform supports WSRP 2.0 with a comp= lete implementation of the non-optional features. The only features that we= have not implemented is support for lifetimes and leasing support. + </para> + = + <note> + <para> + As of version &VY; of JBoss Enterprise Portal Platform, WSR= P is only activated and supported when JBoss Enterprise Portal Platform is = deployed on JBoss Application Server. + </para> + </note> + </section> + = + <section> + <title>Deploying JBoss Enterprise Portal Platform's WSRP services= + = + + JBoss Enterprise Portal Platform provides a complete support o= f WSRP 1.0 and 2.0 standard interfaces and offers both consumer and produce= r services. Starting with version 2.1.0-GA of the component, WSRP is packag= ed as a JBoss Enterprise Portal Platform extension and is now self-containe= d in an easy to install package named $JBOSS_PROFILE_HOME/deploy/= gatein-wsrp-integration.ear where $JBOSS_PROFILE_HOME<= /filename> refers to your JBoss AS profile directory (default, for instance). + + = + + The extension itself is composed of the following components, = assuming $WSRP_VERSION (at the time of the writing, it was 2.1= .0-GA) is the version of the WSRP component and $PORTAL_VERSION (at the time of the writing, it was &VY;) is the current JBoss Enterprise= Portal Platform version: = + + + + META-INF contains files necessar= y for EAR packaging. The only file that is of interest from a user perspect= ive is gatein-wsse-consumer.xml which allows you to co= nfigure WS-Security support for the consumer. Please see the WSRP and WS-Security section for more details. + + + = + + + extension-component-$PORTAL_VERSION.jar, which contains the components needed to integrate the WSRP compone= nt into JBoss Enterprise Portal Platform. It also includes the default conf= iguration files for the WSRP producer and the default WSRP consumers. + + + = + + + extension-config-$PORTAL_VERSION.jar, which contains the configuration file needed by the GateIn extension = mechanism to properly register this EAR as an extension. + + + = + + + extension-war-$PORTAL_VERSION.war, which contains the configuration files needed by the GateIn extension me= chanism to properly setup the WSRP service. It includes wsrp-conf= iguration.xml which, in particular, configures several options f= or the WSRPServiceIntegration component at the heart of the WS= RP integration in JBoss Enterprise Portal Platform. + + + = + + + lib, which contains the differen= t libraries needed by the WSRP service. + + + = + + + wsrp-admin-gui-$WSRP_VERSION.war= , which contains the WSRP Configuration portlet with which you can configur= e consumers to access remote servers and how the WSRP producer is configure= d. + + + = + + + wsrp-producer-jb5wsss-$WSRP_VERSION.war, which contains the producer-side support for WS-Security. The only= file of interest from a user perspective is gatein-wsse-producer= .xml which allows you to configure WS-Security support for the p= roducer. Please see the WSRP and WS-Sec= urity section for more details. + + + + + = + + If you're not going to use WSRP in JBoss Enterprise Portal Pla= tform, it won't adversely affect your installation to leave it as-is. Other= wise, you can just remove the gatein-wsrp-integration.ear file from your AS deploy directory. + + = +
+ Considerations to use WSRP when running JBoss Enterpris= e Portal Platform on a non-default port or hostname + = + + JBoss WS (the web service stack that JBoss Enterprise Porta= l Platform uses) should take care of the details of updating the port and h= ost name used in WSDL. See the JBoss WS user guide on that subject for more details. + + = + + Of course, if you have modified you have modified the host = name and port on which your server runs, you will need to update the config= uration for the consumer used to consume JBoss Enterprise Portal Platform's= 'self' producer. Please refer to the to learn how to do so. + +
+
+ = +
+ Securing WSRP + = +
+ Considerations to use WSRP with SSL + = + + It is possible to use WSRP over SSL for secure exchange of = data. Please refer to the instructions on how to do so from GateIn's wiki. + +
+ = +
+ WSRP and WS-Security + = + + Portlets may present different data or options depending on= the currently authenticated user. For remote portlets, this means having t= o propagate the user credentials from the consumer back to the producer in = a safe and secure manner. The WSRP specification does not directly specify = how this should be accomplished, but delegates this work to the existing WS= -Security standards. + + = + + Web Container Compatibility + = + + WSRP and WS-Security is currently only supported on JBos= s Enterprise Portal Platform when running on top of JBoss AS 5. - - - Aggregating frameworks, including portal servers, con= suming presentation-oriented web services - offered by content providers and integrating them into t= he framework. + + = + + Encryption + = + + You will want to encrypt the credentials being sent betw= een the consumer and producer, otherwise they will be sent in plain text an= d could be easily intercepted. You can either configure WS-Security to encr= ypt and sign the SOAP messages being sent, or secure the transport layer by= using an https endpoint. Failure to encrypt the soap message or transport = layer will result in the username and password being sent in plain text. Use of encryption is strongly recommended. - - - - - More information on WSRP can be found on the - official website for WSRP. - We suggest reading the - primer - for a good, albeit technical, overview of WSRP. - -
- -
- Level of support in JBoss Enterprise Portal Platform - The WSRP Technical Committee defined - WSRP Use Profiles - to help with WSRP interoperability. We will refer to terms define= d in that document in - this section. - - - JBoss Enterprise Portal Platform provides a Simple level of su= pport for our WSRP Producer except that out-of-band registration - is not currently handled. We support in-band registration and per= sistent local state (which are - defined at the Complex level). - - - On the Consumer side, JBoss Enterprise Portal Platform provide= s a Medium level of support for WSRP, except that we only handle - HTML markup (as JBoss Enterprise Portal Platform itself doesn't h= andle other markup types). We do support explicit portlet - cloning and we fully support the PortletManagement interface. - - - As far as caching goes, we have Level 1 Producer and Consumer.= We support Cookie handling properly on the - Consumer and our Producer requires initialization of cookies (as = we have found that it improved interoperabilty - with some consumers). We don't support custom window states or mo= des, as JBoss Enterprise Portal Platform doesn't either. We do, - however, support CSS on both the Producer (though it's more a fun= ction of the portlets than inherent Producer - capability) and Consumer. - - - While we provide a complete implementation of WSRP 1.0, we do = need to go through the - Conformance statements - and perform more interoperability testing (an area that needs to = be better supported by the WSRP Technical - Committee and Community at large). - - - JBoss Enterprise Portal Platform supports WSRP 2.0 with a comp= lete implementation of the non-optional features. The only - features that we have not implemented is support for lifetimes an= d leasing - support. - - - - As of version &VY; of JBoss Enterprise Portal Platform, WSR= P is only activated and supported - when JBoss Enterprise Portal Platform is deployed on JBoss App= lication Server. - - -
- -
- Deploying JBoss Enterprise Portal Platform's WSRP services</t= itle> - <para> - JBoss Enterprise Portal Platform provides a complete support of W= SRP 1.0 and 2.0 standard interfaces and offers both consumer and - producer services. Starting with version 2.1.0-GA of the componen= t, WSRP is packaged as a JBoss Enterprise Portal Platform - extension and is now self-contained in an easy to install package= named - <filename>$JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear<= /filename> - where - <filename>$JBOSS_PROFILE_HOME</filename> - refers to your JBoss AS profile directory (<filename>default</fil= ename>, for instance). - </para> - <para> - The extension itself is composed of the following components, ass= uming - <code>$WSRP_VERSION</code> - (at the time of the writing, it was 2.1.0-GA) is the version of t= he WSRP component and - <code>$PORTAL_VERSION</code> - (at the time of the writing, it was &VY;) is the current JBoss En= terprise Portal Platform version: - <itemizedlist> - <listitem> + </warning> + = + <important> + <title>Credentials + = - META-INF - contains files necessary for EAR packaging. The only fil= e that is of interest from a user perspective - is - gatein-wsse-consumer.xml - which allows you to configure WS-Security support for th= e consumer. Please see the - WSRP and WS-Security= section for more details. + When the consumer sends the user credentials to the prod= ucer, it is sending the credentials for the currently authenticated user in= the consumer. This makes signing in to remote portlets transparent to end = users, but also requires that the producer and consumer use the same creden= tials. This means that the username and password must be the same and valid= on both servers. - - + = - extension-component-$PORTAL_VERSION.jar, which contains the components needed to - integrate the WSRP component into JBoss Enterprise Porta= l Platform. It also includes the default configuration files for - the WSRP producer and the default WSRP consumers. + The recommended approach for this situation would be to = use a common ldap configuration. Please see the user guide on how to config= ure ldap for use with JBoss Enterprise Portal Platform - - + + = + + The GateIn Wiki article, GateIn WSRP and Web Service S= ecurity, also provides a step-by-step example on how to configure W= SRP with WS-Security. + + = +
+ WS-Security Configuration + = - extension-config-$PORTAL_VERSION.jar, which contains the configuration file - needed by the GateIn extension mechanism to properly reg= ister this EAR as an extension. + JBoss Enterprise Portal Platform uses JBossWS Native to = handle ws-security. Please see the WS-Security section of the JBoss AS 5 Administration and Confi= guration Guide for indepth configuration options. Please note that= since the consumer passes its credentials to the producer, the consumer wi= ll act at the wss client and the producer will act as the wss server. - - + = - extension-war-$PORTAL_VERSION.war, = which contains the configuration files - needed by the GateIn extension mechanism to properly set= up the WSRP service. It includes - wsrp-configuration.xml - which, in particular, configures several options for the - WSRPServiceIntegration - component at the heart of the WSRP integration in JBoss = Enterprise Portal Platform. + The following are the JBossWS Native configuration files= which need to be configure for WSRP: - - + = + + + + gatein-wsrp-integration.ear/META-INF/gat= ein-wsse-consumer.xml: JBossWS configuration file for the consum= er. + + + = + + + gatein-wsrp-integration.ear/wsrp-produce= r-jb5wss.war/WEB-INF/conf/gatein-wsse-producer.xml : JBossWS con= figuration file for the producer. + + + +
+ = +
+ WS-Security Producer Configuration + = - lib, which contains the different l= ibraries needed by the WSRP service. + Other than the JBossWS configuration file mention above,= no other configuration changes should be necessary for the producer. - - +
+ = +
+ WS-Security Consumer Configuration + = - wsrp-admin-gui-$WSRP_VERSION.war, w= hich contains the WSRP Configuration portlet - with which you can configure consumers to access remote = servers and how the WSRP producer is - configured. + The consumer requires a few changes before it will funct= ion properly with WS-Security. The consumer needs access to the current ser= vlet request since this is used to retrieve the currently authenticated use= r. In order for the consumer to access this information, it needs a special= servlet-filter added to the portal. - - - wsrp-producer-jb5wsss-$WSRP_VERSION.war, which contains the producer-side - support for WS-Security. The only file of interest from = a user perspective is - gatein-wsse-producer.xml which allo= ws you to configure WS-Security support for - the producer. Please see the WSRP and WS-Security section - for more details. + = + + In gatein.ear/02portal.war/WEB-INF/web.xml add the following information: - - - - - If you're not going to use WSRP in JBoss Enterprise Portal Platfo= rm, it won't adversely affect your installation to leave it - as-is. Otherwise, you can just remove the - gatein-wsrp-integration.ear - file from your AS deploy directory. - - -
- Considerations to use WSRP when running JBoss Enterprise P= ortal Platform on a non-default port or hostname - - JBoss WS (the web service stack that JBoss Enterprise Portal P= latform uses) should take care of the details of updating the - port and host name used in WSDL. See the - JBoss WS user guide on that - subject - - for more details. - - - Of course, if you have modified you have modified the host nam= e and port on which your server runs, you will - need to - update the configuration for the consumer used to consume JBos= s Enterprise Portal Platform's 'self' producer. Please refer to - the - - to learn how to do so. - -
-
- -
- Securing WSRP -
- Considerations to use WSRP with SSL - It is possible to use WSRP over SSL for secure exchange of = data. Please refer to the - instructions - on how to do so from - GateIn's= wiki. - -
-
- WSRP and WS-Security - Portlets may present different data or options depending on = the currently authenticated user. For remote - portlets, this means having to propagate the user credential= s from the consumer back to the producer in - a safe and secure manner. The WSRP specification does not di= rectly specify how this should be - accomplished, but delegates this work to the existing WS-Sec= urity standards. - - - Web Container Compatibility - WSRP and WS-Security is currently only supported on JBoss = Enterprise Portal Platform when running on top of JBoss - AS 5. - - - - Encryption - You will want to encrypt the credentials being sent betwee= n the consumer and producer, otherwise they - will be sent in plain text and could be easily intercepted= . You can either configure WS-Security to - encrypt and sign the SOAP messages being sent, or secure t= he transport layer by using an https endpoint. - Failure to encrypt the soap message or transport layer wil= l result in the username and password being - sent in plain text. Use of encrypt= ion is strongly recommended. - - - - Credentials - When the consumer sends the user credentials to the produc= er, it is sending the credentials for the - currently authenticated user in the consumer. This makes s= igning in to remote portlets transparent - to end users, but also requires that the producer and cons= umer use the same credentials. This means - that the username and password must be the same and valid = on both servers. - - The recommended approach for this situation would be to use= a common ldap configuration. Please - see the user guide on how to configure ldap for use with JB= oss Enterprise Portal Platform - - - The GateIn Wiki article, - GateIn WSRP and Web Service Security, also provides = a step-by-step example on how to configure - WSRP with WS-Security. - -
- WS-Security Configuration - JBoss Enterprise Portal Platform uses JBossWS Native to ha= ndle ws-security. Please see the WS-Security section of the - JBoss= AS 5 Administration and Configuration Guide - for indepth configuration options. Please note th= at since the consumer passes its credentials - to the producer, the consumer will act at the wss client a= nd the producer will act as the wss server. - - The following are the JBossWS Native configuration files = which need to be configure for WSRP: - - - - - gatein-wsrp-integration.ear/META-INF/gatein-wsse= -consumer.xml: JBossWS - configuration file for the consumer. - - - - - gatein-wsrp-integration.ear/wsrp-producer-jb5wss= .war/WEB-INF/conf/gatein-wsse-producer.xml - : JBossWS configuration file for the producer. - - - -
-
- WS-Security Producer Configuration - - Other than the JBossWS configuration file mention above, no ot= her configuration changes should be necessary - for the producer. - -
-
- WS-Security Consumer Configuration - The consumer requires a few changes before it will functio= n properly with WS-Security. The consumer - needs access to the current servlet request since this is = used to retrieve the currently authenticated - user. In order for the consumer to access this information= , it needs a special servlet-filter added to - the portal. - - In gatein.ear/02portal.war/WEB-INF/web.xml add the following information: - ServletAccessFilter @@ -278,62 +244,73 @@ /* ]]> - - Finally, in the WSRP Configuration portlet, in the consumer co= nfiguration options, you will need to check the 'Enable WS Security' checkb= ox: - - - - - - -
-
- WS-Security Consumer Checklist - - In order for the consumer to handle ws-security, the following= steps must be completed properly - - - - The JBossWS configuration files must be configured - - - The filter must be added to the portal's web.xml - - - the enable wss feature must be check in the wsrp admin= - - - The consumer will not properly handle ws-security unless a= ll 3 are properly configured -
+ + Finally, in the WSRP Configuration portlet, in the consu= mer configuration options, you will need to check the 'Enable WS Security' = checkbox: + + = + + + + + +
+ = +
+ WS-Security Consumer Checklist + = + + In order for the consumer to handle ws-security, the fol= lowing steps must be completed properly + + = + + + + The JBossWS configuration files must be configured + + + = + + + The filter must be added to the portal's web.xml + + + = + + + the enable wss feature must be check in the wsrp a= dmin + + + + = + + The consumer will not properly handle ws-security unless= all 3 are properly configured + +
+
-
- -
- Making a portlet remotable - + = +
+ Making a portlet remotable + = + + + Only JSR-286 (Portlet 2.0) portlets can be made remotable a= s the mechanism to expose a portlet to WSRP relies on a JSR-286-only functi= onality. + + + = - Only JSR-286 (Portlet 2.0) portlets can be made remotable as t= he mechanism to expose a portlet to WSRP - relies on a JSR-286-only functionality. + JBoss Enterprise Portal Platform does = NOT, 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 marking it as such in the associated portlet.= xml. This is accomplished by using a specific org.gatein.p= c.remotable container-runtime-option. Setting its value to tru= e makes the portlet available for remote consumption, while setting = its value to false will not publish it remotely. As specifying= the remotable status for a portlet is optional, you do not need to do anyt= hing if you don't need your portlet to be available remotely. - - JBoss Enterprise Portal Platform does - NOT, by default, expose local = portlets for consumption - by remote WSRP consumers. In order to make a portlet remotely ava= ilable, it must be made "remotable" by marking - it as such in the associated - portlet.xml. This is accomplished by using a= specific - org.gatein.pc.remotable container-runtime-option. Se= tting its value to - true - makes the portlet available for remote consumption, while setting= its value to - false - will not publish it remotely. As specifying the remotable status = for a portlet is optional, you do not need to - do anything if you don't need your portlet to be available remote= ly. - - In the following example, the "BasicPortlet" portlet is specif= ied as being remotable. - - - Example + = - + = + + Example + = + + ]]> - - - - - It is also possible to specify that all the portlets declared wit= hin a given portlet application to be - remotable by default. This is done by specifying the - - container-runtime-option - - at the - portlet-app - element level. Individual portlets can override that value to not= be remotely exposed. Let's look at an - example: - - - Example + + + = - container-runtime-option at the por= tlet-app element level. Individual portlets can override that value = to not be remotely exposed. Let's look at an example: + + = + + Example + = + + ]]> + + + = + + In the example above, we defined two portlets. The org.g= atein.pc.remotable container-runtime-option being set to true<= /code> at the portlet-app level, all portlets defined in this = particular portlet application are exposed remotely by JBoss Enterprise Por= tal Platform's WSRP producer. Note, however, that it is possible to overrid= e the default behavior: specifying a value for the org.gatein.pc.remo= table container-runtime-option at the portlet level wil= l take precedence over the default. In the example above, the = + + RemotelyExposedPortlet + + inherits the remotable status defined at the portlet-ap= p level since it does not specify a value for theorg.gatein.pc= .remotable container-runtime-option. The + + NotRemotelyExposedPortlet + + , however, overrides the default behavior and is not remotely = exposed. Note that in the absence of a top-level org.gatein.pc.remota= ble container-runtime-option value set totrue, portlets= are NOT remotely exposed. - - - - - In the example above, we defined two portlets. The - org.gatein.pc.remotable container-runtime-option - being set to - true - at the - portlet-app - level, all portlets defined in this particular portlet applicatio= n are exposed remotely by JBoss Enterprise Portal Platform's - WSRP - producer. - Note, however, that it is possible to override the default behavi= or: specifying a value for the - org.gatein.pc.remotable container-runtime-option - at the - portlet - level will take precedence over the default. In the example above= , the - RemotelyExposedPortlet - inherits the remotable status defined at the - portlet-app - level since it does not specify a value for theorg.gatein.p= c.remotable container-runtime-option. - TheNotRemotelyExposedPortlet, however, overrid= es the default behavior and is not remotely - exposed. Note that in the absence of a top-level - org.gatein.pc.remotable container-runtime-option - value set totrue, portlets are NOT remotely exposed. - -
- -
- Consuming JBoss Enterprise Portal Platform's WSRP portlets fr= om a remote Consumer - WSRP Producers vary a lot as far as how they are configured. M= ost of them require that you specify - the URL for the Producer's WSDL definition. Please refer to the r= emote producer's documentation for specific - instructions. For instructions on how to do so in JBoss Enterpris= e Portal Platform, please refer to - . - - - JBoss Enterprise Portal Platform's Producer is automatically set = up when you deploy a portal instance with the WSRP service. - You can access the WSDL file at - http://{hostname}:{port}/wsrp-producer/v2/MarkupService= ?wsdl. If you wish to use only the - WSRP 1 compliant version of the producer, please use the WSDL fil= e found at - http://{hostname}:{port}/wsrp-producer/v1/MarkupService= ?wsdl. - The default hostname is - localhost - and the default port is 8080. - -
- -
- Consuming remote WSRP portlets in JBoss Enterprise Portal Pla= tform +
+ =
- Overview + Consuming JBoss Enterprise Portal Platform's WSRP portlets= from a remote Consumer + = - To be able to consume WSRP portlets exposed by a remote produc= er, JBoss Enterprise Portal Platform's WSRP consumer needs to - know how to access that remote producer. One can configure acc= ess to a remote producer using the provided - configuration portlet. Alternatively, it is also possible to c= onfigure access to remote producers using an - XML descriptor, though it is recommended (and easier) to do so= via the configuration portlet. + WSRP Producers vary a lot as far as how they are configured. M= ost of them require that you specify the URL for the Producer's WSDL defini= tion. Please refer to the remote producer's documentation for specific inst= ructions. For instructions on how to do so in JBoss Enterprise Portal Platf= orm, please refer to . + = - Once a remote producer has been configured, the portlets that = it exposes are then available in the - Application Registry to be added to categories and then to pag= es. + JBoss Enterprise Portal Platform's Producer is automatically s= et up when you deploy a portal instance with the WSRP service. You can acce= ss the WSDL file at http://{hostname}:{port}/wsrp-producer/v2/Mar= kupService?wsdl. If you wish to use only the WSRP 1 compliant ve= rsion of the producer, please use the WSDL file found at http://{= hostname}:{port}/wsrp-producer/v1/MarkupService?wsdl. The defaul= t hostname is localhost and the default port is 8080.
- -
- Configuring a remote producer using the configuration port= let - - Let's work through the steps of defining access to a remote pr= oducer using the configuration portlet so that its portlets can be - consumed within JBoss Enterprise Portal Platform. We will conf= igure access to NetUnity's public WSRP producer. - - - + = +
+ Consuming remote WSRP portlets in JBoss Enterprise Portal = Platform + = +
+ Overview + = - Some WSRP producers do not support chunked encoding that is= activated by default by JBoss WS. If your - producer does not support chunked encoding, your consumer w= ill not be able to properly connect to the - producer. This will manifest itself with the following erro= r: - Caused by: org.jboss.ws.WSException: Invalid HTTP ser= ver response [503] - Service - Unavailable. - Please see this GateIn's - wiki page - - for more details. + To be able to consume WSRP portlets exposed by a remote pro= ducer, JBoss Enterprise Portal Platform's WSRP consumer needs to know how t= o access that remote producer. One can configure access to a remote produce= r using the provided configuration portlet. Alternatively, it is also possi= ble to configure access to remote producers using an XML descriptor, though= it is recommended (and easier) to do so via the configuration portlet. - - - - JBoss Enterprise Portal Platform provides a portlet to configu= re access (among other functions) to remote WSRP Producers - grahically. Starting with &VY;, the WSRP configuration portlet= is installed by default. You - can find it at - - http://localhost:8080/portal/login?initialURI=3D%2Fportal%2= Fprivate%2Fclassic%2FwsrpConfigurationp&username=3Droot&password=3D= gtn - - - - - You should see a screen similar to: - - - - - - This screen presents all the configured Consumers associated w= ith their status and possible actions on - them. A Consumer can be active or inactive. Activating a Consu= mer means that it is ready to act as a - portlet provider. Note also that a Consumer can be marked as r= equiring refresh meaning that the - information held about it might not be up to date and refreshi= ng it from the remote Producer might be a - good idea. This can happen for several reasons: the service de= scription for that remote Producer has not - been fetched yet, the cached version has expired or modificati= ons have been made to the configuration - that could potentially invalidate it, thus requiring re-valida= tion of the information. - - - + = - The WSRP configuration didn't use to be installed by defaul= t in previous versions of JBoss Enterprise Portal Platform. - We include here the legacy instructions on how to install t= his portlet in case you ever need to - re-install it. + Once a remote producer has been configured, the portlets th= at it exposes are then available in the Application Registry to be added to= categories and then to pages. +
+ = +
+ Configuring a remote producer using the configuration p= ortlet + = - Use the usual procedure to log in as a Portal administrator= and go to the Application - Registry. With the default install, you can just go to - - http://localhost:8080/portal/login?initialURI=3D%2Fporta= l%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=3Droot&p= assword=3Dgtn - - Add the WSRP Configuration portlet to the Administration ca= tegory. If you use the Import Applications - functionality, the WSRP Configuration portlet will be autom= atically added to the Administration - category. + Let's work through the steps of defining access to a remote= producer using the configuration portlet so that its portlets can be consu= med within JBoss Enterprise Portal Platform. We will configure access to Ne= tUnity's public WSRP producer. - - Now that the portlet is added to a category, it can be adde= d to a page and used. We recommend adding - it to the same page as the Application Registry as operatio= ns relating to WSRP and adding portlets to - categories are somewhat related as we will see. Go ahead an= d add the WSRP Configuration portlet to the - page using the standard procedure. - - - - - Next, we create a new Consumer which we will call net= unity. Type - "netunity" in - the "Create a consumer named:" field then click on "Create con= sumer": - - - - - - You should now see a form allowing you to enter/modify the inf= ormation about the Consumer. - Set the cache expiration value to 300 seconds, leave the defau= lt timeout value for web services (WS) - operations and enter the WSDL URL for the producer in the text= field - and press the "Refresh & Save" button: - - - - - - This will retrieve the service description associated with the= Producer which WSRP interface is described - by the WSDL file found at the URL you just entered. In our cas= e, querying the service description will - allow us to learn that the Producer requires registration, req= uested three registration properties and that - we are missing values for these properties: - - - - - - This particular producer requests simple - Yes - or - No - values for the three registration properties. Entering No, - Yes - and - No - (in that order) for the values and then pressing the "Refresh = & Save" button should result in: - - - - - - + = - At this point, there is no automated way to learn abo= ut which possible values (if any) are - expected by the remote Producer. Sometimes, the possible= values will be indicated in the - registration - property description but this is not always the case... = Please refer to the specific Producer's - documentation. + + Some WSRP producers do not support chunked encoding that= is activated by default by JBoss WS. If your producer does not support chu= nked encoding, your consumer will not be able to properly connect to the pr= oducer. This will manifest itself with the following error: Caused by= : org.jboss.ws.WSException: Invalid HTTP server response [503] - Service Un= available. Please see this GateIn's wiki page for more details. - - - - If we had been dealing with a producer which required registra= tion but didn't require any registration - properties, as is the case for the - selfv2 - consumer (the consumer that accesses the portlets made remotel= y available by JBoss Enterprise Portal Platform's producer via - WSRP 2), we'd have seen something similar to, after pressing t= he "Refresh & Save" button: - - - + JBoss Enterprise Portal Platform provides a portlet to conf= igure access (among other functions) to remote WSRP Producers grahically. S= tarting with &VY;, the WSRP configuration portlet is installed by default. = You can find it at http://localhost:8080/portal/login?initialURI=3D%2Fportal%2Fpri= vate%2Fclassic%2FwsrpConfigurationp&username=3Droot&password=3Dgtn = + + = + + You should see a screen similar to: = + + + - - - -
- -
- Configuring access to remote producers via XML - - While we recommend you use the WSRP Configuration portlet t= o configure Consumers, we provide an - alternative way to configure consumers by adding an XML fil= e called - wsrp-consumers-config.xml in the - $JBOSS_PROFILE_HOME/conf/gatein/ direc= tory. + + + This screen presents all the configured Consumers associat= ed with their status and possible actions on them. A Consumer can be active= or inactive. Activating a Consumer means that it is ready to act as a port= let provider. Note also that a Consumer can be marked as requiring refresh = meaning that the information held about it might not be up to date and refr= eshing it from the remote Producer might be a good idea. This can happen fo= r several reasons: the service description for that remote Producer has not= been fetched yet, the cached version has expired or modifications have bee= n made to the configuration that could potentially invalidate it, thus requ= iring re-validation of the information. + + = - An XML Schema defining which elements are available t= o configure Consumers via XML can be found - in - - $JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ea= r/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.x= sd - + + The WSRP configuration didn't use to be installed by def= ault in previous versions of JBoss Enterprise Portal Platform. We include h= ere the legacy instructions on how to install this portlet in case you ever= need to re-install it. - - + = - It is important to note that once the XML configuration = file for consumers has been read upon - the WSRP service first start, the associated information= is put under control of JCR (Java Content - Repository). Subsequent launches of the WSRP service wil= l use the JCR-stored information and ignore - the content of the XML configuration file. + Use the usual procedure to log in as a Portal administra= tor and go to the Application Registry. With the default install, you can j= ust go to http://localhost:8080/portal/login?initialURI=3D%2Fp= ortal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=3Droot&a= mp;password=3Dgtn Add the WSRP Configuration portlet to the Admini= stration category. If you use the Import Applications functionality, the WS= RP Configuration portlet will be automatically added to the Administration = category. - - - - - -
- Required configuration information - - Let's now look at which information needs to be provided= to configure access to a remote producer. + - - 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 - id - attribute of the - <wsrp-producer> - element. - - - JBoss Enterprise Portal Platform also needs to learn abo= ut the remote producer's endpoints to be able to connect to the - remote web services and perform WSRP invocations. This is a= ccomplished by specifying the URL for the - WSDL description for the remote WSRP service, using the - <endpoint-wsdl-url> - element. - - - Both the - id - attribute and - <endpoint-wsdl-url> - elements are required for a functional remote producer conf= iguration. - -
- -
- Optional configuration - It is also possible to provide addtional configuration, = which, in some cases, might be important to - establish a proper connection to the remote producer. - - - One such optional configuration concerns caching. To pre= vent useless roundtrips between the local - consumer and the remote producer, it is possible to cache s= ome 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 - expiration-cache - attribute of the - <wsrp-producer> - element which specifies the refreshing period in seconds. F= or example, providing a value of 120 for - expiration-cache means that the producer information will n= ot be refreshed for 2 minutes after it has - been somehow accessed. If no value is provided, JBoss Enter= prise Portal Platform will always access the remote producer - regardless of whether the remote information has changed or= not. Since, in most instances, the - information provided by the producer does not change often,= we recommend that you use this caching - facility to minimize bandwidth usage. - - - It is also possible to define a timeout after which WS o= perations are considered as failed. This is - helpful to avoid blocking the WSRP service, waiting forever= on the service that doesn't answer. Use the - ws-timeout - attribute of the - <wsrp-producer> - element to specify how many milliseconds the WSRP service w= ill wait for a response from the remote - producer before timing out and giving up. - - - Additionally, some producers require consumers to regist= er with them before authorizing them to access - their offered portlets. If you know that information before= hand, you can provide the required - registration information in the producer configuration so t= hat the consumer can register with the remote - producer when required. - - At this time, though, only simple String propertie= s are supported and it is not possible to - configure complex registration data. This should, how= ever, be sufficient for most cases. - - - - - Registration configuration is done via the - <registration-data> - element. Since JBoss Enterprise Portal Platform can generat= e the mandatory information for you, if the remote producer does - not require any registration properties, you only need to p= rovide an empty - <registration-data> - element. Values for the registration properties - required by the remote producer can be provided via - <property> - elements. See the example below for more details. Additiona= lly, you can override the default consumer - name automatically provided by JBoss Enterprise Portal Plat= form via the - <consumer-name> - element. If you choose to provide a consumer name, please r= emember that this should uniquely identify - your consumer. - -
- -
- Examples - - - Here is the configuration of the - selfv1 - and - selfv2 - consumers as found in - $JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integratio= n.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-consumers-config.= xml - with a cache expiring every 500 seconds and with a 50 secon= d timeout for web service operations. - - - This file contains the default configuration and you = shouldn't need to edit it. If you want to make - modifications to it, we recommend that you follow the= procedure detailed in - . - - - - - - Example + = +
+ Required configuration information + = - + = + + First, we need to provide an identifier for the producer= we are configuring so that we can refer to it afterwards. This is accompli= shed via the mandatory id attribute of the <= wsrp-producer> element. + + = + + JBoss Enterprise Portal Platform also needs to learn abo= ut the remote producer's endpoints to be able to connect to the remote web = services and perform WSRP invocations. This is accomplished by specifying t= he URL for the WSDL description for the remote WSRP service, using the <endpoint-wsdl-url> element. + + = + + Both the id attribute and &l= t;endpoint-wsdl-url> elements are required for a functional re= mote producer configuration. + +
+ = +
+ Optional configuration + = + + It is also possible to provide addtional configuration, = which, in some cases, might be important to establish a proper connection t= o the remote producer. + + = + + One such optional configuration concerns caching. To pre= vent 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 t= he information is refreshed is defined by the expiration-cache attribute of the <wsrp-producer> element wh= ich specifies the refreshing period in seconds. For example, providing a va= lue of 120 for expiration-cache means that the producer information will no= t be refreshed for 2 minutes after it has been somehow accessed. If no valu= e is provided, JBoss Enterprise Portal Platform will always access the remo= te producer regardless of whether the remote information has changed or not= . Since, in most instances, the information provided by the producer does n= ot change often, we recommend that you use this caching facility to minimiz= e bandwidth us! age. + + = + + It is also possible to define a timeout after which WS o= perations are considered as failed. This is helpful to avoid blocking the W= SRP service, waiting forever on the service that doesn't answer. Use the ws-timeout attribute of the <wsrp-producer>= element to specify how many milliseconds the WSRP service will w= ait for a response from the remote producer before timing out and giving up. + + = + + Additionally, some producers require consumers to regist= er with them before authorizing them to access their offered portlets. If y= ou know that information beforehand, you can provide the required registrat= ion information in the producer configuration so that the consumer can regi= ster with the remote producer when required. = + + + At this time, though, only simple String propertie= s are supported and it is not possible to configure complex registration da= ta. This should, however, be sufficient for most cases. + + + + = + + Registration configuration is done via the <= registration-data> element. Since JBoss Enterprise Portal Plat= form can generate the mandatory information for you, if the remote producer= does not require any registration properties, you only need to provide an = empty <registration-data> element. Values for the = registration properties required by the remote producer can be provided via= <property> elements. See the example below for mo= re details. Additionally, you can override the default consumer name automa= tically provided by JBoss Enterprise Portal Platform via the <c= onsumer-name> element. If you choose to provide a consumer nam= e, please remember that this should uniquely identify your consumer. + +
+ = +
+ Examples + = + + Here is the configuration of the selfv1 and selfv2 consumers as found in $JBOSS_PRO= FILE_HOME/deploy/gatein-wsrp-integration.ear/lib/extension-component-$WSRP_= VERSION.jar/conf/wsrp-consumers-config.xml with a cache expiring= every 500 seconds and with a 50 second timeout for web service operations. = + + + This file contains the default configuration and y= ou shouldn't need to edit it. If you want to make modifications to it, we r= ecommend that you follow the procedure detailed in . + + + + = + + Example + = + + ]]> - - - - - Here is an example of a WSRP descriptor with registratio= n data and cache expiring every minute: - - - - Example + + + = - + = + + Example + = + + ]]> - - + + +
-
- -
- Adding remote portlets to categories - - If we go to the Application Registry and examine the available= portlets by clicking on the - Portlet link, you will now be able to see remote portlets if y= ou click on the REMOTE tab in the left - column: - - - - - - - - - These portlets are, of course, available to be used such as re= gular portlets: they can be used in - categories and added to pages. If you use the Import Applicati= ons functionality, they will also be - automatically imported in categories based on the keywords the= y define. - - - - More specifically, if you want to add a WSRP portlet to a cate= gory, you can access these portlets by - selecting - wsrp - in the Application Type drop-down menu: - - - - - - -
-
- -
- Consumers maintenance - -
- Modifying a currently held registration - + =
- Registration modification for service upgrade + Adding remote portlets to categories + = - Producers often offer several levels of service depending o= n consumers' subscription levels (for - example). This is implemented at the WSRP level with the re= gistration concept: producers can assert which - level of service to provide to consumers based on the value= s of given registration properties. - - - There might also be cases where you just want to update the= registration information because it has - changed. For example, the producer required you to provide = a valid email and the previously email - address is not valid anymore and needs to be updated. - - - It is therefore sometimes necessary to modify the registrat= ion that concretizes the service agreement - between a consumer and a producer. Let's take the example o= f a producer requiring a valid email (via an - email - registration property) as part of its required information = that consumers need to provide to be properly - registered. - - - Suppose now that we would like to update the email address = that we provided to the remote producer when - we first registered. We will need to tell the producer that= our registration data has been modified. - Let's see how to do this. Select the consumer for the remot= e producer in the available consumers list to - display its configuration. Assuming you want to change the = email you registered with to - foo(a)example.com, change its value in t= he field for the - email - registration property: + If we go to the Application Registry and examine the availa= ble portlets by clicking on the Portlet link, you will now be able to see r= emote portlets if you click on the REMOTE tab in the left column: = - + - Now click on "Update properties" to save the change. A "Mod= ify registration" button should now appear to - let you send this new data to the remote producer: - - - - - - Click on this new button and, if everything went well and y= our updated registration has been accepted by - the remote producer, you should see something similar to: - - - - - - -
- -
- Registration modification on producer error - + = - It can also happen that a producer administrator decided to= change its requirement for registered - consumers. JBoss Enterprise Portal Platform will attempt to= help you in this situation. Let's walk through an example using - the selfv2 consumer. Let's assume that r= egistration is requiring a valid value for an - email - registration property. If you go to the configuration scree= n for this consumer, you should see: + These portlets are, of course, available to be used such as= regular portlets: they can be used in categories and added to pages. If yo= u use the Import Applications functionality, they will also be automaticall= y imported in categories based on the keywords they define. + + = + + More specifically, if you want to add a WSRP portlet to a c= ategory, you can access these portlets by selecting wsrp= in the Application Type drop-down menu: = - + - - Now suppose that the administrator of the producer now addi= tionaly requires a value to be provided for a - name - registration property. We will actually see how to do perfo= rm this operation - in JBoss Enterprise Portal Platform when we examine how to = configure JBoss Enterprise Portal Platform's producer in - . - 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 p= roducer and refresh the information held by - the consumer by pressing "Refresh & Save": - - - - - - - As you can see, the configuration screen now shows the curr= ently held registration information and - the expected information from the producer. Enter a value f= or the - name - property - and then click on "Modify registration". If all went well a= nd the producer accepted your new registration - data, you should see something similar to: - - - - - - - - WSRP 1 makes it rather difficult to ascertain for = sure what caused an - OperationFailedFault - as it is the generic exception returned by - producers if something didn't quite happen as expecte= d during a method invocation. This means that - OperationFailedFault - can be caused by several different reasons, one - of them being a request to modify the registration da= ta. Please take a look at the log files to see - if you can gather more information as to what happene= d. WSRP 2 introduces an exception that is - specific to a request to modify registrations thus re= ducing the ambiguity that exists when using WSRP 1. - - -
- + =
- Consumer operations + Adding remote portlets to pages + = - Several operations are available from the consumer list view o= f the WSRP configuration portlet: - - - - - + Since remote portlets can be manipulated just like regular por= tlets, you can add them to pages just like you would do for a regular portl= et. Please refer to the appropriate section of the documentation for how to= do so. + = - The available operations are: - - - Configure: displays the consumer details and allow= s user to edit them - - - Refresh: forces the consumer to retrieve the servi= ce description from the remote producer to - refresh - the local information (offered portlets, registration= information, etc.) - - - - Activate/Deactivate: activates/deactivates a consu= mer, governing whether it will be available to - provide portlets and receive portlet invocations - - - - Register/Deregister: registers/deregisters a consu= mer based on whether registration is required - and/or acquired - - - - Delete: destroys the consumer, after deregistering= it if it was registered - - - Export: exports some or all of the consumer's port= lets to be able to later import them in a - different context - - - - Import: imports some or all of previously exported= portlets - - + Of note, though, is that, starting with version 3.2 of GateIn = (5.2 of EPP), it is now possible to also add a remote portlet to a pages.xml configuration file. This is accomplished using the <= literal><wsrp> element instead of the <portlet&= gt; element in your pages.xml document. Whil= e <portlet> references a local portlet using the n= ame of the application in which the portlet is contained and the portlet na= me itself to identify which portlet to use, <wsrp>= references a remote portlet using a combination of the consumer identifier= for the producer publishing the portlet and the portlet handle identifying= the portlet within the context of the producer. + = + + The format for such a reference to a remote portlet is a follo= ws: first, the identifier of the consumer that accesses the remote producer= publishing the remote portlet, then a separator (currently a period (.)) and finally the portlet handle for that portlet, which is= a string provided by the producer to identify the portlet. + + = + + Since there currently is no easy way to determine the correct = portlet handle, we recommend that you use the graphical user interface to a= dd remote portlets to pages instead of using pages.xml. + + = + Note - Import/Export functionality is only available to WSRP 2 con= sumers of producers that support this optional - functionality. Import functionality is only available if po= rtlets had previously been exported. + For remote portlets published by JBoss Enterprise Portal Pl= atform's WSRP producer, the portlet handles are, at the time of this writin= g, following the /<portlet application name>.<portlet nam= e> format. -
+ = +
+ Example + = + + In the following example, we define 2 portlets for a page n= amed Test in our pages.xml configur= ation. They are actually references to the same portlet, albeit one accesse= d locally and the other one accessing it via the selfv2 = consumer which consumes JBoss Enterprise Portal Platform's WSRP producer. Y= ou can see that the first one is local (the <portlet-application&g= t; with the 'Added locally' title) and follows th= e usual declaration. The second portlet (the one with the 'Added f= rom selfv2 consumer' title) comes from the selfv2 consumer and uses the <wsrp> element instead of <portlet> element and follows the format for portlets coming= from the JBoss Enterprise Portal Platform's WSRP producer. + + = + + Example + + + Test = -
- Importing and exporting portlets - Import and export are new functionalities added in WSRP 2. = Exporting a portlet allows a consumer to get - an opaque representation of the portlet which can then be use = by the corresponding import operation to - reconstitute it. It is mostly used in migration scenarios duri= ng batch operations. Since JBoss Enterprise Portal Platform - does not currently support automated migration of portal data,= the functionality that we provide as part of - WSRP 2 is necessarily less complete than it could be with full= portal support. - - The import/export implementation in JBoss Enterprise Portal= Platform (available since 3.1) allows users to export portlets - from a given consumer. - These portlets can then be used to replace existing content on= pages. This is accomplished by assigning - previously exported portlets to replace the content displayed = by windows on the portal's pages. Let us walk - through an example to make things clearer. - - Clicking on the "Export" action for a given consumer will d= isplay the list of portlets currently made - available by this specific consumer. An example of such a list= is shown below: - - - - - - - Once portlets have been selected, they can be exported by c= licking on the "Export" button thus making - them available for later import: - - - - - - - You can re-import the portlets directly by pressing the "Us= e for import" button or, on the Consumers list - page, using the "Import" action for a given consumer. Let's as= sume that you used that second option and that - you currently have several available sets of previously export= ed portlets to import from. After clicking the - action link, you should see a screen similar to the one below: - - - - - - - As you can see this screen presents the list of available e= xports with available operations for each. - - - View: displays the export details as previously se= en when the export was first performed - - - Delete: deletes the selected export, asking you fo= r confirmation first - - - Use for import: selects the export to import portl= ets from - - - - Once you've selected an export to import from, you will see= a screen similar to the one below: - - - - - - The screen displays the list of available exported portlets= for the previously selected export. You can - select which portlet you want to import by checking the checkb= ox next to its name. Next, you need to select - the content of which window the imported portlet will replace.= This process is done in three steps. Let's - assume in this example that you have the following page called - page1 - and containing two windows called - NetUnity WSRP 2 Interop - Cache Markup (remote) - and - /samples-remotecontroller-portlet.RemoteControl (remo= te) - as shown below: - - - - - - - In this example, we want to replace the content of the - /samples-remotecontroller-portlet.RemoteControl (remo= te) - by the content of the - /ajaxPortlet.JSFAJAXPortlet - portlet that we previously exported. To do so, we will check t= he checkbox next to the - /ajaxPortlet.JSFAJAXPortlet - portlet name to indicate that we want to import its data and t= hen select the - page1 - in the list of available pages. The screen will then refresh t= o display the list of available windows on - that page, similar to the one seen below: - - - - - - - Note that, at this point, we still need to select the windo= w which content we want to replace before - being able to complete the import operation. Let's select the - /samples-remotecontroller-portlet.RemoteControl (remo= te) - window, at which point the "Import" button will become enabled= , indicating that we now have all the - necessary data to perform the import. If all goes well, pressi= ng that button should result in a screen - similar to the one below: - - - - - - - If you now take a look at the - page1 - page, you should now see that the content - /samples-remotecontroller-portlet.RemoteControl (remo= te) - window has been replaced by the content of the - /ajaxPortlet.JSFAJAXPortlet - imported portlet and the window renamed appropriately: - - - - - - -
+ ... = -
- Erasing local registration data - - There are rare cases where it might be required to erase the l= ocal information without being able to - deregister first. This is the case when a consumer is register= ed with a producer that has been modified by - its administrator to not require registration anymore. If that= ever was to happen (most likely, it won't), - you can erase the local registration information from the cons= umer so that it can resume interacting with - the remote producer. To do so, click on "Erase local registrat= ion" button next to the registration context - information on the consumer configuration screen: - - - - - - - - Warning: - This operation is dangerous as it can result in inability to i= nteract with the remote producer if invoked - when not required. A warning screen will be displayed to give = you a chance to change your mind: - - - - - - -
-
+ + + richFacesPortlet + richFacesPortlet + + Added locally = -
- Configuring JBoss Enterprise Portal Platform's WSRP Producer<= /title> + ... + + </portlet-application> + + <portlet-application> + <wsrp>selfv2./richFacesPortlet.richFacesPortlet</wsrp> + <title>Added from selfv2 consumer + + ... + + +]]> + + +
+
+ =
- Overview - - The preferred way to configure the behavior of Portal's WSRP P= roducer is via the WSRP configuration portlet. - Alternatively, it is possible to add an XML file called - wsrp-producer-config.xml - in the - $JBOSS_PROFILE_HOME/conf/gatein/ - directory. - Several aspects can be modified with respects to whether regis= tration is required for consumers to access - the Producer's services. - - An XML Schema defining which elements are available t= o configure Consumers via XML can be found - in - - $JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ea= r/lib/wsrp-integration-api-$WSRP_VERSION.jar/xsd/gatein_wsrp_producer_1_0.x= sd - + Consumers maintenance + = +
+ Modifying a currently held registration + = +
+ Registration modification for service upgrade + = + + Producers often offer several levels of service dependin= g on consumers' subscription levels (for example). This is implemented at t= he WSRP level with the registration concept: producers can assert which lev= el of service to provide to consumers based on the values of given registra= tion properties. - - + = - 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 - Repository). Subsequent launches of the WSRP service wil= l use the JCR-stored information and ignore - the content of the XML configuration file. + There might also be cases where you just want to update = the registration information because it has changed. For example, the produ= cer required you to provide a valid email and the previously email address = is not valid anymore and needs to be updated. - + = + + It is therefore sometimes necessary to modify the regist= ration that concretizes the service agreement between a consumer and a prod= ucer. Let's take the example of a producer requiring a valid email (via an = email registration property) as part of its required inf= ormation that consumers need to provide to be properly registered. + + = + + Suppose now that we would like to update the email addre= ss that we provided to the remote producer when we first registered. We wil= l need to tell the producer that our registration data has been modified. L= et's see how to do this. Select the consumer for the remote producer in the= available consumers list to display its configuration. Assuming you want t= o change the email you registered with to foo(a)example.com, change its value in the field for the email registr= ation property: = + + + + + + Now click on "Update properties" to save the change. A = "Modify registration" button should now appear to let you send this new dat= a to the remote producer: = + + + + + + Click on this new button and, if everything went well a= nd your updated registration has been accepted by the remote producer, you = should see something similar to: = + + + + + + +
+ = +
+ Registration modification on producer error + = + + It can also happen that a producer administrator decided= to change its requirement for registered consumers. JBoss Enterprise Porta= l Platform will attempt to help you in this situation. Let's walk through a= n example using the selfv2 consumer. Let's assume that r= egistration is requiring a valid value for an email regi= stration property. If you go to the configuration screen for this consumer,= you should see: = + + + + + + Now suppose that the administrator of the producer now = additionaly requires a value to be provided for a name r= egistration property. We will actually see how to do perform this operation= in JBoss Enterprise Portal Platform when we examine how to configure JBoss= Enterprise Portal Platform's producer in . Operations with this producer will now fail. If you suspect that a regi= stration modification is required, you should go to the configuration scree= n for this remote producer and refresh the information held by the consumer= by pressing "Refresh & Save": = + + + + + + As you can see, the configuration screen now shows the = currently held registration information and the expected information from t= he producer. Enter a value for the name property and the= n click on "Modify registration". If all went well and the producer accepte= d your new registration data, you should see something similar to: = + + + + + + = + + + WSRP 1 makes it rather difficult to ascertain for = sure what caused an = + + OperationFailedFault + + as it is the generic exception returned by produc= ers if something didn't quite happen as expected during a method invocation= . This means that = + + OperationFailedFault + + can be caused by several different reasons, one o= f 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 happe= ned. WSRP 2 introduces an exception that is specific to a request to modify= registrations thus reducing the ambiguity that exists when using WSRP 1. + + + +
+
+ = +
+ Consumer operations + = + + Several operations are available from the consumer list vie= w of the WSRP configuration portlet: = + + + + + + + = + + The available operations are: = + + + + Configure: displays the consumer details and allow= s user to edit them + + + = + + + Refresh: forces the consumer to retrieve the servi= ce description from the remote producer to refresh the local information (o= ffered portlets, registration information, etc.) + + + = + + + Activate/Deactivate: activates/deactivates a consu= mer, governing whether it will be available to provide portlets and receive= portlet invocations + + + = + + + Register/Deregister: registers/deregisters a consu= mer based on whether registration is required and/or acquired + + + = + + + Delete: destroys the consumer, after deregistering= it if it was registered + + + = + + + Export: exports some or all of the consumer's port= lets to be able to later import them in a different context + + + = + + + Import: imports some or all of previously exported= portlets + + + + + = - The default configuration file for the producer can be f= ound at - $JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integra= tion.ear/lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-producer-confi= g.xml + Import/Export functionality is only available to WSRP 2 = consumers of producers that support this optional functionality. Import fun= ctionality is only available if portlets had previously been exported. - -
-
- Default configuration - - The default producer configuration is to require that consumer= s register with it before providing access its - services but does not require any specific registration proper= ties (apart from what is mandated by the - WSRP standard). It does, however, require consumers to be regi= stered before sending them a full service - description. This means that our WSRP producer will not provid= e the list of offered portlets and other - capabilities to unregistered consumers. The producer also uses= the default - RegistrationPolicy - paired with the default - RegistrationPropertyValidator. We will = look into property - validators in greater detail later in. 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. - - - JBoss Enterprise Portal Platform provides a web interface to c= onfigure 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: +
+ = +
+ Importing and exporting portlets + = + + Import and export are new functionalities added in WSRP 2. = Exporting a portlet allows a consumer to get an opaque representation of th= e portlet which can then be use by the corresponding import operation to re= constitute it. It is mostly used in migration scenarios during batch operat= ions. Since JBoss Enterprise Portal Platform does not currently support aut= omated migration of portal data, the functionality that we provide as part = of WSRP 2 is necessarily less complete than it could be with full portal su= pport. + + = + + The import/export implementation in JBoss Enterprise Portal= Platform (available since 3.1) allows users to export portlets from a give= n consumer. These portlets can then be used to replace existing content on = pages. This is accomplished by assigning previously exported portlets to re= place the content displayed by windows on the portal's pages. Let us walk t= hrough an example to make things clearer. + + = + + Clicking on the "Export" action for a given consumer will d= isplay the list of portlets currently made available by this specific consu= mer. An example of such a list is shown below: + + = - + - As would be expected, you can specify whether or not the produ= cer will send the full service description to - unregistered consumers, and, if it requires registration, which - RegistrationPolicy - to use (and, if needed, which - RegistrationPropertyValidator), along w= ith required - registration property description for which consumers must pro= vide acceptable values to successfully - register. - - New in JBoss Enterprise Portal Platform, we now display the= WSDL URLs to access JBoss Enterprise Portal Platform's WSRP producer eithe= r in WSRP 1 - or WSRP 2 mode. - -
- -
- Registration configuration - - In order to require consumers to register with Portal's produc= er before interacting with it, you need to - configure Portal's behavior with respect to registration. Regi= stration is optional, as are registration - properties. The producer can require registration without requ= iring consumers to pass any registration - properties as is the case in the default configuration. Let's = configure our producer starting with a blank - state: + = + + Once portlets have been selected, they can be exported by c= licking on the "Export" button thus making them available for later import: + + = - + - We will allow unregistered consumers to see the list of offere= d 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 t= o interact with our producer. Check the second - checkbox ("Requires registration. Modifying this information w= ill trigger invalidation of consumer - registrations."). The screen should now refresh and display: + = + + You can re-import the portlets directly by pressing the "Us= e for import" button or, on the Consumers list page, using the "Import" act= ion for a given consumer. Let's assume that you used that second option and= that you currently have several available sets of previously exported port= lets to import from. After clicking the action link, you should see a scree= n similar to the one below: + + = - + - You can specify the fully-qualified name for your - RegistrationPolicy - and - RegistrationPropertyValidator - there. We will keep the default value. See - - for more details. Let's add, however, a registration property = called - email. Click "Add property" and enter the a= ppropriate information in the fields, - providing a description for the registration property that can= be used by consumers to figure out its - purpose: + = + + As you can see this screen presents the list of available e= xports with available operations for each. = + + + + View: displays the export details as previously se= en when the export was first performed + + + = + + + Delete: deletes the selected export, asking you fo= r confirmation first + + + = + + + Use for import: selects the export to import portl= ets from + + + + + = + + Once you've selected an export to import from, you will see= a screen similar to the one below: + + = - + - Press "Save" to record your modifications. - - - At this time, only String (xsd:string) properties are= supported. If your application requires more - complex properties, please let us know. - - - - - If consumers are already registered with the producer= , modifying the configuration of required - registration - information will trigger the invalidation of held regist= rations, requiring consumers to modify their - registration before being able to access the producer ag= ain. We saw the consumer side of that process - in - . - - - - - -
- Customization of Registration handling behavior + = - Registration handling behavior can be customized by users t= o suit their Producer needs. This is - accomplished by providing an implementation of the - RegistrationPolicy - interface. This interface defines methods that are called b= y 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 nee= ds. + The screen displays the list of available exported portlets= for the previously selected export. You can select which portlet you want = to import by checking the checkbox next to its name. Next, you need to sele= ct the content of which window the imported portlet will replace. This proc= ess is done in three steps. Let's assume in this example that you have the = following page called page1 and containing two windows c= alled NetUnity WSRP 2 Interop - Cache Markup (remote) an= d /samples-remotecontroller-portlet.RemoteControl (remote) as shown below: + = + + + + + + = - While the default registration policy provides default beha= vior for most registration-related aspects, - there is still one aspect that requires configuration: whet= her a given value for a registration property - is acceptable by the WSRP Producer. This is accomplished by= plugging a - RegistrationPropertyValidator - in the default registration policy. This allows users to de= fine their own validation mechanism. + In this example, we want to replace the content of the /samples-remotecontroller-portlet.RemoteControl (remote) by = the content of the /ajaxPortlet.JSFAJAXPortlet portlet t= hat we previously exported. To do so, we will check the checkbox next to th= e /ajaxPortlet.JSFAJAXPortlet portlet name to indicate t= hat we want to import its data and then select the page1= in the list of available pages. The screen will then refresh to display th= e list of available windows on that page, similar to the one seen below: + = + + + + + + = - Please refer to the - Javadoc - for - org.gatein.registration.RegistrationPolicy - and - org.gatein.registration.policies.RegistrationPro= pertyValidator - for more - details on what is expected of each method. + Note that, at this point, we still need to select the windo= w which content we want to replace before being able to complete the import= operation. Let's select the /samples-remotecontroller-portlet.Rem= oteControl (remote) window, at which point the "Import" button wi= ll become enabled, indicating that we now have all the necessary data to pe= rform the import. If all goes well, pressing that button should result in a= screen similar to the one below: - Defining a registration policy is required for the produ= cer 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. - + = + + + + + + = + + If you now take a look at the page1 page= , you should now see that the content /samples-remotecontroller-po= rtlet.RemoteControl (remote) window has been replaced by the cont= ent of the /ajaxPortlet.JSFAJAXPortlet imported portlet = and the window renamed appropriately: + + = + + + + + +
+ = +
+ Erasing local registration data + = + + There are rare cases where it might be required to erase th= e local information without being able to deregister first. This is the cas= e when a consumer is registered with a producer that has been modified by i= ts administrator to not require registration anymore. If that ever was to h= appen (most likely, it won't), you can erase the local registration informa= tion from the consumer so that it can resume interacting with the remote pr= oducer. To do so, click on "Erase local registration" button next to the re= gistration context information on the consumer configuration screen: + + = + + + + + + = + + Warning: This operation is dangerous a= s it can result in inability to interact with the remote producer if invoke= d when not required. A warning screen will be displayed to give you a chanc= e to change your mind: + + = + + + + + +
+
+ = +
+ Configuring JBoss Enterprise Portal Platform's WSRP Produc= er + = +
+ Overview + = + + The preferred way to configure the behavior of Portal's WSR= P Producer is via the WSRP configuration portlet. Alternatively, it is poss= ible to add an XML file called wsrp-producer-config.xml in the $JBOSS_PROFILE_HOME/conf/gatein/ directory. S= everal aspects can be modified with respects to whether registration is req= uired for consumers to access the Producer's services. = - 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 clas= s is available to the application server. One - way - to accomplish that is to deploy your policy implement= ation as JAR file in your AS instance deploy - directory. Note also that, since both policies and va= lidators are dynamically instantiated, they - must - provide a default, no-argument constructor. + + An XML Schema defining which elements are available t= o configure Consumers via XML can be found in $JBOSS_PROFILE_HOM= E/deploy/gatein-wsrp-integration.ear/lib/wsrp-integration-api-$WSRP_VERSION= .jar/xsd/gatein_wsrp_producer_1_0.xsd + = + + + It is important to note that once the XML configurati= on file for the producer has been read upon the WSRP service first start, t= he associated information is put under control of JCR (Java Content Reposit= ory). Subsequent launches of the WSRP service will use the JCR-stored infor= mation and ignore the content of the XML configuration file. + + + = + + + The default configuration file for the producer can b= e found at $JBOSS_PROFILE_HOME/deploy/gatein-wsrp-integration.ear= /lib/extension-component-$WSRP_VERSION.jar/conf/wsrp-producer-config.xml + +
+ = +
+ Default configuration + = + + The default producer configuration is to require that consu= mers register with it before providing access its services but does not req= uire any specific registration properties (apart from what is mandated by t= he WSRP standard). It does, however, require consumers to be registered bef= ore sending them a full service description. This means that our WSRP produ= cer will not provide the list of offered portlets and other capabilities to= unregistered consumers. The producer also uses the default Regi= strationPolicy paired with the default RegistrationP= ropertyValidator. We will look into property validators in grea= ter detail later in. Suffice = to say for now that this allows users to customize how Portal's WSRP Produc= er decides whether a given registration property is valid or not. + + = + + JBoss Enterprise Portal Platform provides a web interface t= o 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: = + + + + + + As would be expected, you can specify whether or not the p= roducer will send the full service description to unregistered consumers, a= nd, if it requires registration, which RegistrationPolicy to use (and, if needed, which RegistrationPropertyValidato= r), along with required registration property description for w= hich consumers must provide acceptable values to successfully register. + + = + + New in JBoss Enterprise Portal Platform, we now display the= WSDL URLs to access JBoss Enterprise Portal Platform's WSRP producer eithe= r in WSRP 1 or WSRP 2 mode. + +
+ = +
+ Registration configuration + = + + In order to require consumers to register with Portal's pro= ducer before interacting with it, you need to configure Portal's behavior w= ith respect to registration. Registration is optional, as are registration = properties. The producer can require registration without requiring consume= rs to pass any registration properties as is the case in the default config= uration. Let's configure our producer starting with a blank state: = + + + + + + We will allow unregistered consumers to see the list of of= fered portlets so we leave the first checkbox ("Access to full service desc= ription requires consumers to be registered.") unchecked. We will, however,= specify that consumers will need to be registered to be able to interact w= ith our producer. Check the second checkbox ("Requires registration. Modify= ing this information will trigger invalidation of consumer registrations.")= . The screen should now refresh and display: = + + + + + + You can specify the fully-qualified name for your RegistrationPolicy and RegistrationPropertyValida= tor there. We will keep the default value. See for more details. Let's add, however, a registratio= n property called email. 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 purpo= se: = + + + + + + Press "Save" to record your modifications. = + + + At this time, only String (xsd:string) properties are= supported. If your application requires more complex properties, please le= t us know. + + + = + + + If consumers are already registered with the producer= , modifying the configuration of required registration information will tri= gger the invalidation of held registrations, requiring consumers to modify = their registration before being able to access the producer again. We saw t= he consumer side of that process in . + + + + = +
+ Customization of Registration handling behavior</tit= le> + = + <para> + Registration handling behavior can be customized by user= s to suit their Producer needs. This is accomplished by providing an implem= entation of the <classname>RegistrationPolicy</classname> interface. This i= nterface defines methods that are called by Portal's Registration service s= o that decisions can be made appropriately. A default registration policy t= hat provides basic behavior is provided and should be enough for most user = needs. + </para> + = + <para> + While the default registration policy provides default b= ehavior for most registration-related aspects, there is still one aspect th= at requires configuration: whether a given value for a registration propert= y is acceptable by the WSRP Producer. This is accomplished by plugging a <c= lassname>RegistrationPropertyValidator</classname> in the default registrat= ion policy. This allows users to define their own validation mechanism. + </para> + = + <para> + Please refer to the <trademark class=3D"trade">Javadoc</= trademark> for <classname>org.gatein.registration.RegistrationPolicy</class= name> and <classname>org.gatein.registration.policies.RegistrationPropertyV= alidator</classname> for more details on what is expected of each method. + </para> + = + <para> + Defining a registration policy is required for the produ= cer to be correctly configured. This is accomplished by specifying the qual= ified class name of the registration policy. Since we anticipate that most = users will use the default registration policy, it is possible to provide t= he class name of your custom property validator instead to customize the de= fault registration policy behavior. Note that property validators are only = used by the default policy. = + <note> + <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 y= our AS instance deploy directory. Note also that, since both policies and v= alidators are dynamically instantiated, they must provide a default, no-arg= ument constructor. + </para> + </note> + </para> + </section> + </section> + = + <section id=3D"strict-mode"> + <title>WSRP validation mode + = + + The lack of conformance kit and the wording of the WSRP spe= cification leaves room for differing interpretations, resulting in interope= rability issues. It is therefore possible to encounter issues when using co= nsumers from different vendors. We have experienced such issues and have in= troduced a way to relax the validation that our WSRP producer performs on t= he data provided by consumers to help with interoperability by accepting da= ta that would normally be invalid. Note that we only relax our validation a= lgorithm on aspects of the specification that are deemed harmless such as i= nvalid language codes. + + = + + By default, the WSRP producer is configured in strict mode.= If you experience issues with a given consumer, you might want to try to r= elax the validation mode. This is accomplished by unchecking the "Use stric= t WSRP compliance." checkbox on the Producer configuration screen. + +
-
- WSRP validation mode - The lack of conformance kit and the wording of the WSRP spe= cification leaves room for differing - interpretations, resulting in interoperability issues. It is t= herefore possible to encounter issues when - using consumers from different vendors. We have experienced su= ch issues and have introduced a way to relax - the validation that our WSRP producer performs on the data pro= vided by consumers to help with - interoperability by accepting data that would normally be inva= lid. Note that we only relax our validation - algorithm on aspects of the specification that are deemed harm= less such as invalid language codes. - - - By default, the WSRP producer is configured in strict mode. If= you experience issues with a given consumer, - you might want to try to relax the validation mode. This is ac= complished by unchecking the "Use strict WSRP - compliance." checkbox on the Producer configuration screen. - -
- -
- + --===============1796793735539059307==--