org.ceryle.wiki.plugin.query
Class QueryPlugin

java.lang.Object
  org.ceryle.wiki.plugin.query.QueryPlugin

All Implemented Interfaces:

WikiPlugin, PluginConstants

Direct Known Subclasses:

Query, QueryExecutor

public class QueryPlugin
extends Object
implements WikiPlugin, PluginConstants

The QueryPlugin treats the pages and references between them like a database. You can query the pages using a simple syntax (AND, OR, NOT, ...). The matching pages are returned sorted alphabetically in a bulleted list.

The query is done against the ReferenceManager's collection of all pages/links so it's fast. The query results are "cached" for 30 seconds, so viewing pages with a query doesn't load the server too much.

In some sense the ReferringPagesPlugin is a degenerate form of this plugin (pages='(TO [ThisPage]').

Parameters

• pages= The page query string to be evaluated, alternativly you can use a 'named' query.
• named= If 'pages' is not specified, the plugin will look for a 'named' query that is defined in your properties file. If 'pages' or 'named' cannot be resovled into a usable expression, the plugin attempts to use it's raw commandline as a query expression.
• echo= Optional, echo the parsed parenthesized query string back out, default = 'false', set to 'true' to see the formalized form of your query.
• emptytext= Optional. This is the (non-markup) text returned if there is no query result. The default is "No pages found."
• output= Optional. One of 'none', 'count', 'list', 'bullet', 'number', 'space' or 'comma'. This alters the output presentation of the query result pages. The default is 'list' which generates a simple vertical list; 'none' suppresses the list output; 'bullet' and 'number' generate bulleted and numbered lists (resp.); 'space' generates a space-delimited list; 'comma' generates a comma-delimited list.

Query Syntax

The query syntax is pretty basic.

Parentheses

