SPL Language Reference

Imperius (Simple Policy Language) or SPL - Is a simple standards based object-oriented policy language that allows expression of management policies using condition-action rules. Imperius provides an extensible set of over 100 operations for expressing conditions and actions.Imperius is a generalization of the CIM-SPL language. Conversely, CIM-SPL can be thought of as Imperius with CIM binding. Imperius can be extended to create similar bindings for other environments. JavaSPL (Imperius with Java binding) is another such example.

An SPL Policy is actually a group of one or more sub policies. Each sub policy is a simple condition - action pair. An import statement declares one or more anchor classes and instances that are referenced throughout the policy.

Canonical Policy syntax

      Import  Qualifier <namespace> Class <Class Name> : <instances>*;	(one or more)	 
      Strategy <strategy>
      Policy  (one or more)
      { 
        Declaration {
          <List of constant definition>   (Optional)
          <List of macro definitions> (Optional)
        } 
        Condition {		(Optional)
          <If Condition>  /* java-like boolean expression */
        } 
        Decision {		(Required)
          <Then Decision >  /* sequence of actions */
           /*   invocations                      */
        }
      } <priority>;
	
		
		

A Sample Policy

		Import Class org.apache.imperius.javaspl.samples.windowscomputersystem.WindowsComputerSystem:system1;

    Strategy Execute_All_Applicable;

    Declaration   {

      from = "johndoe@us.ibm.com";
      to = "johndoe@us.ibm.com";
    }
    Policy {
      Declaration 	{
      supportedJavaVersion = "1.5" ; 
    	subject = "Java version noncompliance";
      message = Concatenate( "IBM does not support java :", system1.javaVersion );
    }

    Condition 	{

      system1.javaVersion != supportedJavaVersion 

    }   

    Decision  	{  
 
       		SendMail( from, to, subject, message )
  
    }
  }:1;
		
		

Import Statement

Declares the anchor classes and the instances of these classes which are referenced throughout the policy. An anchor class encapsulates the state of the system managed using policies

Syntax: Import <qualifier> Class <classname> <instance>,...;

The Qualifier is unused by JavaSPL and there can be more than one Import statements

Strategy Statement

Allows the policy author to specify which of the sub-policies will be executed at execution time

• Execute_All_Applicable: This strategy specifies that all polices with condition evaluating to true should be executed. The policies are evaluated in the descending order of their priorities. This strategy is useful in conditions when several actions based on several different conditions need to be performed
• Execute_First_Applicable: This strategy specifies that only the policy with the highest priority with its condition evaluating to true should be executed.

Declaration Statement

Allows the policy author to declare constants and macros that can be referenced later on in the policy. Declarations support the paradigm of declare once and use anywhere. The constants and macros declared are visible within the current policy and other embedded policies. The constants declared in the Declaration section after the Strategy Statement are visible throughout the policy

Constant Declaration: As the name suggests declares a constant. The syntax is as follows:

 <constant> = <expression> 

The data type of the LHS is determined at compile time as being same as the RHS. During evaluation of a policy the RHS expression is evaluated and its result populated in the symbol table entry for the LHS.

 //Example constant declaration
       Declaration {
        x = 2;
       }
       

Macro Declaration: Macros are actually user defined functions that can be called from within the policy. The Macros can take one or more parameters and return exactly one value. Macros help in simplifying a policy by hiding the complexity of a function in the declaration section.

 Macro {
               
               Name = <string expression>;
               type = <type constant>;
               argument = <argumentname:argumenttype>,...;
               procedure = <expression with type same as the one declared in the type field of Macro>
               }
               // type constants of SPL are : Sint8, Sint16, Sint32, Sint64, Real32, Real64, String, DateTime, Boolean, Char16
      

        //Example of a Macro Declaration
        Declaration {
            Macro   /* macro that calculates avrg of 2 nos */
            {
             Name = GetAverage; /* Name of the macro */
             type = Real64; /* Return type */
             argument = number1:Sint64,number2:Sint64; /* Input parameters and types */
             procedure = (number1 + number2) / 2 /* Actual code */
            }
        
        // Sample invocation
        
        ...
        Condition {
          2 > GetAverage(8,4)
        }
        
        }
      
      

