portlet.xml

The portlet.xml is the Portlet API descriptor for portlets. The entire contents of the file is indexed and stored in the Jetspeed registry database. Typical content includes:

• Portlet Name, description, display name
• Implementing class
• Init Parameters
• Supported Mime Types / Modes
• Supported Locales
• Resource Bundle Information / Localization (titles, keywords)
• Default Portlet Preferences

Refer to the Portlet Specification for more information on the portlet.xml.

jetspeed-portlet.xml

The jetspeed-portlet.xml is used for configuration of specific Jetspeed features not found in other portals such as parallel rendering. The jetpeed-portlet.xml is made up of a set of elements extending the portlet application definition, and then repeatable sections for each portlet (very much like the portlet.xml). Here is a look at an example portlet application elements:

					
   <js:security-constraint-ref>admin</js:security-constraint-ref>
 
    <dc:title>Jetspeed-2 Administration Portlets</dc:title>
    <dc:title xml:lang="en">Jetspeed-2 Administration Portlets</dc:title>
    <dc:creator>J2 Team</dc:creator>
    <js:metadata name="pa-version">2.2</js:metadata>

Notice the dc: prefixed settings refer to a Dublin Core XML schema. The js:metadata tag provides the version number of the portlet application. This is used by Jetspeed's Versioned deployment for clusters in order to determine when a new version of the application WAR is ready for deployment.

Addtionally, a portlet application can be secured with the js:security-constraint-ref tag, referencing a security constraint. Security constraints allow you to protect an entire portlet application securely. For instance you may want to require the 'admin' role restricting edit mode on all portlets in this application. Or you may require the 'developer' role to restrict users from viewing portlets in this application. Constraints secure access to portlets or applications.

By default, render-time checking of these global security constraints is disabled. So for 'view', if someone with appropriate permissions has added a portlet to a page visible to a user, the user will be able to view (but only view) the portlet. This happens even if there is a global portlet-level constraint intended to prevent the user viewing all instances of the portlet. Access is therefore controlled by pages and fragments in the PSML, and by controls on the selection and adding of portlets.

If render-time checking is enabled (default: false), a portlet which is not accessible to be viewed by the user, regardless of the current page or fragment, will not be rendered, and an "Access Denied" error message will be rendered instead. To enable this feature, change a Spring configuration setting in WEB-INF/assembly/aggregation.xml. Find the bean with id="org.apache.jetspeed.aggregator.PortletRenderer" and change the 5th constructor-arg element from false -> true (see also inline comment in the bean definition)

<!-- Portlet Renderer -->
<bean id="org.apache.jetspeed.aggregator.PortletRenderer"
class="org.apache.jetspeed.aggregator.impl.PortletRendererImpl"
init-method="start" destroy-method="stop">
<meta key="j2:cat" value="default" />
<constructor-arg>
<ref bean="org.apache.pluto.PortletContainer" />
</constructor-arg>
<constructor-arg>
<ref bean="org.apache.jetspeed.aggregator.WorkerMonitor" />
</constructor-arg>
<constructor-arg>
<ref bean="PortalStatistics" />
</constructor-arg>
<constructor-arg>
<ref bean="org.apache.jetspeed.aggregator.PortletTrackingManager" />
</constructor-arg>
<!-- flag indicating whether to check jetspeed-portlet.xml security
constraints
before rendering a portlet. If security check fails, do not display
portlet content
-->
<constructor-arg type="boolean">
<value>true</value>
</constructor-arg>
<constructor-arg>
<ref bean="org.apache.jetspeed.security.SecurityAccessController" />
</constructor-arg>
<constructor-arg>
<ref bean="portletContentCache" />
</constructor-arg>
</bean>

