diff --git a/.github/spellcheck-settings.yml b/.github/spellcheck-settings.yml index 07b400f063..51f9d85e5d 100644 --- a/.github/spellcheck-settings.yml +++ b/.github/spellcheck-settings.yml @@ -25,4 +25,5 @@ matrix: - img sources: - '*.md' - - 'docs/**' + - 'docs/*.md' + diff --git a/.github/wordlist.txt b/.github/wordlist.txt index d60e297814..ee74a49a51 100644 --- a/.github/wordlist.txt +++ b/.github/wordlist.txt @@ -1,6 +1,7 @@ !!!Spelling check failed!!! APM ARGV +BaseObjectPoolConfig BFCommands BitOP BitPosParams @@ -16,6 +17,7 @@ ClusterPipeline ClusterPubSub ConnectionPool CoreCommands +Dockerfile EVAL EVALSHA Failback @@ -46,6 +48,7 @@ JedisCluster JedisConnectionException JedisPool JedisPooled +JedisPubSub JedisShardInfo ListPosition Ludovico @@ -174,6 +177,7 @@ incr incrBy incrByFloat ini +io json keyslot keyspace @@ -198,6 +202,9 @@ mget microservice microservices millisecondsTimestamp +MkDocs +mkdocs +md mset msetnx multikey @@ -224,6 +231,7 @@ pubsub punsubscribe py pypi +PoolConfig quickstart readonly readwrite @@ -234,10 +242,12 @@ reinitialization renamenx replicaof repo +README rpush rpushx runtime sadd +SafeEncoder scard scoreMembers sdiffstore @@ -260,6 +270,7 @@ strlen stunnel subcommands sunionstore +pipelining thevalueofmykey timeseries toctree @@ -311,3 +322,4 @@ zrevrangeByScore zrevrangeByScoreWithScores zrevrangeWithScores zunionstore +yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..5791f3712f --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,36 @@ +name: Publish Docs +on: + push: + branches: ["master"] +permissions: + contents: read + pages: write + id-token: write +concurrency: + group: "pages" + cancel-in-progress: false +jobs: + build-and-deploy: + concurrency: ci-${{ github.ref }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.9 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install mkdocs mkdocs-material pymdown-extensions mkdocs-macros-plugin + - name: Build docs + run: | + mkdocs build -d docsbuild + - name: Setup Pages + uses: actions/configure-pages@v3 + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: 'docsbuild' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 \ No newline at end of file diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000000..7fc23ffd3d --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,3 @@ +FROM squidfunk/mkdocs-material +RUN pip install mkdocs-macros-plugin +RUN pip install mkdocs-glightbox diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..5427fa7b3d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,15 @@ +# Jedis Documentation + +This documentation uses [MkDocs](https://www.mkdocs.org/) to generate the static site. + +See [mkdocs.yml](../mkdocs.yml) for the configuration. + +To develop the documentation locally, you can use the included [Dockerfile](Dockerfile) to build a container with all the +dependencies, and run it to preview your changes: + +```bash +# in docs/ +docker build -t squidfunk/mkdocs-material . +# cd .. +docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material +``` \ No newline at end of file diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md new file mode 100644 index 0000000000..ae2f5fac5c --- /dev/null +++ b/docs/advanced-usage.md @@ -0,0 +1,135 @@ +# Advanced Usage + +## Transactions + +To do transactions in Jedis, you have to wrap operations in a transaction block, very similar to pipelining: + +```java +jedis.watch (key1, key2, ...); +Transaction t = jedis.multi(); +t.set("foo", "bar"); +t.exec(); +``` + +Note: when you have any method that returns values, you have to do like this: + + +```java +Transaction t = jedis.multi(); +t.set("fool", "bar"); +Response result1 = t.get("fool"); + +t.zadd("foo", 1, "barowitch"); t.zadd("foo", 0, "barinsky"); t.zadd("foo", 0, "barikoviev"); +Response> sose = t.zrange("foo", 0, -1); // get the entire sortedset +t.exec(); // dont forget it + +String foolbar = result1.get(); // use Response.get() to retrieve things from a Response +int soseSize = sose.get().size(); // on sose.get() you can directly call Set methods! + +// List allResults = t.exec(); // you could still get all results at once, as before +``` +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. + +Note 2: Redis does not allow to use intermediate results of a transaction within that same transaction. This does not work: + +```java +// this does not work! Intra-transaction dependencies are not supported by Redis! +jedis.watch(...); +Transaction t = jedis.multi(); +if(t.get("key1").equals("something")) + t.set("key2", "value2"); +else + t.set("key", "value"); +``` + +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. + + +## Pipelining + +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. + +Here is how to do it: + +```java +Pipeline p = jedis.pipelined(); +p.set("fool", "bar"); +p.zadd("foo", 1, "barowitch"); p.zadd("foo", 0, "barinsky"); p.zadd("foo", 0, "barikoviev"); +Response pipeString = p.get("fool"); +Response> sose = p.zrange("foo", 0, -1); +p.sync(); + +int soseSize = sose.get().size(); +Set setBack = sose.get(); +``` +For more explanations see code comments in the transaction section. + + +## Publish/Subscribe + +To subscribe to a channel in Redis, create an instance of JedisPubSub and call subscribe on the Jedis instance: + +```java +class MyListener extends JedisPubSub { + public void onMessage(String channel, String message) { + } + + public void onSubscribe(String channel, int subscribedChannels) { + } + + public void onUnsubscribe(String channel, int subscribedChannels) { + } + + public void onPSubscribe(String pattern, int subscribedChannels) { + } + + public void onPUnsubscribe(String pattern, int subscribedChannels) { + } + + public void onPMessage(String pattern, String channel, String message) { + } +} + +MyListener l = new MyListener(); + +jedis.subscribe(l, "foo"); +``` +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. + + +### Monitoring + +To use the monitor command you can do something like the following: + +```java +new Thread(new Runnable() { + public void run() { + Jedis j = new Jedis("localhost"); + for (int i = 0; i < 100; i++) { + j.incr("foobared"); + try { + Thread.sleep(200); + } catch (InterruptedException e) { + } + } + j.disconnect(); + } +}).start(); + +jedis.monitor(new JedisMonitor() { + public void onCommand(String command) { + System.out.println(command); + } +}); +``` + +## Miscellaneous + +### A note about String and Binary - what is native? + +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. +In short: if you have binary data, don't encode it into String, but use the binary versions. + +### A note on Redis' master/slave distribution + +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. diff --git a/docs/assets/images/favicon-16x16.png b/docs/assets/images/favicon-16x16.png new file mode 100644 index 0000000000..ba4b7ac118 Binary files /dev/null and b/docs/assets/images/favicon-16x16.png differ diff --git a/docs/assets/images/logo.png b/docs/assets/images/logo.png new file mode 100644 index 0000000000..33fbeeafd7 Binary files /dev/null and b/docs/assets/images/logo.png differ diff --git a/docs/css/extra.css b/docs/css/extra.css new file mode 100644 index 0000000000..22807a194a --- /dev/null +++ b/docs/css/extra.css @@ -0,0 +1,4 @@ +/* extra.css */ +.md-header { + background-color: #FB2A2C; +} diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000000..ce021b37ce --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,44 @@ +# Frequently Asked Questions + +## If you get `java.net.SocketTimeoutException: Read timed out` exception + +Try setting own `timeout` value when constructing `JedisPool` using the following constructor: +```java +JedisPool(GenericObjectPoolConfig poolConfig, String host, int port, int timeout) +``` +where `timeout` is given as milliseconds. + +Default `timeout` value is **2 seconds**. + +## JedisPool blocks after getting 8 connections + +JedisPool defaults to 8 connections, you can change this in the PoolConfig: + +```java +JedisPoolConfig poolConfig = new JedisPoolConfig(); +poolConfig.setMaxTotal(maxTotal); // maximum active connections +poolConfig.setMaxIdle(maxIdle); // maximum idle connections +``` + +Take into account that `JedisPool` inherits commons-pool [BaseObjectPoolConfig](https://commons.apache.org/proper/commons-pool/api-2.3/org/apache/commons/pool2/impl/BaseObjectPoolConfig.html) which has a lot of configuration parameters. +We've set some defined ones which suit most of the cases. In case, you experience [issues](https://github.com/xetorthio/jedis/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+JedisPool) tuning these parameters may help. + +## How to configure the buffer size of socket(s) + +The buffer size of all Jedis sockets in an application can be configured through system property. + +Buffer size of input stream can be configured by setting `jedis.bufferSize.input` or `jedis.bufferSize` system property. +Buffer size of output stream can be configured by setting `jedis.bufferSize.output` or `jedis.bufferSize` system property. +If you want to set the buffer size of both input and output stream to same value, you can just set `jedis.bufferSize`. + +Note: This feature is available since Jedis 4.2.0. + +## How to avoid cluster initialization error + +As of Jedis 4.0.0, a `JedisClusterOperationException` is raised with the message `Could not initialize cluster slots cache.` when the cluster initialization process fails. + +Should you would want to avoid this error (for example, creating `JedisConnectionFactory` to an unavailable cluster for a spring-data-redis `Bean`), set the system property `jedis.cluster.initNoError` to any value. +In the console, add the option `-Djedis.cluster.initNoError`. +In an application, `System.setProperty("jedis.cluster.initNoError", "");` can be set before creating any cluster object. + +Note: This feature is available since Jedis 4.4.2. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..074a48bf84 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +{% include 'README.md' %} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..83000d59c1 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,35 @@ +site_name: Jedis +repo_name: Jedis +site_author: Redis, Inc. +site_description: Jedis is a Redis client for the JVM. +repo_url: https://github.com/redis/jedis +remote_branch: gh-pages + +theme: + name: material + logo: assets/images/logo.png + favicon: assets/images/favicon-16x16.png +extra_css: + - css/extra.css + +plugins: + - search + - macros: + include_dir: . + +nav: + - Home: index.md + - Migrating from older versions: + - 3 to 4: + - Breaking changes: 3to4.md + - Primitives: 3to4-primitives.md + - ZSET: 3to4-zset-list.md + - Using Jedis with ...: + - Search: redisearch.md + - JSON: redisjson.md + - Failover: failover.md + - FAQ: faq.md + - API Reference: https://www.javadoc.io/doc/redis.clients/jedis/latest/index.html + - Jedis Guide: https://redis.io/docs/latest/develop/connect/clients/java/jedis/ + - Redis Command Reference: https://redis.io/docs/latest/commands/ +