com.ibm.portal.propertybroker.service
Interface PropertyBrokerContextPassingService

All Superinterfaces:

PortletService

public interface PropertyBrokerContextPassingService
extends PortletService

An interface used to pass context information to portlets. The context is a set of property value which is provided by a portlet and can be either delivered to multiple portlets in the target page(which may be a dynamically launched page or a static page) or a special portlet in the current page. It should be used by portlets written to the JSR-168 APIs; an analogous interface called com.ibm.wps.pb.service.PropertyBrokerContextPassingService exists for use by portlets written to the IBM portlet API.

The PropertyBrokerContextPassingService interface is implemented by a PortletService. A portlet can obtain the service by using JNDI. A boolean guard may be used to guard uses of the PropertyFactory by the portlet; this will enable the portlet to execute correctly in JSR-168 compliant portlet containers outside of WebSphere Portal. A snippet of the JNDI lookup code:


boolean contextPassingServiceAvailable = false;
PropertyBrokerContextPassingService contextPassingService = null;

try {
Context ctx = new InitialContext();
PortletServiceHome serviceHome = (PortletServiceHome) ctx.lookup("portletservice/com.ibm.portal.propertybroker.service.PropertyBrokerContextPassingService");
contextPassingService = (PropertyBrokerContextPassingService)serviceHome.getPortletService(com.ibm.portal.propertybroker.service.PropertyBrokerContextPassingService.class);
contextPassingServiceAvailable = true;
}
catch(Throwable t) {
}


Since:

5.1.0.1

Method Summary

void	changedProperties(javax.portlet.ActionRequest request, javax.portlet.ActionResponse response, ObjectID targetPageId, PropertyValue[] pageContext) This method is invoked to pass an array of property values (referred to as context) to be passed to portlets on the page identified by the target page id.
void	changedPropertiesForPortlet(javax.portlet.ActionRequest request, javax.portlet.ActionResponse response, ObjectID targetPortletWindowId, PropertyValue[] context) This method is invoked to pass an array of property values (referred to as context) to be passed to a portlet on the current page, identified by the target portlet window id.

Method Detail

changedProperties

void changedProperties(javax.portlet.ActionRequest request,
                       javax.portlet.ActionResponse response,
                       ObjectID targetPageId,
                       PropertyValue[] pageContext)
                       throws PropertyBrokerServiceException

This method is invoked to pass an array of property values (referred to as context) to be passed to portlets on the page identified by the target page id. The next time the target page is viewed, the properties are delivered to portlets which have indicated through special settings that they are enabled for receiving context. For such portlets, the context is delivered (with possibly some additional filtering), using the setProperties method in the com.ibm.wps.pb.portlet.PropertyListener interface, for portlets written to the IBM portlet API, and by using a special portlet action for JSR 168 compliant portlets.

A JSR-168 compliant portlet which wishes to participate in receiving the context must provide a read-only preference attribute named com.ibm.portal.context.enable and set its value to true. Such portlets will be passed the context through invocation of the processAction method, with an action request parameter named com.ibm.portal.action set to a value of com.ibm.portal.context.receive. A portlet written to the IBM portlet API needs to specify the attribute using a portlet configuration setting.

The context is passed as a java.util.Map object, set as an action request attribute named com.ibm.portal.context. The set of properties passed via the map may be filtered from the context if the target portlet indicates that additional filtering should be applied, as part of its deployment descriptor information. By default, no filtering is applied, but additional filtering will be applied if a read-only preference attribute named com.ibm.portal.context.filter.type is set to one of the following values:
filter-none - this indicates no filtering, which is the default
filter-on-type - the context will be filtered so that only the entries whose property type matches the type of a registered input property for the portlet will be delivered
filter-on-name-and-type - the type-based filtering of filter-on-type will be applied, but, in addition, the filtered property must match on the name attribute as well
A portlet written to the IBM portlet API can also specify the same values for the filter type, using a portlet configuration setting with the same name.

The context is scoped to the current user session, and is stored by the property broker from the time this method is invoked to the time the target page is next viewed in the session, at which point the context is distributed. A context can be set only once in a request. Subsequent attempts to set contexts will result in PropertyBrokerServiceException being thrown. This behavior may change in future releases.

Parameters:

request - an ActionRequest object corresponding to the current action request

response - an ActionResponse object corresponding to the current action response

targetPageId - an ObjectID corresponding to the target page to which the context is to be passed

pageContext - an array of PropertyValue objects representing the context to be distributed to the portlets on the target page

Throws:

PropertyBrokerServiceException - if any problem is encountered

The runtime exception java.lang.IllegalArgumentException is thrown if any of the values in the pageContext are not valid e.g. missing required fields

PropertyBrokerServiceException

See Also:

PropertyValue, Property, PropertyFilterType, PropertyListener, PropertyBrokerServiceException

changedPropertiesForPortlet

void changedPropertiesForPortlet(javax.portlet.ActionRequest request,
                                 javax.portlet.ActionResponse response,
                                 ObjectID targetPortletWindowId,
                                 PropertyValue[] context)
                                 throws PropertyBrokerServiceException

This method is invoked to pass an array of property values (referred to as context) to be passed to a portlet on the current page, identified by the target portlet window id. The properties will be delivered to the target portletin the current event cycle. The target must have indicated through special settings that it is enabled for receiving context. For such portlets, the context is delivered (with possibly some additional filtering), using a special portlet action for JSR 168 compliant portlets.

A JSR 168 compliant portlet which wishes to participate in receiving the context must provide a read-only preference attribute named com.ibm.portal.context.enable and set its value to true. Such portlets will be passed the context through invocation of the processAction method, with an action request parameter named com.ibm.portal.action set to a value of com.ibm.portal.context.receive.

The context is passed as a java.util.Map object, set as an action request attribute named com.ibm.portal.context. The set of properties passed via the map may be filtered from the context if the target portlet indicates that additional filtering should be applied, as part of its deployment descriptor information. By default, no filtering is applied, but additional filtering will be applied if a read-only preference attribute named com.ibm.portal.context.filter.type is set to one of the following values:
filter-none - this indicates no filtering, which is the default
filter-on-type - the context will be filtered so that only the entries whose property type matches the type of a registered input property for the portlet will be delivered
filter-on-name-and-type - the type-based filtering of filter-on-type will be applied, but, in addition, the filtered property must match on the name attribute as well

Parameters:

request - an ActionRequest object corresponding to the current action request

response - an ActionResponse object corresponding to the current action response

targetPortletWindowId - an ObjectID corresponding to the target portlet window to which the context is to be passed

context - an array of PropertyValue objects representing the context to be distributed to the target portlet

Throws:

PropertyBrokerServiceException - if any problem is encountered

The runtime exception java.lang.IllegalArgumentException is thrown if any of the values in the context are not valid e.g. missing required fields

PropertyBrokerServiceException

See Also:

PropertyValue, Property, PropertyFilterType,