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.numbers;
023
024
025import com.nexmo.client.HttpWrapper;
026import com.nexmo.client.NexmoClientException;
027
028import java.io.IOException;
029
030/**
031 * A client for accessing the Nexmo API calls that manage phone numbers.
032 */
033public class NumbersClient {
034    private ListNumbersEndpoint listNumbers;
035    private SearchNumbersEndpoint searchNumbers;
036    private CancelNumberEndpoint cancelNumber;
037    private BuyNumberEndpoint buyNumber;
038    private UpdateNumberEndpoint updateNumber;
039
040    public NumbersClient(HttpWrapper httpWrapper) {
041        this.listNumbers = new ListNumbersEndpoint(httpWrapper);
042        this.searchNumbers = new SearchNumbersEndpoint(httpWrapper);
043        this.cancelNumber = new CancelNumberEndpoint(httpWrapper);
044        this.buyNumber = new BuyNumberEndpoint(httpWrapper);
045        this.updateNumber = new UpdateNumberEndpoint(httpWrapper);
046    }
047
048    /**
049     * Get the first page of phone numbers assigned to the authenticated account.
050     *
051     * @return A ListNumbersResponse containing the first 10 phone numbers
052     * @throws IOException          if an error occurs contacting the Nexmo API
053     * @throws NexmoClientException if an error is returned by the server.
054     */
055    public ListNumbersResponse listNumbers() throws IOException, NexmoClientException {
056        return this.listNumbers.listNumbers(new ListNumbersFilter());
057    }
058
059    /**
060     * Get a filtered set of numbers assigned to the authenticated account.
061     *
062     * @param filter A ListNumbersFilter describing the filters to be applied to the request.
063     * @return A ListNumbersResponse containing phone numbers matching the supplied filter.
064     * @throws IOException          if an error occurs contacting the Nexmo API
065     * @throws NexmoClientException if an error is returned by the server.
066     */
067    public ListNumbersResponse listNumbers(ListNumbersFilter filter) throws IOException, NexmoClientException {
068        return this.listNumbers.listNumbers(filter);
069    }
070
071
072    /**
073     * Search for available Nexmo Virtual Numbers.
074     *
075     * @throws IOException          if an error occurs contacting the Nexmo API
076     * @throws NexmoClientException if an error is returned by the server.
077     */
078    public SearchNumbersResponse searchNumbers(String country) throws IOException, NexmoClientException {
079        return this.searchNumbers(new SearchNumbersFilter(country));
080    }
081
082    /**
083     * Search for available Nexmo Virtual Numbers.
084     *
085     * @throws IOException          if an error occurs contacting the Nexmo API
086     * @throws NexmoClientException if an error is returned by the server.
087     */
088    public SearchNumbersResponse searchNumbers(SearchNumbersFilter filter) throws IOException, NexmoClientException {
089        return this.searchNumbers.searchNumbers(filter);
090    }
091
092    /**
093     * Start renting a Nexmo Virtual Number.
094     *
095     * @param country A String containing a 2-character ISO country code.
096     * @param msisdn  The phone number to be bought.
097     * @throws IOException          if an error occurs contacting the Nexmo API
098     * @throws NexmoClientException if an error is returned by the server.
099     */
100    public void buyNumber(String country, String msisdn) throws IOException, NexmoClientException {
101        this.buyNumber.execute(new BuyNumberRequest(country, msisdn));
102    }
103
104    /**
105     * Stop renting a Nexmo Virtual Number.
106     *
107     * @param country A String containing a 2-character ISO country code.
108     * @param msisdn  The phone number to be cancelled.
109     * @throws IOException          if an error occurs contacting the Nexmo API
110     * @throws NexmoClientException if an error is returned by the server.
111     */
112    public void cancelNumber(String country, String msisdn) throws IOException, NexmoClientException {
113        CancelNumberResponse response = this.cancelNumber.execute(new CancelNumberRequest(country, msisdn));
114    }
115
116    /**
117     * Update the callbacks and/or application associations for a given Nexmo Virtual Number.
118     *
119     * @param request Details of the updates to be made to the number association.
120     * @throws IOException          if an error occurs contacting the Nexmo API
121     * @throws NexmoClientException if an error is returned by the server.
122     */
123    public void updateNumber(UpdateNumberRequest request) throws IOException, NexmoClientException {
124        this.updateNumber.execute(request);
125    }
126
127    /**
128     * Link a given Nexmo Virtual Number to a Nexmo Application with the given ID.
129     *
130     * @param msisdn  The Nexmo Virtual Number to be updated.
131     * @param country The country for the given msisdn.
132     * @param appId   The ID for the Nexmo Application to be associated with the number.
133     * @throws IOException          if an error occurs contacting the Nexmo API
134     * @throws NexmoClientException if an error is returned by the server.
135     */
136    public void linkNumber(String msisdn, String country, String appId) throws IOException, NexmoClientException {
137        UpdateNumberRequest request = new UpdateNumberRequest(msisdn, country);
138        request.setVoiceCallbackType(UpdateNumberRequest.CallbackType.APP);
139        request.setVoiceCallbackValue(appId);
140        this.updateNumber(request);
141    }
142}