Java Web Service API Application Samples
The following Java samples illustrate how to use
Version 2.0 of the
Aculab Cloud Web Services API to
invoke your outbound services and to manage your media files on the cloud.
All of the samples are thin application wrappers around functionality that is provided in a Common class library.
This implements the web service requests and unwraps the JSON format responses.
Please note that in the interests of clarity these samples are short on the kind of
error handling and diagnostic aspects that would typically be required in a live
environment.
The Web Service API is documented
here.
They are included in the Java UAS download package and located in
<UAS install folder>\Samples\WSApplications.
Pre-built versions of all of these samples are provided in
<UAS install folder>\Samples\WSApplications\bin.
Each sample contains eclipse .project and .classpath files and an Ant build script file (build.xml).
All the samples depend on the common.jar library for which the source is also provided.
These samples are all console applications. Some require command line parameters to be supplied.
Those that do describe the expected parameters below each sample description.
Samples that are designed to invoke an outbound service require that service to be registered with the
cloud from
Outbound Services.
Invoke an Outbound Service
A command line console application that simply invokes an outbound service that is currently
registered on a cloud.
This application takes a number of command line options:
java -jar InvokeOutboundService.jar <cloudId> <cloudUsername>
<outboundService> <outboundServicePassword>
[<outboundParameters> [<count>]] | [outboundParametersFilename];
where:
- cloudId = cloud region id (e.g. 0-2-0)
- cloudUsername = cloud account username
- outboundService = the outbound service to invoke
- outboundServicePassword = the outbound service password
followed by either:
- outboundParameters = a single outbound parameters string that will be passed to the application
followed optionally by
- [count] = the number of invocations to make, all with the specified outboundParameters
or
- outboundParametersFilename = the name of a file containing 1 or more outboundParameter
strings, comma-separated
Note: outboundParameters, whether defined on the command line or in a file, must not
contain characters carriage return, line feed or ^. Also, parameters defined in a file are not
trimmed of leading and trailing spaces.
Note: a comma-separated file containing the application instance ids of the invoked services
is written when they have all completed ("appInstances.csv").
Note: multiple call invocations are only supported on standard production cloud
accounts or above.
e.g. java -jar InvokeOutboundService.jar 0-2-0 bob@acompany.com MyOutboundService 54321 sip:bill@bcompany.com 5
Invokes service MyOutboundService (with password 54321) 5 times
on cloud region 0-2-0 on account bob@acompany.com
and passes each invocation the outbound parameters: sip:bill@bcompany.com
e.g. java -jar InvokeOutboundService.jar 0-2-0 bob@acompany.com MyOutboundService 54321 outParams.csv
outParams.csv file contents:
sip:bill@bcompany.com,sip:ben@bcompany.com,sip:lw@bcompany.com
Invokes service MyOutboundService (with password 54321) three times
on cloud region 0-2-0 on account bob@acompany.com
and passes each invocation one of the sip addresses from the outParams.csv file.
Get an Application Instance Result
A command line console application to query the cloud for the result of a UAS application
instance, either inbound or outbound.
This application takes a number of command line options:
jav -jar GetApplicationInstanceResult.jar <cloudId> <cloudUsername:password>
<applicationInstanceId> | <applicationInstanceIdsFileName>
where:
- cloudId = cloud region id (e.g. 0-2-0)
- cloudUsername:password = cloud account username and password
followed by either
- applicationInstanceId = the unique id relating to a single invocation of an outbound or
inbound application (e.g. 01f92d482e33a4ce.375315)
or
- applicationInstanceIdsFileName = the name of a file containing 1 or more
application instance id strings, comma-separated
e.g. java -jar GetApplicationInstanceResult.jar 0-2-0 bob@acompany.com:bobsPword 01f92d482e33a4ce.375315
This retrieves the application result from cloud region 0-2-0 on account
bob@acompany.com:bobsPword for application instance 01f92d482e33a4ce.375315.
e.g. java -jar GetApplicationInstanceResult.jar 0-2-0 bob@acompany.com:bobsPword appInstances.csv
appInstance.csv file contents:
040880762e891fab.798,040880762e891fab.799,0408804b36f73ef5.809
This retrieves the application results from cloud region 0-2-0
on account bob@acompany.com:bobsPword
for all three application instances specified.
An applicationInstanceId can be obtained from a number of sources:
Note that there can be a delay of several seconds before the result data for a particular
application instance becomes available on the cloud.
Manage Large Conferences
A command line console application that manages reservations on a specified cloud region
for large conferences (see
Conferencing Capabilities)
using a specified account on that cloud.
Once the reservation has been made successfully, then, after the specified start time and
for the duration specified, calls may be made to the conferenceRoom e.g. using the AddToConference
UASApplication sample (specifying the conferenceRoom as a 4-digit pin).
This application takes a number of command line options:
java -jar ManageLargeConferences.jar <cloudId> <cloudUsername:password>
<command>
where:
- cloudId = cloud region id (e.g. 0-2-0)
- cloudUsername:password= cloud account username:password
- command= one of the following:
- reserve
- list
- remove
- extend
command arguments:
- reserve conferenceRoom numberOfParties [startTime [minutesDuration]]
where:
- conferenceRoom = a conference room name consisting of alphanumeric characters only and
must be unique on the chosen cloud
- numberOfParties = the maximum number of parties to reserve for this conference.
See Conferencing Capabilities for the allowable range.
- startTime = the earliest start time of the conference (UTC) expressed as yyyy-MM-dd_HH:mm.
(e.g. 2011-11-10_09:30 for 10th Nov 2011 09:30)
This must be at least 5 minutes and at most 24 hours away.
The conference can only be started after this time.
(default 20 mins from now)
- minutesDuration = the maximum duration of the conference in minutes
(default 20 mins, allowable range 15-480)
- list
takes no arguments...
- remove conferenceRoom
where:
- conferenceRoom = the name of the conference room to remove.
- extend conferenceRoom additionalMinutes
where:
- conferenceRoom = the name of the conference room to extend.
- additionalMinutes = the number of minutes by which to extend the conference.
(allowable range 15-60 minutes)
e.g. java -jar ReserveLargeConference.jar 0-2-0 bob@acompany.com:bobspword reserve MyLargeConf1 120 2013-11-10-09-30 20
reserves a 20 minute conference "MyLargeConf1" for 120 parties
for 09:30 on 10th Nov 2013
on cloud region 0-2-0 (account bob@acompany.com:bobspswd)
A command line console application that provides access to the media file
management facilities of the Aculab Cloud Web Services API.
This application takes a number of command line options:
java -jar ManageMediaFiles.jar <cloudId> <cloudUsername:password>
<command>
where:
- cloudId = cloud region id (e.g. 0-2-0)
- cloudUsername:password = cloud account username and password
- command = one of the following:
- upload localFilename cloudFilename
- download cloudFilename localFilename
- list localFilename [filespecPrefix]
- delete filespecPrefix
- rename cloudFilename newCloudFilename
filespecPrefix is an optional argument to the list command and a reqired argument to delete
that specifies a filename prefix and can accept a trailing '*' wildcard. This matches all files
with the filespec as a prefix. Note that this effectively means the command is applied recursively through all subfolders.
e.g.
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword upload c:/test/acuwelcome.wav /wavs/newacuwelcome.wav
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword download /wavs/newacuwelcome.wav c:/test/newacuwelcome.wav
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword list *
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword list /wavs/rec*
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword list /wavs/rec* 0 1000
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword list /wavs/rec* 1000 1000
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword delete *
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword delete /*
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword delete /rec*
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword rename /wavs/old/acuwelcome.wav /wavs/newacuwelcome.wav
Manage Reports
A command line console application that provides access to the report
management facilities of the Aculab Cloud Web Services API.
This application takes a number of command line options:
java -jar ManageReports.jar <cloudId> <cloudUsername:password>
<command>
where:
- cloudId = cloud region id (e.g. 0-2-0)
- cloudUsername:password = cloud account username and password
- command = one of the following:
- start content from [to]
- list listtype
- cancel reportname
- download reportname localfilename
- delete reportname
and:
- content = adr | cdr | err | cwp | full
- from/to = YYYY-MM-DD_HH:MM:SS
(to is optional and defaults to current time if omitted)
- listtype = inprogress | completed
- reportname = the name of the report to cancel, download or delete
- localfilename = path and filename for the downloaded file
Note: this sample requests reports in JSON format. The web service also supports
the CSV format, but that is not implemented in this sample.
e.g.
java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword start cdr 2012-06-28_00:00:00
java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword start cdr
2012-06-28_00:00:00 2012-06-29_00:00:00
java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword list inprogress
java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword list completed
java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword cancel
0-2-0_bob@acompany.com_cdr-adm_2012-06-28_00:00:00_2012-07-29_00:00:00.json
java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword download
0-2-0_bob@acompany.com_cdr-adm_2012-06-28_00:00:00_2012-07-29_00:00:00.json
.\myReport.json
java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword delete
0-2-0_bob@acompany.com_cdr-adm_2012-06-28_00:00:00_2012-07-29_00:00:00.json
Manage Telephone Numbers
A console application that provides access to the telephone number
management facilities of the Aculab Cloud Web Services API. It allows
one or more telephone numbers to be purchased and can be configured
to create corresponding inbound services for each new number based
on an existing service.
This application takes a number of command line options:
java -jar ManageTelephoneNumbers.jar <cloudId> <cloudUsername:password>
<command>
where:
- cloudId = cloud region id (e.g. 0-2-0)
- cloudUsername:password = cloud account username and password
- command = one of the following:
- listcountries
- liststates "country"
- listregions "country[:state]"
- listnumbers ["country[:state]" ["region"]]
- listregaddresses
- delete number | numbersFile
- purchase "country[:state]" "region" [quantity [allowpartial [baseonservice ["regaddress"]]]]
- purchasedev "country[:state]" "region" [quantity [allowpartial [baseonservice ["regaddress"]]]]
and:
- country = one of the returned country strings.
- state = one of the returned state strings.
- region = one of the returned region strings.
- quantity = the quantity of telephone numbers to purchase. Defaults to 1.
- allowpartial = (true/false) determines whether the request succeeds even
if the requested quantity of telephone numbers are not available. Defaults to false.
- baseonservice = the name of an existing inbound service (including the "sip:"
prefix). If set then a new service will be created for each new number purchased, based on the settings within
this service.
- regaddress = the name of a regulation address that exists on the cloud account
being used. Some countries require a regulation address to be specified.
- number = a single inbound telephone number.
- numbersFile = the name of a file containing 1 or more telephone numbers,
comma-separated.
e.g.
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listcountries
Output:
Israel, Georgia, Mexico, Lithuania, United Kingdom, Netherlands, Croatia,
Greece, Switzerland, Dominican Republic, Brazil, Romania, Czech Republic,
El Salvador, Poland, South Africa, Luxembourg, Sweden, Germany, Peru,
Puerto Rico, Hungary, Norway, Spain, Canada, Italy, Finland, United States,
Slovenia, Ireland, Argentina, Cyprus, Australia, Vietnam, France, New Zealand,
Latvia, Slovakia, Chile, Belgium, Japan, Bulgaria
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword liststates "Canada"
Output:
Ontario, Newfoundland And Labrador, Saskatchewan, Prince Edward Island,
British Columbia, Nova Scotia, Quebec, Alberta, Manitoba, New Brunswick
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listregions "France"
Output:
Orleans, Lyon, Sarcelles, Dreux, Strasbourg, Lille, Paris, Enghien-Les-Bains,
Saint-Malo, Bourges, Avignon, Saint-Germain-En-Laye, Calais, Beziers,
Le Raincy, Toulon, Belfort, La Roche-Sur Yon, Dunkerque, Saint-Etienne, Pau,
Troyes, Reims, Tulle, Creteil, Vesoul, Nimes, Nice, Le Mans, Carhaix-Plouguer,
Cergy, Clermont-Ferrand, Versailles, Vannes, Colmar, Corse, Amiens, Grenoble,
Meaux, Poitiers, Angers, Evreux, Beauvais, Saint-Nazaire, Nancy,
Aix-En-Provence, Le Havre, Auray, Blois, Mulhouse, Perpignan, Moissac,
Cannes, Bobigny, Rennes, Bordeaux, Marseille, Boulogne-Billancourt, Limoges,
Nanterre, Toulouse, Montpellier, Metz, Cholet, Dijon, Chalon-Sur-Saone,
Saint-Quentin, Montauban, Caen, Corbeil-Essones, Niort, Chambery, Tours,
Besancon, Rouen, Laval, Charleville-Mezieres, Brest, Annecy, Nantes, Arles
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listregions "United States:Michigan"
Output:
Utica, Pontiac, Auburn Heights, Roseville, Ann Arbor, Grand Rapids, Flint,
Detroit Zone 04, Detroit Zone 06, Detroit Zone 01, Detroit Zone 02,
Detroit Zone 03, Commerce, Port Huron, Belleville, Howell, Trenton,
Battle Creek, Romulus, Center Line, Troy, Royal Oak, Birmingham
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listnumbers
Output:
7890123: Stockholm, Sweden 2012-03-04 $3.0
0123456: Dallas, Texas, United States 2012-03-04 $3.0
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listnumbers "Sweden" "Stockholm"
Output:
7890123: Stockholm, Sweden 2012-03-04 $3.0
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listnumbers "United States:Texas" "Dallas"
Output:
0123456: Dallas, Texas, United States 2012-03-04 $3.0
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listregaddresses
Output:
My French Place: Paris, France
My German Hideout: Berlin, Germany
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword delete 7890123
Output:
7890123 deleted
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword delete numbersToDelete.csv
Output:
7890123: deleted
1010202: not deleted (0300: Telephone number 1010202 does not belong to you.
see https://cloud.aculab.com/documents/cnws_errors?error=0300 for more information)
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "United States" "Dallas"
Output:
19725877455
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "United States:Texas" "Dallas"
Output:
19725877456
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "Sweden" "Stockholm" 2
Output:
Purchased 2 of 2 numbers:
33249880328
33249880410
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "Sweden" "Stockholm" 2 true sip:MyExistingService
Output:
Purchased 2 of 2 numbers:
33249880540 Created service sip:33249880540
33249880631 Created service sip:33249880631
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "Sweden" "Stockholm" 3 true sip:MyExistingService
Output:
Purchased 2 of 3 numbers:
33249880740 Created service sip:33249880740
33249880752 Created service sip:33249880752
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "France" "Nantes" 3 false sip:MyExistingService "My French Place"
Output:
Purchased 3 of 3 numbers:
33249880765 Created service sip:33249880765
33249880766 Created service sip:33249880766
33249880767 Created service sip:33249880767
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "Germany" "Mönchengladbach" 1 false "" "MyGermanAddress"
Output:
Purchased 3 of 3 numbers:
45249880768
45249880769
45249880770
Wake Up Call
A console application that invokes an OutboundReminder service
(that runs the
OutboundReminder UAS application) to make an
outbound call and play a wake up call media file that has been uploaded to the cloud.
This application has a properties file (wakeUpCall.properties) controls the address/number that is called and
which media file to play etc.