org.intermine.pathquery
Class PathQuery

java.lang.Object
  org.intermine.pathquery.PathQuery

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

TemplateQuery

public class PathQuery
extends java.lang.Object
implements java.lang.Cloneable

Class to represent a path-based query.

Field Summary

protected static java.util.regex.Pattern	SPACE_SPLITTER A Pattern that finds spaces in a String.
static int	USERPROFILE_VERSION Version number for the userprofile and PathQuery XML format.

Constructor Summary

PathQuery(Model model)
Constructor.

PathQuery(PathQuery o)
Constructor.

Method Summary

java.lang.String	addConstraint(PathConstraint constraint) Adds a PathConstraint to this query.
void	addConstraint(PathConstraint constraint, java.lang.String code) Adds a PathConstraints to this query, associated with a given constraint code.
void	addConstraints(java.util.Collection<PathConstraint> constraints) Adds a collection of constraints to this query.
void	addConstraints(PathConstraint... constraints) Adds a group of constraints to this query.
void	addOrderBy(OrderElement orderElement) Adds an element to the order by list of this query.
void	addOrderBy(java.lang.String orderPath, OrderDirection direction) Adds an element to the order by list of this query.
void	addOrderBys(java.util.Collection<OrderElement> orderElements) Adds a group of elements to the order by list of this query.
void	addOrderBys(OrderElement... orderElements) Adds a group of elements to the order by list of this query.
void	addOrderBySpaceSeparated(java.lang.String orderString) Adds a group of elements to the order by list, given a space-separated list.
void	addView(java.lang.String viewPath) Add a single element to the view list.
void	addViews(java.util.Collection<java.lang.String> viewPaths) Adds a group of elements to the view list.
void	addViews(java.lang.String... viewPaths) Adds a group of elements to the view list.
void	addViewSpaceSeparated(java.lang.String viewPaths) Adds a group of elements to the view list, given a space-separated list.
static void	checkPathFormat(java.lang.String path) Verifies the format of a path for a query.
void	clearConstraints() Clears the entire set of constraints from this query, and resets the constraint logic.
void	clearDescriptions() Removes all path descriptions from this query.
void	clearOrderBy() Clears the entire order by list.
void	clearOuterJoinStatus() Clears all outer join status data from this query.
void	clearView() Clears the entire view list.
PathQuery	clone() Returns a deep copy of this object.
java.util.List<java.lang.String>	fixUpForJoinStyle() Fixes up the order by list and the constraint logic, given the arrangement of outer joins in the query.
java.util.Set<java.lang.String>	getBagNames() Returns all bag names used in constraints on this query.
java.util.Set<java.lang.String>	getCandidateLoops(java.lang.String stringPath) Returns the set of paths that could feasibly be loop constrained onto the given path, given the current outer join situation.
java.util.Set<java.lang.String>	getConstraintCodes() Return the constraint codes used in the query, some constraint types (subclasses) don't get assigned a code, these are not included.
PathConstraint	getConstraintForCode(java.lang.String code) Returns the PathConstraint associated with a given code.
java.util.Map<java.lang.String,java.util.Set<java.lang.String>>	getConstraintGroups() Returns the outer join constraint codes groups map for this query, if the query verifies correctly.
java.lang.String	getConstraintLogic() Returns the current constraint logic.
LogicExpression	getConstraintLogicForGroup(java.lang.String group) Returns the constraint logic for the given outer join group, if the query verifies correctly.
java.util.Map<PathConstraint,java.lang.String>	getConstraints() Returns a Map of all the constraints in this query, from PathConstraint to the constraint code used in the constraint logic.
java.util.List<PathConstraint>	getConstraintsForPath(java.lang.String path) Returns a list of PathConstraints applied to a given path or an empty list.
java.lang.String	getDescription() Gets the description for this PathQuery.
java.lang.String	getDescription(java.lang.String path) Returns the description for a given path, or null if no description is registered.
java.util.Map<java.lang.String,java.lang.String>	getDescriptions() Returns an unmodifiable Map which is a copy of the current set of path descriptions of this query at the time of execution of this method.
java.util.Set<java.lang.String>	getExistingLoops() Returns the set of loop constraint descriptive strings, for the purpose of checking for uniqueness.
java.lang.String	getGeneratedPathDescription(java.lang.String path) Returns the path description for the given path.
java.util.List<java.lang.String>	getGroupedConstraintLogic() Returns a List of logic Strings according to the different outer join sections of the query.
Model	getModel() Returns the Model object stored in this object.
java.util.List<OrderElement>	getOrderBy() Returns the current order by list.
java.lang.String	getOuterJoinGroup(java.lang.String stringPath) Returns the outer join group that the given path is in.
java.util.Map<java.lang.String,java.lang.String>	getOuterJoinGroups() Returns the outer join groups map for this query, if the query verifies correctly.
java.util.Map<java.lang.String,OuterJoinStatus>	getOuterJoinStatus() Returns an unmodifiable Map which is a copy of the current outer join status of this query at the time of execution of this method.
OuterJoinStatus	getOuterJoinStatus(java.lang.String path) Returns the outer join status of the last part of a given path in this query.
java.util.Map<java.lang.String,java.lang.Boolean>	getOuterMap() Returns a Map from path to TRUE for all paths that are outer joined.
PathQuery	getQueryToExecute() Get the PathQuery that should be executed.
java.lang.String	getRootClass() Returns the root path for this query, if the query verifies correctly.
java.util.Map<java.lang.String,java.lang.String>	getSubclasses() Returns the subclass Map for this query, if the query verifies correctly.
java.util.List<java.lang.String>	getView() Returns the current view list.
boolean	isPathCompletelyInner(java.lang.String stringPath) Returns true if a path string is in the root outer join group of this query.
boolean	isValid() Returns true if the query verifies correctly.
Path	makePath(java.lang.String path) Produces a Path object from the given path String, using subclass information from the query.
void	removeAllIrrelevant() Removes everything from this query that is irrelevant, and therefore making the query invalid.
void	removeAllUnder(java.lang.String path) Removes everything under a given path from the query, such that if the query was valid before, it will be valid after this method.
void	removeConstraint(PathConstraint constraint) Removes a constraint from this query.
void	removeOrderBy(java.lang.String orderPath) Removes an element from the order by list of this query.
java.util.List<java.lang.String>	removeSubclassAndFixUp(java.lang.String path) Removes a subclass from the query, and removes any parts of the query that relied on it.
void	removeView(java.lang.String viewPath) Removes a single element from the view list.
void	replaceConstraint(PathConstraint old, PathConstraint replacement) Replaces a constraint in the query with a different, carrying over the constraint code, and preserving the constraint logic.
void	setConstraintLogic(java.lang.String logic) Sets the current constraint logic.
void	setDescription(java.lang.String description) Sets the description for this PathQuery.
void	setDescription(java.lang.String path, java.lang.String description) Sets the description for a given path.
void	setOuterJoinStatus(java.lang.String path, OuterJoinStatus status) Sets the outer join status of the last part of a given path in this query.
protected void	sortConstraints(java.util.List<PathConstraint> listToSortBy) A method to sort constraints by a given lists, provided to allow TemplateQuery to set a specific sort order that will be preserved in a round-trip to XML.
java.lang.String	toString() Converts this object into a rudimentary String format, containing all the data.
java.lang.String	toXml(int version) Convert a PathQuery to XML.
java.util.List<java.lang.String>	verifyQuery() Verifies the contents of this query against the model, and for internal integrity.

