How to create custom extended operators

For many developers, the quickest way to learn is by example. You might want to compare the three Java source files in the Extended Operator Java Project to see what is common and what changes. In this example, the AttributeOperators.java is presented.

1. Specify the imports and interfaces you will need.

   package com.corticon.samples.extensions;
   
   import java.util.Calendar;
   import java.util.Date;
   
   import com.corticon.services.extensions.ArgumentName;
   import com.corticon.services.extensions.Description;
   import com.corticon.services.extensions.ICcDateTimeExtension;
   import com.corticon.services.extensions.ICcStringExtension;
   import com.corticon.services.extensions.OperatorFolder;
   import com.corticon.services.extensions.TopLevelFolder;

   This class imports the Corticon ICcStringExtension and ICcDateTimeExtension interfaces because it will implement extended operators for String and DateTime attributes. The other Corticon imports are for the annotations which will be used to describe the extensions.
2. Enter your comments that describe the class.

   /**
    * This class provides sample Corticon stand-alone extended operators.
    * Extended operators are a means to add custom features to Corticon for
    * use in Corticon rules.
    * 
    * The samples in this class provide simple operators for calculating the
    * present and future value of an investment for a number of years at a given
    * interest rate.
    */

   A general description of this source file is always good coding practice. It has no use outside of the source file.
3. Specify the TopLevelFolder name.

   @TopLevelFolder("Sample Extended Operators")      

   The TopLevelFolder annotation identifies the folder that will group the extended operators on the Rule Operators tab in Corticon Studio. You can name the folder to fit your needs, such as "My Operators", or "Financial Operators".
4. Specify the class and its implementations.

   public class AttributeOperators implements ICcStringExtension, ICcDateTimeExtension {

5. Name your operator folder, and use the locale parameters if appropriate.

   	@OperatorFolder(lang = { "en" }, values = { "Date" })

   The OperatorFolder defines the subfolder that will list an individual operator within the TopLevelFolder on the Rule Operators tab in Corticon Studio. You can organize and name folders to fit your needs.

6. Add your description of the operator, and use the locale parameters if appropriate..

   	@Description(lang = { "en" }, values = { "Returns true if the date is in a leap year." }) 

   The Description annotation describes the specific operator. The hover help reveals what is passed, what is returned, and description text for the locale.

7. Write your actual implementation of the extended operator. It is always public static.

   	public static Boolean isLeapYear(Date d) {
   		if (d == null)
   			return null;
   
   		Calendar c = Calendar.getInstance();
   		c.setTime(d);
   
   		int year = c.get(Calendar.YEAR);
   		if ((year % 400 == 0) || ((year % 4 == 0) && (year % 100 != 0)))
   			return true;
   		else
   			return false;
   	}     

   The example takes a date and returns a boolean. It is up to you to determine that this produces the result you want, and that you can verify it across a range of values and error conditions.

8. The sample includes another operator definition using the same structure, this one for the String OperatorFolder. You can similarly change this section, or just cut the whole section out.

   	/**
   	 * Replaces all occurrences of a substring in a string with another string.
   	 * 
   	 * @param s A string.
   	 * @param searchString The substring to look for in s.
   	 * @param replacement The string to replace it with.
   	 * @return The original string with all instances of searchString replace by
   	 * replacement.
   	 */
   	@OperatorFolder(lang = { "en" }, values = { "String" })
   	@Description(lang = { "en" }, values = { "Replace all occurrences of a substring within a string with another string." })  
   	public static String replaceAll(String s, 
   			@ArgumentName(lang = { "en" }, values = { "searchString" }) String searchString,
   			@ArgumentName(lang = { "en" }, values = { "replacement" }) String replacement) {
   		if (s == null)
   			return null;
   
   		if (searchString == null)
   			return s;
   
   		String r = s.replaceAll(searchString, replacement);
   		return r;
   	}
   	}

9. Save your work, and then go ahead to build the Java project by right-clicking on the project name, and then choosing Export. In the Export Dialog, choose Java > Jar file. Enter a destination location for the JAR file, then choose appropriate options, and click Finish.
10. In order for the extension to get referenced by a Rules project, and then packaged with a Decision Service, you must Add the compiled Java classes to the Rules Project.
11. Create and run Ruletests that evaluate the range of possible values that could be presented to the extension. Be sure to include blanks and nulls so that you get complete coverage.