Exercise - Configure applications to send or receive messages through an event hub

Completed

You're now ready to configure your publisher and consumer applications for your event hub.

In this unit, you configure applications to send or receive messages through your event hub. One application acts as the message sender (SimpleSend), the other as the message receiver (EventProcessorSample). The applications are stored in a GitHub repository.

Create a general-purpose, standard storage account

The Java receiver application stores messages in Azure Blob Storage, which requires a storage account. To create a storage account (general-purpose V2), use the storage account create command. We define the following parameters for this command:

Parameter	Description
name (required)	A name for your storage account.
resource-group (required)	The resource group owner is the sandbox resource group, which is already defined as a default value.
location (optional)	Region is already defined as a default value, but you can include it if you want to set a different region from the default resource group location.
sku	The default SKU value of the storage account is Standard_RAGRS. But in this exercise, we specify that value.

In the previous exercise, we defined default values for resource group and location, so we can omit those parameters from the command.

1. In Azure Cloud Shell, set the storage account name to a variable. A storage account name must be unique within Azure and must contain 3 to 24 numbers or lower-case letters.

   STORAGE_NAME=storagename$RANDOM
   

2. Run the following command to create the storage account.

   az storage account create --name $STORAGE_NAME --sku Standard_RAGRS --encryption-service blob
   

   Tip

   It can take a moment to create this storage account. If storage account creation fails, change your environment variable, and try again.

3. Run the following command to obtain the access keys associated with your storage account.

   az storage account keys list --account-name $STORAGE_NAME
   

4. Two keys associated with your storage account are output in JSON format. Copy and save the value of key1 for future use. You need this key to access your storage account.

5. Run the following command to obtain the connection string for your storage account.

   az storage account show-connection-string -n $STORAGE_NAME
   

6. The output contains the connection details for your storage account. Copy and save the value of connectionString. It should look something like this:

   "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName=storage_account_name;AccountKey=xxxxxxxxxxx"
   

7. Run the following command to create a container called messages in your storage account. Use the connectionString value you copied in the previous step.

   az storage container create --name messages --connection-string "<connection string here>"
   

Clone the event hubs GitHub repository

The source files for the applications that you build in this unit are located in a GitHub repository.

1. Launch GitBash on your computer.

2. Run the following command to clone the Git project solution:

   cd ~
   git clone https://github.com/Azure/azure-event-hubs.git
   

3. Launch VS Code on your computer.

Edit SimpleSend.java that sends events to the event hub

In this exercise, you use Visual Studio Code (VS Code) to modify the SimpleSend application. You need to add your Event Hubs namespace, event hub name, shared access policy name, and primary key.

1. Launch VS Code.

2. Select File -> Open Folder, and select the SimpleSend folder under c:/users/USERID/azure-event-hubs/samples/java/basic.

3. In the Code Explorer in the left pane, double-click SimpleSend.java to open it in the editor.

