Overview

Package

Class

Tree

Serialized

Deprecated

Index

Help

PREV class NEXT class

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.ibm.wps.pb.service
Interface PropertyBrokerService

All Superinterfaces:

org.apache.jetspeed.portlet.service.PortletService

All Known Subinterfaces:

PropertyBrokerServiceExtended

public interface PropertyBrokerService

extends org.apache.jetspeed.portlet.service.PortletService

This interface is for use by portlets written to the IBM portlet API. An analogous interface, com.ibm.portal.propertybroker.service.PropertyBrokerService is available for portlets written to the JSR-168 API.

The public interface provided by the Property Broker service. It provides methods for the portlet to publish property changes, programmatically activate or deactivate actions for a session, programmatically register action sets or property sets, and to programmatically generate Click-to-Action menus. For simple uses of Click-to-Action, this interface need not be used; the portlet can register actions and properties by declaring them in a WSDL file, and Click-to-Action menus can be generated by using JSP tags from a custom tag library. The PropertyBrokerService interface is implemented by a PortletService. The following code fragment is an example of how a reference to the PropertyBrokerService may be obtained:

PropertyBrokerService pbService = null;
PortletConfig portletConfig = null;
...
//portletConfig must have been initialized to the PortletConfig for this portlet
try {
pbService = (PropertyBrokerService) portletConfig.getContext().getService(PropertyBrokerService.class);
} catch(Exception e) {
//handle exception
}


Since:

5.0

See Also:

PropertyListener, PortletService

Method Summary
void	activateActions(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings settings, java.lang.String[] actionNames) Actions which are not automatically activated upon portlet startup are activated explicitly using this call.
boolean	areCrossPageWiresActive(org.apache.jetspeed.portlet.PortletRequest request, Property property) Returns true if cross page wires exist with the specified property and the calling portlet entity as the source, and at least one of the wires is to an active target.
boolean	areWiresActive(org.apache.jetspeed.portlet.PortletRequest request, Property property) Returns true if wires exist with the specified property and the calling portlet entity as the source, and at least one of the wires is to an active target.
void	changedProperties(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletConfig config, PropertyValue[] properties) Publishes changes in properties.
void	clearSessionState(org.apache.jetspeed.portlet.PortletSession session) Reverts the state of all actions which were programmatically activated or deactivated for the current session using the activateActions or deactivateActions calls.
void	deactivateActions(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings settings, java.lang.String[] actionNames) Actions which are active for the session are deactivated using this call.
java.lang.String	generateActionTriggerControl(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletResponse response, PropertyValue[] properties, java.lang.String caption, java.lang.String description) Returns markup to generate a Click-to-Action menu for triggering actions which can process any one of the set of properties passed to this method.
java.lang.String	generateActionTriggerControl(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletResponse response, PropertyValue property, boolean broadcast) Returns markup for displaying a Click-to-Action menu for triggering actions which can process the property passed to this method.
Action[]	getActions(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings settings) Deprecated.
ActionTriggerMarkup	getActionTriggerMarkup(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletResponse response, PropertyValue[] properties, java.lang.String caption, java.lang.String description) Returns an interface allowing access to markup to generate a Click-to-Action menu for triggering actions which can process any one of the set of properties passed to this method.
ActionTriggerMarkup	getActionTriggerMarkup(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletResponse response, PropertyValue property, boolean broadcast) Returns an interface allowing access to markup for displaying a Click-to-Action menu for triggering actions which can process the property passed to this method.
Action[]	getActiveActions(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings settings) Returns an array of Action objects which are registered for this portlet and are currently active.
Action[]	getAllActions(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings settings) Returns all the actions (active or inactive) registered by the calling portlet.
Property[]	getAllProperties(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings settings) Returns all the properties registered by the calling portlet.
Property[]	getProperties(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings settings) Deprecated.
boolean	isWired(org.apache.jetspeed.portlet.PortletRequest request, Property property) Returns true if wires exist with the specified property and the calling portlet entity as the source.
boolean	isWiredAcrossPages(org.apache.jetspeed.portlet.PortletRequest request, Property property) Returns true if cross page wires exist with the specified property and the calling portlet entity as the source.
void	registerActions(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings portletSettings, Action[] actions) Registers an array of Actions for a given portlet with the PropertyBrokerService.
void	registerProperties(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings settings, Property[] properties) Registers the properties which are produced or consumed by the portlet.
void	unregisterActions(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings portletSettings) Unregisters all previously registered actions for the specified portlet.
void	unregisterProperties(org.apache.jetspeed.portlet.PortletRequest request, org.apache.jetspeed.portlet.PortletSettings settings) Unregisters all properties which are currently registered on behalf of the portlet.

