kaos.policy.util
Interface KAoSPolicyBuilder

public interface KAoSPolicyBuilder

Class building a DAML Policy representation within com.hp.hpl.jena.daml.DAMLModel

Method Summary

void	addAgentInstance(java.lang.String actorName) Add the provided Actor instance to the class being the range of the actors controlled by this policy.
void	addBaseActionType(java.lang.String actionBaseClassName) Add the base Action class to be controlled by this policy.
void	addBaseActionTypeComplement(java.lang.String actionBaseClassName) Add the complement of the base Action class to be controlled by this policy.
void	addTargetInstance(java.lang.String targetRoleName, java.lang.String targetName) Add the provided Target instance to the class being the range of the tarets of this policy for the provided role.
void	copyActorFromOtherPolicy(KAoSPolicyBuilder sourcePolicy) Copies the actor data to the current policy from the provided source policy
void	copyTargetFromOtherPolicy(KAoSPolicyBuilder sourcePolicy, java.lang.String targetRoleName) Copies the target data for the specified role to the current policy from the provided source policy
java.lang.String[]	getAgentInstance() Get the list of instances of the Actor class controlled by the current policy.
java.util.Vector	getBaseActionTypes() Get the superclasses of the Action controlled by the current policy.
java.lang.String	getBaseActorClass() If the current actor class is a complement, then get the name of the base actor class of which the current class is a complement; else get the name of the current actor class.
java.lang.String	getBaseTargetClass(java.lang.String targetRoleName) If the current target class is a complement, then get the name of the base target class of which the current class is a complement; else get the name of the current target class.
java.lang.String	getCurrentActorClass() Get the name of the current actor class that denotes the range of actors controlled by the this policy.
java.lang.String	getCurrentTargetClass(java.lang.String targetRoleName) Get the name of the current target class that denotes the range of targets controlled by the this policy.
java.lang.String	getHasSiteOfEnforcement() Get the site of enforcment for the current policy.
java.lang.String	getModalityType() Get the value of the modality type for the current policy.
SerializableOntModelImpl	getPolicy() Return the build policy as DAMLModel.
java.lang.String	getPolicyAsText() Return the build policy as text.
java.lang.String	getPolicyDesc() Get the value of the policy description for the current policy.
java.lang.String	getPolicyID() Get the id of the current policy.
java.lang.String	getPolicyName() Get the value of the policy name for the current policy.
int	getPriority() Get the priority for the current policy.
java.lang.String[]	getTargetInstance(java.lang.String targetRoleName) Get the instances of the Target class being the range of target for the provided role name.
java.util.Vector	getTargetRoleNames() Get the names of all targets.
java.lang.Long	getUpdateTimeStamp() Get the value of the time stamp for the current policy.
boolean	isActorComplement() Check if the range of the actor is a complement.
boolean	isActorRangeBasedOnClass() Check if a class or instances of the Actor class are based for the range of actors controlled by this policy.
boolean	isTargetComplement(java.lang.String targetRoleName) Check if the range of the target is a complement.
boolean	isTargetRangeBasedOnClass(java.lang.String targetRoleName) Check if the class for a target role is based on a class or on a list of instances.
void	makeActorComplement(java.lang.String className) Make the range of the actor complement of the current range.
void	makeTargetComplement(java.lang.String targetRoleName, java.lang.String targetName) Make the range of the target complement of the current range.
void	readFromModel(SerializableOntModelImpl dm) A method to recreate a DAMLPolicyBuilder object by reading from a DAMLModel object
void	removeActorClass() Remove the value of 'toClass' restriction on performedBy property
void	removeAgentInstance(java.lang.String actorClassName) Remove the given Actor instance from the class containing instances of the actors controlled by this policy.
void	removeBaseActionType(java.lang.String actionBaseClassName) Remove the provided Action class from the list of superclasses of the given class.
void	removeTargetClass(java.lang.String targetRoleName) Remove the value of 'toClass' restriction on the given property
void	removeTargetInstance(java.lang.String targetRoleName, java.lang.String targetName) Remove the given Target instance from the class being the range of the tarets of this policy for the provided role.
void	resetPolicyBuilding() Starts building the new policy, delete any existing state of the previously build policy.
void	setActorClass(java.lang.String actorClassName) Set the range of the actors controlled by this policy to the specified subclass of the Actor class.
void	setActorClassDifference(java.lang.String actorClassName1, java.lang.String actorClassName2) Set the range of the actors controlled by this policy to the difference of specified subclasses of the Actor class.
void	setActorClassIntersection(java.lang.String actorClassName1, java.lang.String actorClassName2) Set the range of the actors controlled by this policy to the intersection of specified subclasses of the Actor class.
void	setHasSiteOfEnforcement(java.lang.String _siteName) Set the site of enforcment for the build policy.
void	setPolicyDesc(java.lang.String desc) Set the description of the defined policy.
void	setPolicyIDAndModalityType(java.lang.String policyID, java.lang.String modalityType) Set the ID of the defined policy and its modality type.
void	setPolicyName(java.lang.String pName) Set the name of the defined policy.
void	setPriority(int priority) Set the priority for the build policy.
void	setTargetClass(java.lang.String targetRoleName, java.lang.String targetClassName) Set the range of the named performOn subpoperty of the action controlled by this policy to the specified class of the Target.
void	setTargetClassDifference(java.lang.String targetRoleName, java.lang.String targetClassName1, java.lang.String targetClassName2) Set the range of the named performOn subpoperty of the action controlled by this policy to the diference of specified subclasses of the Target class.
void	setTargetClassIntersection(java.lang.String targetRoleName, java.lang.String targetClassName1, java.lang.String targetClassName2) Set the range of the named performOn subpoperty of the action controlled by this policy to the intersection of specified subclasses of the Target.
void	showPolicy() A utility method to print the policy.

