Java tutorial
/***************************************************************** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. ****************************************************************/ package org.apache.cayenne.query; import org.apache.cayenne.exp.Expression; import org.apache.cayenne.exp.ExpressionException; import org.apache.cayenne.exp.parser.ASTDbPath; import org.apache.cayenne.exp.parser.ASTObjPath; import org.apache.cayenne.util.ConversionUtil; import org.apache.cayenne.util.Util; import org.apache.cayenne.util.XMLEncoder; import org.apache.cayenne.util.XMLSerializable; import org.apache.commons.collections.ComparatorUtils; import java.io.PrintWriter; import java.io.Serializable; import java.io.StringWriter; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.Comparator; import java.util.List; /** * Defines object sorting criteria, used either for in-memory sorting of object * lists or as a specification for building <em>ORDER BY</em> clause of a * SelectQuery query. Note that in case of in-memory sorting, Ordering can be * used with any JavaBeans, not just DataObjects. */ public class Ordering implements Comparator<Object>, Serializable, XMLSerializable { private static final long serialVersionUID = -9167074787055881422L; protected String sortSpecString; protected transient Expression sortSpec; protected SortOrder sortOrder; protected boolean pathExceptionSuppressed = false; protected boolean nullSortedFirst = true; /** * Orders a given list of objects, using a List of Orderings applied * according the default iteration order of the Orderings list. I.e. each * Ordering with lower index is more significant than any other Ordering * with higher index. List being ordered is modified in place. * * @param objects elements to sort * @param orderings list of Orderings to be applied */ @SuppressWarnings("unchecked") public static void orderList(List<?> objects, List<? extends Ordering> orderings) { Collections.sort(objects, ComparatorUtils.chainedComparator(orderings)); } /** * Orders a given list of objects, using a List of Orderings applied * according the default iteration order of the Orderings list. I.e. each * Ordering with lower index is more significant than any other Ordering * with higher index. * * @param objects elements to sort * @param orderings list of Orderings to be applied * @return new List with ordered elements * * @since 4.0 */ public static <E> List<E> orderedList(final Collection<E> objects, List<? extends Ordering> orderings) { List<E> newList = new ArrayList<>(objects); orderList(newList, orderings); return newList; } public Ordering() { } /** * Create an ordering instance with a provided path and ascending sorting * strategy. * * @since 4.0 */ public Ordering(String sortPathSpec) { this(sortPathSpec, SortOrder.ASCENDING); } /** * @since 3.0 */ public Ordering(String sortPathSpec, SortOrder sortOrder) { setSortSpecString(sortPathSpec); setSortOrder(sortOrder); } /** * @since 4.0 */ public Ordering(Expression sortSpec) { this(sortSpec, SortOrder.ASCENDING); } /** * @since 4.0 */ public Ordering(Expression sortSpec, SortOrder sortOrder) { setSortSpec(sortSpec); setSortOrder(sortOrder); } @Override public boolean equals(Object object) { if (this == object) { return true; } if (!(object instanceof Ordering)) { return false; } Ordering o = (Ordering) object; if (!Util.nullSafeEquals(sortSpecString, o.sortSpecString)) { return false; } if (sortOrder != o.sortOrder) { return false; } if (pathExceptionSuppressed != o.pathExceptionSuppressed) { return false; } if (nullSortedFirst != o.nullSortedFirst) { return false; } return true; } @Override public int hashCode() { int result = sortSpecString != null ? sortSpecString.hashCode() : 0; result = 31 * result + (sortOrder != null ? sortOrder.hashCode() : 0); result = 31 * result + (pathExceptionSuppressed ? 1 : 0); result = 31 * result + (nullSortedFirst ? 1 : 0); return result; } /** * Sets sortSpec to be an expression represented by string argument. * * @since 1.1 */ public void setSortSpecString(String sortSpecString) { if (!Util.nullSafeEquals(this.sortSpecString, sortSpecString)) { this.sortSpecString = sortSpecString; this.sortSpec = null; } } /** * Sets sort order for whether nulls are at the top or bottom of the * resulting list. Default is true. * Affects only in-memory sorting. * * @param nullSortedFirst * true sorts nulls to the top of the list, false sorts nulls to * the bottom */ public void setNullSortedFirst(boolean nullSortedFirst) { this.nullSortedFirst = nullSortedFirst; } /** * Get sort order for nulls. * * @return true if nulls are sorted to the top of the list, false if sorted * to the bottom */ public boolean isNullSortedFirst() { return nullSortedFirst; } /** * Sets whether a path with a null in the middle is ignored. For example, a * sort from <code>painting</code> on <code>artist.name</code> would by * default throw an exception if the artist was null. If set to true, then * this is treated just like a null value. Default is false. * * @param pathExceptionSuppressed * true to suppress exceptions and sort as null */ public void setPathExceptionSupressed(boolean pathExceptionSuppressed) { this.pathExceptionSuppressed = pathExceptionSuppressed; } /** * Is a path with a null in the middle is ignored. * * @return true is exception is suppressed and sorted as null */ public boolean isPathExceptionSuppressed() { return pathExceptionSuppressed; } /** * Returns sortSpec string representation. * * @since 1.1 */ public String getSortSpecString() { return sortSpecString; } /** * Sets the sort order for this ordering. * * @since 3.0 */ public void setSortOrder(SortOrder order) { this.sortOrder = order; } /** Returns true if sorting is done in ascending order. */ public boolean isAscending() { return sortOrder == null || sortOrder == SortOrder.ASCENDING || sortOrder == SortOrder.ASCENDING_INSENSITIVE; } /** * Returns true if the sorting is done in descending order. * * @since 3.0 */ public boolean isDescending() { return !isAscending(); } /** * If the sort order is DESCENDING or DESCENDING_INSENSITIVE, sets the sort * order to ASCENDING or ASCENDING_INSENSITIVE, respectively. * * @since 3.0 */ public void setAscending() { if (sortOrder == null || sortOrder == SortOrder.DESCENDING) setSortOrder(SortOrder.ASCENDING); else if (sortOrder == SortOrder.DESCENDING_INSENSITIVE) setSortOrder(SortOrder.ASCENDING_INSENSITIVE); } /** * If the sort order is ASCENDING or ASCENDING_INSENSITIVE, sets the sort * order to DESCENDING or DESCENDING_INSENSITIVE, respectively. * * @since 3.0 */ public void setDescending() { if (sortOrder == null || sortOrder == SortOrder.ASCENDING) setSortOrder(SortOrder.DESCENDING); else if (sortOrder == SortOrder.ASCENDING_INSENSITIVE) setSortOrder(SortOrder.DESCENDING_INSENSITIVE); } /** Returns true if the sorting is case insensitive */ public boolean isCaseInsensitive() { return !isCaseSensitive(); } /** * Returns true if the sorting is case sensitive. * * @since 3.0 */ public boolean isCaseSensitive() { return sortOrder == null || sortOrder == SortOrder.ASCENDING || sortOrder == SortOrder.DESCENDING; } /** * If the sort order is ASCENDING or DESCENDING, sets the sort order to * ASCENDING_INSENSITIVE or DESCENDING_INSENSITIVE, respectively. * * @since 3.0 */ public void setCaseInsensitive() { if (sortOrder == null || sortOrder == SortOrder.ASCENDING) setSortOrder(SortOrder.ASCENDING_INSENSITIVE); else if (sortOrder == SortOrder.DESCENDING) setSortOrder(SortOrder.DESCENDING_INSENSITIVE); } /** * If the sort order is ASCENDING_INSENSITIVE or DESCENDING_INSENSITIVE, * sets the sort order to ASCENDING or DESCENDING, respectively. * * @since 3.0 */ public void setCaseSensitive() { if (sortOrder == null || sortOrder == SortOrder.ASCENDING_INSENSITIVE) setSortOrder(SortOrder.ASCENDING); else if (sortOrder == SortOrder.DESCENDING_INSENSITIVE) setSortOrder(SortOrder.DESCENDING); } /** * Returns the expression defining a ordering Java Bean property. */ public Expression getSortSpec() { if (sortSpecString == null) { return null; } // compile on demand .. since orderings can only be paths, avoid the // overhead of // Expression.fromString, and parse them manually if (sortSpec == null) { if (sortSpecString.startsWith(ASTDbPath.DB_PREFIX)) { sortSpec = new ASTDbPath(sortSpecString.substring(ASTDbPath.DB_PREFIX.length())); } else if (sortSpecString.startsWith(ASTObjPath.OBJ_PREFIX)) { sortSpec = new ASTObjPath(sortSpecString.substring(ASTObjPath.OBJ_PREFIX.length())); } else { sortSpec = new ASTObjPath(sortSpecString); } } return sortSpec; } /** * Sets the expression defining a ordering Java Bean property. */ public void setSortSpec(Expression sortSpec) { this.sortSpec = sortSpec; this.sortSpecString = (sortSpec != null) ? sortSpec.toString() : null; } /** * Orders the given list of objects according to the ordering that this * object specifies. List is modified in-place. * * @param objects * a List of objects to be sorted */ public void orderList(List<?> objects) { Collections.sort(objects, this); } /** * @since 4.0 */ public <E> List<E> orderedList(Collection<E> objects) { List<E> newList = new ArrayList<>(objects); orderList(newList); return newList; } /** * Comparable interface implementation. Can compare two Java Beans based on * the stored expression. */ @Override public int compare(Object o1, Object o2) { Expression exp = getSortSpec(); Object value1 = null; Object value2 = null; try { value1 = exp.evaluate(o1); } catch (ExpressionException e) { if (pathExceptionSuppressed && e.getCause() instanceof org.apache.cayenne.reflect.UnresolvablePathException) { // do nothing, we expect this } else { // re-throw throw e; } } try { value2 = exp.evaluate(o2); } catch (ExpressionException e) { if (pathExceptionSuppressed && e.getCause() instanceof org.apache.cayenne.reflect.UnresolvablePathException) { // do nothing, we expect this } else { // rethrow throw e; } } if (value1 == null && value2 == null) { return 0; } else if (value1 == null) { return nullSortedFirst ? -1 : 1; } else if (value2 == null) { return nullSortedFirst ? 1 : -1; } if (isCaseInsensitive()) { // TODO: to upper case should probably be defined as a separate // expression // type value1 = ConversionUtil.toUpperCase(value1); value2 = ConversionUtil.toUpperCase(value2); } int compareResult = ConversionUtil.toComparable(value1).compareTo(ConversionUtil.toComparable(value2)); return (isAscending()) ? compareResult : -compareResult; } /** * Encodes itself as a query ordering. * * @since 1.1 */ @Override public void encodeAsXML(XMLEncoder encoder) { encoder.print("<ordering"); if (isDescending()) { encoder.print(" descending=\"true\""); } if (isCaseInsensitive()) { encoder.print(" ignore-case=\"true\""); } encoder.print(">"); if (getSortSpec() != null) { getSortSpec().encodeAsXML(encoder); } encoder.println("</ordering>"); } @Override public String toString() { StringWriter buffer = new StringWriter(); PrintWriter pw = new PrintWriter(buffer); XMLEncoder encoder = new XMLEncoder(pw); encodeAsXML(encoder); pw.close(); buffer.flush(); return buffer.toString(); } /** * Returns sort order for this ordering * * @since 3.1 */ public SortOrder getSortOrder() { return sortOrder; } }