Choosing builders that use actions and events

Portlet Factory, Version 6.1.2

Choosing builders that use actions and events

The builders described in this topic use actions and events.

Task Builder you should use
Perform some processing in a model such as:

Calling a method and then returning a page.
Executing several backend calls before loading the initial page in a Model.
Use the Action List builder, which lets you add a set of one or more actions to your WebApp. Typically, all models must have an action in them called main. Most of the higher-level builders automatically create this action. However, this builder includes the ability to override this feature, so you can add your own main action list to your model, which can perform whatever processing you need.
Perform a conditional statement (for example, if two variables contain the same value, perform an action), without writing Java code. Within the Action List builder, you can build conditional statements without having to write Java code. Use the picker labeled Select Action underneath the Actions input to navigate to Special > Conditional. From there, you can select if, else, endif, and build up statements that execute an action or return a page based upon conditional logic.
Debug by sending SystemOut messages to the console. Within the Action List builder, use the picker labeled Select Action underneath the Actions input to select Special > SystemOut. This builder sends SystemOut messages to the application server console, and to the debugTracing log located in the deployed /WEB-INF/logs directory.
For example, in IBM® WebSphere® Portal server, the log files for running as a portlet are found in the deployed portlet WAR directory. If the portlet is run standalone, log files can be found in the deployed enterprise application directory.
Assign or append values to variables. For example, to append or replace what is in a given variable with the results of a method call, an argument, or another XML variable. Within the Action List builder, select the Assignment option underneath Special within the action picker.
Use some Java code in my model.
Use the Linked Java Object builder to point at a Java class. It then adds the public methods of that class to your WebApp, so you can call them from any builder input where you specify an action. In some scenarios, you could also use the Method builder. This builder lets you easily create a simple Method, which can make calls to display pages, call methods, or execute service calls. If you need significant amounts of hand-coded Java, you should write a Java class and bring it into the Model with a Linked Java Object builder instead of using Method builders. This will make the Model easier to manage, and the code assistance is better in the Eclipse Java editor. In general, Method builders in your Model should only contain small amounts of “glue” code.
Add error handling to my model. The Error Handler builder catches Java exceptions that may occur within the run-time execution of a Web application’s actions. The error handling can be specified on any action, such as a page, method or action list. You can also set a general handler for the entire application to be used if an action has no error handler. This type of error handling is modeled closely after the Java try-catch exception handling and JSP page directive, where each page can set the error page at design time. In all of these cases the lowest-level handler (catch) is called to handle the exception.
Add caching to my model.
For example, you are populating an Employee select list from a database call. Because the list of employees does not change that frequently, you want to cache the content when received from the database.
The Cache Control builder caches the output of a specific action within a model. Note that this caching is across users: all users in a given profile who access that model will be presented with the same cached data. When this caching is suitable, it can substantially improve performance.
The Service Operation and Lookup Table builders also have built-in caching options (this is implemented under the covers with Cache Control).
Establish communication between models using simple broadcast events. Use the Portal Event Declaration builder to define the event name and any arguments if you are building a portlet. Use the same declaration in both models. (A convenient way to do this is to put the declaration in a separate model and then to use Imported Model to bring it into both models). In the source model, call the fire<EventName> method to send the event. In the target model, use the Event Handler builder builder to specify the action to perform when the event is received.
If you are building a widget, use the Widget Event builder builder to create a widget event.
Whether the widget fires, handles, or both fires and handles the event.
Establish communication between models using client communication. Use an event declaration builder to define the event name and any arguments.
If you are building a portlet, use Portal Event Declaration builder. If you are building a widget, use Widget Event builder.
Establish communication between portlets using portlet wiring or Click-to-Action. If you are building a portlet, use the Cooperative Portlet Source builder in the source model.
In the source model, call the fire<EventName> method to send the event. In the target model, use the Cooperative Portlet Target builder. Use the Event Handler builder to specify the action to perform when the event is received. The Output information in Cooperative Portlet Source builder must match the Input information specified in the Cooperative Portlet Target builder.