Method Detail

registerProperties

public void registerProperties(org.apache.jetspeed.portlet.PortletRequest request,
                               org.apache.jetspeed.portlet.PortletSettings settings,
                               Property[] properties)
                        throws PropertyBrokerServiceException,
                               InvalidPropertyException

Registers the properties which are produced or consumed by the portlet. Each property must have a unique name. If the portlet provides a WSDL file, properties will be automatically registered, and this method need not be invoked. If actions are registered programmatically using registerActions, the associated properties will be automatically registered also. This method need only be called to register properties which are not associated with actions, i.e. by portlets implementing PropertyListener. This call needs to be made once only after the portlet is installed, the property set is then stored persistently for the portlet. Subsequent calls will update and/or add to the existing property set.

Parameters:

request - the PortletRequest object for current portlet request

settings - the PortletSettings object identifying the calling portlet

properties - an array of Property objects

Throws:

PropertyBrokerServiceException - is thrown for general problems encountered in registering the properties.

InvalidPropertyException - is thrown if any property is invalid e.g. is missing a required field.

See Also:

Property

unregisterProperties

public void unregisterProperties(org.apache.jetspeed.portlet.PortletRequest request,
                                 org.apache.jetspeed.portlet.PortletSettings settings)
                          throws PropertyBrokerServiceException

Unregisters all properties which are currently registered on behalf of the portlet. Properties are automatically unregistered by the Property Broker when the portlet is uninstalled, so this method rarely needs to be invoked explicitly by the portlet.

Parameters:

request - the PortletRequest object for the current portlet request

settings - the PortletSettings object identifying the calling portlet

Throws:

PropertyBrokerServiceException - is thrown if any problem is encountered

registerActions

public void registerActions(org.apache.jetspeed.portlet.PortletRequest request,
                            org.apache.jetspeed.portlet.PortletSettings portletSettings,
                            Action[] actions)
                     throws PropertyBrokerServiceException

Registers an array of Actions for a given portlet with the PropertyBrokerService. Each action must have a unique name. The registration happens automatically when the portlet is initialized, if a WSDL file describing the actions has been provided. The actions are made available for invocation using Click-to-Action and as the target of wires from other portlets. Any properties associated with the actions which have not been registered earlier are automatically registered. Any actions registered earlier will be removed. Actions registered once are stored persistently as long as the portlet remains installed in the portal; hence, a check should be made if actions have already been registered using the getAllActions method before invoking this method. Actions registered are applicable for all instances of the calling portlet on all pages. So this call should usually be made very early in a portlet's lifecycle.

Parameters:

request - the PortletRequest object identifying the current portlet request

portletSettings - the PortletSettings object identifying the calling portlet

actions - the array of supported actions.

Throws:

PropertyBrokerServiceException - is thrown if the registration failed for any reason.

See Also:

Action, getAllActions(org.apache.jetspeed.portlet.PortletRequest, org.apache.jetspeed.portlet.PortletSettings)

unregisterActions

public void unregisterActions(org.apache.jetspeed.portlet.PortletRequest request,
                              org.apache.jetspeed.portlet.PortletSettings portletSettings)
                       throws PropertyBrokerServiceException

Unregisters all previously registered actions for the specified portlet. The actions are removed for all instances of the portlet on all pages. All properties associated with the actions are automatically unregistered. This method is automatically invoked when the portlet is uninstalled from the portal. Rarely should a portlet need to invoke this method.

Parameters:

request - the PortletRequest object identifying the current portlet request

portletSettings - the PortletSettings object identifying the calling portlet

Throws:

PropertyBrokerServiceException - is thrown if any problem is encountered

changedProperties

public void changedProperties(org.apache.jetspeed.portlet.PortletRequest request,
                              org.apache.jetspeed.portlet.PortletConfig config,
                              PropertyValue[] properties)
                       throws IllegalStateException,
                              PropertyBrokerServiceException

Publishes changes in properties. May be called during the portlet's event phase only. This includes the beginEventPhase method of the EventPhaseListener interface, the actionPerformed method of the ActionListener interface, and the setProperties method of the PropertyListener interface. All properties must have been registered earlier, implicitly or explicitly. A simpler alternative to explicitly invoking this method is often applicable: declare output parameters for registered actions (either programmatically or via a WSDL declaration), in which case the action may bind the values of the output parameters on invocation, and the runtime will transfer the values as if the changedProperties method had been explicitly invoked.

