com.aerospike.vector.client.Projection Maven / Gradle / Ivy

Go to download
package com.aerospike.vector.client;

import com.aerospike.vector.client.proto.ProjectionFilter;
import com.aerospike.vector.client.proto.ProjectionSpec;
import com.aerospike.vector.client.proto.ProjectionType;
import java.util.Collection;

/**
 * This class represents a projection specification used to define which fields to include or
 * exclude in a query result. It supports building custom inclusion and exclusion filters using its
 * nested Builder class.
 */
public class Projection {
    // Projected fields to include
    private final ProjectionFilter include;

    // Projected fields to exclude
    private final ProjectionFilter exclude;

    // include all the vector fields
    public static final Projection DEFAULT = new Builder().withIncludeAll().build();

    /**
     * Constructs a Projection instance with specified inclusion and exclusion filters.
     *
     * @param include the filter specifying fields to include
     * @param exclude the filter specifying fields to exclude
     */
    private Projection(ProjectionFilter include, ProjectionFilter exclude) {
        this.include = include;
        this.exclude = exclude;
    }

    /**
     * Returns the default Projection instance with all fields included and none excluded.
     *
     * @return the default Projection instance
     */
    public static Projection getDefault() {
        return DEFAULT;
    }

    /**
     * Returns the inclusion filter of this Projection.
     *
     * @return the inclusion filter
     */
    public ProjectionFilter getInclude() {
        return include;
    }

    /**
     * Returns the exclusion filter of this Projection.
     *
     * @return the exclusion filter
     */
    public ProjectionFilter getExclude() {
        return exclude;
    }

    /**
     * Builder class for constructing Projection instances with specific inclusion and exclusion
     * filters.
     */
    public static class Builder {
        private static final ProjectionFilter ALL_FILTER =
                ProjectionFilter.newBuilder().setType(ProjectionType.ALL).build();
        private static final ProjectionFilter NONE_FILTER =
                ProjectionFilter.newBuilder().setType(ProjectionType.NONE).build();

        private ProjectionFilter include = ALL_FILTER;
        private ProjectionFilter exclude = NONE_FILTER;

        /**
         * Sets the inclusion filter to include all fields.
         *
         * @return this Builder instance for chaining
         */
        public Builder withIncludeAll() {
            this.include = ALL_FILTER;
            return this;
        }

        /**
         * Sets the inclusion filter to include specified fields.
         *
         * @param field the first field to include
         * @param fields additional fields to include
         * @return this Builder instance for chaining
         */
        public Builder withIncludeSpecified(String field, String... fields) {
            ProjectionFilter.Builder filterBuilder =
                    ProjectionFilter.newBuilder()
                            .setType(ProjectionType.SPECIFIED)
                            .addFields(field);
            for (String f : fields) {
                filterBuilder.addFields(f);
            }
            this.include = filterBuilder.build();
            return this;
        }

        /**
         * Sets the inclusion filter to include a collection of specified fields.
         *
         * @param fields the collection of fields to include
         * @return this Builder instance for chaining
         */
        public Builder withIncludeSpecified(Collection fields) {
            this.include =
                    ProjectionFilter.newBuilder()
                            .setType(ProjectionType.SPECIFIED)
                            .addAllFields(fields)
                            .build();
            return this;
        }

        /**
         * Sets the exclusion filter to exclude specified fields.
         *
         * @param field the first field to exclude
         * @param fields additional fields to exclude
         * @return this Builder instance for chaining
         */
        public Builder withExcludeSpecified(String field, String... fields) {
            ProjectionFilter.Builder filterBuilder =
                    ProjectionFilter.newBuilder()
                            .setType(ProjectionType.SPECIFIED)
                            .addFields(field);
            for (String f : fields) {
                filterBuilder.addFields(f);
            }
            this.exclude = filterBuilder.build();
            return this;
        }

        /**
         * Sets the exclusion filter to exclude a collection of specified fields.
         *
         * @param fields the collection of fields to exclude
         * @return this Builder instance for chaining
         */
        public Builder withExcludeSpecified(Collection fields) {
            this.exclude =
                    ProjectionFilter.newBuilder()
                            .setType(ProjectionType.SPECIFIED)
                            .addAllFields(fields)
                            .build();
            return this;
        }

        /**
         * Sets the exclusion filter to exclude all fields.
         *
         * @return this Builder instance for chaining
         */
        public Builder withExcludeAll() {
            this.exclude = ALL_FILTER;
            return this;
        }

        /**
         * Builds and returns a new Projection instance based on the current settings of this
         * Builder.
         *
         * @return a new Projection instance
         */
        public Projection build() {
            return new Projection(this.include, this.exclude);
        }
    }

    /**
     * Converts this Projection instance into a protocol buffer ProjectionSpec.
     *
     * @return a ProjectionSpec protocol buffer object
     */
    public ProjectionSpec toProjectionSpec() {
        return ProjectionSpec.newBuilder().setExclude(exclude).setInclude(include).build();
    }
}