ILOG JRules 4.5 ILOG Rule Language Reference Manual June 2003 © Copyright 2003 by ILOG. Printed in France This document and the software described in this document are furnished under a license or nondisclosure agreement, and may be used or copied only within the terms of such license or nondisclosure agreement. No part of this work may be reproduced or disseminated in any form or by any means, without the prior written permission of ILOG S.A. C O N T E N T S Table of Contents Preface About this ILOG Rule Language Reference Manual vii Features of the ILOG Rule Language viii What You Need To Know ix Typographic Conventions ix What is in this Manual x Related Documentation x Chapter 1 Language Description 1 Import Statement 2 Rulesets 2 Ruleset Header 2 Ruleset Variables 3 Rule Structure 6 Defining a Rule in IRL 6 Rule Keywords 7 Rule Header 8 Rule 9 Property 9 Priority 10 I L OG JRUL E S 4 . 5 — IR L RE F ER EN C E MA NUA L CON TE N T S Packet 12 Rule Conditions 13 Syntax of Conditions 13 Combination sign: & 14 Conjunction 14 Rule Variables in Conditions 14 Negating the Existence of an Object 15 Unknown Values 16 Rule Actions 16 Asserting Objects 16 Rule Variables in Actions 17 Removing Objects 17 Modifying Objects 18 Updating Objects 18 Control Flow Statements 19 Ruleflow 26 Task Overview 26 Rule Task 26 Function Task 27 Flow Task 27 Functions 27 Java and Language Elements 28 Comments 28 Literals 29 Identifiers 29 Variables 29 Predefined Variables 29 Class Names 30 Keyword Summary 30 List of Keywords 30 Keyword Restrictions 30 I L OG JRUL E S 4 . 5 — IR L RE F ER EN C E MA NUA L CON T E N T S Operator Summary 31 Chapter 2 Keywords 33 after 34 agendafilter 35 apply 37 assert 39 before 42 bind 43 body (in flow task) 44 body (in function task) 45 body (in rule task) 46 break 48 collect 49 continue 51 evaluate 52 event 54 execute 56 exists 57 flowtask 58 for 61 fork 62 from 63 function 65 functiontask 67 goto 69 if/else 70 if/else (in ruleflow) 72 import 73 in 74 insert 75 instanceof 76 I L OG JRUL E S 4 . 5 — IR L RE F ER EN C E MA NUA L CON TE N T S isknown 77 isunknown 78 modify 79 not 81 occursin 82 packet 83 priority 85 property 87 retract 88 return 89 rule 90 ruleset 92 ruletask 94 setup 98 switch/case/default 99 then 101 throw 103 timeof 104 try/catch/finally 105 update 107 var 109 wait 110 when 113 while 115 while/break/continue (in ruleflow) 116 Chapter 3 Language Grammar 119 Grammar Notation 120 Grammar Specification 121 Index 139 I L OG JRUL E S 4 . 5 — IR L RE F ER EN C E MA NUA L PREFAC E About this ILOG Rule Language Reference Manual The ILOG Rule Language Reference Manual describes the ILOG Rule Language (IRL). Rules written in this language can be executed by the 100% pure Java ILOG JRules rule engine. ILOG JRules allows you to integrate business rules in your Java applications. ILOG JRules is a complete programming environment, consisting of an object-oriented rulebased programming language and the Rule Builder graphical user interface. Application developers may write rule-based programs as either stand-alone business rule applications or components integrated into C++ or Java applications. ILOG Rule Language programs are thread-safe, and different threads may share data between them. ILOG JRules applications can be used in both client-server and multitier environments. This preface provides an overview of the main features of IRL and describes the overall organization of the manual. It is divided into the following sections: . Features of the ILOG Rule Language—a short introduction to the main features of the ILOG Rule language. . What You Need To Know—prerequisites for using ILOG JRules. . Typographic Conventions—typographic conventions used in this documentation. . What is in this Manual—outlines the main sections in the manual. . Related Documentation—describes how to access the required information in the remainder of the documentation set. ILOG JRULES 4.5 — IRL REFERENCE MANUAL Features of the ILOG Rule Language The ILOG Rule Language (IRL) provides a rich set of constructs which includes collections, support for relations between objects, and temporal reasoning. The rule engine uses various optimization techniques to improve efficiency in rule processing. An IRL program can be integrated into multithreaded applications and deployed in many environments including J2EE and as a web service. It also provides support for XML-based reporting. One of the important features of ILOG JRules is its Business Rule Language support which uses a framework to ensure the translation from the business rule language to the execution rule language: IRL. The main features of the ILOG Rule Language are the following: . Java language integration: supports Java operators in expressions and tests, Java-like syntax interfaces, Java arrays, and variable scope management. . Ruleflow and Task support: enables the modeling and control of the execution sequence of the rules in a ruleset. This is made possible using tasks. . XML support: provides support for an XML syntax that can be used alternatively to the Java-like syntax when more appropriate. . Any Java class: any application class or interface can be accessed, and there is no need to derive the application classes from ILOG JRules classes. . Dynamic resolution strategy: provides both dynamic and static priorities for rules. . Collections: objects that fulfill certain conditions may be grouped in a collection object and treated in a single rule. . Relations between objects: links between objects can be followed in rules. . Rule grouping: using packets, sets of rules can be grouped together to be activated or deactivated as a group. . Truth Maintenance System: can keep track of the validity of a particular object and can automatically remove the object when the justifying conditions are no longer satisfied. . Temporal reasoning: provides a temporal reasoning facility that allows you to incorporate time as a parameter in your rule-based system. The main features of the ILOG JRules engine are the following: . Java library: the library is a 100% pure Java library with a powerful, flexible, and extensive API and can notably be used in an applet. . XML centric: an API is provided to allow you to integrate XML objects with your ILOG JRules application. ILOG JRULES 4.5 — IRL REFERENCE MANUAL . Open Java API: since the engine is implemented in Java, everything in your application that uses ILOG JRules is controlled by an API which utilizes the Java classes of the ILOG JRules libraries. . Rule Factory API: rules are Java objects themselves which can be manipulated. You can add, remove, or change conditions of the rules on the fly as well as manipulate actions. . Dynamic rule management: rules can be added to or removed from the inference engine on the fly and whenever needed. They can also be added from numerous sources, for example, from a text file, a string, a stream, or a URL. . Optimizations: various tuning and optimization mechanisms are provided to more efficiently process the ruleset, for example, finders and autohashing. . Multithreaded architecture: in a multithreaded application, multiple threads can share objects using public methods of the IlrContext class. . EJB deployment support: a high-level rule session API is provided to allow you to integrate your business rule application into different environments in a transparent way: J2EE, J2SE, or as a web service. . Bytecode generation: it is used to increase the performance of the execution of any rule and can be controlled by engine parameters. Bytecode generation can also be used to dramatically increase performance in the case of simple homogeneous rules. . Compiler: to gain speed, you may compile your ruleset. . Documentation generator: a JavaDoc-like documentation may be generated for your business rule application. . Syntax checker: the engine provides a syntax checker module. What You Need To Know This manual assumes that you are familiar with the environment in which you are going to use ILOG JRules. Since ILOG JRules is written for Java developers and the ILOG Rule Language is very similar to the Java language, this manual also assumes that you can write Java code and that you are familiar with your Java environment. Typographic Conventions The following typographic conventions apply throughout this manual: . Code extracts and filenames are written in this typeface. ILOG JRULES 4.5 — IRL REFERENCE MANUAL . Classes, member functions, and keywords appear in this typeface in the sections in which they are documented. . In syntax presentations, keywords are highlighted like this. . Italic type is used to indicate user-specific information. Also, important ideas are emphasized like this. . Values that you must fill in (for example, a filename or a path name on your platform) also appear in the same typeface as code extracts but with angle brackets to indicate you must supply an appropriate value; for example, /usr/local/ indicates that you must fill in a value for YourHome. . is used throughout this manual to refer to the directory in which you choose to install JRules. By default this directory is C:\ILOG\JRules45 on the PC, and $HOME/ILOG/JRules45 on UNIX, where HOME is an environment variable. . Square brackets ([]) indicate optional items. . Ellipsis (...) indicate that you can repeat the information. . A vertical bar (|) indicates a choice within braces ({}) or brackets ([]). What is in this Manual This Language Reference Manual is divided as follows: . Chapter 1, Language Description introduces the ILOG Rule Language and its main features. . Chapter 2, Keywords presents the ILOG Rule Language by keyword arranged in alphabetical order. . Chapter 3, Language Grammar presents the ILOG Rule Language specification. Related Documentation The ILOG JRules documentation consists of a number of manuals that cover the different components of the product. For more information on the documentation set, and to help you locate the information you require, see the ILOG JRules Overview which describes all the features of the product and how it could be used to produce a business rule application as well as how the documentation is organized. ILOG JRULES 4.5 — IRL REFERENCE MANUAL C HAPTER Language Description Language Description This chapter presents a detailed introduction to the ILOG Rule Language. It describes the overall components of an IRL program: import statements, ruleset header, ruleset variables, rules, ruleflow, and functions. The chapter closes with listings of keyword groups, preparatory to Chapter 2, Keywords which contains a detailed description of each keyword presented in alphabetical order. The chapter is divided into the following sections: . Import Statement . Rulesets . Rule Structure . Rule Header . Rule Conditions . Rule Actions . Ruleflow . Functions . Java and Language Elements . Keyword Summary . Operator Summary ILOG JRULES 4.5 — IRL REFERENCE MANUAL IMPORT STATEMENT Import Statement The import statement is used to import a Java class or package into the rule file. Once imported, the class or package is accessible from the rules. For example, with the following import statements: import java.util.*; import userPackage.UserClass; The following packages are automatically imported: java.lang.*; ilog.rules.engine.*; Import statements are not mandatory, but when present, they are always placed at the beginning of the rule file, before the ruleset header. Rulesets An ILOG Rule Language program consists of a ruleset. A ruleset contains a header, a set of rules (referred to as execution rules), a set of functions, and a set of tasks. Rules, functions, or tasks may either have been written directly or generated from rules, functions, or tasks written in a business language in an editor such as the Rule Builder. Ruleset Header The ruleset header is not mandatory. When present, it is placed after import statements, if any, and before the rules, functions, and tasks. The header can contain three parts: name, properties, and variables. . Ruleset Name The ruleset name is declared as follows: ruleset rulesetName; if the header is limited to a name declaration, or: ruleset rulesetName { properties rulesetVariables } . Ruleset Properties Properties can be declared as follows: ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULESETS ruleset rulesetName { property propertyName = propertyValue; } The properties are not interpreted by the rule engine except the predefined property context.class. This property is used to declare the class from which the class of ?context used in this ruleset is derived. . Ruleset Variables Ruleset variables provide a convenient way to exchange data between the application and the ruleset. See the section Ruleset Variables for more details. Ruleset Variables The ruleset allows the definition of ruleset variables. Ruleset variables provide a simple way to exchange data between the application and the ruleset. Declaring Ruleset Variables The declaration of the ruleset variables contains modifiers that specify how these variables are accessible from outside the ruleset. These variables are accessible either from rules, functions, or task definitions. The ruleset variables are comprised of: . In Variables . Out Variables . Local Variables In Variables The initial values of in variables are set by the API in IlrContext.setParameters(IlrParameterMap). The in variables are defined as follows: ruleset Connect4 { in Grid grid; inout SavedGame saved; } A variable whose modifier is inout is either an in variable or an out variable. Out Variables The initial values of out variables can be given when they are declared or not, as follows: ruleset Connect4 { out SavedGame saved; out int games = 0; } Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULESETS The value of an out variable is accessible from the application by the following APIs: . IlrParameterMap IlrContext.getReturnValues() . IlrParameterMap IlrContext.execute() . IlrParameterMap IlrContext.execute(String taskName) . IlrParameterMap IlrContext.executeTask() Local Variables The initial values of local variables can be given when they are declared or not, as follows: ruleset Connect4 { int winner = Constants.None; Connect4 connect4; }; A local variable is not accessible from the application; it stays local to the ruleset. Ruleset Variables and Initial Rule If either ruleset variables or an initial rule introduced by the setup keyword are defined on the ruleset, the initial rule is not automatically executed because the in variables are not yet initialized. The initial rule can be executed by calling the IlrContext.executeInitialRule() method. Ruleset Variables and Task Definition Ruleset variables are accessible from the task definition except from the body defined by comprehension (that is, defined by the select keyword) for a rule-based task; these variables are not initialized when the body code is evaluated. However, they are accessible from a dynamic body (that is, defined by the dynamicselect keyword). Scope of Ruleset Variables Local binding with the same name as a ruleset variable has priority over the ruleset variable. Look at the following example: ruleset r { int count = 3; }; function void example() { … bind count = 4.5; … } rule r2 { when { ?count: String(); } ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULESETS then { … } } rule r3 { when { ?s: String(count: ?s.length); } then { … } } In all cases in this example, the local binding takes precedence over the ruleset variable. There is no problem in cases where local binding is defined with a type different from the ruleset variable of the same name. The given example uses local ruleset variables, but the previous scope rules apply either on in or out ruleset variables. Referencing Ruleset Variables Ruleset variables can be accessed either from rules, functions, or task descriptions. They can be referenced simply by name when there is no local binding hiding the ruleset variable. Even if there is local binding, the following syntax allows you to reference the ruleset variable without ambiguity: ?context.?thevariable as illustrated in the following example. ruleset r { int count = 3; }; rule r1 { ?count: Integer(intValue() > ?context.?count); } Tip: We advise using the unambiguous syntax to access ruleset variables even if there is no ambiguity. This will prevent any problems in case the rule, function, or task description changes. Modifying a Ruleset Variable Since a ruleset variable is accessible in the functions, task descriptions, and rules in the ruleset, it is in particular accessible from a rule condition part. Consequently, its modification can modify the rule eligibility to be fired. This is why ruleset variables are considered as references of the context, meaning that the engine should be notified of any modifications to them by a call to the IlrContext.updateContext() method. Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE STRUCTURE Rule Structure An execution rule has a structure composed of a header, a condition part, and an action part. . The header part defines the name of the rule, the eventual packet to which the rule is attached, and its priority. . The condition part utilizes the object-oriented structure of Java to carry out pattern matching on class instances, that is, objects. This pattern matching binds (instantiates) variables to objects and field values. Rule conditions are also used to test field values. This provides a filtering mechanism for objects. . The action part of the rule specifies actions to be taken if the rule is executed. A rule is processed in the following manner: given a set of conditions, each condition with its variables is matched to an object with its field values. A condition may include tests on variable values. If all the conditions are matched, that is, the variables return field values that fulfill the tests, the action part of the rule may be executed. The set of actions may include simple operations such as printing text as well as complex operations such as invoking methods on objects, modifying objects used by the rules, or creating new objects. The rule engine carries out the ruleset execution using a working memory and an agenda. The working memory contains the Java and XML objects to which the rules are applied. The agenda contains the rule instances. A rule instance is a rule with all its conditions matched to specific objects from the working memory. The pattern matching between conditions and objects is carried out on the class name and attribute values, including tests on the attribute values. Only a subset, null included, of field values need be utilized. A particular rule can have multiple rule instances in the agenda. This results from the various combinations of objects in the working memory that verify the rule conditions. Defining a Rule in IRL The ILOG Rule language, like other programming languages, has a number of keywords, or reserved words. A rule is defined by means of the rule keyword, as shown in Figure 1.1. rule ruleName { priority = priorityValue; packet = packetName; property propertyName = value; ... when { conditions ... } then { actions ... } else { actions ... } } Figure 1.1 : Execution rule structure ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE STRUCTURE Here is a typical example: rule FindFilm { priority = 1; when { Film(language == English; ProductionYear > 1980 & < 1990; ?t:title); Cinema(location == Paris; filmTitle == ?t; showingTime > 13.00 & < 16.00; ?c:name); } then { System.out.println("The film: " + ?t + " is showing at the cinema: " + ?c); } }; After the rule keyword in the first line we find the name of the rule, FindFilm. The second line expresses its priority by means of the priority keyword. In this example there are two conditions. These conditions use the classes Film and Cinema. In ILOG JRules, a rule can have any number of conditions, but a rule without any conditions is not allowed. The then keyword marks the end of the conditions and the start of the actions. In the example, there is only one action: an ILOG JRules instruction that prints the title of a film showing at a cinema in Paris. Rule Keywords IRL contains various keywords related to rule statements. Figure 1.2 presents the rule statement keywords divided into their separate functions. We have: . The header part, which defines the name of the rule with the rule keyword statement, also defines its priority, associated packet, and properties, each with an assigned keyword. For more details on creating the header, see Rule Header on page 8. . The condition part, which begins with the keyword when, also referred to as the lefthand side (LHS) of the rule. For more details on creating the condition part, see Rule Conditions on page 13. . The action part, composed of one or two parts, also referred to as the right-hand side (RHS) of the rule. The first part begins with the keyword then. The optional second part begins with the keyword else. For more details on creating actions, see Rule Actions on page 16. Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE HEADER Rule Header packet, priority, property, rule Rule Condition Part after, before, collect, evaluate, event, exists, fork, in, instanceof, isknown, isunknown, logical, not, Left-hand until, occursin, timeof, when, where Side Rule Action Part apply, assert, bind, break, catch, continue, else, event, execute, finally, for, if, instanceof, isknown, isunknown, modify, refresh, retract, timeout, then, Right-hand throw, timeof, try, update, var, while Side Figure 1.2 Rule statement keywords by function Rule Header A rule includes a header part where the rule name is declared. The header may also contain the priority of the rule as well as the packet with which the rule is associated. Both items are optional. This section is composed of the following subsections: . Rule . Property . Priority ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE HEADER . Packet Rule The name of a rule can be any legal identifier, starting with a letter and including numbers and symbols, except the keywords listed in Keyword Restrictions. The following example shows the general structure of a rule. The keyword rule is followed by the rule name, FindFilm in this case, which is then followed by an open curly brace “{”. This is the structure of all rules. rule FindFilm { ... }; Property The property keyword is used to declare specific properties in the rule file and is part of the header declarations: property propertyName = value; A property can be a literal, a class, or a date. Date literals are converted from strings or printed to strings using a java.text.DateFormat. The date literal mechanism is generic and can be applied to any class so long as the IlrReflect object is initialized with the correct formatting object, a subclass of java.text.Format. The following extract of a rule file defines, among other things, the system rule property activation as false and a user property declaring a startDate and an endDate. rule MyRule { property myprop.int = 12; property myprop.long = 121; property myprop.float = 3.14; property myprop.double = 12.54252d; property myprop.char = ’#’; priority = 12; packet = mypacket1; property myprop.mystring = "myprop.mystring first value"; property myprop.class = java.util.Vector; property activation = false; property startDate = java.util.Date("4/10/2003 0:0"); // April 10th property endDate = java.util.Date("9/12/2003 0:0"); // Sept 12th when { String(); } then { } }; Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE HEADER Priority The rule priority determines the order in which rules are executed in an application. The priority of a rule determines the position of a rule in the agenda. The priority can be an integer or an integer expression. If not specified, the value 0 is used. There are two types of rule priorities: static and dynamic. Static priorities are fixed values while dynamic priorities are rule variables whose values are determined by rule expressions. Static Priority A static priority may be used to alter the sequence of rule execution among different rules. Static priorities are any legal Java integer literals. The larger the number, the higher the firing priority of the rule. The following example presents three rules with priorities 1, 5, and 10. The rule to locate a film has a lower priority than the rule for adding a new film, while the priority for the rule to reserve a ticket is higher. rule FindFilm { priority = 1; ... }; rule AddNewFilm { priority = 5; ... }; rule ReserveTicket { priority = 10; ... }; ILOG JRules provides four predefined priority values, maximum, high, low, and minimum. These predefined constants are of the IlrPriorityValues class, provided for static priorities. They have the following values: . maximum: 1 000 000 000 . high: 1 000 000 . low: -1 000 000 . minimum: -1 000 000 000 In the following example, the rule with the highest priority is for the demand of additional system resources, due to a large number of users on the system. rule AddSystemResources { priority = high; ... }; Dynamic Priority A dynamic priority may be used to alter the order of execution of the same rule when several rule instances are in the agenda. Dynamic priorities are expressions whose value depends on variables bound in the condition part of a rule. All variables defined in the condition part of the rule and whose scope is the entire rule and not only a specific condition can be used in the dynamic priority expression. Note that the use of not or exists restricts the scope and cannot be used in the dynamic priority expression. ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE HEADER Dynamic priorities are a powerful and elegant device for solving control problems with respect to the order in which rules are to be fired. There is a range of possibilities, extending from the simple selection of one of two competing rules, up to the programming of a resolution strategy or the management of tasks. The following examples illustrate the use of dynamic priorities. Example of Dynamic Choice Let us suppose we are going to use ILOG JRules to monitor patients in a hospital that are likely to need immediate care if their condition worsens. With limited resources, the hospital must prioritize which patient the doctor attends to first, despite all of the patients being in need of care. The seriousness of the patient’s condition is registered on a scale of 0 to 100 (the higher the number, the more serious the problem). If at any time a patient’s condition reaches a warning level (say 70), the doctor must be called. The following rule prioritizes the doctor’s actions so that the doctor visits patients with more critical conditions before less serious ones. rule PatientCare { packet = MonitorHealth; priority = ?health; when { ?h:hospital(?warning:warning); ?p:patient(hospital == ?h; ?health > ?warning) } then { ?h.calldoctor(?p); ... } }; Example of Dynamic Strategy Imagine a monitoring system for a production process in a chemical factory. Process control is based upon temperature and pressure data obtained directly from production. For accuracy checking, each measurement is obtained by three autonomous instruments. Most sensors operate with a high degree of precision, but certain inferior-quality instruments operate with lesser degrees of precision. Within each group of three sensors, instruments are numbered to reflect their performance degrees. A high-precision sensor is numbered 3. The precision then drops down to 2 and 1 for the two accompanying sensors. When an instrument breaks down completely (as often happens for sensors numbered 1), it no longer supplies any values, and no more objects are inserted into the working memory. We can write a ruleset that adapts itself automatically to the precision of each instrument. Here is a sketch of the kind of rule that might be used: rule ProcessControl { priority = ?to + ?po; when { temperature(?temp:value; ?to:origin); pressure(?press:value; ?po:origin); } then { Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE HEADER ... } } Here, the origin attribute of the temperature and pressure objects indicates the number of the sensor that supplied the measurement. Packet One of the means that ILOG JRules offers for breaking up the rules of a set into tasks and controlling their execution is rule packets. Important: We recommend that you use the new ruleflow feature to group and organize your rules. While packets are not deprecated, they are no longer the best way to organize rules per task. See Ruleflow on page 26. A ruleset usually contains various groups of rules that deal with specific domains of expertise. The global expertise represented by the rules can be broken down into tasks, where each task handles a specific part of the overall expertise. The collection of rules into tasks creates a means to organize them. For example, we avoid the situation in which a display task might be invoked before the end of a processing task. Rule packets provide a means to represent tasks. For each task, there is a rule packet that contains all the rules for the task. Associating rules as a packet provides a way to activate and inactivate the rules applying the packet name. Task management, such as adding or removing a packet from the ruleset, can be done from the functions of your application using the API. Rule packets are defined by means of the packet keyword. Here is an example: rule UsedCarsAvailableAtPriceRange { packet = cars; when { UserRequest(?x:mark; ?p_h:high_price; ?p_l:low_price); ?y:UsedCar(mark equals ?x ; price < ?p_h & > ?p_l); } then { System.out.println("A " + ?y.year + " " + ?y.mark + " " + ?y.model + " is available for you."); } }; This rule is applied for a used car search, but similar rules might deal with other products such as books, electronics, or music. Each topic may be differentiated by a different packet name. Note: A ruleset in ILOG JRules can contain both isolated rules and packets of rules. Rules that belong to a packet must be loaded into an execution context through the API method getPacketRules and activated specifically by the method fireRules. ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE CONDITIONS Rule Conditions A business rule in ILOG JRules has the following form: IF conditions THEN actions. The keyword when is used to specify the condition part of a rule. The condition part of a rule (its left-hand side) is composed of a set of conditions, or patterns, that refer to Java objects. Each pattern is matched, if possible, with one or more objects in the working memory. More precisely, a pattern comprises tests that are applied to each object in the working memory, and an object is said to match the pattern when it passes these tests successfully. For example, suppose that we wish to search, or test, for films showing at an evening hour after 8. In ILOG JRules, this condition may be expressed like this: Film(showTime > 20.00); This condition matches objects of the Film class whose showTime attribute is greater than 20.00. Suppose, now, that we require that the location of the film be in Paris. This compound condition is expressed like this: Film(showTime > 20.00; location == Paris ); Language Description Syntax of Conditions The syntax of conditions in ILOG JRules is straightforward. The condition starts with the name of the class concerned by the condition: for example, Film. This class name is followed by tests, enclosed in parentheses, that express constraints concerning the values of attributes for objects of this class. Each test starts by naming the attribute in question, followed by one of the following predicates: . == . != . < . > . <= . >= . a method call It ends with an expression whose value will be compared with that of the attribute. A condition can contain several tests involving the same attribute of the object in question. Consider the simple condition that tests for films whose show times are between 8 and 10 in the evening. This may be expressed in ILOG JRules in the following way: Film(showTime > 20.00; showTime < 22.00); ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE CONDITIONS Combination sign: & The ampersand sign & is used in ILOG JRules as a combination sign, which associates several tests with the same attribute of an object involved in a condition. This combiner allows us to rewrite the previous condition in a more precise form: Film(showTime > 20.00 & < 22.00); Here are two equivalent conditions, the second of which uses the & sign: Film(produced > 1980; produced < 1990; showTime > 20.00; showTime < 22.00); Film(produced > 1980 & < 1990; showTime > 20.00 & < 22.00); Conjunction In ILOG JRules, implicit AND relationships exist between all the conditions in a rule. In other words, all the conditions of a rule must be satisfied before the execution of its actions. For example, consider the following conditions: “a film whose spoken language is English” and “a cinema whose location is Paris.” These conditions may be written in ILOG JRules in the following way: Film(language == English); Cinema(location == Paris); These two conditions are matched by pairs of Film and Cinema objects for which the language of the film object is equal to English AND the location of the cinema object is equal to Paris. Rule Variables in Conditions A rule variable refers to an attribute of an object matched by a condition. This enables conditions in a rule to make use of earlier matched objects in that rule. For example, our first test might be to match Film objects that have English as the spoken language. A later condition in this rule might then test if these Film objects are being shown in a particular location. In such situations, we use rule variables. The syntax for a rule variable is the name prefixed by a question mark. In ILOG JRules we would first write the condition that matches those Film objects that have English as the spoken language. We assign the title attribute of the matched Film to a rule variable called ?t. Film(language == English; ?t:title); Then we write the condition concerning the cinema location by using the variable named ?t: Cinema(location == Paris; filmTitle == ?t); ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE CONDITIONS Rule variables do not need to be declared. Each rule variable is bound by ILOG JRules at the moment it first appears in a condition of a rule. A rule variable can be used within the same condition in which it was bound. For example, consider the condition “a film shown in the original language version.” We could write this condition in the following way: Film(?l:language; originalLanguage == ?l); The condition selects a Film object, instantiates the ?l rule variable to its language argument, and then tests whether the original language of this Film is equivalent to ?l. Note: In the ILOG Rule Language a question mark (“?”) is used to designate a variable, for example: ?x, ?result. The question mark is not required by the Rule compiler but is used to improve the readability of code. In this manual, all Rule variables are prefixed by a question mark. Negating the Existence of an Object To express the nonexistence of a particular object in the working memory, we place the not keyword before the condition of the object, as shown here: not Stock(change == 0.0); Here is an example of the use of not in a rule: rule LargestPercentStockChange { when { ?s: Stock(?c:currentValue; ?l:lastClosing; ?p:(?c-?l)/?l); not Stock(?c1:currentValue; ?l1:lastClosing; ?p < (?c1-?l1)/?l1); } then { System.out.println(?s.ticker + "has the largest change of: "+ ?p +"%"); } }; The purpose of the LargestPercentStockChange rule is to print out the stock with the largest percent change. . The first condition, in the line starting with ?s, specifies a stock, and the rule variables named ?c and ?l are bound to the current stock value and the last closing value, respectively. The stock percent change is calculated and saved as ?p. . In the second condition, the line contains the not keyword. Similar to the previous condition, we calculate a percent change with rule variables ?c1 and ?l1. The condition then compares the result with the previous calculated change ?p. The not keyword will cause the condition to fail for any percentage change except the largest. Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS Rule Actions Unknown Values The ILOG Rule Language has postfix operators isknown and isunknown that can be used to check if a field value is known or not. An unknown field value can be found in XML objects only when an XML attribute is set to xsi:nil or when an optional element is not provided in the XML document. In all other cases, isknown returns true. Here is an example of a rule checking for a known field value: rule sendEmailIfProvided { when { ?u: User(address isknown); } then { sendMail(?u.address); } }; The action part of a rule (its right-hand side) is composed of ILOG Rule primitives that can, for example, create, remove, and modify objects. The keyword then is used to specify the action part of a rule. When the condition part of a rule finishes with an evaluate statement, the action part of the rule may include an else clause. The last evaluate within the condition part acts as a discriminator to choose between the then or the else execution branch. If the evaluate expression is true, the then part is executed; if it is false, the else part is executed. Asserting Objects The assert statement lets you create a new object and insert it into the working memory. This keyword is followed by the name of the class and the values of the attributes of the object to be created. Here is an example that involves the creation of a new Course object whose department and number attributes take the values History and 324, respectively: assert Course(History,324); There are two possibilities for the way that an assert operation is processed: . The object is already in the working memory. In this case, the assert operation is equivalent to an update. See Updating Objects for more information. . The object is not in the working memory. In this case, the object is inserted into the working memory, and the assert demon of the corresponding class and its superclasses, if any, is invoked, and the agenda is updated. ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS More information about the assert method can be found in the ILOG JRules API Reference Manual. Rule Variables in Actions We saw in Rule Variables in Conditions that variables can be used in rules to refer to attributes. The rule variable t is defined in the following example: Course(title equals "The rise and fall of empires"; ?t:time);. Note: In the ILOG Rule Language the word equals is used to compare string elements and the == predicate is used with integers. Similarly, in the action part of a rule ILOG JRules refers to an object matched by a particular condition using a rule variable. For example, to modify the value of the time attribute for all Course objects whose number is greater than 300, ILOG JRules identifies objects matched by this condition using a rule variable. The rule variable is defined as c in the following example: ?c:Course(number > 300; ?t:time); In addition, the bind statement allows you to create a local variable for the scope of the rule. The variable must be initialized with a value. Here is an example where ?x is a local variable that is bound to an object called element. bind ?x = element; The var statement provides the same feature. Removing Objects The retract statement lets you remove from the working memory an object that is bound to a rule variable. In the following example, the retract primitive removes the object bound to the ?c variable: rule RemoveCourse { when { ?c: Course(department == History; number == 254); } then { retract ?c; } }; The retract demon of the corresponding class, if any, is called, and the agenda is updated accordingly. Retracting an object from the working memory might cause a logical object to lose one or several of its justifications. Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS For details refer to the Truth Maintenance System information in the Rule Engine User’s Manual. More information about the retract method can be found in the ILOG JRules API Reference Manual. Modifying Objects The modify statement lets you modify the values of the attributes of objects in the working memory. Here is an example: rule ModifyLecturer { when { ?c: Course(department equals "History"; lecturer equals "Tanner"); } then { modify ?c {lecturer = "Chen"}; } }; Updating Objects When an object is modified by Java, the modifications are not seen by ILOG JRules. This means that data maintained by ILOG JRules will not be consistent with the new contents of the modified object. To avoid inconsistencies, the update statement should be called for such an object. This statement allows ILOG JRules to update its internal structures according to the new contents of the modified object. In the following rule, the first action modifies the number attribute. The update primitive is then called to inform ILOG JRules that the object has been modified. rule NumberingUpdate { when { ?c: Course(department equals "history"; number > 300); } then { ?c.updateNumbering(); // This call modifies ?c update ?c; } }; Modifying an object in the working memory might cause a logical object to lose one or several of its justifications. For more details refer to the Truth Maintenance System information in the Rule Engine User’s Manual. A logical object should never be modified. ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS More information about the update method can be found in the ILOG JRules API Reference Manual. Warning: If you do not use modify, you must use the update primitive to inform ILOG JRules that objects have been modified. Forgetting to notify ILOG JRules of modifications leads to inconsistent states. Control Flow Statements For controlling the flow of the action part of a rule, the ILOG Rule language has three loop constructs, an if/else statement, a for statement, and a while statement. It also uses branching statements (break, continue, return) and exception handling statements (try, catch, finally) that follow the Java language specification. The if/else Statement The if statement enables rule actions to selectively execute other statements based on some criteria. For example, suppose that your ruleset prints debugging information based on the value of a Boolean variable named DEBUG. If DEBUG is true, your ruleset prints debugging information, such as the value of a variable x. Otherwise, your ruleset proceeds normally. A segment of code to implement the action might look like this: if (?DEBUG) { System.out.println("DEBUG: x = " + ?x); } This is the simplest version of the if statement: The block governed by the if is executed if a condition is true. Generally, the simple form of if can be written like this: if (test) { statements } What if you want to perform a different set of statements if the expression is false? You use the else statement. Consider another example: suppose your ruleset needs to perform different actions depending on whether the user clicks the OK button or another button in an alert window. Your ruleset could do this by using an if statement along with an else statement: bind ?i = 1; if ( ?i == 1 ) { System.out.println( " i = 1 " ) ; } else { System.out.println( " i <> 1 " ) ; } The else block is executed if the if part is false. Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS The for statement The for statement provides a compact way to iterate over a range of values. The general form of the for statement can be expressed like this: for (initialization; test; increment) { statements } The expression initialization is used to initialize the loop—it is executed once at the beginning of the loop. The test expression determines when to terminate the loop. This expression is evaluated at the top of each iteration of the loop. When the expression evaluates to false, the loop terminates. Finally, increment is an expression that is invoked after each iteration through the loop. Here is an example: bind ?i = 1; bind ?j = 1; for ( ?i = 1; ?i <= 3; ?i++ ) { for ( ?j = 1; ?j <= 3; ?j++ ) { System.out.println(" i =" + ?i + " j = " + ?j ) ; } } Often for loops are used to iterate over the elements in an array or the characters in a string. The following sample uses a for statement to iterate over the elements of an array and print them: for (?i = 0; ?i < ?arrayOfInts.length; ?i++) { System.out.println(?arrayOfInts[?i] + " "); } The while statement You use a while statement to continually execute a block of statements while a condition remains true. The general syntax of the while statement is: while (test) { statements } First the while statement evaluates the test expression, which must return a boolean value. If the test returns true, then the while statement executes the statements associated with it. The while statement continues testing the test expression and executing its block until the test returns false. Here is an example of a while loop: bind ?i = 0 ; while ( ?i <= 3 ) { System.out.println( ?i ) ; ?i++ ; } The following example uses a while statement in the action part of the rule to iterate over an array of elements in a variable named elements. The variable elements is bound to an ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS attribute of a variable c, also named elements. The variable c is declared in the condition part of the rule as a collection of ManagedObject(). See the Collection of Objects information in the Rule Engine User’s Manual for an explanation of collections. rule foundManagedObject { when { ?c: collect ManagedObject(); } then { bind ?elements = ?c.elements(); while (?elements.hasMoreElements()) { System.out.println(elements.nextElement()); } } Branching Statements The ILOG Rule language supports three branching statements: break statement, continue statement, and return statement. The break statement The break statement terminates a for or a while loop when the statement is found. In a for loop, for example, the flow of control transfers to the statement following the enclosing for as shown here: bind ?i = 1; bind ?j = 1; for ( ?i = 1; ?i <= 3; ?i++ ) { for ( ?j = 1; ?j <= 3; ?j++ ) { if ( ?i == ?j ) { break ; } System.out.println("i = " + ?i + ", j = " + ?j "\n") ; } System.out.println("i and j are both equal to 3" ) ; } It is important to remember that the break statement ends only the loop in which it appears. If two loops are nested, a break in the inner loop exits that loop but not the outer loop. The output of the example is shown here: i = 1, j = 1 i = 2, j = 2 i and j are both equal to 3 The continue statement You use the continue statement to skip the current iteration of a for or while loop. Instead of ending the loop like the break statement, the continue statement skips all following statements in the loop body and triggers the next iteration of the loop. The continue statement is demonstrated in the following example. bind ?whitePaper = new StringBuffer( "Business Rules, Powering Business and e-Business"); bind ?max = ?whitePaper.length(); bind ?numSs = 0; bind ?i = 0; Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS for (?i = 0; ?i < ?max; ?i++) { if (?whitePaper.charAt(?i) != ’s’) continue; ?numSs++; ?whitePaper.setCharAt(?i, ’S’); } System.out.println("Found " + ?numSs + " s’s in the string.\n"); System.out.println(?whitePaper); Here is the output: Found 10 s’s in the string. BuSineSS RuleS, Powering BuSineSS and e-BuSineSS The example steps through a string buffer checking each letter. If the current character is not an s, the continue statement skips the rest of the statements in the loop and proceeds to the next iteration to test the next character. If it is an s, the rule increments a counter and converts the s to uppercase. The return statement You use return to exit from the current function. The flow of control returns to the statement that follows the original function call. The return statement has two forms: one that returns a value and one that does not. To return a value, simply put the value (or an expression that calculates the value) after the return keyword: return ++count; The data type of the value returned by return must match the type of the function’s declared return value. When a function is declared void, use the form of return that does not return a value: return; Exception handling statements The ILOG Rule language provides the Java language mechanism known as exceptions to help report and handle errors. When an error occurs, the ruleset throws an exception. This means that the normal flow of the ruleset is interrupted, and the rule engine attempts to find an exception handler—a block of code that handles a particular type of error. The exception handler generally performs the necessary actions to recover from the error. Before you can catch an exception, code somewhere must throw one. Any Java code can throw an exception. Regardless of who (or what) throws the exception, it is always thrown with the throw statement: throw expression ; A throw expression is any kind of expression whose type is assignable to the Java Throwable type or subclass. A throw expression in ILOG JRules can be specified either in the API or in a rule. When an exception is thrown it can be caught by the API or a rule— with a try-catch-finally statement or by any Java code—which causes the IRL code to ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS execute. Note: A thrown exception is an IlrUserRuntimeException subtype of IlrRunTimeException which encapsulates the exception thrown by the throw statement. . A function is not required to declare in its throws statement any subclasses of IlrRuntimeException that might be thrown during the execution of the function. . IlrSystemRuntimeException is thrown when JRules detects an error at run time. This kind of exception cannot be recovered; it is used only for debugging purposes. . IlrUserRuntimeException , on the other hand, could be used to reset the context and relaunch the rules. The try-catch-finally statements . The try statement identifies a block of statements within which an exception might be thrown. . The catch statement must be associated with a try statement and identifies a block of statements that can handle a particular type of exception. The statements are executed if an exception of a particular type occurs within the try block. There can be as many statements following a try statement as needed. Each statement handles any and all exceptions that are instances of the class listed in parentheses, of any of its subclasses, or of a class that implements the interface listed in parentheses. . The finally statement must be associated with a try statement and identifies a block of statements that is executed regardless of whether or not an error occurs within the try block. The finally statement is generally used to clean up after the code in the try statement. If an exception occurs in the try block and there is an associated catch block to handle the exception, control transfers first to the catch block and then to the finally block. Here is the general form of these statements: try { statements } catch (ExceptionType1 name) { statements } catch (ExceptionType2 name) { statements } ... finally { statements } ILOG JRules allows general exception handlers that handle multiple types of exceptions. However, it is recommended that exception handlers be more specialized in order to Language Description ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS determine what type of exception occurred and assist in the recovery of these errors. Handlers that are too general can make code more error prone by catching and handling exceptions that were not anticipated and for which the handler was not intended. The following try statements demonstrate how to create an exception and throw it. try { method1(1) ; System.out.println("Call method1(1) was OK") ; } catch ( Exception e ) { System.out.println("Catch from method1(1) call") ; } try { method1(2) ; System.out.println("Call method1(2) was OK") ; } catch ( Exception e ) { System.out.println("Catch from method1(2) call") ; System.out.println("Exception details :-") ; System.out.println("Message: " + e) ; } The try-catch statements use a method call from a Java class to throw an exception when the variable passed into method1 is not equal to 1. Here is method1: public static void method1(i) throws Exception{ if (i == 1) { System.out.println("method1 - Things are fine \n") ; } else { System.out.println("method1 - Somethings wrong! \n") ; throw new Exception("method1 - Its an exception! \n") ; } } Exceptions thrown by any rule or Java code within the scope of the rule engine will be caught by the try-catch statements for that specific exception. The following CatchCustomer rule provides an example of a try-catch statement block capable of catching exceptions thrown by the ILOG Rule language and/or Java code. The rule uses two classes, Customer and Item, and two subclasses of the Java Exception class, TooHighExpense and IsNotMember. rule CatchCustomer { when { ?c: Customer(); ?item: Item(); } then { try { System.out.println("Customer " + ?c.getName() + " wants to buy " + " item " + ?item.getLabel() + " for a price of " + ?item.getPrice() + "$"); IsMember(?c); ILOG JRULES 4.5 — IRL REFERENCE MANUAL RULE ACTIONS ?c.buy(?item); } catch (TooHighExpense ex) { System.out.println("M/Mrs/Mz " + ?c.getName() + " you have already bought:"); bind j = 0; for(j = 0; j, >= number, number greater than, greater than or equal 5 L instanceof reference, type type comparison 5 L == primitive, primitive equal (have identical values) 4 L != primitive, primitive not equal (have different values) 4 L == reference, reference equal (refer to same object) 4 L != reference, reference not equal (refer to different objects) 4 L && boolean, boolean conditional AND 3 L || boolean, boolean conditional OR 2 L = variable, any assignment 1 R *=, /=, %=, +=, -=, variable, any assignment with operation 1 R I L OG JRUL E S 4 . 5 — IR L RE F ER EN C E MA NUA L C HAPTER Keywords This chapter documents the keywords in the ILOG Rule Language. The keywords are presented alphabetically. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL after after Summary A binary temporal constraint in an event condition. Synopsis [?var:] event className (?eventVar1 after [interval] ?eventVar2); Description The after keyword is used in the condition part of a rule in an event condition. A temporal constraint between two events is expressed using the after and before keywords. An interval is of the form [lowerBound, upperBound], where a bound is either an expression evaluating to an integer, or the $ sign which denotes infinity. Consider that the timestamp of ?event1 is t1 and that the timestamp of ?event2 is t2. The after operator can be expressed as follows: 1. ?event2 after[min,max] ?event1 is satisfied if the value of t2 - t1 is between the values of min and max, inclusive. 2. ?event2 after[min,$] ?event1 is satisfied if the value of t2 - t1 is greater than or equal to the value of min. 3. ?event2 after[$,max] ?event1 is satisfied if the value of t2 - t1 is less than or equal to the value of max. 4. ?event2 after ?event1 is satisfied if the value of t2 - t1 is positive or null. Example rule ReportAlarmPairsToUsers { when { ?u: User(); ?a1: event Alarm(); ?a2: event Alarm(?this after[1, 4] ?a1); } then { ?u.report(?a1, ?a2); } }; Assume that a User instance is in the working memory and that an Alarm instance is asserted. A partial instance of the ReportAlarmPairsToUsers rule will be created and maintained for 4 ticks. If the User instance is then retracted, the partial instance of the rule will be immediately deleted. An instance of the ReportAlarmsToUsers rule is created on each instance of the User class in the working memory when a second alarm event ?a2 is asserted no greater than 4 ticks after ?a1. See Also before, event, occursin, timeof. ILOG JRULES 4.5 — IRL REFERENCE MANUAL agendafilter agendafilter Summary The keyword used to define an agenda filter in a rule task. Synopsis (1) ruletask ruleTaskName { agendafilter = filter (variableName) { action1 ... actionn } }; (2) ruletask ruleTaskName { agendafilter = value; }; Description Synopsis (1) presents a way to define an agenda filter in the rule task. In this case the code of the agenda filter is inlined in the task definition. It can be seen as a JRules function with an ilog.rules.engine.IlrRuleInstance parameter and whose return type is Boolean. The variable in parentheses represents this IlrRuleInstance object. It can be referenced in the inlined code of the agenda filter. Ruleset variables are accessible from the agenda filter code. This agenda filter will be applied on each instance of rules that compose the task body. The instance for which the agenda filter returns true will be effectively fired; otherwise it is not. Synopsis (2) presents a second way to define an agenda filter in the rule task. In this case the agenda filter is an instance of a class that will implement ilog.rules.engine.IlrAgendaFilter. This filter will be applied on each instance of rules that compose the task body. The instance for which the agenda filter returns true will be effectively fired; otherwise it is not. Examples ruletask ruletask1 { body = select(?rule) {return true;} agendafilter = filter(?instance) { bind deployed = ?instance.getRule().getProperties().getBoolean ("deployed", ""); if (deployed) return true; // the instance will be fired else return false; // the instance will not be fired Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL agendafilter } }; This example defines a rule task ruletask1 whose body is composed of all the ruleset rules. The agenda filter defined on the task filters the rule instances whose property deployed is set to true. Only these instances will be fired; the others will not. ruletask ruletask1 { body = select(?rule) {return true;} agendafilter = new MyAgendaFilter(); }; This example defines another rule task whose body is composed of all the ruleset’s rules. The agenda filter defined on the task is an instance of the Java class MyAgendaFilter that will implement ilog.rules.engine.IlrAgendaFilter. See Also ruletask. ILOG JRULES 4.5 — IRL REFERENCE MANUAL apply apply Summary A right-hand side statement that modifies objects without updating the agenda. Synopsis apply object {statement1 ... statementn}; Description The apply statement is used in the action part of a rule and in a function. An object of the working memory may be modified by applying the statement block. The statements may be assignment expressions or method calls. The object may be defined by a variable or an expression that denotes an object, associated with the current context or a specified context. If only a single statement is used, the braces ({}) are not required. The apply statement does not update the rules of the agenda, as opposed to the modify statement which does. If the statement block modifies the object, the rules of the agenda may not be in a consistent state with respect to the new contents of the object. In such a case, the update statement should be called as well. The apply statement may be used to call methods that do not modify the values of objects used in rules, such as methods modifying the display of an object (see the second example). Examples rule NewUserPreferences { when { ?u: User(state == User.NEW;); } then { apply ?u {queryUserPreferences();} update(?u); }; The NewUserPreferences rule tests for a new user and queries the user’s preferences. The single condition binds the variable ?u and object User with the field state equal to NEW. If such an object is found, the action part is executed. The apply statement calls the method queryUserPreferences() on the object variable ?u. An update is called to modify the agenda to take the user’s preferences into account. rule DrawWhenIntersection { when { ?r: Rectangle(?x:x; ?y:y); ?f: Form(shape==circle; ?this.intersect(?r)); } then { apply ?f {draw(?x,?y,Color.RED);} } } Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL apply The DrawWhenIntersection rule tests if any object Rectangle positioned at coordinates (?x,?y) intersects a circle, using the method intersect of class Form. If true, the circle will be redrawn in red, following the call to the method draw on the circle object, in the apply statement. See Also modify, update. ILOG JRULES 4.5 — IRL REFERENCE MANUAL assert assert Summary A right-hand side statement that creates an object and inserts it into the working memory. Synopsis assert [logical] [event] [(timeExpression)] object [{statement1 ... statementn}] ; Description The assert statement is used in the action part of a rule and in a function. It creates a new object of a given class, may execute statements on the scope of the object, and then inserts the object into the working memory. The object may be marked as logical, thereby invoking the Truth Maintenance System. The object may also be asserted as an event; refer to the event statement for details. If only a single statement is used, the braces ({}) are not required. The term object must be a constructor for the desired class. To allow ILOG JRules to apply the constructor, you must declared it as public in your Java code. Following the object, the assert statement may either terminate with a semicolon (;) or specify a block of executable statements. The statements must operate implicitly on the newly created object. They are executed before the object is inserted into the working memory. The assert keyword can be optionally followed by the keyword logical, indicating that the object is of a logical type. A logical object has two properties: the object is unique, and the validity of the object is maintained. The uniqueness of the object is specified using the equals method of the Java class Object, which must be redefined in your Java class (see below). First an object is created normally using the specified constructor. This object is then tested, using the equals method, to determine whether an object already exists in the working memory that equals this object. . If an existing object in the working memory equals the object, the new object is not inserted into the working memory. The existing object is set to have a new justification that corresponds to the condition part of the rule that was just fired. . If no existing object in the working memory equals the object, the new object is inserted into the working memory. This object is then maintained by the condition part of the rule that inserted it. Maintenance of a logical object means that as long as the condition part of a rule that justified the object remains true, the object is kept in the working memory. If the condition part becomes false, the object will lose a justification. A logical object that loses its last justification is automatically retracted from the working memory. For further details on the Truth Maintenance System, see the Rule Engine User’s Manual. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL assert In order to use the Truth Maintenance System, the equals method of the Java class Object must be redefined in your Java class; for example: public boolean equals (Object obj) { if (obj == null || !(obj instanceof className)) return(false); className myObj = (className)obj; return (fieldName.equals(myObj.fieldName)); } As well, you must define a hashCode method: public int hashCode() { return (fieldName.hashCode()); } Note: If several fields are used to discriminate the object, they must all be tested using equals and summed for their hashCode. After an object has been inserted into the working memory, the insertion may optionally execute a demon. To execute a demon, the class must implement the interface IlrAssertDemon and must define the method asserted. For example: public void asserted(IlrContext context) { System.out.println("Asserted className object in memory with fieldName: " + filedName ); } prints a message every time an object of the class className is inserted into the working memory. Examples assert Integer(12); assert Integer(13) { System.out.println("Inserting the value: " + intValue()); } The first assert calls the constructor of the class Integer and passes the value 12 as a parameter. The new object is then inserted into the working memory. The second assert passes the value 13 as a parameter. The ILOG JRules engine then interprets the block of executable statements while considering that the statements apply to the current object. When the method intValue is encountered, it is considered as the call to the method intValue on the current object, which returns 13 as a result. Thus, the print statement prints out: ILOG JRULES 4.5 — IRL REFERENCE MANUAL assert Inserting the value: 13 and the object is then inserted into the working memory. assert Form() { color=Red; shape=Circle; } A constructor without parameters is called. The statement block is then executed. The fields color and shape of the class Form are assigned values before the object is inserted into the working memory. Using logical objects: rule CheckTemperature { when { Sensor(type==Temperature; value>150); } then { assert logical (new Alarm()); } }; rule CheckPressure { when { Sensor(type==Pressure; value>2); } then { assert logical Alarm(); } }; Our example shows how to manage alarms in a chemical plant. If the temperature is greater than 150, an alarm must be issued. If the pressure is greater than 2, the same alarm must be issued. Here we want to have a single alarm if both temperature and pressure are exceeded. If the rule CheckTemperature is fired, an alarm is created. Since the object is logical, it is maintained by the condition of the rule. If the temperature changes and is no longer greater than 150, the alarm is automatically removed from the working memory. However, if the temperature does not change and the rule CheckPressure is fired, instead of asserting a new alarm, the existing alarm will be justified a second time, using the rule’s condition part. Note that with the assert statement there are two ways of writing the object to be inserted. Either use parentheses around the object with the keyword new preceding the object as in the first example, or without parentheses and without the keyword new, as in the second example. See Also event, retract. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL before before Summary A binary temporal constraint in an event condition. Synopsis [?var:] event className(?eventVar1 before [interval] ?eventVar2); Description The before keyword is used in the condition part of a rule in an event condition. A temporal constraint between two events is expressed using the after and before keywords. An interval is of the form [lowerBound, upperBound], where a bound is either an expression evaluating to an integer, or the $ sign which denotes infinity. Consider that the timestamp of ?event1 is t1 and that the timestamp of ?event2 is t2. The before operator can be expressed as follows: 1. ?event1 before[min,max] ?event2 is satisfied if the value of t2 - t1 is between the values of min and max, inclusive. 2. ?event1 before[min,$] ?event2 is satisfied if the value of t2 - t1 is greater than or equal to the value of min. 3. ?event1 before[$,max] ?event2 is satisfied if the value of t2 - t1 is less than or equal to the value of max. 4. ?event1 before ?event2 is satisfied if the value of t2 - t1 is positive or null. Example rule ReportAlarmPairsToUsers { when { ?u: User(); ?a1: event Alarm(); ?a2: event Alarm(?a1 before[1, 4] ?this); } then { ?u.report(?a1, ?a2); } }; Assume that a User instance is in the working memory and that an Alarm instance is asserted. A partial instance of the ReportAlarmPairsToUsers rule will be created and maintained for 4 ticks. If the User instance is then retracted, the partial instance of the rule will be immediately deleted. An instance of the ReportAlarmsToUsers rule is created on each instance of the User class in the working memory when ?a1 is no greater than 4 ticks before a second alarm event ?a2 is asserted. See Also after, event, occursin, timeof. ILOG JRULES 4.5 — IRL REFERENCE MANUAL bind bind Summary A right-hand side statement that creates a local variable for the scope of the rule. Synopsis bind variable = expression; Description The bind statement is used in the action part of a rule and in a function. It allows you to introduce a new variable that may be used for the remainder of the execution block, which is defined by braces ({}). The variable must be initialized with a value. The type of the variable matches the type returned by the expression, which is computed according to the Java language specifications. Example rule ComputeSurface { when { ?c: Circle(?r: radius); } then { bind ?s = ?c.computeSurface(?r); System.out.println("Surface is: " + ?s + "."); } }; The rule ComputeSurface computes the surface area of a circle. The condition Circle returns the radius in variable ?r and the circle object in variable ?c. The method computeSurface is called on the object with the radius, and the result is placed in the new variable ?s, using the bind statement. The variable ?s is bound to the value of a static method call. If the method returns a float, then ?s is of type float. See Also var. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL body (in flow task) body (in flow task) Summary The keyword used to define a flow task body. Synopsis flowtask flowTaskName { body {ruleflow} }; Description Note: The ruleflow syntax is described in Chapter 3, Language Grammar. The flow task body defines a ruleflow. It is composed of task invocations that are chained together through control statements. The control statements are: sequence, if, switch, while (break and continue), fork, goto. Example flowtask main { body = { while(!ending) { if (turn == Constants.Player1) ChooseMovePlayer1; else ChooseMovePlayer2; CheckMove; if (ending) break; UpdateDistance; ExpandObjects; DetectConnect4; if (ending) break; DetectGridFull; if (ending) break; ChangeTurn; } EndOfGame; } }; See Also goto, fork, if/else (in ruleflow), switch/case/default, while/break/continue (in ruleflow). ILOG JRULES 4.5 — IRL REFERENCE MANUAL body (in function task) body (in function task) Summary The keyword used to define a function task body. Synopsis functiontask functionTaskName { body { action1; ... actionn; } }; Description The function task body is equivalent to a JRules function without arguments and whose return type is void. The task execution consists in executing the statements that compose its body (after its initial actions and before its final actions, if they are defined). Example functiontask UpdateDistance { body = { bind x = move.x; bind y = move.y; for (var i = y + 1; i < 10; i++) { bind p = grid.position(x,i); if (p == null) break; p.distance--; update(p); } } }; See Also apply, assert, bind, evaluate, execute, for, functiontask, if/else, modify, retract, return, throw, try/catch/finally, update, while. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL body (in rule task) body (in rule task) Summary The keyword used to define a rule task body. Synopsis (1) ruletask ruleTaskName { body {ruleName1, ..., ruleNamen} }; (2) ruletask ruleTaskName { body = select(variableName) { action1; ... actionn; } }; (3) ruletask ruleTaskName { body = dynamicselect(variableName) { action1; ... actionn; } }; Description In synopsis (1) the rule task body is composed of the rules that have been explicitly listed by their names. These rules must belong to the same ruleset as the rule-based task. In synopsis (2) the rule task body has been specified by comprehension: the rules composing the task body have not been explicitly listed. The contents of the task body will be computed by executing the code given as body for each rule in the ruleset. This body definition can be seen as a JRules function whose return type is boolean, with an argument of type ilog.rules.engine.IlrRule. The code is executed for each ruleset rule: when it returns true, the rule become part of the rule-based task; otherwise it does not. The calculation of the body is done when the context and the ruleset are linked together. Ruleset variables are accessible from the code except for the variables tagged in and inout because they are not set when the code is executed. ILOG JRULES 4.5 — IRL REFERENCE MANUAL body (in rule task) In synopsis (3) the difference with synopsis (2) is the time at which the body is computed. In this case the rule-based task body is computed before each task’s execution. This is useful when the body content depends on variables whose values change during the ruleflow execution. All the ruleset variables are accessible from this code, without restriction. Examples ruletask DetectGridFull { ordering = literal; firinglimit = 1; body = { DetectGridFull } }; ruletask ExpandObjects { ordering = dynamic; firing = allrules; body = select(?rule) { bind ?task = ?rule.getProperties().getString("task",""); return ?task.equals("ExpandObjects"); } }; See Also rule, ruletask. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL break break Summary A right-hand side statement for exiting a loop. Synopsis break; Description The break statement is used in the action part of a rule and in a function. It permits you to exit a loop, either a while loop or a for loop. This statement forces the ILOG JRules engine to skip to the end of the containing statement block and continue to the next instruction. Example rule AlarmSurveillance { when { ?a: Alarm(state == NEW); } then { modify ?a { state = ON; } while (?a.state == ON ) { ... if (?a.level == 3) break; } } }; The AlarmSurveillance rule tests for a new Alarm object and loops while the state is equal to ON unless the level is equal to 3. The single rule condition matches an object Alarm if the field state equals the static value NEW. If such a Alarm object is matched, the action part can be executed. The modify statement is used to change the field state from NEW to ON. The while statement is used to loop as long as the field state has the value ON. An if statement tests the field level. If the level is equal to 3, a break is executed and the program exits the while loop. See Also continue, for, while. ILOG JRULES 4.5 — IRL REFERENCE MANUAL collect collect Summary A left-hand side statement to construct a collection object. Synopsis [?variable:] collect [(expression)] collectionTarget [where (collectionTest1 ... collectionTestn)]; Description The collect statement is used in the condition part of a rule to create a collection object. The collection object stores instances of the class collectionTarget that match the condition. This condition may contain tests on the class fields. The collection object may be bound to a variable for the scope of the rule. The expression is optional, but if provided, must return a collector object that implements three public methods: addElement, updateElement and removeElement. The collect statement may contain a list of tests on the collection object in the where part of the statement. The collector object, declared by expression, must implement the interface IlrCollection and its three public methods: addElement, updateElement, and removeElement. The IlrCollection interface is defined as follows: public interface IlrCollection { public void addElement(java.lang.Object element); public void updateElement(java.lang.Object element); public void removeElement(java.lang.Object element); } If the expression argument is left empty, a default collector object of type IlrDefaultCollector is used (see the ILOG Java API Reference Manual for details). The where part of the statement may contain tests that the collection object must fulfill. It may be left empty. There are several methods, including the IlrCollection interface methods, that are provided by default for all collections: size(), isEmpty(), contains(), and elements() (see the ILOG Java API Reference Manual for details). Example rule MusicCollector { when { ?s: Store(domain==MUSIC); ?c: collect(new ItemCollector(?s)) Music(store==?s; category==JAZZ; artist equals "Miles Davis"; production > 1956 & < 1965) where ( size() > 5 && ItemCollector.averagePrice() < 15.0); } then { bind ?enum = ?c.elements(); while (?enum.hasMoreElements()) { bind ?cd = (Music)enum.nextElement(); System.out.println("At " + ?s.name ILOG JRULES 4.5 — IRL REFERENCE MANUAL 49 Keywords collect "you can find the title: " + ?cd.title); } } } The MusicCollector rule collects Music objects and stores them in an ItemCollector object.The first condition returns in variable ?s the objects of class Store that have the field domain equal to MUSIC. The variable ?c refers to the ItemCollector object. The constructor for the ItemCollector object takes as an argument a Store object. The collectionTarget is the class Music with the following field values: store equal to the result in ?s; category equal to JAZZ; artist equal to the string “Miles Davis”; production between the dates 1956 and 1965. Any object matching this condition will be inserted into the object ItemCollector. For the collect statement to be true, there are two tests defined in the where part of the statement. The default method size() is used to test that the number of items in the collector is greater than 5, and the user defined method averagePrice() is used to test that the average price of the items is less than 15. If the when part of the rule is true, the then part is executed. The variable ?c refers to the ItemCollector object. The bind statement creates a variable ?enum that refers to an enumeration of the elements of the ItemCollector object. The while statement is used to print the name field of the Store object and the corresponding title field of each Music object. See Also exists, from, in, not. ILOG JRULES 4.5 — IRL REFERENCE MANUAL continue continue Summary A right-hand side statement for skipping an iteration. Synopsis continue; Description The continue statement is used in the action part of a rule and in a function. It permits you to skip an iteration of a loop, either a while loop or a for loop. This statement forces the ILOG JRules engine to skip to the next test of the loop statement. Example rule StockDropWarning { packet = stock; when { ?c:Client(?a:account_number;?p:percentWarningMark); ClientStockList(account_number == ?a; ?s:stockList); } then { bind ?enum = ?s.elements(); while (?enum.hasMoreElements()) { bind ?x = (Stock)enum.nextElement(); if (?x.type == Stock.LONG) continue; if ( ((1.-?p)*?x.purchasePrice) > ?x.currentPrice ) { System.out.println("Dear "+ ?c.name + " Your stock " + ?x.ticker + " has dropped " + ((?x.purchasePrice - ?x.currentPrice) / ?x.purchasePrice ) + " percent."); } } } }; The rule StockDropWarning checks the percent change of a client’s stocks and warns if a stock price dropped by more than a certain percentage. The rule is part of a packet named stock. The condition Client returns an account number in variable ?a and a decimal value percentWarningMark in variable ?p. The second condition, ClientStockList, returns a stock list in variable ?s corresponding to the account number equal to ?a. In the action part of the rule, the while statement is used to iterate over every stock in the stock list ?s.If a stock type is equal to LONG, the continue statement cause the iteration to skip the rest of the statements in the while block and proceed to the while test. If a stock type is not equal to LONG, the difference between the purchase price and the current price is calculated. If the stock price decreased in ?p percent below the purchasePrice, a message is printed. See Also break, for, while. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL evaluate evaluate Summary A left-hand side statement for specifying tests on objects. Synopsis evaluate (expression); Description The evaluate statement is used in the condition part of a rule to test objects of the working memory. An evaluate statement must have a simple condition preceding it that binds a variable to an object or a value. Any such variable bound to an object or a value may be tested. Note that the statements not, exists, and collect are not simple conditions. An evaluate statement is true if all the tests carried out in the expression are true. The expression may be multiple tests enclosed by braces ({}). The evaluate statement differs from the not and exists statements. The not and exists statements apply tests only within the scope of their statement. The evaluate statement is more general in that it specifies tests that must be satisfied by the objects that exist in the working memory. Example rule CloseOrder { when { ?s: CustomerShipment(?id:CustomerId; ?sl:shipmentList); ?o: CustomerOrder(?id==CustomerId; ?ol:orderList); evaluate (?sl.isEqualTo(?ol)); } then { retract(?s); assert Shipped(?o,currentDate()); } }; rule CloseOrder { when { ?s: CustomerShipment(?id:CustomerId; ?sl:shipmentList); ?o: CustomerOrder(?id==CustomerId; ?ol:orderList; ?sl.isEqualTo(?ol)); } then { retract(?s); assert Shipped(?o,currentDate()); } }; The two rules show equivalent ways of testing objects of the working memory. The first rule has two conditions followed by an evaluate statement. In the second rule the test of the evaluate statement is incorporated in the second condition. For both rules, variable ?s refers to a CustomerShipment object, variable ?id returns the field CustomerId, and variable ?sl returns the field shipmentList. In the second condition, variable ?o refers to a CustomerOrder object where the CustomerId field 52 ILOG JRULES 4.5 — IRL REFERENCE MANUAL evaluate matches ?id and variable ?ol contains the field orderList. The evaluate statement calls a test, the method isEqualTo, defined in either the CustomerShipment class or the context class, which returns true if the two lists contain the same elements. If the conditions are true, the action part is executed. The CustomerShipment object is deleted from the working memory using the retract statement, and a Shipped object is inserted into the working memory using the assert statement. See Also exists, instanceof, isknown, isunknown, not. ILOG JRULES 4.5 — IRL REFERENCE MANUAL Keywords event event Summary A statement for declaring an event condition or an event object. Synopsis Condition form in the left-hand side of a rule. . An event condition can be bound to a variable: [?var:] event className (test1;...;testn); where a temporal test testi has the form: {after|before|occursin} [interval] Action form in the right-hand side of a rule. . The assert event statement: assert event [(timeExpression)] object [{statement1;...;statementn}]; Description The event statement is used in both the condition part of a rule and the action part of a rule. On the left-hand side of a rule, an event condition can be bound to a variable. The event className is defined in the statement together with tests, where testi can be either nontemporal or temporal tests. In the case of a temporal test in an event condition, a temporal constraint is expressed with test operators: after, before, occursin. The temporal constraints between two events are expressed using the after and before operators. The interval, when provided, restricts the allowed delay between the events. A temporal constraint on a single event is expressed using the occursin operator. An occursin test is satisfied if the timestamp of the event is included in the interval. The reference to variables bound to or in other event conditions is forbidden in the expression. The expression is evaluated once, when the events occurring as operands of the temporal constraint operator are asserted. Non-temporal tests and temporal constraints can be combined in the following way: ?a: event Alarm(); ?b: event Alarm(sev >= HIGH || ?this after[1,5] ?a); On the right-hand side of a rule, when an object is asserted into the working memory as an event, a timestamp is automatically associated with it. The TimeExpression defines an integer value that is used as the timestamp when asserting an event. The term object must be a constructor for the desired class. To allow ILOG JRules to apply the constructor, you must declare it as public in your Java code. The desired class may implement the IlrEvent interface. If the IlrEvent interface is not implemented, the IlrDefaultEvent class is used whenever an event object is added to the working memory. ILOG JRULES 4.5 — IRL REFERENCE MANUAL event Following the optional TimeExpression, the assert event statement may either terminate with a semicolon (;) or specify a block of executable statements. The statements are executed on the object before being inserted into the working memory. An event object can be explicitly removed from the working memory using the retract statement or with the API method IlrContext.retract. Example rule alarmManager { when { ?mo: ManagedObject(); ?operator: Operator() in ?mo.subscribers(); ?alarm1: event Alarm(managedObject == ?mo); ?alarm2: event Alarm(managedObject == ?mo; ?this after[1, 5] ?alarm1); } then { System.out.println("Seen two alarms on " + ?mo.name); ?operator.report(?alarm1, ?alarm2); } } The alarmManager rule prints a message when two alarms occur on the same managed object with a time difference between 1 and 5 clock ticks. The rule contains four conditions: . In the first condition, a variable ?mo is matched by a ManagedObject object. . The second condition returns the subscribed Operator objects in the variable ?operator. . The third condition is an event statement. The variable ?alarm1 points to an event object named Alarm with a single constraint: the value of the field managedObject is equal to the variable ?mo. . The fourth condition is also an event statement, where the variable ?alarm2 points to an event object named Alarm with the following constraints: the value of the field managedObject is equal to the variable ?mo, and the difference between the first event object timestamp and the second event object timestamp is greater than or equal to 1 and less than or equal to 5 clock ticks. There are two action statements: . The first action prints a message naming a managed object. . The second action executes an ?operator.report method using the event object variables ?alarm1 and ?alarm2. Any alarm will be automatically retracted from the working memory 6 clock ticks after its assertion. See Also after, assert, before, occursin, timeof. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL execute execute Summary A right-hand side statement for grouping statements. Synopsis execute {statement1 ... statementn}; Description The execute statement is used in the action part of a rule and in a function. Any ILOG Rule Language statement may be executed within the statement block as well as arithmetic expressions and method calls. A statement block may consist of one or more statements. A single statement does not require the braces ({}). The scope for the execute statement is the current context. This differs from the apply statement, where the statement block is implicitly applied to an object. If the statement block modifies an object, the rules of the agenda may not be in a consistent state with respect to the new contents of the object. In such a case, the update statement should also be applied. Example rule Selection { priority=maximum; when { ?s: Shoes(chosen); } then { execute { getPanel().select(?s); System.out.println("" + ?s.type + " is selected."); } } }; The rule Selection has a priority equal to maximum. The single condition returns a Shoes object in the variable ?s, if the Boolean field chosen is set to true. The action part of the rule consists of an execute statement. The method getPanel() is defined in a subclass of the execution context. ILOG JRULES 4.5 — IRL REFERENCE MANUAL exists exists Summary A left-hand side statement that tests if a class condition is true. Synopsis exists condition; Description The exists statement is used in the condition part of a rule. It may be applied to a simple condition, an in statement, or a from statement. The exists statement tests whether the condition is true. An exists statement returns true for a simple condition if the working memory contains at least one object that can match the condition. An exists statement returns true with an in or from statement when the in or from statement returns true. An exists statement cannot be bound to an external variable. The exists statement returns true when any object in the working memory matches the condition. This condition does not discriminate which object was matched. Hence it is illegal to bind this condition to a variable. Any variable bound within the exists statement is local to the statement. The variable cannot be referred to in the remainder of the rule. The special variable ?this may be used within the exists statement to designate the current working memory object being tested. Example rule GeneralCustomerRequest { when { CustomerRequest(?item:request); exists Item(?this == ?item); } then { System.out.println(?item + " are in stock."); } }; The GeneralCustomerRequest rule uses the exists statement to verify that an item requested by a customer exists. The exists statement returns true when a single instance of the object is found, which is faster than providing all the items that match the customer’s request. In the first condition, CustomerRequest, the variable ?item is matched with the field request. In the exists statement, the Item object is represented by the variable ?this and is tested whether it is equal to the variable ?item. The action part is executed if an Item object is matched, printing that the item(s) “are in stock.” See Also collect, fork, from, in, not. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL flowtask flowtask Summary Synopsis Description The keyword used to declare a flow task. flowtask flowTaskName { [property propertyName = value;] [initialaction {action1 ... actionm}] [finalaction {action1 ... actionn}] [completionflag = value;] body {ruleflow} }; Note: The ruleflow syntax is described in Chapter 3, Language Grammar. A flow task is one of the three kinds of tasks available in the JRules ruleflow. property This attribute is used to define a user property on the task. The engine does not interpret this property. Its value can be retrieved later using the API. initialaction, finalaction A flow task can be given initial and final actions (or only one of them). Initial actions are executed before the task body. Final actions are executed after the task body. They are composed of inlined JRules code, such as JRules functions. They can be compared with a JRules function whose return type is void and without arguments. completionflag This attribute can be used to specify a Boolean value that will be evaluated after the task body finishes its execution. If this Boolean value is true, then the task is completed; its final actions, if any, are executed, and the ruleflow execution continues. If the Boolean value returns false, the task is suspended: its final actions are not executed, the ruleflow execution is suspended, and the program returns to the caller of the ruleflow execution. When the ruleflow is executed again, it starts from this suspended task. body A flow task describes how task executions are chained together and under which conditions. If a formal comment (/**...*/) precedes the task definition, it is saved so that it may be retrieved later using the API. ILOG JRULES 4.5 — IRL REFERENCE MANUAL flowtask Example flowtask main { initialaction = { turn = Constants.Player2; saved = new SavedGame(grid); for (var i = 0; i < 7; i++) for (var j = 0; j < 6; j++) assert(grid.array[i][j]); }; finalaction = { grid = null; move = null; winner = Constants.None; connect4 = null; ending = false; message = null; }; body = { while(!ending) { if (turn == Constants.Player1) ChooseMovePlayer1; else ChooseMovePlayer2; CheckMove; if (ending) break; UpdateDistance; ExpandObjects; DetectConnect4; if (ending) break; DetectGridFull; if (ending) break; ChangeTurn; } EndOfGame; } }; This example illustrates a flow task definition. When this task is executed, its initial actions are executed first. Then its body is executed. The body consists of a while loop, each loop corresponding to a player’s move in the Connect4 game. A player’s move consists of playing a move. If this move causes a Connect4 to be accomplished or the grid to be full, then the game is finished: the while loop can be interrupted by a break statement. Here the ruleflow resumes after the while loop; in this particular example, the EndOfGame task is executed. When the flow finishes execution, the task’s final actions are executed. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL flowtask See Also body (in flow task), functiontask, ruletask. ILOG JRULES 4.5 — IRL REFERENCE MANUAL for for Summary A right-hand side statement for executing a statement block numerous times. Synopsis for (initialize; test; increment) statement; Description The for statement is used in the action part of a rule and in a function. It permits you to execute multiple times the statement or a block of statements enclosed in braces ({}). The initialize, test, and increment may be any legal expression as in the Java programming language. Any ILOG Rule Language statement may be executed within the statement block as well as arithmetic expressions and method calls. Example rule ConnectivityUpdate{ when { ?n: Node(state == NEW; ?neighbors: neighbors() ); } then { bind ?i = 0; for (?i = 0; ?i < ?neighbors().size(); ?i++) { apply ( ((Node)?neighbors()).elementAt(i) ) { addLink(?n); } } update (?n); } }; The ConnectivityUpdate rule tests if a new node exists in the network and adds a link to such a new node from each of its neighbors. The single rule condition matches an object Node when the field state equals the static value NEW, and it binds the variable ?neighbors with the vector field neighbors(). If such a Node object is found, the action part can be executed. The variable ?i is initialized to 0 using the bind operator. The for statement loops for each neighbor. The apply statement is used to update the links of the neighbors with the new node using the method addLink(?n). The last action uses the update command to update the agenda concerning the new node. See Also break, continue, while. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL fork fork Summary A ruleflow statement for executing several statement blocks in parallel. Synopsis fork {ruleflowStatement} && {ruleflowStatement} [&& {ruleflowStatement}] * Description The fork statement is a ruleflow statement. It allows defining several ruleflow statement blocks that execute in parallel. Note: In JRules 4.5 the block execution is not done in parallel: the first block is executed, then the second one, and so forth. The flow continues after the fork statement when all the statement blocks of the fork statement have been executed. Example flowtask main { body = { fork { T1; T2; } && { T3; T4; } } T5; }; In the fork statement the first block will be executed, which consists of executing T1, then T2. When T2 finishes its execution, the second block is executed, consisting of executing T3, then T4. When T4 finished, all the fork blocks are finished; T5 can be executed. See Also body (in flow task), flowtask. ILOG JRULES 4.5 — IRL REFERENCE MANUAL from from Summary A left-hand side statement that supports relations between objects. Synopsis condition from expression; Description The from statement is used in the condition part of a rule to express the relations between objects. The statement returns true when the from condition matches an object that is returned by the from expression. Using the from statement, you can directly access objects not only in the working memory but also objects that are linked to other objects by fields or by method invocations. Methods that are attached directly to the context object may be called in the expression part of the statement. The from statement has performance advantages, since the pattern matching is done on a reduced number of objects and not on all the objects in the working memory (see the first example below). The from statement may also be used to access objects in a database. Using SQL queries in the expression part of the statement, you can retrieve information from a relational database (see the second example below). Examples rule FindBookStore { when { ?s: Store(city == London); ?d: Department(type == Books) from ?s.department; } then { System.out.println( "The following book store/department was found: " + ?s.address); } } The rule FindBookStore returns bookstores or stores with a book department in the city of London. The first condition provides the stores in London in variable ?s. The second condition uses this reduced set of stores to find which store has a book department. If the when part is successful, the action part will print the store(s) found. rule FindCarOwner { when { CarToMove(?l:license); ?c: Car(license == ?l); ?p: Person(?n:name) from ?c.getOwner(); } then { System.out.println("Contact " + ?n + " at telephone " ILOG JRULES 4.5 — IRL REFERENCE MANUAL 63 Keywords from ?p.telephone + " to move a " + ?c.model + " with license: " + ?l); } } The rule FindCarOwner finds the owner of a car using an SQL query to a relational database where employee information resides. The first condition matches a CarToMove object and returns a license number in variable ?l. The second condition returns, in variable ?c, a Car object found using ?l, the license number. The from statement uses the Person object to return a name in variable ?n, which matches the name of the car owner. The car owner is retrieved using an SQL query, which is launched by the getOwner() method. The action part of the rule prints the person’s name and telephone number as well as the car model and license number. See Also collect, exists, in, not. ILOG JRULES 4.5 — IRL REFERENCE MANUAL function function Summary The keyword for defining a function. Synopsis function returnType functionName (argList) {statement} Description Functions may be declared in a rule file before rule declarations. The function keyword is used to declare a function that may be called in the action part of a rule. The function declaration consists of a header part and the statement block. The header part contains the return type of the function, the function name, and a list of arguments. The argument list consists of pairs: the argument type and name, separated by commas. The statement block may contain any ILOG Rule Language right-hand side statement as well as arithmetic expressions and method calls. A statement block may consist of one or more statements. The keyword return is used to declare the value returned by the function, of the type returnType. Example function String buildMessage(Client ?c, ShoppingCart ?s) { bind ?a = ?s.getAmount(); bind ?t = ?c.getTotalAmount(); if (?a > 100.0 && ?t > 1000.0) return("Dear "+ ?c.getName() + ", you are a GOLD customer and will receive a 10% discount today!!!"); else if ( ?a > 100.0 ) return("Dear "+ ?c.getName() + ", you are a SILVER customer and will receive a 5% discount today!!!"); else if (?t > 1000.0) return("Dear "+ ?c.getName() + ", we can offer you a 10% discount on a shopping cart valued at over $100 today."); else return("Dear "+ ?c.getName() + ", we can offer you a 5% discount on a shopping cart valued at over $100 today."); } rule Promotion { when { ?s:ShoppingCart(?a:amount;?id:clientNumber); ?c:Client(clientNumber == ?id; ?t:totalPurchaseToDate); } then { System.out.println(buildMessage(?c,?s)); } }; Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL function The function buildMessage takes as arguments a Client and a ShoppingCart and returns a message with the possible discount. The bind keyword is used to assign the variable ?a with the current shopping cart amount and the variable ?t with the total purchased to date for the client. Three if statements are used to identify which discount corresponds to the client. Four cases are treated: . Current shopping cart is valued at over $100 and past purchases have exceeded $1000. . Current shopping cart is valued at over $100 and past purchases have not exceeded $1000. . Current shopping car is valued at below $100 and past purchases have exceeded $1000. . Current shopping car is valued at below $100 and past purchases have not exceeded $1000. The rule Promotion provides a client with a promotion depending on the value of the shopping cart and past purchases. The condition ShoppingCart returns an amount in variable ?a and a client number in variable ?c. The second condition, Client, returns a total amount spent in variable ?t corresponding to the client number equal to ?c. In the action part of the rule, the function buildMessage is called and returns the appropriate message, which is displayed. See Also apply, assert, bind, evaluate, execute, for, if/else, modify, retract, return, throw, try/ catch/finally, update, while. ILOG JRULES 4.5 — IRL REFERENCE MANUAL functiontask functiontask Summary The keyword used to declare a function task. Synopsis functiontask functionTaskName { [property propertyName = value;] [initialaction {action1 ... actionm}] [finalaction {action1 ... actionn}] [completionflag = value; ] body {action1 ... actionp} }; Description A function task is one of the three kinds of tasks available in the JRules ruleflow. property This attribute is used to define a user property on the task. The engine does not interpret this property. Its value can be retrieved later using the API. initialaction, finalaction A function task can be given initial and final actions (or only one of them). Initial actions are executed before the task body. Final actions are executed after the task body. They are composed of inlined JRules code, such as JRules functions. They can be compared with a JRules function whose return type is void and without arguments. completionflag This attribute can be used to specify a Boolean value that will be evaluated after the task body finishes its execution. If this Boolean value is true, then the task is completed; its final actions, if any, are executed, and the ruleflow execution continues. If the Boolean value returns false, the task is suspended: its final actions are not executed, the ruleflow execution is suspended, and the program returns to the caller of the ruleflow execution. When the ruleflow is executed again, it starts from this suspended task. body A function task is composed of inlined JRules code, such as JRules functions. The body can be seen as a JRules function whose return type is void and without arguments. If a formal comment (/**...*/) precedes the task definition, it is saved so that it may be retrieved later using the API. Example functiontask UpdateDistance { body = { Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL functiontask bind x = move.x; bind y = move.y; for (var i = y + 1; i < 10; i++) { bind p = grid.position(x,i); if (p == null) break; p.distance--; update(p); } } }; This example defines a function task whose body is the code given between the braced brackets. This code is executed when the task is called to be executed in a ruleflow. If initial actions are provided, they are executed before the task body. If final actions are defined, they are executed after the task body. See Also body (in function task), flowtask, ruletask. ILOG JRULES 4.5 — IRL REFERENCE MANUAL goto goto Summary A ruleflow statement for jumping to another ruleflow statement. Synopsis goto label; Description The goto statement is a ruleflow statement that gives the option of jumping to another statement in the ruleflow. The target statement must be labeled, and this label is the one referenced in the goto statement. A goto statement can be used in a fork or while statement if the following rules are respected: . in a fork statement if it does not jump to a statement that does not belong to one of the fork blocks. . in a while statement if it does not jump to a statement outside the while loop. Example flowtask main { body = { start: if (turn == Constants.Player1) ChooseMovePlayer1; else ChooseMovePlayer2; CheckMove; if (ending) goto end; UpdateDistance; ExpandObjects; DetectConnect4; if (ending) goto end; DetectGridFull; if (ending) goto end; ChangeTurn; goto start; end: EndOfGame; } }; The ruleflow consists of a loop implemented with the goto statement goto start, which jumps to the beginning of the flow. The loop can be interrupted under some conditions, and this interruption is implemented with goto statements goto end; start and end are the labels of the first and last ruleflow statements, respectively. See Also body (in flow task), flowtask. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL if/else if/else Summary A right-hand side statement for executing one of two statement blocks. Synopsis if (test) {statement} [else {statement}] Description The if statement is used in the action part of a rule and in a function. The test may be any legal test as in the programming language Java. If the expression returns true, the first statement block is executed and the else block is skipped over. If the expression returns false, the first block is skipped over and the statement block following the else is executed. Any ILOG Rule Language statement may be executed within the statement block as well as arithmetic expressions and method calls. A statement block may consist of one or more statements. A single statement does not require the braces ({}). The else keyword and its statement block is optional. Example rule PromotionLevel { priority = high; when { ?s:ShoppingCart(?a:amount;?id:clientNumber); ?c:Client(clientNumber == ?id; ?t:totalPurchaseToDate); } then { if (?a > 100.0 && ?t > 1000.0) assert Promotion() {level = 1;} else { if ( ?a > 100.0 ) assert Promotion() {level = 2;} else if (?t > 1000.0) System.out.println("Dear "+ ?c.name + ", we can offer you a 10% discount on a shopping cart valued at over $100 today."); } } }; The rule PromotionLevel provides a client with a promotion depending on the value of the shopping cart and past purchases. The rule has a priority value of high. The condition ShoppingCart returns an amount in variable ?a and a client number in variable ?c. The second condition, Client, returns a total amount spent in variable ?t corresponding to the client number equal to ?c. In the action part of the rule, if statements are used to identify which promotion, if any, corresponds to the client. Three cases are treated: . Current shopping cart is valued at over $100 and past purchases have exceeded $1000. . Current shopping cart is valued at over $100 and past purchases have not exceeded $1000. ILOG JRULES 4.5 — IRL REFERENCE MANUAL if/else . Current shopping car is valued at below $100 and past purchases have exceeded $1000. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL if/else (in ruleflow) if/else (in ruleflow) Summary A ruleflow conditional statement for executing one statement block or another according to a Boolean expression value. Synopsis if (test) {ruleflowStatement} [else {ruleflowStatement}] Description The if statement is a conditional ruleflow statement. The test may be any legal test as in the programming language Java. If the Boolean expression returns true, the statement block following the if is executed. If the expression returns false, the statement block corresponding to the else part is executed. Having an else part is not mandatory. Example flowtask main { body = { while(!ending) { if (turn == Constants.Player1) ChooseMovePlayer1; else ChooseMovePlayer2; CheckMove; if (ending) break; UpdateDistance; ExpandObjects; DetectConnect4; if (ending) break; DetectGridFull; if (ending) break; ChangeTurn; } EndOfGame; } }; See Also body (in flow task), flowtask. ILOG JRULES 4.5 — IRL REFERENCE MANUAL import import Summary This statement is used to import Java classes into a rule file. Synopsis import [packageName.] className|packageName.*; Description The import declarations must be the first statements in a rule file. The import statement indicates to ILOG JRules which Java classes may be used in the ruleset. The scope of the import declarations is the ruleset file. It is possible to import a specific class or an entire package. There are several Java classes that are implicitly imported. The following Java classes are automatically added by the rule interpreter: import java.lang.*; import ilog.rules.engine.*; Thus, it is not necessary to import classes of these packages explicitly. Examples import java.util.*; import userPackage.UserClass; Here are some examples of class names that may be used as a result of the above two imports: Class Name Qualified Class Name Vector java.util.Vector java.util.Vector java.util.Vector UserClass userPackage.UseClass Number java.lang.Number IlrRule ilog.rules.engine.IlrRule Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL in in Summary Synopsis Description Examples See Also A left-hand side statement that supports relations between object values. condition in expression; The in statement is used in the condition part of a rule to express the relations between values. It is used to test if the value of the condition is a member of the set of values returned by the in expression. The expression may be an array, a java.util.Vector, or a java.util.Enumeration. The in statement allows you to retrieve not only objects in the working memory but also objects that are linked to other objects by fields or by method invocations. In combination with the collect statement, the in statement allows you to express logical statements such as all, at least, and none (see examples below). The in statement provides performance advantages since the pattern matching is done on a reduced number of objects and not on all the objects in the working memory. Note: The in statement is used within a condition. ?c: Customer(); ?d: Item() in ?c.boughtItems(); The above code will retrieve the items bought by the customer even if they are not inserted in the working memory. The variable ?d will return the items bought. The method boughtItems() may return a user-defined array, a java.util.Vector, or a java.util.Enumeration. ?c: Customer(); collect Item(price > 10) in ?c.boughtItems() where (size() > 0); The in statement is used within a collect statement to retrieve all the items bought by the customer with a price larger than 10. The where part tests that the collection has at least one element, using the method size(). ?c: Customer(); collect Item(price > 10) in ?c.boughtItems() where (size() == ?c.boughtItems().length() ); This is similar to the previous example except that the where part now tests that all the items bought had a price larger than 10. This is done by testing the equality of the results from the methods size() and length(). collect, exists, from, not. ILOG JRULES 4.5 — IRL REFERENCE MANUAL insert insert Summary A right-hand side statement that creates an object and inserts it into the working memory. It is a synonym for assert. See Also assert. ILOG JRULES 4.5 — IRL REFERENCE MANUAL Keywords instanceof instanceof Summary Tests whether an expression is castable into a referenced type. Synopsis [?var:] className (expression instanceof type) Description The instanceof operator can be used in the condition part or in the action part of a rule and in a function. It tests whether the passed expression (left operand of instanceof) can be cast into the passed type (right operand of instanceof) without raising a ClassCastException. If it passed successfully, this test returns true. It returns false if the test is unsuccessful. Example rule InstanceofTest { when { ?a: Alarm(equipment instanceof Multiplex); } then { System.out.println("Alarm occurs on Multiplex"); } }; ILOG JRULES 4.5 — IRL REFERENCE MANUAL isknown isknown Summary Tests whether a class attribute has an initialized value. Synopsis [?var:] className (?attribute isknown); Description The isknown keyword can be used in the condition part or in the action part of a rule and in a function. It tests whether the attribute has a value. In the case of the XML binding, an attribute has no value when: . the value is not given in the XML file, or . the value is given in the XML file and set to xsi:nil. In the case of Java classes, the test always returns true. That means that a Java attribute of a Java class is always considered initialized. Examples rule TestknownValue { when { ?u: User(address isknown); } then { sendToAddress(?u.address); } }; See Also isunknown. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL isunknown isunknown Summary Tests whether a class attribute has an initialized value. Synopsis [?var:] className (?attribute isunknown); Description The isunknown keyword can be used in the condition part or in the action part of a rule and in a function. It tests whether the attribute has a value. In the case of the XML binding, an attribute has no value when: . the value is not given in the XML file, or . the value is given in the XML file and set to xsi:nil. In the case of Java classes, the test always returns false. That means that a Java attribute of a Java class is never considered uninitialized. Example rule TestUnknownValue { when { ?u: User(address isunknown); } then { askForAddress(?u); } }; See Also isknown. ILOG JRULES 4.5 — IRL REFERENCE MANUAL modify modify Summary A right-hand side statement that modifies objects and updates the agenda. Synopsis modify [refresh] object {statement1 ... statementn}; Description The modify statement is used in the action part of a rule and in a function. An object of the working memory may be modified by applying the statement block. The statements may be arithmetic expressions or method calls. Modifying an object also causes the agenda to be updated. If only a single statement is used, the braces ({}) are not required. In a modify statement, the statements that modify the object are specified directly in the statement block that follows the object. This is different from the update statement where the modifications are specified before the update keyword, independent of the update statement. The apply statement is similar to the modify statement except that it does not update the rules in the agenda. If the refresh keyword is applied, rules that remain true or become true after the modification of the object are reinserted into the agenda. Without this keyword, only rules that become true as a result of the modification are inserted into the agenda. After the object has been updated in the working memory, the update can optionally launch a demon. To carry this out, the class must implement the interface IlrUpdateDemon and must define the method updated (see the update keyword for details). Examples rule InventoryUpdate { priority = high; when { Sold(item == book; ?ISBN:ISBN); ?b:Book(?ISBN == ISBN; currentStock > 0); } then { modify ?b { currentStock-=1; } } }; The InventoryUpdate rule has a high priority. The first condition matches an object Sold with field item equal to book, and instantiates the variable ?ISBN with the value of the field ISBN. The second condition uses the variable ?ISBN to match an object Book and tests that the field current_stock is greater than 0. The condition is true only if Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL modify the current stock is one or more. When both conditions are fulfilled, the action part can be executed. The object referenced by ?b is updated in the working memory by using the modify statement; the field currentStock is decremented by one. rule IncrementClock { priority = maximum; when { ?t:Time(second); ?c:Clock(time); } then { modify refresh ?c { time+=1; } retract(?t); } }; The IncrementClock rule has the highest possible priority, maximum. In the first condition the variable ?t references an object Time with a field second. In the second condition the variable ?c references an object Clock with a field time. The action part of the rule increments the field time of the Clock object, referenced by variable ?c. The refresh keyword is used to reinsert into the agenda any rule that contains a Clock object. The retract statement is used to delete the object Time from the working memory. This rule is fired whenever an object Time is inserted into the working memory. See Also apply, update. ILOG JRULES 4.5 — IRL REFERENCE MANUAL not not Summary A left-hand side statement that tests the negation of a rule condition. Synopsis not condition; Description The not statement is used in the condition part of a rule. It may be applied to a simple condition, an in statement, or a from statement. The not statement returns true if the specified condition is false. A not condition returns true for a simple condition if the working memory does not contain any object that can match the condition. A not statement returns true with an in or from statement when the in or from statement returns false. A not condition cannot be bound to an external variable. The not condition returns true when no object in the working memory matches the condition. Hence it is illegal to bind a false condition to a variable. Any variable bound within the not condition is local to the condition. It cannot be referred to in the remainder of the rule. The special variable ?this may be used within the not statement to designate the current working memory object being tested. Example rule GuestPromotion { when { ?g:Guest(?i:id); not GroupId(this.contains(?i)); } then { execute ?g.promotions(); } } The GuestPromotion rule verifies that a guest is not part of a group, in order to provide a promotion. The first condition uses the variable ?g to reference a Guest object and the variable ?i to return the field value id. The not statement is used to test if this id is contained in the object GroupId using the method contains applied to the variable ?this. The then part uses the execute statement to launch the method promotion(). See Also collect, exists, fork, in. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL occursin occursin Summary A unary temporal constraint in an event condition. Synopsis [?var:] event className (?eventVar occursin interval); Description The occursin keyword is used in the condition part of a rule in an event condition. A temporal constraint on a single event is expressed using the occursin operator. An occursin test is satisfied if the timestamp of the event is included in the interval. An interval is of the form [lowerBound, upperBound], where a bound is either an expression evaluating to an integer, or the $ sign which denotes infinity. Example rule CheckErrorReport { when { ?u: User(); ?a1: not event Check(?this occursin [1, 60]); } then { ?u.report(?a1); } }; An instance of the CheckErrorReport rule is created on each instance of the User class in the working memory when the timestamp of the Check event ?a1 does not occur between 1 and 60. See Also after, before, event, timeof. ILOG JRULES 4.5 — IRL REFERENCE MANUAL packet packet Summary A rule header property that associates a rule with a rule packet. Synopsis packet = packetName; Description A rule header may contain a parameter packet. The keyword packet is used to group rules together into packets. The packetName can be any identifier. The ILOG JRules API provides methods for manipulating rules of a packet. If not specified, a rule is not attached to a packet. Example /* The Main.java file contains the following code. */ IlrRuleset ruleset = new IlrRuleset(); boolean parsed = ruleset.parseFileName("stocks.ilr"); if (!parsed) { System.out.println("Parsing not OK."); return; } IlrContext context = new IlrContext(ruleset); int nrules = context.fireAllRules(); IlrRule[] packet = ruleset.getPacketRules("largestStock"); int npacket = context.fireRules(packet); /* the ruleset file: stocks.ilr */ rule PrintPercentStockChange { priority = ?p; when { ?s:Stock(?c:currentPrice; ?l:closingPrice; ?p:(?c-?l)/(.01*?l)); } then { System.out.println("Stock " + ?s.symbol + " % change " + ?p); } }; rule LargestPercentStockChange { packet = largestStock; when { ?s:Stock(?c:currentPrice; ?l:closingPrice; ?p:(?c-?l)/?l); not Stock(?c1:currentPrice; ?l1:closingPrice; ?p <(?c1-?l1)/?l1); } then { System.out.println("Stock " + ?s.symbol + " has the largest % change " + ?p*100); } }; Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL packet The Main file contains the ILOG JRules API code for creating and executing the ruleset. There are two calls to fire rules of the stocks.ilr file. The fireAllRules method causes all the rules with no packet name to be eligible. This causes the rule PrintPercentStockChange to fire. The rule LargestPercentStockChange of the packet largestStock will fire only after the rules of this packet are included in the agenda. The rule is inserted in the agenda following the call to the method getPacketRules and the call to the method fireRules with the corresponding ruleset object packet. See Also rule. ILOG JRULES 4.5 — IRL REFERENCE MANUAL priority priority Summary A rule header property that controls the sequence of rule execution. Synopsis priority = {maximum|high|low|minimum|expression}; Description A rule header may contain a parameter priority. The priority may be an integer expression. If not specified, the value 0 is used as the default priority. The priority of a rule determines its position in the agenda. The priority can be static or dynamic. A static priority may be used to alter the sequence of rule execution among different rules. Static priorities are any integer between -109 and +109. The larger the number, the higher the firing priority of the rule. Four predefined constants of the IlrPriorityValues class are provided to be used as static priorities. They have the following values: . maximum: 1,000,000,000 . high: 1,000,000 . low: -1,000,000 . minimum: -1,000,000,000 When rules have the same priority, a conflict set resolution strategy is applied. Rules are processed in the agenda according to the order by which they are listed. Rules are listed in the agenda with most recently inserted being before less recently inserted. For rules inserted at the same time, the order the rules appear in the agenda corresponds to the order the rules appear in the ruleset source file. (For further details see the Rule Priorities information in the Rule Builder User’s Manual.) A dynamic priority may be used to alter the order of execution between several instances of the same rule, when several rule instances are in the agenda. Dynamic priorities are expressions whose value depends on variables bound in the condition part of a rule. All variables defined in the condition part of the rule and whose scope is global, that is, for the entire rule, can be used in the expression. If the expression returns a noninteger, it is converted into an integer following the Java language specification. The predefined priority values may be used within an expression, for example priority = high + ?p. Examples rule StaticExample { priority = high; when ... then ... } Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL priority The rule StaticExample has a static priority value of high, meaning it will be listed in the agenda before rules with a priority lower than 1,000,000. rule ActiveStockByChange{ priority = ?c; when { ?s:Stock(?p:currentPrice; ?l:lastClosingPrice; ?c = (?p-?l)/?l); } then { System.out.println(?s.symbol +" : price: "+ ?p + " change: "+ ?c); } The rule ActiveStockByChange has a dynamic priority equal to the percent change of the stock price. This means that for all the Stock objects of this class, the order of rule execution will be according to the change in price. The larger the positive change, the earlier the rule will fire. The larger the negative change, the later the rule will fire. See Also rule. ILOG JRULES 4.5 — IRL REFERENCE MANUAL property property Summary The keyword to declare a rule or ruleset property. Synopsis property propertyName = value; Description The property keyword is used to declare specific properties in the rule file. The propertyName is any identifier and value is of type String, except for system-defined properties. The property keyword may be used at two levels: the ruleset level and the individual rule level. . At the ruleset level the property declaration must appear after the import statement and before the setup statement. There is one system-defined property, context.class, which may be set to a class name. . At the rule level the property declaration is part of the rule header. There is one system-defined property, activation, which may be set to true. Other properties may be declared by the user at both the ruleset level and the rule level. Examples ruleset Vacation { property context.class = vacationAgent.VacationContext; property author.lastname = "Brans"; property author.firstname = "Sue"; } When used at the ruleset level, the property keyword is enclosed by a declaration that begins with the word ruleset, followed by any identifier. The system-defined property context.class is set to the context vacationAgent.VacationContext. Two user-defined properties store the first and last name of the ruleset author. Rule CdUpdate { priority = low; property activation = true; property lastChangeDate = "22 02 03"; when { ... When used at the rule level, the property keyword is part of the header declarations. The system-defined rule property activation is set to true. A user-defined property declares the date the rule was last changed. Note that the value is of type String. See Also flowtask, functiontask, rule, ruleset, ruletask. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL retract retract Summary A right-hand side statement that removes an object from the working memory. Synopsis retract object; Description The retract statement is used in the action part of a rule and in a function. It removes an object from the working memory. The object may be defined by a variable or an expression that denotes an object associated with the current context or a specified context. After the object has been retracted from the working memory, the removal can optionally execute a demon. To execute a demon, the class must implement the interface IlrRetractDemon, and must define the method retracted. For example: public void retracted(IlrContext context) { System.out.println("Retracted a className object from memory with fieldName: " + fieldName); } will print a message every time a className object is retracted from the working memory. Example rule FlightDisplayExpired { when { ?f: Flight( status==ARRIVED; landingTime + 30 < currentTime() ); } then { retract ?f; } }; The FlightDisplayExpired rule removes a Flight object once the arrival time has passed 30 minutes. The first condition returns a Flight object in the variable ?f. The object field status must be equivalent to the static constant ARRIVED; the field landingTime plus 30 must be less than the time returned by the method currentTime(). If the condition is true, the object ?f is removed from the working memory by applying the retract statement. See Also assert. ILOG JRULES 4.5 — IRL REFERENCE MANUAL return return Summary A statement to return to the invoker. This statement is available only in JRules functions or inlined code in a task definition, such as initial actions, final actions, the function task body, an agenda filter, or a rule task body defined with the select or dynamicselect keyword. Synopsis return [expression]; Description The return statement returns to the invoker of the code that contains this statement. A return statement without an expression is allowed in a function whose return type is void. In the task definition, such a statement is authorized in initial actions, final actions, and the function task body. A return statement with an expression is allowed in a function whose return type is not void. The type of the returned expression must be assignable to the function return type. A return statement is not allowed in a rule (neither right-hand side nor left-hand side); it leads to a parsing error. Examples function int getOtherPlayer(int player) { if (player == Constants.Player1) return Constants.Player2; else return Constants.Player1; } This example illustrates a return statement with an expression. A function returning an int is declared. The return statements in this function are followed by int expressions. ruletask ExpandObjects { ordering = dynamic; firing = allrules; body = select(?rule) { bind ?task = ?rule.getProperties().getString("task",""); return ?task.equals("ExpandObjects"); } }; Here is a second example that illustrates a return statement with an expression. The return statement appears in a rule task body declared with the select keyword. The returned value is of boolean type. See Also function. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL rule rule Summary The keyword used to declare a rule. Synopsis rule ruleName {[priority = value;] [packet = packetName;] [property propertyName = value;] when {condition1 ... conditionn} then {[action1 ... actionm]} [else {[action1 ... actionp]}] }; Description A rule is composed of three parts: . A header part, which defines the name of the rule, its priority, properties, and associated packet. . The condition part, which begins with the keyword when, also referred to as the lefthand side (LHS) of the rule. . The action part, which begins with the keyword then, also referred to as the righthand side (RHS) of the rule. In the case where the condition part ends with an evaluate statement, the action part can have an else part, executed if the evaluate statement returns false. If it returns true, the then part is executed. If a formal comment (/**...*/) precedes the rule definition, it is saved so that it can be retrieved later using the API. Examples rule VideoCallBilling { packet = customerBilling; when { ?c:Customer(?p:phoneNo); ?v:collect (new videoCallCollection()) Usage(phoneNo == ?p; type == videoCall) where (size() > 0); } then { bind ?t = 0.; bind ?enum = ?v.elements(); while (?enum.hasMoreElements()) { bind ?x = (Usage)enum.nextElement(); ?t += ?x.charge(); } System.out.println("Dear "+ ?c.name + "Your bill for Video conference calls is : "+ ?t); } }; ILOG JRULES 4.5 — IRL REFERENCE MANUAL rule The VideoCallBilling rule collects appropriate Usage objects, sums the charge, and prints the result with the client’s name. The rule has a packet name customerBilling. The first condition returns in variable ?c the Customer object with the field phoneNo stored in variable ?p. The second condition is a collect statement. This statement returns in variable ?v a videoCallCollection object. This collection object contains Usage objects with the field phoneNo equal to the variable ?p, phoneNo from the previous condition, and field type equal to videoCall. The where part of the collect statement verifies that one or more Usage objects have been collected. The then part of the rule declares two variables using the bind statement: variable ?t, initialized to 0, and variable ?enum, set to the elements of the collection using the default collection method elements(). Using the while statement, the elements of the collection are enumerated and the Usage objects are accessed and referenced using the variable ?x. Variable ?t is used to sum the charge for each Usage object by applying the method charge(). The println statement prints the client’s name and the total charge. rule CheckTemperature { priority = high + 1; when { Sensor(type==Temperature; value>150); } then { assert Alarm(); } }; The CheckTemperature rule has a priority of 1,000,001. If an object Sensor with a field type equal to Temperature has a value greater than 150, the condition part is true and the action part is executed. An object Alarm is inserted into the working memory using the command assert. See Also packet, priority, property, ruleset, ruletask, then, when. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL ruleset ruleset Summary The keyword used to declare a ruleset. Synopsis ruleset rulesetName { [property propertyName = value;] [instances (className) = value|{value1,...,valuen};] [hasher (typeName variableName) = value;] [in typeName variableName;] [inout typeName variableName;] [out typeName variableName [= value];] [typeName variableName [= value];] }; Description A ruleset declaration is not mandatary. If present, it must contain at least the ruleset name. property Properties can be defined on the ruleset. The specific context.class property is used to declare a class from which the class of the ?context object used in this ruleset is derived. instances Class instances allow the user to declare on which instances for a specified class the rule engine will work on instead of looking for objects of this class in the working memory. There are two ways to define class instances: . Give a value whose type implements java.util.Collection. This collection contains the objects of the specified class on which the rule engine will work. . Specify explicitly the instances used by the engine. Values are given to compute these instances. The value type is derived from the specified class. hasher A hashing expression can be defined to optimize rule execution. Ruleset Variables Ruleset variables can be defined as a simple way to exchange data between the application and the ruleset. Ruleset variables are accessible from a rule, function, setup rule, or task definition in the ruleset. There are four types of ruleset variables: in, inout, out, and local. ILOG JRULES 4.5 — IRL REFERENCE MANUAL ruleset The in and inout ruleset variables cannot have an initial value specified in the ruleset. Their initialization is done through the API IlrContext.setParameters(IlrParameterMap). The out ruleset variables can be initialized in the ruleset. Their values, as well as in and inout variables, are accessible from the application through API calls: . IlrParameterMap IlrContext.getReturnValues() . IlrParameterMap IlrContext.execute() . IlrParameterMap IlrContext.execute(String taskName) . IlrParameterMap IlrContext.executeTask() Local ruleset variables can be declared. They can be used only in the ruleset; they are not visible outside the ruleset. Example ruleset Connect4 { // Provides the grid, the player and the adversary in Grid grid; out SavedGame saved; // The latest move int turn; Position move; // Who’s the winner, what is the connect4, and any other reason // to end the game. int winner = Constants.None; Connect4 connect4; boolean ending = false; String message; // Where to find the position objects. instances(Position) = ?grid.getAllPositions(); }; This example illustrates a ruleset declaration. The ruleset name is Connect4. Ruleset variables are declared. One of them, named grid, is an in ruleset variable; its initial value will be set by a call to IlrContext.setParameters. The variable saved is an out ruleset variable; its value can be obtained from the application with the different API calls listed above. The ruleset variables turn, move, winner, connect4, ending, and message are local. Instances for the class Position have been defined. For each object of type Position, bound in a rule condition part, the engine does not look for it in the working memory but in the specified list obtained with ?grid.getAllPositions(). See Also flowtask, function, functiontask, import, property, rule, ruletask. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL ruletask ruletask Summary The keyword used to declare a rule task. Synopsis ruletask ruleTaskName { [property propertyName = value;] [algorithm = default|sequential;] [matchedclasses = matchedClasses] [iterator = value;] [ordering = dynamic|sorted|literal;] [firing = allrules|rule;] [firinglimit = integer value;] [agendafilter = agendaFilter] [completionflag = value;] [initialaction {action1 ... actionm}] [finalaction {action1 ... actionn}] body body }; where: . matchedClasses is given a value in one of two ways: matchedclasses = {class1, class2, ..., classn} matchedclasses = value; . agendaFilter is defined in one of two ways: agendafilter = filter(?instance) {action1 ... actions} agendafilter = value; . body is defined in one of three ways: body {ruleName1, ruleName2,..., ruleNamep} body = select(?rule) {action1 ... actionq} body = dynamicselect(?rule) {action1 ... actionr} Description A rule task is one of the three kinds of tasks available in the JRules ruleflow. property This attribute is used to define a user property on the task. The engine does not interpret this property. Its value can be retrieved later using the API. algorithm The value following this keyword indicates which algorithm will be used to fire the rules: the traditional Rete (the algorithm value is then default, which is its default value) or the sequential mode (the algorithm value is sequential). ILOG JRULES 4.5 — IRL REFERENCE MANUAL ruletask matchedclasses, iterator These keywords are used to configure the rule task in case the rule engine algorithm is sequential. This algorithm needs to know on which objects the rules will be fired because it does not use the working memory. These objects are given to the engine by tuples. The tuples can be either inferred from the working memory or specified through the iterator keyword. The value following the keyword is the instantiation of an object whose class implements the ilog.rules.engine.IlrTupleIterator interface. This iterator provides the tuples of objects on which the sequential algorithm will be applied. In this case it is necessary to indicate how the tuples are formed, that is, the type of the objects that compose the tuple. This information is given as the value of the matchedclasses keyword. There are two ways to define the matched classes, either by giving the explicit list of classes names or by referencing a value whose type implements java.util.Collection. This collection object contains the references to ilog.rules.bom.IlrClass objects. ordering, firing, firinglimit A rule task aims at firing rules. It is possible to finely parameterize the firing of rules: how are the rules ordered and how many rules will be fired. The keyword ordering specifies how the rules are sorted. The possible values are: . dynamic: the rule instances are sorted in the agenda according to the traditional rules presented for the agenda in the Rule Engine User’s Manual . sorted: the rules are sorted by static priority in increasing order . literal: the rules are ordered in the same way they have been listed in the rule task body. agendafilter JRules 4.0 introduced the agenda filter feature to allow filtering of the rules in the agenda that will effectively be fired, according to a specify criteria. This feature is available in the rule task definition through the agendafilter keyword. completionflag This attribute can be used to specify a Boolean value that will be evaluated after the task body finishes its execution. If this Boolean value is true, then the task is completed; its final actions, if any, are executed, and the ruleflow execution continues. If the Boolean value returns false, the task is suspended: its final actions are not executed, the ruleflow execution is suspended, and the program returns to the caller of the ruleflow execution. When the ruleflow is executed again, it starts from this suspended task. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL ruletask initialaction, finalaction A rule task can be given initial and final actions (or only one of them). Initial actions are executed before the task body. Final actions are executed after the task body. They are composed of inlined JRules code, such as JRules functions. They can be compared with a JRules function whose return type is void and without arguments. body A rule task is composed of a list of rules that compose its body. The rule list can be specified either by extension: the rule names are explicitly given, or by comprehension: the rule list is computed from the code that is given (using select or dynamicselect keywords). The given code must return a boolean value. If a formal comment (/**...*/) precedes the task definition, it is saved so that it can be retrieved later using the API. Examples ruletask DetectConnect4 { ordering = literal; body = { DetectConnect4, DetectGridFull } }; This is a rule task whose body is composed of the rules DectectConnect4 and DetectGridFull. The rule ordering is set to literal, which means that the order in which the rules are listed in the body is kept for the execution. ruletask ChooseMovePlayer1 { initialaction = { move = null; }; body = select(?rule) { bind ?task = ?rule.getProperties().getString("task",""); return ?task.equals("ChooseMovePlayer1"); } ordering = sorted; firing = rule; }; This a rule task whose body is defined by comprehension. To compute the body, the code is executed for each rule in the ruleset. Those whose returned value is true are part of the rule task body. The others are not part of the body. The ordering here is set to sorted, which means that the rules are sorted by static priority in decreasing order before being fired. ILOG JRULES 4.5 — IRL REFERENCE MANUAL ruletask The firing value is set to rule, which means that only one rule is executed among the rules that compose the body, even if several are firable. The initial actions are executed before the task body. If final actions are provided, they will be executed after the task body. See Also agendafilter, body (in rule task), flowtask, functiontask. ILOG JRULES 4.5 — IRL REFERENCE MANUAL Keywords setup setup Summary The keyword to initialize a rule execution context. Synopsis setup { [apply|assert|bind|if|execute|modify|update|retract|while] action1 ... [apply|assert|bind|if|execute|modify|update|retract|while] actionn }; Description The setup rule initializes an execution context. There can be at most one setup rule per ruleset, that is, for each .ilr file, or none at all. The setup rule can use any of the action statements: apply, assert, execute, if, modify, retract, update, and while, except for timeout. A setup rule has no conditions, only actions. It is executed as soon as the creation of the execution context is completed. A setup rule can be used to initialize the objects of the working memory. The setup rule can also be executed using the ILOG JRules API. Examples setup { assert Star() }; The setup rule inserts into the working memory a single initial object, Star(). A constructor, Star(), must exist for creating the object. This object may serve as a condition to launch a rule of the ruleset. setup { assert UsedCar() { mark = "Porsche"; model = "911"; year = 1996; color = silver; price = 80000; milage = 47000; } }; The setup rule inserts into the working memory a UsedCar object, using the constructor UsedCar(). The values for the various fields are provided within the statement block for the assert. See Also apply, assert, execute, for, if/else, modify, retract, throw, try/catch/finally, update, var, while. ILOG JRULES 4.5 — IRL REFERENCE MANUAL switch/case/default switch/case/default Summary A ruleflow conditional statement for executing one statement block or another according to an integer expression value. Synopsis switch (expression) { case value1: {ruleflowStatement} ... case valuen: {ruleflowStatement} default: {ruleflowStatement} } Description The switch statement is a conditional ruleflow statement. The integer expression is evaluated. If there is a case block whose value is equal to the evaluated expression, then the corresponding statement block is executed. If no block with the requested value is found, then the default block is executed. Example ruleset r { int count; } flowtask main { body = { switch(count) { case 1: { T1; } case 3: { T2; } default: { T3; } } } }; Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL switch/case/default This example illustrates a switch statement. The count variable on which the switch is executed is a ruleset variable in this example. When the switch is executed, the value of the count variable is evaluated. Depending on its value, one of the switch statement blocks is executed. If the count equals 1, the first case block (case 1) is executed. If it equals 3, the second case block (case 3) is executed. Otherwise the default block is executed. See Also body (in flow task), flowtask. ILOG JRULES 4.5 — IRL REFERENCE MANUAL then then Summary The action part of a rule. Synopsis then { [apply|assert|bind|if|execute|modify|update|retract| timeout|while] action1 ... [apply|assert|bind|if|execute|modify|update|retract| timeout|while] actionn } Description The keyword then specifies the action part of a rule, also known as the right-hand side (RHS). It may contain one or more action statements to be performed when the rule is fired, or may be empty. Variables defined in the condition part of a rule may be used in the action part of the rule, except for variables defined within not and exists statements. The timeout action must be associated with a wait condition; see the statement var for details. Example rule ConnectivityUpdate{ when { ?n: Node(state == NEW; ?neighbors: neighbors() ); } then { bind ?i = 0; while (?i < ?neighbors().size()) { apply ( ((Node)?neighbors()).elementAt(i) ) { addLink(?n); } ?i +=1; } update (?n); } }; The ConnectivityUpdate rule tests if a new node exists in the network and adds a link to such a new node from each of its neighbors. There is a single rule condition that matches an object Node—when the field state equals the static value NEW—and binds the variable ?neighbors with the vector field neighbors(). If such a Node object is found, the action part can be executed. The variable ?i is initialized to 0 using the bind operator. The while statement loops for each neighbor. The apply statement is used to update the links of the neighbors with the new node using the method addLink(?n). The last action uses the update command to update the agenda concerning the new node. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL then See Also apply, assert, execute, for, if/else, modify, retract, throw, try/catch/finally, update, var, while. ILOG JRULES 4.5 — IRL REFERENCE MANUAL throw throw Summary Throws an exception to make control flow immediately to an exception handler. Synopsis throw expression Description The throw statement is used in the action part of a rule or in a function to throw an exception. The throw statement requires a single expression that is a throwable object. Throwable objects are instances of any subclass of the Java Throwable class. The exception thrown in the throw statement is not actually the thrown exception. The thrown exception is an IlrUserRuntimeException, subtype of IlrRuntimeException, that encapsulates the exception thrown in the throw statement. The IlrUserRuntimeException class provides an accessor getTargetException to get the exception thrown in the throw statement. The getTargetException signature is: public Throwable getTargetException() Example function void replaceValue(String name, Object newValue) { bind ?attr = find(name); if (?attr == null) throw new NoSuchAttributeException(name,this); ?attr.valueOf(newValue); } This example shows a function that replaces the attribute valueOf by an object called newValue. The function assigns the name string to an attr object and then tests to see if the attr object can be found. If the attr object does not exist, the NoSuchAttributeException is thrown. The thrown exception can be caught either in Java code, by catching an IlrUserRuntimeException or superclass, or in a JRules rule or function, by catching a NoSuchAttributeException or superclass. Notice that, contrary to Java, the declaration of the replaceValue function does not contain a throws statement specifying that the function can throw a NoSuchAttributeException. See Also try/catch/finally. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL timeof timeof Summary Access to an event timestamp. Synopsis timeof (?eventVar) ?time Description The value of the timeof operator applied on an event is the event timestamp returned as a long. ?time is synonymous with timeof(?this). Example rule TraceAlarms { when { ?a: event Alarm(); } then { System.out.println(timeof(?a)); } }; This rule prints a timestamp each time an Alarm object is asserted in the working memory. See Also after, before, event, occursin. ILOG JRULES 4.5 — IRL REFERENCE MANUAL try/catch/finally try/catch/finally Summary A try executes control statements with the ability to predeclare named exception handlers. A catch designates exceptions that will be caught if thrown within a try block. A finally specifies a control block to be executed after all processing of a try block, including the processing for any exceptions. Synopsis try {statements} catch (exceptionType1 identifier) {statements} [catch (exceptionType2 identifier) {statements} ...] finally {statements} Description The try-catch-finally statements are used in the action part of a rule and in a function. These statements establish a block of code for exception handling. The try, catch, and finally blocks all begin and end with curly braces. The try block must be followed by at least one catch and/or a finally statement. The try statement governs the statements enclosed within it and defines the scope of any exception handlers associated with it. The catch statements are designed to handle a specific type of exception. The code within a catch statement is executed if an exception is caught. A catch statement is declared with an exceptionType that specifies the type of exception the statement can handle and also provides an identifier the statement can use to refer to the exception object it is currently handling. The identifier must be of type Throwable or one of its subclasses. The finally statement is guaranteed to be executed if any portion of the try statement is executed, regardless of how the code in the try and catch statements completes. Examples rule division { when { ?x = Integer() ; ?y = Integer() ; } then { try { bind ?z = ?y/?x; } catch ( ArithmeticException e) { System.out.println("Exception message : " + e ) ;} } } Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL try/catch/finally Here the rule division includes a try statement in the action part of the rule. When the ?x variable is equal to zero, the division throws an ArithmeticException. The exception is caught by the catch clause which prints a message. try { ... } catch (ArrayIndexOutOfBoundsException e) { System.err.println("Caught ArrayIndexOutOfBoundsException: " + e); } catch (IOException e) { System.err.println("Caught IOException: " + e); } This example describes two catch statements, one handler for each of the two types of exceptions that can be thrown within the try block— ArrayIndexOutOfBoundsException and IOException. When an exception occurs, the first catch whose exception type is compatible with the thrown exception is executed. try{ ... } finally { if (?out != null) { System.out.println("Closing PrintWriter"); ?out.close(); } else { System.out.println("PrintWriter not open"); } } This example shows a finally statement that cleans up and closes the PrintWriter object named out. See Also throw. ILOG JRULES 4.5 — IRL REFERENCE MANUAL update update Summary A right-hand side statement that updates an object in the working memory. Synopsis update [refresh] object; Description The update statement is used in the action part of a rule and in a function. It updates an object in the working memory. The object may be defined by a variable or an expression that denotes an object associated with the current context or a specified context. When an object is modified in Java, the rules of the agenda may not be in a consistent state with respect to the new contents of the object. In such a case, the update statement should be used to notify ILOG Rules of the modification. If the refresh keyword is applied, rules that remain true or become true after the modification of the object are reinserted into the agenda. Without this keyword, only rules that become true as a result of the modification are inserted into the agenda. After an object has been updated in the working memory, the update statement can optionally execute a demon. In order to carry this out, the class must implement the interface IlrUpdateDemon and must define the method updated. For example: public void updated(IlrContext context) { System.out.println("Updated a className object in memory with fieldName: " + fieldName); } will print a message every time a className object is updated in the working memory. Example rule JobProcessing { priority = -?a; when { ?n:NewJob(?s:size;?p:priority); ?proc:Server(?a:activity; ?id:identifier); } then { retract(?n); assert( new Job(?s,?p,?id)); ?a = ?a + ?proc.updateActivity(?n); update refresh ?proc; } }; The JobProcessing rule assigns new jobs to servers based on the server activity level. The rule uses a dynamic priority equal to the negation of the activity level. The lower the activity level, variable ?a, the higher the priority; hence the server with the lowest activity level will fire first. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL update The rule has two conditions. The first condition matches an object NewJob which is returned by the variable ?n. This condition contains variable ?s, which returns the value of field size, and variable ?p, which returns the value of field priority. The second condition matches an object Server, referenced by variable ?proc. This condition contains variable ?a, which returns the value of field activity, and variable ?id, which returns the value of field identifier. The action part of the rule follows the keyword then. The first action is a retract statement applied to the NewJob object, pointed to by variable ?n. The second action is an assert statement applied to a Job object with three fields, size, priority, and identifier, represented by the three variables ?s, ?p, and ?id. A new activity value is calculated by incrementing the activity ?a with the result of the method updateActivity. This method is called on the Server object pointed to by the variable ?proc. Finally, the Server object is updated in the working memory using the update statement with the refresh keyword. Any rule matching a Server object in the condition part may be reinserted into the working memory. See Also apply, modify. ILOG JRULES 4.5 — IRL REFERENCE MANUAL var var Summary A right-hand side statement that creates a local variable for the scope of the rule. It is a synonym for bind. See Also bind. ILOG JRULES 4.5 — IRL REFERENCE MANUAL Keywords wait wait Summary Synopsis Description A left-hand side statement that incorporates time as a rule parameter. (1) wait [[until] expression] {condition}; (2) wait logical [[until] expression] [{condition}]; (3) ?variable: wait [logical] [until] expression {condition} ... then ... timeout ?variable {action} The wait statement is used in the condition part of a rule. The wait statement allows you to test if conditions become valid during a designated waiting period. It may also be used to test whether conditions remain true for a waiting period. The waiting period or time frame may be either a specific duration relative to the current time or an absolute time. If no expression is provided, the wait is indefinite. The wait statement creates a timer that delays the execution of a rule. Multiple timers can be included in a rule, and an optional timeout statement can be specified for each timer. In the wait statement (2), the keyword logical is used to designate that the previously realized conditions must remain true for the wait statement to become true. If logical is not used, all previously realized conditions are ignored, that is, they may become false during the waiting period and the wait statement may succeed. The keyword until is used to designate that the expression specifies an absolute time by which the wait statement must succeed. If until is not used, the expression specifies a relative time, that is, a specific duration as the waiting period. The expression must return an integer value. The wait statement (3) may include a timeout statement that is part of the action part of a rule. If the wait statement fails, the timeout statement is executed. The rule engine has a time counter that is updated by the application according to the application requirements. The initial value of the time counter is 0. The rule engine’s time counter can be synchronized with an external clock using the methods of IlrContext: . time() - returns the current time; . nextTime() - increments time by 1; . nextTime(long increment) - increments time by a specified increment; . setTime(long time) - sets time to a specified time. Note: It is the developer’s responsibility to synchronize the time counter with any external clock according to the application requirements. ILOG JRULES 4.5 — IRL REFERENCE MANUAL wait Examples rule DisplayScreen { when { Display(); ?to: wait 5 {User(?r:response);} } then { execute displayScreen(?r); timeout ?to { execute defaultScreen(); } } }; The DisplayScreen rule displays either a user’s chosen screen or a default screen. The rule contains two conditions. The first condition matches a Display object. The second condition is a wait statement. A wait duration of 5 time units is designated. The wait statement condition tests whether a User object is not found in the working memory within the 5 time units. There are two action statements. The first is an execute statement that launches a displayScreen method applied to the user’s response, represented by the variable ?r. This statement is executed if the wait statement succeeds. On the other hand, if the wait statement fails, that is, a User object is not found in the working memory within the designated time duration, the timeout statement is executed. The timeout statement calls an execute statement with the defaultScreen method. rule NetworkMonitoring { when { Network(?e:element; status == alive; ?m:maxLoad); not Alarm(?e); ?t:Traffic(element == ?e; ?l:load ); wait logical 1; ?a:wait logical 1 {Traffic(element == ?e; ?l2: load && ?l2 < 0.95*?m);} } then { modify ?t {?t.derivative = ?l2-?l} timeout ?a {assert Alarm(?e);} } } The NetworkMonitoring rule checks the traffic load of network elements and inserts an alarm if an element’s load passes 95% of its maximum load value. The first condition matches a Network object with variable ?e returning the value of field element, the field status being equal to alive and the variable ?m returning the value of the field maxLoad. The second condition tests that an Alarm object for the element referenced by variable ?e does not exist in the working memory. The third condition returns the Traffic object in variable ?t, where the field element is equal to variable ?e and the variable ?l returns the value of the field load. The first wait statement simply causes a wait of one time unit. The second wait statement matches within one time unit the object Traffic, as in the third condition, and the current value of the field load, returned in variable ?l2, is verified to be less than 95% of the maxLoad, using variable Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL wait ?m. If the load is below this threshold, the first action statement is executed, applying a modify statement on object Traffic with the calculated derivative of the load change. If the wait statement fails, that is, the load is above 95% for over one time unit, the timeout statement is executed. The timeout statement inserts an Alarm object with the element pointed to by the variable ?e, using the assert statement. rule WatchDogSample { when { ?a: Alarm(?id:networkElement; severity == LOW || severity == MEDIUM; ?t:time;) ?to: wait until ?t+10 {Alarm(networkElement == ?id; severity == CLEAR; time > ?t);} } then { retract ?a; timeout ?to { System.out.println("We have a problem with " + ?id " at time: " +?t); } }; The WatchDogSample rule checks if an Alarm exists for a network element and tests if the problem is regulated within 10 time units. In the first condition, the variable ?a points to an Alarm object with the following constraints: variable ?id contains the value of the field networkElement, the value of the field severity is either LOW or MEDIUM, and variable ?t contains the value of the field time. The second condition is a wait statement. Note that by not using the keyword logical, the previous conditions may turn false and the rule may still succeed. The until keyword means that the expression value is an absolute time and not a relative time. Therefore the wait condition must become valid by time ?t+10, 10 time units past the value of ?t. The wait condition tests for an Alarm object with the value of the field networkElement equal to ?id, the field severity equal to CLEAR, and field time greater than ?t. If within 10 time units an Alarm object is found that fulfills these conditions, the retract action statement is executed. The retract statement removes the Alarm object pointed to by ?a from the working memory. If the wait statement fails, the timeout statement is executed. The variable ?to designates the corresponding timeout statement for the wait statement. The timeout statement prints a message “We have a problem with” ?id “at time:” +?t. ILOG JRULES 4.5 — IRL REFERENCE MANUAL when when Summary The condition part of a rule. Synopsis when { [collect|evaluate|exists|not|wait] condition1 ... [collect|evaluate|exists|not|wait] condition2 } The keyword when specifies the condition part of a rule, also known as the left-hand side (LHS). It may be composed of one or more conditions upon which a rule can be fired. A condition can be instantiated with objects in the working memory. Using a class name, instances of that class, or instances of any derived class, may be matched. A condition may be preceded by a keyword not, exists, or evaluate. Conditions may be used to: . pattern match with objects of the working memory to test their validity. For example, Car(color == blue) tests if a Car object has a color field equal to the value blue. . instantiate a rule variable with a field of an object in the working memory. For example, given a Car object in the working memory with a field color, the condition Car(?c:color) instantiates the variable ?c with the color of the car. . bind a rule variable with an object of the working memory that fulfills the constraints of the condition. For example, ?c:Car(color == blue) will return in variable ?c a Car object with the field color equal to blue. If no such object exists in the working memory, the condition will fail. For each rule, the cardinality of rule instances in the agenda equals the product of the number of matched instances for each condition of the rule. For example, suppose we have two classes, Depart and Destination, and for each, three city instances: Paris, New York and Tokyo. rule example { when { Depart(?c1:city); Destination(?c2:city); } then { System.out.println("Possible city pairs are: " + ?c1 + ":" + ?c2); } } Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL when This rule will generate nine instances of the rule in the agenda, including the three naive results such as “Tokyo:Tokyo”. Examples rule CarColor { when { Car(color == red); not Car(color == green); } then { System.out.println("There is a red car but no green car.") } } The first condition is true if a Car object exists with the field color equal to red. The second condition tests that no Car object exists with the field color equal to green. If both conditions are true, the action is performed, printing the message “There is a red car but no green car.” rule CarsAvailableAtPriceRange { when { Request(?m: mark; ?h: highPrice; ?l: lowPrice ); ?car: UsedCar(mark equals ?m ; price < ?h & > ?l) } then { System.out.println("A " + ?car.year + " " + ?car.mark + " " + ?car.model + " is available for you."); } } The rule CarsAvailableAtPriceRange searches for a car using information supplied by the user. The rule has two condition statements and one action statement. To execute the action statement, the two condition statements must be fulfilled. In the first condition, a Request object is matched, binding the three variables ?m, ?h, and ?l with the fields mark, highPrice, and lowPrice, respectively. In the second condition, a UsedCar object is matched with the following constraints: the field mark equals ?m, and the field price has a value that is between ?h and ?l. If a UsedCar object is found that fulfills these constraints, it is bound to the variable ?car. The action part of the rule consists of printing out any car found, for example, “A 1996 BMW 573i is available for you.” Multiple cars may be printed since each UsedCar object fulfilling the constraints generates a separate rule instance (for further details, see the information on Rule Instances of the Agenda in the Rule Builder User’s Manual) See Also collect, evaluate, exists, not, wait. ILOG JRULES 4.5 — IRL REFERENCE MANUAL while while Summary A right-hand side statement for executing a statement block numerous times. Synopsis while (test) [{statement1; ... statementn;}] Description The while statement is used in the action part of a rule and in a function. The test may be any legal test as in the programming language Java. Any ILOG Rule Language statement may be executed within the statement block as well as arithmetic expressions and method calls. The statement block may be empty. If only a single statement is used, the braces {} are not required. Example rule StockDropWarning { packet = stock; when { ?c:Client(?a:account_number;?p:percentWarningMark); ClientStockList(account_number == ?a; ?s:stockList); } then { bind ?enum = ?s.elements(); while (?enum.hasMoreElements()) { bind ?x = (Stock)enum.nextElement(); if (((1.-?p)*?x.purchasePrice) > ?x.currentPrice){ System.out.println("Dear "+ ?c.name + "Your stock " + ?x.ticker + " has dropped " + ( (?x.purchasePrice - ?x.currentPrice) / ?x.purchasePrice ) + " percent."); } } } }; The rule StockDropWarning checks the percent change of a client’s stocks and warns if a stock price is below its purchase price by a certain percentage. The rule is part of a packet named stock. The condition Client returns an account number in variable ?a and a decimal value percentWarningMark in variable ?p. The second condition, ClientStockList, returns a stock list in variable ?s corresponding to the account number equal to ?a. In the action part of the rule, the while statement is used to iterate on every stock in the stock list ?s and check the difference between the purchase price and the current price. If the stock price decreased in ?p percent below the purchasePrice, a message is printed. See Also break, continue, for. Keywords ILOG JRULES 4.5 — IRL REFERENCE MANUAL while/break/continue (in ruleflow) while/break/continue (in ruleflow) Summary A ruleflow conditional statement for executing a loop while a Boolean expression value remains true. Synopsis while (test) {ruleflowStatement} Description The while statement is a conditional ruleflow statement. The test may be any legal test as in the programming language Java. While this value remains true, the statements inside the while block are executed. Any ruleflow statement can be in a while block. When the value becomes false, the execution stops executing the while block and continues the ruleflow execution after the while statement. A break statement can interrupt a while loop. When such statement is encountered, the while loop is interrupted, and the ruleflow execution continues after the while statement. A continue statement can be used in a while loop. When such a statement is encountered, ruleflow execution goes to the while statement again, reevaluates the test, and continues ruleflow execution according to this value. Example ruleset Connect4 { // The latest move int turn; // Who’s the winner, what is the connect4, and any other reason // to end the game. int winner = Constants.None; Connect4 connect4; boolean ending = false; }; flowtask main { body = { while(!ending) { if (turn == Constants.Player1) ChooseMovePlayer1; else ChooseMovePlayer2; CheckMove; if (ending) break; UpdateDistance; ExpandObjects; DetectConnect4; if (ending) break; DetectGridFull; if (ending) break; ILOG JRULES 4.5 — IRL REFERENCE MANUAL while/break/continue (in ruleflow) ChangeTurn; } EndOfGame; } This example illustrates a while statement. The while block is executed while the ending variable value remains false (because then !ending remains true). The loop can be interrupted by a break statement, executed in case the ending Boolean value becomes true. See Also body (in flow task), flowtask. ILOG JRULES 4.5 — IRL REFERENCE MANUAL Keywords while/break/continue (in ruleflow) ILOG JRULES 4.5 — IRL REFERENCE MANUAL C HAPTER Language Grammar This chapter presents the ILOG Rule Language grammar. It describes the grammar notation used. The lexical and syntactic structure of the ILOG Rule Language is presented in table form. The chapter is composed of the following sections: . Grammar Notation . Grammar Specification Language Grammar ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR NOTATION Grammar Notation The grammar notation used in this chapter follows the notation presented in “The Java Language Specification” by James Gosling, Bill Joy and Guy Steele (Addison Wesley, 1996). Terminal symbols, that is, the language keywords, are shown in Courier bold font in the syntactic and lexical rules presented in this chapter. Nonterminal symbols are shown in Times italic font in the syntactic rules. A definition of a nonterminal symbol starts with the symbol followed by a colon. For example: RulePacket : packet = Identifier ; states that the nonterminal symbol RulePacket has a single definition, which comprises the terminal token packet followed by the token equals sign, followed by an Identifier, followed by the token semicolon. A definition may have several right-hand side rules. Each rule is described on a separate line. The following example shows a nonterminal symbol with two rule definitions: TestAssignmentList : TestAssignment TestAssignmentList ; TestAssignment The syntactic definition of the nonterminal symbol TestAssignmentList can be either TestAssignment or TestAssignmentList, followed by the token semicolon, followed by TestAssignment. The subscripted suffix “opt” indicates an optional symbol. It may appear after a terminal or nonterminal symbol. For example: WaitStatement: wait untilopt Expression is equivalent to: WaitStatement: wait Expression wait until Expression When the words “one of” follow the colon in a grammar definition, they signify that each of the symbols on the following line or lines is an alternative definition. For example, the following lexical grammar rule: PriorityExpression : one of ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION maximum high low minimum Expression is a convenient abbreviation for: PriorityExpression : maximum high low minimum Expression The words “but not” are used to indicate symbols that are excluded from the rule definition. For example: ReducedPriorityExpression : PriorityExpression but not maximum is equivalent to: ReducedPriorityExpression: one of high low minimum Expression Grammar Specification This section provides the lexical grammar for the ILOG Rule Language. In the following sections, a bullet (.) before a grammar rule indicates that the terminal symbol in the rule is detailed in Chapter 2, Keywords. Syntax of an ILOG Rule Program General Form of an ILOG Rule Program RuleSetDefinition : ImportDeclarationopt RulesetPropertyDefinitionopt SetupDefinitionopt FunctionDefinitionListopt RuleDefinitionListopt TaskDefinitionListopt FunctionDefinitionList : FunctionDefinition FunctionDefinitionListopt RuleDefinitionList : RuleDefinition RuleDefinitionListopt Language Grammar ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of an ILOG Rule Program (Continued) TaskDefinitionList : TaskDefinition TaskDefinitionListopt Import Declaration ImportDeclaration : SingleTypeImportDeclaration TypeImportOnDemandDeclaration . TypeImportOnDemandDeclaration: import PackageName . * ; . SingleTypeImportDeclaration : import TypeName ; TypeName -fully qualified name of a class. Property Definition RulesetPropertyDefinition : ruleset identifier { ContextPropertyopt PropertyListopt RulesetParameterListopt HasherDefinitionListopt InstanceDefinitionListopt } . ContextProperty : property context.class = ClassName ; PropertyList : PropertyEntry PropertyListopt . PropertyEntry : property PropertyName = PropertyValue ; RulesetParameterList : RulesetParameter RulesetParameterListopt RulesetParameter : InRulesetParameter InOutRulesetParameter OutRulesetParameter LocalRulesetParameter . InRulesetParameter : in ReturnType Variable ; . InoutRulesetParameter : inout ReturnType Variable ; ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of an ILOG Rule Program (Continued) . OutRulesetParameter : out ReturnType Variable ; out ReturnType Variable = Expression ; . LocalRulesetParameter : ReturnType Variable ; ReturnType Variable = Expression ; . HasherDefinitionList : hasher ( ReturnType Variable ) = Expression ; . InstanceDefinitionList : instances ( ReturnType ) = Expression ; instances ( ReturnType ) = { InstancesList } ; InstancesList : Expression Expression , InstanceList Setup Definition . SetupDefinition : setup { SetupStatement } SetupStatement : one of RuleActionList but not TimeoutAction Function Definition . FunctionDefinition : function ReturnType FunctionName ( FunctionArgumentList ) { FunctionActionList } ReturnType : one of void boolean char byte short int long float double String ClassName FunctionArgumentList : FunctionArgument FunctionArgument , FunctionArgumentList FunctionArgument : ReturnType Variable Language Grammar ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of an ILOG Rule Program (Continued) FunctionActionList : FunctionAction FunctionActionListopt FunctionAction: one of ApplyAction AssertAction BindAction ExecuteAction ExecutableStatement ForFunctionAction IfElseFunctionAction ModifyAction RetractAction ReturnStatement ThrowAction TryFunctionAction UpdateAction WhileFunctionAction Syntax of Rules Rule Header . RuleDefinition : rule Identifier { RuleParametersopt RuleConditions RuleActions } ; RuleParameters : RulePacketopt RulePriorityopt RulePropertyopt . RulePriority : priority = PriorityExpression ; PriorityExpression : one of maximum high low minimum Expression . RulePacket : packet = Identifier ; RuleProperty : ActivationPropertyopt PropertyList ActivationProperty : property activation = true ; Rule Conditions . RuleConditions : when { FirstRuleCondition RuleConditionListopt } RuleConditionList : RuleCondition RuleConditionList RuleCondition FirstRuleCondition : RuleCondition except WaitStatementList , EvaluateCondition ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Rules (Continued) RuleCondition : one of SimpleCondition NotCondition ExistsCondition EvaluateCondition FromExpression InExpression CollectCondition WaitStatementList . SimpleCondition : Variableopt :opt eventopt ClassCondition Variable : ?opt Identifier ClassCondition : ClassName ( TestAssignmentList ) ; . NotCondition : not ClassCondition ; . ExistsCondition : exists ClassCondition ; . EvaluateCondition : evaluate ( TestAssignmentList ) ; . FromExpression : Variableopt SimpleCondition from PrimaryExpression ; . InExpression : Variableopt SimpleCondition in PrimaryExpression ; . CollectCondition : Variableopt collect ( Expressionopt ) SimpleCondition where TestAssignmentSet ; WaitStatementList : WaitLogicalStatement WaitStatement . WaitLogicalStatement : wait logical untilopt Expression WaitConditionopt Variable wait logical untilopt Expression WaitConditionopt TimeoutAction Language Grammar ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Rules (Continued) . WaitStatement : wait Expressionopt WaitConditions wait until Expression WaitConditions Variable wait Expressionopt WaitConditions TimeoutAction Variable wait until Expression WaitConditions TimeoutAction WaitConditions : { WaitConditionList } WaitConditionList : WaitCondition WaitConditionList WaitCondition : one of SimpleCondition NotCondition ExistsCondition CollectCondition Tests and Variable Bindings TestAssignmentList : TestAssignment TestAssignmentList ; TestAssignment TestAssignment : one of AndExpresssionList OrExpressionList VariableAssignment TestAssignmentSet BooleanExpression NotAssignment TemporalConstraint AndExpressionList : TestAssignment && TestAssignment OrExpressionList : TestAssignment || TestAssignment VariableAssignment : Variable Expression BooleanAssignmentListopt TestAssignmentSet : ( TestAssignment ) NotAssignment : ! TestAssignment TemporalConstraint : Expressionopt .opt TemporalOperator Arguments ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Rules (Continued) . TemporalOperator : one of after before occursin BooleanExpression : Expression BooleanArgumentList BooleanArgumentList : BooleanArgument BooleanArgumentList & BooleanArgument . BooleanArgument : BooleanTerm instanceof Identifier isknown isunknown BooleanTerm : one of PredefinedPredicate Expression PredefinedPredicate : one of == != < > >= <= Expressions Expression : AdditiveExpression AdditiveExpression : MultiplicativeExpression MultiplicativeExpressionList MultiplicativeExpressionList : + MultiplicativeExpression -MultiplicativeExpression + MultiplicativeExpressionList -MultiplicativeExpressionList MultiplicativeExpression : UnaryExpression UnaryExpressionList Language Grammar ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Rules (Continued) UnaryExpressionList : * UnaryExpression / UnaryExpression % UnaryExpression * UnaryExpressionList / UnaryExpressionList % UnaryExpressionList UnaryExpression : + UnaryExpression - UnaryExpression ++ UnaryExpression -- UnaryExpression UnaryExpression ++ UnaryExpression CastExpression TimeOfExpression PrimaryExpression CastExpression : ( ClassName ) UnaryExpression TimeOfExpression : timeof ( Expression ) ; Primary Expressions PrimaryExpression : PrimaryPrefix PrimaryPrefix PrimarySuffixList PrimaryPrefix : one of Literal Name AllocationExpression ( Expression ) Literal : one of INTEGER_LITERAL FLOATING_POINT_LITERAL CHARACTER_LITERAL STRING_LITERAL true false null Name : Identifier Variable IdentifierListopt ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Rules (Continued) IdentifierList : SingleIdentifier IdentifierList SingleIdentifier SingleIdentifier : Identifier AllocationExpression : new ClassName Arguments Arguments : ( Expression ExpressionListopt ) ExpressionList : Expression ExpressionList , Expression PrimarySuffixList : PrimaySuffix PrimarySuffixList PrimarySuffix PrimarySuffix : one of SingleIdentifier Arguments Rule Actions . RuleActions : then { RuleActionListopt } RuleActionList : RuleAction RuleActionList RuleAction RuleAction : one of ApplyAction AssertAction BindAction ExecuteAction ExecutableStatement ForAction IfElseAction ModifyAction RetractAction ThrowAction TimeoutAction TryAction UpdateAction WhileAction . ApplyAction : apply PrimaryExpression { ExecutableStatementList } ; . AssertAction : assert logicalopt eventopt ClassName Argumentsopt ExecutableActionStatementsopt Language Grammar ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Rules (Continued) . insert - synonym for assert . BindAction : bind Variable = Expression ; . var - synonym for bind . ExecuteAction : execute ExecutableStatement ExecutableActionStatementsopt . ForAction : for( ForInitopt ; TestAssignmentopt ; ForUpdateopt ) LoopRuleAction for( ForInitopt ; TestAssignmentopt ; ForUpdateopt ) { LoopRuleActionList } . ForFunctionAction : for ( ForInitopt ; TestAssignmentopt ; ForUpdateopt ) LoopFunctionAction for ( ForInitopt ; TestAssignmentopt ; ForUpdateopt ) { LoopFunctionActionList } ForInit : PrimaryExpression AssignmentOperatorExpression ForUpdate : PrimaryExpression AssignmentOperatorExpression . IfElseAction : if TestAssignmentSet RuleAction ElseStatementopt if TestAssignmentSet { RuleActionList } ElseStatementopt . ElseStatement : else RuleAction else { RuleActionList } . IfElseFunctionAction : if TestAssignmentSet FunctionAction ElseFunctionActionopt if TestAssignmentSet { FunctionActionList } ElseFunctionActionopt . ElseFunctionAction : else FunctionAction else { FunctionActionList } ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Rules (Continued) . ModifyAction : modify refreshopt PrimaryExpression ExecutableActionStatements ;opt . RetractAction : retract PrimaryExpression ; ThrowAction : throw Expression ; . TimeoutAction : timeout Variable { NonTimeoutRuleActionList } NonTimeoutRuleActionList : NonTimeoutRuleAction NonTimeoutRuleActionList NonTimeoutRuleAction NonTimeoutRuleAction : RuleAction but not TimeoutAction RuleAction : one of ApplyAction AssertAction BindAction ExecuteAction ExecutableStatement ForAction IfElseAction ModifyAction RetractAction UpdateAction WhileAction break; continue; FunctionAction : one of ApplyAction AssertAction BindAction ExecuteAction ExecutableStatement ForFunctionAction IfElseFunctionAction ModifyAction RetractAction UpdateAction WhileFunctionAction break; continue; ReturnStatement . ReturnStatement : return ( expression ) RuleActionList : RuleAction RuleActionListopt FunctionActionList : FunctionAction FunctionActionListopt Language Grammar ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Rules (Continued) . TryAction : try { RuleActionListopt } Catches or try { RuleActionListopt } Catchesopt Finally Catches : CatchClause Catches CatchClause . CatchClause : catch ( ExceptionType Identifier ) { RuleActionListopt } . Finally : finally { RuleActionListopt } . TryFunctionAction : try { FunctionActionListopt } FunctionCatches or try { FunctionActionListopt } FunctionCatchesopt Finally FunctionCatches : FunctionCatchClause FunctionCatches FunctionCatchClause . FunctionCatchClause : catch ( ExceptionType Identifier ) { FunctionActionListopt } . FunctionFinally : finally { FunctionActionListopt } . UpdateAction : update refreshopt PrimaryExpression ; . WhileAction : while TestAssignmentSet LoopRuleAction while TestAssignmentSet { LoopRuleActionList } ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Rules (Continued) . : whilewhile{} { } opt ; : : = *= /= %= += -= WhileFunctionAction TestAssignmentSet LoopFunctionAction TestAssignmentSet LoopFunctionActionList Executable Statements ExecutableStatementList : ExecutableStatement ExecutableStatementList ExecutableStatement ExecutableActionStatements : ExecutableStatementList ExecutableStatement : PrimaryExpression AssignmentOperatorExpressionAssignmentOperatorExpression AssignmentOperator Expression AssignmentOperatorone of Syntax of Tasks . : { } ; . : { } ; Tasks RuleTaskDefinition ruletask identifier CommonTaskParameters RuleTaskBody RuleTaskParametersopt opt FunctionTaskDefinition functiontask identifier CommonTaskParameters FunctionTaskBody opt Language Grammar ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Tasks (Continued) . FlowTaskDefinition : flowtask identifier { CommonTaskParameters FlowTaskBody } ;opt CommonTaskParameters : CompletionFlagParameteropt InitialActionsopt FinalActionsopt PropertyListopt . CompletionFlagParameter : completionflag = Expression . InitalActions : initialaction { FunctionActionList } . FinalActions : finalaction { FunctionActionList } RuleTaskBody : ExtendedBodyDefinition ComprehensiveBodyDefinition DynamicComprehensiveBodyDefinition . ExtendedBodyDefinition : body { RulesList } ;opt RulesList : identifier identifier , RulesList . ComprehensiveBodyDefinition : body = select ( Variable ) { FunctionActionList } ;opt . DynamicComprehensiveBodyDefinition : body = dynamicselect ( Variable ) { FunctionActionList } ;opt RuleTaskParameters : AgendaFilterParameter AlgorithmParameters FiringParameter FiringLimitParameter OrderingParameter . AgendaFilterParameter : agendafilter = INTEGER_LITERAL ; agendafilter = filter ( Variable ) { FunctionActionList } ;opt ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Tasks (Continued) . AlgorithmParameters : algorithm = AlgorithmValues ; iterator = Expression ; MatchedClasses AlgorithmValues : default sequential . MatchedClasses : matchedclasses = Expression ; matchedclasses = { MatchedClassesList } ; opt MatchedClassesList : ReturnType ReturnType , MatchedClassesList . FiringParameter : firing = FiringValues ; FiringValues : allrules rule . FiringLimitParameter : firinglimit = Expression ; . OrderingParameter : ordering = OrderingValues ; OrderingValues : dynamic sorted literal . FunctionTaskBody : body { FunctionActionList } ; opt . FlowTaskBody : body { FlowActionList } ; opt FlowActionList : FlowAction FlowActionListopt FlowAction: one of FlowTaskInvocationAction FlowForkAction FlowGotoAction FlowIfElseAction FlowSwitchAction FlowWhileAction FlowTaskInvocationAction : Labelopt identifier ; Language Grammar ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Tasks (Continued) Label : identifier : . FlowForkAction : Labelopt fork FlowForkActionList ; . FlowForkActionList : { FlowActionList } ; opt { FlowActionList } && FlowForkActionList . FlowGotoAction : goto identifier ; . FlowIfElseAction : Labelopt if TestAssignmentSet FlowAction FlowElseActionopt ; Labelopt if TestAssignmentSet { FlowActionList } FlowElseActionopt ; . FlowElseAction : else FlowAction else { FlowActionList } . FlowSwitchAction : Labelopt switch ( Expression ) { Casesopt Defaultopt } . Cases : CaseClause Cases CaseClause . CaseClause : case INTEGER_LITERAL : FlowAction case INTEGER_LITERAL : { FlowActionList } . Default : default : FlowAction default : { FlowActionList } . FlowWhileAction : Labelopt while TestAssignmentSet LoopFlowAction while TestAssignmentSet { LoopFlowActionList } ILOG JRULES 4.5 — IRL REFERENCE MANUAL GRAMMAR SPECIFICATION Syntax of Tasks (Continued) . LoopFlowAction : FlowAction break ; continue ; LoopFlowActionList : LoopFlowAction LoopFlowActionListopt ILOG JRULES 4.5 — IRL REFERENCE MANUAL Language Grammar GRAMMAR SPECIFICATION ILOG JRULES 4.5 — IRL REFERENCE MANUAL I NDEX != predicate 127 %= assignment operator 133 & combination sign 14 && conditional AND operator 126 *= assignment operator 133 += assignment operator 133 /* */ multiline comments 28 /** */ doc comments 28 // single line comments 28 /= assignment operator 133 < predicate 127 <= predicate 127 -= assignment operator 133 = assignment operator 133 == predicate 127 > predicate 127 >= predicate 127 ?context predefined variable 29 ?instance predefined variable 29 ?this predefined variable 29 ||conditional OR operator 126 A actions rule variables 17 after grammar rule 127 keyword 8, 30 statement 34 Index agendafilter grammar rule 134 in ruletask statement 94 keyword 30 statement 35 algorithm grammar rule 135 in ruletask statement 94 keyword 30 ampersand 14 AND relationships 14 apply grammar rule 129 keyword 8, 30 statement 37 assert grammar rule 129 keyword 8, 30 statement 39 asserting objects 16 assignment operators 133 attributes associating several tests 14 B before grammar rule 127 keyword 8, 30 ILOG JRULES 4.5 — IRL REFERENCE MANUAL INDEX statement 42 bind grammar rule 130 keyword 8, 30, 31 statement 43 body (in flow task) grammar rule 135 keyword 30 statement 44 body (in function task) grammar rule 135 keyword 30 statement 45 body (in rule task) grammar rule 134 keyword 30 statement 46 break grammar rule 131 keyword 8, 30, 31 statement 48 break (in ruleflow) grammar rule 137 keyword 30, 31 with ruleflow while statement 116 case grammar rule 136 keyword 30 with switch statement 99 catch grammar rule 132 keyword 8, 30, 31 with try statement 105 collect grammar rule 125 keyword 8, 30, 31 statement 49 combination sign & 14 comments 28 completionflag grammar rule 134 in flowtask statement 58 in functiontask statement 67 in ruletask statement 94 keyword 30 conditions rule 13 rule variables 14 syntax 13 conjunction 14 consistency Java/ILOG JRules 18 continue grammar rule 131 keyword 8, 30, 31 statement 51 continue (in ruleflow) grammar rule 137 keyword 30, 31 with ruleflow while statement 116 D declaring ruleset variables 3 default grammar rule 136 keyword 30 with switch statement 99 defining rule in IRL 6 dynamic priorities 85 dynamicselect grammar rule 134 in ruletask body statement 46 keyword 30 E else grammar rule 130 if statement 70 keyword 8, 30, 31 else (in ruleflow) grammar rule 136 if statement 72 keyword 30, 31 ILOG JRULES 4.5 — IRL REFERENCE MANUAL INDEX evaluate grammar rule 125 keyword 8, 30, 31 statement 52 event grammar rule 125 keyword 8, 30, 31 statement 54 execute grammar rule 130 keyword 8, 30 statement 56 exists grammar rule 125 keyword 8, 30, 31 statement 57 F false keyword 30 filter grammar rule 134 in agendafilter statement 35 keyword 30 finalaction grammar rule 134 in flowtask statement 58 in functiontask statement 67 in ruletask statement 94 keyword 30 finally grammar rule 132 keyword 8, 30, 31 with try statement 105 firing grammar rule 135 in ruletask statement 94 keyword 30 firinglimit grammar rule 135 in ruletask statement 94 keyword 30 flowtask grammar rule 134 keyword 30 statement 58 for grammar rule 130 keyword 8, 30 statement 61 fork grammar rule 136 keyword 30 statement 62 from grammar rule 125 keyword 8, 30 statement 63 function grammar rule 123 keyword 30 statement 65 functions 27 functiontask grammar rule 133 keyword 30 statement 67 G goto grammar rule 136 keyword 30 statement 69 grammar rules after 127 agendafilter 134 algorithm 135 apply 129 assert 129 before 127 bind 130 body (in flow task) 135 body (in function task) 135 body (in rule task) 134 break 131 break (in ruleflow) 137 case 136 catch 132 ILOG JRULES 4.5 — IRL REFERENCE MANUAL INDEX collect 125 completionflag 134 continue 131 continue (in ruleflow) 137 default 136 dynamicselect 134 else 130 else (in ruleflow) 136 evaluate 125 event 125 execute 130 exists 125 filter 134 finalaction 134 finally 132 firing 135 firinglimit 135 flowtask 134 for 130 fork 136 from 125 function 123 functiontask 133 goto 136 hasher 123 if 130 if (in ruleflow) 136 import 122 in 125 in (ruleset variable) 122 initialaction 134 inout (ruleset variable) 122 insert 130 instanceof 127 instances 123 isknown 127 isunknown 127 iterator 135 logical 125, 129 matchedclasses 135 modify 131 not 125 occursin 127 ordering 135 out (ruleset variable) 123 packet 124 priority 124 property 122 refresh 131 retract 131 return 131 rule 124 ruleset 122 ruletask 133 select 134 setup 123 switch 136 then 129 throw 131 timeout 131 try 132 until 125 update 132 var 130 wait 125 when 124 where 125 while 132, 133 while (in ruleflow) 136 H hasher grammar rule 123 in ruleset statement 92 keyword 30, 31 high priority 10, 85 I if grammar rule 130 keyword 8, 30, 31 statement 70 if (in ruleflow) grammar rule 136 keyword 30, 31 statement 72 import grammar rule 122 ILOG JRULES 4.5 — IRL REFERENCE MANUAL INDEX keyword 30 statement 2, 73 in grammar rule 125 keyword 8, 30 statement 74 in (ruleset variable) grammar rule 122 in ruleset statement 92 initial value 3 keyword 30 initialaction grammar rule 134 in flowtask statement 58 in functiontask statement 67 in ruletask statement 94 keyword 30 inout (ruleset variable) grammar rule 122 in ruleset statement 92 initial value 3 keyword 30 insert grammar rule 130 keyword 30 statement 75 instanceof grammar rule 127 keyword 8, 30, 31 statement 76 instances grammar rule 123 in ruleset statement 92 keyword 30, 31 isknown grammar rule 127 keyword 8, 30, 31 statement 77 isunknown grammar rule 127 keyword 8, 30, 31 statement 78 iterator grammar rule 135 in ruletask statement 94 keyword 30 K keywords 8, 30 L left-hand side 13 literals 29 local ruleset variables 4 logical grammar rule 125, 129 in assert statement 39 in wait statement 110 keyword 8, 30, 31 low priority 10, 85 M matchedclasses grammar rule 135 in ruletask statement 94 keyword 30 maximum priority 10, 85 minimum priority 10, 85 modify grammar rule 131 keyword 8, 30 statement 79 modifying objects 18 N negating objects 15 new keyword 30, 31 not grammar rule 125 keyword 8, 30, 31 statement 81 notation, grammar ix, 120 null ILOG JRULES 4.5 — IRL REFERENCE MANUAL INDEX keyword 30 O objects asserting 16 modifying 18 negating 15 removing 17 updating 18 occursin grammar rule 127 keyword 8, 30 statement 82 ordering grammar rule 135 in ruletask statement 94 keyword 30 out (ruleset variable) grammar rule 123 in ruleset statement 92 initial value 3 keyword 30 P packet grammar rule 124 keyword 8, 30 statement 83 packets 12 patterns 13 predefined predicates 127 prerequisites ix priority grammar rule 124 keyword 8, 30 statement 85 property grammar rule 122 in flowtask statement 58 in functiontask statement 67 in ruleset statement 92 in ruletask statement 94 keyword 8, 30 statement 87 R refresh grammar rule 131 in update statement 107 keyword 8, 30, 31 removing objects 17 reserved words 31 retract grammar rule 131 keyword 8, 30 statement 88 return grammar rule 131 keyword 30, 31 statement 89 right-hand side 16 rule grammar rule 124 keyword 6, 8, 30 statement 90 rule actions apply 37 assert 39 bind 43 break 48 continue 51 definition 101 execute 56 for 61 grammar rule 129 if 70 in rule structure 6 modify 79 retract 88 throw 103 try-catch-finally 105 update 107 while 115 rule conditions collect 49 definition 113 ILOG JRULES 4.5 — IRL REFERENCE MANUAL INDEX evaluate 52 exists 57 from 63 grammar rule 124, 125 in 74 in rule structure 6 mandatory 7 not 81 wait 110 rule headers grammar rule 124 in rule structure 6 packet 83 priority 85 property 87 rule structure 6 rule variables in actions 17 in conditions 14 ruleflow 26 ruleset grammar rule 122 keyword 30 statement 92 ruleset header 2 ruleset name 2 ruleset properties 2 ruleset variables 3 access 5 and initial rule 4 and task definition 4 declaring 3 in 3 inout 3 local 4 modifying 5 out 3 purpose 3 referencing 5 scope 4 ruletask grammar rule 133 keyword 30 statement 94 S select grammar rule 134 in ruletask body statement 46 keyword 30 setup grammar rule 123 keyword 30 statement 98 static priorities 85 switch grammar rule 136 keyword 30 statement 99 syntax of conditions 13 T tests associating several with the same attribute 14 then grammar rule 129 keyword 8, 30 statement 101 throw grammar rule 131 keyword 8, 30, 31 statement 103 timeof grammar rule 128 keyword 8, 30, 31 statement 104 timeout grammar rule 131 in wait statement 110 keyword 8, 30, 31 true keyword 30 try grammar rule 132 keyword 8, 30, 31 statement 105 ILOG JRULES 4.5 — IRL REFERENCE MANUAL INDEX U until grammar rule 125 in wait statement 110 keyword 8, 30, 31 update grammar rule 132 keyword 8, 30 statement 107 update action 18 updating objects 18 var grammar rule 130 keyword 8, 30, 31 statement 109 variables 29 W wait grammar rule 125 keyword 30 statement 110 when grammar rule 124 keyword 8, 30 statement 113 where grammar rule 125 in collect statement 49 keyword 8, 30 while grammar rule 132, 133 keyword 8, 30 statement 115 while (in ruleflow) grammar rule 136 keyword 30 statement 116 ILOG JRULES 4.5 — IRL REFERENCE MANUAL