Parameters:

request - the PortletRequest object for the current request

config - the PortletConfig object for the calling portlet

properties - an array of PropertyValue objects containing the changed properties.

Throws:

IllegalStateException - if invoked outside the event phase

PropertyBrokerServiceException - is thrown if any problem is encountered

See Also:

PropertyValue, PropertyListener.setProperties(org.apache.jetspeed.portlet.PortletRequest, com.ibm.wps.pb.property.PropertyValue[]), org.apache.jetspeed.portlet.event.ActionListener#actionPerformed, com.ibm.wps.portlet.event.EventPhaseListener#beginEventPhase

generateActionTriggerControl

public java.lang.String generateActionTriggerControl(org.apache.jetspeed.portlet.PortletRequest request,
                                                     org.apache.jetspeed.portlet.PortletResponse response,
                                                     PropertyValue property,
                                                     boolean broadcast)
                                              throws PropertyBrokerServiceException

Returns markup for displaying a Click-to-Action menu for triggering actions which can process the property passed to this method. This method provides the function exposed through the encodeProperty Click-to-Action JSP tag. It may be used to generate Click-to-Action menus when it is not possible to use JSPs.
Generates markup to be written to the response stream which provides the end-user with a means for visually selecting portlet actions which can process the specified property and sending the property value to these actions The locale for the request is used for any locale-specific markup. If the property has not been wired to targets, a match is performed on the type of the property and the markup generated shows an icon which displays a pop-up menu of matching actions when clicked. If the property has been wired to targets, the markup generated shows an icon which causes the wired actions to be fired when clicked. The icons generated for the wired and non-wired cases differ slightly to offer a visual cue to the user as to which case is in effect.

Parameters:

request - the PortletRequest object for the current request

response - the PortletResponse object for the current request

property - a PropertyValue object holding the property and its value

broadcast - a boolean, if true an additional meta-action to trigger all matching portlet actions is generated.

Returns:

a String containing the markup

Throws:

PropertyBrokerServiceException - thrown if any problem is encountered creating the menu markup

generateActionTriggerControl

public java.lang.String generateActionTriggerControl(org.apache.jetspeed.portlet.PortletRequest request,
                                                     org.apache.jetspeed.portlet.PortletResponse response,
                                                     PropertyValue[] properties,
                                                     java.lang.String caption,
                                                     java.lang.String description)
                                              throws PropertyBrokerServiceException

Returns markup to generate a Click-to-Action menu for triggering actions which can process any one of the set of properties passed to this method. This method provides the function exposed through the encodeProperties Click-to-Action JSP tag. It may be used to generate Click-to-Action menus when it is not possible to use JSPs.
Takes an array of property values and generates markup to display a visual control in the form of a clickable icon which allows the end-user to trigger all actions matching any property in the array at once. Useful for allowing user-driven resync on a set of related information - e.g. all the information in a table row. See the description of the alternate generateActionTriggerControl method for details on the markup generated.

Parameters:

request - the PortletRequest object

response - the PortletResponse object

properties - an array of PropertyValue containing the descriptions and values of the properties to be passed to the actions

caption - the string which will be used to visually identify to the user the actions which will be taken.

description - a descriptive string expanding on the caption

Returns:

the string containing the markup to for displaying the visual control

Throws:

PropertyBrokerServiceException - thrown if any problem was encountered creating the markup

getActionTriggerMarkup

public ActionTriggerMarkup getActionTriggerMarkup(org.apache.jetspeed.portlet.PortletRequest request,
                                                  org.apache.jetspeed.portlet.PortletResponse response,
                                                  PropertyValue property,
                                                  boolean broadcast)
                                           throws PropertyBrokerServiceException

Returns an interface allowing access to markup for displaying a Click-to-Action menu for triggering actions which can process the property passed to this method. Performs the same matching logic as the generateActionTriggerControl method, but returns the markup in a form that may be embedded with custom elements, rather than the standard icon that is provided. Allows the generated Click-to-Action menu to be associated with arbitrary clickable elements in the markup generated by the portlet.

Parameters:

request - the PortletRequest object for the current request

response - the PortletResponse object for the current request

property - a PropertyValue object holding the property and its value description and value

broadcast - a boolean, if true an additional meta-action to trigger all matching portlet actions is generated.

Returns:

a String containing the markup

Throws:

