001/*
002 *   Copyright 2024 Vonage
003 *
004 *   Licensed under the Apache License, Version 2.0 (the "License");
005 *   you may not use this file except in compliance with the License.
006 *   You may obtain a copy of the License at
007 *
008 *        http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *   Unless required by applicable law or agreed to in writing, software
011 *   distributed under the License is distributed on an "AS IS" BASIS,
012 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *   See the License for the specific language governing permissions and
014 *   limitations under the License.
015 */
016package com.vonage.client.numbers;
017
018import java.util.Arrays;
019import java.util.Map;
020import java.util.stream.Collectors;
021
022/**
023 * This class encapsulates a request to search for available Vonage Virtual Numbers.
024 */
025public class SearchNumbersFilter extends BaseNumbersFilter {
026    private Feature[] features;
027    private Type type;
028
029    private SearchNumbersFilter(Builder builder) {
030        super(builder);
031        features = builder.features;
032        type = builder.type;
033    }
034
035    /**
036     * Construct a request with the only required parameter, the country code.
037     *
038     * @param country A String containing a two-character country code.
039     * @deprecated Use {@link #builder()}. This will be removed in the next major release.
040     */
041    @Deprecated
042    public SearchNumbersFilter(String country) {
043        this(builder().country(country));
044    }
045
046    @Deprecated
047    public void setFeatures(String[] features) {
048        this.features = Feature.setFromString(features);
049    }
050
051    @Deprecated
052    public void setType(Type type) {
053        this.type = type;
054    }
055
056    /**
057     * Desired capabilities as an array of strings. In a future release, these will be enums.
058     *
059     * @return The capabilities to search for as a string array, or {@code null} if unspecified.
060     */
061    public String[] getFeatures() {
062        return Feature.getToString(features);
063    }
064
065    /**
066     * Type of number to search for.
067     *
068     * @return The number type as an enum, or {@code null} if unspecified.
069     */
070    public Type getType() {
071        return type;
072    }
073
074    @Override
075    public Map<String, String> makeParams() {
076        Map<String, String> params = super.makeParams();
077        if (features != null && features.length > 0) {
078            params.put("features", Arrays.stream(features).map(Feature::toString).collect(Collectors.joining(",")));
079        }
080        if (type != null) {
081            params.put("type", type.toString());
082        }
083        return params;
084    }
085
086    /**
087     * Entrypoint for constructing an instance of this class.
088     *
089     * @return A new Builder.
090     * @since 8.10.0
091     */
092    public static Builder builder() {
093        return new Builder();
094    }
095
096    /**
097     * Builder for setting the parameters of SearchNumbersFilter.
098     *
099     * @since 8.10.0
100     */
101    public static final class Builder extends BaseNumbersFilter.Builder<SearchNumbersFilter, Builder> {
102        private Feature[] features;
103        private Type type;
104
105        private Builder() {}
106
107        /**
108         * Set this parameter to find numbers that have one or more features.
109         *
110         * @param features The desired features of the number as enums.
111         * @return This builder.
112         */
113        public Builder features(Feature... features) {
114            if (features != null) {
115                this.features = Arrays.stream(features).distinct().toArray(Feature[]::new);
116            }
117            return this;
118        }
119
120        /**
121         * Set this parameter to filter the type of number, such as mobile or landline.
122         *
123         * @param type The type of number as an enum.
124         * @return This builder.
125         */
126        public Builder type(Type type) {
127            this.type = type;
128            return this;
129        }
130
131        @Override
132        public SearchNumbersFilter build() {
133            return new SearchNumbersFilter(this);
134        }
135    }
136}