Rules Guide

CHAPTER 2

How You Use Rules

This chapter describes how you use rules in your applications. It has these sections:

• How rules work

• Working with conditions and actions

• Accessing and firing rules

• Handling the result of a rule

• Using pipelines

How rules work

As stated in the first chapter, a rule is a combination of conditions and actions that return a value. You define rules in the exteNd Director Rule Editor, and then access rules and handle the results in your exteNd Director application code.

Basic process

Using rules is a three-step process:

1. In the Rule Editor, you create a rule by selecting conditions and actions and setting their properties. For example, you might select the CheckDay condition and set the property to When today is Thursday, then select the ReturnResponsePhrase action and enter an appropriate phrase.

2. From the appropriate point in your application code, you fire the rule using one of the available methods. For example:

     fireRule(Thursdays)
   

3. You handle the result of the rule in your application. For example, if the rule returns a certain response phrase when today is Thursday and another phrase otherwise, you set the result in your application.

Rule application components

These are the components for building rules:

Working with conditions and actions

You use the exteNd Director's Rule Editor to create rules by selecting installed (prebuilt) conditions and actions.

NOTE:   Before creating rules, you should become familiar with the Rule Editor. For more information, see Rule and Macro Editors.

There are several ways you can set up your business logic. Some setup can be done in the rule itself, and other setup needs to be done in application code before the application fires the rule. Here are some techniques for using the installed conditions and actions to set up values and build results:

    For details about these and other installed conditions and actions, see Installed Conditions and Installed Actions.

Using whiteboard values

An exteNd Director session includes a whiteboard where you can store values needed for your business logic. You give each whiteboard value a key that you use to retrieve the value. You can access the whiteboard from installed conditions and actions in the Rule Editor as well as from your application code. Whiteboard values are accessed in a condition or action property sheet in the Rule Editor.

Using the !valueOf template

For some properties, you can either enter the actual value or specify a whiteboard key that holds the value. You can also specify a key that holds the name of another key.

In the Rule Editor, if a condition or action property has a caret (^) as part of its name, you can use the special code !valueOf.whiteboardkey, where whiteboardkey is the name of the key whose value you want. The rule substitutes the key's value for the special code.

To specify a whiteboard key, use this format:

  !valueOf.keyname

where keyname is a key that exists on the whiteboard when the application runs the rule.

NOTE:   keyname is case sensitive.

Using built-in whiteboard values

There are several built-in constants you can use like whiteboard keys in !valueOf expressions. They provide information about the logged-in user, the rule that is being run, and the current date and time:

Example of !valueOf

In the following panel, the ReturnResponseWithDefault action has a Default property for a message to the user. In the message you can refer to values on the whiteboard. This sample text uses the system whiteboard value userID and a key called appname, created by the application:

  The current user !valueOf.userID is authorized to get more data from the application !valueOf.appname.

Accessing object attributes from the whiteboard

If an item on the whiteboard is a programming object rather than plain text, you can access any attributes (instance variables) associated with the object. You can refer to object attributes on the whiteboard with this format:

  !valueOf.whiteboardkey^attributename

For example, if your application puts an EbiUser object on the whiteboard, you can get the user's last name this way:

  !valueOf.myUser^lastName

Accessing whiteboard values

The context object provides several methods for accessing values stored on the whiteboard.

    For more information, see Context methods for accessing the whiteboard.

Removing values from the whiteboard

You can use an eraser to remove a whiteboard key at a designated time or after a specified number of accesses. An eraser has the same name as the whiteboard key it will erase. You can use the installed actions AddEraser and RemoveEraser to manage erasers. You can also access eraser methods from the com.sssw.fw.api.EbiWhiteboard class.

Accessing scoped paths

The ^ template field in conditions and actions also supports substitution syntax for scoped paths. Scoped paths allow you to access different types of data in your exteNd Director applications, such as documents in the resource set and the Content Management subsystem.

You can specify a scoped path using this format:

  ${spath}

    For more information, see the chapter on working with scoped paths and XPaths in Developing exteNd Director Applications.

Accessing and firing rules

When you fire a rule, the Rule subsystem evaluates the conditions for a decision node (the When section in the Rule Editor) and if true, executes the node's actions (Do section). If no decision node evaluates to true, the Rule subsystem executes the default actions (Otherwise Do section— if any. The result of the action is then returned to the application.

NOTE:   You can fire rules from an EbiContext object or from an EbiRuleManager. The rule manager provides additional methods for firing and accessing rules and is the recommended implementation for applications that use rules extensively.

