			     *SPCL TUTORIAL*



I. INTRODUCTION

SPCL is a domain-independent language for specifying policy requirements.  Generally speaking, a policy is a set of principles that defines what is permissible in a specific domain.  SPCL allows you to define a domain, the agents that exist in the domain, the objects upon which the agents may act, and the actions that apply to said objects.  This tutorial will introduce you to the basic elements of SPCL and help you write and test your first SPCL program. 



II. A SIMPLE SPCL EXAMPLE

Let's begin by looking at a simple SPCL program.  Your first helping of SPCL defines a policy for the four members of the Smith family -- parents George and Glenda, and children Timmy and Sarah -- who live together in an ulra-modern computerized home.  

George is on a diet so he should only be able to access the refrigerator during certain hours.  Neither of the children should watch late night televsion, and Timmy is not allowed to watch the Playboy channel.  Sarah has been known to sneak out of the house after her eleven o'clock curfew.  Glenda is perfect.  She's the policy administrator and she would like to know if Sarah breaks her curfew.  The following SPCL file, House_Rules.spcl, will keep the family members' vices in check.  If you don't understand the following code right away, don't worry:



zone smith_house;

policy HouseRules {

       default{
		DENY *;
       }

       group Parents {
		ALLOW * ON *;     
       }


       group Children {
		ALLOW "open" ON refrigerator;         
		ALLOW "open" ON front_door;         
		// 'system.time' returns the current time    
		ALLOW "watch" ON tv WHEN ( system.time <= "9:00 pm");
       }

       principal Mom {
		 alias Glenda, supermom, ADMIN;
		 groups Parents;
       }

       principal Dad {
		 alias George;
		 groups Parents;
		 DENY "open" ON refrigerator WHEN ( system.time >= "8:00 pm");	
       }	

       principal Son {
		 alias Timmy;
		 groups Children;
		 DENY "watch" ON tv WHEN ( tv.channel != "Playboy");	
       }	

       principal Daughter {
		 alias Sarah;
		 groups Children;
		 DENY "open" ON front_door WHEN ( system.time >= "11:00 pm")
		      AND {NOTIFY ADMIN};	
       }	

       object front_door {
	      actions {
		      action unlock_door = "unlock";
		      // tell mom if somebody tries to unlock the door
		      open_door.meta_action = NOTIFY Mom;
	      }
       }

       object refrigerator {
	      actions {
		      action open_frige = "open";	
		      open_frige.meta_action = NOTIFY Mom;
	      }	      
       }

       object tv {
	      string channel = "Playboy";
       	      actions {
		      action watch_tv = "watch";
	      }
       }
}

  


III. ELEMENTS OF THE SPCL LANGUAGE

In order to understand the above program, you must first familiarize yourself with some of the SPCL basics.  The following are fundamental elements of SPCL:  
Zone
A zone the area to which one or many policies apply.  A zone is generally under one administrative domain.  In the above program, the zone is the Smith household, called "smith_house".  The syntax for declaring a zone is: "zone" ID ';', where "ID" is the name of the zone.

Policy
A policy is a policy definition as defined in an SPCL program.  A policy definition may contain the elements described below.  A policy has the following form: "policy" ID '{' default_definition ' (group_definition)* (principal_definition)* (object_definition)* '}'.  

Principal
A principal is an object in the system that acts autonomously.  Principals attempt to act upon objects.  'Mom', 'Dad', 'Son' and 'Daughter' are principals in the above program.  A principal declaration looks like this:  "principal" ID '{' ("email" '=' string ';' )? ("member" '=' gID ( ',' gID )* ';' )? '}'.

Group
A group is a collection of pricipals.  The above program defined two groups -- 'Parents' and 'Students'.

Object
An object is something that can be acted upon by principals.  House_Rules.spcl defines three objects -- 'tv', 'front_door', and 'refrigerator'.  The declaration of an object has the following form: "object" ID '{' ("url" '=' string ';' )? ("property" '=' gID ( '=' value )? ';' )* ("action" '=' string ( ',' string)* ';' )?.        

Action
An action is a definition of what a principal may do to an object.  A principal must have permission to perform an action on an object.  For example, the principals in the above program may 'open' the refrigerator object.