Method Detail

resetPolicyBuilding

void resetPolicyBuilding()

Starts building the new policy, delete any existing state of the previously build policy.

getPolicy

SerializableOntModelImpl getPolicy()
                                   throws PolicyBuildingNotCompleted

Return the build policy as DAMLModel.

Returns:

SerializableOntModelImpl containg the DAML policy

Throws:

PolicyBuildingNotCompleted - if the current policy is not fully specified

getPolicyAsText

java.lang.String getPolicyAsText()

Return the build policy as text.

Returns:

string containg the DAML policy

Throws:

PolicyBuildingNotCompleted - if the current policy is not fully specified

getUpdateTimeStamp

java.lang.Long getUpdateTimeStamp()
                                  throws ValueNotSet

Get the value of the time stamp for the current policy.

Returns:

the value of the time stamp

Throws:

ValueNotSet - if value of the time stamp is not known

setPolicyIDAndModalityType

void setPolicyIDAndModalityType(java.lang.String policyID,
                                java.lang.String modalityType)
                                throws SpecifiedModalityTypeNotExists

Set the ID of the defined policy and its modality type. There is no method to change the name and the modality type of the policy; in this case a new policy should be build.

Parameters:

policyName - the name of the policy

modalityType - the name (url) of the class representing the modality type of policy, one of: PosAuthorizationPolicy NegAuthorizationPolicy PosObligationPolicy NegObligationPolicy

Throws:

SpecifiedModalityTypeNotExists - if the modality type does not exist

See Also:

kaos.ontology.PolicyConcepts

getPolicyID

java.lang.String getPolicyID()
                             throws ValueNotSet

Get the id of the current policy.

Returns:

the id of the policy

Throws:

ValueNotSet - if value of the policy ID is not known

getModalityType

java.lang.String getModalityType()
                                 throws ValueNotSet

Get the value of the modality type for the current policy.

Returns:

the name of the modality type

Throws:

ValueNotSet - if value of the modalitytype is not known

setPolicyName

void setPolicyName(java.lang.String pName)

Set the name of the defined policy. If the name is already set, it will be replaced by the given name.

Parameters:

pName - the name of the policy

getPolicyName

java.lang.String getPolicyName()
                               throws ValueNotSet

Get the value of the policy name for the current policy.

Returns:

the name of the policy

Throws:

ValueNotSet - if value of the modalitytype is not known

setPolicyDesc

void setPolicyDesc(java.lang.String desc)

Set the description of the defined policy. If the desc is already set, it will be replaced by the given desc.

Parameters:

desc - description of the policy

getPolicyDesc

java.lang.String getPolicyDesc()
                               throws ValueNotSet

Get the value of the policy description for the current policy.

Returns:

the description of the policy

Throws:

ValueNotSet - if value of the modalitytype is not known

addBaseActionType

void addBaseActionType(java.lang.String actionBaseClassName)
                       throws DisjointClassWithAlreadyAdded,
                              PolicyNameNotSet

Add the base Action class to be controlled by this policy. As a result a new action class will be created, and will be set as a subclass of the given class. If this is the first call to this method a new action class is created. If this is a subsequent call, the given class will be added to the list of superclasses of the already created action class.

Parameters:

actionBaseClassName - the name of the action superclass

Throws:

PolicyNameNotSet - if the policy name has not been set before

DisjointClassWithAlreadyAdded - if the provided Action class is disjoint with the classes already added