Methods inherited from class java.lang.Object

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

Field Detail

SPACE_SPLITTER

protected static final java.util.regex.Pattern SPACE_SPLITTER

A Pattern that finds spaces in a String.

USERPROFILE_VERSION

public static final int USERPROFILE_VERSION

Version number for the userprofile and PathQuery XML format.

See Also:

Constant Field Values

Constructor Detail

PathQuery

public PathQuery(Model model)

Constructor. Takes a Model object, to enable verification later.

Parameters:

model - a Model object

PathQuery

public PathQuery(PathQuery o)

Constructor. Takes an existing PathQuery object, and copies all the data. Similar to the clone method.

Parameters:

o - a PathQuery to copy

Method Detail

getModel

public Model getModel()

Returns the Model object stored in this object.

Returns:

a Model

addView

public void addView(java.lang.String viewPath)

Add a single element to the view list. The element should be a normal path expression, with dots separating the parts. Do not use colons to represent outer joins, and do not use square brackets to represent subclass constraints. The path will not be verified until the verifyQuery() method is called, but will be merely checked for format.

Parameters:

viewPath - the new path String to add to the view list

Throws:

java.lang.NullPointerException - if viewPath is null

java.lang.IllegalArgumentException - if the viewPath contains colons or square brackets, or is otherwise in a bad format

