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:

1. The consumer and producer use different versions of ADF Faces, or
2. The consumer has additional skin-additions that the producer doesn't have or vice-versa, or
3. 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