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.voice.ncco;
017
018import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
019import com.fasterxml.jackson.annotation.JsonInclude;
020import com.fasterxml.jackson.annotation.JsonProperty;
021import com.vonage.client.voice.MachineDetection;
022
023import java.util.Arrays;
024import java.util.Collection;
025
026/**
027 * An NCCO connect action that allows for the establishment of a connection to various {@link Endpoint}.
028 */
029@JsonInclude(value = JsonInclude.Include.NON_NULL)
030@JsonIgnoreProperties(ignoreUnknown = true)
031public class ConnectAction implements Action {
032    private static final String ACTION = "connect";
033
034    private Collection<Endpoint> endpoint;
035    private String from;
036    private EventType eventType;
037    private Integer timeOut;
038    private Integer limit;
039    private MachineDetection machineDetection;
040    private Collection<String> eventUrl;
041    private EventMethod eventMethod;
042
043    private ConnectAction(Builder builder) {
044        this.endpoint = builder.endpoint;
045        this.from = builder.from;
046        this.eventType = builder.eventType;
047        this.timeOut = builder.timeOut;
048        this.limit = builder.limit;
049        this.machineDetection = builder.machineDetection;
050        this.eventUrl = builder.eventUrl;
051        this.eventMethod = builder.eventMethod;
052    }
053
054    @Override
055    public String getAction() {
056        return ACTION;
057    }
058
059    public Collection<Endpoint> getEndpoint() {
060        return endpoint;
061    }
062
063    public String getFrom() {
064        return from;
065    }
066
067    public EventType getEventType() {
068        return eventType;
069    }
070
071    @JsonProperty("timeout")
072    public Integer getTimeOut() {
073        return timeOut;
074    }
075
076    public Integer getLimit() {
077        return limit;
078    }
079
080    public MachineDetection getMachineDetection() {
081        return machineDetection;
082    }
083
084    public Collection<String> getEventUrl() {
085        return eventUrl;
086    }
087
088    public EventMethod getEventMethod() {
089        return eventMethod;
090    }
091
092    public static Builder builder(Collection<Endpoint> endpoint) {
093        return new Builder(endpoint);
094    }
095
096    public static Builder builder(Endpoint... endpoint) {
097        return new Builder(endpoint);
098    }
099
100    public static class Builder {
101        private Collection<Endpoint> endpoint;
102        private String from = null;
103        private EventType eventType = null;
104        private Integer timeOut = null;
105        private Integer limit = null;
106        private MachineDetection machineDetection = null;
107        private Collection<String> eventUrl = null;
108        private EventMethod eventMethod = null;
109
110        /**
111         * @param endpoint Connect the call to a specific #{@link Endpoint}.
112         */
113        public Builder(Collection<Endpoint> endpoint) {
114            this.endpoint = endpoint;
115        }
116
117        /**
118         * @param endpoint Connect the call to a specific #{@link Endpoint}.
119         */
120        public Builder(Endpoint... endpoint) {
121            this(Arrays.asList(endpoint));
122        }
123
124        /**
125         * @param endpoint Connect the call to a specific #{@link Endpoint}.
126         *
127         * @return The {@link Builder} to keep building.
128         */
129        public Builder endpoint(Collection<Endpoint> endpoint) {
130            this.endpoint = endpoint;
131            return this;
132        }
133
134        /**
135         * @param endpoint Connect the call to a specific #{@link Endpoint}.
136         *
137         * @return The {@link Builder} to keep building.
138         */
139        public Builder endpoint(Endpoint... endpoint) {
140            return endpoint(Arrays.asList(endpoint));
141        }
142
143        /**
144         * @param from A number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format that identifies the caller.
145         *             <p>
146         *             This must be one of your Vonage virtual numbers, another value will result in the caller ID being unknown.
147         *
148         * @return The {@link Builder} to keep building.
149         */
150        public Builder from(String from) {
151            this.from = from;
152            return this;
153        }
154
155        /**
156         * @param eventType Set to {@link EventType#SYNCHRONOUS} to:
157         *                  <ul>
158         *                  <li>Make the connect action synchronous.
159         *                  <li>Enable eventUrl to return an NCCO that overrides the current NCCO when a call moves to
160         *                  specific states.
161         *                  </ul>
162         *                  <p>
163         *                  See the <a href="https://developer.nexmo.com/voice/voice-api/ncco-reference#connect-with-fallback-ncco">Connect with fallback NCCO example.</a>
164         *
165         * @return The {@link Builder} to keep building.
166         */
167        public Builder eventType(EventType eventType) {
168            this.eventType = eventType;
169            return this;
170        }
171
172        /**
173         * @param timeOut If the call is unanswered, set the number in seconds before Vonage stops ringing endpoint.
174         *                The default value is 60.
175         *
176         * @return The {@link Builder} to keep building.
177         */
178        public Builder timeOut(Integer timeOut) {
179            this.timeOut = timeOut;
180            return this;
181        }
182
183        /**
184         * @param limit Maximum length of the call in seconds. The default and maximum value is 7200 seconds (2 hours).
185         *
186         * @return The {@link Builder} to keep building.
187         */
188        public Builder limit(Integer limit) {
189            this.limit = limit;
190            return this;
191        }
192
193        /**
194         * @param machineDetection Configure the behavior when Vonage detects that a destination is an answerphone.
195         *                         <p>
196         *                         Set to either:
197         *                         <ul>
198         *                         <li> {@link MachineDetection#CONTINUE} Vonage sends an HTTP request to event_url with the Call event machine
199         *                         <li> {@link MachineDetection#HANGUP} to end the Call
200         *                         </ul>
201         *
202         * @return The {@link Builder} to keep building.
203         */
204        public Builder machineDetection(MachineDetection machineDetection) {
205            this.machineDetection = machineDetection;
206            return this;
207        }
208
209        /**
210         * @param eventUrl Set the webhook endpoint that Vonage calls asynchronously on each of the possible <a href="https://developer.nexmo.com/voice/voice-api/guides/call-flow#call-states">Call States</a>.
211         *                 If eventType is set to synchronous the eventUrl can return an NCCO that overrides the current
212         *                 NCCO when a timeout occurs.
213         *
214         * @return The {@link Builder} to keep building.
215         */
216        public Builder eventUrl(Collection<String> eventUrl) {
217            this.eventUrl = eventUrl;
218            return this;
219        }
220
221        /**
222         * @param eventUrl Set the webhook endpoint that Vonage calls asynchronously on each of the possible <a href="https://developer.nexmo.com/voice/voice-api/guides/call-flow#call-states">Call States</a>.
223         *                 If eventType is set to synchronous the eventUrl can return an NCCO that overrides the current
224         *                 NCCO when a timeout occurs.
225         *
226         * @return The {@link Builder} to keep building.
227         */
228        public Builder eventUrl(String... eventUrl) {
229            return eventUrl(Arrays.asList(eventUrl));
230        }
231
232        /**
233         * @param eventMethod The HTTP method Vonage uses to make the request to eventUrl. The default value is POST.
234         *
235         * @return The {@link Builder} to keep building.
236         */
237        public Builder eventMethod(EventMethod eventMethod) {
238            this.eventMethod = eventMethod;
239            return this;
240        }
241
242        /**
243         * @return A new {@link ConnectAction} object from the stored builder options.
244         */
245        public ConnectAction build() {
246            return new ConnectAction(this);
247        }
248    }
249}