Library | Support |

Task	Builder you should use
Perform some processing in a model such as: Calling a method and then returning a page. Executing several backend calls before loading the initial page in a Model.	Use the Action List builder, which lets you add a set of one or more actions to your WebApp. Typically, all models must have an action in them called main. Most of the higher-level builders automatically create this action. However, this builder includes the ability to override this feature, so you can add your own main action list to your model, which can perform whatever processing you need.
Perform a conditional statement (for example, if two variables contain the same value, perform an action), without writing Java code.	Within the Action List builder, you can build conditional statements without having to write Java code. Use the picker labeled Select Action underneath the Actions input to navigate to Special > Conditional. From there, you can select if, else, endif, and build up statements that execute an action or return a page based upon conditional logic.
Debug by sending SystemOut messages to the console.	Within the Action List builder, use the picker labeled Select Action underneath the Actions input to select Special > SystemOut. This builder sends SystemOut messages to the application server console, and to the debugTracing log located in the deployed /WEB-INF/logs directory. For example, in IBM® WebSphere® Portal server, the log files for running as a portlet are found in the deployed portlet WAR directory. If the portlet is run standalone, log files can be found in the deployed enterprise application directory.
Assign or append values to variables. For example, to append or replace what is in a given variable with the results of a method call, an argument, or another XML variable.	Within the Action List builder, select the Assignment option underneath Special within the action picker.
Use some Java code in my model.	Use the Linked Java Object builder to point at a Java class. It then adds the public methods of that class to your WebApp, so you can call them from any builder input where you specify an action. In some scenarios, you could also use the Method builder. This builder lets you easily create a simple Method, which can make calls to display pages, call methods, or execute service calls. If you need significant amounts of hand-coded Java, you should write a Java class and bring it into the Model with a Linked Java Object builder instead of using Method builders. This will make the Model easier to manage, and the code assistance is better in the Eclipse Java editor. In general, Method builders in your Model should only contain small amounts of “glue” code.
Add error handling to my model.	The Error Handler builder catches Java exceptions that may occur within the run-time execution of a Web application’s actions. The error handling can be specified on any action, such as a page, method or action list. You can also set a general handler for the entire application to be used if an action has no error handler. This type of error handling is modeled closely after the Java try-catch exception handling and JSP page directive, where each page can set the error page at design time. In all of these cases the lowest-level handler (catch) is called to handle the exception.
Add caching to my model. For example, you are populating an Employee select list from a database call. Because the list of employees does not change that frequently, you want to cache the content when received from the database.	The Cache Control builder caches the output of a specific action within a model. Note that this caching is across users: all users in a given profile who access that model will be presented with the same cached data. When this caching is suitable, it can substantially improve performance. The Service Operation and Lookup Table builders also have built-in caching options (this is implemented under the covers with Cache Control).
Establish communication between models using simple broadcast events.	Use the Portal Event Declaration builder to define the event name and any arguments if you are building a portlet. Use the same declaration in both models. (A convenient way to do this is to put the declaration in a separate model and then to use Imported Model to bring it into both models). In the source model, call the fire<EventName> method to send the event. In the target model, use the Event Handler builder builder to specify the action to perform when the event is received. If you are building a widget, use the Widget Event builder builder to create a widget event. Whether the widget fires, handles, or both fires and handles the event.
Establish communication between models using client communication.	Use an event declaration builder to define the event name and any arguments. If you are building a portlet, use Portal Event Declaration builder. If you are building a widget, use Widget Event builder.
Establish communication between portlets using portlet wiring or Click-to-Action.	If you are building a portlet, use the Cooperative Portlet Source builder in the source model. In the source model, call the fire<EventName> method to send the event. In the target model, use the Cooperative Portlet Target builder. Use the Event Handler builder to specify the action to perform when the event is received. The Output information in Cooperative Portlet Source builder must match the Input information specified in the Cooperative Portlet Target builder.