From portal-commits at lists.jboss.org Fri May 25 00:32:24 2007 Content-Type: multipart/mixed; boundary="===============6278497443039540120==" MIME-Version: 1.0 From: portal-commits at lists.jboss.org To: portal-commits at lists.jboss.org Subject: [portal-commits] JBoss Portal SVN: r7333 - docs/trunk/referenceGuide/en/modules. Date: Fri, 25 May 2007 00:32:24 -0400 Message-ID: --===============6278497443039540120== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: chris.laprun(a)jboss.com Date: 2007-05-25 00:32:24 -0400 (Fri, 25 May 2007) New Revision: 7333 Modified: docs/trunk/referenceGuide/en/modules/wsrp.xml Log: - Added information on level of support of WSRP 1.0 spec. - Added information on processing of Producer descriptors. - Started adding info about configuration portlet. - Need to update graphics. Modified: docs/trunk/referenceGuide/en/modules/wsrp.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- docs/trunk/referenceGuide/en/modules/wsrp.xml 2007-05-25 02:37:52 UTC (= rev 7332) +++ docs/trunk/referenceGuide/en/modules/wsrp.xml 2007-05-25 04:32:24 UTC (= rev 7333) @@ -39,6 +39,33 @@ = + Level of support in JBoss Portal + The WSRP Technical Committee defined WSRP + Use Profiles to help with WSRP interoperability. We will = refer to terms defined in that document in + this section. + + + JBoss Portal provides a Simple level of support for our WSRP P= roducer except that out-of-band registration + is not currently handled. We support in-band registration and per= sistent local state (which are + defined at the Complex level). + + On the Consumer side, JBoss Portal provides a Medium level of = support for WSRP, except that we only handle + HTML markup (as Portal itself doesn't handle 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 wi= ndow states or modes, as Portal doesn't either. + We do, however, support CSS on both the Producer (though it's mo= re a function of the portlets than + inherent Producer capability) and Consumer. + + While we provide a complete implementation of WSRP 1.0, we = do need to go through the + Conformance statements and + perform more interoperability testing (an area that needs to b= e better supported by the WSRP Technical + Committee and Community at large). = + + + Deploying JBoss Portal's WSRP services JBoss Portal provides a complete support of WSRP 1.0 standard = interfaces and offers both consumer and producer services. WSRP support is provided by= the portal-wsrp.sar @@ -62,7 +89,7 @@ WS (bundled with JBoss Application Server 4.0.4.GA) that prevents= the complete deployment of JBoss Portal's WSRP service if the user is not online or behind a firew= all/proxy. For this reason, we recommend that you deploy Portal on JBoss Application Server 4.0.5.GA. Alte= rnatively, you can also perform a manual - upgrade of JBoss WS, in which case we recommend that you use JBos= s WS version 1.0.4.GA (and later). + upgrade of JBoss WS, in which case we recommend that you use JBos= s WS version 1.2.1.GA (and later). Please follow the instructions on how to upgrade JBoss WS as found on JBoss Portal's wiki. @@ -72,8 +99,9 @@ Considerations to use WSRP when running Portal on a non-de= fault port If you have modified the port number on which Portal runs, = you will also need - update the port information for WSRP = - as found on JBoss Portal's wiki. + update the port information for + WSRP as found on JBoss Portal's + wiki. = @@ -89,10 +117,10 @@ = Making a portlet remotable - JBoss Portal does not, by default, expose local portlets for c= onsumption by remote WSRP consumers. In order - to make a portlet remotely available, it must be made "remotable"= by adding a remotable - element to the jboss-portlet.xml deployment = descriptor for that portlet. If a - jboss-portlet.xml file does not exist, one m= ust be added to the + JBoss Portal does NOT, by d= efault, expose local portlets for consumption by remote WSRP + consumers. In order to make a portlet remotely available, it must= be made "remotable" by adding a + remotable element to the jboss-por= tlet.xml deployment descriptor for + that portlet. If a jboss-portlet.xml file do= es not exist, one must be added to the WEB-INF folder of the web application contai= ning the portlet. In the following example, the "BasicPortlet" portlet is specif= ied as being remotable. The @@ -101,9 +129,7 @@ - + BasicPortlet @@ -113,7 +139,8 @@ It is also possible to specify that all the portlets declared wit= hin a given jboss-portlet.xml - file have a specific "remotable" status by default. Usually, this= feature will be used to remotely expose + file have a specific "remotable" status by default. This is done = by adding a single remotable + element to the root portlet-app element. Usu= ally, this feature will be used to remotely expose several portlets without having to specify the status for all the= declared portlets. Let's look at an example: @@ -154,7 +181,8 @@ Consuming JBoss Portal's WSRP portlets from a remote Consumer= WSRP Consumers vary a lot as far as how they are configured. M= ost of them require that you either specify the URL for the Producer's WSDL definition or the URLs for the in= dividual endpoints. Please refer to your - Consumer's documentation for specific instructions. + Consumer's documentation for specific instructions. For instructi= ons on how to do so in JBoss Portal, please + refer to . JBoss Portal's Producer is automatically set up when you deploy a= portal instance with the WSRP service. = @@ -170,20 +198,18 @@ = - + Consuming remote WSRP portlets in JBoss Portal Overview To be able to consume WSRP portlets exposed by a remote produc= er, JBoss Portal's WSRP consumer needs to know - how to access that remote producer. One can configure access t= o a remote producer via - *-wsrp.xml descriptors. These files can b= e dropped in the deploy directory of the JBoss - application server or nested in .sar files. It is possible to = configure access to several different - producers within a single -wsrp.xml file = or use one file per producer. + how to access that remote producer. One can configure access t= o a remote producer using WSRP Producer + descriptors. Alternatively, a portlet is provided to configure= remote producers. - Once a remote producer has been configured in a -wsr= p.xml file, it becomes available - in the list of portlet provider in the Management portlet on t= he Admin page of JBoss Portal. You can then + Once a remote producer has been configured, it can be made ava= ilable + in the list of portlet providers in the Management portlet on = the Admin page of JBoss Portal. You can then examine the list of portlets that are exposed by this producer= and configure the portlets just like you would for local portlets. @@ -194,16 +220,28 @@ identifier in the portlet providers list in the Management por= tlet of the Admin page. All local portlets marked as remotable are exposed as remote portlets via the self portlet provider so that you can check that they work as expected with= WSRP. The portal-wsrp.sar - file contains a default-wsrp.xml that con= figures this default producer. This file can - be edited or removed if needed. + file contains a WSRP Producer descriptor (default-ws= rp.xml) that configures this + default producer. This file can be edited or removed if needed. + + + + Configuring a remote producer walk-through Let's work through the steps of defining access to a remote pr= oducer so that its portlets can be - consumed within JBoss Portal. We will configure access to BEA'= s public WSRP producer. To do so, you will - need to create a -wsrp.xml file (which we= will call here - public-bea-wsrp.xml but the name does not= matter as long as it ends with - -wsrp.xml) as follows: + consumed within JBoss Portal. We will configure access to BEA'= s public WSRP producer. We will first examine + how to do so using an XML descriptor then see how the same can= be accomplished using the configuration + portlet. + + + + Using a WSRP Producer XML descriptor + + We will create a public-bea-wsrp.xml descriptor. Note that the actual name does not + matter as long as it ends with -wsrp.xml. @@ -222,12 +260,21 @@ This producer descriptor gives access to BEA's public WSRP pro= ducer. We will look at the details of the different elements later. Note for now the producer-= id element with a "bea" value. Put this file in the deploy directory and start the server (with J= Boss Portal and its WSRP service deployed). - - + + + + Using the configuration portlet + TODO + + + + Configuring access to a remote portlet + Let's now look at the Admin page and the Management portlet. C= lick on the "Portlets" link at the top to manage the portlets. Once this is done, look at the list of av= ailable portlet providers. If all went well, you should see something similar to this: = + TODO: update image @@ -241,6 +288,7 @@ the portlets exposed by the default WSRP producer. The "bea" p= rovider corresponds to BEA's public producer we just configured. Select it and click on "Change portlet pro= vider". You should now see something similar to: = + TODO: update image @@ -248,20 +296,46 @@ - From there on out, you should be able to configure WSRP portle= ts just as any other. In particular, you = + From there on out, you should be able to configure WSRP portle= ts just as any other. In particular, you can create an instance of one of the remote portlets offered by BEA's p= ublic producer just like you would create an instance of a local portlet and then assign it to a window in= a page. If you go to that page, you should see something similar to below for this portlet: = + TODO: update image + = + WSRP Producer descriptors + + + A WSRP Producer descriptor is an XML file which name ends in <= emphasis>-wsrp.xml and + which can be dropped in the deploy directory of the JBoss appl= ication server or nested in .sar files. It is + possible to configure access to several different producers wi= thin a single descriptor or use one file per + producer, depending on your needs. The DTD for the WSRP Produc= er descriptor format can be found at + portal-wsrp.sar/dtd/jboss-wsrp-consumer_2_6.dtd. + It is important to note how WSRP Producer descriptors ar= e processed. They are read the first time the + WSRP service starts and the associated information is then = put in the Portal database. Subsequent launch + of the WSRP service will use the database-stored informatio= n for all producers which identifier is + already known to Portal. More specifically, all the descrip= tors are scanned for producer identifiers. + Any identifier that is already known will be bypassed and t= he configuration associated with this remote + producer in the database will be used. If a producer identi= fier is found that wasn't already in the + database, that producer information will be processed and r= ecorded in the database. Therefore, if you + wish to delete a producer configuration, you need to delete= the associated information in the database + (this can be accomplished using the configuration portlet a= s we shall see in + ) AND= remove the associated information in any + WSRP Producer descriptor (if such information exists) as th= e producer will be re-created the next time + the WSRP is launched if that information is not removed. + + + + Required configuration information = Let's now look at which information needs to be provided to= configure access to a remote producer. @@ -304,9 +378,9 @@ <endpoint-wsdl-url> e= lements are required for a functional remote producer configuration. - + = - + Optional configuration It is also possible to provide addtional configuration, whi= ch, in some cases, might be important to establish a proper connection to the remote producer. @@ -326,7 +400,7 @@ = Additionally, some producers require consumers to register = with them before authorizing them to access their offered portlets. If you know that information beforehan= d, you can provide the required registration - information in the producer configuration so that the Portal consumer c= an register with the remote = + information in the producer configuration so that the Portal consumer c= an register with the remote producer when required. At this time, though, only simple String properties are = supported and it is not possible to configure complex registration data. This should however be sufficien= t for most cases. @@ -335,23 +409,56 @@ Registration configuration is done via the <registration-data> element. Since JBoss Portal can generate the mandatory informa= tion for you, if the remote producer does not require any registration properties, you only need to provide = an empty - <registration-datat> = element. Values for the registration properties + <registration-data> e= lement. Values for the registration properties required by the remote producer can be provided via <property> elements. See the example below for more details. Additionally= , you can override the default consumer name automatically provided by JBoss Portal via the <consumer-name> element. If you choose to provide a consumer name, please reme= mber that this should uniquely identify your consumer. + = - Examples + + + Here is the configuration of the "self" producer as found in <= emphasis>default-wsrp.xml with a + cache expiring every five minutes: + + + + + + + + + + + http://localhost:8080/portal-wsrp/Ser= viceDescriptionService + http://localhost:8080/portal-wsrp/MarkupService + http://localhost:8080/portal-wsrp/Registrati= onService + http://localhost:8080/portal-wsrp/Port= letManagementService + + + + +]]> + + + Here is an example of a WSRP descriptor with a 2 minute cac= hing time and manual definition of the endpoint URLs: = @@ -380,6 +487,8 @@ = @@ -463,9 +572,9 @@ 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 behaviors that are called= by Portal's Registration service so that + 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 - behaviors is provided and should be enough for most user ne= eds. + behavior is provided and should be enough for most user nee= ds. While the default registration policy provides default beha= vior for most registration-related aspects, @@ -538,4 +647,4 @@ - + --===============6278497443039540120==--