addBaseActionTypeComplement

void addBaseActionTypeComplement(java.lang.String actionBaseClassName)
                                 throws DisjointClassWithAlreadyAdded,
                                        PolicyNameNotSet

Add the complement of the base Action class to be controlled by this policy. As a result a new action class will be created, and will be set as a subclass of the given class complement. If this is the first call to this method a new action class is created. If this is a subsequent call, the given class complement will be added to the list of superclasses of the already created action class.

Parameters:

actionBaseClassName - the name of the action superclass whose complemet is to be taken

Throws:

PolicyNameNotSet - if the policy name has not been set before

DisjointClassWithAlreadyAdded - if the provided Action class is disjoint with the classes already added

removeBaseActionType

void removeBaseActionType(java.lang.String actionBaseClassName)
                          throws ClassNotSuperClass

Remove the provided Action class from the list of superclasses of the given class.

Parameters:

actionBaseClassName - the name of the Action class

Throws:

ClassNotSuperClass - if the class was not previously added

getBaseActionTypes

java.util.Vector getBaseActionTypes()
                                    throws ValueNotSet

Get the superclasses of the Action controlled by the current policy.

Returns:

the array containg names of the superclasses

Throws:

ValueNotSet - if Action superclasses are not known

isActorRangeBasedOnClass

boolean isActorRangeBasedOnClass()
                                 throws ValueNotSet

Check if a class or instances of the Actor class are based for the range of actors controlled by this policy.

Returns:

true if based on a class, false if based on instances

Throws:

ValueNotSet - if the range is not set

setActorClass

void setActorClass(java.lang.String actorClassName)
                   throws ValueNotSet,
                          PolicyNameNotSet

Set the range of the actors controlled by this policy to the specified subclass of the Actor class. If the class is already set the function will return without doing anything.

Parameters:

actorClassName - the name of the Actor subclass

Throws:

PolicyNameNotSet - if the policy name has not been set before

RangeIsBasedOnInstances - if the actor range was already initiatied with instances of actors

ValueNotSet

setActorClassIntersection

void setActorClassIntersection(java.lang.String actorClassName1,
                               java.lang.String actorClassName2)
                               throws ValueNotSet,
                                      PolicyNameNotSet

Set the range of the actors controlled by this policy to the intersection of specified subclasses of the Actor class.

Parameters:

actorClassName1 - the name of the Actor subclass

actorClassName2 - the name of the Actor subclass

Throws:

PolicyNameNotSet - if the policy name has not been set before

ValueNotSet

setActorClassDifference

void setActorClassDifference(java.lang.String actorClassName1,
                             java.lang.String actorClassName2)
                             throws ValueNotSet,
                                    PolicyNameNotSet

Set the range of the actors controlled by this policy to the difference of specified subclasses of the Actor class. This is implemented as an intersection of actorClassName1 and complementof actorClassName2.

Parameters:

actorClassName1 - the name of the Actor subclass

actorClassName2 - the name of the Actor subclass

Throws:

PolicyNameNotSet - if the policy name has not been set before

ValueNotSet

removeActorClass

void removeActorClass()
                      throws ValueNotSet

Remove the value of 'toClass' restriction on performedBy property

Throws:

ValueNotSet - if the restriciton, the property or the 'toClass' value is null

getBaseActorClass

java.lang.String getBaseActorClass()
                                   throws ValueNotSet,
                                          RangeIsBasedOnInstances

If the current actor class is a complement, then get the name of the base actor class of which the current class is a complement; else get the name of the current actor class.

Returns:

the name of the base Actor class

Throws:

ValueNotSet - if current Actor class is not a complement

RangeIsBasedOnInstances - if the restriction is based on instances

getCurrentActorClass

java.lang.String getCurrentActorClass()
                                      throws ValueNotSet

Get the name of the current actor class that denotes the range of actors controlled by the this policy.

Returns:

the name of the current Actor class

Throws:

ValueNotSet - if current Actor class is instance based

addAgentInstance

void addAgentInstance(java.lang.String actorName)
                      throws RangeIsBasedOnAClass,
                             ValueNotSet,
                             PolicyNameNotSet

Add the provided Actor instance to the class being the range of the actors controlled by this policy. As a result a new instance of the Actor class will be created with the given name. If this is a first call to this method a new 'container' class is created, and the instance added to it. If this is a subsequent call the instance will be added to the list of actor instances of the already created class.

Parameters:

actorClassName - the name of the Actor instance

Throws:

PolicyNameNotSet - if the policy name has not been set before

RangeIsBasedOnAClass - if the actor range was already set to class

