001/*
002 * Copyright (c) 2011-2017 Nexmo Inc
003 *
004 * Permission is hereby granted, free of charge, to any person obtaining a copy
005 * of this software and associated documentation files (the "Software"), to deal
006 * in the Software without restriction, including without limitation the rights
007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
008 * copies of the Software, and to permit persons to whom the Software is
009 * furnished to do so, subject to the following conditions:
010 *
011 * The above copyright notice and this permission notice shall be included in
012 * all copies or substantial portions of the Software.
013 *
014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
020 * THE SOFTWARE.
021 */
022package com.nexmo.client.voice.ncco;
023
024import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
025import com.fasterxml.jackson.annotation.JsonInclude;
026import com.fasterxml.jackson.annotation.JsonProperty;
027import com.nexmo.client.voice.MachineDetection;
028
029import java.util.Arrays;
030import java.util.Collection;
031
032/**
033 * An NCCO connect action that allows for the establishment of a connection to various {@link Endpoint}.
034 */
035@JsonInclude(value = JsonInclude.Include.NON_NULL)
036@JsonIgnoreProperties(ignoreUnknown = true)
037public class ConnectAction implements Action {
038    private static final String ACTION = "connect";
039
040    private Collection<Endpoint> endpoint;
041    private String from;
042    private EventType eventType;
043    private Integer timeOut;
044    private Integer limit;
045    private MachineDetection machineDetection;
046    private Collection<String> eventUrl;
047    private EventMethod eventMethod;
048
049    private ConnectAction(Builder builder) {
050        this.endpoint = builder.endpoint;
051        this.from = builder.from;
052        this.eventType = builder.eventType;
053        this.timeOut = builder.timeOut;
054        this.limit = builder.limit;
055        this.machineDetection = builder.machineDetection;
056        this.eventUrl = builder.eventUrl;
057        this.eventMethod = builder.eventMethod;
058    }
059
060    @Override
061    public String getAction() {
062        return ACTION;
063    }
064
065    public Collection<Endpoint> getEndpoint() {
066        return endpoint;
067    }
068
069    public String getFrom() {
070        return from;
071    }
072
073    public EventType getEventType() {
074        return eventType;
075    }
076
077    @JsonProperty("timeout")
078    public Integer getTimeOut() {
079        return timeOut;
080    }
081
082    public Integer getLimit() {
083        return limit;
084    }
085
086    public MachineDetection getMachineDetection() {
087        return machineDetection;
088    }
089
090    public Collection<String> getEventUrl() {
091        return eventUrl;
092    }
093
094    public EventMethod getEventMethod() {
095        return eventMethod;
096    }
097
098    public static Builder builder(Collection<Endpoint> endpoint) {
099        return new Builder(endpoint);
100    }
101
102    public static Builder builder(Endpoint... endpoint) {
103        return new Builder(endpoint);
104    }
105
106    public static class Builder {
107        private Collection<Endpoint> endpoint;
108        private String from = null;
109        private EventType eventType = null;
110        private Integer timeOut = null;
111        private Integer limit = null;
112        private MachineDetection machineDetection = null;
113        private Collection<String> eventUrl = null;
114        private EventMethod eventMethod = null;
115
116        /**
117         * @param endpoint Connect the call to a specific #{@link Endpoint}.
118         */
119        public Builder(Collection<Endpoint> endpoint) {
120            this.endpoint = endpoint;
121        }
122
123        /**
124         * @param endpoint Connect the call to a specific #{@link Endpoint}.
125         */
126        public Builder(Endpoint... endpoint) {
127            this(Arrays.asList(endpoint));
128        }
129
130        /**
131         * @param endpoint Connect the call to a specific #{@link Endpoint}.
132         *
133         * @return The {@link Builder} to keep building.
134         */
135        public Builder endpoint(Collection<Endpoint> endpoint) {
136            this.endpoint = endpoint;
137            return this;
138        }
139
140        /**
141         * @param endpoint Connect the call to a specific #{@link Endpoint}.
142         *
143         * @return The {@link Builder} to keep building.
144         */
145        public Builder endpoint(Endpoint... endpoint) {
146            return endpoint(Arrays.asList(endpoint));
147        }
148
149        /**
150         * @param from A number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format that identifies the caller.
151         *             <p>
152         *             This must be one of your Nexmo virtual numbers, another value will result in the caller ID being unknown.
153         *
154         * @return The {@link Builder} to keep building.
155         */
156        public Builder from(String from) {
157            this.from = from;
158            return this;
159        }
160
161        /**
162         * @param eventType Set to {@link EventType#SYNCHRONOUS} to:
163         *                  <ul>
164         *                  <li>Make the connect action synchronous.
165         *                  <li>Enable eventUrl to return an NCCO that overrides the current NCCO when a call moves to
166         *                  specific states.
167         *                  </ul>
168         *                  <p>
169         *                  See the <a href="https://developer.nexmo.com/voice/voice-api/ncco-reference#connect-with-fallback-ncco">Connect with fallback NCCO example.</a>
170         *
171         * @return The {@link Builder} to keep building.
172         */
173        public Builder eventType(EventType eventType) {
174            this.eventType = eventType;
175            return this;
176        }
177
178        /**
179         * @param timeOut If the call is unanswered, set the number in seconds before Nexmo stops ringing endpoint.
180         *                The default value is 60.
181         *
182         * @return The {@link Builder} to keep building.
183         */
184        public Builder timeOut(Integer timeOut) {
185            this.timeOut = timeOut;
186            return this;
187        }
188
189        /**
190         * @param limit Maximum length of the call in seconds. The default and maximum value is 7200 seconds (2 hours).
191         *
192         * @return The {@link Builder} to keep building.
193         */
194        public Builder limit(Integer limit) {
195            this.limit = limit;
196            return this;
197        }
198
199        /**
200         * @param machineDetection Configure the behavior when Nexmo detects that a destination is an answerphone.
201         *                         <p>
202         *                         Set to either:
203         *                         <ul>
204         *                         <li> {@link MachineDetection#CONTINUE} Nexmo sends an HTTP request to event_url with the Call event machine
205         *                         <li> {@link MachineDetection#HANGUP} to end the Call
206         *                         </ul>
207         *
208         * @return The {@link Builder} to keep building.
209         */
210        public Builder machineDetection(MachineDetection machineDetection) {
211            this.machineDetection = machineDetection;
212            return this;
213        }
214
215        /**
216         * @param eventUrl Set the webhook endpoint that Nexmo calls asynchronously on each of the possible <a href="https://developer.nexmo.com/voice/voice-api/guides/call-flow#call-states">Call States</a>.
217         *                 If eventType is set to synchronous the eventUrl can return an NCCO that overrides the current
218         *                 NCCO when a timeout occurs.
219         *
220         * @return The {@link Builder} to keep building.
221         */
222        public Builder eventUrl(Collection<String> eventUrl) {
223            this.eventUrl = eventUrl;
224            return this;
225        }
226
227        /**
228         * @param eventUrl Set the webhook endpoint that Nexmo calls asynchronously on each of the possible <a href="https://developer.nexmo.com/voice/voice-api/guides/call-flow#call-states">Call States</a>.
229         *                 If eventType is set to synchronous the eventUrl can return an NCCO that overrides the current
230         *                 NCCO when a timeout occurs.
231         *
232         * @return The {@link Builder} to keep building.
233         */
234        public Builder eventUrl(String... eventUrl) {
235            return eventUrl(Arrays.asList(eventUrl));
236        }
237
238        /**
239         * @param eventMethod The HTTP method Nexmo uses to make the request to eventUrl. The default value is POST.
240         *
241         * @return The {@link Builder} to keep building.
242         */
243        public Builder eventMethod(EventMethod eventMethod) {
244            this.eventMethod = eventMethod;
245            return this;
246        }
247
248        /**
249         * @return A new {@link ConnectAction} object from the stored builder options.
250         */
251        public ConnectAction build() {
252            return new ConnectAction(this);
253        }
254    }
255}