ABSTRACT

The VIP application tests properties to decide, if a session is allowed to use a feature or not. Each property is a switch for just one feature. When a program should decide something depending on more than one property, a new property should be defined which will be set if any of the other properties is set.

Properties can always be tested with a simple boolean test. I.e. they have always a true value if present. The actual value may depend on the property.

Properties are not granted to users directly, but are collected in roles, which are granted to users. The session of a user then gets all the properties of his roles as a set. The value of a property granted by a role is always 1.

Properties may be calculated. They are set for a session, when other properties are set or when it has access to resources. Calculated only properties are marked with a flag.

A property has the following attributes:

Name
The name is the property's identification conforming to Perl naming rules: it is a 2 to 60 character name consisting of plain ASCII letters, digits and underlines. The first character is a letter or underline.

Description
Is a ISO-8859-1 string of 2 to 255 characters.

Calculated Only
Is a boolean flag. Any true value will prevent the CGI script, which lets administrators assign properties to rules, to select this property.

Note, that calculated_only=>false just allows administrators to assign the property to roles. It does not prevent that the property can be assigned automatically to a session, depending on other properties or access to resources.


DESCRIPTION

Object Constructors

$property = Properties->find( -name=>property_name );
Searchs the database and returns the property identified by property_name. If the property is not found, an empty property is returned.

$property = Properties->create( );
Returns an empty property object. It is generated only in memory, not on the database. You should set its values by calling the update method, which will write the property to the database.

$aref = Properties->get_object_list( -included_in_role=>roles_id );
$aref = Properties->get_object_list( -calculated_only=>boolean );
$aref = Properties->get_object_list( -all=>1 );
Returns a reference to an array of property objects. Called with argument -all=>1, it returns all properties. Called with argument -included_in_role=>roles_id it returns only the properties which are assigned to the role identified by roles_id. Called with argument -calculated_only=>false it returns only properties which may be assigned to roles; -calculated_only=>true returns properties which should not be assigned to roles.

$aref = Properties->get_id_list( ... )
Returns a reference to an array of property names, not blessed objects. Arguments and the function are the same as Properties->get_object_list( ... ) method.

Accessor Methods

$property->name( );
Returns the identification, which is a name which conforms to Perl naming rules.

$property->description( );
ISO-8859-1 string, not empty.

$property->calculated_only( );
Boolean value.

Object Modification Methods

($field, $errmsg) = $property->update( ... )
The update method checks the syntax of the modified fields and returns a two element list in case of an error: the name of the field and an error message. If the syntax checks pass, the state of the property is changed: in memory and on the data base and update will return an undef value.

Arguments:

-name=>new_name
-desciption=>new_description
-calculated_only=>boolean
$property->delete( );
Deletes the property from the database and in memory.


SEE ALSO

Access to VIP database through VipDB.pm.

An initial set of properties is assigned to new sessions in method _session_init in Class Vip.pm. More properties are assigned to sessions in Login.pm.

Properties are stored in CGIsession.pm session storage with a name consisting of PROPERTY_ followed by the property name. I.e. set property 'debug':

  $cgi->session_data(PROPERTY_debug => 1); # enable debug

Programs should check properties of a session (or job) with class Validation.pm:

  use Validation;
  $validation = Validation->new( ... ); # see description of class Validation
  ...
  if ($validation->has_property('is_vegetarian')) {
      # this code is for surfers with the property 'is_vegetarian' only.
  }

Properties which are assigned to a session depending on the surfers access rights to resources may be set in the same form in other places of the application.

Roles.pm contains method set_properties which will assign properties to a role. Roles have a granters_property, which must be present in a session to allow the surfer to grant the role to users. To generate granters_property popup menues for role editors, Role.pm contains the methods granters and granters_labels, which contain an array of property names and a hash with labels for this properties.


COPYRIGHT

Copyright 2004-2013 Thedi gerber@id.ethz.ch