DEV Community: Steve Crow

Quick Tip: Kotlin, Spring Data, and Optionals

Steve Crow — Mon, 08 Nov 2021 17:01:18 +0000

Quick Tip: Kotlin Extension Functions and Spring Data

Photo by Diego PH on Unsplash

When working with Spring Data and Kotlin, you may have noticed that the default findById returns an Optional . This super-short post will show you how you can leverage Kotlin extension functions to customize this logic.

What is Optional ?

Optional was introduced in Java 8 as a solution to handle nullability. It serves as a container that might contain a value, freeing you up from using null to mean optionally defined.

Kotlin addresses this using a different approach: being null-safe.

What are extension functions?

Extension functions allow you to extend a class with additional functionality without using decorators or having direct access to modifying the class.

They can be really useful when you want to add things to third-party libraries as if the function was part of the library.

Extending Spring Data

Spring Data added an extension function in 2.1.4 to CrudRepository called findByIdOrNull . However, this method doesn’t work in some of the other interfaces, like JpaSpecificationExecutor .

Here’s one I use for JpaSpecificationExecutor that wraps the findOne method:

By defining this extension function, I can now bypass the optional entirely and work directly with the nullable return value:

Conclusion

While Kotlin is fully interoperable with Java, we can do some things to improve the overall user experience. Stay tuned for more Quick Tips to help you on your Kotlin journey.

Publish Vonage Events to Kafka with Spring Boot

Steve Crow — Sun, 26 Jul 2020 22:29:23 +0000

Event-Driven Architecture is the asynchronous, dynamic processing of events to communicate between decoupled services.

For example, we might have a unified communication platform that manages millions of users and conversations. We might bring in these conversations from a multitude of sources and process them in many different ways.

Event-Driven Architecture enables us to distribute processing of these events between various services which might:

Transfer information to long-term storage like a data lake
Perform administrative tasks like stopping spammers in real-time.

Events can come from many different channels. In this guide, you will build a Spring Boot application, using Kotlin, that can receive events from the Vonage Communication APIs and store them in Apache Kafka.

This guide assumes that you have some experience with Spring Boot and the Vonage Communication APIs.

An example of the code can be found on GitHub: cr0wst/vonage-events-kafka

What are the Vonage Communication APIs?

The Vonage Communication APIs enable developers to create things like in-app messaging, voice chat, and integration with third-party chat services.

Many of these actions generate Events, which can be handled by your application via a pre-configured Webhook.

I have created a Demo Application that can generate a random conversation to produce events.

What is Kafka?

Apache Kafka is a horizontally scalable, fault-tolerant tool for building real-time data pipelines and streaming applications.

Kafka allows you to publish and subscribe to topics, which serve as a category for records to be published. A topic can have multiple publishers and consumers. Unlike traditional message brokers, it can store historical data indefinitely.

You can read more about Kafka on the Confluent Docs.

This guide will cover the following concepts:

Connecting a Spring Boot Application to Kafka.
Creating a controller to serve as a Webhook for incoming Vonage Communication events.
Pipelining these events into a Kafka topic for later processing.

Download the Demo Application

The Pre-Setup instructions will guide you through creating a Vonage Application. You can also follow the official documentation for Creating an Application.

Most of this guide assumes that you are already receiving webhook events from Vonage, but you aren't currently sending them to Kafka.

If you don't have an application, I have created a Demo Application, which simulates multiple conversations using the Vonage Conversation API.

Initialize a New Spring Boot Application

Use your IDE or the Spring Initializr to create a new Spring Boot Application with Spring For Apache Kafka and Spring Reactive Web:

Create a Webhook

The Vonage Communication APIs send event messages to a pre-configured webhook.

Configure the Event URL

The Event URL can be defined using the Vonage Dashboard

This has to be a publicly-accessible URL. You can use a tool like ngrok to safely tunnel traffic to your application. Check out this post on Working with Webhooks using Ngrok.

I'm going to start a tunnel using Ngrok to listen on port 8080:

ngrok http 8080 -subdomain=cr0wst

Create a Controller

Create a new class called EventWebhookController and add the following code:

package com.smcrow.demo

import org.slf4j.LoggerFactory
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RestController

@RestController
class EventWebhookController {
    @PostMapping("/webhooks/events")
    fun incomingEvents(@RequestBody body: String) {
        // Handle the Event Here
        log.info(body)
    }

    companion object {
        private val log = LoggerFactory.getLogger(this::class.java)
    }
}

This code registers a route at /webhooks/events that accepts POST requests and logs the request body.

If you were to start both applications, you would see a stream of Vonage events:

Start the Webhook Application:

./mvnw spring-boot:run

Now, start the demo application:

cd ~/Code/vonage-conversation-demo
./mvnw spring-boot:run

The top terminal shows the events from Vonage, and the bottom is the application generating random conversations and messages:

Now that your application is receiving events from Vonage, it's time to set up Kafka.

Setting up Kafka

If you don't already have access to a Kafka cluster, there are a few solutions.

The simplest way is to sign up for a service like Confluent Cloud. I will be using Confluent for the remainder of this guide and the Confluent Cloud CLI

Create a Cluster

Create a new cluster on Confluent Cloud with the following command:

ccloud kafka cluster create demo --cloud aws --region us-east-2

The output has an ID number and an Endpoint, record these for later. For this guide, I will be using the ID lkc-03wkq and endpoint pkc-ep9mm.us-east-2.aws.confluent.cloud:9092

Create a Topic

Create the vonage.webhook.events topic inside of your Kafka cluster for storing the Vonage webhook events:

ccloud kafka topic create --cluster lkc-03wkq --partitions 1 vonage.webhook.events

Connecting a Spring Boot Application to Kafka

To connect your Spring Boot Application to Confluent Cloud, you'll need to create an API Key and Secret. Run the following command, replacing the resource with your ID from a previous step.

ccloud api-key create --resource=lsrc-7qz91

You will also need your bootstrap server address, which is the endpoint from a previous step.

Using the bootstrap server address, API Key and Secret, add the following properties to application.properties, replacing the appropriate variables.

# Kafka
spring.kafka.properties.ssl.endpoint.identification.algorithm=https
spring.kafka.properties.sasl.mechanism=PLAIN
spring.kafka.bootstrap-servers={{ BOOTSTRAP_SERVER_ADDRESS }}
spring.kafka.properties.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule   required username="{{ CLUSTER_API_KEY }}"   password="{{ CLUSTER_API_SECRET }}";
spring.kafka.properties.security.protocol=SASL_SSL

# Producer
spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
spring.kafka.producer.value-serializer=org.apache.kafka.common.serialization.StringSerializer

For example:

# Kafka
spring.kafka.properties.ssl.endpoint.identification.algorithm=https
spring.kafka.properties.sasl.mechanism=PLAIN
spring.kafka.bootstrap-servers=pkc-ep9mm.us-east-2.aws.confluent.cloud:9092
spring.kafka.properties.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule   required username="my-api-key"   password="my-api-secret";
spring.kafka.properties.security.protocol=SASL_SSL

# Producer
spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
spring.kafka.producer.value-serializer=org.apache.kafka.common.serialization.StringSerializer

Produce Messages from Spring Boot

The Spring Kafka project uses a KafkaTemplate object to produce messages. KafkaTemplate is generic with two generic types: one for the Kafka key, and one for the value.

Update the EventWebhookController to inject a KafkaTemplate<String, String> as a dependency:

package com.smcrow.demo

import org.slf4j.LoggerFactory
import org.springframework.kafka.core.KafkaTemplate
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RestController

@RestController
class EventWebhookController(private val kafkaTemplate: KafkaTemplate<String, String>) {
    @PostMapping("/webhooks/events")
    fun incomingEvents(@RequestBody body: String) {
        // Handle the Event Here
        log.info(body)
    }

    companion object {
        private val log = LoggerFactory.getLogger(this::class.java)
    }
}

Now, update the incomingEvents method to send the event to Kafka:

package com.smcrow.demo

import org.slf4j.LoggerFactory
import org.springframework.kafka.core.KafkaTemplate
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RestController

@RestController
class EventWebhookController(private val kafkaTemplate: KafkaTemplate<String, String>) {
    @PostMapping("/webhooks/events")
    fun incomingEvents(@RequestBody body: String) {
        // Handle the Event Here
        kafkaTemplate.send("vonage.webhook.events", body)
    }

    companion object {
        private val log = LoggerFactory.getLogger(this::class.java)
    }
}

Consuming Kafka Messages Using the CLI

You can use the Confluent Cloud CLI to consume events on the vonage.webhook.events topic.

First, configure the CLI to use your API key from before, replacing my-api-key with your API key and lkc-03wkq with the ID from a previous step:

ccloud api-key use my-api-key --resource lkc-03wkq

Now, start consuming messages:

ccloud kafka topic consume --cluster lkc-03wkq -b vonage.webhook.events

Remember that Kafka is a commit log. The -b flag starts consumption from the beginning. Using this flag means you'll get a back-fill of messages that you missed while you weren't connected.

Start Everything

First, start the Kafka Consumer if you haven't already:

ccloud kafka topic consume --cluster lkc-03wkq -b vonage.webhook.events

Now start the Webhook Application:

cd ~/Code/vonage-events-kafka-demo
./mvnw spring-boot:start

Finally, start the conversation simulator application:

cd ~/Code/vonage-conversation-demo
./mvnw spring-boot:run

The following shows all three running:

Conclusion

In this guide, you created a Spring Boot Application that can listen to Vonage Events and publish them to Kafka.

An example of the code can be found on GitHub: cr0wst/vonage-events-kafka

In another guide, I'll show you how to consume these events and store them in a relational database like Snowflake.

Here are some links you might find useful:

Multiple JPA Data Sources with Spring Boot and Kotlin

Steve Crow — Tue, 14 Jul 2020 22:12:43 +0000

Spring Boot offers an opinionated way to bootstrap applications by favoring auto-configuration and making reasonable assumptions about how your application operates.

To configure a data source using Spring Data, you can add the following properties to application.properties:

spring.datasource.url=jdbc:mysql://localhost:3306/my_database
spring.datasource.username=sqluser
spring.datasource.password=p@55w0rd

Under the hood, Spring Boot will instantiate and wire up all of the classes needed to connect to your database.

But what happens if you need to connect to multiple databases? In this post, I'll show you how to configure Spring Boot to work with two entities on two separate databases.

Create a New Spring Boot Project

The Spring Initializr can be used to make a new Spring Boot project.

You can also access the Initializr with curl:

curl https://start.spring.io/starter.zip -d dependencies=data-jpa,h2 \
-d language=kotlin \
-d packageName=com.smcrow.demo \
-d artifactId=spring-boot-multiple-datasources \
-d groupId=com.smcrow.demo \
-d baseDir=spring-boot-multiple-datasource | tar -xzvf -