PropertyBrokerServiceException - is thrown if any problem is encountered

See Also:

ActionTriggerMarkup, generateActionTriggerControl(PortletRequest, PortletResponse,PropertyValue, boolean)

getActionTriggerMarkup

public ActionTriggerMarkup getActionTriggerMarkup(org.apache.jetspeed.portlet.PortletRequest request,
                                                  org.apache.jetspeed.portlet.PortletResponse response,
                                                  PropertyValue[] properties,
                                                  java.lang.String caption,
                                                  java.lang.String description)
                                           throws PropertyBrokerServiceException

Returns an interface allowing access to markup to generate a Click-to-Action menu for triggering actions which can process any one of the set of properties passed to this method. Performs the same matching logic as the generateActionTriggerControl method, but returns the markup in a form that may be embedded with custom elements, rather than the standard icon that is provided. Allows the generated Click-to-Action menu to be associated with arbitrary clickable elements in the markup generated by the portlet.

Parameters:

request - the PortletRequest object

response - the PortletResponse object

properties - an array of PropertyValue containing the descriptions and values of the properties to be passed to the actions

caption - the string which will be used to visually identify to the user the actions which will be taken.

description - a descriptive string expanding on the caption

Returns:

the string containing the markup to for displaying the visual control

Throws:

PropertyBrokerServiceException - is thrown if any problem is encountered

See Also:

ActionTriggerMarkup, generateActionTriggerControl(PortletRequest, PortletResponse,PropertyValue[], String, String)

getAllProperties

public Property[] getAllProperties(org.apache.jetspeed.portlet.PortletRequest request,
                                   org.apache.jetspeed.portlet.PortletSettings settings)
                            throws PropertyBrokerServiceException

Returns all the properties registered by the calling portlet. This method may be invoked to determine if properties were registered earlier. Usually, since properties are registered persistently, they need to be registered once only, and if this method returns a non-empty array, it means registration is not required. Invoking this method to check if properties are registered has less of a performance impact than invoking registerProperties multiple times.

Parameters:

request - the PortletRequest object for the current portlet request

settings - the PortletSettings object for the calling portlet

Returns:

an array of Property objects which are registered for this portlet

Throws:

PropertyBrokerServiceException - is thrown if any problem is encountered

See Also:

registerProperties(org.apache.jetspeed.portlet.PortletRequest, org.apache.jetspeed.portlet.PortletSettings, com.ibm.wps.pb.property.Property[])

getProperties

public Property[] getProperties(org.apache.jetspeed.portlet.PortletRequest request,
                                org.apache.jetspeed.portlet.PortletSettings settings)
                         throws PropertyBrokerServiceException

Deprecated.

This method is deprecated. Use getAllProperties instead.

Throws:

PropertyBrokerServiceException

See Also:

getAllProperties(org.apache.jetspeed.portlet.PortletRequest, org.apache.jetspeed.portlet.PortletSettings)

getActiveActions

public Action[] getActiveActions(org.apache.jetspeed.portlet.PortletRequest request,
                                 org.apache.jetspeed.portlet.PortletSettings settings)
                          throws PropertyBrokerServiceException

Returns an array of Action objects which are registered for this portlet and are currently active. Active actions are ones that will appear in the Click-to-Action menus and will be triggered when wires to the actions are activated.

Parameters:

request - the PortletRequest object for the current request

settings - the PortletSettings object for the calling portlet

Returns:

an array of Action objects which are registered for this portlet and are currently active

Throws:

PropertyBrokerServiceException - is thrown if any problem is encountered

getActions

public Action[] getActions(org.apache.jetspeed.portlet.PortletRequest request,
                           org.apache.jetspeed.portlet.PortletSettings settings)
                    throws PropertyBrokerServiceException

Deprecated.

This method is deprecated. Use getActiveActions instead.

Throws:

PropertyBrokerServiceException

See Also:

getActiveActions(org.apache.jetspeed.portlet.PortletRequest, org.apache.jetspeed.portlet.PortletSettings)

getAllActions

public Action[] getAllActions(org.apache.jetspeed.portlet.PortletRequest request,
                              org.apache.jetspeed.portlet.PortletSettings settings)
                       throws PropertyBrokerServiceException

Returns all the actions (active or inactive) registered by the calling portlet. The method may be invoked to determine if actions were registered earlier. Usually, since actions are registered persistently, they need to be registered once only, and if this method returns a non-empty array, it means registration is not required. Invoking this method to check if actions are registered has a lower performance overhead than invoking registerActions multiple times.

