Skip to content

Commit

Permalink
Adds README and other smaller fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
joaoandremartins committed Jul 14, 2017
1 parent a06cd45 commit 43ef2e8
Show file tree
Hide file tree
Showing 4 changed files with 152 additions and 1 deletion.
144 changes: 144 additions & 0 deletions spring/pubsub/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
# Getting started with Spring Integration channel adapters for Google Cloud Pub/Sub

This comment has been minimized.

Copy link
@meltsufin

meltsufin Jul 14, 2017

Member

I think we need a build and run section.


This is a sample application that uses Spring Integration and Spring Boot to read and write messages
to Google Cloud Pub/Sub.

PubsubApplication is a typical Spring Boot application. We declare all the necessary beans for the
application to work in the `PubsubApplication` class. The most important ones are the inbound and
outbound channel adapters.

## Channel adapters

On Spring Integration, channel adapters are adapters that send or receive messages from external
systems, convert them to/from an internal Spring message representation and read/write them to a
Spring channel, which can then have other components attached to it, such as service activators.

### Inbound channel adapter

PubsubInboundChannelAdapter is Spring Cloud GCP Pub/Sub inbound channel adapter class. It's declared
in the user app as follows:

```
@Bean
public PubsubInboundChannelAdapter messageChannelAdapter(
@Qualifier("pubsubInputChannel") MessageChannel inputChannel,
SubscriberFactory subscriberFactory) {
PubsubInboundChannelAdapter adapter =
new PubsubInboundChannelAdapter(subscriberFactory, "messages");
adapter.setOutputChannel(inputChannel);
adapter.setAckMode(AckMode.MANUAL);
return adapter;
}
```

In the example, we instantiate the `PubsubInboundChannelAdapter` object with a SubscriberFactory and
a Google Cloud Pub/Sub subscription name, from where the adapter listens to messages, and then set
its output channel and ack mode.

In apps which use the Spring Cloud GCP Pubsub Boot starter, a SubscriberFactory is automatically
provided. The subscription name (e.g., `"messages"`) is the name of a Google Cloud Pub/Sub
subscription that must already exist when the channel adapter is created.

The input channel is a channel in which messages get into Spring from an external system.
In this example, we use a PublishSubscribeChannel, which broadcasts incoming messages to all its
subscribers, including service activators.

```
@Bean
public MessageChannel pubsubInputChannel() {
return new PublishSubscribeChannel();
}
```

Setting the acknowledgement mode on the inbound channel adapter is optional. It is set to automatic
by default. If set to manual, messages must be explicitly acknowledged through the
`AckReplyConsumer` object from the Spring message header `GcpHeader.ACKNOWLEDGEMENT`.

```
AckReplyConsumer consumer =
(AckReplyConsumer) message.getHeaders().get(GcpHeaders.ACKNOWLEDGEMENT);
consumer.ack();
```

A service activator is typically attached to a channel in order to process incoming messages. Here
is an example of a service activator that logs and acknowledges the received message.

```
@Bean
@ServiceActivator(inputChannel = "pubsubInputChannel")
public MessageHandler messageReceiver1() {
return message -> {
LOGGER.info("Message arrived! Payload: "
+ ((ByteString) message.getPayload()).toStringUtf8());
AckReplyConsumer consumer =
(AckReplyConsumer) message.getHeaders().get(GcpHeaders.ACKNOWLEDGEMENT);
consumer.ack();
};
}
```

### Outbound channel adapter

PubSubMessageHandler is Spring Cloud GCP's Pub/Sub outbound channel adapter. It converts Spring
messages in a channel to an external representation and sends them to a Google Cloud Pub/Sub topic.

```
@Bean
@ServiceActivator(inputChannel = "pubsubOutputChannel")
public MessageHandler messageSender(PubsubTemplate pubsubTemplate) {
PubsubMessageHandler outboundAdapter = new PubsubMessageHandler(pubsubTemplate);
outboundAdapter.setTopic("test");
return outboundAdapter;
}
```

`PubsubTemplate` is Spring Cloud GCP's abstraction to send messages to Google Cloud Pub/Sub. It
contains the logic to create a Google Cloud Pub/Sub `Publisher`, convert Spring messages to Google
Cloud Pub/Sub `PubsubMessage` and publish them to a topic.

`PubsubMessageHandler` requires a `PubsubTemplate` to be instantiated. The Spring Cloud GCP Boot
Pubsub starter provides a pre-configured `PubsubTemplate`, ready to use. `PubsubMessageHandler`
also requires the name of a Google Cloud Pub/Sub topic, which must exist before any messages are
sent.

We use a messaging gateway to write to a Spring channel.

```
@MessagingGateway(defaultRequestChannel = "pubsubOutputChannel")
public interface PubsubOutboundGateway {
void sendToPubsub(String text);
}
```

Spring auto-generates the output channel, as well as the gateway code and injects it to the local
variable in `WebAppController`.

```
@Autowired
private PubsubOutboundGateway messagingGateway;
```

## Administration

The Spring Cloud GCP Pubsub package provides a Google Cloud Pub/Sub administration utility,
`PubsubAdmin`, to simplify the creation, listing and deletion of Google Cloud Pub/Sub topics and
subscriptions. The Spring Cloud GCP Pubsub starter provides a pre-configured `PubsubAdmin`, based on
an application's properties.

```
@Autowired
private PubsubAdmin admin;
```

## Sample application

This sample application uses Spring Boot and Spring Web to declare a REST controller. The front-end
uses client-side scripting with Angular.

It is exemplified how to:
* Send messages to a Google Cloud Pub/Sub topic through an outbound channel adapter;
* Receive and process messages from a Google Cloud Pub/Sub subscription through an inbound channel
adapter;
* Create new Google Cloud Pub/Sub topics and subscriptions through the Pub/Sub admin utility.
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,9 @@ public class PubsubApplication {
public static void main(String[] args) throws IOException {
SpringApplication.run(PubsubApplication.class, args);
}

// Inbound channel adapter.

/**
* Spring channel for incoming messages from Google Cloud Pub/Sub.
*
Expand Down Expand Up @@ -115,6 +118,8 @@ public MessageHandler messageReceiver2() {
};
}

// Outbound channel adapter

/**
* The outbound channel adapter to write messages from a Spring channel to a Google Cloud Pub/Sub
* topic.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ public class WebAppController {
@Autowired
private PubsubOutboundGateway messagingGateway;

@Autowired private PubsubAdmin admin;
@Autowired
private PubsubAdmin admin;

/**
* Lists every topic in the project.
Expand Down
1 change: 1 addition & 0 deletions spring/pubsub/src/main/resources/application.properties
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,5 @@
#spring.cloud.gcp.credentialsLocation=file:[LOCAL_PATH_TO_CREDENTIALS]
#
#spring.cloud.gcp.pubsub.subscriber.executorThreads=[SUBSCRIBER_THREADS]
#spring.cloud.gcp.pubsub.subscriber.ackDeadline=[ACK_DEADLINE_SECONDS]
#spring.cloud.gcp.pubsub.publisher.executorThreads=[PUBLISHER_THREADS]

0 comments on commit 43ef2e8

Please sign in to comment.