See: Description
Interface | Description |
---|---|
ClusterHealthCheck |
A helper to create Vert.x cluster
HealthChecks procedures. |
InfinispanAsyncMap<K,V> |
Extensions to the generic
AsyncMap . |
Class | Description |
---|---|
InfinispanClusterManager |
examples.Examples#createClusterManagerProgramatically()
----
== Configuring this cluster manager
The default cluster manager configuration can be modified with `infinispan.xml` and/or `jgroups.xml` files.
The former configures the data grid, the latter group management and member discovery.
You can place one or both of them on your classpath.
If you want to embed your custom file in a fat jar, it must be located at the root of the fat jar.
If it's an external file, the **directory** containing the file must be added to the classpath. For
example, if you are using the _launcher_ class from Vert.x, the classpath enhancement can be done as follows:
[source,shell]
----
# If infinispan.xml and/or jgroups.xml files are in the current directory:
java -jar my-app.jar -cp . -cluster
# If infinispan.xml and/or jgroups.xml files are in the conf directory:
java -jar my-app.jar -cp conf -cluster
----
Another way to override the configuration is by providing the file locations via system properties:
`vertx.infinispan.config` and/or `vertx.jgroups.config`.
[source,shell]
----
# Use a cluster configuration located in an external file
java -Dvertx.infinispan.config=./config/my-infinispan.xml -jar ... -cluster
# Or use a custom configuration from the classpath
java -Dvertx.infinispan.config=my/package/config/my-infinispan.xml -jar ... -cluster
----
The cluster manager will search for the file in classpath first, and fallback to the filesystem.
The system properties, when present, override any `infinispan.xml` or `jgroups.xml` on the classpath.
The xml files are Infinispan and JGroups configuration files and are described in detail in the documentation on the Infinispan and JGroups web-sites.
IMPORTANT: if a `jgroups.xml` file is on the classpath or if you set the `vertx.jgroups.config` system property,
it will override any JGroups `stack-file` path defined in the Infinispan configuration file.
The default JGroups configuration uses multicast for discovery and TCP for group management.
Make sure multicast is enabled on your network for this to work.
For full documentation on how to configure the transport differently or use a different transport please consult the
Infinispan / JGroups documentations.
== Using an existing Infinispan Cache Manager
You can pass an existing `DefaultCacheManager` in the cluster manager to reuse an existing cache manager:
[source,$lang]
----
examples.Examples#useExistingCacheManager(org.infinispan.manager.DefaultCacheManager)
----
In this case, Vert.x is not the cache manager owner and so do not shut it down on close.
Notice that the custom Infinispan instance need to be configured with:
[source,xml]
----
examples.Examples#healthCheck(io.vertx.core.Vertx)
----
After creation, it can be exposed over HTTP with a link:../../vertx-web/$lang/[Vert.x Web] router handler:
[source,$lang]
----
examples.Examples#healthCheckHandler(io.vertx.core.Vertx, io.vertx.ext.healthchecks.HealthChecks)
----
== Configuring for Docker Compose
Make sure to start the Java Virtual Machines with those system properties:
[source,shell]
----
-Djava.net.preferIPv4Stack=true -Djgroups.tcp.address=NON_LOOPBACK
----
This will make JGroups pick the interface of the virtual private network created by Docker.
== Trouble shooting clustering
If the default multicast discovery configuration is not working here are some common causes:
=== Multicast not enabled on the machine.
It is quite common in particular on OSX machines for multicast to be disabled by default. Please google for
information on how to enable this.
=== Using wrong network interface
If you have more than one network interface on your machine (and this can also be the case if you are running
VPN software on your machine), then JGroups may be using the wrong one.
To tell JGroups to use a specific interface you can provide the IP address of the interface in the `bind_addr`
element of the configuration. For example:
[source,xml]
----
VertxOptions.setClusterHost(java.lang.String)
.
=== Using a VPN
This is a variation of the above case. VPN software often works by creating a virtual network interface which often
doesn't support multicast. If you have a VPN running and you do not specify the correct interface to use in both the
JGroups configuration and to Vert.x then the VPN interface may be chosen instead of the correct interface.
So, if you have a VPN running you may have to configure both JGroups and Vert.x to use the correct interface as
described in the previous section.
=== When multicast is not available
In some cases you may not be able to use multicast discovery as it might not be available in your environment. In that case
you should configure another protocol, e.g. `TCPPING` to use TCP sockets, or `S3_PING` when running on Amazon EC2.
For more information on available JGroups discovery protocols and how to configure them
please consult the http://www.jgroups.org/manual/index.html#Discovery[JGroups documentation].
=== Problems with IPv6
If you have troubles configuring an IPv6 host, force the use of IPv4 with the `java.net.preferIPv4Stack` system property.
----
-Djava.net.preferIPv4Stack=true
----
=== Enabling logging
When trouble-shooting clustering issues with it's often useful to get some logging output from Infinispan and JGroups
to see if it's forming a cluster properly. You can do this (when using the default JUL logging) by adding a file
called `vertx-default-jul-logging.properties` on your classpath. This is a standard java.util.logging (JUL)
configuration file. Inside it set:
----
org.infinispan.level=INFO
org.jgroups.level=INFO
----
and also
----
java.util.logging.ConsoleHandler.level=INFO
java.util.logging.FileHandler.level=INFO
----
== Infinispan logging
Infinispan relies on JBoss logging. JBoss Logging is a logging bridge providing integration with numerous logging frameworks.
Add the logging JARs of you choice to the classpath and JBoss Logging will pick them up automatically.
If you have multiple logging backends on your classpath, you can force selection with the `org.jboss.logging.provider` system property.
For exeample:
----
-Dorg.jboss.logging.provider=log4j2
----
See this http://docs.jboss.org/hibernate/orm/4.3/topical/html/logging/Logging.html[JBoss Logging guide] for more details.
== JGroups logging
JGroups uses JDK logging by default. log4j and log4j2 are supported if the corresponding JARs are found on the classpath.
Please refer to the http://www.jgroups.org/manual/index.html#Logging[JGroups logging documentation] if you need
more details or want to implement your own logging backend implementation.
== SharedData extensions
=== AsyncMap content streams
The `InfinispanAsyncMap` API allows to retrieve keys, values and entries as streams.
This can be useful if you need to go through the content of a large map for bulk processing.
[source,$lang]
----
examples.Examples#asyncMapStreams(io.vertx.core.shareddata.AsyncMap)
----Copyright © 2018 Eclipse. All rights reserved.