Debian Codegraph @

curator-examples/src/main/java/pubsub/README.md

raw
1 # Pub-Sub Example
2
3 <!--
4 Licensed to the Apache Software Foundation (ASF) under one
5 or more contributor license agreements. See the NOTICE file
6 distributed with this work for additional information
7 regarding copyright ownership. The ASF licenses this file
8 to you under the Apache License, Version 2.0 (the
9 "License"); you may not use this file except in compliance
10 with the License. You may obtain a copy of the License at
11
12 http://www.apache.org/licenses/LICENSE-2.0
13
14 Unless required by applicable law or agreed to in writing,
15 software distributed under the License is distributed on an
16 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 KIND, either express or implied. See the License for the
18 specific language governing permissions and limitations
19 under the License.
20 -->
21
22 This example models a publish and subscribe system (note: it is not meant for production) using
23 the strongly typed modeled APIs in Apache Curator.
24
25 ## Design Notes
26
27 In this example, there are three models that can be published: `Instance`, `LocationAvailable`
28 and `UserCreated`. Instances have an `InstanceType`; LocationAvailable and UserCreated both have
29 a `Priority` and are associated with a `Group`. (Note: these names/objects are meant for
30 illustrative purposes only and are completely contrived)
31
32 Each model is stored at a unique path in ZooKeeper:
33
34 * Instance: `/root/pubsub/instances/TYPE/ID`
35 * LocationAvailable: `/root/pubsub/messages/locations/GROUP/PRIORITY/ID`
36 * UserCreated: `/root/pubsub/messages/users/GROUP/PRIORITY/ID`
37
38 All models are stored using a TTL so that they automatically get deleted after 10 minutes.
39
40 ## Clients
41
42 This example uses the "typed" models (`TypedModelSpec`, etc.). The typed paths, models and
43 clients are meant to be created early in your application and re-used as needed. Thus, you
44 can model your ZooKeeper usage and the rest of your application can use them without worrying
45 about correct paths, types, etc.
46
47 `TypedModeledFramework` is a template that produces a `ModeledFramework` by applying
48 parameters to the `TypedZPath` in the contained `TypedModelSpec`. Curator provides variants
49 that accept from 1 to 10 parameters (`TypedModeledFramework`, `TypedModeledFramework2`,
50 `TypedModeledFramework3`, etc.).
51
52 In this example, the TypedModeledFrameworks are defined in `Clients.java`. E.g.
53
54 ```
55 public static final TypedModeledFramework2<LocationAvailable, Group, Priority> locationAvailableClient =
56 TypedModeledFramework2.from(
57 ModeledFramework.builder(),
58 builder(LocationAvailable.class),
59 "/root/pubsub/messages/locations/{group}/{priority}"
60 );
61 ```
62
63 ## Publisher
64
65 `Publisher.java` shows how to use the ModeledFramework to write models. There are methods to
66 write single instances and to write lists of instances in a transaction. Each publish method
67 resolves the appropriate typed client and then calls its `set()` method with the given model.
68
69 ## Subscriber
70
71 `Subscriber.java` uses CachedModeledFrameworks to listen for changes on the parent nodes for
72 all of the models in this example. Each of the methods resolves the appropriate typed client
73 and then starts the cache (via `cached()`).
74
75 ## SubPubTest
76
77 `SubPubTest.java` is a class that exercises this example.
78
79 * `start()` uses `Subscriber` to start a `CachedModeledFramework` for each combination of
80 the Instance + InstanceType, LocationAvailable + Group + Priority, and UserCreated + Group + Priority. It then adds a simple listener to each cache that merely prints the class name
81 and path whenever an update occurs (see `generalListener()`).
82 * `start()` also starts a scheduled task that runs every second. This task calls
83 `publishSomething()`
84 * `publishSomething()` randomly publishes either a single Instance, LocationAvailable,
85 UserCreated or a list of those.
86
87 `SubPubTest.java` has a `main()` method. When you run you should see something similar to this:
88
89 ```
90 Publishing 9 instances
91 Subscribed Instance @ /root/pubsub/instances/proxy/1
92 Subscribed Instance @ /root/pubsub/instances/web/2
93 Subscribed Instance @ /root/pubsub/instances/cache/4
94 Subscribed Instance @ /root/pubsub/instances/proxy/9
95 Subscribed Instance @ /root/pubsub/instances/database/3
96 Subscribed Instance @ /root/pubsub/instances/cache/5
97 Subscribed Instance @ /root/pubsub/instances/database/6
98 Subscribed Instance @ /root/pubsub/instances/cache/7
99 Subscribed Instance @ /root/pubsub/instances/cache/8
100 Publishing 1 userCreated
101 Subscribed UserCreated @ /root/pubsub/messages/users/main/high/10
102 Publishing 9 locationsAvailable
103 Subscribed LocationAvailable @ /root/pubsub/messages/locations/admin/low/11
104 Subscribed LocationAvailable @ /root/pubsub/messages/locations/admin/medium/12
105 Subscribed LocationAvailable @ /root/pubsub/messages/locations/admin/medium/13
106 Subscribed LocationAvailable @ /root/pubsub/messages/locations/admin/medium/14
107 Subscribed LocationAvailable @ /root/pubsub/messages/locations/admin/medium/16
108 Subscribed LocationAvailable @ /root/pubsub/messages/locations/admin/high/15
109 Subscribed LocationAvailable @ /root/pubsub/messages/locations/admin/medium/17
110 ...
111 ```
112
113 It runs for 1 minute and then exits.