here are probably many on going debates whether to use portlets or taskflows in a WebCenter custom portal application. Usually
the main battle on which side to take in these debates are centered around which technology enables better performance.
The good news is that both of my colleagues, Maiko Rocha and George Maggessy have posted their respective views on this topic so I will not have to further
the discussion. However, if you do plan to use portlets in a WebCenter custom portal application, this post will help you not have
the "portlet skin mismatch" issue. An example of
the presence of
the mismatch can be view from
the applications log:
The skin customsharedskin.desktop specified on
the requestMap will be used even though
the consumer's skin's styleSheetDocumentId on
the requestMap does not match
the local skin's styleSheetDocument's id. This will impact performance since
the consumer and producer stylesheets cannot be shared.
The producer styleclasses will not be compressed to avoid conflicts. A reason
the ids do not match may be
the jars are not identical on
the producer and
the consumer. For example, one might have trinidad-skins.xml's skin-additions in a jar file on
the class path that
the other does not have.
Notice that due to the mismatch
the portlet's CSS will not be able to be compressed, which will most like impact performance in the portlet's consuming portal.
The first part of
the blog will define the portlet mismatch and cover some debugging tips that can help you solve
the portlet mismatch issue. Following that I will give a complete example of
the creating, using and sharing a shared skin in both a portlet producer and
the consumer application.
Portlet Mismatch Defined
In general, when you consume/render an ADF page (or task flow) using
the ADF Portlet bridge,
the portlet (producer) would try to use
the skin of
the consumer page - this is called skin-sharing. When
the producer cannot match
the consumer skin,
the portlet would generate its own stylesheet and reference it from its markup - this is called mismatched-skin. This can happen because:
The consumer and producer use different versions of ADF Faces, or
The consumer has additional skin-additions that
the producer doesn't have or vice-versa, or
The producer does not have
the consumer skin
For case (1) & (2) above,
the producer still uses
the consumer skin ID to render its markup. For case (3),
the producer would default to using portlet skin.
If there is a skin mis-match then there may be a performance hit because:
The browser needs to fetch this extra stylesheet (though it should be cached unless expires caching is turned off)
The generated portlet markup uses uncompressed styles resulting in a larger markup
It is often not obvious when a skin mismatch occurs, unless you look for either of these indicators:
The log messages in
the producer log, for example:
The skin blafplus-rich.desktop specified on
the requestMap will not be used because
the styleSheetDocument id on
the requestMap does not match
the local skin's styleSheetDocument's id. It could mean
the jars are not identical. For example, one might have trinidad-skins.xml's skin-additions in a jar file on
the class path that
the other does not have.
View
the portlet markup inside
the iframe, there should be a <link> tag to
the portlet stylesheet resource like this (note
the CSS is proxied through consumer's resourceproxy):
<link rel=\"stylesheet\" charset=\"UTF-8\" type=\"text/css\" href=\"http:.../resourceproxy/portletId...252525252Fadf%252525252Fstyles%252525252Fcache%252525252Fblafplus-rich-portlet-d1062g-en-ltr-gecko.css... Using HTTP monitoring tool (eg, firebug, httpwatch), you can see a request is made to
the portlet stylesheet resource (see URL above)
There are a number of reasons for mismatched-skin. For skin to match
the producer and consumer must match
the following configurations:
The ADF Faces version (different versions may have different style selectors)
Style Compression, this is defined in
the web.xml (default value is false, i.e. compression is ON)
Tonal styles or themes, also defined in
the web.xml via context-params
The same skin additions (jars with skin) are available for both producer and consumer. Skin additions are defined in
the trinidad-skins.xml, using
the <skin-addition> tags. These are then aggregated from all
the jar files in
the classpath. If there's any jar that exists on
the producer but not
the consumer, or vice veras, you get a mismatch.
Debugging Tips
Ensure
the style compression and tonal styles/themes match on
the consumer and producer, by looking at
the web.xml documents for
the consumer & producer applications
It is bit more involved to determine if
the jars match. However, you can enable
the Trinidad logging to show which skin-addition it is processing. To enable this feature, update
the logging.xml log level of both
the producer and consumer WLS to FINEST. For example, in
the case of
the WebLogic server used by JDeveloper:
$JDEV_USER_DIR/system<version number>/DefaultDomain/config/fmwconfig/servers/DefaultServer/logging.xml
Add a new entry:
<logger name="org.apache.myfaces.trinidadinternal.skin.SkinUtils" level="FINEST"/>
Restart WebLogic. Run
the consumer page, you should see
the following logging in both
the consumer and producer log files. Any entries that don't match is
the cause of
the mismatch.
The following is an example of what
the log will produce with this setting:
[SRC_CLASS: org.apache.myfaces.trinidadinternal.skin.SkinUtils] [APP: WebCenter] [SRC_METHOD: _getMetaInfSkinsNodeList]
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/announcement-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/calendar-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/custComps-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/forum-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/page-service-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/peopleconnections-kudos-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/peopleconnections-wall-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/portlet-client-adf-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/rtc-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/serviceframework-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/smarttag-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.skin/in1ar8/APP-INF/lib/spaces-service-skins.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/oracle.webcenter.composer/3yo7j/WEB-INF/lib/custComps-skin.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/adf.oracle.domain.webapp/q433f9/WEB-INF/lib/adf-richclient-impl-11.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/adf.oracle.domain.webapp/q433f9/WEB-INF/lib/dvt-faces.jar!/META-INF/trinidad-skins.xml
Processing skin URL:zip:/tmp/_WL_user/adf.oracle.domain.webapp/q433f9/WEB-INF/lib/dvt-trinidad.jar!/META-INF/trinidad-skins.xml
The Complete Example
The first step is to create
the shared library.
The WebCenter documentation covering this is located here in section 15.7. In addition, our ADF guru Frank Nimphius also covers this in hes blog. Here are my steps (in JDeveloper) to create
the skin that will be used as
the shared library for both
the portlet producer and consumer.
Create a new Generic Application
Give application name (i.e. MySharedSkin)
Give a project name (i.e. MySkinProject)
Leave Project Technologies blank (none selected), and click Finish
Create
the trinidad-skins.xml
Right-click on
the MySkinProject node in
the Application Navigator and select "New"
In
the New Galley, click on "General", select "File" from
the Items, and click OK
In
the Create File dialog, name the file trinidad-skins.xml, and (IMPORTANT) give
the directory path to MySkinProject\src\META-INF
In
the trinidad-skins.xml, complete
the skin entry. for example:
<?xml version="1.0" encoding="windows-1252" ?> <skins xmlns="http://myfaces.apache.org/trinidad/skin"> <skin> <id>mysharedskin.desktop</id> <family>mysharedskin</family> <extends>fusionFx-v1.desktop</extends> <style-sheet-name>css/mysharedskin.css</style-sheet-name> </skin> </skins>
Create CSS file
In
the Application Navigator, right click on
the META-INF folder (where
the trinidad-skins.xml is located), and select "New"
In
the New Gallery, select Web-Tier-> HTML, CSS File from
the the Items and click OK
In
the Create Cascading Style Sheet dialog, give
the name (i.e. mysharedskin.css)
Ensure that
the Directory path is
the under
the META-INF (i.e. MySkinProject\src\META-INF\css)
Once
the new CSS opens in
the editor, add in a style selector. For example, this selector will style
the background of a particular panelGroupLayout:
af|panelGroupLayout.customPGL{ background-color:Fuchsia; }
Create
the MANIFEST.MF (used for deployment JAR)
In
the Application Navigator, right click on
the META-INF folder (where
the trinidad-skins.xml is located), and select "New"
In
the New Galley, click on "General", select "File" from
the Items, and click OK
In
the Create File dialog, name the file MANIFEST.MF, and (IMPORTANT) ensure that
the directory path is to MySkinProject\src\META-INF
Complete
the MANIFEST.MF, where
the extension name is
the shared library name
Manifest-Version: 1.1 Created-By: Martin Deh Implementation-Title: mysharedskin Extension-Name: mysharedskin.lib.def Specification-Version: 1.0.1 Implementation-Version: 1.0.1 Implementation-Vendor: MartinDeh
Create new Deployment Profile
Right click on
the MySkinProject node, and select New
From
the New Gallery, select General->Deployment Profiles, Shared Library JAR File from Items, and click OK
In
the Create Deployment Profile dialog, give name (i.e.mysharedskinlib) and click OK
In
the Edit JAR Deployment dialog, un-check Include Manifest File option
Select Project Output->Contributors, and check Project Source Path
Select Project Output->Filters, ensure that all items under
the META-INF folder are selected
Click OK to exit
the Project Properties dialog
Deploy
the shared lib to WebLogic (start server before steps)
Right click on MySkin Project and select Deploy
For this example, I will deploy to JDeverloper WLS
In
the Deploy dialog, select Deploy to Weblogic Application Server and click Next
Choose IntegratedWebLogicServer and click Next
Select Deploy to selected instances in
the domain radio, select Default Server (note: server must be already started), and ensure Deploy as a shared Library radio is selected
Click Finish
Open
the WebLogic console to see
the deployed shared library
The following are
the steps to create a simple test Portlet
Create a new WebCenter Portal - Portlet Producer Application
In
the Create Portlet Producer dialog, select default settings and click Finish
Right click on
the Portlets node and select New
IIn
the New Gallery, select Web-Tier->Portlets, Standards-based Java Portlet (JSR 286) and click OK
In
the General Portlet information dialog, give portlet name (i.e. MyPortlet) and click Next 2 times, stopping at Step 3
In
the Content Types, select
the "view" node, in
the Implementation Method, select
the Generate ADF-Faces JSPX radio and click Finish
Once
the portlet code is generated, open
the view.jspx in
the source editor
Based on
the simple CSS entry, which sets
the background color of a panelGroupLayout, replace the <af:form/> tag with the example code
<af:form> <af:panelGroupLayout id="pgl1" styleClass="customPGL"> <af:outputText value="background from shared lib skin" id="ot1"/> </af:panelGroupLayout> </af:form>
Since this portlet is to use
the shared library skin, in
the generated trinidad-config.xml, remove both
the skin-family tag and
the skin-version tag
In
the Application Resources view, under Descriptors->META-INF, double-click to open
the weblogic-application.xml
Add a library reference to
the shared skin library (note:
the library-name must match
the extension-name declared in
the MANIFEST.MF):
<library-ref> <library-name>mysharedskin.lib.def</library-name> </library-ref>
Notice that a reference to oracle.webcenter.skin exists. This is important if this portlet is going to be consumed by a WebCenter Portal application. If this tag is not present,
the portlet skin mismatch will happen.
Configure
the portlet for deployment
Create Portlet deployment WAR
Right click on
the Portlets node and select New
In
the New Gallery, select Deployment Profiles, WAR file from Items and click OK
In
the Create Deployment Profile dialog, give name (i.e. myportletwar), click OK
Keep all of
the defaults, however, remember
the Context Root entry (i.e. MyPortlet4SharedLib-Portlets-context-root, this will be needed to obtain
the producer WSDL URL)
Click OK, then OK again to exit from
the Properties dialog
Since
the weblogic-application.xml has to be included in
the deployment,
the portlet must be deployed as a WAR, within an EAR
In
the Application dropdown, select Deploy->New Deployment Profile...
By default EAR File has been selected, click OK
Give Deployment Profile (EAR) a name (i.e. MyPortletProducer) and click OK
In
the Properties dialog, select Application Assembly and ensure that
the myportletwar is checked
Keep all of
the other defaults and click OK
For this demo, un-check
the Auto Generate ..., and all of
the Security Deployment Options, click OK
Save All
In
the Application dropdown, select Deploy->MyPortletProducer
In
the Deployment Action, select Deploy to Application Server, click Next
Choose IntegratedWebLogicServer and click Next
Select Deploy to selected instances in
the domain radio, select Default Server (note: server must be already started), and ensure Deploy as a standalone Application radio is selected
The select deployment type (identifying
the deployment as a JSR 286 portlet) dialog appears. Keep default radio "Yes" selection and click OK
Open
the WebLogic console to see
the deployed Portlet
The last step is to create
the test portlet consuming application. This will be done using
the OOTB WebCenter Portal - Framework Application.
Create
the Portlet Producer Connection
In
the JDeveloper Deployment log, copy
the URL of
the portlet deployment (i.e. http://localhost:7101/MyPortlet4SharedLib-Portlets-context-root
Open a browser and paste in
the URL.
The Portlet information page should appear. Click on
the WSRP v2 WSDL link
Copy
the URL from
the browser (i.e. http://localhost:7101/MyPortlet4SharedLib-Portlets-context-root/portlets/wsrp2?WSDL)
In
the Application Resources view, right click on
the Connections folder and select New Connection->WSRP Connection
Give
the producer a name or accept
the default, click Next
Enter (paste in)
the WSDL URL, click Next
If connection to Portlet is succesful, Step 3 (Specify Additional ...) should appear. Accept defaults and click Finish
Add
the portlet to a test page
Open
the home.jspx. Note in
the visual editor,
the orange dashed border, which identifies
the panelCustomizable tag.
From
the Application Resources. select
the MyPortlet portlet node, and drag and drop
the node into
the panelCustomizable section. A Confirm Portlet Type dialog appears, keep default ADF Rich Portlet and click OK
Configure the portlet to use
the shared skin library
Open
the weblogic-application.xml and add
the library-ref entry (mysharedskin.lib.def) for
the shared skin library. See create portlet example above for
the steps
Since by default,
the custom portal using a managed
bean to (dynamically) determine
the skin family,
the default trinidad-config.xml will need to be altered
Open
the trinidad-config.xml in
the editor and replace
the EL (preferenceBean) for
the skin-family tag, with mysharedskin (this is
the skin-family named defined in
the trinidad-skins.xml)
Remove
the skin-version tag
Right click on
the index.html to test
the application
Notice that the JDeveloper log view does not have any reporting of a skin mismatch. In addition, since I have configured
the extra logging outlined in debugging section above, I can see
the processed skin jar in both
the producer and consumer logs:
<SkinUtils> <_getMetaInfSkinsNodeList> Processing skin URL:zip:/JDeveloper/system11.1.1.6.38.61.92/DefaultDomain/servers/DefaultServer/upload/mysharedskin.lib.def/
[email protected]/app/mysharedskinlib.jar!/META-INF/trinidad-skins.xml