Policy Statement

Consists of a "if" "then" style rule. The "if" is specified using the Condition Statement and the "then" specified using the Decision Statement

Condition Statement: Consists of a boolean expression. If the Condition statement is absent it is assumed to be true.

          // Condition example
          Condition {
              freeMemory < freememorythreshold
          
          }
      
      
      

Decision Statement: Is a required statement that consists of one or more actions arranged in a sequence using the decision operators.

Types of Actions:

• Invoke a method on the imported anchor class instance.

  <instancename>.<method name>(<expression>[,<expression>]*) <boolean operator> <numeric return code>

                // Example of invoke method action
                anchorInstance1.method1("xx", 2) == 0
  
               

• Modify the properties of the imported anchor class instance.

  Set(<instanceName>.<argument name>=<expression>[,<argument name> = <expression>]*)

                //Example of set property action
                Set(anchorInstance1.property1 = 2, anchorInstance1.property2 = "x")
            

• Invoke a custom action. Custom actions are user created actions that are made available to the policy runtime as a jar. The ability to define custom actions enables the SPL language to be extended or customized for a user's environment.

  <custom action name>(<expression>[,<expression>]*)

              //Example of a custom action
              SendMail("xxx@mail.com","yyy@mail.com","hello","hi how are you?")
            
            

Ordering the Actions:

• If-Then action ordering.

  Execute action block1 if that succeeds then execute action block2. The result of executing the action block2 will be returned. If action block1 execution fails return without execution action block2 with failure.

  <action block1> -> <action block2>

              // If-Then action
              Decision { //Clean up the system and if that succeeds send out an email
                 system.cleanup() -> SendMail(...)
              }
              
            

  Note

  An action is deemed a success if no exceptions are thrown and if the returned value satisfies the constant boolean expression.

• Concurrency "some semantics " action ordering.

  Both action blocks are executed concurrently. If either of the action blocks executes successfully the entire execution is deemed successful.

  <action block1> || <action block2>

              // Concurrency some semantics action
              Decision { //Clean up the system and send out an email
                 system.cleanup() || SendMail(...)
              }
              
            

• Concurrency "all semantics " action ordering.

  Both action blocks are executed concurrently. Both action blocks should execute successfully for entire execution to be deemed successful.

  <action block1> && <action block2>

              // Concurrency all semantics action
              Decision { //Clean up the system and send out an email
                 system.cleanup() && SendMail(...)
              }
              
            

• Conditional action ordering.

  Action block1 is executed first if that fails only then action block2 is executed. If action block1 succeeds then the block returns with success, if block 1 fails then the result of execution will be whatever block2 returns.

  <action block1> | <action block2>

              // Conditional action
              Decision { //Clean up the system if that fials send out an email
                 system.cleanup() | SendMail(...)
              }
              
            

Priority: Priority is an integral value assigned to each policy that determines the relative order of execution among subpolicies. Higher number implies higher priority

        Policy {
        ...
        }1;
      
      

SPL supports all the basic Java data types along with the arrays of the data types

SPL ships with over a 100 core Operators. These operators are especially useful while defining complex conditions within a policy. New custom operators can be added to enhance SPL to work with a user's specific need.

Numeric Operators

These operators perform numeric calculations on numeric operands. The implementation is largely the encapsulation of the Java Math operations.

Comparison Operators

As the name suggests these operators perform comparisons among type comparable operands. The return value is always Boolean.

Boolean Operators

These operators perform Logical operations like And, Or, Xor on Boolean operands.

String Operators

A group of operators that deal with string operands. These include operators to manipulate strings or test strings for specific patterns.

Collection Operators

These are array manipulation and comparison operators. These operators encapsulate the complexity of traditional programming language constructs like loops and make the language more readable and maintainable.

Calendar Operators

These operators allow comparison and retrieval of Date-Time related attributes.

Unary Operators

As the name suggests these operators require only a single operand.

Cast Operators

These are transformation operators that allow legal conversions between different data types. Note: General rules of widening and shortening conversions apply.

SPL comes out of the box with a set of Actions. Users can extend the SPL action set by adding their own custom actions.

• CIM-SPL Specification The CIM-SPL specification