Class 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 serialising
      void 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_VERSION
      java.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.
      • Methods inherited from class java.lang.Object

        finalize, getClass, 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. 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 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. 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 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> 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 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 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 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
      • 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 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
      • 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 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()
        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 key
        value - 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 convert
        code - 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 class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object