removeView

public void removeView(java.lang.String viewPath)

Removes a single element from the view list. The element should be a normal path expression, with dots separating the parts. Do not use colons to represent outer joins, and do not use square brackets to represent subclass constraints. If there are multiple copies of the path on the view list (which is an invalid query), then this method will remove all of them.

Parameters:

viewPath - the path String to remove from the view list

Throws:

java.lang.NullPointerException - if the viewPath is null

java.util.NoSuchElementException - if the viewPath is not already on the view list

clearView

public void clearView()

Clears the entire view list.

addViews

public void addViews(java.util.Collection<java.lang.String> viewPaths)

Adds a group of elements to the view list. The elements should be normal path expressions, with dots separating the parts. Do not use colons to represent outer joins, and do not use square brackets to represent subclass constraints. The paths will not be verified until the verifyQuery() method is called, but will merely be checked for format. The paths will be added in the order of the iterator of the collection. If there is an error with any of the elements of the collection, then none of the elements will be added and the query will be unchanged.

Parameters:

viewPaths - a Collection of String paths to add to the view list

Throws:

java.lang.NullPointerException - if viewPaths is null or contains a null element

java.lang.IllegalArgumentException - if a view path contains colons or square brackets, or is otherwise in a bad format

addViews

public void addViews(java.lang.String... viewPaths)

Adds a group of elements to the view list. The elements should be normal path expressions, with dots separating the parts. Do not use colons to represent outer joins, and do not use square brackets to represent subclass constraints. The paths will not be verified until the verifyQuery() method is called, but will merely be checked for format. The paths will be added in the order of the arguments (varargs or array). If there is an error with any of the elements of the array/varargs, then none of the elements will be added and the query will be unchanged.

Parameters:

viewPaths - String paths to add to the view list

Throws:

java.lang.NullPointerException - if viewPaths is null or contains a null element

java.lang.IllegalArgumentException - if a view path contains colons or square brackets, or is otherwise in a bad format

addViewSpaceSeparated

public void addViewSpaceSeparated(java.lang.String viewPaths)

Adds a group of elements to the view list, given a space-separated list. The elements should be normal path expressions, with dots separating the parts. Do not use colons to represent outer joins, and do not use square brackets to represent subclass constraints. The paths will not be verified until the verifyQuery() method is called, but will merely be checked for format. The paths will be added preserving the order in the argument. The paths should be separated by spaces in the argument, but not commas. If there is an error with any of the elements in the argument, then none of the elements will be added and the query will be unchanged.

Parameters:

viewPaths - String paths to add to the view list

Throws:

java.lang.NullPointerException - if viewPaths is null or contains a null element

java.lang.IllegalArgumentException - if a view path contains colons or square brackets, or is otherwise in a bad format

getView

public java.util.List<java.lang.String> getView()

Returns the current view list. This is an unmodifiable copy of the view list as it is at the point of execution of this method. Changes in this query are not reflected in the result of this method. The paths listed are normal path expressions without colons or square brackets. The paths may not have been verified.

Returns:

a List of String paths

addOrderBy

public void addOrderBy(java.lang.String orderPath,
                       OrderDirection direction)

Adds an element to the order by list of this query. The element should be a normal path expression, with dots separating the parts. Do not use colons to represent outer joins, and do not use square brackets to represent subclass constraints. The path will not be verified until the verifyQuery() method is called, but will merely be checked for format.

Parameters:

orderPath - the path expression to add to the order by list

direction - the sort order

Throws:

java.lang.NullPointerException - if orderPath or direction is null

java.lang.IllegalArgumentException - if the orderPath contains colons or square brackets, or is otherwise in a bad format

removeOrderBy

public void removeOrderBy(java.lang.String orderPath)