Parameters:

request - the PortletRequest object for the current request

settings - the PortletSettings object for the calling portlet

Returns:

an array of Action objects which are registered for this portlet whether they are currently active or not

Throws:

PropertyBrokerServiceException - is thrown if any problem is encountered

See Also:

registerActions(org.apache.jetspeed.portlet.PortletRequest, org.apache.jetspeed.portlet.PortletSettings, com.ibm.wps.pb.property.Action[])

activateActions

public void activateActions(org.apache.jetspeed.portlet.PortletRequest request,
                            org.apache.jetspeed.portlet.PortletSettings settings,
                            java.lang.String[] actionNames)
                     throws PropertyBrokerServiceException

Actions which are not automatically activated upon portlet startup are activated explicitly using this call. This activates the actions for the current session. If any of the specified actions is already active, its state is not affected by this call.

Parameters:

request - the PortletRequest object for the current portlet request

settings - the PortletSettings object identifying the calling portlet

actionNames - the names of the actions to be activated

Throws:

PropertyBrokerServiceException - is thrown if any problem is encountered

deactivateActions

public void deactivateActions(org.apache.jetspeed.portlet.PortletRequest request,
                              org.apache.jetspeed.portlet.PortletSettings settings,
                              java.lang.String[] actionNames)
                       throws PropertyBrokerServiceException

Actions which are active for the session are deactivated using this call. This deactivates the actions for the current session. If any of the specified actions is already inactive, its state is not affected by this call. If actions are inactive, they will not appear in Click-to-Action menus or be invoked as a result of wires being activated in the current session.

Parameters:

request - the PortletRequest object for the current portlet request

settings - the PortletSettings object identifying the calling portlet

actionNames - the names of the actions to be activated

Throws:

PropertyBrokerServiceException - is thrown if any problem is encountered

clearSessionState

public void clearSessionState(org.apache.jetspeed.portlet.PortletSession session)
                       throws PropertyBrokerServiceException

Reverts the state of all actions which were programmatically activated or deactivated for the current session using the activateActions or deactivateActions calls. i.e, resets the state of all actions to their default state on initialization (active or inactive).

Parameters:

session - the current portlet session

Throws:

PropertyBrokerServiceException

See Also:

activateActions(org.apache.jetspeed.portlet.PortletRequest, org.apache.jetspeed.portlet.PortletSettings, java.lang.String[]), deactivateActions(org.apache.jetspeed.portlet.PortletRequest, org.apache.jetspeed.portlet.PortletSettings, java.lang.String[])

isWired

public boolean isWired(org.apache.jetspeed.portlet.PortletRequest request,
                       Property property)
                throws PropertyBrokerServiceException

Returns true if wires exist with the specified property and the calling portlet entity as the source.

Parameters:

request - the PortletRequest identifying the caller

property - the Property

Returns:

a boolean, true if the specified property and caller are the source of wires

Throws:

PropertyBrokerServiceException - if any problem is encountered

isWiredAcrossPages

public boolean isWiredAcrossPages(org.apache.jetspeed.portlet.PortletRequest request,
                                  Property property)
                           throws PropertyBrokerServiceException

Returns true if cross page wires exist with the specified property and the calling portlet entity as the source.

Parameters:

request - the PortletRequest identifying the caller

property - the Property

Returns:

a boolean, true if the specified property and caller are the source of cross page wires

Throws:

PropertyBrokerServiceException - if any problem is encountered

areWiresActive

public boolean areWiresActive(org.apache.jetspeed.portlet.PortletRequest request,
                              Property property)
                       throws PropertyBrokerServiceException

Returns true if wires exist with the specified property and the calling portlet entity as the source, and at least one of the wires is to an active target.

Parameters:

request - the PortletRequest identifying the caller

property - the Property

Returns:

a boolean, true if the specified property and caller are the source of at least one wire with an active target

Throws:

PropertyBrokerServiceException - if any problem is encountered

areCrossPageWiresActive

public boolean areCrossPageWiresActive(org.apache.jetspeed.portlet.PortletRequest request,
                                       Property property)
                                throws PropertyBrokerServiceException

Returns true if cross page wires exist with the specified property and the calling portlet entity as the source, and at least one of the wires is to an active target.

Parameters:

request - the PortletRequest identifying the caller

property - the Property

Returns:

a boolean, true if the specified property and caller are the source of at least one cross page wire with an active target

Throws:

PropertyBrokerServiceException - if any problem is encountered