Methods for firing rules

Here are the context and rule manager methods for firing rules:

Firing rules from the context object

Typically, you fire rules from an exteNd Director portlet or a JSP page. First you need to instantiate a rule context object using this method:

  public static EbiContext createEbiContext(HttpServletRequest
   request, HttpServletResponse response, ServletContext 
     servletContext) 
  throws EboFactoryException

You can get the request and response objects from an EbiContext object, which you can instantiate using another factory method.

Here is sample code showing how to fire a rule from a portlet's doView() method; where myapp is the (optional) rule owner and access rule is the rule ID:

  public void doView( RenderRequest req, RenderResponse res ) {
   try{
  // get an EbiContext from the RenderRequest
    com.sssw.fw.api.EbiContext context =
     com.sssw.fw.factory.EboFactory.createEbiContext( req, res, 
        GenericPortlet.getPortletContext() );
  // Get the rule context    
    reContext = com.sssw.re.factory.EboFactory.createEbiContext(
      context );
  // Fire the rule
      reContext.fireRule("myapp.accessRule");
  // handle the result...
  // Catch excepions ...

Firing rules from a rule manager

A rule manager allows you to fire rules without specifying the owner each time. You can invoke a rule manager for a particular owner and fire rules by specifying the rule ID.

This code instantiates a rule manager in a portlet:

  public void doView( RenderRequest req, RenderResponse res ) {
   try{
    {
      // If a rule owner exicts
      EbiRuleManager rm = com.sssw.re.factory.EboFactory. 
        createRuleManager( "myapp" );
    /** For rules with no owner
     EbiRuleManager rm = 
        com.sssw.re.factory.EboFactory.createRuleManager();
    */
    // get an EbiContext from the RenderRequest
    com.sssw.fw.api.EbiContext context =
     com.sssw.fw.factory.EboFactory.createEbiContext( req, res, 
        GenericPortlet.getPortletContext() );
  // Get the rule context    
    reContext = com.sssw.re.factory.EboFactory.createEbiContext(
      context );
     rm.fireRule("myRule", reContext);
  // handle the result...
  // Catch excepions ...

NOTE:   Regardless of the owner you used to instantiate a rule manager, you can fire any rule as you would from the context object by specifying an owner:

  rm.fireRule("secondApp.contentRule", reContext);

Firing rules from a JSP page

You can also get a rule manager directly from a JSP page or a servlet. In this case you need to get a class that extends HttpServlet and call getServletContext(). Then you can get the rule manager and fire the rule the same way you would from a portlet:

  public class reTester extends HttpServlet
  {
     ServletContext m_servletContext = null; 
      public void init( ServletConfig config )
          throws ServletException
       {
         super.init( config );
          // Initialize any instance variables...
          m_servletContext = config.getServletContext();
       }
     // Create a rule manager and fire the rule
     EbiRuleManager rm = com.sssw.re.factory.EboFactory. 
        createRuleManager();
     com.sssw.re.api.EbiContext ctx = 
         com.sssw.re.factory.EboFactory.createEbiContext(
         m_servletContext.getEbiRequest().getHttpServletRequest(),
         m_servletContext.getEbiResponse().getHttpServletResponse(),
         m_servletContext.getServletContext());
     rm.fireRule(myRule, ctx);

Firing temporary rules

Typically you define rules in the exteNd Director Rule Editor, where they are saved to a known location in your exteNd Director project resource set. This is what allows you to reference rules by rule name. Temporary rules are XML strings that can be referenced directly. You can get the XML for a rule by defining it in the Rule Editor and exporting the XML using EbiRuleManager.toXMLString().

Here is how you fire a temporary rule from the rule context object:

  string xmlrule =...;
  reContext.fireTemporarayRule(xmlrule);

Here is how you fire a temporary rule from the rule manager:

  rm.fireTemporaryRule(xmlrule, reContext);

Handling the result of a rule

This section describes methods you can use to handle HTTP response values and whiteboard values returned from a rule, and includes some code examples.

Context methods for accessing HTTP response values

This table lists the methods available on the rule EbiContext to handle HTTP response values:

Context methods for accessing the whiteboard

This table lists some EbiContext methods to store and retrieve session and object values from the whiteboard.

Examples of handling return values

This section provides some code examples for handling values returned by rules in your application code.

Example of a rule that returns a boolean

This code shows a portlet that fires a rule called bonus whose owner is sample.

The bonus is based on this rule: "If today is a weekday, display the value the bonus is $100,000; otherwise, display $1."

The rule's actions return true or false by setting the response status to 200 for true and 412 for false. The code determines what to do with those results:

  public void doView(RenderRequest req, RenderResponse res) {
   try {
     //get the context
     com.sssw.fw.api.EbiContext context =
       com.sssw.fw.factory.EboFactory.createEbiContext(req,
         res, GenericPortlet.getPortletContext());
     // Get the rule manager
     EbiRuleManager rm =
       com.sssw.re.factory.EboFactory.createRuleManager("sample" );
     // Get the rule context
     com.sssw.re.api.EbiContext reContext =  
        com.sssw.re.factory.EboFactory.createEbiContext(context);
    // nitialize bonus
     Double bonusAmount = null;
     
   // Fire rule to determine bonus.
    if (rm.ruleExists( "bonus" ) ) 
    {
      if (rm.isTrue( "bonus", reContext ))
       bonusAmount = new Double(100000.00);
      else
       bonusAmount = new Double(1.00);
    }
    else
     bonusAmount = new Double(0.00);
   } 
  catch (Exception e) 
   {
   // ..exception handling ...  
    }
  }

Example of a rule that returns data

Building on the preceding example, suppose the rule returns a bonus amount instead of true or false. Both the Do and Otherwise Do actions are ReturnContentFromData, rather than ReturnTrue and ReturnFalse. Do gets the value bonus1 and Otherwise Do gets bonus2 from the whiteboard. The selected action returns the value as a response phrase, which is available from the context object.

Before firing the rule, you must get the values (from a company database, for example) and call EbiContext.setValue() to set the values for the whiteboard keys bonus1 and bonus2 in this user's session:

  String bonusString = "0";
  Double bonusAmount = null;
  
  // Get a rule manager and context objects.
  EbiRuleManager rm = com.sssw.re.factory.EboFactory. 
    createRuleManager();
  com.sssw.fw.api.EbiContext context =
    com.sssw.fw.factory.EboFactory.createEbiContext(req,
       res, GenericPortlet.getPortletContext());
  com.sssw.re.api.EbiContext reContext =  
    com.sssw.re.factory.EboFactory.createEbiContext(context);
  
  // Fire rule to determine bonus.
  if ( rm.ruleExists( "bonus" ) ) 
  {
     context.setValue("bonus1", ...); // retrieve value from db
     context.setValue("bonus2", ...); // retrieve value from db
     rm.fireRule( "bonus", reContext );
     bonusString = context.getResponsePhrase();
     bonusAmount = Double.valueOf(bonusString);
  }

Example of a rule that uses a whiteboard value

Again using the bonus example, suppose instead that the bonus value is set in the Rule Editor. The Do and Otherwise Do sections both use the installed action Return Response, where the bonus amounts are specified:

  String bonusString = "0";
  Double bonusAmount = null;
  
  // Get a rule manager and context objects as shown 
  // in previous example.
  
  // Fire rule to determine bonus.
  if ( rm.ruleExists( "bonus" ) ) 
  {
     rm.fireRule( "bonus", reContext );
     bonusString = context.getResponsePhrase();
     bonusAmount = Double.valueOf(bonusString);

Using pipelines

A pipeline is a mechanism for binding a rule or set of rules to a known user or group, or for firing a set of rules in a specified order as a unit.

You set up a pipeline using exteNd Director's Pipeline and Binding Editors.

    For information about setting up pipelines in exteNd Director, see Pipeline and Binding Editors.

Benefits of pipelines

Pipelines enhance the power of rules by providing a higher level of logical encapsulation and reusability, while maintaining the benefits of tool-based maintenance and the hot deployment capability. Here is a summary of some of the benefits:

How pipelines work

When you create a pipeline, you can associate it with one or more binders, of which there are three types:

Here is how a pipeline is processed:

After you create a pipeline, you use the appropriate Binding Editor to select a rule or rules and specify the order in which you want them to fire. Then you use the validate() method to execute the pipeline in your application code. You handle the result of the pipeline the same way you handle the result of a rule.

    For more information, see Handling the result of a rule.

Validating a pipeline

Firing the rules in a pipeline is called validating the pipeline. You use the validate() method on the EbiContext object.

First you need to get the EbiContext, as shown in Firing rules from the context object.

This code validates the pipeline you specify:

  ctx.validate("CheckAllAccessRestrictions");

This code sets a pipeline ID in the EbiContext object and validates it:

  ctx.setPipelineID("CheckAllAccessRestrictions");
  ctx.validate();}

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...