Must "balance" (the number of ( must match the number of ), and must "nest" properly ( ())( balances, but doesn't nest properly). Explicit parentheses are respected when present. As is typical of most queries, more parentheses are better, in that you don't have to worry about how the plugin dis-ambiguages and formalizes your query string. This version of QueryPlugin now permits use of regular expressions in Terms.

Brackets

All page names in the query string must be surrounded by []'s. Failure to enclose a page name in []'s will cause the parser to choke. Brackets must "balance" and must not "nest".

Prefix Operators	IS, TO, FROM (BY), NOT, ALL, ANY	OPERATOR (...)
Infix Operators	AND, OR	(... OPERATOR ...)

AND, OR, NOT

Pretty much what you'd expect.

IS(...)

Selects the pages specified as ...

TO(...)

Selects pages that refer "to" the pages specified as ...

FROM(...)

Selects pages that are referenced "from" the pages specified as ... (previously "by")

Page Names

Must be in brackets, must be given as CamelCase (no spaces or special chars, named just like the page would appear on the URL.

Regular Expressions

This version of QueryPlugin now provides for Java-style regular expressions in the specification of terms, e.g., [Wiki.*] returns all wiki pages whose name begins with "Wiki".

NOTE: The token [.] is NOT treated as a regular expression, rather it is expanded into the current page name.

Example Usage

Here is a "realistic" example (for you XP folks) that would list all pages linking to the pages [Bug] and [Open] an not linked to by [PlanningGame].

   [{QueryPlugin pages='TO( [Bug] AND [Open]) AND NOT( BY( [PlanningGame] ) )'}]
   
  Alternatively if your jspwiki.properties file contained:
    queryPlugin.namedExpression.unplannedOpenBugs=TO( [Bug] AND [Open]) AND NOT( BY( [PlanningGame] ) )
  You could use: 
   [{QueryPlugin named='unplannedOpenBugs'}]
   
  Finally if you don't need or want to specify any other parameters:
   [{QueryPlugin TO( [Bug] AND [Open]) AND NOT( BY( [PlanningGame] ) )}]
 

Examples

[{QueryPlugin pages='TO [Main]'}]

Returns all pages referring to [Main].

[{QueryPlugin pages='BY [Main]'}]

Returns all pages that [Main] refers to.

[{QueryPlugin pages='IS [Main]'}]

Returns the [Main] page.

[{QueryPlugin pages='NOT TO [Main]'}]

Returns all pages that don't refer to [Main] (probably a lot!).

[{QueryPlugin pages='NOT BY [Main]'}]

Returns all pages that [Main] doesn't refer to (again, probably a lot!).

[{QueryPlugin pages='IS NOT [Main]'}]

Returns every page except for the [Main] page.

[{QueryPlugin pages='NOT IS [Main]'}]

Same as IS NOT, yup the parser/evaluator is pretty flexible.

Author:

Murray Altheim, John Volkar (john.volkar at gmail.com)

Field Summary

String	currentPageName
protected static String	DIV_query
protected String	m_emptyText
protected boolean	m_executionError
protected static QueryItemManager	m_queryManager
protected String	NoPagesFound
static String	PARAM_ECHO
static String	PARAM_EMPTY_TEXT
static String	PARAM_NAMED
static String	PARAM_OUTPUT The parameter indicating the output format.
static String	PARAM_PAGES
static String	PARAM_PARSED_EXPRESSION
static String	PROP_PREFIX_NAMED

Fields inherited from interface com.ecyrd.jspwiki.plugin.WikiPlugin

CORE_PLUGINS_RESOURCEBUNDLE

Fields inherited from interface org.ceryle.wiki.plugin.util.PluginConstants

ACL, AOP, APOS_ENT, ASTERISK, BCL, BOP, BR, CAPCL, CAPOP, CLATT, COLON, COMMA, DIV_class, DIV_style, DIVCL, DOT, EQ, EQQUO, EQSQUO, FALSE, FORMCL, FORMOP, GET, ICL, INPUTOP, IOP, LABELCL, LABELFOR, LABELOP, LCURL, LICL, LIOP, LPAR, LSBR, MT, NBSP, NL, OLCL, OLOP, P_class, PCL, PLUGCL, PLUGO, POP, POST, QUO, QUOCL, QUOETCL, RCURL, RPAR, RSBR, SEMI, SP, SPAN_class, SPANCL, SPANOP, SQUO, TABLECL, TABLEOP, TDCL, TDOP, THCL, THOP, TRCL, TROP, TRUE, TTCL, TTOP, ULCL, ULOP, UNDER

Constructor Summary

QueryPlugin()

Method Summary

protected String	error(String message)
String	execute(WikiContext context, Map params) This expands the this page notation, then calls the actual workhorse of this plugin, execute(WikiEngine,Map).
String	execute(WikiEngine engine, Map params) Execute a query upon the wiki using the parameters provided.
WikiContext	getContext() Returns the WikiContext, or null it has not been set.
String	getExpression() Return the page expression as processed from the query.
String	getOutput(WikiEngine engine) Return appropriate XHTML markup for the query results, obtained from getResultSet().
int	getOutputFormat() Return the output format as set by the default or the input parameter.
protected String	getQueryExpression(WikiEngine engine, Map params) Return the page expression provided the parameter set.
Set	getResultSet() Returns the results of the last query execution.
protected boolean	isDebug() Returns true if in debug mode.
protected boolean	isEcho() Returns true if in echo mode.
protected void	setResultSet(Set resultSet) Sets the output result to the provided Set.

Methods inherited from class java.lang.Object

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

Field Detail

PARAM_PAGES

public static final String PARAM_PAGES

See Also:

Constant Field Values

PARAM_ECHO

public static final String PARAM_ECHO

See Also:

Constant Field Values

PARAM_EMPTY_TEXT

public static final String PARAM_EMPTY_TEXT

See Also:

Constant Field Values

PARAM_NAMED

public static final String PARAM_NAMED

See Also:

Constant Field Values

PARAM_PARSED_EXPRESSION

public static final String PARAM_PARSED_EXPRESSION

See Also:

Constant Field Values

PROP_PREFIX_NAMED

public static final String PROP_PREFIX_NAMED

See Also:

Constant Field Values

PARAM_OUTPUT

public static final String PARAM_OUTPUT

The parameter indicating the output format. Acceptable values include those available in PluginTextUtils as any of the OUTPUT_* constants.

See Also:

Constant Field Values

DIV_query

protected static final String DIV_query

See Also:

Constant Field Values

m_queryManager

protected static QueryItemManager m_queryManager

NoPagesFound

protected String NoPagesFound

m_emptyText

protected String m_emptyText

m_executionError

protected boolean m_executionError

currentPageName

public String currentPageName

Constructor Detail

QueryPlugin

public QueryPlugin()

Method Detail

execute

public String execute(WikiContext context,
                      Map params)

This expands the this page notation, then calls the actual workhorse of this plugin, execute(WikiEngine,Map).

Specified by:

execute in interface WikiPlugin

See Also:

WikiPlugin.execute(com.ecyrd.jspwiki.WikiContext,java.util.Map)

execute

public String execute(WikiEngine engine,
                      Map params)

Execute a query upon the wiki using the parameters provided.

Parameters:

engine -

params -

Returns:

the generated HTML markup

isEcho

protected boolean isEcho()

Returns true if in echo mode.

isDebug

protected boolean isDebug()

Returns true if in debug mode.

setResultSet

protected void setResultSet(Set resultSet)

Sets the output result to the provided Set.

getContext

public WikiContext getContext()

Returns the WikiContext, or null it has not been set.

getQueryExpression

protected String getQueryExpression(WikiEngine engine,
                                    Map params)
                             throws PluginException

Return the page expression provided the parameter set.

Throws:

PluginException

getExpression

public String getExpression()

Return the page expression as processed from the query. This returns null if any errors occurred in processing.

getOutputFormat

public int getOutputFormat()

Return the output format as set by the default or the input parameter.

See Also:

for available constants.

getResultSet

public Set getResultSet()

Returns the results of the last query execution.

Returns:

the query results as a Set, or null if it has not occurred or has otherwise failed.

getOutput

public String getOutput(WikiEngine engine)

Return appropriate XHTML markup for the query results, obtained from getResultSet().

error

protected String error(String message)