Create the Entities

For this example, you're going to create two entities:

com.smcrow.demo.farm.Animal will be used to access information from the Animal table of the Farm database.
com.smcrow.demo.factory.Worker will be used to access information from the Worker table of the Factory database.

Create the Animal Entity

First, create a new class to represent an Animal. This class will be created in the com.smcrow.demo.farm package:

package com.smcrow.demo.farm

import org.springframework.data.jpa.repository.JpaRepository
import org.springframework.stereotype.Repository
import javax.persistence.Entity
import javax.persistence.GeneratedValue
import javax.persistence.GenerationType
import javax.persistence.Id

@Entity
class Animal(
        @Id
        @GeneratedValue(strategy = GenerationType.IDENTITY)
        val id: Long = 0,

        val name: String
)

@Repository
interface AnimalRepository : JpaRepository<Animal, Long>

I like to put my JpaRepository interfaces inside of the same file as the class.

Create the Worker Entity

Now, create a new class to represent a Worker. This class will be created in the com.smcrow.demo.factory package. Separating the Worker and Animal classes into different packages will help later with configuration:

package com.smcrow.demo.factory

import org.springframework.data.jpa.repository.JpaRepository
import org.springframework.stereotype.Repository
import javax.persistence.Entity
import javax.persistence.GeneratedValue
import javax.persistence.GenerationType
import javax.persistence.Id

@Entity
class Worker(
        @Id
        @GeneratedValue(strategy = GenerationType.IDENTITY)
        val id: Long = 0,

        val name: String
)

@Repository
interface WorkerRepository : JpaRepository<Worker, Long>

Add Database Configuration to `application.properties`

Since the worker and the animal tables exist in different databases, two configuration blocks are necessary.

You can define multiple data sources inside of application.properties:

# Farm DB Connection
spring.datasource-farm.jdbcUrl=jdbc:h2:mem:farm
spring.datasource-farm.username=sa
spring.datasource-farm.password=

# Factory DB Connection
spring.datasource-factory.jdbcUrl=jdbc:h2:mem:factory
spring.datasource-factory.username=sa
spring.datasource-factory.password=

Register the Database Connections

Normally, Spring Boot expects to find database credentials as part of the spring.datasource.* configuration prefix. Instead of using the automatic configuration, the data sources must be defined manually.

Create the Farm Data Source Configuration

Create a new class inside of the com.smcrow.demo.farm package called FarmDataSourceConfiguration:

package com.smcrow.demo.farm

import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.jdbc.DataSourceBuilder
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.data.jpa.repository.config.EnableJpaRepositories
import org.springframework.orm.jpa.JpaTransactionManager
import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean
import org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter
import javax.sql.DataSource

@Configuration
@EnableJpaRepositories(
        basePackages = ["com.smcrow.demo.farm"],
        entityManagerFactoryRef = "farmEntityManager",
        transactionManagerRef = "farmTransactionManager"
)
class FarmDataSourceConfiguration {
    @Bean
    @ConfigurationProperties(prefix = "spring.datasource-farm")
    fun farmDataSource(): DataSource = DataSourceBuilder.create().build()

    @Bean
    fun farmEntityManager(): LocalContainerEntityManagerFactoryBean =
            (LocalContainerEntityManagerFactoryBean()).apply {
                dataSource = farmDataSource()
                setPackagesToScan("com.smcrow.demo.farm")
                jpaVendorAdapter = HibernateJpaVendorAdapter()
            }

    @Bean
    fun farmTransactionManager() = JpaTransactionManager(farmEntityManager().`object`!!)
}

Create the Factory Data Source Configuration

Create a new class inside of the com.smcrow.demo.factory package called FactoryDataSourceConfiguration:

package com.smcrow.demo.factory

import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.jdbc.DataSourceBuilder
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.data.jpa.repository.config.EnableJpaRepositories
import org.springframework.orm.jpa.JpaTransactionManager
import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean
import org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter
import javax.sql.DataSource

@Configuration
@EnableJpaRepositories(
        basePackages = ["com.smcrow.demo.factory"],
        entityManagerFactoryRef = "factoryEntityManager",
        transactionManagerRef = "factoryTransactionManager"
)
class FactoryDataSourceConfiguration {
    @Bean
    @ConfigurationProperties(prefix = "spring.datasource-factory")
    fun factoryDataSource(): DataSource = DataSourceBuilder.create().build()

    @Bean
    fun factoryEntityManager(): LocalContainerEntityManagerFactoryBean =
            (LocalContainerEntityManagerFactoryBean()).apply {
                dataSource = factoryDataSource()
                setPackagesToScan("com.smcrow.demo.factory")
                jpaVendorAdapter = HibernateJpaVendorAdapter()
            }

    @Bean
    fun factoryTransactionManager() = JpaTransactionManager(factoryEntityManager().`object`!!)
}

More Detail

Now let's break down the configuration classes.

Each configuration class has an @EnableJpaRepositories annotation. This enables package scanning for interfaces annotated with @Repository.

The basePackages is an array of packages that contain the @Repositories that will be associated with the specific data source being configured.

There are three beans that are created in each configuration class.

The first is the data source which represents a connection to a physical data source. The @ConfigurationProperties annotation allows the properties from spring.datasource-factory to be loaded into the DataSource.

@Bean
@ConfigurationProperties(prefix = "spring.datasource-factory")
fun factoryDataSource(): DataSource = DataSourceBuilder.create().build()

The next bean is the LocalContainerEntityManagerFactoryBean which is used to create the EntityManagerFactory

@Bean
fun factoryEntityManager(): LocalContainerEntityManagerFactoryBean =
        (LocalContainerEntityManagerFactoryBean()).apply {
            dataSource = factoryDataSource()
            setPackagesToScan("com.smcrow.demo.factory")
            jpaVendorAdapter = HibernateJpaVendorAdapter()
        }

And the third is the JpaTransactionManager:

@Bean
fun factoryTransactionManager() = JpaTransactionManager(factoryEntityManager().`object`!!)

Summary

I hope that this helps serve as a quick reference guide for setting up multiple data sources in Spring Boot and Kotlin.

The full code repository can be found on GitHub: cr0wst/spring-boot-multiple-datasource

I've found a few other resources for configuring this in Java, but none of them were written with Kotlin in mind. They can be found here:

Make Text-to-Speech Phone Call with Java

Steve Crow — Thu, 21 Mar 2019 20:18:28 +0000

Introduction

In a previous tutorial, we showed you how to Receive a Phone Call with Java and respond using Text-to-Speech. In addition to receiving a phone call, you can also make outgoing phone calls.

In this tutorial, you will create an application that can make outgoing text-to-speech phone calls utilizing Java and the Nexmo Voice API.

Prerequisites

To work through this tutorial, you will need a Nexmo account. Sign up now if you don't already have an account.

You will be using Gradle to manage your dependencies and run your application. Additionally, you'll need to make sure you have a copy of the JDK installed. I will be using JDK 11, which is the current LTS, in this tutorial.

Finally, you'll need the Nexmo CLI installed. You'll use it to purchase a phone number and configure your Nexmo account to point at your new application.

Make Text-to-Speech Phone Call with Java

This tutorial will walk you through the following steps:

Using the Nexmo CLI to purchase a phone number and create an application.
Using Gradle to initialize a new Java application.
Using the Nexmo Java Client Library to initiate a phone call and execute text-to-speech.

Purchasing a Number

You will need a Nexmo number to send phone calls. If you do not have a number, you can use the Nexmo CLI to purchase one:

nexmo number:buy --country_code US

Take note of the number that you just purchased. You will need this number to link your application, and you will use it later when writing the code to create the phone call.

Configure Your Nexmo Account

If you do not have an application, you can use the Nexmo CLI to create one. You will need to define the name of the application, and an answer and event URL that the Voice API will use by default:

The Nexmo Voice API will make a request to your answer URL when a phone number linked to your application receives a phone call.
The Nexmo Voice API will make requests to your event URL when various status changes occur.

To learn more about applications see our Nexmo Concepts Guide.

Use the following command to create an application using the Nexmo CLI:

nexmo app:create "Send TTS Call" http://example.com/webhooks/answer http://example.com/webhooks/events --keyfile private.key

This command will also create a file called private.key which you will need to authenticate with the Nexmo Voice API to make calls. This file will be saved to the directory you run the command inside of. Also make a note of the Application ID that is returned, as you will need it later.

Using Gradle to Set Up a New Java Project

You will be using Gradle to manage your dependencies and to create and run your Java application.

The gradle init --type=java-application command will create all of the folders you need as well as a sample class where you will be writing your code.

From the command line, create a new Java project with the following command and accept the default values at the interactive prompts:

mkdir make-tts-call
cd make-tts-call
gradle init --type java-application

Gradle will create the App class in the src/main/java/make/tts/call folder. Inside of this class is a getGreeting and main method. You won't need the getGreeting method, so feel free to remove it.

Your App class should look like this:

/*
 * This Java source file was generated by the Gradle 'init' task.
 */
package make.tts.call;

public class App {
    public static void main(String[] args) {
        // Future Code Goes Here
    }
}

Add the Dependencies

You will be using the Nexmo Java Library to communicate with the Nexmo Voice API. Add the following to the dependencies block in your build.gradle file:

// Nexmo Java Client
implementation 'com.nexmo:client:4.2.0'

Initialize the Nexmo Client

The Nexmo Java Library contains a NexmoClient class which gives you access to the various Nexmo APIs. You will use your Application ID, and the path to your private.key file from a previous step. The NexmoClient will use this information to authenticate to the Nexmo Voice API.

Add the following to the main method of the App class, resolving any imports:

NexmoClient nexmoClient = NexmoClient.builder()
        .applicationId(APPLICATION_ID)
        .privateKeyPath(PRIVATE_KEY_PATH)
        .build();

VoiceClient voiceClient = nexmoClient.getVoiceClient();

The NexmoClient throws an Exception if the private key file cannot be loaded. For the sake of convenience, modify your main method signature to throw any exceptions. Your main method should now look like this:

