001/*
002 *   Copyright 2020 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.insight;
017
018public class AdvancedInsightRequest extends BaseInsightRequest {
019    private boolean async;
020    private String callback;
021
022    private AdvancedInsightRequest(Builder builder) {
023        this.number = builder.number;
024        this.country = builder.country;
025        this.cnam = builder.cnam;
026        this.ipAddress = builder.ipAddress;
027        this.async = builder.async;
028        this.callback = builder.callback;
029    }
030
031    public static Builder builder(String number) {
032        return new Builder(number);
033    }
034
035    public Boolean getCnam() {
036        return cnam;
037    }
038
039    public String getIpAddress() {
040        return ipAddress;
041    }
042
043    public boolean isAsync() {
044        return async;
045    }
046
047    public String getCallback() {
048        return callback;
049    }
050
051    /**
052     * Construct a AdvancedInsightRequest with a number.
053     *
054     * @param number A single phone number that you need insight about in national or international format.
055     *
056     * @return A new {@link AdvancedInsightRequest} object.
057     */
058    public static AdvancedInsightRequest withNumber(String number) {
059        return new Builder(number).build();
060    }
061
062    /**
063     * Construct a AdvancedInsightRequest with a number and country.
064     *
065     * @param number  A single phone number that you need insight about in national or international format.
066     * @param country If a number does not have a country code or it is uncertain, set the two-character country code.
067     *
068     * @return A new {@link AdvancedInsightRequest} object.
069     */
070    public static AdvancedInsightRequest withNumberAndCountry(String number, String country) {
071        return new Builder(number).country(country).build();
072    }
073
074    public static class Builder {
075        protected String number;
076        protected String country;
077        protected Boolean cnam;
078        protected String ipAddress;
079        protected boolean async;
080        protected String callback;
081
082        /**
083         * @param number A single phone number that you need insight about in national or international format.
084         */
085        public Builder(String number) {
086            this.number = number;
087        }
088
089        /**
090         * @param number A single phone number that you need insight about in national or international format.
091         *
092         * @return The {@link Builder} to keep building.
093         */
094        public Builder number(String number) {
095            this.number = number;
096            return this;
097        }
098
099        /**
100         * @param country If a number does not have a country code or it is uncertain, set the two-character country
101         *                code.
102         *
103         * @return The {@link Builder} to keep building.
104         */
105        public Builder country(String country) {
106            this.country = country;
107            return this;
108        }
109
110        /**
111         * @param cnam Indicates if the name of the person who owns the phone number should also be looked up and
112         *             returned. Set to true to receive phone number owner name in the response. This is only available
113         *             for US numbers and incurs an additional charge.
114         *
115         * @return The {@link Builder} to keep building.
116         */
117        public Builder cnam(Boolean cnam) {
118            this.cnam = cnam;
119            return this;
120        }
121
122        /**
123         * @param ipAddress The IP address of the user. If supplied, we will compare this to the country the user's
124         *                  phone is located in and return an error if it does not match.
125         *
126         * @return The {@link Builder} to keep building.
127         */
128        public Builder ipAddress(String ipAddress) {
129            this.ipAddress = ipAddress;
130            return this;
131        }
132
133        /**
134         * @param async True if the call should be done asynchronously. When setting this value to true, the {@link
135         *              Builder#callback(String)} parameter must also be set.
136         *
137         * @return The {@link Builder} to keep building.
138         */
139        public Builder async(boolean async) {
140            this.async = async;
141            return this;
142        }
143
144        /**
145         * @param url The URL that Vonage will send a request to when the insight lookup is finished.
146         *
147         * @return The {@link Builder} to keep building.
148         */
149        public Builder callback(String url) {
150            this.callback = url;
151            return this;
152        }
153
154        /**
155         * @return A new {@link AdvancedInsightRequest} object from the stored builder options.
156         */
157        public AdvancedInsightRequest build() {
158            if (this.async && (this.callback == null || this.callback.isEmpty())) {
159                throw new IllegalStateException("You must define a callback url when using asyncronous insights.");
160            }
161            return new AdvancedInsightRequest(this);
162        }
163    }
164}