Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
145 lines (76 sloc) 7 KB
outputFileName
index.html

Step 2 - Read events from a stream and subscribe to changes

[!include]

This second step covers reading events from a stream and subscribing to changes to events in a stream.

Read a Stream of Events

Event Store exposes all streams as atom feeds, and you can read data from the stream by navigating to the head URI of the stream <http://127.0.0.1:2113/streams/<STREAM_ID>> with cURL, or click the Stream Browser tab in the Admin UI and you see the stream you created in step 1.

The Admin UI Dashboard

Request

[!code-bashgetting-started-read-stream-request]

[!NOTE] This returns the feed in JSON format, you can also use Accept:application/atom+xml if you prefer XML.

Response

[!code-httpgetting-started-read-stream-response]


.NET Client API

To use the .NET API, use the following method passing the stream name, the start point in the stream, the number of events to read and whether to follow links to the event data:

[!code-csharpgetting-started-read-stream-request]

[!NEXT] Read this guide for more information on how to read events with the .NET API.

JVM Client

To use the JVM client, use the following method passing the stream name, the start point in the stream, and whether to follow links to the event data:

[!code-javagetting-started-read]


Read a Single Event

The feed has a single item inside of it, the one you posted in part 1. You can see details of the event in the Stream Browser tab in the Admin UI by clicking a stream to see its events, and then clicking an event. Or with cURL, issue a GET to the alternate URI value from the response above.

Request

[!code-bashgetting-started-read-event-request]

[!NOTE] You can also use Accept: text/xml if you prefer XML.

Response

[!code-httpgetting-started-read-event-response]


.NET Client API

To use the .NET API, use the following method passing the stream name, the event you want to read and wether to return the event data:

[!code-csharpgetting-started-read-stream-request]

JVM Client

To use the Java client, use the following method passing the stream name, the event you want to read and if you want to also return the event data:

[!code-javagetting-started-read]


Paginating through Events

For longer feeds of events than this example, you need to paginate through the feed, reading a certain number of events at a time.

You can use the HTTP API to paginate through the feed using previous and next links within the stream. Or you can use a read method of the .NET API (and JVM client), to loop through events a certain number at a time.

Subscribing to Receive Stream Updates

A common operation is to subscribe to a stream and receive notifications for changes. As new events arrive, you continue following them.

You can create subscriptions and watch events as they arrive under the Persistent Subscriptions tab, or use an API method:

Subscriptions in the Admin UI

HTTP API

[!code-bashgetting-started-create-subscription]

.NET API

[!code-csharpgetting-started-read-stream-request]

[!NEXT] Find more details on the parameters used in the example above, read the API documentation for PersistentSubscriptionSettings, CreatePersistentSubscriptionAsync and ConnectToPersistentSubscription

JVM Client API

[!code-javagetting-started-read]


There are three types of subscription patterns, useful in different situations.

Volatile Subscriptions

This subscription calls a given function for events written after establishing the subscription. They are useful when you need notification of new events with minimal latency, but where it's not necessary to process every event.

For example, if a stream has 100 events in it when a subscriber connects, the subscriber can expect to see event number 101 onwards until the time the subscription is closed or dropped.

Catch-Up Subscriptions

This subscription specifies a starting point, in the form of an event number or transaction file position. You call the function for events from the starting point until the end of the stream, and then for subsequently written events.

For example, if you specify a starting point of 50 when a stream has 100 events, the subscriber can expect to see events 51 through 100, and then any events are subsequently written until you drop or close the subscription.

Persistent Subscriptions

[!NOTE] Persistent subscriptions exist in version 3.2.0 and above of Event Store.

This subscription supports the "competing consumers" messaging pattern and are useful when you need to distribute messages to many workers. Event Store saves the subscription state server-side and allows for at-least-once delivery guarantees across multiple consumers on the same stream. It is possible to have many groups of consumers compete on the same stream, with each group getting an at-least-once guarantee.

Next Step

In this second part of our getting started guide you learned how to read events from a stream and subscribe to changes. The next part covers projections, used to give you continuous queries of your data.