bereng commented on code in PR #3095: URL: https://github.com/apache/cassandra/pull/3095#discussion_r1547755419
########## src/java/org/apache/cassandra/cql3/restrictions/ClusteringElements.java: ########## @@ -0,0 +1,449 @@ +/* + * 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.cassandra.cql3.restrictions; + +import java.nio.ByteBuffer; +import java.util.List; + +import com.google.common.collect.BoundType; +import com.google.common.collect.ForwardingList; +import com.google.common.collect.ImmutableList; +import com.google.common.collect.Range; +import com.google.common.collect.RangeSet; +import com.google.common.collect.TreeRangeSet; + +import org.apache.cassandra.cql3.ColumnSpecification; +import org.apache.cassandra.db.BufferClusteringBound; +import org.apache.cassandra.db.ClusteringBound; +import org.apache.cassandra.db.marshal.AbstractType; +import org.apache.cassandra.schema.ColumnMetadata; + +/** + * One or more contiguous clusterings elements. A clustering element is composed of a clustering column and its + * associated value. In practice, that class is not only used for clustering elements but also for partition key elements + * and tokens expression. + * + * <p>There are some difference between how predicates are represented in a CQL query and how they have to be expressed + * internally. Those differences are: + * <ul> + * <li>The selected partition keys and clustering columns can be expressed with separates predicates in a CQL query + * but need to be grouped internally to define exact partition and clustering keys. For example, + * <pre>[..] WHERE pk1 = 2 AND pk2 = 3 AND c1 = 5 AND c2 IN (3, 4)</pre> will request 2 rows with clustering (5, 3) and + * (5, 4) from the partition (2, 3).</li> + * <li>When clustering slices are expressed in a CQL query they are expressed as if all columns were in + * ascending order. Internally the engine handle slice according to the clustering columns real order. + * For example, if column c1 is descending and column c2 is ascending the predicate <pre>(c1, c2) >= (1, 2)</pre> + * should be translated internally in [(bottom) .. (1, bottom)),[(1, 2, bottom)..(1.top)].</li> + * </ul> + * This class is used to bridge the gap between the CQL expression and its internal representation. It allows for elements + * to be appended together through the {@code extend} method and translate CQL ranges into their internal representation. + * </p> + * <p>It is important to realize that Guava {@code Range} instances are used in a slightly different way than how they were + * designed to be use in order to deal with the tree model of Clusterings. {@code Range} returned by this class are never + * unbounded so the methods {@code hasLowerEndpoint} and {@code hasUpperEndpoint} should not be used on those. + * When a range does not have a lower endpoint its lower endpoint value will be (bottom) (e.g. ClusteringElements.of().bottom()) + * and if it does not have an upper endpoint its upper endpoint value will be (top) (e.g. ClusteringElements.of().top()). + * Therefore a missing endpoint will always return {@code true} to {@code isEmpty()}.</p> + */ +public class ClusteringElements extends ForwardingList<ByteBuffer> implements Comparable<ClusteringElements> +{ + /** + * The empty {@code ClusteringElements} instance used to avoid creating unecessary empty instances. + */ + private static final ClusteringElements EMPTY = new ClusteringElements(ImmutableList.of(), ImmutableList.of()); + + /** + * A range representing all {@code ClusteringElements}. + */ + private static final Range<ClusteringElements> ALL = Range.closed(EMPTY.bottom(), EMPTY.top()); + + /** + * The elements columns. + */ + // We use ColumnSpecification to allow support for things like Token expressions that do not match real columns directly. + private final ImmutableList<? extends ColumnSpecification> columns; + + /** + * The elements values. + */ + private final ImmutableList<ByteBuffer> values; + + private ClusteringElements(ImmutableList<? extends ColumnSpecification> columns, ImmutableList<ByteBuffer> values) + { + if (columns.size() != values.size()) + throw new IllegalArgumentException("columns and values should have the same size"); + + checkColumns(columns); + + this.columns = columns; + this.values = values; + } + + private static void checkColumns(ImmutableList<? extends ColumnSpecification> columns) + { + if (columns.size() > 1) + { + // All the columns should be ColumnMetadata for partition key or clustering key + int offset = ((ColumnMetadata) columns.get(0)).position(); + for (int i = 1, m = columns.size(); i < m; i++) + { + if (((ColumnMetadata) columns.get(i)).position() != (offset + i)) + throw new IllegalArgumentException("columns should have increasing position"); + } + } + } + + private AbstractType<?> type(int index) + { + return columns.get(index).type; + } + + @Override + protected List<ByteBuffer> delegate() + { + return values; + } + + /** + * Returns an empty {@code ClusteringElements}. + * @return an empty {@code ClusteringElements}. + */ + public static ClusteringElements of() + { + return EMPTY; + } + + /** + * Returns a {@code ClusteringElements} with a single element. + * @param column the element column + * @param value the element value + * @return a {@code ClusteringElements} with a single element. + */ + public static ClusteringElements of(ColumnSpecification column, ByteBuffer value) + { + return new ClusteringElements(ImmutableList.of(column), ImmutableList.of(value)); + } + + /** + * Returns a {@code ClusteringElements} with the specified elements. + * @param columns the elements columns + * @param values the elements values + * @return a {@code ClusteringElements} with the specified elements. + */ + public static ClusteringElements of(List<? extends ColumnSpecification> columns, List<ByteBuffer> values) + { + return new ClusteringElements(ImmutableList.copyOf(columns), ImmutableList.copyOf(values)); + } + + /** + * Extends this set of elements with the specified ones. This method should only be called on {@code ClusteringElements} + * corresponding to partition key or clustering elements. + * @param suffix the elements to append to this ones + * @return A new {@code ClusteringElements} instance composed of both set of elements + */ + public ClusteringElements extend(ClusteringElements suffix) + { + // We cannot extend a Top or Bottom has those are only use for ranges and ranges endpoint should not be extended + if (this instanceof Top || this instanceof Bottom) + throw new UnsupportedOperationException("Range endpoints cannot be extended"); + + checkSuffix(suffix); + + ImmutableList<? extends ColumnSpecification> newColumns = concat(columns, suffix.columns); + ImmutableList<ByteBuffer> newValues = concat(values, suffix.values); + + return suffix instanceof Top ? new Top(newColumns, newValues) + : suffix instanceof Bottom ? new Bottom(newColumns, newValues) + : new ClusteringElements(newColumns, newValues); + } + + private void checkSuffix(ClusteringElements suffix) + { + // If the columns are not ColumnMetadata instances we are dealing a Token representation which cannot be extended + if (!(columns.get(0) instanceof ColumnMetadata)) + throw new UnsupportedOperationException("Non partition key or clustering columns cannot be extended"); + + if (!suffix.isEmpty()) // suffix can be empty if equal to (top) or (bottom) + { + ColumnMetadata lastPrefixElement = ((ColumnMetadata) last(this.columns)); + ColumnMetadata firstSuffixElement = ((ColumnMetadata) suffix.columns.get(0)); + if (firstSuffixElement.kind != lastPrefixElement.kind) + throw new UnsupportedOperationException("Cannot extends elements with elements of a different kind"); + if (firstSuffixElement.position() != lastPrefixElement.position() + 1) + throw new UnsupportedOperationException("Cannot extends elements with not consecutive elements"); + } + } + + private static <T> ImmutableList<T> concat(ImmutableList<? extends T> prefix, ImmutableList<? extends T> suffix) + { + return ImmutableList.<T>builderWithExpectedSize(prefix.size() + suffix.size()) + .addAll(prefix) + .addAll(suffix) + .build(); + } + + /** + * Returns a {@code RangeSet} representing all the possible {@code ClusteringElements} values. + * @return a {@code RangeSet} representing all the possible {@code ClusteringElements} values. + */ + public static RangeSet<ClusteringElements> all() + { + TreeRangeSet<ClusteringElements> rangeSet = TreeRangeSet.create(); + rangeSet.add(ALL); + return rangeSet; + } + + /** + * Returns a {@code RangeSet} that contains all values less than or equal to endpoint. + * @return a {@code RangeSet} that contains all values less than or equal to endpoint. + */ + public static RangeSet<ClusteringElements> atMost(ClusteringElements endpoint) Review Comment: Why not name these 'lessThanOrEquals'? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
