From do-not-reply at jboss.org Thu Nov 24 19:43:13 2011 Content-Type: multipart/mixed; boundary="===============7002836502574970605==" MIME-Version: 1.0 From: do-not-reply at jboss.org To: gatein-commits at lists.jboss.org Subject: [gatein-commits] gatein SVN: r8139 - in epp/docs/branches/5.2: Developer_Guide/en-US and 5 other directories. Date: Thu, 24 Nov 2011 19:43:13 -0500 Message-ID: <201111250043.pAP0hDAH009585@svn01.web.mwc.hst.phx2.redhat.com> --===============7002836502574970605== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: smumford Date: 2011-11-24 19:43:12 -0500 (Thu, 24 Nov 2011) New Revision: 8139 Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/RH-WSRP.= xml Modified: epp/docs/branches/5.2/Admin_Guide/en-US/Admin_Guide.ent epp/docs/branches/5.2/Admin_Guide/en-US/Book_Info.xml epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions.= xml epp/docs/branches/5.2/Developer_Guide/en-US/Book_Info.xml epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml epp/docs/branches/5.2/Developer_Guide/en-US/Revision_History.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Author_Group.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Book_Info.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Revision_History= .xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/conf= ig_self.png epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/modi= fy_reg_end.png epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WSRP/modi= fy_reg_self_end.png epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advanced= /Foundations/Configuring_Services.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Authenti= cationAndIdentity/SSO.xml epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xml Log: WSRP ports. Admin/Dev Guide updates Modified: epp/docs/branches/5.2/Admin_Guide/en-US/Admin_Guide.ent =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/Admin_Guide/en-US/Admin_Guide.ent 2011-11-24 17:2= 6:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Admin_Guide/en-US/Admin_Guide.ent 2011-11-25 00:4= 3:12 UTC (rev 8139) @@ -7,7 +7,7 @@ -http://bugzilla.red= hat.com/"> +http://bugzilla.red= hat.com/"> = Modified: epp/docs/branches/5.2/Admin_Guide/en-US/Book_Info.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/Admin_Guide/en-US/Book_Info.xml 2011-11-24 17:26:= 22 UTC (rev 8138) +++ epp/docs/branches/5.2/Admin_Guide/en-US/Book_Info.xml 2011-11-25 00:43:= 12 UTC (rev 8139) @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]> - Admin Guide + Administration Guide For use with JBoss Enterprise Portal Platform 5 JBoss Enterprise Portal Platform 5.2 Modified: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.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/Admin_Guide/en-US/chapter-1-Introduction.xml 2011= -11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-1-Introduction.xml 2011= -11-25 00:43:12 UTC (rev 8139) @@ -154,7 +154,7 @@ - The read-resource operation is responsible for reading t= he managed resource; describing itself and listing any operations and/or s= ub-resources it may contain. + The read-resource operation is responsible for reading t= he managed resource; describing itself and listing any operations and/or = sub-resources it may contain. = This is the primary operation to obtain information abo= ut a managed component and it's managed resources. Modified: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.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/Admin_Guide/en-US/chapter-2-REST.xml 2011-11-24 1= 7:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-2-REST.xml 2011-11-25 0= 0:43:12 UTC (rev 8139) @@ -260,7 +260,7 @@ Management attributes (which are part of a management request)= are mapped by including all request parameters of the HTTP request as attr= ibutes. So if an operation supports certain attributes, query parameters ca= n be added to the request URL to be used as attributes of the management re= quest. Attributes first-name and last-name as request parameters</= title> - <programlisting><![CDATA[http://localhost:8080/rest/private/manage= d-components/foo/bar?first-name=3Djohn&last-name=3Ddoe]]></programlisting> + <programlisting>http://localhost:8080/rest/private/managed-compone= nts/foo/bar?first-name=3Djohn&last-name=3Ddoe</programlisting> </example> <section id=3D"sid-8094332_GateInManagement-MultivalueAttributes"> = @@ -268,7 +268,7 @@ <para>Management attributes can be multi-valued (meaning more then= one value associated with an attribute). This is easy as HTTP query parame= ters can be multi-valued as well.</para> <example> <title>Multi-valued attribute colors as request parameters</titl= e> - <programlisting><![CDATA[http://localhost:8080/rest/private/mana= ged-components/foo/bar?colors=3Dred&colors=3Dgreen&colors=3Dblue]]></progra= mlisting> + <programlisting>http://localhost:8080/rest/private/managed-compo= nents/foo/bar?colors=3Dred&colors=3Dgreen&colors=3Dblue</programlis= ting> </example> </section> </section> @@ -428,7 +428,7 @@ </section> <section id=3D"sid-8094332_GateInManagement-readresource"> = - <title>read-resource + resource Since the read-resource Modified: epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Exte= nsions.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/Admin_Guide/en-US/chapter-4-Management_Extensions= .xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Admin_Guide/en-US/chapter-4-Management_Extensions= .xml 2011-11-25 00:43:12 UTC (rev 8139) @@ -13,257 +13,261 @@ = MOP Management Extension The MOP management extension registers the 'mop' managed compo= nent which is responsible for managing pages, navigation, and site layout. = It primarily supports exporting and importing this data through the export-= resource and import-resource operations. It also supports the read-config-= as-xml operation to expose the portal meta data as xml. - -
- = - Operations -
+
= - read-config-as-xml + Operations - The - read-config-as-xml - operation can only be executed on the site layout, pages, and na= vigation managed resources. The xml format returned is that of which is def= ined in by the - gatein-objects - xsd. This means that these resources are exposed in the same for= mat as what a portal extension would accept for importing data into the por= tal. + = +
+ = + config-as-xml + + The + read-config-as-xml + operation can only be executed on the site layout, pages, and = navigation managed resources. The xml format returned is that of which is d= efined in by the + gatein-objects + xsd. This means that these resources are exposed in the same f= ormat as that which a portal extension would accept for importing data into= the portal. + +
+
+ = + export-resource + + The + export-resource + operation can be executed on any resource of the MOP extension= (including the mop component itself). Since the management system recursiv= ely searches for all sub-resources that have export-resource defined (which= they are defined at the site layout, page, and navigation level), exports = can be very granular. + +
+
+ = + import-resource + + The + import-resource + operation can only be executed at the mop component (root mana= ged resource of the mop extension). This is because the exported zip file c= ontains the path information (like site type and site name). So executing an + import-resource + operation on a group site, when the zip contains data from a p= ortal site, doesn't make sense. + + + The MOP + import-resource + operation defines the + importMode + attribute as follows during import. + + + + + + + + Mode + = + + + + + Description + = + + + + + + + + + conserve + = + + + + + Import data only if no artifacts exist for that site= . For example if one page exists for site 'classic', nothing will be import= ed. + = + + + + + + + insert + = + + + + + Import data when data does not exist, otherwise do n= othing. + = + + + + + + + merge + = + + + + + Import when data does not exist, update data when it= does exist. + = + + + + + + + overwrite + = + + + + + Delete all data for that artifact of the site, impor= t new data. For example if the zip file only contains pages for site classi= c, then + = + all pages for that site are deleted and imported. + = + + + + + + + + Note + 'merge' is the default importMode. + +
-
+
= - export-resource - - The - export-resource - operation can be executed on any resource of the MOP extension (= including the mop component itself). Since the management system recursivel= y searches for all sub-resources that have export-resource defined (which t= hey are defined at the site layout, page, and navigation level), exports ca= n be very granular. - + Path Templates + Below are the list of path template variables defined in the= MOP management extension. These path template variables are used for filt= ering during export. + + + + site-type + = + These are the site types of the portal to include or exclude= . Available values are: + portal + , + group + , and + user + . + + + + + site-name + = + The sites to include or exclude. Examples could be + classic + and + /platform/administrators + . + + + + + site-layout + = + The name of the site layout depending on the site type. Avai= lable values are: + portal + , + group + , + user + . + + + + + page-name + = + The name of the page(s) to include or exclude. + + + + + nav-uri + = + The URI of the navigation node to include or exclude. + + +
-
+
= - import-resource - - The - import-resource - operation can only be executed at the mop component (root manage= d resource of the mop extension). This is because the exported zip file con= tains the path information (like site type and site name). So executing an - import-resource - operation on a group site, when the zip contains data from a por= tal site, doesn't make sense. - - - The MOP - import-resource - operation defines the - importMode - attribute as follows during import. - - - - - - - - Mode - = - - - - - Description - = - - - - - - - - - conserve - = - - - - - Import data only if no artifacts exist for that site. = For example if one page exists for site 'classic', nothing will be imported. - = - - - - - - - insert - = - - - - - Import data when data does not exist, otherwise do not= hing. - = - - - - - - - merge - = - - - - - Import when data does not exist, update data when it d= oes exist. - = - - - - - - - overwrite - = - - - - - Delete all data for that artifact of the site, import = new data. For example if the zip file only contains pages for site classic,= then - = - all pages for that site are deleted and imported. - = - - - - - - + REST API Note - 'merge' is the default importMode. + All URL's below are relative to the REST management entry = point of the portal container. -
-
-
- = - Path Templates - Below are the list of path template variables defined in the M= OP management extension. These path template variables are used for filter= ing during export. - - + + Note - site-type - = - These are the site types of the portal to include or exclude. = Available values are: - portal - , - group - , and - user - . + For all read-config-as-xml refer + + for the format of the XML. - - + +
+ = + MOP Component Resource - site-name - = - The sites to include or exclude. Examples could be - classic - and - /platform/administrators - . + The mop managed component resource (root managed resource) is = the only resource that accepts the + import-resource + operation. - - - - site-layout - = - The name of the site layout depending on the site type. Availa= ble values are: - portal - , - group - , - user - . - - - - - page-name - = - The name of the page(s) to include or exclude. - - - - - nav-uri - = - The URI of the navigation node to include or exclude. - - - -
-
- = - REST API - - Note - All URL's below are relative to the REST management entry po= int of the portal container. - - - Note - - For all read-config-as-xml refer - - for the format of the XML. - - -
- = - MOP Component Resource - - The mop managed component resource (root managed resource) is th= e only resource that accepts the - import-resource - operation. - - - HTTP Request - PUT /mop + + HTTP Request + PUT /mop = Headers: Content-Type: application/zip - - - HTTP Response - HTTP/1.1 200 OK - -
-
- = - Site Layout Resource - - The site layout resource represents the site layout of the porta= l. It's the data defined in the - portal.xml - , - group.xml - , and - user.xml - files (depending on site type) used in portal extensions to conf= igure data. - - - URL - URL: /mop/{site-type}sites/{site-name}/{site-lay= out} - -
+ + + HTTP Response + HTTP/1.1 200 OK + +
+ +
+
= - read-config-as-xml - Example of reading the site layout as xml for site classic= . + Site Layout Resource + + The site layout resource represents the site layout of the por= tal. It's the data defined in the + portal.xml + , + group.xml + , and + user.xml + files (depending on site type) used in portal extensions to co= nfigure data. + - HTTP Request - GET /mop/portalsites/classic/portal.xml + URL + URL: /mop/{site-type}sites/{site-name}/{site-l= ayout} + +
+ = + config-as-xml + Example of reading the site layout as xml for site class= ic. + + HTTP Request + GET /mop/portalsites/classic/portal.xml = or = GET /mop/portalsites/classic/portal?op=3Dread-config-as-xml - - - HTTP Response - HTTP/1.1 200 OK + + + HTTP Response + HTTP/1.1 200 OK Content-Type: application/xml = <portal-config> @@ -273,52 +277,53 @@ <locale>en</locale> ... </portal-config> - -
-
- = - export-resource - Example of exporting the site layout for site classic. - - HTTP Request - GET /mop/portalsites/classic/portal.zip + +
+
+ = + export-resource + Example of exporting the site layout for site classic. + + HTTP Request + GET /mop/portalsites/classic/portal.zip = or = GET /mop/portalsites/classic/portal?op=3Dexport-resource - - - HTTP Response - HTTP/1.1 200 OK + + + HTTP Response + HTTP/1.1 200 OK Content-Type: application/zip = [binary data] - + +
-
-
- = - Pages Resource - The pages resource represents the pages of the portal. It's = the data defined in the pages.xml used in portal extensions to configure da= ta. - - URL - URL: /mop/{site-type}sites/{site-name}/pages/{pa= ge-name} - -
+ +
= - config-as-xml - Example of reading all pages as xml for site classic. + Pages Resource + The pages resource represents the pages of the portal. It'= s the data defined in the pages.xml used in portal extensions to configure = data. - HTTP Request - GET /mop/portalsites/classic/pages.xml + URL + URL: /mop/{site-type}sites/{site-name}/pages/{= page-name} + +
+ = + config-as-xml + Example of reading all pages as xml for site classic. + + HTTP Request + GET /mop/portalsites/classic/pages.xml = or = GET /mop/portalsites/classic/pages?op=3Dread-config-as-xml - - - HTTP Response - HTTP/1.1 200 OK + + + HTTP Response + HTTP/1.1 200 OK Content-Type: application/xml = <page-set> @@ -331,19 +336,19 @@ <portlet-application> ... </page-set> - - Example of reading the homepage as xml for site classic. - - HTTP Request - GET /mop/portalsites/classic/pages/homepage.xml + + Example of reading the homepage as xml for site classic.= + + HTTP Request + GET /mop/portalsites/classic/pages/homepage.= xml = or = GET /mop/portalsites/classic/pages/homepage?op=3Dread-config-as-xml - - - HTTP Response - HTTP/1.1 200 OK + + + HTTP Response + HTTP/1.1 200 OK Content-Type: application/xml = <page-set> @@ -356,53 +361,53 @@ <portlet-application> ... </page-set> - -
-
- = - export-resource - Example of exporting all pages of site classic. - - HTTP Request - GET /mop/portalsites/classic/pages.zip + +
+
+ = + export-resource + Example of exporting all pages of site classic. + + HTTP Request + GET /mop/portalsites/classic/pages.zip = or = GET /mop/portalsites/classic/pages?op=3Dexport-resource - - - HTTP Response - HTTP/1.1 200 OK + + + HTTP Response + HTTP/1.1 200 OK Content-Type: application/zip = [binary data] - + +
-
-
= - Navigation Resource - The navigation resource represents the navigation of the por= tal. It's the data defined in the navigation.xml used in portal extensions = to configure data. - - URL - - -
+
= - read-config-as-xml - Example of reading all navigation as xml for site classic.= + Navigation Resource + The navigation resource represents the navigation of the p= ortal. It's the data defined in the navigation.xml used in portal extension= s to configure data. - HTTP Request - GET /mop/portalsites/classic/navigation.xml + URL + URL: /mop/{site-type}sites/{site-name}/navigat= ion/{nav-uri} + +
+ = + config-as-xml + Example of reading all navigation as xml for site classi= c. + + HTTP Request + GET /mop/portalsites/classic/navigation.xml = or = GET /mop/portalsites/classic/navigation?op=3Dread-config-as-xml - - - HTTP Response - HTTP/1.1 200 OK + + + HTTP Response + HTTP/1.1 200 OK Content-Type: application/xml = <node-navigation> @@ -419,19 +424,19 @@ <name>sitemap</name> ... </node-navigation> - - Example of reading the home node as xml for site classic.<= /para> - - HTTP Request - GET /mop/portalsites/classic/navigation/home.x= ml + + Example of reading the home node as xml for site classic= . + + HTTP Request + GET /mop/portalsites/classic/navigation/home= .xml = or = GET /mop/portalsites/classic/navigation/home?op=3Dread-config-as-xml - - - HTTP Response - HTTP/1.1 200 OK + + + HTTP Response + HTTP/1.1 200 OK Content-Type: application/xml = <node-navigation> @@ -447,113 +452,113 @@ </node> </page-nodes> </node-navigation> - -
-
- = - export-resource Example - Example of exporting all navigation of site classic. - - HTTP Request - GET /mop/portalsites/classic/navigation.zip + +
+
+ = + export-resource + Example of exporting all navigation of site classic. + + HTTP Request + GET /mop/portalsites/classic/navigation.zip = or = GET /mop/portalsites/classic/navigation?op=3Dexport-resource - - - HTTP Response - HTTP/1.1 200 OK + + + HTTP Response + HTTP/1.1 200 OK Content-Type: application/zip = [binary data] + +
+
+
+ = + Export and Filtering + + Filtering is activated when the + filter + attribute is passed to an + export-resource + operation. The filter attribute is a multi-value attribute tha= t is passed as request parameters of the HTTP request. + + + Note + You can either include multiple filter parameters (?filt= er=3Dfoo:bar&filter=3Dbaz:foo-bar) or separate via ';' character (?filt= er=3Dfoo:bar;baz:foo-bar) + + + Export only registry and pageManagement navigation node= s + GET /mop/groupsites/platform/administrators/na= vigation.zip?filter=3Dnav-uri:/administration/registry,/administration/page= Management -
+ + Export all site types but user and group + GET /mop.zip?filter=3Dsite-type:!user,group +
-
+
= - Export and Filtering - - Filtering is activated when the - filter - attribute is passed to an - export-resource - operation. The filter attribute is a multi-value attribute that = is passed as request parameters of the HTTP request. - - - Note - You can either include multiple filter parameters (?filter= =3Dfoo:bar&filter=3Dbaz:foo-bar) or separate via ';' character (?filter= =3Dfoo:bar;baz:foo-bar) - - - Export only registry and pageManagement navigation nodes<= /title> - <programlisting>GET /mop/groupsites/platform/administrators/navi= gation.zip?filter=3Dnav-uri:/administration/registry,/administration/pageMa= nagement</programlisting> - </example> - <example> - <title>Export all site types but user and group - GET /mop.zip?filter=3Dsite-type:!user,group - -
-
-
- = - Command Line Interface - The commands included in the management component provide us t= he tools to perform management operations on these MOP artifacts: site layo= ut, pages, and navigation. -
- = - Resource Paths - The paths of the MOP resources are exactly the same as the R= EST URL's (of course without the URL syntax). For example the path of the h= omepage for the classic site would be: - - Example - [ /]% cd /mop/portalsites/classic/pages/homepage + Command Line Interface + The commands included in the management component provide us= the tools to perform management operations on these MOP artifacts: site la= yout, pages, and navigation. +
+ = + Resource Paths + The paths of the MOP resources are exactly the same as the= REST URL's (of course without the URL syntax). For example the path of the= homepage for the classic site would be: + + Example + [ /]% cd /mop/portalsites/classic/pages/homepa= ge = [homepage]% pwd /mop/portalsites/classic/pages/homepage - - - Note - All resources/paths can be autocompleted by hitting the ta= b key. - + + + Note + All resources/paths can be autocompleted by hitting the = tab key. + +
+
+ = + Export and Filtering + + Filtering is activated when the + filter + attribute is passed to an + export-resource + operation. The filter attribute is a multi-value attribute tha= t is passed to the CLI using the + --filter + attribute for the + export + command. + + + Export all portal site types + export --file /tmp/mop.zip --filter site-type:= portal /mop + + + Export all sites types but user + export --file /tmp/mop.zip --filter site-type:= !user /mop + + The option can be specified multiple times for multiple va= lues. + + Export only the /platform/administrators group site</ti= tle> + <programlisting>export --file /tmp/mop.zip --filter site-type:= group --filter site-name:/platform/administrators /mop</programlisting> + </example> + <para> + Also as discussed in the Path Templates section in this docume= nt, the filter attribute can separate different path templates by the + <code>;</code> + character. + </para> + <example> + <title>Export only pages named homepage, navigation named home= for site classic + export --file /tmp/classic.zip --filter page-n= ame:homepage;nav-uri:home /mop/portalsites/classic + + + Important + All three artifacts (site layout, navigation, and pages)= are included in export by default. In other words if you don't specify the= ir path template in the filter, the data will be included. + +
-
- = - Export and Filtering - - Filtering is activated when the - filter - attribute is passed to an - export-resource - operation. The filter attribute is a multi-value attribute that = is passed to the CLI using the - --filter - attribute for the - export - command. - - - Export all portal site types - export --file /tmp/mop.zip --filter site-type:po= rtal /mop - - - Export all sites types but user - export --file /tmp/mop.zip --filter site-type:!u= ser /mop - - The option can be specified multiple times for multiple valu= es. - - Export only the /platform/administrators group site</titl= e> - <programlisting>export --file /tmp/mop.zip --filter site-type:gr= oup --filter site-name:/platform/administrators /mop</programlisting> - </example> - <para> - Also as discussed in the Path Templates section in this document= , the filter attribute can separate different path templates by the - <code>;</code> - character. - </para> - <example> - <title>Export only pages named homepage, navigation named home f= or site classic - export --file /tmp/classic.zip --filter page-nam= e:homepage;nav-uri:home /mop/portalsites/classic - - - Important - All three artifacts (site layout, navigation, and pages) a= re included in export by default. In other words if you don't specify their= path template in the filter, the data will be included. - -
Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Book_Info.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/Developer_Guide/en-US/Book_Info.xml 2011-11-24 17= :26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Developer_Guide/en-US/Book_Info.xml 2011-11-25 00= :43:12 UTC (rev 8139) @@ -1,23 +1,12 @@ - - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; -]> + + Developer Guide For use with JBoss Enterprise Portal Platform 5 JBoss Enterprise Portal Platform 5.2 5.2.0 - 4 + 5 This guide is intended to assist developers working with JBoss= Enterprise Portal Platform. It assumes a high level of technical knowledge. Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Preface.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/Developer_Guide/en-US/Preface.xml 2011-11-24 17:2= 6:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Developer_Guide/en-US/Preface.xml 2011-11-25 00:4= 3:12 UTC (rev 8139) @@ -1,21 +1,11 @@ - - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; -]> + + + - Preface - - - - + Preface + + + + = Modified: epp/docs/branches/5.2/Developer_Guide/en-US/Revision_History.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/Developer_Guide/en-US/Revision_History.xml 2011-1= 1-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Developer_Guide/en-US/Revision_History.xml 2011-1= 1-25 00:43:12 UTC (rev 8139) @@ -1,21 +1,25 @@ - - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; - -%BOOK_ENTITIES; -]> + + + Revision History + 5.2.0-5 + Friday Nov 25 2011 + + Scott + Mumford + + + + + Staged with updated content. + + + + 5.2.0-4 Tue Nov 15 2011 Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Author_Gr= oup.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-eXoJCR-1.14/en-US/Author_Group.xm= l 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Author_Group.xm= l 2011-11-25 00:43:12 UTC (rev 8139) @@ -4,54 +4,64 @@ %BOOK_ENTITIES; ]> - - Luc - Texier - - Red Hat - JBoss Engineering + + Luc + Texier + + Red Hat + JBoss Engineering = - + = - - - Thomas - Heute - - Red Hat - JBoss Engineering + + + Thomas + Heute + + Red Hat + JBoss Engineering = - + = - - - Wesley - Hales - - Red Hat - JBoss Engineering + + + Wesley + Hales + + Red Hat + JBoss Engineering = - + = - - - Scott - Mumford - - Red Hat - Engineering Content Services + + + Chris + Laprun + + Red Hat + JBoss Engineering = - + = - - - - GateIn and <= ulink type=3D"http" url=3D"http://www.exoplatform.com">eXo Platform= - Documentation Teams + + + Scott + Mumford + + Red Hat + Engineering Content Services = - - Based on original product documentation by: + = - + + + + GateIn and eXo Platf= orm + Documentation Teams + + + Based on original product documentation by: + + = Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Book_Info= .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-eXoJCR-1.14/en-US/Book_Info.xml 2= 011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Book_Info.xml 2= 011-11-25 00:43:12 UTC (rev 8139) @@ -4,30 +4,30 @@ %BOOK_ENTITIES; ]> - Reference Guide eXo JCR 1.14 - An in-depth guide to Enterprise Portal Platform &VZ; - JBoss Enterprise Portal Platform - 5.2 - 5.2.0 - 7 - - - This Reference Guide is a high-level usage document. It deals with more= advanced topics than the Installation and User Guides, adding new content = or taking concepts discussed in the earlier documents further. It aims to p= rovide supporting documentation for advanced users of the JBoss Enterprise = Portal Platform product. Its primary focus is on advanced use of the produc= t and it assumes an intermediate or advanced knowledge of the technology an= d terms. - + Reference Guide eXo JCR 1.14 + An in-depth guide to Enterprise Portal Platform &VZ; + JBoss Enterprise Portal Platform + 5.2 + 5.2.0 + 9 + + + This Reference Guide is a high-level usage document. It deals = with more advanced topics than the Installation and User Guides, adding new= content or taking concepts discussed in the earlier documents further. It = aims to provide supporting documentation for advanced users of the JBoss En= terprise Portal Platform product. Its primary focus is on advanced use of t= he product and it assumes an intermediate or advanced knowledge of the tech= nology and terms. + = - - - - - - + + + + + + = - + = - - <= !-- FOR JDOCBOOK: --> - - - + + + + + = Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Revision_= History.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-eXoJCR-1.14/en-US/Revision_Histor= y.xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/Revision_Histor= y.xml 2011-11-25 00:43:12 UTC (rev 8139) @@ -4,138 +4,168 @@ %BOOK_ENTITIES; ]> - Revision History - - - - 5.2.0-6 - Thu Nov 17 2011 - - Scott - Mumford - + Revision History + + + + 5.2.0-9 + Fri Nov 25 2011 + + Scott + Mumford + + + + + Ported latest community WSRP content. + + + + + 5.2.0-8 + Thu Nov 24 2011 + + Scott + Mumford + + + + + Finalized first edit pass of eXoJCR conten= t. + Moved eXoJCR section to Part IV. + Clean element ids and fix broken linkends.= + + + + + 5.2.0-6 + Thu Nov 17 2011 + + Scott + Mumford + = - - - - Incorporated GateIn SSO updates. + + + + Incorporated GateIn SSO updates. = - + = - + = - - - 5.2.0-5 - Tue Nov 15 2011 - - Scott - Mumford - + + + 5.2.0-5 + Tue Nov 15 2011 + + Scott + Mumford + = - - - - Staging for beta release. + + + + Staging for beta release. = - + = - + = - - - 5.2.0-4 - Wed Nov 9 2011 - - Scott - Mumford - + + + 5.2.0-4 + Wed Nov 9 2011 + + Scott + Mumford + = - - - - Republished for review/feedback. + + + + Republished for review/feedback. = - + = - + = - - - 5.2.0-3 - Wed Nov 2 2011 - - Scott - Mumford - + + + 5.2.0-3 + Wed Nov 2 2011 + + Scott + Mumford + = - - - - Staged for review of updated Foundations and eXo JCR content= . + + + + Staged for review of updated Foundations a= nd eXo JCR content. = - + = - + = - - - 5.2.0-2 - Tue Sep 27 2011 - - Scott - Mumford - + + + 5.2.0-2 + Tue Sep 27 2011 + + Scott + Mumford + = - - - - Incorporated eXo JCR 1.14 documentation. + + + + Incorporated eXo JCR 1.14 documentation. = - + = - + = - - - 5.2.0-5 - Wed Sep 14 2011 - - Scott - Mumford - + + + 5.2.0-5 + Wed Sep 14 2011 + + Scott + Mumford + = - - - - Added Global Portlet Data section. + + + + Added Global Portlet Data section. = - + = - + = - - - 5.2.0-1 - Mon Aug 29 2011 - - Scott - Mumford - + + + 5.2.0-1 + Mon Aug 29 2011 + + Scott + Mumford + = - - - - Updating version and resetting pubs/ed numbers. + + + + Updating version and resetting pubs/ed num= bers. = - + = - + = - + = - + = - + = Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WS= RP/config_self.png =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 (Binary files differ) Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WS= RP/modify_reg_end.png =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 (Binary files differ) Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/images/WS= RP/modify_reg_self_end.png =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 (Binary files differ) Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/A= dvanced/Foundations/Configuring_Services.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-eXoJCR-1.14/en-US/modules/Advance= d/Foundations/Configuring_Services.xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Advance= d/Foundations/Configuring_Services.xml 2011-11-25 00:43:12 UTC (rev 8139) @@ -9,13 +9,19 @@ The eXo Kernel uses dependency injection to create services based = on configuration.xml configuration files. The location= of the configuration files determines if services are placed into the RootContainer scope, or into the PortalContainer scope. - When creating a service, you also should declare its existence to = the Container, therefore you create a fi= rst simple configuration file. Copy the following code to a file called "co= nfiguration.xml" and place this file in a /conf subdirectory of your servic= e base folder. As you already know the container looks for a "/conf/configu= ration.xml" file in each jar-file. + When creating a service, you also should declare its existence to = the Container. This fan be done by creat= ing a simple configuration file. + + + Copy the following code to a configuration.xml file and save this file in a /conf subdirectory of = your service base folder. The container looks for a /conf/configu= ration.xml file in each jar-file. - All configuration.xml files located at conf/configuration.xml in the classpath (any directory, or a= ny jar in the classpath) will have their services configured in the RootContainer scope. All configuration.xml= files located at conf/portal/configuration.xml in the= classpath will have their services configured at the PortalContai= ner scope. + All configuration.xml files located at conf/configuration.xml in the classpath (any directory, or a= ny jar in the classpath) will have their services configured in the RootContainer scope. + + + All configuration.xml files located at conf/portal/configuration.xml in the classpath will have th= eir services configured at the PortalContainer scope. - Additionally, portal extensions= can contain configuration in JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02po= rtal.war/WEB-INF/conf/configuration.xml, and will also have thei= r services configured in the PortalContainer scope. + Additionally, portal extensions= can use configuration information stored in JBOSS_H= OME/server/<PROFILE>/deploy/= gatein.ear/02portal.war/WEB-INF/conf/configuration.xml, and will= also have their services configured in the PortalContainer scope. When eXo kernel reads a configuration, it loads the file from the = kernel jar using the classloader and does not use an internet connection to= resolve the file. @@ -45,7 +51,7 @@ = - The configuration you find inside the jar file is consider= ed as the default configuration. If you want to override this default confi= guration you can do it in different places outside the jar. When the contai= ner finds several configurations for the same service, the configuration wh= ich is found later replaces completely the one found previously. Let's call= this the configuration override mechanism. + The configuration found inside the jar file is considered = as the default configuration. If you want to override this default configur= ation you can do it in different places outside the jar. When the container= finds several configurations for the same service, the configuration which= is found later replaces completely the one found previously. Let's call th= is the configuration override mechanism. After deploying you find the configuration.xml file in web= apps/portal/WEB-INF/conf Use component registration tags. Let's look at the= key tag that defines the interface and the type tag that defines the imple= mentation. Note that the key tag is not mandatory, but it improves performa= nce. Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/A= uthenticationAndIdentity/SSO.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-eXoJCR-1.14/en-US/modules/Authent= icationAndIdentity/SSO.xml 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/Authent= icationAndIdentity/SSO.xml 2011-11-25 00:43:12 UTC (rev 8139) @@ -115,7 +115,7 @@ SSO Integration - Open the /<JBOSS_HOME>/server/<PROFILE>/deploy/jbossw= eb.sar/server.xml file and uncomment one of the two V= alve entries: + Open the <JBOSS_HOME>/server/<PROFILE>/deploy/jbosswe= b.sar/server.xml file and uncomment one of the two Va= lve entries: @@ -192,7 +192,7 @@ - Open the <JBOSS_HOME>/server/all/deploy/jbossweb.sar/server.xml file. + Open the <JBOSS_HOME>/server/all/<PROFILE>/jbossweb.s= ar/server.xml file. = @@ -239,13 +239,13 @@ - Go to http://machine1.yourdomain.com:8080/portal = and login as a user. + Go to http://machine1.yourdomain.com:8080/portal<= /uri> and login as a user. = - Access a private URL on the second host, such as = http://machine2.yourdomain.com:8080/portal/dologin, for example. + Access a private URL on the second host, such as = http://machine2.yourdomain.com:8080/portal/dologin, for example. Now you should be logged directly into machin= e2 thanks to SSO valve. @@ -327,13 +327,13 @@ - Navigate to and authenticate with the = pre-configured user account "root" (password "gtn "). + Navigate to http://machine1.yourdomain.com:8080/p= ortal/private/classic and authenticate with the pre-configured user a= ccount "root" (password "gtn "). = - Navigate to . You should be automatically authenti= cated into the JMX Console. + Navigate to http://machine1.yourdomain.com:8080/j= mx-console. You should be automatically authenticated into the JMX Co= nsole. = @@ -849,7 +849,7 @@ OpenSSO must be purchased from Oracle . - For testing purpose, use OpenSSO_80U2, which can be do= wnloaded from Oracle . + For testing purposes, use OpenSSO_80U2, which can be d= ownloaded from Oracle . = Added: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/RH-W= SRP.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-eXoJCR-1.14/en-US/modules/RH-WSRP= .xml (rev 0) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/RH-WSRP= .xml 2011-11-25 00:43:12 UTC (rev 8139) @@ -0,0 +1,2003 @@ + + +%BOOK_ENTITIES; +]> + + <remark>Web Services for Remote Portlets (WSRP)</remark> +
+ Introduction + + The Web Services for Remote Portlets (WSRP) specification defi= nes a web service interface for accessing and interacting with interactive = presentation-oriented web services. + + + It has been produced through the efforts of the Web Services f= or Remote Portlets (WSRP) OASIS Technical Committee. It is based on the req= uirements gathered and the proposals made to the committee. + + + Scenarios that motivate WSRP functionality include: + + + + + Content hosts, such as portal servers, providing Portl= ets as presentation-oriented web services that can be used by aggregation e= ngines. + + + + + + Aggregating frameworks, including portal servers, cons= uming presentation-oriented web services offered by content providers and i= ntegrating them into the framework. + + + + + + + More information on WSRP can be found on the official we= bsite. We suggest reading the primer for a= good, albeit technical, overview of WSRP. + + +
+ = +
+ Level of Support + + The WSRP Technical Committee defined WSRP Use Profiles to h= elp with WSRP interoperability. Terms defined in that document will be used= in this section. + + + JBoss Enterprise Portal Platform provides a Simple level of support for the WSRP Producer, with the exception of out= -of-band registration. In-band registration and persistent local state (whi= ch are defined at the Complex level) are supported. + + + JBoss Enterprise Portal Platform provides a Medium level of support for the Consumer, excepting HTML markup (as JBos= s Enterprise Portal Platform itself does not handle other markup types). Ex= plicit portlet cloning and the PortletManagement interfa= ce are supported. + + + The WSRP component has Level 1 Producer and Consumer caching. = Cookie handling is supported properly on the Consumer. The Producer require= s cookie initialization (as this improves interoperability with some consum= ers). + + + JBoss Enterprise Portal Platform does not support custom windo= w states or modes, therefore neither does the WSRP component. It does, howe= ver, support CSS on both the Producer (although this is more a function of = the portlets than an inherent Producer capability) and Consumer. + + + JBoss Enterprise Portal Platform &VY; includes implementations= of WSRP 1.0 and 2.0. + + + All optional features in WSRP 2 are implemented in JBoss Enter= prise Portal Platform &VY; except support for lifetimes and leasing support. + + + + As of version &VZ; of Enterprise Portal Platform, WSRP is = only activated and supported when deployed on JBoss Enterprise Application = Server. + + + + +
+ = +
+ Deploying WSRP + + Notational Devices + + The following list of support files uses the following not= ational devices: + + + Notations: + + JBOSS_HOME + + + JBOSS_HOME refers t= o the directory that your instance of JBoss Enterprise Portal Platform has = been extracted/installed to. For example: /home/USER= NAME/jboss-epp-<VERSION>/ + + + + + + + WSRP_PATH + + + The WSRP files referred to in this section are= found in the JBOSS_HOME/jboss-as/serv= er/<PROFILE>/deploy/gatein.ear = directory. + + + For ease of reference this path will be repres= ented by: WSRP_PATH. + + + + + + + WSRP_VERSION + + + WSRP_VERSION repres= ents the version of the WSRP component in use. + + + + + + + PORTAL_VERSION + + + PORTAL_VERSION repr= esents the version of JBoss Enterprise Portal Platform in use. + + + + + + + + + + + Starting with version 2.1.0-GA of the component, WSRP is packa= ged as a JBoss Enterprise Portal Platform extension and is now self-contain= ed in an easy to install package named gatein-wsrp-integration.ea= r, deployed directly in the deploy director= y of your JBoss Application Server configuration directory. + + + The extension itself is composed of the following components: + + + WSRP support files + + META-INF/ + + + This directory contains files necessary for EAR pa= ckaging. The only file that is of interest from a user perspective is gatein-wsse-consumer.xml which allows you to configure WS-S= ecurity support for the consumer. + + + Refer to section for mo= re details. + + + + + + + extension-component-$PORTAL_VERSION.jar + + + This archive which contains the components needed = to integrate the WSRP component into JBoss Enterprise Portal Platform. It a= lso includes the default configuration files for the WSRP producer and the = default WSRP consumers. + + + + + + + extension-config-$PORTAL_VERSION.jar + + + This file contains the configuration file needed b= y the GateIn extension mechanism to properly register this EAR as an extens= ion. + + + + + + + extension-war-$PORTAL_VERSION.war + + + This file contains the configuration files needed = by the GateIn extension mechanism to properly setup the WSRP service. It in= cludes wsrp-configuration.xml which, in particular, co= nfigures several options for the WSRPServiceIntegration comp= onent at the heart of the WSRP integration in JBoss Enterprise Portal Platf= orm. + + + + + + + lib/ + + + This directory contains the different libraries ne= eded by the WSRP service. + + + + + + + wsrp-admin-gui-$WSRP_VERSION.war + + + This file contains the WSRP Configuration portlet = with which you can configure consumers to access remote servers and how the= WSRP producer is configured. + + + + + + + wsrp-producer-jb5wsss-$WSRP_VERSION.war + + + This file contains the producer-side support for W= S-Security. The only file of interest from a user perspective is = gatein-wsse-producer.xml which allows you to configure WS-Securi= ty support for the producer. + + + Refer to for more detai= ls. + + + + + + + +
+ Non-default Ports or Hostnames + + JBoss WS (the web service stack that JBoss Enterprise Port= al Platform uses) should update the port and host name used in WSDL. Refer = to the JBoss WS user guide for more information. + + + If the host name and port on which the server runs have be= en modified, the configuration for the Consumer used to consume JBoss Enter= prise Portal Platform's "self" Producer will need to be updated. Refer to <= xref linkend=3D"sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_P= ortlets_WSRP-Consuming_Remote_WSRP_Portlets" /> for directions on how to do= this. + + +
+ = +
+ Using WSRP with SSL + + It is possible to use WSRP over SSL for secure exchange of= data. Refer to these instructions for how to do this. + + +
+ = + +
+ = +
+ WSRP and WS-Security + + Portlets may present different data or options depending on th= e currently authenticated user. For remote portlets, this means having to p= ropagate the user credentials from the consumer back to the producer in a s= afe and secure manner. + + + The WSRP specification does not directly specify how this shou= ld be accomplished, but delegates this work to the existing WS-Security sta= ndards. + + + 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 + + The use of encryption is strongly = recommended. + + + Credentials being sent between the consumer and producer s= hould be encrypted or they will be sent in plain text and could be easily i= ntercepted. + + + You can either configure WS-Security to encrypt and sign t= he SOAP messages being sent, or secure the 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. + + + + + Credentials + + When the consumer sends the user credentials to the produc= er, it is sending the credentials for the currently authenticated user in t= he consumer. This makes signing in to remote portlets transparent to end us= ers, but also requires that the producer and consumer use the same credenti= als. + + + The username and password must be the same and valid on bo= th servers. + + + The recommended approach for this situation would be to us= e a common LDAP configuration. Please see the User Guide at for information on how to configure LDAP f= or use with JBoss Enterprise Portal Platform + + + + + This community Wiki article, 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 handle ws-security. + + + Refer to the WS-Security section of the JBoss AS 5 Administration and Configurat= ion Guide for in-depth configuration options. + + + Please note that since the consumer passes its credentials= to the producer, the consumer will act at the wss client and the producer = will act as the wss server. + + + The following are the JBossWS Native configuration files w= hich need to be configure for WSRP: + + + + + gatein-wsrp-integration.ear/META-INF/gatein-wsse= -consumer.xml + + + BossWS 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, n= o other configuration changes should be necessary for the producer. + + +
+ = +
+ WS-Security Consumer Configuration + + The consumer requires some changes before it will function= properly with WS-Security. + + + The consumer needs access to the current servlet request s= ince this is used to retrieve the currently authenticated user. In order to= access this information, the consumer needs a special servlet-filter added= to the portal. + + + Add the servlet-filter + + + Open <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.= ear/02portal.war/WEB-INF/web.xml and add the following: + + = +<!-- Filter to put request and response in= ServletAccess --> + <filter> + <filter-name>ServletAccessFilter</filter-name> + <filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</= filter-class> + </filter> + <filter-mapping> + <filter-name>ServletAccessFilter</filter-name> + <url-pattern>/*</url-pattern> + </filter-mapping> + + + + + + Check the Enable WS Security = checkbox in the consumer configuration options of the WSRP Configuration po= rtlet + + + + + + + + + + = + +
+ = +
+ WS-Security Consumer Checklist + + In order for the consumer to handle ws-security, the follo= wing items must be implemented: + + + + + 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 a= ll three items are correctly configured. + + +
+ +
+ = +
+ Making a Portlet Remotable + + + Only JSR-286 (Portlet 2.0) portlets can be made remotable = as the mechanism to expose a portlet to WSRP relies on a JSR-286-only funct= ionality. + + + + + 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<= /filename>. + + + A specific org.gatein.pc.remotable container-runtime-opt= ion is used to accomplish this. Setting its value to true makes the portlet available for remote consumption, while setting its va= lue to false will not publish it remotely. + + + As specifying the remotable status for a portlet is optional, = nothing need be done if portlets do not need to be remotely available. + + + In the following example, the "BasicPortlet" portlet is specif= ied as being remotable. + + = + + + It is also possible to specify that all the portlets declared = within a given portlet application be remotable by default. + + + This is done by specifying the container-runtime-option<= /code> at the portlet-app element level. Individual portlets c= an override that value to not be remotely exposed. + + + For example: + + = + + + This example defines two portlets. As the org.gatein.pc.= remotable container-runtime-option is set to true at th= e portlet-app level, all portlets defined in this particular p= ortlet application are exposed remotely by JBoss Enterprise Portal Platform= 's WSRP Producer. + + + It is possible to override this default behavior. 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 the org.gatein.pc.remota= ble container-runtime-option. + + + The NotRemotelyExposedPortlet, however, ove= rrides the default behavior and is not remotely exposed. + + + Note + + Portlets are not remotely exposed if no top-level or= g.gatein.pc.remotable container-runtime-option value is set to true. + + + + +
+ = +
+ Consuming WSRP portlets from a remote Consumer + + Configuration is extremely variable between different WSRP Con= sumers. Most, however, require a specification of the URL for the Producer'= s WSDL definition. If the JBoss Enterprise Portal Platform Consumer is not = being used, refer to the documentation for the Consumer that is in use for = specific instructions. + + + For instructions on how to specify this URL in JBoss Enterpris= e Portal Platform, refer to . + + + JBoss Enterprise Portal Platform's Producer is automatically s= et up when a portal instance is deployed with the WSRP service. + + + The WSDL file can be accessed at: + + + File paths: + + WSRP 1.0: + + + http://{hostname}:{port}/wsrp-producer/v1/MarkupService?wsdl<= /filename>. + + + + + + + WSRP 2.0: + + + http://{hostname}:{port}/wsrp-producer/v2/MarkupService?wsdl<= /filename>. + + + + + + + + + The default hostname is localhost and the d= efault port is 8080. + + +
+ = +
+ Consuming Remote WSRP Portlets +
+ Overview + + To be able to consume WSRP portlets exposed by a remote pr= oducer, JBoss Enterprise Portal Platform's WSRP consumer must be configured= to access that remote producer. + + + Access to a remote producer can be configured using the pr= ovided configuration portlet. Alternatively, it is also possible to configu= re access to remote producers using an XML descriptor. The configuration po= rtlet is the recommended method. + + + Once a remote producer has been configured, the portlets t= hat it exposes are then available in the Application Registry to be added t= o categories and then to pages. + + +
+ = +
+ Configuring a Remote Producer + + Access to a remote producer needs to be defined so that po= rtlets can be consumed within JBoss Enterprise Portal Platform. This sectio= n will show how to configure access to NetUnity's public WSRP producer. + + + Firstly using the configuration portlet and then how the s= ame result can be accomplished with a producer descriptor, though it is far= easier to do so via the configuration portlet. + + + Chunked Encoding + + Some WSRP producers, such as Oracle, do not support ch= unked encoding. If your producer does not support chunked encoding, it will= not be able to properly connect to the producer. + + + This will manifest itself with the following error: + + = +Caused by: org.jboss.ws.WSException: Invalid HTTP server response = [503] - Service Unavailable. + + + A workaround for this issue involves editing the chunksize setting in the standard-jaxws-client-= config.xml file. + + + Refer to http://communit= y.jboss.org/wiki/Workaroundwhenchunkedencodingisnotsupported for mo= re information. + + + +
+ The Configuration Portlet + + JBoss Enterprise Portal Platform provides a graphical = portlet to assist with configuring access to, and other facets of, remote W= SRP Producers. + + + It is available at: . + + + The portlet also is a group page for /platform/adminis= trators + + + Although the Configuration Portlet is installed by def= ault in JBoss Enterprise Portal Platform &VY;., installation instructions a= re included below should the portlet ever need to be re-installed: + + + <emphasis role=3D"bold">Installing the configur= ation portlet:</emphasis> + + + Log into the portal as an administrator and go= to the Application Registry (Click http://localhost:8080/portal/p= rivate/classic/administration/registry if using the default install= ation). + + + + + + Add the WSRP Configuration portlet to the Admi= nistration category. If the Import Applications functionality is used, the = WSRP Configuration portlet will be automatically added to the Administratio= n category. + + + + + + Once the portlet is added to a category, it ca= n be added to a page and used. It is recommended that it be added to the sa= me page as the Application Registry (as other operations relating to WSRP a= nd adding portlets to categories are somewhat related). Add the WSRP Config= uration portlet to the page using the standard procedure. + + + + + + = +
+ <emphasis role=3D"bold">Using the Configuration= portlet</emphasis> + + + + + + + + + + + This screen presents all the configured consumers = associated 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 portlet provider. + + + Note also that a Consumer can be marked as requiri= ng refresh, which means that the information held abou= t it might not be up to date. Refreshing it from the remote Producer will u= pdate this information. + + + This can happen for several reasons: the service d= escription for that remote Producer has not been fetched yet, the cached ve= rsion has expired or modifications have been made to the configuration that= could potentially invalidate it, thus requiring re-validation of the infor= mation. + + + To create a new Consumer: + + + <emphasis role=3D"bold">Creating a Consumer= </emphasis> + + + Type "netunity" into th= e "Create a consumer named:" field. + + + + + + Click on "Create c= onsumer" to create a new Consumer called netunity. + + + + + + + + + + + + + + + In the next form, set the cache expiration= value to 300 seconds. + + + + + + Leave the default timeout value for web se= rvices (WS) operations. + + + + + + Enter the WSDL URL for the producer in the= text field. + + + + + + Press the "Refresh & Save" button: + + + + + + + + + + + + + + + = + + This will retrieve the service description associa= ted with the Producer which WSRP interface is described by the WSDL file fo= und at the URL entered. + + + In this case, querying the service description wil= l show that the Producer requires registration, that it requested three reg= istration properties and that the current configuration is missing values f= or these properties: + + + + + + + + + + + + This particular producer requests simple = Yes or No values for the three registration pr= operties. + + + Enter No, Yes and No (in that order) for the values and then pressin= g the "Refresh & Save" button should result in: + + + + + + + + + + + + Values + + Unfortunately there is no automated way to lea= rn about which possible values (if any) are expected by the remote Producer= . Possible values may be indicated in the registration property description= but this is not always the case. Refer to the specific Producer's document= ation. + + + + + The Consumer for the netunity P= roducer should now be available as a portlet provider and be ready to be us= ed. + + + If the producer had required registration but did = not require any registration properties, as is the case for the se= lfv2 consumer (the consumer that accesses the portlets made remot= ely available by JBoss Enterprise Portal Platform's producer via WSRP 2), t= he following screen would have appeared after pressing the "Refresh & S= ave" button: + + + + + + + + + + + +
+ = + +
+ = +
+ Using XML + + Although using the WSRP Configuration portlet to confi= gure Consumers is recommended, the WSRP component provides an alternative w= ay to configure consumers. + + + This is done by editing the <= ;JBOSS_HOME>/server/<PROFILE>/conf/gatein/wsrp-consumers-config.xml XML file. + + + XML Elements + + An XML Schema defining which elements are availabl= e to configure Consumers via XML can be found in WSR= P_PATH/lib/wsrp-integration-api-WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd + + + + + The Consumer Configuration file + + It is important to understand how the XML Consumer= s configuration file is processed. It is read the first time the WSRP servi= ce starts and the associated information is then put under control of the J= CR (Java Content Repository). + + + + + Subsequent launches of the WSRP service will use the J= CR-stored information for all producers that are already known to JBoss Ent= erprise Portal Platform. More specifically, the wsrp-consumers-co= nfig.xml file is scanned for producer identifiers. Any identifie= r that is already known will be bypassed and the JCR information associated= with this remote producer will be used. + + + The information defined at the XML level is only proce= ssed for producer definition for which no information is already present in= the JCR. + + + Therefore, to delete a Producer configuration, the ass= ociated information in the database must be deleted (this can be accomplish= ed using the configuration portlet as shown in ). + + + The associated information in wsrp-consumers= -config.xml (if such information exists) must also be removed, o= therwise the producer will be re-created the next time the WSRP is launched. + +
+ Required Configuration Information + + The following information needs to be provided to = configure access to a remote Producer: + + + + + An identifier must be provided for the pro= ducer being configured so that it can be referred to later. This is done in= the mandatory id attribute of the <wsrp-pro= ducer> element. + + + + + + JBoss Enterprise Portal Platform also need= s to know about the remote Producer's endpoints to be able to connect to th= e remote web services and perform WSRP invocations. Use the <en= dpoint-wsdl-url> element to specify the URL for the WSDL descr= iption of the remote WSRP service. + + + + + + + Both the id attribute and <endpoint-wsdl-url> elements are required for a functio= nal remote producer configuration. + + +
+ = +
+ Optional Configuration + + It is also possible to provide additional configur= ation, which, in some cases, might be important to establish a proper conne= ction to the remote producer. + + + Optional Configurations + + Caching + + + To prevent unnecessary traffic between= the local consumer and the remote producer, it is possible to cache some o= f the information sent by the producer (such as the list of offered portlet= s) for a given duration. + + + The rate at which the information is r= efreshed is defined by the expiration-cache attribute of= the <wsrp-producer> element (in seconds). + + + For example; providing a value of 120 for expiration-cache means that the producer information= will not be refreshed for 2 minutes after it has been 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 informat= ion provided by the producer does not change often, use of this caching fac= ility to minimize bandwidth usage is recommended. + + + + + + + WS Timeout + + + It is also possible to define a timeou= t after which WS operations are considered as failed. This is helpful to av= oid blocking the WSRP service, as it waits on a service that does not answe= r. + + + Use the ws-timeout = attribute of the <wsrp-producer> element to specif= y how many milliseconds the WSRP service will wait for a response from the = remote producer before timing out. + + + + + + + Pre-registration information + + + Some producers require consumers to re= gister with them before authorizing them to access their offered portlets. = If known, some registration information can be provided in the producer con= figuration beforehand, so that the consumer can register with the remote pr= oducer when required. + + + + Only simple String properties are = supported. It is not possible to configure complex registration data. Howev= er, this should be sufficient for most cases. + + + + + This pre-registration configuration is= done via the <registration-data> element. + + + If the remote producer does not requir= e any registration properties, only an empty <registration-data= > element need be provided, as JBoss Enterprise Portal Platfor= m can generate the mandatory information. + + + Values for the registration properties= required by the remote producer can be provided via <property&= gt; elements. Refer to the example below for more details. + + + Additionally, the default consumer nam= e automatically provided by JBoss Enterprise Portal Platform can be overrid= den via the <consumer-name> element. When providin= g a consumer name, please remember that it should uniquely identify your co= nsumer. + + + + + + + + +
+ = + +
+ = +
+ Examples + + This is the configuration of the selfv1 and selfv2 consumers as found in default-= wsrp.xml with a cache expiring every 500 seconds and with a 50 s= econd timeout for web service operations: + + + + This file contains the default configuration and s= hould not need to be edited. If modifications are required, the recommended= practice is to follow the procedure detailed in . + + + + = + + + This is an example of a WSRP descriptor with registrat= ion data and cache expiring every minute: + + = + + +
+ = + +
+ = +
+ Adding remote portlets to categories + + Clicking on the Portlet link in the Application Registry w= ill now show the remote portlets in the REMOTE tab in the left column: + + + + + + + + + + + + These portlets are available to be used as regular portlet= s: they can be used in categories and added to pages. Using the Import Appl= ications functionality will also automatically import them into categories = based on the keywords they define. + + + More specifically, to add a WSRP port= let to a category, select wsrp in the Application Type d= rop-down menu: + + + + + + + + +
+ = + +
+ = +
+ Consumers Maintenance +
+ Modifying a Currently Held Registration +
+ Registration Modification for Service Upgrade</titl= e> + <para> + Producers often offer several levels of service depend= ing on consumers' subscription levels (for example). This is implemented at= the WSRP level with the registration concept: producers can assert which l= evel of service to provide to consumers based on the values of given regist= ration properties. + </para> + <para> + There may also be cases where the registration informa= tion has changed and must be updated. For example, the producer required yo= u to provide a valid email and the previous email address is not valid anym= ore and needs to be updated. + </para> + <para> + Therefore at times it may be necessary to modify the r= egistration that sets the service agreement between a consumer and a produc= er. + </para> + <para> + For example; the producer requiring an email that was = configured in <xref linkend=3D"sect-Reference_Guide_eXo_JCR_1.14-Configurin= g_a_Remote_Producer-The_Configuration_Portlet" /> . In that case the produc= er was requiring registration and required a value to be provided for the <= literal>email</literal> property. + </para> + <para> + To update the email address that was provided, the rem= ote producer must be informed that some registration data has been modified. + </para> + <para> + The following procedure assumes access to the producer= has been configured as previously described. + </para> + <procedure> + <step> + <para> + Go to the configuration screen for the <litera= l>self</literal> producer and change the value of <literal>email</literal> = to <literal>foo(a)example.com</literal> instead of <literal>example(a)examp= le.com</literal>: + </para> + <mediaobject> + <imageobject role=3D"html"> + <imagedata align=3D"center" fileref=3D"ima= ges/WSRP/modify_reg_start.png" format=3D"PNG" scale=3D"100" width=3D"444" /> + </imageobject> + <imageobject role=3D"fo"> + <imagedata align=3D"center" contentwidth= =3D"140mm" fileref=3D"images/WSRP/modify_reg_start.png" format=3D"PNG" widt= h=3D"444" /> + </imageobject> + + </mediaobject> + + </step> + <step> + <para> + Click on "<emphasis role=3D"bold">Update prope= rties</emphasis>" to save the change. A "<emphasis role=3D"bold">Modify reg= istration</emphasis>" button should now appear to let you send this new dat= a to the remote producer: + </para> + <mediaobject> + <imageobject role=3D"html"> + <imagedata align=3D"center" fileref=3D"ima= ges/WSRP/modify_reg_modify.png" format=3D"PNG" scale=3D"100" width=3D"444" = /> + </imageobject> + <imageobject role=3D"fo"> + <imagedata align=3D"center" contentwidth= =3D"140mm" fileref=3D"images/WSRP/modify_reg_modify.png" format=3D"PNG" wid= th=3D"444" /> + </imageobject> + + </mediaobject> + + </step> + <step> + <para> + Click on <emphasis role=3D"bold">Modify regist= ration</emphasis> and, if the updated registration details have been accept= ed by the remote producer the following should appear: + </para> + <mediaobject> + <imageobject role=3D"html"> + <imagedata align=3D"center" fileref=3D"ima= ges/WSRP/modify_reg_end.png" format=3D"PNG" scale=3D"120" width=3D"444" /> + </imageobject> + <imageobject role=3D"fo"> + <imagedata align=3D"center" contentwidth= =3D"140mm" fileref=3D"images/WSRP/modify_reg_end.png" format=3D"PNG" width= =3D"444" /> + </imageobject> + + </mediaobject> + + </step> + + </procedure> + = + + </section> + = + <section id=3D"sect-Reference_Guide_eXo_JCR_1.14-Modifying_a_= Currently_Held_Registration-Registration_Modification_on_Producer_Error"> + <title>Registration Modification on Producer Error + + If a Producer administrator changes the requirements f= or registered consumers, invoking operations on the producer may fail with = an OperationFailedFault. JBoss Enterprise Po= rtal Platform will attempt to assist in these cases. + + + This section will discuss an example using the self producer. + + + Assuming that the registration requires a valid value = for an email registration property (as has been shown) t= he configuration screen for this producer should show: + + + + + + + + + + + + If the administrator of the producer now requires an a= dditional value to be provided for a name registration p= roperty operations with this producer will fail. + + + If a registration modification is required, go to the = configuration screen for this remote producer and refresh the information h= eld by the consumer by pressing "Refresh & Save= ": + + + + + + + + + + + + The configuration screen now shows the currently held = registration information and the expected information from the producer. + + + Enter a value for the name property= and then click on "Modify registration"= . If the producer accepts the new registration data, the following screen w= ill appear: + + + + + + + + + + + + <emphasis role=3D"bold">JBoss Enterprise Portal= Platform &VY; and WSRP 1 Exceptions</emphasis> + + In WSRP 1, it can be difficult to ascertain what c= aused an OperationFailedFault as it is a g= eneric exception returned by producers during a failed method invocation. + + + An OperationFailedFault failure can be caused by several different reasons, one of them being = a request to modify the registration data. + + + In these instances examining the log files may ass= ist in gathering more information about the problem. + + + WSRP 2 introduces an exception that is specific to= a request to modify registrations which reduces the ambiguity that current= ly exists. + + + + +
+ = + +
+ = +
+ Consumer Operations + + Several operations are available from the consumer list vi= ew of the WSRP configuration portlet: + + + + + + + + + + + + The available operations are: + + + + Configure + + + Displays the consumer details and allows user = to edit them. + + + + + + + Refresh + + + Forces the consumer to retrieve the service de= scription from the remote producer to refresh the local information (such a= s offered portlets, registration information). + + + + + + + Activate/Deactivate + + + Activates or deactivates a consumer, governing= whether it will be available to provide portlets and receive portlet invoc= ations. + + + + + + + Register/De-register + + + Registers or de-registers a consumer based on = whether registration is required and/or acquired. + + + + + + + Delete + + + Destroys the consumer, after de-registering it= if it was registered. + + + + + + + + + <emphasis role=3D"bold">Additional Functionalities = in WSRP 2.0</emphasis> + + In addition to those listed above, the WSRP 2.0 implem= entation in JBoss Enterprise Portal Platform &VY; also includes the followi= ng functions: + + + + + Additional Functions: + + Export + + + Exports some or all of the consumer's portlets= to be able to later import them in a different context + + + + + + + Import + + + Imports some or all of previously exported por= tlets. + + + + + + + +
+ <emphasis role=3D"bold">Importing and Exporting Por= tlets</emphasis> + + Import and export are new functionalities added in WSR= P 2. + + + Exporting a portlet allows a consumer to get an opaque= representation of the portlet which can then be use by the corresponding i= mport operation to reconstitute it. + + + This is mostly used in migration scenarios during batc= h operations. Since JBoss Enterprise Portal Platform does not currently sup= port automated migration of portal data, the functionality provided as part= of WSRP 2 is necessarily less complete than it could be with full portal s= upport. + + + The import/export implementation in JBoss Enterprise P= ortal Platform allows users to export portlets from a given consumer and th= en import them back to replace existing portlets assigned to windows on pag= es by the previously exported portlets. + + + + + + Click on the "Export" act= ion for a given consumer to display the list of portlets currently made ava= ilable by this specific consumer. An example list is shown below: + + + + + + + + + + + + + + + Once portlets have been selected, they can be = exported by clicking on the "Export" button. This make= s them available for later import: + + + + + + + + + + + + + + + The portlets can be re-imported directly by pr= essing the "Use for import" button or, on the Consumer= s list page, using the "Import" action for a given con= sumer. + + + The example below assumes that the second opti= on has been used and that several sets of previously exported portlets are = available to import from. After clicking the action link, a screen similar = to the one below should appear: + + + + + + + + + + + + This screen presents the list of available exp= orts with available operations for each. + + + Operations: + + View + + + Displays the export details as pre= viously seen when the export was first performed. + + + + + + + Delete + + + Deletes the selected export, askin= g you for confirmation first. + + + + + + + Use for import + + + Selects the export to import portl= ets from. + + + + + + + + + + + + Once you have selected an export to import fro= m, you will see a screen similar to the one below: + + + + + + + + + + + + The screen displays the list of available expo= rted portlets for the previously selected export. You can select which port= let you want to import by checking the checkbox next to its name. + + + + + + Select the content of which window the importe= d portlet will replace. This process is done in three steps: + + + This example assumes that you have the followi= ng page called page1 which contains two windows called <= literal>NetUnity WSRP 2 Interop - Cache Markup (remote) and /samples-remotecontroller-portlet.RemoteControl (remote), as = shown below: + + + + + + + + + + + + In this example, we want to replace the conten= t of the /samples-remotecontroller-portlet.RemoteControl (remote)<= /literal> with the content of the /ajaxPortlet.JSFAJAXPortlet portlet that was previously exported. + + + + + + Check the box next to the /aj= axPortlet.JSFAJAXPortlet portlet name to indicate that you want t= o import its data. + + + + + + Select page1 in the= list of available pages. The screen will then refresh to display the list = of available windows on that page, similar to the image below: + + + + + + + + + + + + Note + + At this point, you still need to s= elect which window content you want to replace before being able to complet= e the import operation + + + + + + + + Select the /samples-remotecon= troller-portlet.RemoteControl (remote) window, which enables the = "Import" button. This indicates that all the necessary= data to perform the import is available. + + + + + + Click the "Import= " button. A screen similar to the one below will appear: + + + + + + + + + + + + + + + = + + + + + The page1 page should now s= how that the content of /samples-remotecontroller-portlet.RemoteCo= ntrol (remote) window has been replaced by the content of the /ajaxPortlet.JSFAJAXPortlet imported portlet and that the w= indow has been renamed appropriately. + + + + + + + + + + + + + + + = + +
+ = + +
+ = +
+ Erasing Local Registration Data + + In rare cases, it may be necessary to erase the local data= without being able to de-register first. + + + This can occur when a consumer is registered with a produc= er that has been modified by its administrator to not require registration = any longer. + + + In this scenario, local registration information can be er= ased from the consumer to allow it to resume interacting with the remote pr= oducer. + + + To do this click on the "Erase loc= al registration" button next to the registration context informa= tion on the consumer configuration screen: + + + + + + + + + + + + + This operation is dangerous as it can result in inabil= ity to interact with the remote producer if invoked when not required. The = warning message below will be displayed before any data is erased. + + + + + + + + + + + + + +
+ = + +
+ = +
+ Configuring the WSRP Producer +
+ Overview + + The behavior of the Portal's WSRP Producer can be configur= ed using the WSRP administration interface, (this is the recommended method= ), or by editing the WSRP_PATH/lib/gat= ein.portal.component.wsrp-<VERSION>-epp-GA= .jar/conf/wsrp-producer-config.xml file. + + + Several aspects can be modified with respect to whether re= gistration is required for consumers to access the Producer's services. An = XML Schema for the configuration format is available at WSRP_PATH/lib/wsrp-integration-api-WSRP_VERS= ION.jar/xsd/gatein_wsrp_producer_1_0.xsd . + + + An alternative to editing the default wsrp-produ= cer-config.xml file is to make a custom copy containing the requ= ired configuration options. + + + If a copy is used in place of the original, however, the <= filename>WSRP_PATH/02portal.war/WEB-INF/conf/wsr= p/wsrp-configuration.xml must= be updated to reference the custom file (this file defines the component <= literal>WSRPServiceIntegration and contains a producer and consum= er configuration location). + + +
+ = +
+ Default Configuration + + The default producer configuration requires that consumers= register with it before providing access to its services. However it does = not require any specific registration properties (excepting those mandated = by the WSRP standard). + + + It does, however, require consumers to be registered befor= e sending them a full service description. This means that the WSRP produce= r will not provide the list of offered portlets and other capabilities to u= nregistered consumers. + + + The producer also uses the default Registration= Policy paired with the default RegistrationPropertyV= alidator. + + + This allows users to customize how Portal's WSRP Producer = decides whether a given registration property is valid or not (however prop= erty validators are discussed in greater detail in ). + + + JBoss Enterprise Portal Platform provides a web interface = to configure the producer's behavior. It can be accessed by clicking on the= "Producer Configuration" tab of the "WSRP" page of the "admin" portal. + + + The default configuration should show: + + + + + + + + + + + + You can specify whether or not the producer will send the = full service description to unregistered consumers, and, if it requires reg= istration, which RegistrationPolicy to use (and, if need= ed, which RegistrationPropertyValidator), along with req= uired registration property description for which consumers must provide ac= ceptable values to successfully register. + + + WSDL URLs to access JBoss Enterprise Portal Platform's WSR= P producer are now displayed in either in WSRP 1 or WSRP 2 mode. + + +
+ = +
+ Registration Configuration + + In order to have consumers register with Portal's producer= the Portal's behavior with respect to registration must be configured. + + + Registration is optional, as are registration properties. = The producer can require registration without requiring consumers to pass a= ny registration properties as is the case in the default configuration. + + + The following section discusses configuring a producer's r= egistration behavior from a blank state: + + + + + + + + + + + + + + To allow unregistered consumers to see the list of= offered portlets, leave the first checkbox ("Acces= s to full service description requires consumers to be registered.") unchecked. + + + + + + To specify, however, that consumers will need to b= e registered to be able to interact with the producer, check the second box= ("Requires registration. Modifying this informatio= n will trigger invalidation of consumer registrations."). + + + The screen will refresh and display: + + + + + + + + + + + + + + + The fully-qualified name for the Regist= rationPolicy and RegistrationPropertyValidator can be specified here. The default values are acceptable. Refer to <= xref linkend=3D"sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuratio= n-Customization_of_Registration_Handling_Behavior" /> for more information. + + + + + + To add a registration property called ema= il click "Add property" and en= ter the appropriate information in the fields, providing a description for = the registration property that can be used by consumers to determine its pu= rpose: + + + + + + + + + + + + + + + Press "Save" to record the modifications. + + + + + + = + + + At this time, only String (xsd:string) properties are supported. + + + + + + If consumers are already registered with the producer,= modifying the configuration of required registration information will trig= ger the invalidation of held registrations, requiring consumers to modify t= heir registration before being able to access the producer again. The consu= mer side of that process is documented in . + + + +
+ Customization of Registration Handling Behavior</ti= tle> + <para> + Registration handling behavior can be customized by us= ers to suit their Producer needs. This is done with an implementation of th= e <classname>RegistrationPolicy</classname> interface. + </para> + <para> + This interface defines methods that are called by Port= al's Registration service so that decisions can be made appropriately. A de= fault registration policy that provides basic behavior is provided and shou= ld be enough for most user needs. + </para> + <para> + While the default registration policy provides default= behavior for most registration-related aspects, one aspect requires specif= ic configuration: whether a given value for a registration property is acce= ptable by the WSRP Producer. + </para> + <para> + This is done by plugging a <classname>RegistrationProp= ertyValidator</classname> into the default registration policy. This allows= users to define their own validation mechanism. + </para> + <para> + Refer to the <trademark class=3D"trade">Javadoc</trade= mark> for <classname>org.gatein.registration.RegistrationPolicy</classname>= and <classname>org.gatein.registration.policies.RegistrationPropertyValida= tor</classname> for more details on what is expected of each method. + </para> + <para> + A defined registration policy is required for the prod= ucer to be correctly configured. Do this by specifying the qualified class = name of the registration policy. + </para> + <para> + As it is anticipated that most users will use the defa= ult registration policy, it is possible to provide the class name of a cust= om property validator instead to customize the default registration policy = behavior. Note that property validators are only used by the default policy. + </para> + <note> + <para> + Since the policy or the validator are defined via = their class name and dynamically loaded, it is important to ensure that the= identified class is available to the application server. + </para> + <para> + One way to accomplish that is to deploy the policy= implementation as a JAR file in the AS instance deploy directory. + </para> + <para> + Note also that, since both policies and validators= are dynamically instantiated, they must provide a default, no-argument con= structor. + </para> + + </note> + + </section> + = + + </section> + = + <section id=3D"sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_= WSRP_Producer-WSRP_Validation_Mode"> + <title>WSRP Validation Mode + + The lack of conformance kit and the wording of the WSRP sp= ecification leaves room for differing interpretations, resulting in interop= erability issues. It is therefore possible to encounter issues when using c= onsumers from different vendors. + + + Experience of these issues has produced a way to relax the= validation that the WSRP producer performs on the data provided by consume= rs to help with interoperability by accepting data that would normally be i= nvalid. + + + Note that the our validation algorithm is only relaxed on = aspects of the specification that are deemed harmless such as invalid langu= age codes. + + + By default, the WSRP producer is configured in strict mode= . If you experience issues with a given consumer, you may attempt to relax = the validation mode. Un-checking the "Use strict WSRP compliance" checkbox = on the Producer configuration screen to do this. + + +
+ = + +
+ = +
+ Removing WSRP + + If you are not going to use WSRP in your JBoss Enterprise Port= al Platform instance, the WSRP configuration files may be left in place. Th= ey will not adversely affect your installation. + + + However, if you wish to completely remove WSRP from your porta= l installation, remove the gatein-wsrp-integration.ear= file from your application server deploy directory. + + +
+ = + + + Modified: epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/W= SRP.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-eXoJCR-1.14/en-US/modules/WSRP.xm= l 2011-11-24 17:26:22 UTC (rev 8138) +++ epp/docs/branches/5.2/Reference_Guide-eXoJCR-1.14/en-US/modules/WSRP.xm= l 2011-11-25 00:43:12 UTC (rev 8139) @@ -1,2003 +1,1370 @@ -%BOOK_ENTITIES; -]> - - Web Services for Remote Portlets (WSRP) -
- Introduction - - The Web Services for Remote Portlets (WSRP) specification defi= nes a web service interface for accessing and interacting with interactive = presentation-oriented web services. - - - It has been produced through the efforts of the Web Services f= or Remote Portlets (WSRP) OASIS Technical Committee. It is based on the req= uirements gathered and the proposals made to the committee. - - - Scenarios that motivate WSRP functionality include: - + + %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 Portl= ets as presentation-oriented web services that can be used by aggregation e= ngines. - - + 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, cons= uming presentation-oriented web services offered by content providers and i= ntegrating them into the framework. - - + + Aggregating frameworks, including portal servers, con= suming presentation-oriented web services + offered by content providers and integrating them into t= he framework. + + + = - - - More information on WSRP can be found on the official we= bsite. We suggest reading the primer for a= good, albeit technical, overview of WSRP. - + 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 - - The WSRP Technical Committee defined WSRP Use Profiles to h= elp with WSRP interoperability. Terms defined in that document will be used= in this section. - - - JBoss Enterprise Portal Platform provides a Simple level of support for the WSRP Producer, with the exception of out= -of-band registration. In-band registration and persistent local state (whi= ch are defined at the Complex level) are supported. - - - JBoss Enterprise Portal Platform provides a Medium level of support for the Consumer, excepting HTML markup (as JBos= s Enterprise Portal Platform itself does not handle other markup types). Ex= plicit portlet cloning and the PortletManagement interfa= ce are supported. - - - The WSRP component has Level 1 Producer and Consumer caching. = Cookie handling is supported properly on the Consumer. The Producer require= s cookie initialization (as this improves interoperability with some consum= ers). - - - JBoss Enterprise Portal Platform does not support custom windo= w states or modes, therefore neither does the WSRP component. It does, howe= ver, support CSS on both the Producer (although this is more a function of = the portlets than an inherent Producer capability) and Consumer. - - - JBoss Enterprise Portal Platform &VY; includes implementations= of WSRP 1.0 and 2.0. - - - All optional features in WSRP 2 are implemented in JBoss Enter= prise Portal Platform &VY; except support for lifetimes and leasing support. - - - - As of version &VZ; of Enterprise Portal Platform, WSRP is = only activated and supported when deployed on JBoss Enterprise Application = Server. - +
+ 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). + = -
- = -
- Deploying WSRP - - Notational Devices - - The following list of support files uses the following not= ational devices: - - - Notations: - - JBOSS_HOME - - - JBOSS_HOME refers t= o the directory that your instance of JBoss Enterprise Portal Platform has = been extracted/installed to. For example: /home/USER= NAME/jboss-epp-<VERSION>/ - + 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. + = - - - WSRP_PATH - - - The WSRP files referred to in this section are= found in the JBOSS_HOME/jboss-as/serv= er/<PROFILE>/deploy/gatein.ear = directory. - - - For ease of reference this path will be repres= ented by: WSRP_PATH. - + 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. + = - - - WSRP_VERSION - - - WSRP_VERSION repres= ents the version of the WSRP component in use. - + + 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> + <para> + <filename>META-INF</filename> + contains files necessary for EAR packaging. The only fil= e that is of interest from a user perspective + is + <filename>gatein-wsse-consumer.xml</filename> + which allows you to configure WS-Security support for th= e consumer. Please see the + <link linkend=3D"wss_configuration">WSRP and WS-Security= </link> section for more details. + </para> + </listitem> + <listitem> + <para> + <filename>extension-component-$PORTAL_VERSION.jar</filen= ame>, 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. + </para> + </listitem> + <listitem> + <para> + <filename>extension-config-$PORTAL_VERSION.jar</filename= >, which contains the configuration file + needed by the GateIn extension mechanism to properly reg= ister this EAR as an extension. + </para> + </listitem> + <listitem> + <para> + <filename>extension-war-$PORTAL_VERSION.war</filename>, = which contains the configuration files + needed by the GateIn extension mechanism to properly set= up the WSRP service. It includes + <filename>wsrp-configuration.xml</filename> + which, in particular, configures several options for the + <code>WSRPServiceIntegration</code> + component at the heart of the WSRP integration in JBoss = Enterprise Portal Platform. + </para> + </listitem> + <listitem> + <para> + <filename>lib</filename>, which contains the different l= ibraries needed by the WSRP service. + </para> + </listitem> + <listitem> + <para> + <filename>wsrp-admin-gui-$WSRP_VERSION.war</filename>, w= hich contains the WSRP Configuration portlet + with which you can configure consumers to access remote = servers and how the WSRP producer is + configured. + </para> + </listitem> + <listitem> + <para><filename>wsrp-producer-jb5wsss-$WSRP_VERSION.war</fi= lename>, which contains the producer-side + support for WS-Security. The only file of interest from = a user perspective is + <filename>gatein-wsse-producer.xml</filename> which allo= ws you to configure WS-Security support for + the producer. Please see the <link linkend=3D"wss_config= uration">WSRP and WS-Security</link> section + for more details. + </para> + </listitem> + </itemizedlist> + </para> + <para> + 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 + <filename>gatein-wsrp-integration.ear</filename> + file from your AS deploy directory. + </para> = - </varlistentry> - <varlistentry> - <term><replaceable>PORTAL_VERSION</replaceable></term> - <listitem> - <para> - <replaceable>PORTAL_VERSION</replaceable> repr= esents the version of JBoss Enterprise Portal Platform in use. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </note> + <section id=3D"wsrp-ports"> + <title>Considerations to use WSRP when running JBoss Enterprise P= ortal Platform on a non-default port or hostname - Starting with version 2.1.0-GA of the component, WSRP is packa= ged as a JBoss Enterprise Portal Platform extension and is now self-contain= ed in an easy to install package named gatein-wsrp-integration.ea= r, deployed directly in the deploy director= y of your JBoss Application Server configuration directory. - + 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. + - The extension itself is composed of the following components: - - - WSRP support files - - META-INF/ - - - This directory contains files necessary for EAR pa= ckaging. The only file that is of interest from a user perspective is gatein-wsse-consumer.xml which allows you to configure WS-S= ecurity support for the consumer. - - - Refer to section for mo= re 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. + +
+
= - - - - - extension-component-$PORTAL_VERSION.jar - - - This archive which contains the components needed = to integrate the WSRP component into JBoss Enterprise Portal Platform. It a= lso includes the default configuration files for the WSRP producer and the = default WSRP consumers. - - - - - - - extension-config-$PORTAL_VERSION.jar - - - This file contains the configuration file needed b= y the GateIn extension mechanism to properly register this EAR as an extens= ion. - - - - - - - extension-war-$PORTAL_VERSION.war - - - This file contains the configuration files needed = by the GateIn extension mechanism to properly setup the WSRP service. It in= cludes wsrp-configuration.xml which, in particular, co= nfigures several options for the WSRPServiceIntegration comp= onent at the heart of the WSRP integration in JBoss Enterprise Portal Platf= orm. - - - - - - - lib/ - - - This directory contains the different libraries ne= eded by the WSRP service. - - - - - - - wsrp-admin-gui-$WSRP_VERSION.war - - - This file contains the WSRP Configuration portlet = with which you can configure consumers to access remote servers and how the= WSRP producer is configured. - - - - - - - wsrp-producer-jb5wsss-$WSRP_VERSION.war - - - This file contains the producer-side support for W= S-Security. The only file of interest from a user perspective is = gatein-wsse-producer.xml which allows you to configure WS-Securi= ty support for the producer. - - - Refer to for more detai= ls. - - - - - - - -
- Non-default Ports or Hostnames - - JBoss WS (the web service stack that JBoss Enterprise Port= al Platform uses) should update the port and host name used in WSDL. Refer = to the JBoss WS user guide for more information. - - - If the host name and port on which the server runs have be= en modified, the configuration for the Consumer used to consume JBoss Enter= prise Portal Platform's "self" Producer will need to be updated. Refer to <= xref linkend=3D"sect-Reference_Guide_eXo_JCR_1.14-Web_Services_for_Remote_P= ortlets_WSRP-Consuming_Remote_WSRP_Portlets" /> for directions on how to do= this. - - -
- = -
- Using WSRP with SSL - - It is possible to use WSRP over SSL for secure exchange of= data. Refer to these instructions for how to do this. - - -
- = - -
- = -
+
+ 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 th= e currently authenticated user. For remote portlets, this means having to p= ropagate the user credentials from the consumer back to the producer in a s= afe and secure manner. + 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. - - The WSRP specification does not directly specify how this shou= ld be accomplished, but delegates this work to the existing WS-Security sta= ndards. - - - Web Container Compatibility - - WSRP and WS-Security is currently only supported on JBoss = Enterprise Portal Platform when running on top of JBoss AS 5. - - + + 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 - - The use of encryption is strongly = recommended. - - - Credentials being sent between the consumer and producer s= hould be encrypted or they will be sent in plain text and could be easily i= ntercepted. - - - You can either configure WS-Security to encrypt and sign t= he SOAP messages being sent, or secure the 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. - - + + 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 t= he consumer. This makes signing in to remote portlets transparent to end us= ers, but also requires that the producer and consumer use the same credenti= als. - - - The username and password must be the same and valid on bo= th servers. - - - The recommended approach for this situation would be to us= e a common LDAP configuration. Please see the User Guide at for information on how to configure LDAP f= or use with JBoss Enterprise Portal Platform - - + + 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 + - - This community Wiki article, also provides a step-= by-step example on how to configure WSRP with WS-Security. + 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 handle ws-security. - - - Refer to the WS-Security section of the JBoss AS 5 Administration and Configurat= ion Guide for in-depth configuration options. - - - Please note that since the consumer passes its credentials= to the producer, the consumer will act at the wss client and the producer = will act as the wss server. - - - The following are the JBossWS Native configuration files w= hich need to be configure for WSRP: - - - - - gatein-wsrp-integration.ear/META-INF/gatein-wsse= -consumer.xml - - - BossWS 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 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, n= o other configuration changes should be necessary 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 some changes before it will function= properly with WS-Security. - - - The consumer needs access to the current servlet request s= ince this is used to retrieve the currently authenticated user. In order to= access this information, the consumer needs a special servlet-filter added= to the portal. - - - Add the servlet-filter - - - Open <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.= ear/02portal.war/WEB-INF/web.xml and add the following: - - = -<!-- Filter to put request and response in= ServletAccess --> - <filter> - <filter-name>ServletAccessFilter</filter-name> - <filter-class>org.gatein.wsrp.servlet.ServletAccessFilter</= filter-class> - </filter> - <filter-mapping> - <filter-name>ServletAccessFilter</filter-name> - <url-pattern>/*</url-pattern> - </filter-mapping> +
+ 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 + org.gatein.wsrp.servlet.ServletAccessFilter + + + ServletAccessFilter + /* + ]]> + + 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 +
+
+
= - - - - Check the Enable WS Security = checkbox in the consumer configuration options of the WSRP Configuration po= rtlet - - - - - +
+ Making a portlet remotable + + + 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 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 + + + + + + BasicPortlet = - - - - = + ... = -
- = -
- WS-Security Consumer Checklist - - In order for the consumer to handle ws-security, the follo= wing items must be implemented: - - - - - The JBossWS configuration files must be configured - + + org.gatein.pc.remotable + true + + +]]> + = - - - - The filter must be added to the portal's web.xml - + + + 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 + + + + = - - - - the enable wss feature must be check in the wsrp a= dmin - + + RemotelyExposedPortlet + ... + + + NotRemotelyExposedPortlet + ... + + org.gatein.pc.remotable + false + + = - + + org.gatein.pc.remotable + true + +]]> + + = - - - The consumer will not properly handle ws-security unless a= ll three items are correctly configured. - + = -
+ + 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. + +
= -
- = -
- Making a Portlet Remotable - - - Only JSR-286 (Portlet 2.0) portlets can be made remotable = as the mechanism to expose a portlet to WSRP relies on a JSR-286-only funct= ionality. - +
+ 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 - JBoss Enterprise Portal Platform does = not, by default, expose local portlets for consumption by remote= WSRP consumers. - + 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. + - In order to make a portlet remotely available, it must be made= "remotable" by marking it as such in the associated portlet.xml<= /filename>. - + 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. + +
+ +
+ Configuring a remote producer using the configuration port= let - A specific org.gatein.pc.remotable container-runtime-opt= ion is used to accomplish this. Setting its value to true makes the portlet available for remote consumption, while setting its va= lue to false will not publish it remotely. - - - As specifying the remotable status for a portlet is optional, = nothing need be done if portlets do not need to be remotely available. - - - In the following example, the "BasicPortlet" portlet is specif= ied as being remotable. - - = - - - It is also possible to specify that all the portlets declared = within a given portlet application be remotable by default. - - - This is done by specifying the container-runtime-option<= /code> at the portlet-app element level. Individual portlets c= an override that value to not be remotely exposed. - - - For example: - - = - - - This example defines two portlets. As the org.gatein.pc.= remotable container-runtime-option is set to true at th= e portlet-app level, all portlets defined in this particular p= ortlet application are exposed remotely by JBoss Enterprise Portal Platform= 's WSRP Producer. - - - It is possible to override this default behavior. 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 the org.gatein.pc.remota= ble container-runtime-option. - - - The NotRemotelyExposedPortlet, however, ove= rrides the default behavior and is not remotely exposed. - + 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. + + - Note - - Portlets are not remotely exposed if no top-level or= g.gatein.pc.remotable container-runtime-option value is set to true. + + 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. + = - - -
- = -
- Consuming WSRP portlets from a remote Consumer - Configuration is extremely variable between different WSRP Con= sumers. Most, however, require a specification of the URL for the Producer'= s WSDL definition. If the JBoss Enterprise Portal Platform Consumer is not = being used, refer to the documentation for the Consumer that is in use for = specific instructions. - - - For instructions on how to specify this URL in JBoss Enterpris= e Portal Platform, refer to . - - - JBoss Enterprise Portal Platform's Producer is automatically s= et up when a portal instance is deployed with the WSRP service. - - - The WSDL file can be accessed at: - - - File paths: - - WSRP 1.0: - - - http://{hostname}:{port}/wsrp-producer/v1/MarkupService?wsdl<= /filename>. - + 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 + + = - - - - - WSRP 2.0: - - - http://{hostname}:{port}/wsrp-producer/v2/MarkupService?wsdl<= /filename>. - - - - - - - - The default hostname is localhost and the d= efault port is 8080. - + 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. + = -
- = -
- Consuming Remote WSRP Portlets -
- Overview - - To be able to consume WSRP portlets exposed by a remote pr= oducer, JBoss Enterprise Portal Platform's WSRP consumer must be configured= to access that remote producer. + + + 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. - - Access to a remote producer can be configured using the pr= ovided configuration portlet. Alternatively, it is also possible to configu= re access to remote producers using an XML descriptor. The configuration po= rtlet is the recommended method. - - - Once a remote producer has been configured, the portlets t= hat it exposes are then available in the Application Registry to be added t= o categories and then to pages. - - -
- = -
- Configuring a Remote Producer - - Access to a remote producer needs to be defined so that po= rtlets can be consumed within JBoss Enterprise Portal Platform. This sectio= n will show how to configure access to NetUnity's public WSRP producer. - - - Firstly using the configuration portlet and then how the s= ame result can be accomplished with a producer descriptor, though it is far= easier to do so via the configuration portlet. - - - Chunked Encoding - - Some WSRP producers, such as Oracle, do not support ch= unked encoding. If your producer does not support chunked encoding, it will= not be able to properly connect to the producer. - - - This will manifest itself with the following error: - - = -Caused by: org.jboss.ws.WSException: Invalid HTTP server response = [503] - Service Unavailable. - - - A workaround for this issue involves editing the chunksize setting in the standard-jaxws-client-= config.xml file. - - - Refer to http://communit= y.jboss.org/wiki/Workaroundwhenchunkedencodingisnotsupported for mo= re information. - - - -
- The Configuration Portlet - - JBoss Enterprise Portal Platform provides a graphical = portlet to assist with configuring access to, and other facets of, remote W= SRP Producers. - - - It is available at: . - - - The portlet also is a group page for /platform/adminis= trators - - - Although the Configuration Portlet is installed by def= ault in JBoss Enterprise Portal Platform &VY;., installation instructions a= re included below should the portlet ever need to be re-installed: - - - <emphasis role=3D"bold">Installing the configur= ation portlet:</emphasis> - - - Log into the portal as an administrator and go= to the Application Registry (Click http://localhost:8080/portal/p= rivate/classic/administration/registry if using the default install= ation). - - - - - - Add the WSRP Configuration portlet to the Admi= nistration category. If the Import Applications functionality is used, the = WSRP Configuration portlet will be automatically added to the Administratio= n category. - - - - - - Once the portlet is added to a category, it ca= n be added to a page and used. It is recommended that it be added to the sa= me page as the Application Registry (as other operations relating to WSRP a= nd adding portlets to categories are somewhat related). Add the WSRP Config= uration portlet to the page using the standard procedure. - - - - - - = -
- <emphasis role=3D"bold">Using the Configuration= portlet</emphasis> - - - - - - - - - - - This screen presents all the configured consumers = associated 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 portlet provider. - - - Note also that a Consumer can be marked as requiri= ng refresh, which means that the information held abou= t it might not be up to date. Refreshing it from the remote Producer will u= pdate this information. - - - This can happen for several reasons: the service d= escription for that remote Producer has not been fetched yet, the cached ve= rsion has expired or modifications have been made to the configuration that= could potentially invalidate it, thus requiring re-validation of the infor= mation. - - - To create a new Consumer: - - - <emphasis role=3D"bold">Creating a Consumer= </emphasis> - - - Type "netunity" into th= e "Create a consumer named:" field. - - - - - - Click on "Create c= onsumer" to create a new Consumer called netunity. - - - - - - - - - - - - - - - In the next form, set the cache expiration= value to 300 seconds. - - - - - - Leave the default timeout value for web se= rvices (WS) operations. - - - - - - Enter the WSDL URL for the producer in the= text field. - - - - - - Press the "Refresh & Save" button: - - - - - - - - - - - - - - - = - - This will retrieve the service description associa= ted with the Producer which WSRP interface is described by the WSDL file fo= und at the URL entered. - - - In this case, querying the service description wil= l show that the Producer requires registration, that it requested three reg= istration properties and that the current configuration is missing values f= or these properties: - - - - - - - - - - - - This particular producer requests simple = Yes or No values for the three registration pr= operties. - - - Enter No, Yes and No (in that order) for the values and then pressin= g the "Refresh & Save" button should result in: - - - - - - - - - - - - Values - - Unfortunately there is no automated way to lea= rn about which possible values (if any) are expected by the remote Producer= . Possible values may be indicated in the registration property description= but this is not always the case. Refer to the specific Producer's document= ation. - - - - - The Consumer for the netunity P= roducer should now be available as a portlet provider and be ready to be us= ed. - - - If the producer had required registration but did = not require any registration properties, as is the case for the se= lfv2 consumer (the consumer that accesses the portlets made remot= ely available by JBoss Enterprise Portal Platform's producer via WSRP 2), t= he following screen would have appeared after pressing the "Refresh & S= ave" button: - - - - - - - - - - - -
- = - -
- = -
- Using XML - - Although using the WSRP Configuration portlet to confi= gure Consumers is recommended, the WSRP component provides an alternative w= ay to configure consumers. - - - This is done by editing the <= ;JBOSS_HOME>/server/<PROFILE>/conf/gatein/wsrp-consumers-config.xml XML file. - - - XML Elements - - An XML Schema defining which elements are availabl= e to configure Consumers via XML can be found in WSR= P_PATH/lib/wsrp-integration-api-WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd - - - - - The Consumer Configuration file - - It is important to understand how the XML Consumer= s configuration file is processed. It is read the first time the WSRP servi= ce starts and the associated information is then put under control of the J= CR (Java Content Repository). - - - - - Subsequent launches of the WSRP service will use the J= CR-stored information for all producers that are already known to JBoss Ent= erprise Portal Platform. More specifically, the wsrp-consumers-co= nfig.xml file is scanned for producer identifiers. Any identifie= r that is already known will be bypassed and the JCR information associated= with this remote producer will be used. - - - The information defined at the XML level is only proce= ssed for producer definition for which no information is already present in= the JCR. - - - Therefore, to delete a Producer configuration, the ass= ociated information in the database must be deleted (this can be accomplish= ed using the configuration portlet as shown in ). - - - The associated information in wsrp-consumers= -config.xml (if such information exists) must also be removed, o= therwise the producer will be re-created the next time the WSRP is launched. - -
- Required Configuration Information - - The following information needs to be provided to = configure access to a remote Producer: - - - - - An identifier must be provided for the pro= ducer being configured so that it can be referred to later. This is done in= the mandatory id attribute of the <wsrp-pro= ducer> element. - - - - - - JBoss Enterprise Portal Platform also need= s to know about the remote Producer's endpoints to be able to connect to th= e remote web services and perform WSRP invocations. Use the <en= dpoint-wsdl-url> element to specify the URL for the WSDL descr= iption of the remote WSRP service. - - - - - - - Both the id attribute and <endpoint-wsdl-url> elements are required for a functio= nal remote producer configuration. - - -
- = -
- Optional Configuration - - It is also possible to provide additional configur= ation, which, in some cases, might be important to establish a proper conne= ction to the remote producer. - - - Optional Configurations - - Caching - - - To prevent unnecessary traffic between= the local consumer and the remote producer, it is possible to cache some o= f the information sent by the producer (such as the list of offered portlet= s) for a given duration. - - - The rate at which the information is r= efreshed is defined by the expiration-cache attribute of= the <wsrp-producer> element (in seconds). - - - For example; providing a value of 120 for expiration-cache means that the producer information= will not be refreshed for 2 minutes after it has been 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 informat= ion provided by the producer does not change often, use of this caching fac= ility to minimize bandwidth usage is recommended. - - - - - - - WS Timeout - - - It is also possible to define a timeou= t after which WS operations are considered as failed. This is helpful to av= oid blocking the WSRP service, as it waits on a service that does not answe= r. - - - Use the ws-timeout = attribute of the <wsrp-producer> element to specif= y how many milliseconds the WSRP service will wait for a response from the = remote producer before timing out. - - - - - - - Pre-registration information - - - Some producers require consumers to re= gister with them before authorizing them to access their offered portlets. = If known, some registration information can be provided in the producer con= figuration beforehand, so that the consumer can register with the remote pr= oducer when required. - - - - Only simple String properties are = supported. It is not possible to configure complex registration data. Howev= er, this should be sufficient for most cases. - - - - - This pre-registration configuration is= done via the <registration-data> element. - - - If the remote producer does not requir= e any registration properties, only an empty <registration-data= > element need be provided, as JBoss Enterprise Portal Platfor= m can generate the mandatory information. - - - Values for the registration properties= required by the remote producer can be provided via <property&= gt; elements. Refer to the example below for more details. - - - Additionally, the default consumer nam= e automatically provided by JBoss Enterprise Portal Platform can be overrid= den via the <consumer-name> element. When providin= g a consumer name, please remember that it should uniquely identify your co= nsumer. - - - - - - - - -
- = - -
- = -
- Examples - - This is the configuration of the selfv1 and selfv2 consumers as found in default-= wsrp.xml with a cache expiring every 500 seconds and with a 50 s= econd timeout for web service operations: - - - - This file contains the default configuration and s= hould not need to be edited. If modifications are required, the recommended= practice is to follow the procedure detailed in . - - - - = - - - This is an example of a WSRP descriptor with registrat= ion data and cache expiring every minute: - - = - - -
- = - -
- = -
- Adding remote portlets to categories - - Clicking on the Portlet link in the Application Registry w= ill now show the remote portlets in the REMOTE tab in the left column: + 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": + + + + - - These portlets are available to be used as regular portlet= s: they can be used in categories and added to pages. Using the Import Appl= ications functionality will also automatically import them into categories = based on the keywords they define. - - - More specifically, to add a WSRP port= let to a category, select wsrp in the Application Type d= rop-down menu: - - - - - - + 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. + + + = -
- = -
- Consumers Maintenance -
- Modifying a Currently Held Registration -
- Registration Modification for Service Upgrade</titl= e> - <para> - Producers often offer several levels of service depend= ing on consumers' subscription levels (for example). This is implemented at= the WSRP level with the registration concept: producers can assert which l= evel of service to provide to consumers based on the values of given regist= ration properties. - </para> - <para> - There may also be cases where the registration informa= tion has changed and must be updated. For example, the producer required yo= u to provide a valid email and the previous email address is not valid anym= ore and needs to be updated. - </para> - <para> - Therefore at times it may be necessary to modify the r= egistration that sets the service agreement between a consumer and a produc= er. - </para> - <para> - For example; the producer requiring an email that was = configured in <xref linkend=3D"sect-Reference_Guide_eXo_JCR_1.14-Configurin= g_a_Remote_Producer-The_Configuration_Portlet" /> . In that case the produc= er was requiring registration and required a value to be provided for the <= literal>email</literal> property. - </para> - <para> - To update the email address that was provided, the rem= ote producer must be informed that some registration data has been modified. - </para> - <para> - The following procedure assumes access to the producer= has been configured as previously described. - </para> - <procedure> - <step> - <para> - Go to the configuration screen for the <litera= l>self</literal> producer and change the value of <literal>email</literal> = to <literal>foo(a)example.com</literal> instead of <literal>example(a)examp= le.com</literal>: - </para> - <mediaobject> - <imageobject role=3D"html"> - <imagedata align=3D"center" fileref=3D"ima= ges/WSRP/modify_reg_start.png" format=3D"PNG" scale=3D"100" width=3D"444" /> - </imageobject> - <imageobject role=3D"fo"> - <imagedata align=3D"center" contentwidth= =3D"140mm" fileref=3D"images/WSRP/modify_reg_start.png" format=3D"PNG" widt= h=3D"444" /> - </imageobject> + <para> + 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 + <literal>selfv2</literal> + 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: + <mediaobject> + <imageobject> + <imagedata fileref=3D"images/WSRP/config_refresh.png" fo= rmat=3D"PNG" align=3D"center" valign=3D"middle" + scalefit=3D"1"/> + </imageobject> + </mediaobject> + </para> + </section> = - </mediaobject> + <section id=3D"consumer_xml"> + <title>Configuring access to remote producers via XML = - - - - Click on "Update prope= rties" to save the change. A "Modify reg= istration" button should now appear to let you send this new dat= a to the remote producer: - - - - - - - - + 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. + + 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 + + + + + + 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. + = - + + + = - - - - Click on Modify regist= ration and, if the updated registration details have been accept= ed by the remote producer the following should appear: - - - - - - - - +
+ 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. + = -
- = -
- Registration Modification on Producer Error - - If a Producer administrator changes the requirements f= or registered consumers, invoking operations on the producer may fail with = an OperationFailedFault. JBoss Enterprise Po= rtal Platform will attempt to assist in these cases. - - - This section will discuss an example using the self producer. - - - Assuming that the registration requires a valid value = for an email registration property (as has been shown) t= he configuration screen for this producer should show: - - - - - - - - + Both the + id + attribute and + <endpoint-wsdl-url> + elements are required for a functional remote producer conf= iguration. + +
= - - - If the administrator of the producer now requires an a= dditional value to be provided for a name registration p= roperty operations with this producer will fail. - - - If a registration modification is required, go to the = configuration screen for this remote producer and refresh the information h= eld by the consumer by pressing "Refresh & Save= ": - - - - - - - - +
+ 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. + = - - - The configuration screen now shows the currently held = registration information and the expected information from the producer. - - - Enter a value for the name property= and then click on "Modify registration"= . If the producer accepts the new registration data, the following screen w= ill appear: - - - - - - - - + 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. + = - - - <emphasis role=3D"bold">JBoss Enterprise Portal= Platform &VY; and WSRP 1 Exceptions</emphasis> - - In WSRP 1, it can be difficult to ascertain what c= aused an OperationFailedFault as it is a g= eneric exception returned by producers during a failed method invocation. - - - An OperationFailedFault failure can be caused by several different reasons, one of them being = a request to modify the registration data. - - - In these instances examining the log files may ass= ist in gathering more information about the problem. - - - WSRP 2 introduces an exception that is specific to= a request to modify registrations which reduces the ambiguity that current= ly exists. - + 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. + = - - -
- = - -
- = -
- Consumer Operations - - Several operations are available from the consumer list vi= ew of the WSRP configuration portlet: + 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. + + - - - - - - - = - - - The available operations are: + 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. - - - Configure - - - Displays the consumer details and allows user = to edit them. - +
= - +
+ Examples = - - - Refresh - - - Forces the consumer to retrieve the service de= scription from the remote producer to refresh the local information (such a= s offered portlets, registration information). - + + 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 + + + + http://localhost:8080/wsrp-producer/v1/MarkupS= ervice?wsdl + + + + + + http://localhost:8080/wsrp-producer/v2/MarkupS= ervice?wsdl + + + +]]> + + = - - - Activate/Deactivate - - - Activates or deactivates a consumer, governing= whether it will be available to provide portlets and receive portlet invoc= ations. - + = - + Here is an example of a WSRP descriptor with registratio= n data and cache expiring every minute: + = - - - Register/De-register - - - Registers or de-registers a consumer based on = whether registration is required and/or acquired. - + + Example + + + + http://example.com/producer/producer?WSDL + + + property name + en + property value + + + + +]]> + + +
+
= - +
+ 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: + + + + + + = - - - Delete - - - Destroys the consumer, after de-registering it= if it was registered. - + + 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 = - - - <emphasis role=3D"bold">Additional Functionalities = in WSRP 2.0</emphasis> - - In addition to those listed above, the WSRP 2.0 implem= entation in JBoss Enterprise Portal Platform &VY; also includes the followi= ng functions: - +
+ Modifying a currently held registration = - - - Additional Functions: - - Export - - - Exports some or all of the consumer's portlets= to be able to later import them in a different context - - - - - - - Import - - - Imports some or all of previously exported por= tlets. - - - - - - - -
- <emphasis role=3D"bold">Importing and Exporting Por= tlets</emphasis> - - Import and export are new functionalities added in WSR= P 2. - - - Exporting a portlet allows a consumer to get an opaque= representation of the portlet which can then be use by the corresponding i= mport operation to reconstitute it. - - - This is mostly used in migration scenarios during batc= h operations. Since JBoss Enterprise Portal Platform does not currently sup= port automated migration of portal data, the functionality provided as part= of WSRP 2 is necessarily less complete than it could be with full portal s= upport. - - - The import/export implementation in JBoss Enterprise P= ortal Platform allows users to export portlets from a given consumer and th= en import them back to replace existing portlets assigned to windows on pag= es by the previously exported portlets. - - - - - - Click on the "Export" act= ion for a given consumer to display the list of portlets currently made ava= ilable by this specific consumer. An example list is shown below: - - - - - - - - - - - - - - - Once portlets have been selected, they can be = exported by clicking on the "Export" button. This make= s them available for later import: - - - - - - - - - - - - - - - The portlets can be re-imported directly by pr= essing the "Use for import" button or, on the Consumer= s list page, using the "Import" action for a given con= sumer. - - - The example below assumes that the second opti= on has been used and that several sets of previously exported portlets are = available to import from. After clicking the action link, a screen similar = to the one below should appear: - - - - - - - - - - - - This screen presents the list of available exp= orts with available operations for each. - - - Operations: - - View - - - Displays the export details as pre= viously seen when the export was first performed. - - - - - - - Delete - - - Deletes the selected export, askin= g you for confirmation first. - - - - - - - Use for import - - - Selects the export to import portl= ets from. - - - - - - - - - - - - Once you have selected an export to import fro= m, you will see a screen similar to the one below: - - - - - - - - - - - - The screen displays the list of available expo= rted portlets for the previously selected export. You can select which port= let you want to import by checking the checkbox next to its name. - - - - - - Select the content of which window the importe= d portlet will replace. This process is done in three steps: - - - This example assumes that you have the followi= ng page called page1 which contains two windows called <= literal>NetUnity WSRP 2 Interop - Cache Markup (remote) and /samples-remotecontroller-portlet.RemoteControl (remote), as = shown below: - - - - - - - - - - - - In this example, we want to replace the conten= t of the /samples-remotecontroller-portlet.RemoteControl (remote)<= /literal> with the content of the /ajaxPortlet.JSFAJAXPortlet portlet that was previously exported. - - - - - - Check the box next to the /aj= axPortlet.JSFAJAXPortlet portlet name to indicate that you want t= o import its data. - - - - - - Select page1 in the= list of available pages. The screen will then refresh to display the list = of available windows on that page, similar to the image below: - - - - - - - - - - - - Note - - At this point, you still need to s= elect which window content you want to replace before being able to complet= e the import operation - - - - - - - - Select the /samples-remotecon= troller-portlet.RemoteControl (remote) window, which enables the = "Import" button. This indicates that all the necessary= data to perform the import is available. - - - - - - Click the "Import= " button. A screen similar to the one below will appear: - - - - - - - - - - - - - - - = - - - - - The page1 page should now s= how that the content of /samples-remotecontroller-portlet.RemoteCo= ntrol (remote) window has been replaced by the content of the /ajaxPortlet.JSFAJAXPortlet imported portlet and that the w= indow has been renamed appropriately. - - - - - - - - - - - - - - - = - -
- = - -
- = -
- Erasing Local Registration Data - - In rare cases, it may be necessary to erase the local data= without being able to de-register first. +
+ Registration modification for service upgrade + + 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. - - This can occur when a consumer is registered with a produc= er that has been modified by its administrator to not require registration = any longer. + + 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. - - In this scenario, local registration information can be er= ased from the consumer to allow it to resume interacting with the remote pr= oducer. + + 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. - - To do this click on the "Erase loc= al registration" button next to the registration context informa= tion on the consumer configuration screen: + + 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: + + + + + + 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: + + + + + - - - - - - - = - - - - This operation is dangerous as it can result in inabil= ity to interact with the remote producer if invoked when not required. The = warning message below will be displayed before any data is erased. - - - - - - - - +
= - +
+ 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: + + + + + = -
- = + 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": + + + + + = -
- = -
- Configuring the WSRP Producer -
- Overview - - The behavior of the Portal's WSRP Producer can be configur= ed using the WSRP administration interface, (this is the recommended method= ), or by editing the WSRP_PATH/lib/gat= ein.portal.component.wsrp-<VERSION>-epp-GA= .jar/conf/wsrp-producer-config.xml file. - - - Several aspects can be modified with respect to whether re= gistration is required for consumers to access the Producer's services. An = XML Schema for the configuration format is available at WSRP_PATH/lib/wsrp-integration-api-WSRP_VERS= ION.jar/xsd/gatein_wsrp_producer_1_0.xsd . - - - An alternative to editing the default wsrp-produ= cer-config.xml file is to make a custom copy containing the requ= ired configuration options. - - - If a copy is used in place of the original, however, the <= filename>WSRP_PATH/02portal.war/WEB-INF/conf/wsr= p/wsrp-configuration.xml must= be updated to reference the custom file (this file defines the component <= literal>WSRPServiceIntegration and contains a producer and consum= er configuration location). - + 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: + + + + + = -
- = -
- Default Configuration - - The default producer configuration requires that consumers= register with it before providing access to its services. However it does = not require any specific registration properties (excepting those mandated = by the WSRP standard). + + 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. + + + - - It does, however, require consumers to be registered befor= e sending them a full service description. This means that the WSRP produce= r will not provide the list of offered portlets and other capabilities to u= nregistered consumers. - - - The producer also uses the default Registration= Policy paired with the default RegistrationPropertyV= alidator. - - - This allows users to customize how Portal's WSRP Producer = decides whether a given registration property is valid or not (however prop= erty validators are discussed in greater detail in ). - - - JBoss Enterprise Portal Platform provides a web interface = to configure the producer's behavior. It can be accessed by clicking on the= "Producer Configuration" tab of the "WSRP" page of the "admin" portal. - - - The default configuration should show: - - - - - - - - +
+
= +
+ Consumer operations + + Several operations are available from the consumer list view o= f the WSRP configuration portlet: + + + + - - You can specify whether or not the producer will send the = full service description to unregistered consumers, and, if it requires reg= istration, which RegistrationPolicy to use (and, if need= ed, which RegistrationPropertyValidator), along with req= uired registration property description for which consumers must provide ac= ceptable values to successfully register. + + + 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 + + + + + + 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. - - WSDL URLs to access JBoss Enterprise Portal Platform's WSR= P producer are now displayed in either in WSRP 1 or WSRP 2 mode. - + +
= -
- = -
- Registration Configuration - - In order to have consumers register with Portal's producer= the Portal's behavior with respect to registration must be configured. - - - Registration is optional, as are registration properties. = The producer can require registration without requiring consumers to pass a= ny registration properties as is the case in the default configuration. - - - The following section discusses configuring a producer's r= egistration behavior from a blank state: - - - - - - - - +
+ 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: + + + + + + +
+
+ +
+ Configuring JBoss Enterprise Portal Platform's WSRP Producer<= /title> + <section> + <title>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 + + + + + + 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. + + + + + 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 + + + +
+
+ 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: + + + + - - - - To allow unregistered consumers to see the list of= offered portlets, leave the first checkbox ("Acces= s to full service description requires consumers to be registered.") unchecked. - + 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. + +
= - - - - To specify, however, that consumers will need to b= e registered to be able to interact with the producer, check the second box= ("Requires registration. Modifying this informatio= n will trigger invalidation of consumer registrations."). - - - The screen will refresh and display: - - - - - - - - +
+ 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: + + + + + + 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 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: + + + + + + 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. + + = - - - - The fully-qualified name for the Regist= rationPolicy and RegistrationPropertyValidator can be specified here. The default values are acceptable. Refer to <= xref linkend=3D"sect-Reference_Guide_eXo_JCR_1.14-Registration_Configuratio= n-Customization_of_Registration_Handling_Behavior" /> for more information. - + + 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 + . + = - - - - To add a registration property called ema= il click "Add property" and en= ter the appropriate information in the fields, providing a description for = the registration property that can be used by consumers to determine its pu= rpose: - - - - - - - - - - - - - - - Press "Save" to record the modifications. - - - - - - = - - - At this time, only String (xsd:string) properties are supported. - - - - - If consumers are already registered with the producer,= modifying the configuration of required registration information will trig= ger the invalidation of held registrations, requiring consumers to modify t= heir registration before being able to access the producer again. The consu= mer side of that process is documented in . - + = - -
- Customization of Registration Handling Behavior</ti= tle> - <para> - Registration handling behavior can be customized by us= ers to suit their Producer needs. This is done with an implementation of th= e <classname>RegistrationPolicy</classname> interface. - </para> - <para> - This interface defines methods that are called by Port= al's Registration service so that decisions can be made appropriately. A de= fault registration policy that provides basic behavior is provided and shou= ld be enough for most user needs. - </para> - <para> - While the default registration policy provides default= behavior for most registration-related aspects, one aspect requires specif= ic configuration: whether a given value for a registration property is acce= ptable by the WSRP Producer. - </para> - <para> - This is done by plugging a <classname>RegistrationProp= ertyValidator</classname> into the default registration policy. This allows= users to define their own validation mechanism. - </para> - <para> - Refer to the <trademark class=3D"trade">Javadoc</trade= mark> for <classname>org.gatein.registration.RegistrationPolicy</classname>= and <classname>org.gatein.registration.policies.RegistrationPropertyValida= tor</classname> for more details on what is expected of each method. - </para> - <para> - A defined registration policy is required for the prod= ucer to be correctly configured. Do this by specifying the qualified class = name of the registration policy. - </para> - <para> - As it is anticipated that most users will use the defa= ult registration policy, it is possible to provide the class name of a cust= om property validator instead to customize the default registration policy = behavior. Note that property validators are only used by the default policy. - </para> - <note> - <para> - Since the policy or the validator are defined via = their class name and dynamically loaded, it is important to ensure that the= identified class is available to the application server. - </para> - <para> - One way to accomplish that is to deploy the policy= implementation as a JAR file in the AS instance deploy directory. - </para> - <para> - Note also that, since both policies and validators= are dynamically instantiated, they must provide a default, no-argument con= structor. - </para> - - </note> - - </section> - = - - </section> - = - <section id=3D"sect-Reference_Guide_eXo_JCR_1.14-Configuring_the_= WSRP_Producer-WSRP_Validation_Mode"> - <title>WSRP Validation Mode - - The lack of conformance kit and the wording of the WSRP sp= ecification leaves room for differing interpretations, resulting in interop= erability issues. It is therefore possible to encounter issues when using c= onsumers from different vendors. +
+ 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. - - Experience of these issues has produced a way to relax the= validation that the WSRP producer performs on the data provided by consume= rs to help with interoperability by accepting data that would normally be i= nvalid. + + 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. - - Note that the our validation algorithm is only relaxed on = aspects of the specification that are deemed harmless such as invalid langu= age codes. + + 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. - - By default, the WSRP producer is configured in strict mode= . If you experience issues with a given consumer, you may attempt to relax = the validation mode. Un-checking the "Use strict WSRP compliance" checkbox = on the Producer configuration screen to do this. - + 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. = -
- = - -
- = -
- Removing WSRP + + 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. + + + +
+
+
+ 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. + - If you are not going to use WSRP in your JBoss Enterprise Port= al Platform instance, the WSRP configuration files may be left in place. Th= ey will not adversely affect your installation. - - - However, if you wish to completely remove WSRP from your porta= l installation, remove the gatein-wsrp-integration.ear= file from your application server deploy directory. - - -
- = - +
- --===============7002836502574970605==--