Removes an element from the order by list of this query. The element should be a normal path expression, with dots separating the parts. Do not use colons to represent outer joins, and do not use square brackets to represent subclass constraints. If there are multiple copies of the path on the order by list (which is an invalid query), then this method will remove all of them.

Parameters:

orderPath - the path String to remove from the order by list

Throws:

java.lang.NullPointerException - if the orderPath is null

java.util.NoSuchElementException - if the orderPath is not already in the order by list

clearOrderBy

public void clearOrderBy()

Clears the entire order by list.

addOrderBy

public void addOrderBy(OrderElement orderElement)

Adds an element to the order by list of this query. The OrderElement will have already checked the path for format, and the path will not be verified until the verifyQuery() method is called.

Parameters:

orderElement - an OrderElement to add to the order by list

Throws:

java.lang.NullPointerException - if orderElement is null

addOrderBys

public void addOrderBys(java.util.Collection<OrderElement> orderElements)

Adds a group of elements to the order by list of this query. The elements will have already checked the paths for format, but the paths will not be verified until the verifyQuery() method is called. If there is an error with any of the elements of the collection, then none of the elements will be added and the query will be unchanged.

Parameters:

orderElements - a Collection of OrderElement objects to add to the view list

Throws:

java.lang.NullPointerException - if orderElements is null or contains a null element

addOrderBys

public void addOrderBys(OrderElement... orderElements)

Adds a group of elements to the order by list of this query. The elements will have already checked the paths for format, but the paths will not be verified until the verifyQuery() method is called. If there is an error with any of the elements in this array/varargs, then none of the elements will be added and the query will be unchanged.

Parameters:

orderElements - an array/varargs of OrderElement objects to add to the view list

Throws:

java.lang.NullPointerException - if orderElements is null or contains a null element

addOrderBySpaceSeparated

public void addOrderBySpaceSeparated(java.lang.String orderString)

Adds a group of elements to the order by list, given a space-separated list. The elements should be normal path expressions, with dots separating the parts. Do not use colons to represent outer joins, and do not use square brackets to represent subclass constraints. The paths will not be verified until the verifyQuery() method is called, but will merely be checked for format. The paths will be added preserving the order in the argument. Each element should be a path expression followed by a space and then either "asc" or "desc" to describe the direction of sorting, and the elements should be separated by spaces. If there is an error with any of the elements in the argument, then none of the elements will be added and the query will be unchanged.

Parameters:

orderString - the order elements in space-separated string form

Throws:

java.lang.NullPointerException - if orderString is null

java.lang.IllegalArgumentException - if a path expression contains colons or square brackets, or is otherwise in a bad format, or if there is not an even number of space-separated elements, or if any even-numbered element is not either "asc" or "desc".

getOrderBy

public java.util.List<OrderElement> getOrderBy()

Returns the current order by list. This is an unmodifiable copy of the order by list as it is at the point of execution of this method. Changes in this query are not reflected in the result of this method. The returned value is a List containing OrderElement objects, which contain a String path expression without colons or square brackets, and an OrderDirection. The paths may not have been verified.

Returns:

a List of OrderElement objects

addConstraint

public java.lang.String addConstraint(PathConstraint constraint)

Adds a PathConstraint to this query. The PathConstraint will be attached to the path in the constraint, which will have already been checked for format (no colons or square brackets), but will not be verified until the verifyQuery() method is called. This method returns a String code which is a single character that can be used in the constraint logic to logically combine constraints. The constraint will be added to the existing constraint logic with the AND operator - for any other arrangement, set the logic after calling this method. If the constraint is already present in the query, then this method will do nothing.

Parameters:

constraint - the PathConstraint to add to this query

Returns:

a String constraint code for use in the constraint logic

Throws:

java.lang.NullPointerException - if the constraint is null

addConstraint

public void addConstraint(PathConstraint constraint,
                          java.lang.String code)

Adds a PathConstraints to this query, associated with a given constraint code. The PathConstraint will be attached to the path in the constraint, which will have already been checked for format (no colons or square brackets), but will not be verified until the verifyQuery() method is called. If the given code is already in use by a different constraint, or if the constraint already has a different code, then an exception is thrown. The new constraint will be added to the existing constraint logic with the AND operator - for any other arrangement, set the logic after calling this method. If the constraint is already present in the query with the same constraint code, then this method will do nothing.