Condition
A condition is a expression that must be satisfied in order for a principle to act upon an object.  In the above program, for example, the 'Son' principal cannot perform the 'watch' action on the 'tv' object if the tv's channel is Playboy.    

Meta-action
A meta action is the action a system takes in response to a principal's request to perform an action on an object.  In the above example, Mom is notified if her daughter opens the front door after 11 pm.  

Rule
A rule is a statement that defines, for a given principal or group, what actions may be performed on what objects.  In the previous program, rules are the statements that begin with 'ALLOW' and 'DENY'.  SPCL rules have the following format: ("ALLOW" | "DENY" ) (action list) "ON" object ';'.  An action list declaration follows the form action (',' action)*;
 
Comments 
Comments are sequences of characters included in SPCL code that describe the code itself.  Comments are ignored by the SPCL compiler.  Comments are designated in one of two ways; either by lines that begin with '//' and end with a newline character or by a block of text that begins with '/*' and ends with '*/'.
 
Kleene Star (*)
The '*' is used in SPCL as you would use it in Perl.  The command 'DENY *;' means deny everything.  

That should be enough to get you started.  For more detailed explaination of the SPCL syntax, consult the SPCL language reference manual.  




IV. QUICK ANALYSIS

Let's run through HouseRules.spcl.  After declaring the zone and policy name, the program sets the default values.  SPCL contains the notion of precedence for rules.  Essentially, rules with a the highest precedence overide rules with lower precence.  Rules defined in the 'Default' block of code have the lowest precedence, followed by group rules, followed by principal rules.  For the default case, the program denies evryone permission to do anything.

After the default case, the program declares two groups -- 'parents' and 'children'.  Let's look at one of them:

       group Children {
		ALLOW "open" ON refrigerator;         
		ALLOW "unlock" ON front_door;         
		ALLOW "watch" ON tv WHEN ( system.time <= "9:00 pm");
       }           

The above block of code overrides the default case.  The children are now allowed to open the refrigerator, unlock the front door, and watch tv if it is before 9 pm.  The default case makes certain that the children cannot watch tv after 9 pm.

The program defines four principals -- Mom, Dad, Son and Daughter.  Let's take a closer look at one of those definitions:

       principal Son {
		 alias Timmy;
		 groups Children;
		 DENY "watch" ON tv WHEN ( tv.channel != "Playboy");	
       }	  

Since a rule defined within a principle code-block has higher-precedence than a rule defined within a group code-block, the 'Son' principle cannot watch the Playboy channel even if it is before 9 pm.  

The variable channel is defined in the 'tv' object declaration:

       object tv {
	      string channel = "Playboy";
       	      actions {
		      action watch_tv = "watch";
	      }
       }

Note that the channel is set to 'Playboy'.  Objects in SPCL have a state.  When a request is made about an object, the Policy Engine uses the object's state to determine whether it should accept or deny the request.  The 'channel' variable is an aspect of the 'tv' object's state.  Assume that some interface exists between the tv object and a tv.  That is to say, the 'channel' variable would changes when the channel changes on the actual tv to which object refers.  




V. INSTALLATION

*********************************
****INCLUDE DOWNLOAD LOCATION****
*********************************



