de.fuberlin.wiwiss.wiqa
Class Policy

java.lang.Object
  extended byde.fuberlin.wiwiss.wiqa.Policy

public class Policy
extends Object

A WIQA policy defines rules for accepting or rejecting RDF statements. Policies are usually authored in a SPARQL-like syntax and parsed using the PolicyParser. A policy consists of:

TODO: There are also count constraints.

A policy forms an implicit SPARQL query. A statement is accepteded if it matches the query. The policy also provides explanations templates which can generate an explanation stating why a particular statement was accepteded (but not why a statement was rejected).

Policy instances are created mainly through the PolicyParser.

Version:
$Id: Policy.java,v 1.7 2006/06/12 16:47:27 cyganiak Exp $
Author:
Richard Cyganiak (richard@cyganiak.de)

Field Summary
static Policy ACCEPT_EVERYTHING
          A pre-defined policy that accepts all statements.
 
Constructor Summary
Policy()
          Creates a new policy without name and description.
Policy(String name, String description)
          Creates a new policy.
 
Method Summary
 void addCountConstraint(CountConstraint countConstraint)
          Adds a count constraint to the policy.
 void addExtension(ElementExtension extension)
          Adds an Extension call.
 void addGraphPatternElement(ElementNamedGraph element, ExplanationTemplate explanationTemplate)
          Adds a graph pattern and its explanation template to the policy.
 void addRootFilter(Constraint constraint)
          Adds a filter Constraint to the root level.
 List countConstraints()
           
 String description()
           
 ExplanationTemplate explanationTemplate(ElementNamedGraph element)
           
 List extensions()
          In a WIQA policy, Extensions may be provided inside any graph pattern or on the query pattern level, but in either case, they are executed after all graph patterns and filter constraints have been processed.
 Template graphExplanationTemplate()
           
 List graphPatternElements()
          Returns ARQ parse tree elements for each of the policy's graph patterns.
 String name()
           
 PrefixMapping prefixes()
           
 ExplanationTemplate rootExplanationTemplate()
           
 List rootFilters()
           
 GraphPatternTreeNode rootGraphPattern()
          The graph patterns of a policy are arranged into a tree shape based on common variables.
 void setDescription(String description)
          Changes the policy's description.
 void setGraphExplanationTemplate(Template template)
           
 void setName(String name)
          Changes the policy's name.
 void setRootExplanationTemplate(ExplanationTemplate tpl)
          Sets the root-level explanation template.
 Query toARQ()
          A policy forms an implicit ARQ query.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ACCEPT_EVERYTHING

public static final Policy ACCEPT_EVERYTHING
A pre-defined policy that accepts all statements.

Constructor Detail

Policy

public Policy()
Creates a new policy without name and description.


Policy

public Policy(String name,
              String description)
Creates a new policy.

Parameters:
name - The name of the policy
description - The description of the policy
Method Detail

name

public String name()
Returns:
The policy's name

setName

public void setName(String name)
Changes the policy's name.


description

public String description()
Returns:
The policy's description

setDescription

public void setDescription(String description)
Changes the policy's description.


graphPatternElements

public List graphPatternElements()
Returns ARQ parse tree elements for each of the policy's graph patterns.

Returns:
A list of ElementNamedGraphs

explanationTemplate

public ExplanationTemplate explanationTemplate(ElementNamedGraph element)
Parameters:
element - An ARQ parse tree element representing one of the policy's graph patterns
Returns:
The explanation template for that pattern, or null if the graph pattern doesn't have one

addGraphPatternElement

public void addGraphPatternElement(ElementNamedGraph element,
                                   ExplanationTemplate explanationTemplate)
Adds a graph pattern and its explanation template to the policy.

Parameters:
element - The ARQ parse tree element
explanationTemplate - The explanation template

rootExplanationTemplate

public ExplanationTemplate rootExplanationTemplate()
Returns:
The root-level explanation template, or null if none is provided

setRootExplanationTemplate

public void setRootExplanationTemplate(ExplanationTemplate tpl)
Sets the root-level explanation template.

Parameters:
tpl -

rootFilters

public List rootFilters()
Returns:
Any filter Constraints provided for the root of the query pattern, outside of the graph patterns

addRootFilter

public void addRootFilter(Constraint constraint)
Adds a filter Constraint to the root level. Filter constraints can be located inside one of the graph patterns (then they become part of the pattern's ARQ parse tree), or outside of any graph pattern (then they are added to the query with this method).

Parameters:
constraint -

extensions

public List extensions()
In a WIQA policy, Extensions may be provided inside any graph pattern or on the query pattern level, but in either case, they are executed after all graph patterns and filter constraints have been processed. Their location in the policy is only used to determine their relative order.

Returns:
A list of ElementExtensions

addExtension

public void addExtension(ElementExtension extension)
Adds an Extension call. The call is represented here by an ARQ parse tree, but WIQA actually uses a different custom syntax for extensions, and the parser has to construct the ARQ style parse tree before delivering it to this method.

Parameters:
extension - The ARQ parse tree representing the extension call

addCountConstraint

public void addCountConstraint(CountConstraint countConstraint)
Adds a count constraint to the policy.

Parameters:
countConstraint - The count constraint

countConstraints

public List countConstraints()
Returns:
A list of all CountConstraints in the order they were defined in the policy

prefixes

public PrefixMapping prefixes()
Returns:
The policy's namespace prefixes

rootGraphPattern

public GraphPatternTreeNode rootGraphPattern()
The graph patterns of a policy are arranged into a tree shape based on common variables. The tree shape is not visible in the WIQA policy syntax. The tree is used to group explanation templates into a tree form, and to determine which variables form the groups in which to apply count constraints. The algorithm for building the tree is described in TreeBuilder.

Returns:
The root of the graph pattern tree
See Also:
TreeBuilder

setGraphExplanationTemplate

public void setGraphExplanationTemplate(Template template)
Parameters:
template - The graph explanation template for the policy

graphExplanationTemplate

public Template graphExplanationTemplate()
Returns:
The policy's graph explanation template, or null if it doesn't have one

toARQ

public Query toARQ()
A policy forms an implicit ARQ query. (It would be a SPARQL query if we wouldn't use Extensions. An ARQ query is a SPARQL query that can use some additional language features.)

Returns:
An ARQ representation of the policy