ValueNotSet

removeAgentInstance

void removeAgentInstance(java.lang.String actorClassName)
                         throws RangeIsBasedOnAClass,
                                InstanceNotInThisRange

Remove the given Actor instance from the class containing instances of the actors controlled by this policy. If as the result the class becomes empty it is removed and the role range is not set.

Parameters:

actorClassName - the name of the Actor instance

Throws:

InstanceNotInThisRange - if the instance was not previously added

RangeIsBasedOnAClass - if the actor range was already set to class

copyActorFromOtherPolicy

void copyActorFromOtherPolicy(KAoSPolicyBuilder sourcePolicy)

Copies the actor data to the current policy from the provided source policy

Parameters:

sourcePolicy - KAoSPolicyBuilder containing the source policy

getAgentInstance

java.lang.String[] getAgentInstance()
                                    throws ValueNotSet,
                                           RangeIsBasedOnAClass

Get the list of instances of the Actor class controlled by the current policy.

Returns:

the array containg names of the superclasses

Throws:

ValueNotSet - if Actor instances are not known

RangeIsBasedOnAClass

makeActorComplement

void makeActorComplement(java.lang.String className)
                         throws AlreadyComplement

Make the range of the actor complement of the current range.

Throws:

AlreadyComplement - if property range was already made complement

isActorComplement

boolean isActorComplement()
                          throws AlreadyComplement

Check if the range of the actor is a complement.

Returns:

true if complement, false if not

Throws:

AlreadyComplement - if property range was already made complement

isTargetRangeBasedOnClass

boolean isTargetRangeBasedOnClass(java.lang.String targetRoleName)
                                  throws ValueNotSet

Check if the class for a target role is based on a class or on a list of instances.

Parameters:

targetRoleName - the name of the role

Returns:

true if based on a class, false if based on instances

Throws:

ValueNotSet - if the range is not set

setTargetClass

void setTargetClass(java.lang.String targetRoleName,
                    java.lang.String targetClassName)
                    throws ActionTypeNotSet

Set the range of the named performOn subpoperty of the action controlled by this policy to the specified class of the Target. If the class is already set the function returns without doing anything.

Parameters:

targetRoleName - the name of the role

targetClassName - the name of the class

Throws:

ActionTypeNotSet - if the action name has not been set before

RangeIsBasedOnInstances - if the given target range was already initiatied with instances of target

setTargetClassIntersection

void setTargetClassIntersection(java.lang.String targetRoleName,
                                java.lang.String targetClassName1,
                                java.lang.String targetClassName2)
                                throws ActionTypeNotSet,
                                       ValueNotSet

Set the range of the named performOn subpoperty of the action controlled by this policy to the intersection of specified subclasses of the Target. If the class is already set the function returns without doing anything.

Parameters:

targetRoleName - the name of the role

targetClassName1 - the name of the Target subclass

targetClassName1 - the name of the Target subclass

Throws:

ActionTypeNotSet - if the action name has not been set before

ValueNotSet

setTargetClassDifference

void setTargetClassDifference(java.lang.String targetRoleName,
                              java.lang.String targetClassName1,
                              java.lang.String targetClassName2)
                              throws ActionTypeNotSet,
                                     ValueNotSet,
                                     PolicyNameNotSet

Set the range of the named performOn subpoperty of the action controlled by this policy to the diference of specified subclasses of the Target class. This is implemented as an intersection of targetClassName1 and complementof targetClassName2. If the class is already set the function returns without doing anything.

Parameters:

targetRoleName - the name of the role

targetClassName1 - the name of the Target subclass

targetClassName1 - the name of the Target subclass

Throws:

ActionTypeNotSet - if the action name has not been set before

ValueNotSet

PolicyNameNotSet

removeTargetClass

void removeTargetClass(java.lang.String targetRoleName)
                       throws ValueNotSet

Remove the value of 'toClass' restriction on the given property

Parameters:

targetRoleName - the name of the property.

Throws:

ValueNotSet - if the restriciton, the property or the 'toClass' value is null

getBaseTargetClass

java.lang.String getBaseTargetClass(java.lang.String targetRoleName)
                                    throws ValueNotSet,
                                           RangeIsBasedOnInstances

If the current target class is a complement, then get the name of the base target class of which the current class is a complement; else get the name of the current target class.

Parameters:

targetRoleName - the name of the role

Returns:

the name of the base target class

Throws:

ValueNotSet - if current target class is not a complement

RangeIsBasedOnInstances - if the restriction is based on instances

getCurrentTargetClass

java.lang.String getCurrentTargetClass(java.lang.String targetRoleName)
                                       throws ValueNotSet