4. In the editor, locate and replace the following strings under `ConnectionStringBuilder``:

   • <EVENT HUBS NAMESPACE - CONNECTION STRING> with the connection string to your Event Hubs namespace.
   • <EVENT HUB NAME> with the name of your event hub.

   For your primary SAS key, when you create an Event Hubs namespace, a 256-bit SAS key called RootManageSharedAccessKey is created and includes primary and secondary keys that grant send, listen, and manage rights to the namespace. Earlier in this exercise, you obtained the key by running an Azure CLI command; however, you can also find the keys and connection strings by selecting your Event Hubs namespace in the Azure portal, and then in the menu under the Settings, select Shared access policies; now select the policy name RootManageSharedAccessKey to display the SAS Policy keys.

5. Save the SimpleSend.java file.

Use Maven to build SimpleSend.java

Now, you build the Java application by running mvn commands.

1. In the Code Explorer, right-click SimpleSend.java, and select Open in Integrated Terminal.

2. Enter the following command to navigate to the main SimpleSend folder.

   cd ~/azure-event-hubs/samples/Java/Basic/SimpleSend
   

3. Build the Java SimpleSend application. This command builds your application using the connection details for your event hub.

   mvn clean package -DskipTests
   

   The build process can take several minutes to complete. Ensure that you see the [INFO] BUILD SUCCESS message before continuing.

   

Edit EventProcessorSample.java that receives events to the event hub

You now configure a receiver (also known as a subscriber or consumer) application to ingest data from your event hub.

For the receiver application, two classes are available: EventHubReceiver and EventProcessorClient. EventProcessorClient is built on top of EventHubReceiver, but provides a simpler programmatic interface than EventHubReceiver. EventProcessorClient can automatically distribute message partitions across multiple instances of EventProcessorClient using the same storage account.

In this procedure, you use the EventProcessorClient method. You edit the EventProcessorSample application to add the following values: Your Event Hubs namespace, event hub name, shared access policy name and primary key, storage account name, connection string, and container name.

1. Launch another instance of the VS Code.

2. Select File -> Open Folder, and select the EventProcessorSample folder under c:/users/USERID/azure-event-hubs/samples/java/basic.

3. In the Code Explorer in the left pane, double-click EventProcessorSample.java to open it in the editor.

4. In the editor, locate and replace the following strings in the editor:

   • <EVENT HUBS NAMESPACE - CONNECTION STRING> - connection string to the Event Hubs namespace.
   • <EVENT HUB NAME> - name of the event hub.
   • <AZURE STORAGE - CONNECTION STRING> - connection string to the Azure Storage account.
   • Confirm that the blob container name is messages. If you're using a different name for the container, use that name.

5. Save EventProcessorSample.java.

Use Maven to build EventProcessorSample.java

1. In the Code Explorer, right-click EventProcessorSample.java, and select Open in Integrated Terminal.

2. Change to the main EventProcessorSample folder by running the following command.

   cd ~/azure-event-hubs/samples/Java/Basic/EventProcessorSample
   

3. Build the Java SimpleSend application by running the following command to ensure that your application uses the connection details for your event hub.

   mvn clean package -DskipTests
   

   The build process can take several minutes to complete. Ensure that you see a [INFO] BUILD SUCCESS message before continuing.

   

Start the sender and receiver apps

1. Start the EventProcessorSample application by running the following command.

   cd ~/azure-event-hubs/samples/Java/Basic/EventProcessorSample
   java -jar ./target/eventprocessorsample-1.0.0-jar-with-dependencies.jar
   

2. Switch to the VS Code window that has the sending application (SimpleSend) code open. In the integrated terminal, run the Java application from the command line by running the following java command, and specifying a .jar package.

   cd ~/azure-event-hubs/samples/Java/Basic/SimpleSend
   java -jar ./target/simplesend-1.0.0-jar-with-dependencies.jar
   

3. When you see Send Complete..., Enter to stop the application.

   jar-with-dependencies.jar
   SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
   SLF4J: Defaulting to no-operation (NOP) logger implementation
   SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
   2018-09-18T19:42:15.146Z: Send Complete...
   

4. In the VS Code with the receiver application running, verify that you see messages. Press Enter or press CTRL+C to end the program.

   ...
   SAMPLE: Partition 0 checkpointing at 1064,19
   SAMPLE (3,1120,20): "Message 80"
   SAMPLE (3,1176,21): "Message 84"
   SAMPLE (3,1232,22): "Message 88"
   SAMPLE (3,1288,23): "Message 92"
   SAMPLE (3,1344,24): "Message 96"
   SAMPLE: Partition 3 checkpointing at 1344,24
   SAMPLE (2,1120,20): "Message 83"
   SAMPLE (2,1176,21): "Message 87"
   SAMPLE (2,1232,22): "Message 91"
   SAMPLE (2,1288,23): "Message 95"
   SAMPLE (2,1344,24): "Message 99"
   SAMPLE: Partition 2 checkpointing at 1344,24
   SAMPLE: Partition 1 batch size was 3 for host mystorageacct2018-46d60a17-7060-4b53-b0e0-cca70c970a47
   SAMPLE (0,1120,20): "Message 81"
   SAMPLE (0,1176,21): "Message 85"
   SAMPLE: Partition 0 batch size was 10 for host mystorageacct2018-46d60a17-7060-4b53-b0e0-cca70c970a47
   SAMPLE: Partition 0 got event batch
   SAMPLE (0,1232,22): "Message 89"
   SAMPLE (0,1288,23): "Message 93"
   SAMPLE (0,1344,24): "Message 97"
   SAMPLE: Partition 0 checkpointing at 1344,24
   SAMPLE: Partition 3 batch size was 8 for host mystorageacct2018-46d60a17-7060-4b53-b0e0-cca70c970a47
   SAMPLE: Partition 2 batch size was 9 for host mystorageacct2018-46d60a17-7060-4b53-b0e0-cca70c970a47
   SAMPLE: Partition 0 batch size was 3 for host mystorageacct2018-46d60a17-7060-4b53-b0e0-cca70c970a47
   

Summary

In this unit, you configured a sender application ready to send messages to your event hub. You also configured a receiver application ready to receive messages from your event hub.