Parameters:

constraint - the PathConstraint to add to this query

code - the constraint code to associate with this constraint

Throws:

java.lang.NullPointerException - if the constraint or the code is null

java.lang.IllegalStateException - if the constraint is already associated with a different code, or the code is already associated with a different constraint

java.lang.IllegalArgumentException - if the code is in an inappropriate format - that is, if it is not a single uppercase character

removeConstraint

public void removeConstraint(PathConstraint constraint)

Removes a constraint from this query. The PathConstraint should be a constraint that already exists in this query. The constraint will also be removed from the constraint logic.

Parameters:

constraint - the PathConstraint to remove from this query

Throws:

java.lang.NullPointerException - if the constraint is null

java.util.NoSuchElementException - if the constraint is not present in the query

replaceConstraint

public void replaceConstraint(PathConstraint old,
                              PathConstraint replacement)

Replaces a constraint in the query with a different, carrying over the constraint code, and preserving the constraint logic. The new PathConstraint will be attached to the path in the constraint, which will have already been checked for format (no colons or square brackets), but will not be verified until the verifyQuery() method is called. This method preserves the order of constraints - that is, the replacement will be swapped in where the old constraint was.

Parameters:

old - the old PathConstraint object

replacement - the new PathConstraint object to replace it

Throws:

java.lang.NullPointerException - if old or replacement are null

java.util.NoSuchElementException - if the old PathConstraint is not already in the query

java.lang.IllegalArgumentException - if the code from the old constraint is not appropriate to the replacement constraint

java.lang.IllegalStateException - if the replacement is already in the query

clearConstraints

public void clearConstraints()

Clears the entire set of constraints from this query, and resets the constraint logic.

addConstraints

public void addConstraints(java.util.Collection<PathConstraint> constraints)

Adds a collection of constraints to this query. The PathConstraints will be attached to the paths in the constraints, which will have already been checked for format (no colons or square brackets), but will not be verified until the verifyQuery() method is called. The constraints will all be given codes, and added to the constraint logic with the default AND operator. To discover the codes, use the getConstraints() method. If there is an error with any of the elements in the collection, then none of the elements will be added and the query will be unchanged.

Parameters:

constraints - the PathConstraint objects to add to this query

Throws:

java.lang.NullPointerException - if constraints is null, or if it contains a null element

addConstraints

public void addConstraints(PathConstraint... constraints)

Adds a group of constraints to this query. The PathConstraints will be attached to the paths in the constraints, which will have already been checked for format (no colons or square brackets), but will not be verified until the verifyQuery() method is called. The constraints will all be given codes, and added to the constraint logic with the default AND operator. To discover the codes, use the getConstraints() method. If there is an error with any of the elements in the array/varargs, then none of the elements will be added and the query will be unchanged.

Parameters:

constraints - the PathConstraint objects to add to this query

Throws:

java.lang.NullPointerException - if constraints is null, or if it contains a null element

getConstraints

public java.util.Map<PathConstraint,java.lang.String> getConstraints()

Returns a Map of all the constraints in this query, from PathConstraint to the constraint code used in the constraint logic. This returns an unmodifiable copy of the data in the query at the moment this method is executed, so further changes to the query are not reflected in the returned value.

Returns:

a Map from PathConstraint to String constraint code (a single character)

getConstraintForCode

public PathConstraint getConstraintForCode(java.lang.String code)

Returns the PathConstraint associated with a given code.

Parameters:

code - a single uppercase character

Returns:

a PathConstraint object

Throws:

java.lang.NullPointerException - if code is null

java.util.NoSuchElementException - if there is no PathConstraint for that code

getConstraintsForPath

public java.util.List<PathConstraint> getConstraintsForPath(java.lang.String path)

Returns a list of PathConstraints applied to a given path or an empty list.

Parameters:

path - the path to fetch constraints for

Returns:

a List of PathConstraints or an empty list

getConstraintCodes

public java.util.Set<java.lang.String> getConstraintCodes()

Return the constraint codes used in the query, some constraint types (subclasses) don't get assigned a code, these are not included. This method returns all of the codes that should be involved in the logic expression of the query.