Get the name of the current target class that denotes the range of targets controlled by the this policy.

Parameters:

targetRoleName - the name of the role

Returns:

the name of the current target class

Throws:

ValueNotSet - if current target class is null

addTargetInstance

void addTargetInstance(java.lang.String targetRoleName,
                       java.lang.String targetName)
                       throws RangeIsBasedOnAClass,
                              ActionTypeNotSet

Add the provided Target instance to the class being the range of the tarets of this policy for the provided role. If this is the first call, a new class will be created and the instance added to it. If it is a subsequent call, the instance will be added to the already created class.

Parameters:

targetRoleName - the name of the role

targetName - the name of the target instance to define a range ot possible values for this role

Throws:

ActionTypeNotSet - if the action name has not been set before

RangeIsBasedOnAClass - if the target range was already set to class

removeTargetInstance

void removeTargetInstance(java.lang.String targetRoleName,
                          java.lang.String targetName)
                          throws RangeIsBasedOnAClass,
                                 InstanceNotInThisRange

Remove the given Target instance from the class being the range of the tarets of this policy for the provided role. If as the result the class became empty it is removed and the role range is not set.

Parameters:

targetRoleName - the name of the role

targetName - the name of the target instance to define a range ot possible values for this role

Throws:

InstanceNotInThisRange - if the instance was not previously added

RangeIsBasedOnAClass - if the target range was already set to class

copyTargetFromOtherPolicy

void copyTargetFromOtherPolicy(KAoSPolicyBuilder sourcePolicy,
                               java.lang.String targetRoleName)

Copies the target data for the specified role to the current policy from the provided source policy

Parameters:

sourcePolicy - KAoSPolicyBuilder containing the source policy

targetRoleName - the name of the role

getTargetInstance

java.lang.String[] getTargetInstance(java.lang.String targetRoleName)
                                     throws ValueNotSet

Get the instances of the Target class being the range of target for the provided role name.

Parameters:

targetRoleName - the name of the role

Returns:

the array containg names of the Target instances

Throws:

ValueNotSet - if Target instances are not known

makeTargetComplement

void makeTargetComplement(java.lang.String targetRoleName,
                          java.lang.String targetName)
                          throws AlreadyComplement

Make the range of the target complement of the current range.

Parameters:

targetRoleName - the name of the role

targetName - the name of the target class that will be subclassed

Throws:

AlreadyComplement - if property range was already made complement

isTargetComplement

boolean isTargetComplement(java.lang.String targetRoleName)
                           throws AlreadyComplement

Check if the range of the target is a complement.

Parameters:

targetRoleName - the name of the target role

Returns:

true if complement, false if not

Throws:

AlreadyComplement - if property range was already made complement

getTargetRoleNames

java.util.Vector getTargetRoleNames()

Get the names of all targets.

setPriority

void setPriority(int priority)
                 throws PriorityNotValid,
                        PolicyNameNotSet

Set the priority for the build policy. If the priority is already set it will replace its value with the provided value.

Parameters:

_priority - the value of the priority

Throws:

PolicyNameNotSet - if the name of the policy was not set yet; the construction of the policy was not really started

PriorityNotValid - if value is not higher than zero

getPriority

int getPriority()
                throws ValueNotSet

Get the priority for the current policy.

Returns:

the value of the priority

Throws:

ValueNotSet - if value of the priority is not known

setHasSiteOfEnforcement

void setHasSiteOfEnforcement(java.lang.String _siteName)
                             throws PolicyNameNotSet,
                                    SiteOfEnforcementTypeNotExists

Set the site of enforcment for the build policy. If the site of enforcment is already set it will replace its value with the provided value.

Parameters:

_siteId - the name (url) of the class representing the site of policy enforcment, currently one of: ActorSite TargetSite AnySite

Throws:

PolicyNameNotSet - if the name of the policy was not set yet; the construction of the policy was not really started

SpecifiedSiteOfEnforcementTypeNotExists - if the value of the site of enforcement does not exist

SiteOfEnforcementTypeNotExists

See Also:

kaos.ontology.PolicyConcepts

getHasSiteOfEnforcement

java.lang.String getHasSiteOfEnforcement()
                                         throws ValueNotSet

Get the site of enforcment for the current policy.

Returns:

the name of the site of enformcment

Throws:

ValueNotSet - if value of the site of enforcment is not known

showPolicy

void showPolicy()

A utility method to print the policy.

readFromModel

void readFromModel(SerializableOntModelImpl dm)

A method to recreate a DAMLPolicyBuilder object by reading from a DAMLModel object

Parameters:

dm - the model from which to read