de.fuberlin.wiwiss.wiqa
Class Policy

java.lang.Object
  de.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:

• A name and optional description
• A namespace mapping
• Zero or one explanation template outside of any graph pattern
• Zero or more graph patterns with an explicit or anonymous graph name; they may contain zero or more triple patterns, zero or more filters, and zero or one explanation templates each
• Zero or more filters outside of any graph pattern
• Zero or more construct templates for graph explanations
• Zero or more Extensions
• An optional graph explanation template

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