com.epimorphics.lda.query

Class APIQuery

java.lang.Object

com.epimorphics.lda.query.APIQuery

All Implemented Interfaces:

VarSupply, WantsMetadata

public class APIQuery
extends Object
implements VarSupply, WantsMetadata

Query abstraction that supports assembling multiple filter/order/view specifications into a set of working sparql queries.

Version:

$Revision: $

Author:

Dave Reynolds

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	APIQuery.FilterExpressions
static interface	APIQuery.QueryBasis The parameters that form the basis of an API Query.

Field Summary

Fields

Modifier and Type	Field and Description
protected Set<String>	allowedReserved
protected List<RDFQ.Triple>	basicGraphTriples List of pseudo-triples which form the basic graph pattern element of this query.
long	cacheExpiryMilliseconds
protected String	defaultLanguage
protected int	defaultPageSize
List<PendingParameterValue>	deferredFilters
protected boolean	enableETags
protected List<RenderExpression>	filterExpressions List of little infix expressions (operands must be RDFQ.Any's) which are SPARQL filters for this query.
protected String	fixedSelect
protected String	graphName
protected String	graphTemplate
protected String	itemTemplate
protected int	maxPageSize
protected Set<String>	metadataOptions
protected List<List<RDFQ.Triple>>	optionalGraphTriples
protected int	pageNumber
protected int	pageSize
static String	PREFIX_VAR
protected boolean	purging
static Variable	SELECT_VAR
protected ShortnameService	sns
protected String	sortByOrderSpecs
protected boolean	sortByOrderSpecsFrozen
protected com.hp.hpl.jena.rdf.model.Resource	subjectResource
protected TextSearchConfig	textSearchConfig
protected int	varcount
protected Map<Variable,Param.Info>	varInfo
static Pattern	varPattern Pattern for matching SPARQL query variables (including the leading '?').
protected Map<String,Variable>	varsForPropertyChains Map from property chain names (ie dotted strings) to the variable at the end of that chain.
protected ValTranslator	vt
protected StringBuffer	whereExpressions

Constructor Summary

Constructors

Constructor and Description
APIQuery(APIQuery.QueryBasis qb)
APIQuery(APIQuery other)

Method Summary

Methods

Modifier and Type	Method and Description
void	addAllowReserved(String name)
void	addFilterExpression(RenderExpression e)
void	addMetadataOptions(String[] options)
protected void	addNameProp(Param param, String literal)
void	addNumericRangeFilter(Variable v, double x, double dx)
protected void	addPropertyHasntValue(Param param)
protected Variable	addPropertyHasValue_REV(Param param)
protected void	addPropertyHasValue(Param param)
protected void	addPropertyHasValue(Param param, String val)
protected void	addRangeFilter(Param param, String val, String op)
void	addSearchTriple(String val)
APIQuery	addSubjectHasProperty(com.hp.hpl.jena.rdf.model.Resource P, Any O)
void	addTriplePatterns(List<RDFQ.Triple> triples) Update this query-generator with a bunch of basic graph triples to use.
void	addWhere(String whereClause)
boolean	allowReserved(String name) Answer true if name is a reserved name (_whatever) that is allowed to be used (and ignored).
void	appendFilterExpressions(PrefixLogger pl, StringBuilder q)
String	assembleRawCountQuery(PrefixLogger pl, Bindings b)
String	assembleRawSelectQuery(PrefixLogger pl, Bindings b)
String	assembleSelectQuery(Bindings b, com.hp.hpl.jena.shared.PrefixMapping prefixes)
String	assembleSelectQuery(com.hp.hpl.jena.shared.PrefixMapping prefixes)
protected String	bindDefinedvariables(PrefixLogger pl, String query, Bindings cc) Take the SPARQL query string query and replace any ?SPOO where SPOO is a variable bound in cc with the SPARQL representation of that variable's value.
void	clearLanguages()
String	constructBGP(PrefixLogger pl)
String	cookRawValue(String raw_val) Raw values have come in from the outside world (as arguments to URL query-part filters) and may optionally be cooked to get rid of suspect characters.
APIQuery	copy()
int	countVarsAllocated() Answer the number of variables allocated so far (used for testing).
protected com.hp.hpl.jena.query.Query	createQuery(String selectQuery)
void	deferrableAddFilter(Param param, String val)
protected APIResultSet	fetchDescriptionOfAllResources(Controls c, String select, APISpec spec, String graphName, View view, List<com.hp.hpl.jena.rdf.model.Resource> results)
List<RDFQ.Triple>	getBasicGraphTriples()
String	getDefaultLanguage() Answer the (current) default language string.
List<RenderExpression>	getFilterExpressions()
TextSearchConfig	getItemSource()
List<List<RDFQ.Triple>>	getOptionalGraphTriples()
int	getPageNumber() Answer the currently-set page number.
int	getPageSize() Answer the currently-set page size.
String	getQueryString(APISpec spec, Bindings call) Return the select query that would be run or a plain string for the resource
String	getSubject() Return the fixed subject for a subject query, null for a select query
boolean	isFixedSubject() Return true if this query is a fixed subject instead of a select
String	languagesFor(String param)
Variable	newVar() Answer a new variable not equal to any that this VarSupply has delivered before.
protected void	optionalProperty(Variable startFrom, Param param, Variable var) Generate triples to bind var to the value of the param property chain if it exists (ie all of the triples are OPTIONAL).
APIResultSet	runQuery(NoteBoard nb, Controls c, APISpec spec, Cache cache, Bindings b, View view) Run the defined query against the datasource
protected APIResultSet	runQueryWithSource(NoteBoard nb, Controls c, APISpec spec, Bindings call, String graphName, View view, Source source)
protected Couple<String,List<com.hp.hpl.jena.rdf.model.Resource>>	selectResources(Controls c, APISpec spec, Bindings b, Source source) Answer the select query (if any; otherwise, "") and list of resources obtained by running that query.
void	setDefaultLanguage(String defaults) Set the default language, discarding any existing default language.
void	setEnableETags(boolean e) Set the etags enable flag; true -> enabled.
void	setFixedSelect(String fixedSelect)
void	setGraphName(String graphName)
void	setLanguagesFor(String fullParamName, String languages)
void	setOrderBy(String orderBy) Discard any existing order expressions (a string that may appear after SPARQL's ORDER BY).
void	setPageNumber(int page) Set which page should be returned.
void	setPageSize(int pageSize) Set the page size to use when paging through results.
void	setSortBy(String orderSpecs) Discard any existing order expressions.
void	setSubject(String subj)
void	setSubjectAsItemEndpoint(String subj) Sets the query to just describe a single resource, rather than search for a list
boolean	setTotalCountRequested(boolean b) If the current total count request is null, set it to b and return true; otherwise return false (meaning "could not set").
void	setTypeConstraint(com.hp.hpl.jena.rdf.model.Resource typeConstraint)
protected void	unpackSortByOrderSpecs()
boolean	wantsMetadata(String name)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SELECT_VAR

public static final Variable SELECT_VAR

PREFIX_VAR

public static final String PREFIX_VAR

See Also:

Constant Field Values

basicGraphTriples

protected List<RDFQ.Triple> basicGraphTriples

List of pseudo-triples which form the basic graph pattern element of this query.

optionalGraphTriples

protected List<List<RDFQ.Triple>> optionalGraphTriples

filterExpressions

protected final List<RenderExpression> filterExpressions

List of little infix expressions (operands must be RDFQ.Any's) which are SPARQL filters for this query.

textSearchConfig

protected final TextSearchConfig textSearchConfig

defaultLanguage

protected String defaultLanguage

varcount

protected int varcount

pageSize

protected int pageSize

pageNumber

protected int pageNumber

subjectResource

protected com.hp.hpl.jena.rdf.model.Resource subjectResource

itemTemplate

protected String itemTemplate

fixedSelect

protected String fixedSelect

enableETags

protected boolean enableETags

sortByOrderSpecs

protected String sortByOrderSpecs

sortByOrderSpecsFrozen

protected boolean sortByOrderSpecsFrozen

graphName

protected String graphName

graphTemplate

protected String graphTemplate

purging

protected final boolean purging

varPattern

public static final Pattern varPattern

Pattern for matching SPARQL query variables (including the leading '?'). Used for finding substitution points in static query strings.

defaultPageSize

protected final int defaultPageSize

maxPageSize

protected final int maxPageSize

sns

protected final ShortnameService sns

vt

protected final ValTranslator vt

whereExpressions

protected final StringBuffer whereExpressions

varInfo

protected final Map<Variable,Param.Info> varInfo

allowedReserved

protected final Set<String> allowedReserved

metadataOptions

protected final Set<String> metadataOptions

deferredFilters

public final List<PendingParameterValue> deferredFilters

cacheExpiryMilliseconds

public final long cacheExpiryMilliseconds

varsForPropertyChains

protected final Map<String,Variable> varsForPropertyChains

Map from property chain names (ie dotted strings) to the variable at the end of that chain. Allows different instances of a property chain (in the same APIQuery) to share the variable.

Constructor Detail

APIQuery

public APIQuery(APIQuery.QueryBasis qb)

APIQuery

public APIQuery(APIQuery other)

Method Detail

getBasicGraphTriples

public List<RDFQ.Triple> getBasicGraphTriples()

getOptionalGraphTriples

public List<List<RDFQ.Triple>> getOptionalGraphTriples()

getFilterExpressions

public List<RenderExpression> getFilterExpressions()

addFilterExpression

public void addFilterExpression(RenderExpression e)

getItemSource

public TextSearchConfig getItemSource()

setTotalCountRequested

public boolean setTotalCountRequested(boolean b)

If the current total count request is null, set it to b and return true; otherwise return false (meaning "could not set").

copy

public APIQuery copy()

setGraphName

public void setGraphName(String graphName)

setEnableETags

public void setEnableETags(boolean e)

Set the etags enable flag; true -> enabled.

setPageSize

public void setPageSize(int pageSize)

Set the page size to use when paging through results. If this is not called then a default size will be used.

getPageSize

public int getPageSize()

Answer the currently-set page size.

setPageNumber

public void setPageNumber(int page)

Set which page should be returned.

getPageNumber

public int getPageNumber()

Answer the currently-set page number.

setTypeConstraint

public void setTypeConstraint(com.hp.hpl.jena.rdf.model.Resource typeConstraint)

setSubjectAsItemEndpoint

public void setSubjectAsItemEndpoint(String subj)

Sets the query to just describe a single resource, rather than search for a list

Parameters:

subj - the target resource as either a prefix_name string or as a full URI

setSubject

public void setSubject(String subj)

addAllowReserved

public void addAllowReserved(String name)

isFixedSubject

public boolean isFixedSubject()

Return true if this query is a fixed subject instead of a select

getSubject

public String getSubject()

Return the fixed subject for a subject query, null for a select query

setDefaultLanguage

public void setDefaultLanguage(String defaults)

Set the default language, discarding any existing default language.

getDefaultLanguage

public String getDefaultLanguage()

Answer the (current) default language string.

clearLanguages

public void clearLanguages()

setLanguagesFor

public void setLanguagesFor(String fullParamName,
                   String languages)

languagesFor

public String languagesFor(String param)

addMetadataOptions

public void addMetadataOptions(String[] options)

deferrableAddFilter

public void deferrableAddFilter(Param param,
                       String val)

cookRawValue

public String cookRawValue(String raw_val)

Raw values have come in from the outside world (as arguments to URL query-part filters) and may optionally be cooked to get rid of suspect characters. If cooking = true, the value is stripped of suspect characters.

addSearchTriple

public void addSearchTriple(String val)

addSubjectHasProperty

public APIQuery addSubjectHasProperty(com.hp.hpl.jena.rdf.model.Resource P,
                             Any O)

addRangeFilter

protected void addRangeFilter(Param param,
                  String val,
                  String op)

addNumericRangeFilter

public void addNumericRangeFilter(Variable v,
                         double x,
                         double dx)

addTriplePatterns

public void addTriplePatterns(List<RDFQ.Triple> triples)

Update this query-generator with a bunch of basic graph triples to use. Note: the argument is a list; the order is preserved apart from the special re-ordering rules.

addPropertyHasValue

protected void addPropertyHasValue(Param param)

addPropertyHasValue_REV

protected Variable addPropertyHasValue_REV(Param param)

addPropertyHasValue

protected void addPropertyHasValue(Param param,
                       String val)

optionalProperty

protected void optionalProperty(Variable startFrom,
                    Param param,
                    Variable var)

Generate triples to bind var to the value of the param property chain if it exists (ie all of the triples are OPTIONAL).

addPropertyHasntValue

protected void addPropertyHasntValue(Param param)

setOrderBy

public void setOrderBy(String orderBy)

Discard any existing order expressions (a string that may appear after SPARQL's ORDER BY). Add orderBy as the new order expressions.

setFixedSelect

public void setFixedSelect(String fixedSelect)

setSortBy

public void setSortBy(String orderSpecs)

Discard any existing order expressions. Decode orderSpec to produce a new order expression. orderSpec is a comma-separated list of sort fields, each optionally proceeded by - for DESC. Each field is a property chain used to bind a new variable v when is used as the ORDER BY field.

unpackSortByOrderSpecs

protected void unpackSortByOrderSpecs()

newVar

public Variable newVar()

Description copied from interface: VarSupply

Answer a new variable not equal to any that this VarSupply has delivered before.

Specified by:

newVar in interface VarSupply

countVarsAllocated

public int countVarsAllocated()

Answer the number of variables allocated so far (used for testing).

addNameProp

protected void addNameProp(Param param,
               String literal)

addWhere

public void addWhere(String whereClause)

assembleSelectQuery

public String assembleSelectQuery(Bindings b,
                         com.hp.hpl.jena.shared.PrefixMapping prefixes)

assembleSelectQuery

public String assembleSelectQuery(com.hp.hpl.jena.shared.PrefixMapping prefixes)

assembleRawSelectQuery

public String assembleRawSelectQuery(PrefixLogger pl,
                            Bindings b)

appendFilterExpressions

public void appendFilterExpressions(PrefixLogger pl,
                           StringBuilder q)

constructBGP

public String constructBGP(PrefixLogger pl)

bindDefinedvariables

protected String bindDefinedvariables(PrefixLogger pl,
                          String query,
                          Bindings cc)

Take the SPARQL query string query and replace any ?SPOO where SPOO is a variable bound in cc with the SPARQL representation of that variable's value. Note that this will include any occurrences of ?SPOO, including those inside SPARQL quotes. Fixing this probably should happen earlier, but note that bits of query are mashed together from strings in the config file, ie, without going through RDFQ.

getQueryString

public String getQueryString(APISpec spec,
                    Bindings call)

Return the select query that would be run or a plain string for the resource

runQuery

public APIResultSet runQuery(NoteBoard nb,
                    Controls c,
                    APISpec spec,
                    Cache cache,
                    Bindings b,
                    View view)

Run the defined query against the datasource

runQueryWithSource

protected APIResultSet runQueryWithSource(NoteBoard nb,
                              Controls c,
                              APISpec spec,
                              Bindings call,
                              String graphName,
                              View view,
                              Source source)

fetchDescriptionOfAllResources

protected APIResultSet fetchDescriptionOfAllResources(Controls c,
                                          String select,
                                          APISpec spec,
                                          String graphName,
                                          View view,
                                          List<com.hp.hpl.jena.rdf.model.Resource> results)

selectResources

protected Couple<String,List<com.hp.hpl.jena.rdf.model.Resource>> selectResources(Controls c,
                                                                      APISpec spec,
                                                                      Bindings b,
                                                                      Source source)

Answer the select query (if any; otherwise, "") and list of resources obtained by running that query. May be subclassed.

assembleRawCountQuery

public String assembleRawCountQuery(PrefixLogger pl,
                           Bindings b)

createQuery

protected com.hp.hpl.jena.query.Query createQuery(String selectQuery)

wantsMetadata

public boolean wantsMetadata(String name)

Specified by:

wantsMetadata in interface WantsMetadata

allowReserved

public boolean allowReserved(String name)

Answer true if name is a reserved name (_whatever) that is allowed to be used (and ignored).