Portlets can also be further defined in the jetspeed-security.xml file. The portlet-name tag allows us to map back to the main portlet.xml file, matching the portlet by name. Again, we have a js:security-constraint-ref tag. This time, we are assigning a security constraint to just one portlet. This constraint overrides the portlet application wide security constraint tag. We also have similar Dublin Core tags for extended metadata.

    <portlet>
        <portlet-name>LoginPortlet</portlet-name>
        <js:security-constraint-ref>public-view</js:security-constraint-ref>
        <dc:title>Login Portlet</dc:title>
        <dc:creator>J2 Team</dc:creator>
    </portlet>

Another setting is a hint to the Jetspeed Customizer's Portlet Selector feature:

                <js:metadata name="selector.conditional.role">admin</js:metadata>

The js:metadata tag with the name attribute set to selector.conditional.role means that only users with the role named admin will be able to see this portlet in the portlet selector. All other users will not see this portlet in the selector. By setting the conditional role to *, you are telling Jetspeed that this portlet should never appear in the portlet selector.

There is a global setting in the jetspeed.properties file allowing you to merge servlet request parameters with portlet parameters. This is useful in Portlet 1.0 applications that need shared render parameters, or if you need to communicate with your portlet via the URL in some rare cases. This global feature is also available on a per portlet basis with the merge.portal.parameters.with.portlet.parameters setting. The second line below, merge.portal.parameters.before.portlet.parameters simply determines whether servlet parameters should be merged before or after portlet parameters

			
         <js:metadata name="merge.portal.parameters.with.portlet.parameters">true</js:metadata>
         <js:metadata name="merge.portal.parameters.before.portlet.parameters">true</js:metadata>

When you have portlets in certain frameworks, they may submit actions when they should be submitting render navigations. If this is the case, we consider this non-standard action behavior. In this case, we do not want cached portlets to be required to refresh while navigating around the portlet. To handle this, we have the nonStandardAction setting.

			
   <js:metadata name="nonStandardAction">true</js:metadata>

Jetspeed allows you to define mapping window states in the jetspeed-portlet.xml. In the example below, we are mapping the window state named popup to an existing window state named solo. Note this setting is portlet application wide.

			
    <custom-window-state>
      <name>popup</name>
      <mapped-name>solo</mapped-name> 
    </custom-window-state>

Finally, for enabling parallel rendering, you can set the metadata attribute timeout. This value is in milliseconds. It serves two purposes: (1) the presence of it enables parallel rendering, and (2) the value determines how long Jetspeed will give this portlet to complete rendering before it times out and abandons rendering the portlet.

			
   <js:metadata name="timeout">3000</js:metadata>

Extended metadata can also be added to the portlets using Dublin Core. This metadata conforms to the Dublin Core DCMI format DCMI allows for extended metadata, including localized data for example:

			
   <dc:title>Title 1</dc:title>
    <dc:title xml:lang="en">Eng Title</dc:title>
    <dc:title xml:lang="fr">Fr Title</dc:title>
    <dc:subject xml:lang="sp">Spanish Subject</dc:subject>
    <dc:creator>Default Jeremy Ford</dc:creator>
    <dc:coverage>Default Coverage</dc:coverage>
    <dc:contributor>Default Contributor</dc:contributor>
    <dc:description>Default Description</dc:description>
    <dc:format>Default Format</dc:format>
    <dc:identifer>Default Identifier</dc:identifer>
    <dc:language>Default Language</dc:language>
    <dc:publisher>Default Publisher</dc:publisher>
    <dc:relation>Default Relation</dc:relation>
    <dc:right>Default Right</dc:right>
    <dc:source>Default Source</dc:source>
    <dc:type>Default Type</dc:type>

Services

The jetspeed-portlet.xml is also used to define required Jetspeed services. If your portlet requires a Jetspeed service it must reference the service by name in the descriptor, for example:

			
	<js:services>        
        <js:service name='ApplicationServerManager'/>
        <js:service name='DeploymentManager'/>
		<js:service name='EntityAccessor'/>
        <js:service name='GroupManager'/>    
        <js:service name='PageManager'/>    
	</js:services>

Registry Administration

Jetspeed provides several Registry Administrative portlets:

• Portlet Application Manager
• Portlet Application Life Cycle Manager