Returns:

the constraint codes used in this query

getConstraintLogic

public java.lang.String getConstraintLogic()

Returns the current constraint logic. The logic is returned in groups, according to the outer join layout of the query. Two codes in separate groups can only be combined with an AND operation, not an OR operation.

Returns:

the current constraint logic

setConstraintLogic

public void setConstraintLogic(java.lang.String logic)

Sets the current constraint logic.

Parameters:

logic - the constraint logic

getOuterJoinStatus

public OuterJoinStatus getOuterJoinStatus(java.lang.String path)

Returns the outer join status of the last part of a given path in this query. The given path expression should not contain any colons to represent outer joins, and should not contain any square brackets to represent subclass constraints.

Parameters:

path - a String path to check

Returns:

an OuterJoinStatus object, or null if no information is held

Throws:

java.lang.NullPointerException - if path is null

java.lang.IllegalArgumentException - if the path String contains colons or square brackets, or is otherwise in a bad format

setOuterJoinStatus

public void setOuterJoinStatus(java.lang.String path,
                               OuterJoinStatus status)

Sets the outer join status of the last part of a given path in this query. The given path expression should not contain any colons to represent outer joins, and should not contain any square brackets to represent subclass constraints. To remove outer join status from a path, call this method with a null status.

Parameters:

path - a String path to set

status - an OuterJoinStatus object

Throws:

java.lang.NullPointerException - if path is null

java.lang.IllegalArgumentException - if the path String contains colons or square brackets, or is otherwise in a bad format

getOuterJoinStatus

public java.util.Map<java.lang.String,OuterJoinStatus> getOuterJoinStatus()

Returns an unmodifiable Map which is a copy of the current outer join status of this query at the time of execution of this method. Further changes to this object will not be reflected in the object that was returned from this method.

Returns:

a Map from String path to OuterJoinStatus

clearOuterJoinStatus

public void clearOuterJoinStatus()

Clears all outer join status data from this query.

getOuterMap

public java.util.Map<java.lang.String,java.lang.Boolean> getOuterMap()

Returns a Map from path to TRUE for all paths that are outer joined. That is, if the path is an outer join (not referring to its parents - use isCompletelyInner() for that), then it is present in this map mapped onto the value TRUE.

Returns:

a Map from String to Boolean TRUE

getDescription

public java.lang.String getDescription(java.lang.String path)

Returns the description for a given path, or null if no description is registered. The given path expression should not contain any colons to represent outer joins, and should not contain any square brackets to represent subclass constraints.

Parameters:

path - a String path to check

Returns:

a String description

Throws:

java.lang.NullPointerException - if path is null

java.lang.IllegalArgumentException - if the path String contains colons or square brackets, or is otherwise in a bad format

setDescription

public void setDescription(java.lang.String path,
                           java.lang.String description)

Sets the description for a given path. The given path expression should not contain any colons to represent outer joins, and should not contain any square brackets to represent subclass constraints. To clear the description on a path, call this method with a null description.

Parameters:

path - the String path to set

description - a String description or null

Throws:

java.lang.NullPointerException - if path is null

java.lang.IllegalArgumentException - if the path String contains colons or square brackets, or is otherwise in a bad format

getDescriptions

public java.util.Map<java.lang.String,java.lang.String> getDescriptions()

Returns an unmodifiable Map which is a copy of the current set of path descriptions of this query at the time of execution of this method. Further changes to this object will not be reflected in the object that was returned from this method.

Returns:

a Map from String path to description

clearDescriptions

public void clearDescriptions()

Removes all path descriptions from this query.

getGeneratedPathDescription

public java.lang.String getGeneratedPathDescription(java.lang.String path)

Returns the path description for the given path. The description is computed from the set descriptions of parent classes.

Parameters:

path - a String path with no square brackets or colons

Returns:

a String description

Throws:

java.lang.NullPointerException - is path is null

java.lang.IllegalArgumentException - if the path String contains colons or square brackets, or is otherwise in a bad format

setDescription

public void setDescription(java.lang.String description)

Sets the description for this PathQuery.

Parameters:

description - the new description, or null for none

getDescription

public java.lang.String getDescription()

Gets the description for this PathQuery.