public static void main(String[] args) throws Exception {
    NexmoClient nexmoClient = NexmoClient.builder()`
            .applicationId(APPLICATION_ID)
            .privateKeyPath(PRIVATE_KEY_PATH)
            .build();

    VoiceClient voiceClient = nexmoClient.getVoiceClient();
}

Build the Nexmo Call Control Object

The Nexmo Voice API is controlled using Nexmo Call Control Object (NCCO). An NCCO is a JSON array which contains a set of actions that the Voice API will execute.

The following NCCO will instruct the Nexmo Voice API to speak to the recipient when they answer the call:

[
    {
        "action": "talk",
        "text": "This is a text-to-speech call from Nexmo"
    }
]

The Nexmo Java Client Library provides classes that allow you to construct an NCCO. You will use the Ncco and TalkAction classes to build the NCCO.

Add the following to the main method, resolving any imports:

TalkAction intro = TalkAction.builder("This is a text-to-speech call from Nexmo").build();
Ncco ncco = new Ncco(intro);

Make the Phone Call

The VoiceClient contains a method called createCall which expects a com.nexmo.client.voice.Call. The Call object is used to define which number you're calling from, the recipient you wish to call, and the NCCO to control the call.

Create a new Call object in the main method and invoke the createCall method with the created object, resolving any imports:

Call call = new Call(TO_NUMBER, NEXMO_NUMBER, ncco);
voiceClient.createCall(call);

Test Your Application

Start your application with the gradle run command inside of your make-tts-call directory. You should receive a phone call from your Nexmo number.

Once you answer this call, the Nexmo Voice API will speak the message, "This is a text-to-speech call from Nexmo."

Conclusion

In a few lines of code, you have created an application that can call a recipient and speak a message.

Check out our documentation on Nexmo Developer where you can learn more about call flow or Nexmo Call Control Objects. See our Nexmo Code Snippets for Java for full code examples on this tutorial and more.

The post Make Text-to-Speech Phone Call with Java appeared first on Nexmo.

Record a Phone Message with Java

Steve Crow — Tue, 19 Feb 2019 19:15:41 +0000

Introduction

In a previous tutorial, we showed you how to Receive a Phone Call with Java and respond using text to speech. We can also allow users to leave a message and then retrieve that recorded message.

Prerequisites

To work through this tutorial, you will need a Nexmo account. Sign up now if you don't already have an account.

You will be using Gradle to manage your dependencies and run your application. Additionally, you'll need to make sure you have a copy of the JDK installed. I will be using JDK 8 in this tutorial.

Finally, you'll need the Nexmo CLI installed. You'll use it to purchase a phone number and configure your Nexmo account to point at your new application.

Record a Phone Message with Java

This tutorial will walk you through the following steps:

Using Gradle to setup a new Java project.
Using the Spark framework for controlling the call.
Purchasing a number and configuring your Nexmo account to use that number with your application.

Using Gradle to Setup a New Java Project

You will use Gradle to manage your dependencies and to create and run your Java application.

The gradle init --type=java-application command will create all of the folders you will need as well as a sample class where you will be writing your code.

From the command line, create a new Java project with the following commands:

mkdir record-a-message
cd record-a-message
gradle init --type=java-application

Using the Spark Framework for Controlling the Call

You will use the Spark framework to receive a HTTP call made by Nexmo when your number receives a call, and to receive the request that Nexmo sends after the message has been recorded.

Adding the Dependencies

Add the following to the dependencies block in your build.gradle file:

// Spark Framework
compile 'com.sparkjava:spark-core:2.7.2'

// Nexmo Java Client
compile 'com.nexmo:client:4.0.1'

Your dependencies block should look like this:

dependencies {
    compile 'com.sparkjava:spark-core:2.7.2'
    compile 'com.nexmo:client:4.0.1'

    // Use JUnit test framework
    testCompile 'junit:junit:4.12'
}

Gradle will create the App class in the src/main/java folder. Inside of this class is a getGreeting and a main method. You won't need the getGreeting method, so feel free to remove it.

Define the Answer Route

First, you will define the route that will be used for answering the call. When a call is received, Nexmo will send a request to a pre-defined webhook URL. It expects to receive a Nexmo Call Control Object (NCCO) containing a list of actions to execute.

When the phone call is answered, your application will instruct Nexmo to execute three actions:

A talk action to greet the caller and instruct them on how to leave a message.
A record action which will instruct the Voice API to start recording.
A talk action to thank them for leaving a message.

This is the resulting NCCO that your application will create:

[
  {
    "text": "Please leave a message after the tone, then press #. We will get back to you as soon as we can.",
    "action": "talk"
  },
  {
    "endOnSilence": 3,
    "endOnKey": "#",
    "beepStart": true,
    "eventUrl": [
      "http://your-web-address/webhooks/recordings"
    ],
    "action": "record"
  },
  {
    "text": "Thank you for your message. Goodbye",
    "action": "talk"
  }
]

Add the following to the main method of the App class, making sure to resolve all imports:

/*
* Route to answer and connect incoming calls with recording.
*/
Route answerRoute = (req, res) -> {
    String recordingUrl = String.format("%s://%s/webhooks/recordings", req.scheme(), req.host());

    TalkAction intro = new TalkAction.Builder("Please leave a message after the tone, then press #. We will get back to you as soon as we can.")
            .build();

    RecordAction record = new RecordAction.Builder()
            .eventUrl(recordingUrl)
            .endOnSilence(3)
            .endOnKey('#')
            .beepStart(true)
            .build();

    TalkAction outro = new TalkAction.Builder("Thank you for your message. Goodbye").build();

    res.type("application/json");

    return new Ncco(intro, record, outro).toJson();
};

The record action has a few different properties. For example, you can define the event url that will be sent a request when the recording is finished, end the recording on a specific key press, and play a beep at the start of the recording.

Define the Recordings Route

The record action has a property called eventUrl which is used to communicate when the recording is finished. The following is an example of the return parameters sent to the event url:

{
  "start_time": "2020-01-01T12:00:00Z",
  "recording_url": "https://api.nexmo.com/media/download?id=aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "size": 12345,
  "recording_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "end_time": "2020-01-01T12:01:00Z",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

The Nexmo Java Client has a class called RecordEvent which can be used to deserialize the JSON sent to eventUrl. For now, you're going to output the recording_url to the console.

Add the following to the main method of the App class, resolving any imports:

/*
* Route which prints out the recording URL it is given to stdout.
*/
Route recordingRoute = (req, res) -> {
    RecordEvent recordEvent = RecordEvent.fromJson(req.body());
    System.out.println(recordEvent.getUrl());

    res.status(204);
    return "";
};

Register the Routes

Up until this point you have defined two routes:

The first route will respond to Nexmo with an NCCO when Nexmo answers the incoming call.
The second route will log the recording URL when Nexmo finishes recording the message.

In order to use these routes, we need to configure Spark. Your application will listen on port 3000, and the routes will be configured on /webhooks/answer and /webhooks/recordings.

Add the following to the main method of the App class:

Spark.port(3000);
Spark.get("/webhooks/answer", answerRoute);
Spark.post("/webhooks/recordings", recordingRoute);

Purchasing a Number

You will need a Nexmo number in order to receive phone calls. If you do not have a number you can use the Nexmo CLI to purchase one:

nexmo number:buy --country_code US

Take note of the number that is assigned to you on purchase. You will need this number to link your application and for testing.

Exposing Your Application

In order to send an HTTP request to your application, Nexmo needs to know the URL that your application is running on.

Instead of configuring your local network or hosting your application on an external service, you can use ngrok to safely expose your application to the internet.

Download ngrok and run the following command:

ngrok http 3000

Take note of the forwarding address as you will need it when you configure your account. In the following picture, the forwarding address is http://99cad2de.ngrok.io.

Configure Your Nexmo Account

If you do not have an application you can use the Nexmo CLI to create one using your ngrok forwarding address:

nexmo app:create "Record Message Demo" http://your-ngrok-forwarding-address/webhooks/answer http://your-ngrok-forwarding-address/webhooks/events --keyfile private.key

After running this command, you will be shown an an application id. For example: notreal-1111-2222-3333-appid. You will need this application id to link your phone number to the application.

You can use the Nexmo CLI to link your phone number and application:

nexmo link:app your-nexmo-phone-number your-application-id

This command instructs Nexmo to create a new application on your account. The application will send a request to the first URL when it receives a phone call. The application will send requests to the second URL when the call status changes.

Test Your Application

Start your application with the gradle run command inside of your record-a-message directory.

Make a call to your Nexmo number and test out your application. You will hear the message, "Please leave a message after the tone, then press #. We will get back to you as soon as we can." Once you hear the beep, leave a message and then press #. You should then hear "Thank you for your message. Goodbye." and the recording URL will be displayed on your console.

Conclusion

In a few lines of code you have created an application that can receive a phone call, record a message, and then display the URL to that recording.

Check out our documentation on Nexmo Developer where you can learn more about call flow or Nexmo Call Control Objects. See our Nexmo Quickstart Examples for Java for full code examples on this tutorial and more.

The post Record a Phone Message with Java appeared first on Nexmo.

Send SMS with GitHub Actions

Steve Crow — Fri, 08 Feb 2019 19:51:08 +0000

Bosses come in all shapes and sizes. Some are hands-off, letting you work to the best of your abilities. Others, take a more direct approach and measure your accomplishments solely through the code that you produce. After all, if you're not writing code then why are we paying you?

Want to show your boss just how hard you're working? Absolutely! With the power of Nexmo and GitHub Actions, you can make sure that an excellent annual review and a sizable pay raise are in order.

Prerequisites

To follow along with this guide, you will need a Nexmo account. Sign up now if you don't have one.

Upon signing up, you will receive an API key and secret. You will need these for a later step. Additionally, you will need to purchase an SMS enabled number to be able to send messages.

At the time of writing, GitHub Actions is currently in public beta. If you aren't a member of the beta, you will need to apply for the beta.

What is GitHub Actions?

GitHub Actions is a new tool from GitHub in which individual actions are combined to make a workflow that performs on different trigger event types.

Each action is a Docker container containing a single entry point. The action lives inside of a Dockerfile with LABEL instructions providing information about the action.

For example, let's say you wanted to print out the name of the user (referred to as the GitHub Actor) to the console. You would create a repository that contains a Dockerfile with the following contents:

FROM alpine:3.8

LABEL "com.github.actions.name"="Print GitHub Actor"
LABEL "com.github.actions.description"="Print the GITHUB_ACTOR environment variable to the console."
LABEL "com.github.actions.icon"="user"
LABEL "com.github.actions.color"="blue"

LABEL "repository"="https://github.com/cr0wst/display-github-actor-action"
LABEL "homepage"="https://smcrow.net"
LABEL "maintainer"="Steve Crow <steve.crow@nexmo.com>"

ENTRYPOINT ["sh", "-c", "echo $GITHUB_ACTOR"]

This entire action runs the command echo $GITHUB_ACTOR where $GITHUB_ACTOR is an environment variable that GitHub provides to the container containing the user who triggered the action.

For more information on Docker see this Docker Overview.

The advantage of GitHub Actions comes in creating reusable actions that others can use in their workflows.

Creating Your First Workflow

For this guide you will be creating a new repository with a workflow that sends your boss a text message every time a push is received.

Create a Repository

First, start by creating a new repository:

Create a New Workflow

After you create your repository, you will need to navigate to the actions tab where you will see a button to create a new workflow:

Workflows can be created in either the graphical user interface (GUI) or by creating a workflow file.

Link the Action Trigger to an Action

Drag the blue connector down to create your first action.

The action that you will be bringing in is the Nexmo SMS Action. This action uses the Nexmo CLI to send text messages.

In the "Find or enter an action..." box put nexmo-community/nexmo-sms-action@master and click the use button.

This action requires three secret variables to be defined:

NEXMO_API_KEY containing your Nexmo API Key.
NEXMO_API_SECRET containing your Nexmo API Secret.
NEXMO_NUMBER containing the number from which to send the message.

I recommend storing your boss' number in another secret variable.

Scroll down and enter your secret variables. I will be using the BOSS_NUMBER environment variable to store the number that will be receiving the SMS.

For testing purposes, and probably production purposes, I wouldn't recommend using your boss's actual number. Try it with your phone number first. The phone number must be in international format without any spaces or special characters separating the numbers. For example, 15551239876.

The command works by taking an argument in the form of RECIPIENT_NUMBER The contents of the message. You can use variables like $BOSS_NUMBER and $GITHUB_ACTOR in the arguments, which resolve upon the execution of the action.

Now, enter the following in the args box:

$BOSS_NUMBER Hey boss! Just letting you know that I, $GITHUB_ACTOR, just pushed some code.

Now you can hit the done button and save your action with the "start commit" button in the upper-right corner:

Saving the action is a push in and of itself. If you look in the actions tab, you can see the status of your action.

You should receive a text message upon saving your action and on any additional pushes to the repository.

Conclusion

Soon enough your boss will start to realize the true value you bring to the company. Your work will be filling up their text message inbox and sending them into a state of "my direct reports are amazing" euphoria.

Check out the hey-boss-im-working repository for a full example of this workflow. You can also find it as part of our Nexmo Extend Catalog.

Tracking Santa with SMS and Java

Steve Crow — Fri, 07 Dec 2018 19:11:13 +0000

Since December of 2004, Google has provided an annual Christmas-themed site which allows users to track Santa during Christmas Eve. Additionally, NORAD has been tracking Santa since 1955. While no official API exists, there is an unofficial API which can be used to track Santa’s whereabouts.

In celebration of the Christmas season, I wanted to create a Spring Boot application that could be used to get updates on Santa’s location via SMS. The full code for this Java application can be found on GitHub.

First, I want to explain how the application works on a higher level. Then we can dive into some of the more challenging problems, and ways to work around them.

See it in Action

When an SMS is received on my Nexmo number, a payload gets sent to my registered webhook. Information such as the sender's phone number and the message contents are then used to determine how to respond to the message.

Here's how it looks in action:

The Initial Message

The first time a message is received, the user is always presented with Santa's current location. They are also asked if they would like to provide their postal code to get distance information.

Location Lookup

Location lookup is not a trivial task. Postal codes are not consistent worldwide, and it helps to know which country the user is contacting from in order to narrow down our search.

If the user elects to provide postal code information, I use Nexmo Number Insight to lookup the country that they are sending messages from. They are then asked to provide their postal code. From this, I use a service called GeoNames to lookup the latitude and longitude for that postal code.

This information gets saved in the database along with their phone number. The latitude and longitude is used to calculate how far Santa is from them:

Getting More Technical

At its surface, the application doesn't seem all that complicated. However, there are quite a few challenges that I ran into during the development process. I'd like to highlight some of the more technical aspects of the code.

Routing Incoming Messages

My Nexmo number is configured to send POST requests to a webhook URL. I have an IncomingMessageController setup to handle the incoming messages:

@PostMapping
public void post(@RequestParam("msisdn") String from,
        @RequestParam("to") String nexmoNumber,
        @RequestParam("keyword") String keyword,
        @RequestParam("text") String text
) {
  Phone phone = findOrCreatePhone(from, nexmoNumber);
  findHandler(phone, keyword).handle(phone, text);
}

The findOrCreatePhone method is used to persist a new Phone entity, or to lookup an existing entity. Here's what the phone entity looks like:

@Entity
public class Phone {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;
  private String number;
  private String nexmoNumber;
  private String countryCode;

  @Enumerated(EnumType.STRING)
  private Stage stage;

  @OneToOne
  private Location location;

  // Getters and Setters
}

The entity contains the phone number, the Nexmo number, a country code, and the current stage that the user is in. I will talk about the Stage enum in a later section.

The findHandler method is used to lookup an appropriate KeywordHandler to handle the message:

public interface KeywordHandler {
  void handle(Phone phone, String text);
}

Each handler is responsible for handling a specific keyword. The keywords that the application knows about are:

HELP which provides contextual information to assist the user.
CANCEL which cancels the current series of questions.
REMOVE which removes the user from the database.
YES in which the user is responding to the question in the affirmative.
NO in which the user is responding to the question in the negative.
WHERE which responds with Santa's current location.
LOCATION which allows the user to update their location.

Each KeywordHandler is registered as a Spring Managed Bean. The HelpKeywordHandler, for example, looks like this:

@Component
public class HelpKeywordHandler implements KeywordHandler {
  @Override
  public void handle(Phone phone, String text) {
    // Logic here
  }
}

All of the KeywordHandler implementations are injected into a keywordHandler map on the IncomingMessageController:

private final Map<String, KeywordHandler> keywordHandlers;

@Autowired
public IncomingMessageController(Map<String, KeywordHandler> keywordHandlers) {
  this.keywordHandlers = keywordHandlers;
}

When injecting into a map, Spring will use camelCase class names as the key, and the instantiated class as the value. For example, the HelpKeywordHandler is stored with the key helpKeywordHandler:

HelpKeywordHandler handler = keywordHandlers.get("helpKeywordHandler");

The appropriate KeywordHandler is then picked using a variant of the Strategy Pattern. If no valid KeywordHandler is found, then the DefaultKeywordHandler is used to respond.

private KeywordHandler findHandler(Phone phone, String keyword) {
  // New users should always go to the default handler
  if (phone.getStage() == null) {
    return keywordHandlers.get("defaultKeywordHandler");
  }

  KeywordHandler handler = keywordHandlers.get(keywordToHandlerName(keyword));
  return (handler != null) ? handler : keywordHandlers.get("defaultKeywordHandler");
}

private String keywordToHandlerName(String keyword) {
  return keyword.toLowerCase() + "KeywordHandler";
}

Routing messages like this allows for flexibility when new keywords need to be added.

Handling the Various Stages

Each handler is responsible for messages that start with its keyword. However, how does the YesKeywordHandler know which question the user is responding to? This is where the Stage enum inside of the Phone class comes in.

The Phone entity can exist in the following intermediary stages:

No Stage (null) for users that have just been created and have not been asked a question yet.
INITIAL for users who have been responded to with the first message containing Santa's location and a prompt on whether or not they would like to provide a postal code.
COUNTRY_PROMPT for users who have been asked if their country code is correct.
POSTAL_PROMPT for users who have been asked to provide a postal code.

Once the questions have been asked, they are put in the following final stages:

REGISTERED for users who have provided a postal code and will receive more detailed information.
GUEST for users who did not wish to provide postal code information and will only receive Santa's current location with no distance calculated.

This is how the YesKeywordHandler uses stages:

@Override
public void handle(Phone phone, String text) {
  if (phone.getStage() == Phone.Stage.INITIAL) {
    handlePromptForCountryCode(phone);
  } else if (phone.getStage() == Phone.Stage.COUNTRY_PROMPT) {
    handlePromptForPostalCode(phone);
  } else {
    outgoingMessageService.sendUnknown(phone);
  }
}

A user that is answering in the INITIAL stage must be answering the question "Would you like to provide postal code information?"

A user answering in the COUNTRY_PROMPT stage must be answering the question "I see you're messaging from the US. Reply YES, a 2-character country code, or CANCEL if you've changed your mind."

Getting the Country Code

In order to lookup the postal code more accurately, it helps to know the country the user is messaging from. I created a PhoneLocationLookupService which uses Nexmo Basic Number Insight to lookup the country information for the phone number:

@Service
public class PhoneLocationLookupService {
  private final InsightClient insightClient;

  @Autowired
  public PhoneLocationLookupService(NexmoClient nexmoClient) {
    this.insightClient = nexmoClient.getInsightClient();
  }

  public String lookupCountryCode(String number) {
    try {
      return this.insightClient.getBasicNumberInsight(number).getCountryCode();
    } catch (IOException | NexmoClientException e) {
      return null;
    }
  }
}

The application will ask the user to confirm their country just in case they are travelling and want to set themselves in a different country instead.

Lookup for Postal Codes

It turns out that looking up latitude and longitude information for postal codes is not a trivial task. I chose to work with GeoNames because the service is free.

I created a PostCodeLookupService to handle looking up the postal code information. The getLocation method first looks to see if we already know about the postal code in the database. This is a good practice as it helps limit the number of calls to the third party service.

If there isn't an existing Location entity, the third party service is called, and a new entity is persisted. If we couldn't find a location matching that postal code, we return an empty Optional so that the application knows to ask the user to try again:

private Optional<Location> getLocation(String country, String postalCode) {
  Optional<Location> locationOptional = locationRepository.findByPostalCode(postalCode);
  if (locationOptional.isPresent()) {
    return locationOptional;
  }

  LocationResponse response = getLocationResponse(country, postalCode);
  if (response.getPostalCodes().isEmpty()) {
    return Optional.empty();
  }

  Location newLocation = buildLocation(response, postalCode);
  return Optional.of(locationRepository.save(newLocation));
}

Calculating Distance

Once we have the user's latitude and longitude we can lookup Santa's current location and use a formula to determine how far away the user is from Santa. This is done in the DistanceCalculationService:

 public double getDistanceInMiles(double lat1, double lng1, double lat2, double lng2) {
  double theta = lng1 - lng2;
  double dist = Math.sin(Math.toRadians(lat1))
          * Math.sin(Math.toRadians(lat2))
          + Math.cos(Math.toRadians(lat1))
          * Math.cos(Math.toRadians(lat2))
          * Math.cos(Math.toRadians(theta));

  dist = Math.acos(dist);
  dist = Math.toDegrees(dist);
  dist = dist * 60 * 1.1515;

  return dist;
}

Conclusion

This was a look into how one might create an application that allows you to get Santa's location updates via SMS. We covered routing messages based on keywords, using multiple stages to determine which questions a user is responding to, and using Nexmo Number Insight to get the country code for a phone number.

For more detailed information, I would recommend looking at the code on GitHub. The README file contains all the information you need to get up and running with the application itself.

Be sure to check out Google's Santa Tracker or NORAD Santa Tracker around Christmas Eve as an additional way to keep tabs on Santa.

Creating a WebSocket Server with the Java API for WebSockets

Steve Crow — Mon, 22 Oct 2018 14:54:57 +0000

WebSocket is a protocol which enables communication between the server and the browser. It has an advantage over RESTful HTTP because communications are both bi-directional and real-time. This allows for the server to notify the client at any time instead of the client polling on a regular interval for updates.

In this series of posts, I'm going to show you three different ways to create a WebSocket server in Java using Spring Boot, the Spark Framework, and the Java API for WebSockets.

Prerequisites

You will be using Gradle to manage your dependencies and run your application.

Additionally, you'll need to make sure you have a copy of the JDK installed. I will be using JDK 8 in this tutorial.

The Java API for WebSockets

Introduced in Java EE 7, the Java API for WebSockets, or JSR 356 is a specification that Java developers can use in order to integrate WebSockets into their applications.

It allows developers to write their WebSocket-based application completely independent of their container's implementation. For this guide you will be using Tomcat. However, because you will be using JSR 356, any other web container which supports Java EE 7 should work.

Create the Project

You will use Gradle to initialize a new Java application. You can use the following command to create a directory for your project, navigate to that directory, and initialize the application:

mkdir websocket-java-api
cd websocket-java-api
gradle init --type=java-application

Add the Java WebSocket API Dependency

Add the following dependency to the dependencies block of build.gradle:

compile 'javax.websocket:javax.websocket-api:1.1'

Create the WebSocket Endpoint

WebSocket messages can be both text and binary. You're going to create an endpoint that can handle both of these messages.

The @ServerEndpoint annotation is used to decorate a class and declare it as a WebSocket endpoint. You can provide it with a parameter which represents the path that the endpoint is published on.

Create a new class called WebSocketEndpoint and annotate it with @ServerEndpoint("/socket"):

import javax.websocket.server.ServerEndpoint;

@ServerEndpoint("/socket")
public class WebSocketEndpoint {

}

Each event that the WebSocketEndpoint handles is defined by an annotation. You can use the @OnMessage annotation to tag methods for receiving binary or text events.

For demonstration purposes, you're going to create an echo server which will echo the message received back to the sender.

In order to test binary messages, you will be sending images to the WebSocket server. The default max size depends on the container, but you can use the maxMessageSize parameter to specify how large of a message to support.

Add the following methods:

@OnMessage
public String handleTextMessage(String message) {
    System.out.println("New Text Message Received");
    return message;
}

@OnMessage(maxMessageSize = 1024000)
public byte[] handleBinaryMessage(byte[] buffer) {
    System.out.println("New Binary Message Received");
    return buffer;
}

Note that the method signature determines which type of message the method will handle. See the OnMessage annotation documentation for a list of supported method signatures.

Create a Client to Test Your Application

You will need to create a client to test your WebSocket server. You will want to test sending both text and binary messages. This can be accomplished with JavaScript.

Create the webapp folder inside of the src/main folder.

Add the following to index.html inside of the src/main/webapp folder:

<html>
<head>
    <style>
        #messages {
            text-align: left;
            width: 50%;
            padding: 1em;
            border: 1px solid black;
        }
    </style>
    <title>Sample WebSocket Client</title>
</head>
<body>
<div class="container">
    <div id="messages" class="messages"></div>
    <div class="input-fields">
        <p>Type a message and hit send:</p>
        <input id="message"/>
        <button id="send">Send</button>

        <p>Select an image and hit send:</p>
        <input type="file" id="file" accept="image/*"/>

        <button id="sendImage">Send Image</button>
    </div>
</div>
</body>
<script>
    const messageWindow = document.getElementById("messages");

    const sendButton = document.getElementById("send");
    const messageInput = document.getElementById("message");

    const fileInput = document.getElementById("file");
    const sendImageButton = document.getElementById("sendImage");

    const socket = new WebSocket("ws://localhost:8080/socket");
    socket.binaryType = "arraybuffer";

    socket.onopen = function (event) {
        addMessageToWindow("Connected");
    };

    socket.onmessage = function (event) {
        if (event.data instanceof ArrayBuffer) {
            addMessageToWindow('Got Image:');
            addImageToWindow(event.data);
        } else {
            addMessageToWindow(`Got Message: ${event.data}`);
        }
    };

    sendButton.onclick = function (event) {
        sendMessage(messageInput.value);
        messageInput.value = "";
    };

    sendImageButton.onclick = function (event) {
        let file = fileInput.files[0];
        sendMessage(file);
        fileInput.value = null;
    };

    function sendMessage(message) {
        socket.send(message);
        addMessageToWindow("Sent Message: " + message);
    }

    function addMessageToWindow(message) {
        messageWindow.innerHTML += `<div>${message}</div>`
    }

    function addImageToWindow(image) {
        let url = URL.createObjectURL(new Blob([image]));
        messageWindow.innerHTML += `<img src="${url}"/>`
    }
</script>
</html>

Embed and Configure Tomcat

Unlike Creating a WebSocket Server with Spring Boot, or Creating a WebSocket Server with the Spark Framework, there is initially no embedded server to run your application.

The Gretty plugin for Gradle can be used to embed a variety of containers.

First, apply the Gretty plugin to build.gradle file by adding this to your plugins block:

id "org.gretty" version "2.2.0"

Second, you will need to configure Gretty to use Tomcat as the servlet container, and set the context path to / for the sake of simplicity.

Add the following block to build.gradle:

gretty {
    servletContainer = 'tomcat8'
    contextPath = '/'
}

Note that, by default, Gretty will use Jetty as the servlet container. This same guide will also run in Jetty, but that is the same container that both Spring Boot and the Spark framework embed and I wanted to show something different.

Start the Application

Your WebSocket server is now complete. Start your application using the gradle appRun command inside of the application's directory.

You can access your application at http://localhost:8080 where you will be greeted with the following page:

The "connected" message indicates that the JavaScript client was able to make a connection.

Try sending a text message by typing into the input field and clicking on the send button. Also try uploading an image. In both instances, you should see the same message and image echoed back.

Conclusion

In this tutorial you learned how to create a WebSocket server using JSR 356 which can receive both binary and text messages and run on any JSR 356 compliant container. Try removing the servletContainer setting and running in Jetty, or use the Gradle WAR plugin to generate a WAR file and deploy it on a different container.

The finished code for this tutorial can be found on the nexmo-community/websocket-java-api repository.

Did you know that you can use WebSocket as an endpoint in a Nexmo Call Control Object? Check out this post on Real Time Call Transcription with IBM Watson to learn how to use the Nexmo Voice API, WebSockets, and IBM Watson to perform real-time call transcription.

Interested in reading more about WebSockets? Check out this post on What are WebSockets? How Can They Enhance Digital Solutions?

Creating a WebSocket Server with the Spark Framework

Steve Crow — Mon, 15 Oct 2018 15:16:13 +0000

In this series of posts, I'm going to show you three different ways to create a WebSocket server in Java using Spring Boot, the Spark Framework, and the Java API for WebSockets.

Prerequisites

You will be using Gradle to manage your dependencies and run your application.

Additionally, you'll need to make sure you have a copy of the JDK installed. I will be using JDK 8 in this tutorial.

WebSockets with the Spark Framework

Spark is a micro framework for creating Java and Kotlin web applications.

Create the Project

You will use Gradle to initialize a new Java application. You can use the following command to create a directory for your project, navigate to that directory, and initialize the application:

mkdir websocket-spark-framework
cd websocket-spark-framework
gradle init --type=java-application

Add the Spark Dependency

Add the following dependency to the dependencies block of build.gradle:

compile 'com.sparkjava:spark-core:2.7.2'

Unlike Creating a WebSocket Server with Spring Boot, WebSockets with Spark only work with the embedded Jetty server, and you will need to define the path and the handler before any HTTP routes.

Create the WebSocket Handler

WebSocket messages can be both text and binary. You're going to create a handler that can handle both of these messages.

Create a new class called WebSocketHandler and annotate it with @WebSocket:

import org.eclipse.jetty.websocket.api.annotations.WebSocket;

@WebSocket
public class WebSocketHandler {

}

Each event that the WebSocketHandler handles is defined by an annotation. You can use the @OnWebSocketMessage annotation to tag methods for receiving binary or text events.

For demonstration purposes, you're going to create an echo server which will echo the message received back to the sender.

Add the following methods:

@OnWebSocketMessage
public void handleTextMessage(Session session, String message) throws IOException {
    System.out.println("New Text Message Received");
    session.getRemote().sendString(message);
}

@OnWebSocketMessage
public void handleBinaryMessage(Session session, byte[] buffer, int offset, int length) throws IOException {
    System.out.println("New Binary Message Received");
    session.getRemote().sendBytes(ByteBuffer.wrap(buffer));
}

Note that the method signature determines which type of message the method will handle. See the OnWebSocketMessage annotation documentation for a list of supported method signatures.

Register the WebSocket Handler

In order to use the WebSocketHandler, it must be registered.

Open up the App class that Gradle has created for you. Delete the getGreeting method and the contents of the main method as you won't be needing either.

Inside of the main method add the following to register the WebSocketHandler on the /socket path:

@Override
public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
    webSocket("/socket", WebSocketHandler.class);
}

Create a Client to Test Your Application

You will need to create a client to test your WebSocket server. You will want to test sending both text and binary messages. This can be accomplished with JavaScript.

Create the resources folder inside of the src/main folder. Inside of the resources folder, create the static folder.

Add the following to index.html inside of the src/main/resources/static folder:

<html>
<head>
    <style>
        #messages {
            text-align: left;
            width: 50%;
            padding: 1em;
            border: 1px solid black;
        }
    </style>
    <title>Sample WebSocket Client</title>
</head>
<body>
<div class="container">
    <div id="messages" class="messages"></div>
    <div class="input-fields">
        <p>Type a message and hit send:</p>
        <input id="message"/>
        <button id="send">Send</button>

        <p>Select an image and hit send:</p>
        <input type="file" id="file" accept="image/*"/>

        <button id="sendImage">Send Image</button>
    </div>
</div>
</body>
<script>
    const messageWindow = document.getElementById("messages");

    const sendButton = document.getElementById("send");
    const messageInput = document.getElementById("message");

    const fileInput = document.getElementById("file");
    const sendImageButton = document.getElementById("sendImage");

    const socket = new WebSocket("ws://localhost:8080/socket");
    socket.binaryType = "arraybuffer";

    socket.onopen = function (event) {
        addMessageToWindow("Connected");
    };

    socket.onmessage = function (event) {
        if (event.data instanceof ArrayBuffer) {
            addMessageToWindow('Got Image:');
            addImageToWindow(event.data);
        } else {
            addMessageToWindow(`Got Message: ${event.data}`);
        }
    };

    sendButton.onclick = function (event) {
        sendMessage(messageInput.value);
        messageInput.value = "";
    };

    sendImageButton.onclick = function (event) {
        let file = fileInput.files[0];
        sendMessage(file);
        fileInput.value = null;
    };

    function sendMessage(message) {
        socket.send(message);
        addMessageToWindow("Sent Message: " + message);
    }

    function addMessageToWindow(message) {
        messageWindow.innerHTML += `<div>${message}</div>`
    }

    function addImageToWindow(image) {
        let url = URL.createObjectURL(new Blob([image]));
        messageWindow.innerHTML += `<img src="${url}"/>`
    }
</script>
</html>

Now you will need to configure Spark to look for your index.html and to initialize the server when the application is run. You can also define the port on which the server will listen for connections.

Inside of the main method of the App class, add the following below webSocket:

staticFileLocation("static");
port(8080)
init();

Start the Application

Your WebSocket server is now complete. Start your application using the gradle run command inside of the application's directory.

You can access your application at http://localhost:8080 where you will be greeted with the following page:

The "connected" message indicates that the JavaScript client was able to make a connection.

Try sending a text message by typing into the input field and clicking on the send button. Also try uploading an image. In both instances, you should see the same message and image echoed back.

Conclusion

In this tutorial you learned how to create a WebSocket server using Spark which can receive both binary and text messages. The finished code for this tutorial can be found on the nexmo-community/websocket-spark-framework repository.

Want to implement WebSockets into your existing Spring application? Maybe you want to learn about Creating a WebSocket Server with Spring Boot?

No frameworks? No problem! Stay tuned for the next tutorial where I show you how to create a WebSocket server using the Java API for WebSockets.

Did you know that you can use WebSocket as an endpoint in a Nexmo Call Control Object? Look at this example on Streaming Calls to a Browser with Voice WebSockets.

Want to see an interesting use of WebSockets? Look at the nexmo-community/dtmf-snake repository to see some code which lets you play a game of snake using dual-tone multi-frequency signals.

Creating a WebSocket Server with Spring Boot

Steve Crow — Mon, 08 Oct 2018 15:19:15 +0000

In this series of posts, I'm going to show you three different ways to create a WebSocket server in Java using Spring Boot, the Spark Framework, and the Java API for WebSockets.

Prerequisites

You will be using Gradle to manage your dependencies and run your application.

Additionally, you'll need to make sure you have a copy of the JDK installed. I will be using JDK 8 in this tutorial.

WebSockets with Spring Boot

Spring Boot allows you to create production-grade Spring applications inside of a runnable JAR.

Create the Project

You can use Spring Initializr to bootstrap your application and select the packages that you need.

For this example, you will need the Websocket dependency. I'm also going to be using Gradle, so you will want to change it to generate a Gradle project.

Clicking the Generate Project button will download a zip file. Unzip this in a directory of your choosing.

Create the WebSocket Handler

WebSocket messages can be both text and binary. You're going to create a handler that can handle both of these messages.

Create a new class called WebSocketHandler which extends AbstractWebSocketHandler in the com.example.demo package. AbstractWebSocketHandler requires you to implement two methods, handleTextMessage and handleBinaryMessage which are called when a new text or binary message are received.

For demonstration purposes, you're going to create an echo server which will echo the message received back to the sender.

Add the following implementations:

@Override
protected void handleTextMessage(WebSocketSession session, TextMessage message) throws IOException {
    System.out.println("New Text Message Received");
    session.sendMessage(message);
}

@Override
protected void handleBinaryMessage(WebSocketSession session, BinaryMessage message) throws IOException {
    System.out.println("New Binary Message Received");
    session.sendMessage(message);
}

Register the WebSocket Handler

In order to use the WebSocketHandler, it must be registered in Spring's WebSocketHandlerRegistry. The following will accomplish two things:

It will register the WebSocketHandler on the /socket path.
It will allow all browser clients to send messages to the server. They won't be required to have a specific origin.

Create a new class called WebSocketConfiguration which implements the WebSocketConfigurer interface in the com.example.websocketdemo package.

Annotate WebSocketConfiguration with the @Configuration and @EnableWebSocket annotations.

WebSocketConfigurer requires you to implement a registerWebSocketHandlers method.

Add the following implementation to register WebSocketHandler:

@Override
public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
    registry.addHandler(new WebSocketHandler(), "/socket").setAllowedOrigins("*");
}

Since you will be dealing with binary messages in addition to text messages, it is a good idea to set the max binary message size. This is a value stored on the server container. You can override this value by injecting a new server container factory as part of your WebSocketConfiguration.

Add the following code to inject a new ServletServerContainerFactoryBean in WebSocketConfiguration above the registerWebSocketHandlers method you have previously added:

@Bean
public ServletServerContainerFactoryBean createWebSocketContainer() {
    ServletServerContainerFactoryBean container = new ServletServerContainerFactoryBean();
    container.setMaxBinaryMessageBufferSize(1024000);
    return container;
}

This will allow for an image up to 1 MB in size to be uploaded.

Create a Client to Test Your Application

You will need to create a client to test your WebSocket server. You will want to test sending both text and binary messages. This can be accomplished with JavaScript.

Add the following to index.html inside of the src/main/resources/static folder:

<html>
<head>
    <style>
        #messages {
            text-align: left;
            width: 50%;
            padding: 1em;
            border: 1px solid black;
        }
    </style>
    <title>Sample WebSocket Client</title>
</head>
<body>
<div class="container">
    <div id="messages" class="messages"></div>
    <div class="input-fields">
        <p>Type a message and hit send:</p>
        <input id="message"/>
        <button id="send">Send</button>

        <p>Select an image and hit send:</p>
        <input type="file" id="file" accept="image/*"/>

        <button id="sendImage">Send Image</button>
    </div>
</div>
</body>
<script>
    const messageWindow = document.getElementById("messages");

    const sendButton = document.getElementById("send");
    const messageInput = document.getElementById("message");

    const fileInput = document.getElementById("file");
    const sendImageButton = document.getElementById("sendImage");

    const socket = new WebSocket("ws://localhost:8080/socket");
    socket.binaryType = "arraybuffer";

    socket.onopen = function (event) {
        addMessageToWindow("Connected");
    };

    socket.onmessage = function (event) {
        if (event.data instanceof ArrayBuffer) {
            addMessageToWindow('Got Image:');
            addImageToWindow(event.data);
        } else {
            addMessageToWindow(`Got Message: ${event.data}`);
        }
    };

    sendButton.onclick = function (event) {
        sendMessage(messageInput.value);
        messageInput.value = "";
    };

    sendImageButton.onclick = function (event) {
        let file = fileInput.files[0];
        sendMessage(file);
        fileInput.value = null;
    };

    function sendMessage(message) {
        socket.send(message);
        addMessageToWindow("Sent Message: " + message);
    }

    function addMessageToWindow(message) {
        messageWindow.innerHTML += `<div>${message}</div>`
    }

    function addImageToWindow(image) {
        let url = URL.createObjectURL(new Blob([image]));
        messageWindow.innerHTML += `<img src="${url}"/>`
    }
</script>
</html>

Start the Application

Your WebSocket server is now complete. Start your application using the gradle bootRun command inside of the application's directory.

You can access your application at http://localhost:8080 where you will be greeted with the following page:

The "connected" message indicates that the JavaScript client was able to make a connection.

Try sending a text message by typing into the input field and clicking on the send button. Also try uploading an image. In both instances, you should see the same message and image echoed back.

Conclusion

In this tutorial you learned how to create a WebSocket server using Spring Boot which can receive both binary and text messages. The finished code for this tutorial can be found on the nexmo-community/websocket-spring-boot repository.

Have you tried out the Spark Framework? You might want to see how to Create a WebSocket server using the Spark Framework.

Did you know that you can use WebSocket as an endpoint in a Nexmo Call Control Object? Look at this example on Streaming Calls to a Browser with Voice WebSockets.

Interested in reading more about WebSockets? Check out this post on What are WebSockets? How Can They Enhance Digital Solutions?

Creating a Caller ID with Number Insight and Java

Steve Crow — Tue, 04 Sep 2018 11:01:15 +0000

Introduction

In this tutorial, you will create an application that can be used as a web-based caller ID. Your application will make requests to the Nexmo Number Insight API and display the results.

Feel free to refer to the nexmo-community/java-caller-id repository as you follow along.

git clone --branch getting-started git@github.com:nexmo-community/java-caller-id.git

Prerequisites

To work through this tutorial, you will need a Nexmo account. Sign up now if you don't already have an account.

During the sign-up process you will be assigned an API key and secret. You will need these in a later step of the tutorial.

You will be using Gradle to manage your dependencies and run your application. Additionally, you'll need to make sure you have a copy of the JDK installed.

Building a Caller ID with Java

This tutorial will walk you through the following steps:

Using Gradle to setup a new Java project.
Using the Spark framework to serve the caller ID page as well as processing number lookup requests.
Creating a front end which can be used to collect phone numbers to look up.

Using Gradle to Setup a New Java Project

You will use Gradle to manage your dependencies and to create and run your Java application.

The gradle init --type=java-application command will create all of the folders you will need as well as a sample class where you will be writing your code.

From the command line, create a new Java project with the following commands:

mkdir java-caller-id
cd java-caller-id
gradle init --type=java-application

Using the Spark Framework

You will use the Spark framework to both serve the caller ID page as well as process number lookup requests through an API.

Adding the Dependencies

Add the following to the dependencies block in your build.gradle file:

// Spark Framework
compile 'com.sparkjava:spark-core:2.7.2'

// Nexmo Java Client
compile 'com.nexmo:client:3.10.0'

// DotEnv
compile 'io.github.cdimascio:java-dotenv:3.1.1'

Creating the API Route

Gradle creates an App class in src/main/java containing getGreeting and main methods. Delete the getGreeting method as we don't need it.

Defining the Environment

Instead of hard-coding your Nexmo API key and secret, you will be storing it in an environment variable.

For the purpose of this demo you will be using the Dotenv library and a .env file.

Create a resources folder in src/main and create a file called .env with the following information:

NEXMO_API_KEY=your-api-key
NEXMO_API_SECRET=your-api-secret

Replace your-api-key and your-api-secret with your Nexmo API key and secret respectively.

Defining the Route

It can be helpful to store things as constants. You will instantiate a new NexmoClient using your NEXMO_API_KEY and NEXMO_API_SECRET defined earlier.

Additionally, you will define some constants that will be used in your Spark routing and an ObjectWriter which will be used to build the JSON response from your API.

Define the following constants and variables in App:

// Environment
private static final String KEY = Dotenv.load().get("NEXMO_API_KEY");
private static final String SECRET = Dotenv.load().get("NEXMO_API_SECRET");

private final InsightClient insightClient = new NexmoClient(new TokenAuthMethod(KEY, SECRET)).getInsightClient();
private final ObjectWriter writer = new ObjectMapper().writer();

Next, you will create a new method which will return a spark.Route. This route will accept a NUMBER_PARAM in the URL, perform a Nexmo Number Insight API request, and return a JSON response containing the AdvancedInsightResponse information.

Create the following method in App below the main method:

/**
* @return A {@link Route} which will handle looking up the number insight information.
*/
private Route createRequestRoute() {
    return (request, response) -> {
        final String number = request.params(NUMBER_PARAM);
        final AdvancedInsightResponse advancedInsightResponse = insightClient.getAdvancedNumberInsight(number,
                "",
                "",
                true
        );

        response.type(ContentType.APPLICATION_JSON.getMimeType());
        return this.writer.writeValueAsString(advancedInsightResponse);
    };
}

Register the Route

You need to configure Spark so that it knows when to use the route you just defined.

First you will configure the port that Spark runs on, and then you will configure the path that your newly-created route will answer to (/api/:number).

The path that you define will use the :number parameter which will represent a phone number inside of the route.

Add the following constant to App near all of the other constants you have created:

private static final int PORT = 3000;

private static final String NUMBER_PARAM = ":number";
private static final String REQUEST_ROUTE = "api/" + NUMBER_PARAM;

Add the following method to App above the createRequestRoute method:

/**
* Start the Sparkframework Application
*/
private void start() {
    Spark.port(PORT);
    Spark.get(REQUEST_ROUTE, createRequestRoute());
}

Now, you will change the main method in App in order to start Spark when the application is run.

Change the main method in App to the following:

public static void main(String[] args) {
    new App().start();
}

Start your application using the gradle run command.

You can now navigate to http://localhost:3000/api/13034997111 and should see a response similar to the following:

{
    "status": 0,
    "ported": "ASSUMED_NOT_PORTED",
    "roaming": {
        "status": "NOT_ROAMING",
        "roaming_country_code": null,
        "roaming_network_code": null,
        "roaming_network_name": null
    },
    "status_message": "Success",
    "error_text": null,
    "request_id": "bf845c39-d0e7-4004-bd68-b8bbadb3b5a6",
    "international_format_number": "13034997111",
    "national_format_number": "(303) 499-7111",
    "country_code": "US",
    "country_code_iso3": "USA",
    "country_name": "United States of America",
    "country_prefix": "1",
    "request_price": "0.04000000",
    "remaining_balance": "39.02969834",
    "original_carrier": {
        "name": "United States of America Landline",
        "country": "US",
        "network_code": "US-FIXED",
        "network_type": "LANDLINE"
    },
    "current_carrier": {
        "name": "United States of America Landline",
        "country": "US",
        "network_code": "US-FIXED",
        "network_type": "LANDLINE"
    },
    "caller_name": "Us Time & Frequency Division",
    "first_name": null,
    "last_name": null,
    "caller_type": "BUSINESS",
    "valid_number": "VALID",
    "reachable": "UNKNOWN",
    "lookup_outcome": 1,
    "lookup_outcome_message": "Partial success - some fields populated"
}

Storing Static Content

You will need a folder for holding your static content. This folder should go in the resources directory under src/main which you created earlier. A good convention is to name the folder public and to also put a css and js folder.

Add an index.html file to the public folder with the following content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Caller ID</title>
</head>
<body>
<h1>Hello World!</h1>
</body>
</html>

Serving Static Content

Static content is served out of a specific folder. You will create a constant to represent the location of this folder.

Define the following constants in App:

private static final String STATIC_FILE_LOCATION = "/public";

Now you will need to update Spark so that it knows to serve static content from this location.

Update the start method in App to the following:

/**
* Start the Spark Framework Application
*/
private void start() {
    Spark.staticFileLocation(STATIC_FILE_LOCATION);
    Spark.port(PORT);
    Spark.get(REQUEST_ROUTE, createRequestRoute());
}

Run the gradle run command.

This will start your application and start serving your index.html file at http://localhost:3000. Navigating to this address in your browser will display the Hello World text in the index.html page you previously made.

Building a User Interface

Now that you have Java and Spark performing requests to Nexmo Number Insight API and serving static content, it's time to move on to building a user interface.

Example User Interface

The following is one approach to a user interface. It uses JavaScript to make AJAX calls to the API you built in an earlier step. It then renders the information on the page. It also uses the cleave.js JavaScript library to format the phone number on input.

The result will produce the following page:

Create the Index Page

Replace your index.html with the following:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1,user-scalable=no">
    <link rel="stylesheet" href="css/style.css">
    <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.2.0/css/all.css"
          integrity="sha384-hWVjflwFxL6sNzntih27bfxkr27PmbbK/iSvJ+a4+0owXq79v+lsFkW54bOGbiDQ" crossorigin="anonymous">
    <title>Nexmo Caller ID</title>
</head>
<body>
<div class="nav">
    <div class="inner-nav">
        <h1>Nexmo Caller ID</h1>
    </div>
</div>
<div class="page">
    <div class="search">
        <div class="inner-search">
            <h1>Enter a phone number</h1>
            <div class="search-bar">
                <div class="search-bar-input">
                    <form>
                        <input type="text" class="phone-input" id="phone-number" placeholder="+1 123 456 7890"
                               autofocus>
                        <button class="form-button" id="look-up"><i class="fas fa-search"></i></button>
                    </form>
                </div>
            </div>
            <p>Searches are performed against the Nexmo Number Insight API</p>
        </div>
    </div>
    <div class="details" hidden></div>
</div>
<div class="footer">
    <div class="inner-footer">
        <ul>
            <li><a href="https://nexmo.com">Nexmo</a></li>
            <li><a href="https://developer.nexmo.com/number-insight/overview">Documentation</a></li>
        </ul>
    </div>
</div>
</body>
<script src="https://cdnjs.cloudflare.com/ajax/libs/cleave.js/1.4.2/cleave.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/cleave.js/1.4.2/addons/cleave-phone.i18n.js"></script>
<script src="js/app.js"></script>
</html>

Style the Index Page

Create style.css in the src/main/resources/public/css folder with the following content:

body, html {
    height: 100%;
    margin: 0;
    padding: 0;
    font-family: Lato, sans-serif;
    background-color: #deedf7;
    font-weight: 200;
}

form {
    display: flex;
}

h1, h2, h3, h4 {
    font-weight: 100;
    margin: .25em;
}

.inner-nav h1 {
    font-weight: 300;
    font-size: 3em;
}

.nav {
    background-color: #0077c8;
    color: #eef6fb;
}

.inner-nav {
    display: flex;
    width: 100%;
    max-width: 970px;
    margin: auto;
    justify-content: center;
}

.search {
    background: #0077c8;
    display: flex;
    text-align: center;
    width: 100%;
    flex-flow: column;
}

.details {
    background: #ffffff;
    display: flex;
    text-align: center;
    width: 100%;
    flex-flow: row;
    justify-content: center;
    flex-wrap: wrap;
}

.inner-details {
    text-align: left;
    border: 1px solid #deedf7;
    border-radius: 4px;
    margin: 0.25em;
    padding: 0.25em;
}

.inner-details h1 {
    border-bottom: 1px solid #deedf7;
}

.output-table {
    text-align: left;
}

.output-table .side-heading {
    font-weight: normal;
    text-align: left;
}

.output-table td {
    padding: 5px;
}

.inner-search {
    width: 100%;
    max-width: 970px;
    margin: auto;
    padding: 0 5px;
    color: #eef6fb;
}

.inner-search h1 {
    font-weight: 100;
}

.inner-search p {
    color: #fcfcfd;
    font-weight: 100;
}

.search-bar {
    position: relative;
    width: 100%;
    margin: auto;
    z-index: 50;
    max-width: 300px;
}

.search-bar-input {
    position: relative;
    z-index: 51;
    background: #ffffff;
    display: flex;
    text-align: center;
    height: 50px;
    border-radius: 5px;
}

.search-bar-input input {
    border: 0;
    background-color: transparent;
    display: block;
    width: 100%;
    font-size: 1.5em;
    padding: .5em 1em;
    font-weight: 100;
}

.search-bar-input input:focus, .search-bar-input button:focus {
    outline: none;
}

.search-bar-input button {
    background-color: transparent;
    border: 0;
    cursor: pointer;
    font-size: 1.5em;
    color: #0077c8;
}

.inner-footer ul {
    display: flex;
    flex-wrap: wrap;
    justify-content: center;
    list-style: none;

}

.inner-footer ul a {
    padding: 1em;
    font-size: 1em;
    text-decoration: none;
    display: flex;
    color: #717171;
}

Create the JavaScript

Create app.js in the src/main/resources/public/js folder with the following content:

let cleave = new Cleave('.phone-input', {
    phone: true,
    phoneRegionCode: 'US'
});

let lookUpButton = document.getElementById("look-up");
lookUpButton.onclick = function (event) {
    event.preventDefault();
    let phoneNumber = document.getElementById("phone-number").value.replace(/[^0-9.]/g, "");
    handlePhoneNumberLookup(phoneNumber);
};

function handlePhoneNumberLookup(phoneNumber) {
    fetch("/api/" + phoneNumber)
        .then(response => {
            if (response.ok) {
                return Promise.resolve(response);
            }

            return Promise.reject("Error Fetching Number Information");
        })
        .then(response => response.json())
        .then(data => {
            renderResponse(data);
        })
        .catch(function (error) {
            console.log("Error: " + error)
        })
}

function renderResponse(data) {
    let detailsContainer = document.getElementsByClassName("details")[0];
    detailsContainer.removeAttribute("hidden");
    detailsContainer.innerHTML = '';
    console.log(data);
    if (data.international_format_number && data.national_format_number) {
        detailsContainer.innerHTML += `
                <div class="inner-details">
                <h1>Number Details</h1>
                <table class="output-table">
                    <tr>
                        <td class="side-heading">International Format</td>
                        <td>${data.international_format_number}</td>
                    </tr>
                    <tr>
                        <td class="side-heading">National Format</td>
                        <td>${data.national_format_number}</td>
                    </tr>
                </table>
                </div>`;
    }

    if (data.caller_type && data.country_name) {
        detailsContainer.innerHTML += `
<div class="inner-details">
                <h1>Caller Details</h1>
                <table class="pure-table pure-table-bordered output-table">
                    <tr>
                        <td class="side-heading">Name</td>
                        <td>${data.caller_name || 'Unknown'}</td>
                    </tr>
                    <tr>
                        <td class="side-heading">Type</td>
                        <td>${data.caller_type}</td>
                    </tr>
                    <tr>
                        <td class="side-heading">Country</td>
                        <td>${data.country_name}</td>
                    </tr>
                </table></div>`
    }

    if (data.roaming && data.roaming.roaming_network_name && data.roaming.roaming_country_code) {
        detailsContainer.innerHTML += `
<div class="inner-details">
                <h1>Roaming Details</h1>
                <table class="output-table">
                    <tr>
                        <td class="side-heading">Network Name</td>
                        <td>${data.roaming.roaming_network_name}</td>
                    </tr>
                    <tr>
                        <td class="side-heading">Country Code</td>
                        <td>${data.roaming.roaming_country_code}</td>
                    </tr>
                </table></div>
            `
    }

    if (data.ported && data.original_carrier && data.current_carrier) {
        detailsContainer.innerHTML += `
<div class="inner-details">
    <h1>Porting Information</h1>
                <table class="output-table">
                    <tr>
                        <td class="side-heading">Status
                        </td>
                        <td>${data.ported}</td>
                    </tr>
                </table>
                <h2>Current Carrier</h2>
                <table class="output-table">
                    <tr>
                        <td class="side-heading">Name</td>
                        <td>${data.current_carrier.name}</td>
                    </tr>
                    <tr>
                        <td class="side-heading">Country</td>
                        <td>${data.current_carrier.country}</td>
                    </tr>
                </table>
                <h2>Original Carrier</h2>
                <table class="output-table">
                    <tr>
                        <td class="side-heading">Name</td>
                        <td>${data.original_carrier.name}</td>
                    </tr>
                    <tr>
                        <td class="side-heading">Country</td>
                        <td>${data.original_carrier.country}</td>
                    </tr>
                </table></div>
            `
    }
}

Test Your Final Application

Start your application with the gradle run command inside of your java-caller-id directory. Navigate to http://localhost:3000 and you will be ready to gain insight.

Conclusion

The Nexmo Number Insight API is a powerful tool for gaining useful information on numbers. It uses a vast amount of real-time data from carrier databases and Nexmo databases to give you the most accurate set of information.

Explore other ways that you might use the Nexmo Number Insight API. Think about what other services you can integrate it with.

Check out our documentation on Nexmo Developer where you can learn more about the Nexmo Number Insight API and other Nexmo offerings. See our Nexmo Quickstart Examples for Java for full code examples on this tutorial and more.

Handle Keypad Input (DTMF) with Java

Steve Crow — Wed, 15 Aug 2018 18:54:33 +0000

Introduction

In a previous tutorial, we showed you how to create an application that can Receive a Phone Call with Java. In this tutorial, you will create an application that can receive a phone call and respond to user input using the Nexmo Voice API.

Prerequisites

To work through this tutorial, you will need a Nexmo account. Sign up now if you don't already have an account.

You will be using Gradle to manage your dependencies and run your application. Additionally, you'll need to make sure you have a copy of the JDK installed. I will be using JDK 8 in this tutorial.

Finally, you'll need the Nexmo CLI installed. You'll use it to purchase a phone number and configure your Nexmo account to point at your new application.

Handle User Input with Java

This tutorial will walk you through the following steps:

Using Gradle to setup a new Java project.
Using the Spark framework for controlling the call.
Purchasing a number and configuring your Nexmo account to use that number with your application.

Using Gradle to Setup a New Java Project

You will use Gradle to manage your dependencies and to create and run your Java application. From the command line, create a new Java project with the following commands:

mkdir handle-user-input
cd handle-user-input
gradle init --type java-application

The gradle init --type java-application command will create all of the folders you will need as well as a sample class where you will write your code.

Using the Spark Framework for Controlling the Call

You will use the Spark framework to intercept the HTTP call that Nexmo uses when your number receives a call, and for the request that Nexmo sends when input is received.

Adding the Dependencies

Add the following to your dependencies block in your build.gradle file:

compile 'com.sparkjava:spark-core:2.7.2'
compile 'com.nexmo:client:4.0.1'

Your dependencies block should look like this:

dependencies {
    // This dependency is found on compile classpath of this component and consumers.
    compile 'com.google.guava:guava:23.0'
    compile 'com.sparkjava:spark-core:2.7.2'
    compile 'com.nexmo:client:4.0.1'

    // Use JUnit test framework
    testCompile 'junit:junit:4.12'
}

Setup the Answer Route

Gradle will create the App class in the src/main/java folder. Inside of this class is a getGreeting and a main method. You won't need the getGreeting method, so feel free to remove it.

Replace the contents of the main method, resolving any imports, with:

/*
* Route to answer incoming calls.
*/
Route answerRoute = (req, res) -> {
    TalkAction intro = new TalkAction
            .Builder("Hello. Please press any key to continue.")
            .build();

    InputAction input = new InputAction.Builder()
            .eventUrl(String.format("%s://%s/webhooks/dtmf", req.scheme(), req.host()))
            .maxDigits(1)
            .build();


    res.type("application/json");

    return new Ncco(intro, input).toJson();
};

/*
* Route to print out call event info.
*/
Route eventRoute = (req, res) -> {
    System.out.println(req.body());
    return "";
};

Spark.port(3000);
Spark.get("/webhooks/answer", answerRoute);
Spark.post("/webhooks/events", eventRoute);

This code will setup a route on http://localhost:3000/webhooks/answer which will respond with the following Nexmo Call Control Object (NCCO):

[
  {
    "text": "Hello please press any key to continue.",
    "action": "talk"
  },
  {
    "maxDigits": 1,
    "action": "input",
    "eventUrl": [
      "http://localhost:3000/webhooks/dtmf"
    ]
  }
]

The talk action will instruct Nexmo to speak the text property back to the caller. The input action will instruct Nexmo to capture a single digit that the caller inputs and to send a POST request to eventUrl with this information.

A route will also be setup on http://localhost:3000/webhooks/events which Nexmo will use to communicate call status changes.

Setup the DTMF Route

When the caller presses a digit on their device, a Dual-Tone Multi-Frequency (DTMF) signal is created. Nexmo uses this DTMF signal to determine which set of keys were pressed. Once this happens, Nexmo sends a POST request to the eventUrl defined in the InputNcco.

Here is an example of the POST request which contains a JSON body:

{
    "dtmf": "5",
    "timed_out": false,
    "uuid": "some-uuid",
    "conversation_uuid": "some-conversation",
    "timestamp": "2018-08-14T19:59:02.528Z"
}

In order to read this information in Java, you will need to a class which will map the JSON properties to Java properties. The Nexmo Java Client Library contains the InputEvent class for handing this mapping.

In the main method of the App class add the following route below the eventRoute:

/*
* Route which returns NCCO saying which DTMF code was received.
*/
Route inputRoute = (req, res) -> {
    InputEvent event = InputEvent.fromJson(req.body());

    TalkAction response = new TalkAction
            .Builder(String.format("You pressed %s, Goodbye.", event.getDtmf()))
            .build();

    res.type("application/json");

    return new Ncco(response).toJson();
};

Next, register the route by adding the following at the end of the main method:

Spark.post("/webhooks/dtmf", inputRoute);

This route will respond with the following NCCO:

[
  {
    "text": "You pressed 6, Goodbye.",
    "action": "talk"
  }
]

where 6 is the dtmf property of the json sent to /webhooks/dtmf.

Purchasing a Number

You will need a Nexmo number in order to receive phone calls. If you do not have a number you can use the Nexmo CLI to purchase one:

nexmo number:buy --country_code US

Take note of the number that is assigned to you on purchase. You will need this number to link your application and for testing.

Exposing Your Application

In order to send an HTTP request to your application, Nexmo needs to know the URL that your application is running on.

Instead of configuring your local network or hosting your application on an external service, you can use ngrok to safely expose your application to the internet.

Download ngrok and run the following command:

ngrok http 3000

Take note of the forwarding address as you will need it when you configure your account. In the following picture, the forwarding address is http://99cad2de.ngrok.io.

Configure Your Nexmo Account

If you do not have an application you can use the Nexmo CLI to create one using your ngrok forwarding address:

nexmo app:create "Receive Call Demo" http://your-ngrok-forwarding-address/webhooks/answer http://your-ngrok-forwarding-address/webhooks/events --keyfile private.key

After running this command, you will be shown an an application id. For example: notreal-1111-2222-3333-appid. You will need this application id to link your phone number to the application.

You can use the Nexmo CLI to link your phone number and application:

nexmo link:app your-nexmo-phone-number your-application-id

Test Your Application

Start your application with the gradle run command inside of your handle-user-input directory.

Make a call to your Nexmo number and test out your application. You will hear the message, "Hello please press any key to continue." Press a digit on your phone's keypad and you will then hear the message, "You pressed 6, Goodbye" where 6 is the number that you pressed.

Conclusion

In a few lines of code you have created an application that can receive a phone call, capture user input, and respond with that input. Experiment with other ways you can use a user's input to control the call.

DEV Community: Steve Crow

Quick Tip: Kotlin, Spring Data, and Optionals

Quick Tip: Kotlin Extension Functions and Spring Data

What is Optional ?

What are extension functions?

Extending Spring Data

Conclusion

Publish Vonage Events to Kafka with Spring Boot

What are the Vonage Communication APIs?

What is Kafka?

Download the Demo Application

Initialize a New Spring Boot Application

Create a Webhook

Configure the Event URL

Create a Controller

Setting up Kafka

Create a Cluster

Create a Topic

Connecting a Spring Boot Application to Kafka

Produce Messages from Spring Boot

Consuming Kafka Messages Using the CLI

Start Everything

Conclusion

Multiple JPA Data Sources with Spring Boot and Kotlin

Create a New Spring Boot Project

Create the Entities

Create the Animal Entity

Create the Worker Entity

Add Database Configuration to application.properties

Register the Database Connections

Create the Farm Data Source Configuration

Create the Factory Data Source Configuration

More Detail

Summary

Make Text-to-Speech Phone Call with Java

Introduction

Prerequisites

Make Text-to-Speech Phone Call with Java

Purchasing a Number

Configure Your Nexmo Account

Using Gradle to Set Up a New Java Project

Add the Dependencies

Initialize the Nexmo Client

Build the Nexmo Call Control Object

Make the Phone Call

Test Your Application

Conclusion

Record a Phone Message with Java

Introduction

Prerequisites

Record a Phone Message with Java

Using Gradle to Setup a New Java Project

Using the Spark Framework for Controlling the Call

Adding the Dependencies

Define the Answer Route

Define the Recordings Route

Register the Routes

Purchasing a Number

Exposing Your Application

Configure Your Nexmo Account

Test Your Application

Conclusion

Send SMS with GitHub Actions

Prerequisites

What is GitHub Actions?

Creating Your First Workflow

Create a Repository

Create a New Workflow

Link the Action Trigger to an Action

Conclusion

Tracking Santa with SMS and Java

See it in Action

The Initial Message

Location Lookup

Getting More Technical

Routing Incoming Messages

Handling the Various Stages

Getting the Country Code

Lookup for Postal Codes

Calculating Distance

Add Database Configuration to `application.properties`