|
| 1 | +# Advanced Usage |
| 2 | + |
| 3 | +## Transactions |
| 4 | + |
| 5 | +To do transactions in Jedis, you have to wrap operations in a transaction block, very similar to pipelining: |
| 6 | + |
| 7 | +```java |
| 8 | +jedis.watch (key1, key2, ...); |
| 9 | +Transaction t = jedis.multi(); |
| 10 | +t.set("foo", "bar"); |
| 11 | +t.exec(); |
| 12 | +``` |
| 13 | + |
| 14 | +Note: when you have any method that returns values, you have to do like this: |
| 15 | + |
| 16 | + |
| 17 | +```java |
| 18 | +Transaction t = jedis.multi(); |
| 19 | +t.set("fool", "bar"); |
| 20 | +Response<String> result1 = t.get("fool"); |
| 21 | + |
| 22 | +t.zadd("foo", 1, "barowitch"); t.zadd("foo", 0, "barinsky"); t.zadd("foo", 0, "barikoviev"); |
| 23 | +Response<Set<String>> sose = t.zrange("foo", 0, -1); // get the entire sortedset |
| 24 | +t.exec(); // dont forget it |
| 25 | + |
| 26 | +String foolbar = result1.get(); // use Response.get() to retrieve things from a Response |
| 27 | +int soseSize = sose.get().size(); // on sose.get() you can directly call Set methods! |
| 28 | + |
| 29 | +// List<Object> allResults = t.exec(); // you could still get all results at once, as before |
| 30 | +``` |
| 31 | +Note that a Response Object does not contain the result before t.exec() is called (it is a kind of a Future). Forgetting exec gives you exceptions. In the last lines, you see how transactions/pipelines were dealt with before version 2. You can still do it that way, but then you need to extract objects from a list, which contains also Redis status messages. |
| 32 | + |
| 33 | +Note 2: Redis does not allow to use intermediate results of a transaction within that same transaction. This does not work: |
| 34 | + |
| 35 | +```java |
| 36 | +// this does not work! Intra-transaction dependencies are not supported by Redis! |
| 37 | +jedis.watch(...); |
| 38 | +Transaction t = jedis.multi(); |
| 39 | +if(t.get("key1").equals("something")) |
| 40 | + t.set("key2", "value2"); |
| 41 | +else |
| 42 | + t.set("key", "value"); |
| 43 | +``` |
| 44 | + |
| 45 | +However, there are some commands like setnx, that include such a conditional execution. Those are of course supported within transactions. You can build your own customized commands using EVAL / LUA scripting. |
| 46 | + |
| 47 | + |
| 48 | +## Pipelining |
| 49 | + |
| 50 | +Sometimes you need to send a bunch of different commands. A very cool way to do that, and have better performance than doing it the naive way, is to use pipelining. This way you send commands without waiting for response, and you actually read the responses at the end, which is faster. |
| 51 | + |
| 52 | +Here is how to do it: |
| 53 | + |
| 54 | +```java |
| 55 | +Pipeline p = jedis.pipelined(); |
| 56 | +p.set("fool", "bar"); |
| 57 | +p.zadd("foo", 1, "barowitch"); p.zadd("foo", 0, "barinsky"); p.zadd("foo", 0, "barikoviev"); |
| 58 | +Response<String> pipeString = p.get("fool"); |
| 59 | +Response<Set<String>> sose = p.zrange("foo", 0, -1); |
| 60 | +p.sync(); |
| 61 | + |
| 62 | +int soseSize = sose.get().size(); |
| 63 | +Set<String> setBack = sose.get(); |
| 64 | +``` |
| 65 | +For more explanations see code comments in the transaction section. |
| 66 | + |
| 67 | + |
| 68 | +## Publish/Subscribe |
| 69 | + |
| 70 | +To subscribe to a channel in Redis, create an instance of JedisPubSub and call subscribe on the Jedis instance: |
| 71 | + |
| 72 | +```java |
| 73 | +class MyListener extends JedisPubSub { |
| 74 | + public void onMessage(String channel, String message) { |
| 75 | + } |
| 76 | + |
| 77 | + public void onSubscribe(String channel, int subscribedChannels) { |
| 78 | + } |
| 79 | + |
| 80 | + public void onUnsubscribe(String channel, int subscribedChannels) { |
| 81 | + } |
| 82 | + |
| 83 | + public void onPSubscribe(String pattern, int subscribedChannels) { |
| 84 | + } |
| 85 | + |
| 86 | + public void onPUnsubscribe(String pattern, int subscribedChannels) { |
| 87 | + } |
| 88 | + |
| 89 | + public void onPMessage(String pattern, String channel, String message) { |
| 90 | + } |
| 91 | +} |
| 92 | + |
| 93 | +MyListener l = new MyListener(); |
| 94 | + |
| 95 | +jedis.subscribe(l, "foo"); |
| 96 | +``` |
| 97 | +Note that subscribe is a blocking operation because it will poll Redis for responses on the thread that calls subscribe. A single JedisPubSub instance can be used to subscribe to multiple channels. You can call subscribe or psubscribe on an existing JedisPubSub instance to change your subscriptions. |
| 98 | + |
| 99 | + |
| 100 | +### Monitoring |
| 101 | + |
| 102 | +To use the monitor command you can do something like the following: |
| 103 | + |
| 104 | +```java |
| 105 | +new Thread(new Runnable() { |
| 106 | + public void run() { |
| 107 | + Jedis j = new Jedis("localhost"); |
| 108 | + for (int i = 0; i < 100; i++) { |
| 109 | + j.incr("foobared"); |
| 110 | + try { |
| 111 | + Thread.sleep(200); |
| 112 | + } catch (InterruptedException e) { |
| 113 | + } |
| 114 | + } |
| 115 | + j.disconnect(); |
| 116 | + } |
| 117 | +}).start(); |
| 118 | + |
| 119 | +jedis.monitor(new JedisMonitor() { |
| 120 | + public void onCommand(String command) { |
| 121 | + System.out.println(command); |
| 122 | + } |
| 123 | +}); |
| 124 | +``` |
| 125 | + |
| 126 | +## Miscellaneous |
| 127 | + |
| 128 | +### A note about String and Binary - what is native? |
| 129 | + |
| 130 | +Redis/Jedis talks a lot about Strings. And here [[http://redis.io/topics/internals]] it says Strings are the basic building block of Redis. However, this stress on strings may be misleading. Redis' "String" refer to the C char type (8 bit), which is incompatible with Java Strings (16-bit). Redis sees only 8-bit blocks of data of predefined length, so normally it doesn't interpret the data (it's "binary safe"). Therefore in Java, byte[] data is "native", whereas Strings have to be encoded before being sent, and decoded after being retrieved by the SafeEncoder. This has some minor performance impact. |
| 131 | +In short: if you have binary data, don't encode it into String, but use the binary versions. |
| 132 | + |
| 133 | +### A note on Redis' master/slave distribution |
| 134 | + |
| 135 | +A Redis network consists of redis servers, which can be either masters or slaves. Slaves are synchronized to the master (master/slave replication). However, master and slaves look identical to a client, and slaves do accept write requests, but they will not be propagated "up-hill" and could eventually be overwritten by the master. It makes sense to route reads to slaves, and write demands to the master. Furthermore, being a slave doesn't prevent from being considered master by another slave. |
0 commit comments