Returns:

description

removeAllUnder

public void removeAllUnder(java.lang.String path)

Removes everything under a given path from the query, such that if the query was valid before, it will be valid after this method.

Parameters:

path - everything under this path will be removed from the query

Throws:

java.lang.NullPointerException - is path is null

java.lang.IllegalArgumentException - if the path String contains colons or square brackets, or is otherwise in a bad format

removeAllIrrelevant

public void removeAllIrrelevant()
                         throws PathException

Removes everything from this query that is irrelevant, and therefore making the query invalid. If the query is invalid for other reasons, then this method will either throw an exception or ignore that part of the query, depending on the error, however the query is unlikely to be made valid.

Throws:

PathException - if the query is invalid for a reason other than irrelevance

fixUpForJoinStyle

public java.util.List<java.lang.String> fixUpForJoinStyle()
                                                   throws PathException

Fixes up the order by list and the constraint logic, given the arrangement of outer joins in the query.

Returns:

a List of messages about the changes that this method has made to the query

Throws:

PathException - if the query is invalid in any way other than that which this method will fix.

removeSubclassAndFixUp

public java.util.List<java.lang.String> removeSubclassAndFixUp(java.lang.String path)
                                                        throws PathException

Removes a subclass from the query, and removes any parts of the query that relied on it. Returns a list of messages related to the extra things that had to be removed.

Parameters:

path - the path of the subclass constraint to remove

Returns:

a list of messages

Throws:

PathException - if the query is already invalid

java.lang.NullPointerException - is path is null

java.lang.IllegalArgumentException - if the path String contains colons or square brackets, or is otherwise in a bad format

clone

public PathQuery clone()

Returns a deep copy of this object. The resulting object may be modified without impacting this object.

Overrides:

clone in class java.lang.Object

Returns:

a PathQuery

makePath

public Path makePath(java.lang.String path)
              throws PathException

Produces a Path object from the given path String, using subclass information from the query. Note that this method does not verify the query, but merely attempts to extract as much sane subclass information as possible to construct the Path.

Parameters:

path - the String path

Returns:

a Path object

Throws:

PathException - if something goes wrong, or if the path is in an invalid format

isValid

public boolean isValid()

Returns true if the query verifies correctly.

Returns:

a boolean

verifyQuery

public java.util.List<java.lang.String> verifyQuery()

Verifies the contents of this query against the model, and for internal integrity. Returns a list of String problems that would need to be rectified for this query to pass validation and be executed. If the return value is an empty List, then the query is valid.
This method validates a few important characteristics about the query:

• All subclass constraints must be subclasses of the class they would otherwise be
• All paths must validate against the model
• All paths need to extend from the same root class
• Paths in the order by list, the outer join status, and the descriptions, must all be attached to classes already defined by the view list and the constraints. Otherwise, it would be possible to change the number of rows by changing the order
• All elements of the view list and the order by list must be attributes, and all paths for outer join status and subclass constraints must not be attributes
• Subclass constraints cannot be on the root class of the query
• Loop constraints cannot cross an outer join
• Check constraint values against their types in the model and specific characteristics
• Check constraint logic for sanity and that it can be split into separate ANDed outer join sections

Returns:

a List of problems

getRootClass

public java.lang.String getRootClass()
                              throws PathException

Returns the root path for this query, if the query verifies correctly.

Returns:

a String path which is the root class

Throws:

PathException - if the query does not verify

getSubclasses

public java.util.Map<java.lang.String,java.lang.String> getSubclasses()
                                                               throws PathException

Returns the subclass Map for this query, if the query verifies correctly.

Returns:

a Map from path String to subclass name, for all PathConstraintSubclass objects

Throws:

PathException - if the query does not verify

getBagNames

public java.util.Set<java.lang.String> getBagNames()

Returns all bag names used in constraints on this query.

Returns:

the bag names used in this query or an empty set

getOuterJoinGroups

public java.util.Map<java.lang.String,java.lang.String> getOuterJoinGroups()
                                                                    throws PathException

Returns the outer join groups map for this query, if the query verifies correctly. This is a Map from all the class paths in the query to the outer join group, represented by the path of the root of the group.

Returns:

a Map from path String to the outer join group it is in

Throws:

