Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

release changes - for version 0.11.0 #63

Merged
merged 2 commits into from
Feb 24, 2017
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 17 additions & 18 deletions ConsumingEvents.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ following dependency declaration inside of your Maven project file:
<dependency>
<groupId>com.microsoft.azure</groupId>
<artifactId>azure-eventhubs-clients</artifactId>
<version>0.10.0</version>
<version>0.11.0</version>
</dependency>
```

Expand All @@ -57,28 +57,27 @@ The receiver code creates an *EventHubClient* from a given connecting string
final String sasKey = "---SharedAccessSignatureKey----";
ConnectionStringBuilder connStr = new ConnectionStringBuilder(namespaceName, eventHubName, sasKeyName, sasKey);

EventHubClient ehClient = EventHubClient.createFromConnectionString(connStr.toString()).get();
EventHubClient ehClient = EventHubClient.createFromConnectionStringSync(connStr.toString());
```

The receiver code then creates (at least) one *PartitionReceiver* that will receive the data. The receiver is seeded with
an offset, in the snippet below it's simply the start of the log.
The receiver code then creates (at least) one *PartitionReceiver* that will receive the data. The receiver is seeded with an offset, in the snippet below it's simply the start of the log.

```Java
String partitionId = "0"; // API to get PartitionIds will be released soon
PartitionReceiver receiver = ehClient.createReceiver(
String partitionId = "0";
PartitionReceiver receiver = ehClient.createReceiverSync(
EventHubClient.DefaultConsumerGroupName,
partitionId,
PartitionReceiver.StartOfStream,
false).get();
false);

receiver.setReceiveTimeout(Duration.ofSeconds(5));
receiver.setReceiveTimeout(Duration.ofSeconds(20));
```

Once the receiver is initialized, getting events is just a matter of calling the *receive()* method in a loop. Each call
to *receive()* will fetch an iterable batch of events to process.

```Java
Iterable<EventData> receivedEvents = receiver.receive(maxEventCount).get();
Iterable<EventData> receivedEvents = receiver.receiveSync(maxEventCount);
```

##Consumer Groups
Expand Down Expand Up @@ -111,20 +110,20 @@ begin receiving events:
after the given instant.

``` Java
PartitionReceiver receiver = ehClient.createReceiver(
PartitionReceiver receiver = ehClient.createReceiverSync(
EventHubClient.DefaultConsumerGroupName,
partitionId,
Instant.now()).get();
Instant.now());
```
3. **Absolute offset** This option is commonly used to resume receiving events after a previous receiver on the partition
has been aborted or suspended for any reason. The offset is a system-supplied string that should not be interpreted by
the application. The next section will discuss scenarios for using this option.

``` Java
PartitionReceiver receiver = ehClient.createReceiver(
PartitionReceiver receiver = ehClient.createReceiverSync(
EventHubClient.DefaultConsumerGroupName,
partitionId,
savedOffset).get();
savedOffset);
```


Expand Down Expand Up @@ -162,11 +161,11 @@ That mechanism is called **epochs**. An epoch is an integer value that acts as a

``` Java
epochValue = 1
PartitionReceiver receiver1 = ehClient.createEpochReceiver(
PartitionReceiver receiver1 = ehClient.createEpochReceiverSync(
EventHubClient.DefaultConsumerGroupName,
partitionId,
savedOffset,
epochValue).get();
epochValue);
```

When a new partition owner takes over, it creates a receiver for the same partition, but with a greater epoch value. This will instantly
Expand All @@ -175,14 +174,14 @@ That mechanism is called **epochs**. An epoch is an integer value that acts as a
``` Java
/* obtain checkpoint data */
epochValue = 2
PartitionReceiver receiver2 = ehClient.createEpochReceiver(
PartitionReceiver receiver2 = ehClient.createEpochReceiverSync(
EventHubClient.DefaultConsumerGroupName,
partitionId,
savedOffset,
epochValue).get();
epochValue);
```

The new leader obviously also needs to know at which offset processing shall continue. For this, the current owner of a partition should
The new reader obviously also needs to know at which offset processing shall continue. For this, the current owner of a partition should
periodically record its progress on the event stream to a shared location, tracking the offset of the last processed message. This is
called "checkpointing". In case of the aforementioned Azure Blob lease election model, the blob itself is a great place to keep this information.

Expand Down
17 changes: 8 additions & 9 deletions PublishingEvents.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ following dependency declaration inside of your Maven project file:
<dependency>
<groupId>com.microsoft.azure</groupId>
<artifactId>azure-eventhubs-clients</artifactId>
<version>0.10.0</version>
<version>0.11.0</version>
</dependency>
```

Expand Down Expand Up @@ -40,20 +40,19 @@ Using an Event Hub connection string, which holds all required connection inform
final String sasKey = "---SharedAccessSignatureKey----";
ConnectionStringBuilder connStr = new ConnectionStringBuilder(namespaceName, eventHubName, sasKeyName, sasKey);

EventHubClient ehClient = EventHubClient.createFromConnectionString(connStr.toString()).get();
EventHubClient ehClient = EventHubClient.createFromConnectionStringSync(connStr.toString());
```

Once you have the client in hands, you can package any arbitrary payload as a plain array of bytes and send it. The samples
we use to illustrate the functionality send a UTF-8 encoded JSON data, but you can transfer any format you wish.

```Java
EventData sendEvent = new EventData(payloadBytes);
ehClient.send(sendEvent).get();
ehClient.sendSync(sendEvent);
```