Now that you have a basic idea of how to write an SPCL program, it is time to install SPCL on your system.  First, make sure that you have a Java Development Kit (JDK version v1.4.x is best) installed.  If you do not have a JDK, you may download it from the Sun website (http://java.sun.com).

Next, download either 'spcl-0.x.tar.gz' or 'spcl-0.x.zip'.  Now copy the file into the directory from which you would like to work.  You must now decompress the file.  NOTE:  The '$' is the command-line prompt so do not include it in your  commands.  

If you downloaded 'spcl-0.x.tar.gz' type: 
$ gzip -d spcl-0.x.tar.gz 

Then type type:
$ tar -xvf spcl-0.x.tar  

If you downloaded 'spcl-0.x.zip', type:
$ unzip  spcl-0.x.zip
      
Now the file should be decompressed.  Type 'ls' to make sure.  In the bin/ directory, there is a makefile and some shell scripts.  You must to edit both the JAVA_HOME and the SPCL_HOME variables at the top and set them to the appropriate directories. For example, if you installed to /home/professor/opt/scpl then  SCPL_HOME=/home/professor/opt/spcl (NOTE: there is no trailing '/'). In addition, if Java is in /usr/java/sdk/jdk1.4.1 then JAVA_HOME=/usr/java/sdk/jdk1.4.1 (NOTE: again, no trailing '/').  
   
Currently, there are two different makefiles but they will be merged.  The Makefile will set up your CLASSPATH properly (to include SPCL_HOME/classes/).




VI. RUNNING A PROGRAM

Now that you have SPCL installed on your system, try running a program.  If you're feeling lucky, try writing your own program.  Otherwise, using a text editor of your choice either cut-and-paste or recopy the above program, HouseRules.spcl, and save it as 'HouseRules.spcl'.
 
The SPCL compiler transforms a given policy into java code, which it then compiled into appropriate the java `.class' files.  The policy can then be loaded into the SPCL policy engine, the mechanism which handles queries regarding the policy.  To compile your policy program, execute '$SPCL_HOME/bin/polc <policy>.spcl' at the command-line, while in the directory from which you have decided to run SPCL.  For example, you might type:
$ /home/professor/bin/polc HouseRules.spcl

If your program is correct, this will invoke the SPCL compiler to produce <policy>.java.  Then it will invoke the java compiler to produce <policy>.class and to place <policy>.class in the directory  'SPCL_HOME/conf/policy'.  Now, you can invoke the PolicyEngine on this policy by typing:
$ SPCL_HOME/bin/pole <policy>

Notice that there is no file extension.  This will run the policyengine and load in the given policy class.  You can stop the policy engine by typing:
$ SPCL_HOME/bin/pole -stop

Otherwise, you can use the client to connect to the policy engine and query it:
$  SPCL_HOME/bin/pec

Now, try querying your policy via the policy engine.  Start by typing:
$ list zones

If you used the above example, this should return the value 'smith_house'.  Next, try typing: 
$ list principals

This should return a list of all the principals you declared in your policy program.  You may also use the 'list' command to display groups, objects, active rules, suspended rules, and policies.

Now you're ready to make requests.  In SPCL, a request applies to a specific object.  A request has the following form:
$ CAN [principal] DO [action] with ([condition])?

To change the object to which your request applies, type:
$ switch object [object]

Of course, the principal must be something you have declared and the action and condition must apply to the object about which you are making the request.  You may leave the condition empty (ie just use empty parenthesis) if you wish to make a more general query.  If you used the SPCL program from the beginning of this tutorial, try the following commands.  First, change the object in question to tv, if you have not done so already:
$ switch object tv

Then check if timmy can watch television:
$ CAN timmy DO watch with ()?

Note that even if the system time is earlier than 9 pm -- the children group to which timmy belongs cannot watch tv after 9 -- the policy engine will deny the request.  Why?  The channel variable in the 'tv' object declaration is set to 'Playboy'.  A rule in the 'Son' (alias timmy) principal declaration specifically forbids the principal from watching the Playboy channel.  Continue making requests until you feel comfortable with the syntax.    

   


VII. WRITING AN ADVANCED PROGRAM

Congratulations on having run your first SPCL program.  Now you're ready to write a more advanced program.  Perhaps you could try  adding neighbors and relatives and the police to the above program.  First try adding new principals and overlapping groups to your program.    This will help you get familiar with SPCL's precedence rules.  

Next, try adding conditional side-effects to your program to rules in your program.  Consult the Language Reference Manual for proper syntax and rules.  Conditional side-effects are triggered whenever their rule is being applied to a request.  Condition side-effects may either trigger meta-actions (ie 'log' an event or 'notify' the policy administrator) or update a rule.  

Now, try experiment with rule updates.  Rule updates have the highest precedence, overriding rules declared in the principal blocks to which they apply.  




VIII. CONCLUSION

************************
**TAKE OUT BAD JOKE*****
************************
Hopefully, you found this tutorial to be helpful.  You should now be an expert in SPCL programming.  Consult the Language Reference Manual and the SPCL Whitepaper for a more detailed exploration of the topics discussed above.  Or purchase the O'Reilly SPCL book with the half-platypus half-monkey on the cover.  Have fun!