PathException - if the query does not verify

getExistingLoops

public java.util.Set<java.lang.String> getExistingLoops()
                                                 throws PathException

Returns the set of loop constraint descriptive strings, for the purpose of checking for uniqueness.

Returns:

a Set of Strings

Throws:

PathException - if the query does not verify

getOuterJoinGroup

public java.lang.String getOuterJoinGroup(java.lang.String stringPath)
                                   throws PathException

Returns the outer join group that the given path is in.

Parameters:

stringPath - a pathString

Returns:

a String representing the outer join group that the path is in

Throws:

java.lang.NullPointerException - if pathString is null

PathException - if the query is invalid or the path is invalid

java.util.NoSuchElementException - is the path is not in the query

isPathCompletelyInner

public boolean isPathCompletelyInner(java.lang.String stringPath)
                              throws PathException

Returns true if a path string is in the root outer join group of this query.

Parameters:

stringPath - a path String

Returns:

true if the given path is in the root outer join group, false if it contains outer joins

Throws:

java.lang.NullPointerException - if pathString is null

PathException - if the query is invalid or the path is invalid

java.util.NoSuchElementException - if the path is not in the query

getCandidateLoops

public java.util.Set<java.lang.String> getCandidateLoops(java.lang.String stringPath)
                                                  throws PathException

Returns the set of paths that could feasibly be loop constrained onto the given path, given the current outer join situation. A candidate path must be a class path, of the same type, and in the same outer join group. It must also not be already looped onto this path.

Parameters:

stringPath - a path String

Returns:

a Set of path strings that could be looped onto the given path

Throws:

java.lang.NullPointerException - if stringPath is null

java.lang.IllegalArgumentException - if stringPath refers to an attribute

PathException - if the query is invalid or stringPath is invalid

getConstraintGroups

public java.util.Map<java.lang.String,java.util.Set<java.lang.String>> getConstraintGroups()
                                                                                    throws PathException

Returns the outer join constraint codes groups map for this query, if the query verifies correctly.

Returns:

a Map from outer join group to the Set of constraint codes in the group

Throws:

PathException - if the query does not verify

getGroupedConstraintLogic

public java.util.List<java.lang.String> getGroupedConstraintLogic()
                                                           throws PathException

Returns a List of logic Strings according to the different outer join sections of the query.

Returns:

a List of String

Throws:

PathException - if the query does not verify

getConstraintLogicForGroup

public LogicExpression getConstraintLogicForGroup(java.lang.String group)
                                           throws PathException

Returns the constraint logic for the given outer join group, if the query verifies correctly.

Parameters:

group - an outer join group

Returns:

the constraint logic for the constraints in that outer join group

Throws:

PathException - if the query does not verify

java.lang.IllegalArgumentException - if the group is not present in this query

checkPathFormat

public static void checkPathFormat(java.lang.String path)

Verifies the format of a path for a query. Paths must fully match the regular expression "([a-zA-Z0-9]+\.)*[a-zA-Z0-9]+"

Parameters:

path - a String path

Throws:

java.lang.NullPointerException - if path is null

java.lang.IllegalArgumentException - if path contains colons or square brackets, or is otherwise in a bad format

getQueryToExecute

public PathQuery getQueryToExecute()

Get the PathQuery that should be executed. This should be called by code creating an ObjectStore query from a PathQuery. For PathQuery the method returns this, subclasses can override. TemplateQuery removes optional constraints that have been switched off in the returned query.

Returns:

a version of the query to execute

sortConstraints

protected void sortConstraints(java.util.List<PathConstraint> listToSortBy)

A method to sort constraints by a given lists, provided to allow TemplateQuery to set a specific sort order that will be preserved in a round-trip to XML. A list of constraints is provided, the constraints map is updated to reflect that order. The list does not need to contain all constraints in the query - TemplateQuery only needs to order the editable constraints.

Parameters:

listToSortBy - a list to define the new constraint order

toString

public java.lang.String toString()

Converts this object into a rudimentary String format, containing all the data.

Overrides:

toString in class java.lang.Object

toXml

public java.lang.String toXml(int version)

Convert a PathQuery to XML.

Parameters:

version - the version number of the XML format

Returns:

this template query as XML.