Package 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.- Author:
- Matthew Wakeling
-
-
Field Summary
Fields Modifier and Type Field Description static char
MAX_CODE
The highest code value a constraint may be assigned.static int
MAX_CONSTRAINTS
The maximum number of coded constraints a PathQuery may hold.static char
MIN_CODE
The lowest code value a constraint may be assigned.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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description 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> constraintList)
Adds a collection of constraints to this query.void
addConstraints(PathConstraint... constraintList)
Adds a group of constraints to this query.protected void
addJsonProperty(java.lang.StringBuffer sb, java.lang.String key, java.lang.Object value)
Add a JSON property when serialisingvoid
addOrderBy(java.lang.String orderPath, OrderDirection direction)
Adds an element to the order by list of this query.void
addOrderBy(OrderElement orderElement)
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.lang.String... viewPaths)
Adds a group of elements to the view list.void
addViews(java.util.Collection<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.protected java.lang.String
constraintToJson(PathConstraint constraint, java.lang.String code)
void
deVerify()
assert that the query is dirty and needs to be re-checked.boolean
equals(java.lang.Object other)
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.protected java.lang.String
formatKVPair(java.lang.String key, java.lang.Object value)
Format a key-value pair in a JSON compatible way.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.List<java.lang.String>
getColumnHeaders()
Returns the paths descriptions for the view.protected java.lang.String
getCommonJsonConstraintPrefix(java.lang.String code, PathConstraint constraint)
Get the JSON prefix common to all constraints.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.protected java.util.Map<java.lang.String,java.lang.Object>
getHeadAttributes()
java.lang.String
getJson()
toJson synonym for JSPs.LogicExpression
getLogicExpression()
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.util.Map<PathConstraint,java.lang.String>
getRelevantConstraints()
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.lang.String
getTitle()
Gets the title for this query.java.util.List<java.lang.String>
getView()
Returns the current view list.int
hashCode()
boolean
isEmpty()
Returns true if the query has no features yet.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.void
setTitle(java.lang.String title)
Sets the name of the 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
toJson()
Convert this PathQuery to a JSON serialisation.java.lang.String
toJson(boolean onlyRelevant)
Convert this PathQuery to a JSON serialisation.java.lang.String
toJson(boolean onlyRelevant, java.util.Date date)
Convert this PathQuery to a JSON serialisation.java.lang.String
toJson(java.util.Date date)
Convert this PathQuery to a JSON serialisation.java.lang.String
toString()
Converts this object into a rudimentary String format, containing all the data.java.lang.String
toXml()
Convert a PathQuery to XML, using the default value of PathQuery.USERPROFILE_VERSIONjava.lang.String
toXml(int version)
Convert a PathQuery to XML.protected java.lang.String
typeConstraintToJson(PathConstraint constraint)
format a type constraint to a JSON representation.protected java.lang.String
valueConstraintToJson(java.lang.String code, PathConstraint constraint)
Format a value constraint to a JSON representation.java.util.List<java.lang.String>
verifyQuery()
Verifies the contents of this query against the model, and for internal integrity.
-
-
-
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. This should be incremented each time the PathQuery serialisation format changes.- 2
- Changed PathQuery format.
- 1
- Original format.
- See Also:
- Constant Field Values
-
MIN_CODE
public static final char MIN_CODE
The lowest code value a constraint may be assigned.- See Also:
- Constant Field Values
-
MAX_CODE
public static final char MAX_CODE
The highest code value a constraint may be assigned.- See Also:
- Constant Field Values
-
MAX_CONSTRAINTS
public static final int MAX_CONSTRAINTS
The maximum number of coded constraints a PathQuery may hold.- 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 nulljava.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 nulljava.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 elementjava.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 elementjava.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 elementjava.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 listdirection
- the sort order- Throws:
java.lang.NullPointerException
- if orderPath or direction is nulljava.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 nulljava.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 nulljava.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 querycode
- the constraint code to associate with this constraint. This must be a string consisting of one of the following characters "A","B","C","D","E","F","G", "H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z".- Throws:
java.lang.NullPointerException
- if the constraint or the code is nulljava.lang.IllegalStateException
- if the constraint is already associated with a different code, or the code is already associated with a different constraintjava.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 nulljava.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 objectreplacement
- the new PathConstraint object to replace it- Throws:
java.lang.NullPointerException
- if old or replacement are nulljava.util.NoSuchElementException
- if the old PathConstraint is not already in the queryjava.lang.IllegalArgumentException
- if the code from the old constraint is not appropriate to the replacement constraintjava.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> constraintList)
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:
constraintList
- 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... constraintList)
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:
constraintList
- 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)
-
getRelevantConstraints
public java.util.Map<PathConstraint,java.lang.String> getRelevantConstraints()
- Returns:
- the constraints that are relevant to the query.
-
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 nulljava.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 and OR operation.- Returns:
- the current constraint logic
-
getLogicExpression
public LogicExpression getLogicExpression()
- Returns:
- the logic expression
-
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 nulljava.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 setstatus
- an OuterJoinStatus object- Throws:
java.lang.NullPointerException
- if path is nulljava.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 nulljava.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 setdescription
- a String description or null- Throws:
java.lang.NullPointerException
- if path is nulljava.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 nulljava.lang.IllegalArgumentException
- if the path String contains colons or square brackets, or is otherwise in a bad format
-
getColumnHeaders
public java.util.List<java.lang.String> getColumnHeaders()
Returns the paths descriptions for the view.- Returns:
- A list of column names
-
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
-
getTitle
public java.lang.String getTitle()
Gets the title for this query.- Returns:
- The title of the query
-
setTitle
public void setTitle(java.lang.String title)
Sets the name of the query.- Parameters:
title
- the new title, or null for none.
-
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 nulljava.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 invalidjava.lang.NullPointerException
- is path is nulljava.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 classjava.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
-
deVerify
public void deVerify()
assert that the query is dirty and needs to be re-checked.
-
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
-
isEmpty
public boolean isEmpty()
Returns true if the query has no features yet.- Returns:
- whether or not this query is empty.
-
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 nullPathException
- if the query is invalid or the path is invalidjava.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 nullPathException
- if the query is invalid or the path is invalidjava.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 nulljava.lang.IllegalArgumentException
- if stringPath refers to an attributePathException
- 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 verifyjava.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 nulljava.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 classjava.lang.Object
-
toXml
public java.lang.String toXml()
Convert a PathQuery to XML, using the default value of PathQuery.USERPROFILE_VERSION- Returns:
- This query as xml
-
addJsonProperty
protected void addJsonProperty(java.lang.StringBuffer sb, java.lang.String key, java.lang.Object value)
Add a JSON property when serialising- Parameters:
sb
- The buffer we are serialing to.key
- the property name.value
- the property value.
-
formatKVPair
protected java.lang.String formatKVPair(java.lang.String key, java.lang.Object value)
Format a key-value pair in a JSON compatible way.- Parameters:
key
- The keyvalue
- The value- Returns:
- A string, all nicely formatted
-
getJson
public java.lang.String getJson()
toJson synonym for JSPs.- Returns:
- This query as json.
-
getHeadAttributes
protected java.util.Map<java.lang.String,java.lang.Object> getHeadAttributes()
- Returns:
- the attributes that should go in the head of a JSON object.
-
toJson
public java.lang.String toJson()
Convert this PathQuery to a JSON serialisation. The returned version should be trimmed to represent only the current state of the query, not all possible states.- Returns:
- This query as json.
-
toJson
public java.lang.String toJson(boolean onlyRelevant)
Convert this PathQuery to a JSON serialisation. The returned version should be trimmed to represent only the current state of the query, not all possible states.- Parameters:
onlyRelevant
- whether to only return relevant, active constraints.- Returns:
- This query as json.
-
toJson
public java.lang.String toJson(java.util.Date date)
Convert this PathQuery to a JSON serialisation. The returned version should be trimmed to represent only the current state of the query, not all possible states.- Parameters:
date
- the creation date, used by savedquery- Returns:
- This query as json.
-
toJson
public java.lang.String toJson(boolean onlyRelevant, java.util.Date date)
Convert this PathQuery to a JSON serialisation.- Parameters:
onlyRelevant
- whether to only return relevant, active constraints.date
- the creation date, used by savedquery- Returns:
- This query as json.
-
typeConstraintToJson
protected java.lang.String typeConstraintToJson(PathConstraint constraint)
format a type constraint to a JSON representation.- Parameters:
constraint
- the constraint to format.- Returns:
- The JSONification.
-
getCommonJsonConstraintPrefix
protected java.lang.String getCommonJsonConstraintPrefix(java.lang.String code, PathConstraint constraint)
Get the JSON prefix common to all constraints.- Parameters:
constraint
- the constraint to format.code
- The constraint code.- Returns:
- The prefix
-
valueConstraintToJson
protected java.lang.String valueConstraintToJson(java.lang.String code, PathConstraint constraint)
Format a value constraint to a JSON representation.- Parameters:
code
- The constraint code.constraint
- constraint.- Returns:
- The stringification.
-
constraintToJson
protected java.lang.String constraintToJson(PathConstraint constraint, java.lang.String code)
- Parameters:
constraint
- constraint to convertcode
- code for constraint, e.g. A- Returns:
- constraint in JSON format
-
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.
-
equals
public boolean equals(java.lang.Object other)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
-