The entire client API is built for Java 8's concurrent task model, generally returning
[*CompletableFuture<T>*](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html), so the
*.get()* suffixing the operations in the snippets above just wait until the respective operation is complete.
[*CompletableFuture<T>*](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html), so the library has these methods suffixed with *Sync* as their Synchronous counterparts/varaints.

##AMQP 1.0
Azure Event Hubs allows for publishing events using the HTTPS and AMQP 1.0 protocols. The Azure Event Hub endpoints
Expand Down Expand Up @@ -126,7 +125,7 @@ The gesture is a straightforward extra override to the send operation supplying

```Java
EventData sendEvent = new EventData(payloadBytes);
> ehClient.send(sendEvent, partitionKey).get();
> ehClient.sendSync(sendEvent, partitionKey);
```

####Using Partition Ids
Expand All @@ -136,10 +135,10 @@ you can send directly to the partition, but doing so requires an extra gesture s
option. To send to a partition you explicitly need to create a client object that is tued to the partition as shown below:

```Java
EventHubClient ehClient = EventHubClient.createFromConnectionString(str).get();
> EventHubSender sender = ehClient.createPartitionSender("0").get();
EventHubClient ehClient = EventHubClient.createFromConnectionStringSync(str);
> EventHubSender sender = ehClient.createPartitionSenderSync("0");
EventData sendEvent = new EventData(payloadBytes);
sender.send(sendEvent).get();
sender.sendSync(sendEvent);
```

#### Publisher Policies
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ private ClientConstants() { }
public final static String DEFAULT_RETRY = "Default";

public final static String PRODUCT_NAME = "MSJavaClient";
public final static String CURRENT_JAVACLIENT_VERSION = "0.11.0-SNAPSHOT";
public final static String CURRENT_JAVACLIENT_VERSION = "0.11.0";

public static final String PLATFORM_INFO = getPlatformInfo();

Expand Down
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
<properties>
<proton-j-version>0.16.0</proton-j-version>
<junit-version>4.12</junit-version>
<client-current-version>0.11.0-SNAPSHOT</client-current-version>
<client-current-version>0.11.0</client-current-version>
</properties>

<build>
Expand Down
21 changes: 10 additions & 11 deletions readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,19 +62,18 @@ you then create an *EventHubClient* instance, which manages a secure AMQP 1.0 co
final String sasKey = "---SharedAccessSignatureKey----";
ConnectionStringBuilder connStr = new ConnectionStringBuilder(namespaceName, eventHubName, sasKeyName, sasKey);

EventHubClient ehClient = EventHubClient.createFromConnectionString(connStr.toString()).get();
EventHubClient ehClient = EventHubClient.createFromConnectionStringSync(connStr.toString());
```

Once you have the client in hands, you can package any arbitrary payload as a plain array of bytes and send it.

```Java
EventData sendEvent = new EventData(payloadBytes);
ehClient.send(sendEvent).get();
ehClient.sendSync(sendEvent);
```

The entire client API is built for Java 8's concurrent task model, generally returning
[*CompleteableFuture<T>*](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html), so the
*.get()* suffixing the operations in the snippets above just wait until the respective operation is complete.
[*CompleteableFuture<T>*](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html), so the library has these methods suffixed with *Sync* as their Synchronous counterparts/varaints.

Learn more about publishing events, including advanced options, and when you should and shouldn't use those options,
[in the event publisher guide](PublishingEvents.md).
Expand Down Expand Up @@ -104,28 +103,28 @@ Just like the sender, the receiver code imports the package and creates an *Even
final String sasKey = "---SharedAccessSignatureKey----";
ConnectionStringBuilder connStr = new ConnectionStringBuilder(namespaceName, eventHubName, sasKeyName, sasKey);

EventHubClient ehClient = EventHubClient.createFromConnectionString(connStr.toString()).get();
EventHubClient ehClient = EventHubClient.createFromConnectionStringSync(connStr.toString());
```

The receiver code then creates (at least) one *PartitionReceiver* that will receive the data. The receiver is seeded with
an offset, in the snippet below it's simply the start of the log.

```Java
String partitionId = "0"; // API to get PartitionIds will be released as part of V0.2
PartitionReceiver receiver = ehClient.createReceiver(
String partitionId = "0";
PartitionReceiver receiver = ehClient.createReceiverSync(
EventHubClient.DefaultConsumerGroupName,
partitionId,
PartitionReceiver.StartOfStream,
false).get();
false);

receiver.setReceiveTimeout(Duration.ofSeconds(5));
receiver.setReceiveTimeout(Duration.ofSeconds(20));
```

Once the receiver is initialized, getting events is just a matter of calling the *receive()* method in a loop. Each call
to *receive()* will fetch an enumerable batch of events to process.

```Java
Iterable<EventData> receivedEvents = receiver.receive(maxEventsCount).get();
Iterable<EventData> receivedEvents = receiver.receiveSync(maxEventsCount);
```

As you might imagine, there's quite a bit more to know about partitions, about distributing the workload of processing huge and
Expand All @@ -148,7 +147,7 @@ the required version of Apache Qpid Proton-J, and the crytography library BCPKIX
<dependency>
<groupId>com.microsoft.azure</groupId>
<artifactId>azure-eventhubs</artifactId>
<version>0.10.0</version>
<version>0.11.0</version>
</dependency>
```

Expand Down