| /* |
| * 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.druid.query; |
| |
| import org.apache.druid.collections.bitmap.BitmapFactory; |
| import org.apache.druid.collections.bitmap.ImmutableBitmap; |
| |
| /** |
| * BitmapResultFactory is an abstraction that allows to record something along with preFilter bitmap construction, and |
| * emit this information as dimension(s) of query metrics. BitmapResultFactory is similar to {@link BitmapFactory}: it |
| * has the same methods with the exception that it accepts generic type T (bitmap wrapper type) instead of {@link |
| * ImmutableBitmap}. |
| * |
| * {@link DefaultBitmapResultFactory} is a no-op implementation, where "wrapper" type is {@code ImmutableBitmap} itself. |
| * |
| * BitmapResultFactory delegates actual operations on bitmaps to a {@code BitmapFactory}, which it accepts in |
| * constructor, called from {@link QueryMetrics#makeBitmapResultFactory(BitmapFactory)}. |
| * |
| * Emitting of query metric dimension(s) should be done from {@link #toImmutableBitmap(Object)}, the "unwrapping" |
| * method, called only once to obtain the final preFilter bitmap. |
| * |
| * Implementors expectations |
| * ------------------------- |
| * BitmapResultFactory is a part of the {@link QueryMetrics} subsystem, so this interface could be changed often, in |
| * every Druid release (including "patch" releases). Users who create their custom implementations of |
| * BitmapResultFactory should be ready to fix the code of their code to accommodate interface changes (e. g. implement |
| * new methods) when they update Druid. See {@link QueryMetrics} Javadoc for more info. |
| * |
| * @param <T> the bitmap result (wrapper) type |
| * @see QueryMetrics#makeBitmapResultFactory(BitmapFactory) |
| * @see QueryMetrics#reportBitmapConstructionTime(long) |
| */ |
| public interface BitmapResultFactory<T> |
| { |
| /** |
| * Wraps a bitmap which designates rows in a segment with some specific dimension value. |
| */ |
| T wrapDimensionValue(ImmutableBitmap bitmap); |
| |
| /** |
| * Wraps a bitmap which is a result of {@link BitmapFactory#makeEmptyImmutableBitmap()} call. |
| */ |
| T wrapAllFalse(ImmutableBitmap allFalseBitmap); |
| |
| /** |
| * Wraps a bitmap which is a result of {@link BitmapFactory#complement(ImmutableBitmap, int)} called with |
| * {@link BitmapFactory#makeEmptyImmutableBitmap()} as argument. |
| */ |
| T wrapAllTrue(ImmutableBitmap allTrueBitmap); |
| |
| /** |
| * Checks that the wrapped bitmap is empty, see {@link ImmutableBitmap#isEmpty()}. |
| */ |
| boolean isEmpty(T bitmapResult); |
| |
| /** |
| * Delegates to {@link BitmapFactory#intersection(Iterable)} on the wrapped bitmaps, and returns a bitmap result |
| * wrapping the resulting intersection ImmutableBitmap. |
| */ |
| T intersection(Iterable<T> bitmapResults); |
| |
| /** |
| * Delegates to {@link BitmapFactory#union(Iterable)} on the wrapped bitmaps, and returns a bitmap result wrapping |
| * the resulting union ImmutableBitmap. |
| */ |
| T union(Iterable<T> bitmapResults); |
| |
| /** |
| * Equivalent of intersection(Iterables.transform(dimensionValueBitmaps, factory::wrapDimensionValue)), but doesn't |
| * create a lot of bitmap result objects. |
| */ |
| T unionDimensionValueBitmaps(Iterable<ImmutableBitmap> dimensionValueBitmaps); |
| |
| /** |
| * Delegates to {@link BitmapFactory#complement(ImmutableBitmap, int)} on the wrapped bitmap, and returns a bitmap |
| * result wrapping the resulting complement ImmutableBitmap. |
| */ |
| T complement(T bitmapResult, int numRows); |
| |
| /** |
| * Unwraps bitmapResult back to ImmutableBitmap. BitmapResultFactory should emit query metric dimension(s) in the |
| * implementation of this method. |
| */ |
| ImmutableBitmap toImmutableBitmap(T bitmapResult); |
| } |