http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/configuring-transports.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/configuring-transports.md b/docs/user-manual/en/configuring-transports.md index 189e3da..d2a0282 100644 --- a/docs/user-manual/en/configuring-transports.md +++ b/docs/user-manual/en/configuring-transports.md @@ -1,43 +1,39 @@ # Configuring the Transport -In this chapter we'll describe the concepts required for understanding -Apache ActiveMQ Artemis transports and where and how they're configured. +In this chapter we'll describe the concepts required for understanding Apache +ActiveMQ Artemis transports and where and how they're configured. ## Acceptors One of the most important concepts in Apache ActiveMQ Artemis transports is the -*acceptor*. Let's dive straight in and take a look at an acceptor -defined in xml in the configuration file `broker.xml`. +*acceptor*. Let's dive straight in and take a look at an acceptor defined in +xml in the configuration file `broker.xml`. ```xml -<acceptors> - <acceptor name="netty">tcp://localhost:61617</acceptor> -</acceptors> +<acceptor name="netty">tcp://localhost:61617</acceptor> ``` -Acceptors are always defined inside an `acceptors` element. There can be -one or more acceptors defined in the `acceptors` element. There's no -upper limit to the number of acceptors per server. +Acceptors are always defined inside an `acceptors` element. There can be one or +more acceptors defined in the `acceptors` element. There's no upper limit to +the number of acceptors per server. -Each acceptor defines a way in which connections can be made to the -Apache ActiveMQ Artemis server. +Each acceptor defines a way in which connections can be made to the Apache +ActiveMQ Artemis server. In the above example we're defining an acceptor that uses -[Netty](https://netty.io/) to listen for connections at port -`61617`. - -The `acceptor` element contains a `URL` that defines the kind of Acceptor -to create along with its configuration. The `schema` part of the `URL` -defines the Acceptor type which can either be `tcp` or `vm` which is -`Netty` or an In VM Acceptor respectively. For `Netty` the host and the -port of the `URL` define what host and port the `acceptor` will bind to. For -In VM the `Authority` part of the `URL` defines a unique server id. - -The `acceptor` can also be configured with a set of key=value pairs -used to configure the specific transport, the set of -valid key=value pairs depends on the specific transport be used and are -passed straight through to the underlying transport. These are set on the -`URL` as part of the query, like so: +[Netty](https://netty.io/) to listen for connections at port `61617`. + +The `acceptor` element contains a `URL` that defines the kind of Acceptor to +create along with its configuration. The `schema` part of the `URL` defines the +Acceptor type which can either be `tcp` or `vm` which is `Netty` or an In VM +Acceptor respectively. For `Netty` the host and the port of the `URL` define +what host and port the `acceptor` will bind to. For In VM the `Authority` part +of the `URL` defines a unique server id. + +The `acceptor` can also be configured with a set of key=value pairs used to +configure the specific transport, the set of valid key=value pairs depends on +the specific transport be used and are passed straight through to the +underlying transport. These are set on the `URL` as part of the query, like so: ```xml <acceptor name="netty">tcp://localhost:61617?sslEnabled=true&keyStorePath=/path</acceptor> @@ -45,43 +41,41 @@ passed straight through to the underlying transport. These are set on the ## Connectors -Whereas acceptors are used on the server to define how we accept -connections, connectors are used to define how to connect to a server. +Whereas acceptors are used on the server to define how we accept connections, +connectors are used to define how to connect to a server. Let's look at a connector defined in our `broker.xml` file: ```xml -<connectors> - <connector name="netty">tcp://localhost:61617</connector> -</connectors> +<connector name="netty">tcp://localhost:61617</connector> ``` -Connectors can be defined inside a `connectors` element. There can be -one or more connectors defined in the `connectors` element. There's no -upper limit to the number of connectors per server. +Connectors can be defined inside a `connectors` element. There can be one or +more connectors defined in the `connectors` element. There's no upper limit to +the number of connectors per server. A `connector` is used when the server acts as a client itself, e.g.: -- When one server is bridged to another -- When a server takes part in a cluster +- When one server is bridged to another +- When a server takes part in a cluster In these cases the server needs to know how to connect to other servers. That's defined by `connectors`. ## Configuring the Transport Directly from the Client -How do we configure a core `ClientSessionFactory` with the information -that it needs to connect with a server? +How do we configure a core `ClientSessionFactory` with the information that it +needs to connect with a server? Connectors are also used indirectly when configuring a core -`ClientSessionFactory` to directly talk to a server. Although in this -case there's no need to define such a connector in the server side -configuration, instead we just specify the appropriate URI. +`ClientSessionFactory` to directly talk to a server. Although in this case +there's no need to define such a connector in the server side configuration, +instead we just specify the appropriate URI. -Here's an example of creating a `ClientSessionFactory` which will -connect directly to the acceptor we defined earlier in this chapter, it -uses the standard Netty TCP transport and will try and connect on port -61617 to localhost (default): +Here's an example of creating a `ClientSessionFactory` which will connect +directly to the acceptor we defined earlier in this chapter, it uses the +standard Netty TCP transport and will try and connect on port 61617 to +localhost (default): ```java ServerLocator locator = ActiveMQClient.createServerLocator("tcp://localhost:61617"); @@ -91,8 +85,8 @@ ClientSessionFactory sessionFactory = locator.createClientSessionFactory(); ClientSession session = sessionFactory.createSession(...); ``` -Similarly, if you're using JMS, you can configure the JMS connection -factory directly on the client side: +Similarly, if you're using JMS, you can configure the JMS connection factory +directly on the client side: ```java ConnectionFactory connectionFactory = new ActiveMQConnectionFactory("tcp://localhost:61617"); @@ -103,8 +97,7 @@ Connection jmsConnection = connectionFactory.createConnection(); ## Configuring the Netty transport Out of the box, Apache ActiveMQ Artemis currently uses -[Netty](https://netty.io/), a high performance low level -network library. +[Netty](https://netty.io/), a high performance low level network library. Our Netty transport can be configured in several different ways; to use straightforward TCP sockets, SSL, or to tunnel over HTTP or HTTPS.. @@ -113,14 +106,14 @@ We believe this caters for the vast majority of transport requirements. ### Single Port Support -Apache ActiveMQ Artemis supports using a single port for all -protocols, Apache ActiveMQ Artemis will automatically detect which protocol is being -used CORE, AMQP, STOMP or OPENWIRE and use the appropriate Apache ActiveMQ Artemis -handler. It will also detect whether protocols such as HTTP or Web -Sockets are being used and also use the appropriate decoders +Apache ActiveMQ Artemis supports using a single port for all protocols, Apache +ActiveMQ Artemis will automatically detect which protocol is being used CORE, +AMQP, STOMP or OPENWIRE and use the appropriate Apache ActiveMQ Artemis +handler. It will also detect whether protocols such as HTTP or Web Sockets are +being used and also use the appropriate decoders -It is possible to limit which protocols are supported by using the -`protocols` parameter on the Acceptor like so: +It is possible to limit which protocols are supported by using the `protocols` +parameter on the Acceptor like so: ```xml <acceptor name="netty">tcp://localhost:61617?protocols=CORE,AMQP</acceptor> @@ -129,340 +122,335 @@ It is possible to limit which protocols are supported by using the ### Configuring Netty TCP Netty TCP is a simple unencrypted TCP sockets based transport. If you're -running connections across an untrusted network please bear in -mind this transport is unencrypted. You may want to look at the SSL or -HTTPS configurations. +running connections across an untrusted network please bear in mind this +transport is unencrypted. You may want to look at the SSL or HTTPS +configurations. -With the Netty TCP transport all connections are initiated from the -client side (i.e. the server does not initiate any connections to the -client). This works well with firewall policies that typically only allow -connections to be initiated in one direction. +With the Netty TCP transport all connections are initiated from the client side +(i.e. the server does not initiate any connections to the client). This works +well with firewall policies that typically only allow connections to be +initiated in one direction. All the valid keys for the `tcp` URL scheme used for Netty are defined in the -class `org.apache.activemq.artemis.core.remoting.impl.netty.TransportConstants`. -Most parameters can be used either with acceptors or connectors, some only -work with acceptors. The following parameters can be used to configure -Netty for simple TCP: +class +`org.apache.activemq.artemis.core.remoting.impl.netty.TransportConstants`. +Most parameters can be used either with acceptors or connectors, some only work +with acceptors. The following parameters can be used to configure Netty for +simple TCP: -> **Note** +> **Note:** > -> The `host` and `port` parameters are only used in the core API, in -> XML configuration these are set in the URI host and port. - -- `host`. This specifies the host name or IP address to connect to - (when configuring a connector) or to listen on (when configuring an - acceptor). The default value for this property is `localhost`. When - configuring acceptors, multiple hosts or IP addresses can be - specified by separating them with commas. It is also possible to - specify `0.0.0.0` to accept connection from all the host's network - interfaces. It's not valid to specify multiple addresses when - specifying the host for a connector; a connector makes a connection - to one specific address. - - > **Note** - > - > Don't forget to specify a host name or IP address! If you want - > your server able to accept connections from other nodes you must - > specify a hostname or IP address at which the acceptor will bind - > and listen for incoming connections. The default is localhost - > which of course is not accessible from remote nodes! - -- `port`. This specified the port to connect to (when configuring a - connector) or to listen on (when configuring an acceptor). The - default value for this property is `61616`. - -- `tcpNoDelay`. If this is `true` then [Nagle's - algorithm](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) will be - disabled. This is a [Java (client) socket - option](https://docs.oracle.com/javase/8/docs/technotes/guides/net/socketOpt.html). - The default value for this property is `true`. - -- `tcpSendBufferSize`. This parameter determines the size of the - TCP send buffer in bytes. The default value for this property is - `32768` bytes (32KiB). - - TCP buffer sizes should be tuned according to the bandwidth and - latency of your network. Here's a good link that explains the theory - behind [this](http://www-didc.lbl.gov/TCP-tuning/). - - In summary TCP send/receive buffer sizes should be calculated as: - - buffer_size = bandwidth * RTT. - - Where bandwidth is in *bytes per second* and network round trip time - (RTT) is in seconds. RTT can be easily measured using the `ping` - utility. - - For fast networks you may want to increase the buffer sizes from the - defaults. - -- `tcpReceiveBufferSize`. This parameter determines the size of the - TCP receive buffer in bytes. The default value for this property is - `32768` bytes (32KiB). +> The `host` and `port` parameters are only used in the core API, in XML +> configuration these are set in the URI host and port. + +- `host`. This specifies the host name or IP address to connect to (when + configuring a connector) or to listen on (when configuring an acceptor). The + default value for this property is `localhost`. When configuring acceptors, + multiple hosts or IP addresses can be specified by separating them with commas. + It is also possible to specify `0.0.0.0` to accept connection from all the + host's network interfaces. It's not valid to specify multiple addresses when + specifying the host for a connector; a connector makes a connection to one + specific address. + + > **Note:** + > + > Don't forget to specify a host name or IP address! If you want your server + > able to accept connections from other nodes you must specify a hostname or + > IP address at which the acceptor will bind and listen for incoming + > connections. The default is localhost which of course is not accessible + > from remote nodes! + +- `port`. This specified the port to connect to (when configuring a connector) + or to listen on (when configuring an acceptor). The default value for this + property is `61616`. + +- `tcpNoDelay`. If this is `true` then [Nagle's + algorithm](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) will be + disabled. This is a [Java (client) socket + option](https://docs.oracle.com/javase/8/docs/technotes/guides/net/socketOpt.html). + The default value for this property is `true`. + +- `tcpSendBufferSize`. This parameter determines the size of the TCP send + buffer in bytes. The default value for this property is `32768` bytes + (32KiB). + + TCP buffer sizes should be tuned according to the bandwidth and latency of + your network. Here's a good link that explains the theory behind + [this](http://www-didc.lbl.gov/TCP-tuning/). + + In summary TCP send/receive buffer sizes should be calculated as: + + buffer_size = bandwidth * RTT. + + Where bandwidth is in *bytes per second* and network round trip time (RTT) is + in seconds. RTT can be easily measured using the `ping` utility. + + For fast networks you may want to increase the buffer sizes from the + defaults. + +- `tcpReceiveBufferSize`. This parameter determines the size of the TCP receive + buffer in bytes. The default value for this property is `32768` bytes + (32KiB). -- `writeBufferLowWaterMark`. This parameter determines the low water mark of - the Netty write buffer. Once the number of bytes queued in the write buffer exceeded - the high water mark and then dropped down below this value, Netty's channel - will start to be writable again. The default value for this property is - `32768` bytes (32KiB). +- `writeBufferLowWaterMark`. This parameter determines the low water mark of + the Netty write buffer. Once the number of bytes queued in the write buffer + exceeded the high water mark and then dropped down below this value, Netty's + channel will start to be writable again. The default value for this property is + `32768` bytes (32KiB). -- `writeBufferHighWaterMark`. This parameter determines the high water mark of - the Netty write buffer. If the number of bytes queued in the write buffer exceeds - this value, Netty's channel will start to be not writable. The default value for - this property is `131072` bytes (128KiB). - -- `batchDelay`. Before writing packets to the transport, Apache ActiveMQ Artemis can - be configured to batch up writes for a maximum of `batchDelay` - milliseconds. This can increase overall throughput for very small - messages. It does so at the expense of an increase in average - latency for message transfer. The default value for this property is - `0` ms. - -- `directDeliver`. When a message arrives on the server and is - delivered to waiting consumers, by default, the delivery is done on - the same thread as that on which the message arrived. This gives - good latency in environments with relatively small messages and a - small number of consumers, but at the cost of overall throughput and - scalability - especially on multi-core machines. If you want the - lowest latency and a possible reduction in throughput then you can - use the default value for `directDeliver` (i.e. `true`). If you are - willing to take some small extra hit on latency but want the highest - throughput set `directDeliver` to `false`. - -- `nioRemotingThreads` This is deprecated. It is replaced by `remotingThreads`, - if you are using this please update your configuration - -- `remotingThreads`. Apache ActiveMQ Artemis will, - by default, use a number of threads equal to three times the number - of cores (or hyper-threads) as reported by - `Runtime.getRuntime().availableProcessors()` for processing incoming - packets. If you want to override this value, you can set the number - of threads by specifying this parameter. The default value for this - parameter is `-1` which means use the value from - `Runtime.getRuntime().availableProcessors()` \* 3. - -- `localAddress`. When configured a Netty Connector it is possible to - specify which local address the client will use when connecting to - the remote address. This is typically used in the Application Server - or when running Embedded to control which address is used for - outbound connections. If the local-address is not set then the - connector will use any local address available - -- `localPort`. When configured a Netty Connector it is possible to - specify which local port the client will use when connecting to the - remote address. This is typically used in the Application Server or - when running Embedded to control which port is used for outbound - connections. If the local-port default is used, which is 0, then the - connector will let the system pick up an ephemeral port. valid ports - are 0 to 65535 - -- `connectionsAllowed`. This is only valid for acceptors. It limits the - number of connections which the acceptor will allow. When this limit - is reached a DEBUG level message is issued to the log, and the connection - is refused. The type of client in use will determine what happens when - the connection is refused. In the case of a `core` client, it will - result in a `org.apache.activemq.artemis.api.core.ActiveMQConnectionTimedOutException`. - -- `handshake-timeout`. Prevents an unauthorised client opening a large - number of connections and just keeping them open. As connections each - require a file handle this consumes resources that are then unavailable - to other clients. Once the connection is authenticated, the usual rules - can be enforced regarding resource consumption. Default value is set to - 10 seconds. Each integer is valid value. When set value to zero or - negative integer this feature is turned off. Changing value needs - to restart server to take effect. +- `writeBufferHighWaterMark`. This parameter determines the high water mark of + the Netty write buffer. If the number of bytes queued in the write buffer + exceeds this value, Netty's channel will start to be not writable. The default + value for this property is `131072` bytes (128KiB). + +- `batchDelay`. Before writing packets to the transport, Apache ActiveMQ + Artemis can be configured to batch up writes for a maximum of `batchDelay` + milliseconds. This can increase overall throughput for very small messages. It + does so at the expense of an increase in average latency for message transfer. + The default value for this property is `0` ms. + +- `directDeliver`. When a message arrives on the server and is delivered to + waiting consumers, by default, the delivery is done on the same thread as + that on which the message arrived. This gives good latency in environments with + relatively small messages and a small number of consumers, but at the cost of + overall throughput and scalability - especially on multi-core machines. If you + want the lowest latency and a possible reduction in throughput then you can use + the default value for `directDeliver` (i.e. `true`). If you are willing to take + some small extra hit on latency but want the highest throughput set + `directDeliver` to `false`. + +- `nioRemotingThreads` This is deprecated. It is replaced by `remotingThreads`, + if you are using this please update your configuration + +- `remotingThreads`. Apache ActiveMQ Artemis will, by default, use a number of + threads equal to three times the number of cores (or hyper-threads) as + reported by `Runtime.getRuntime().availableProcessors()` for processing + incoming packets. If you want to override this value, you can set the number of + threads by specifying this parameter. The default value for this parameter is + `-1` which means use the value from + `Runtime.getRuntime().availableProcessors()` \* 3. + +- `localAddress`. When configured a Netty Connector it is possible to specify + which local address the client will use when connecting to the remote + address. This is typically used in the Application Server or when running + Embedded to control which address is used for outbound connections. If the + local-address is not set then the connector will use any local address + available + +- `localPort`. When configured a Netty Connector it is possible to specify + which local port the client will use when connecting to the remote address. + This is typically used in the Application Server or when running Embedded to + control which port is used for outbound connections. If the local-port default + is used, which is 0, then the connector will let the system pick up an + ephemeral port. valid ports are 0 to 65535 + +- `connectionsAllowed`. This is only valid for acceptors. It limits the number + of connections which the acceptor will allow. When this limit is reached a + DEBUG level message is issued to the log, and the connection is refused. The + type of client in use will determine what happens when the connection is + refused. In the case of a `core` client, it will result in a + `org.apache.activemq.artemis.api.core.ActiveMQConnectionTimedOutException`. + +- `handshake-timeout`. Prevents an unauthorised client opening a large number + of connections and just keeping them open. As connections each require a file + handle this consumes resources that are then unavailable to other clients. Once + the connection is authenticated, the usual rules can be enforced regarding + resource consumption. Default value is set to 10 seconds. Each integer is valid + value. When set value to zero or negative integer this feature is turned off. + Changing value needs to restart server to take effect. ### Configuring Netty Native Transport -Netty Native Transport support exists for selected OS platforms. -This allows Apache ActiveMQ Artemis to use native sockets/io instead of Java NIO. +Netty Native Transport support exists for selected OS platforms. This allows +Apache ActiveMQ Artemis to use native sockets/io instead of Java NIO. -These Native transports add features specific to a particular platform, -generate less garbage, and generally improve performance when compared to Java NIO based transport. +These Native transports add features specific to a particular platform, +generate less garbage, and generally improve performance when compared to Java +NIO based transport. Both Clients and Server can benefit from this. Current Supported Platforms. -- Linux running 64bit JVM -- MacOS running 64bit JVM +- Linux running 64bit JVM +- MacOS running 64bit JVM -Apache ActiveMQ Artemis will by default enable the corresponding native transport if a supported platform is detected. +Apache ActiveMQ Artemis will by default enable the corresponding native +transport if a supported platform is detected. -If running on an unsupported platform or any issues loading native libs, Apache ActiveMQ Artemis will fallback onto Java NIO. +If running on an unsupported platform or any issues loading native libs, Apache +ActiveMQ Artemis will fallback onto Java NIO. #### Linux Native Transport -On supported Linux platforms Epoll is used, @see https://en.wikipedia.org/wiki/Epoll. +On supported Linux platforms Epoll is used, @see +https://en.wikipedia.org/wiki/Epoll. The following properties are specific to this native transport: -- `useEpoll` enables the use of epoll if a supported linux platform is running a 64bit JVM is detected. - Setting this to `false` will force the use of Java NIO instead of epoll. Default is `true` +- `useEpoll` enables the use of epoll if a supported linux platform is running + a 64bit JVM is detected. Setting this to `false` will force the use of Java + NIO instead of epoll. Default is `true` #### MacOS Native Transport -On supported MacOS platforms KQueue is used, @see https://en.wikipedia.org/wiki/Kqueue. +On supported MacOS platforms KQueue is used, @see +https://en.wikipedia.org/wiki/Kqueue. The following properties are specific to this native transport: -- `useKQueue` enables the use of kqueue if a supported MacOS platform running a 64bit JVM is detected. - Setting this to `false` will force the use of Java NIO instead of kqueue. Default is `true` +- `useKQueue` enables the use of kqueue if a supported MacOS platform running a + 64bit JVM is detected. Setting this to `false` will force the use of Java + NIO instead of kqueue. Default is `true` - ### Configuring Netty SSL -Netty SSL is similar to the Netty TCP transport but it provides -additional security by encrypting TCP connections using the Secure -Sockets Layer SSL +Netty SSL is similar to the Netty TCP transport but it provides additional +security by encrypting TCP connections using the Secure Sockets Layer SSL Please see the examples for a full working example of using Netty SSL. -Netty SSL uses all the same properties as Netty TCP but adds the -following additional properties: - -- `sslEnabled` - - Must be `true` to enable SSL. Default is `false`. - -- `keyStorePath` - - When used on an `acceptor` this is the path to the SSL key store on - the server which holds the server's certificates (whether - self-signed or signed by an authority). - - When used on a `connector` this is the path to the client-side SSL - key store which holds the client certificates. This is only relevant - for a `connector` if you are using 2-way SSL (i.e. mutual - authentication). Although this value is configured on the server, it - is downloaded and used by the client. If the client needs to use a - different path from that set on the server then it can override the - server-side setting by either using the customary - "javax.net.ssl.keyStore" system property or the ActiveMQ-specific - "org.apache.activemq.ssl.keyStore" system property. The - ActiveMQ-specific system property is useful if another component on - client is already making use of the standard, Java system property. - -- `keyStorePassword` - - When used on an `acceptor` this is the password for the server-side - keystore. - - When used on a `connector` this is the password for the client-side - keystore. This is only relevant for a `connector` if you are using - 2-way SSL (i.e. mutual authentication). Although this value can be - configured on the server, it is downloaded and used by the client. - If the client needs to use a different password from that set on the - server then it can override the server-side setting by either using - the customary "javax.net.ssl.keyStorePassword" system property or - the ActiveMQ-specific "org.apache.activemq.ssl.keyStorePassword" - system property. The ActiveMQ-specific system property is useful if - another component on client is already making use of the standard, - Java system property. - -- `trustStorePath` - - When used on an `acceptor` this is the path to the server-side SSL - key store that holds the keys of all the clients that the server - trusts. This is only relevant for an `acceptor` if you are using - 2-way SSL (i.e. mutual authentication). - - When used on a `connector` this is the path to the client-side SSL - key store which holds the public keys of all the servers that the - client trusts. Although this value can be configured on the server, - it is downloaded and used by the client. If the client needs to use - a different path from that set on the server then it can override - the server-side setting by either using the customary - "javax.net.ssl.trustStore" system property or the ActiveMQ-specific - "org.apache.activemq.ssl.trustStore" system property. The - ActiveMQ-specific system property is useful if another component on - client is already making use of the standard, Java system property. - -- `trustStorePassword` - - When used on an `acceptor` this is the password for the server-side - trust store. This is only relevant for an `acceptor` if you are - using 2-way SSL (i.e. mutual authentication). - - When used on a `connector` this is the password for the client-side - truststore. Although this value can be configured on the server, it - is downloaded and used by the client. If the client needs to use a - different password from that set on the server then it can override - the server-side setting by either using the customary - "javax.net.ssl.trustStorePassword" system property or the - ActiveMQ-specific "org.apache.activemq.ssl.trustStorePassword" - system property. The ActiveMQ-specific system property is useful if - another component on client is already making use of the standard, - Java system property. - -- `enabledCipherSuites` - - Whether used on an `acceptor` or `connector` this is a comma - separated list of cipher suites used for SSL communication. The - default value is `null` which means the JVM's default will be used. - -- `enabledProtocols` - - Whether used on an `acceptor` or `connector` this is a comma - separated list of protocols used for SSL communication. The default - value is `null` which means the JVM's default will be used. - -- `needClientAuth` - - This property is only for an `acceptor`. It tells a client - connecting to this acceptor that 2-way SSL is required. Valid values - are `true` or `false`. Default is `false`. +Netty SSL uses all the same properties as Netty TCP but adds the following +additional properties: + +- `sslEnabled` + + Must be `true` to enable SSL. Default is `false`. + +- `keyStorePath` + + When used on an `acceptor` this is the path to the SSL key store on the + server which holds the server's certificates (whether self-signed or signed by + an authority). + + When used on a `connector` this is the path to the client-side SSL key store + which holds the client certificates. This is only relevant for a `connector` if + you are using 2-way SSL (i.e. mutual authentication). Although this value is + configured on the server, it is downloaded and used by the client. If the + client needs to use a different path from that set on the server then it can + override the server-side setting by either using the customary + "javax.net.ssl.keyStore" system property or the ActiveMQ-specific + "org.apache.activemq.ssl.keyStore" system property. The ActiveMQ-specific + system property is useful if another component on client is already making use + of the standard, Java system property. + +- `keyStorePassword` + + When used on an `acceptor` this is the password for the server-side keystore. + + When used on a `connector` this is the password for the client-side keystore. + This is only relevant for a `connector` if you are using 2-way SSL (i.e. mutual + authentication). Although this value can be configured on the server, it is + downloaded and used by the client. If the client needs to use a different + password from that set on the server then it can override the server-side + setting by either using the customary "javax.net.ssl.keyStorePassword" system + property or the ActiveMQ-specific "org.apache.activemq.ssl.keyStorePassword" + system property. The ActiveMQ-specific system property is useful if another + component on client is already making use of the standard, Java system + property. + +- `trustStorePath` + + When used on an `acceptor` this is the path to the server-side SSL key store + that holds the keys of all the clients that the server trusts. This is only + relevant for an `acceptor` if you are using 2-way SSL (i.e. mutual + authentication). + + When used on a `connector` this is the path to the client-side SSL key store + which holds the public keys of all the servers that the client trusts. Although + this value can be configured on the server, it is downloaded and used by the + client. If the client needs to use a different path from that set on the server + then it can override the server-side setting by either using the customary + "javax.net.ssl.trustStore" system property or the ActiveMQ-specific + "org.apache.activemq.ssl.trustStore" system property. The ActiveMQ-specific + system property is useful if another component on client is already making use + of the standard, Java system property. + +- `trustStorePassword` + + When used on an `acceptor` this is the password for the server-side trust + store. This is only relevant for an `acceptor` if you are using 2-way SSL (i.e. + mutual authentication). + + When used on a `connector` this is the password for the client-side + truststore. Although this value can be configured on the server, it is + downloaded and used by the client. If the client needs to use a different + password from that set on the server then it can override the server-side + setting by either using the customary "javax.net.ssl.trustStorePassword" system + property or the ActiveMQ-specific "org.apache.activemq.ssl.trustStorePassword" + system property. The ActiveMQ-specific system property is useful if another + component on client is already making use of the standard, Java system + property. + +- `enabledCipherSuites` + + Whether used on an `acceptor` or `connector` this is a comma separated list + of cipher suites used for SSL communication. The default value is `null` which + means the JVM's default will be used. + +- `enabledProtocols` + + Whether used on an `acceptor` or `connector` this is a comma separated list + of protocols used for SSL communication. The default value is `null` which + means the JVM's default will be used. + +- `needClientAuth` + + This property is only for an `acceptor`. It tells a client connecting to this + acceptor that 2-way SSL is required. Valid values are `true` or `false`. + Default is `false`. - Note that this property takes precedence over `wantClientAuth` and if - its value is set to true then `wantClientAuth` will be ignored. + **Note:** This property takes precedence over `wantClientAuth` and if its + value is set to true then `wantClientAuth` will be ignored. -- `wantClientAuth` +- `wantClientAuth` - This property is only for an `acceptor`. It tells a client - connecting to this acceptor that 2-way SSL is requested but not required. - Valid values are `true` or `false`. Default is `false`. + This property is only for an `acceptor`. It tells a client connecting to this + acceptor that 2-way SSL is requested but not required. Valid values are `true` + or `false`. Default is `false`. - Note that if the property `needClientAuth` is set to true then that - property will take precedence and this property will be ignored. + **Note:** If the property `needClientAuth` is set to `true` then that + property will take precedence and this property will be ignored. -- `verifyHost` +- `verifyHost` - When used on an `acceptor` the `CN` of the connecting client's SSL certificate - will be compared to its hostname to verify they match. This is useful - only for 2-way SSL. + When used on an `acceptor` the `CN` of the connecting client's SSL + certificate will be compared to its hostname to verify they match. This is + useful only for 2-way SSL. - When used on a `connector` the `CN` of the server's SSL certificate will be - compared to its hostname to verify they match. This is useful for both 1-way - and 2-way SSL. + When used on a `connector` the `CN` of the server's SSL certificate will be + compared to its hostname to verify they match. This is useful for both 1-way + and 2-way SSL. - Valid values are `true` or `false`. Default is `false`. + Valid values are `true` or `false`. Default is `false`. -- `trustAll` +- `trustAll` - When used on a `connector` the client will trust the provided server certificate - implicitly, regardless of any configured trust store. **Warning:** This setting is - primarily for testing purposes only and should not be used in production. + When used on a `connector` the client will trust the provided server + certificate implicitly, regardless of any configured trust store. **Warning:** + This setting is primarily for testing purposes only and should not be used in + production. - Valid values are `true` or `false`. Default is `false`. + Valid values are `true` or `false`. Default is `false`. -- `useDefaultSslContext` +- `useDefaultSslContext` - Only valid on a `connector`. Allows the `connector` to use the "default" SSL - context (via `SSLContext.getDefault()`) which can be set programmatically by - the client (via `SSLContext.setDefault(SSLContext)`). If set to `true` all - other SSL related parameters except for `sslEnabled` are ignored. + Only valid on a `connector`. Allows the `connector` to use the "default" SSL + context (via `SSLContext.getDefault()`) which can be set programmatically by + the client (via `SSLContext.setDefault(SSLContext)`). If set to `true` all + other SSL related parameters except for `sslEnabled` are ignored. - Valid values are `true` or `false`. Default is `false`. + Valid values are `true` or `false`. Default is `false`. -- `sslProvider` - - Used to change the SSL Provider between `JDK` and `OPENSSL`. The default is `JDK`. - If used with `OPENSSL` you can add `netty-tcnative` to your classpath to use the native - installed openssl. This can be useful if you want to use special ciphersuite - elliptic curve combinations - which are support through openssl but not through the JDK provider. See https://en.wikipedia.org/wiki/Comparison_of_TLS_implementations - for more information's. - - +- `sslProvider` + Used to change the SSL Provider between `JDK` and `OPENSSL`. The default is + `JDK`. If used with `OPENSSL` you can add `netty-tcnative` to your classpath + to use the native installed openssl. This can be useful if you want to use + special ciphersuite - elliptic curve combinations which are support through + openssl but not through the JDK provider. See + https://en.wikipedia.org/wiki/Comparison_of_TLS_implementations for more + information's. + ### Configuring Netty HTTP Netty HTTP tunnels packets over the HTTP protocol. It can be useful in @@ -473,22 +461,22 @@ Please see the examples for a full working example of using Netty HTTP. Netty HTTP uses the same properties as Netty TCP but adds the following additional properties: -- `httpEnabled`. This is now no longer needed. With single port support - Apache ActiveMQ Artemis will now automatically detect if http is being - used and configure itself. +- `httpEnabled`. This is now no longer needed. With single port support Apache + ActiveMQ Artemis will now automatically detect if http is being used and + configure itself. -- `httpClientIdleTime`. How long a client can be idle before - sending an empty http request to keep the connection alive +- `httpClientIdleTime`. How long a client can be idle before sending an empty + http request to keep the connection alive -- `httpClientIdleScanPeriod`. How often, in milliseconds, to scan - for idle clients +- `httpClientIdleScanPeriod`. How often, in milliseconds, to scan for idle + clients -- `httpResponseTime`. How long the server can wait before sending an - empty http response to keep the connection alive +- `httpResponseTime`. How long the server can wait before sending an empty http + response to keep the connection alive -- `httpServerScanPeriod`. How often, in milliseconds, to scan for - clients needing responses +- `httpServerScanPeriod`. How often, in milliseconds, to scan for clients + needing responses -- `httpRequiresSessionId`. If `true` the client will wait after the - first call to receive a session id. Used the http connector is - connecting to servlet acceptor (not recommended) +- `httpRequiresSessionId`. If `true` the client will wait after the first call + to receive a session id. Used the http connector is connecting to servlet + acceptor (not recommended)
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/connection-ttl.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/connection-ttl.md b/docs/user-manual/en/connection-ttl.md index a1876bd..3677d6f 100644 --- a/docs/user-manual/en/connection-ttl.md +++ b/docs/user-manual/en/connection-ttl.md @@ -18,8 +18,7 @@ ServerLocator locator = null; ClientSessionFactory sf = null; ClientSession session = null; -try -{ +try { locator = ActiveMQClient.createServerLocatorWithoutHA(..); sf = locator.createClientSessionFactory();; @@ -27,21 +26,16 @@ try session = sf.createSession(...); ... do some stuff with the session... -} -finally -{ - if (session != null) - { +} finally { + if (session != null) { session.close(); } - if (sf != null) - { + if (sf != null) { sf.close(); } - if(locator != null) - { + if(locator != null) { locator.close(); } } @@ -52,18 +46,14 @@ And here's an example of a well behaved JMS client application: ```java Connection jmsConnection = null; -try -{ +try { ConnectionFactory jmsConnectionFactory = new ActiveMQConnectionFactory("tcp://localhost:61616"); jmsConnection = jmsConnectionFactory.createConnection(); ... do some stuff with the connection... -} -finally -{ - if (connection != null) - { +} finally { + if (connection != null) { connection.close(); } } @@ -73,17 +63,13 @@ finally Or with using auto-closeable feature from Java, which can save a few lines of code: ```java - - try ( ActiveMQConnectionFactory jmsConnectionFactory = new ActiveMQConnectionFactory("tcp://localhost:61616"); - Connection jmsConnection = jmsConnectionFactory.createConnection()) -{ + Connection jmsConnection = jmsConnectionFactory.createConnection()) { ... do some stuff with the connection... } ``` - Unfortunately users don't always write well behaved applications, and sometimes clients just crash so they don't have a chance to clean up their resources! @@ -186,17 +172,17 @@ from a thread pool so that the remoting thread is not tied up for too long. Please note that processing operations asynchronously on another thread adds a little more latency. These packets are: -- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.RollbackMessage` +- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.RollbackMessage` -- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionCloseMessage` +- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionCloseMessage` -- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionCommitMessage` +- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionCommitMessage` -- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionXACommitMessage` +- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionXACommitMessage` -- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionXAPrepareMessage` +- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionXAPrepareMessage` -- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionXARollbackMessage` +- `org.apache.activemq.artemis.core.protocol.core.impl.wireformat.SessionXARollbackMessage` To disable asynchronous connection execution, set the parameter `async-connection-execution-enabled` in `broker.xml` to http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/core-bridges.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/core-bridges.md b/docs/user-manual/en/core-bridges.md index 668a3b5..ede12ab 100644 --- a/docs/user-manual/en/core-bridges.md +++ b/docs/user-manual/en/core-bridges.md @@ -1,45 +1,46 @@ # Core Bridges The function of a bridge is to consume messages from a source queue, and -forward them to a target address, typically on a different Apache ActiveMQ Artemis -server. +forward them to a target address, typically on a different Apache ActiveMQ +Artemis server. -The source and target servers do not have to be in the same cluster -which makes bridging suitable for reliably sending messages from one -cluster to another, for instance across a WAN, or internet and where the -connection may be unreliable. +The source and target servers do not have to be in the same cluster which makes +bridging suitable for reliably sending messages from one cluster to another, +for instance across a WAN, or internet and where the connection may be +unreliable. The bridge has built in resilience to failure so if the target server connection is lost, e.g. due to network failure, the bridge will retry -connecting to the target until it comes back online. When it comes back -online it will resume operation as normal. +connecting to the target until it comes back online. When it comes back online +it will resume operation as normal. -In summary, bridges are a way to reliably connect two separate Apache ActiveMQ Artemis -servers together. With a core bridge both source and target servers must -be Apache ActiveMQ Artemis servers. +In summary, bridges are a way to reliably connect two separate Apache ActiveMQ +Artemis servers together. With a core bridge both source and target servers +must be Apache ActiveMQ Artemis servers. -Bridges can be configured to provide *once and only once* delivery -guarantees even in the event of the failure of the source or the target -server. They do this by using duplicate detection (described in [Duplicate Detection](duplicate-detection.md)). +Bridges can be configured to provide *once and only once* delivery guarantees +even in the event of the failure of the source or the target server. They do +this by using duplicate detection (described in [Duplicate +Detection](duplicate-detection.md)). -> **Note** +> **Note:** > -> Although they have similar function, don't confuse core bridges with -> JMS bridges! +> Although they have similar function, don't confuse core bridges with JMS +> bridges! > -> Core bridges are for linking an Apache ActiveMQ Artemis node with another Apache ActiveMQ Artemis -> node and do not use the JMS API. A JMS Bridge is used for linking any -> two JMS 1.1 compliant JMS providers. So, a JMS Bridge could be used -> for bridging to or from different JMS compliant messaging system. It's -> always preferable to use a core bridge if you can. Core bridges use -> duplicate detection to provide *once and only once* guarantees. To -> provide the same guarantee using a JMS bridge you would have to use XA -> which has a higher overhead and is more complex to configure. +> Core bridges are for linking an Apache ActiveMQ Artemis node with another +> Apache ActiveMQ Artemis node and do not use the JMS API. A JMS Bridge is used +> for linking any two JMS 1.1 compliant JMS providers. So, a JMS Bridge could +> be used for bridging to or from different JMS compliant messaging system. +> It's always preferable to use a core bridge if you can. Core bridges use +> duplicate detection to provide *once and only once* guarantees. To provide +> the same guarantee using a JMS bridge you would have to use XA which has a +> higher overhead and is more complex to configure. ## Configuring Bridges -Bridges are configured in `broker.xml`. Let's kick off -with an example (this is actually from the bridge example): +Bridges are configured in `broker.xml`. Let's kick off with an example (this is +actually from the bridge example): ```xml <bridge name="my-bridge"> @@ -68,154 +69,144 @@ with an example (this is actually from the bridge example): </bridge> ``` -In the above example we have shown all the parameters its possible to -configure for a bridge. In practice you might use many of the defaults -so it won't be necessary to specify them all explicitly. +In the above example we have shown all the parameters its possible to configure +for a bridge. In practice you might use many of the defaults so it won't be +necessary to specify them all explicitly. Let's take a look at all the parameters in turn: -- `name` attribute. All bridges must have a unique name in the server. +- `name` attribute. All bridges must have a unique name in the server. -- `queue-name`. This is the unique name of the local queue that the - bridge consumes from, it's a mandatory parameter. +- `queue-name`. This is the unique name of the local queue that the bridge + consumes from, it's a mandatory parameter. - The queue must already exist by the time the bridge is instantiated - at start-up. - -- `forwarding-address`. This is the address on the target server that - the message will be forwarded to. If a forwarding address is not - specified, then the original address of the message will be - retained. - -- `filter-string`. An optional filter string can be supplied. If - specified then only messages which match the filter expression - specified in the filter string will be forwarded. The filter string - follows the ActiveMQ Artemis filter expression syntax described in [Filter Expressions](filter-expressions.md). - -- `transformer-class-name`. An optional transformer-class-name can be - specified. This is the name of a user-defined class which implements - the `org.apache.activemq.artemis.core.server.transformer.Transformer` interface. - - If this is specified then the transformer's `transform()` method - will be invoked with the message before it is forwarded. This gives - you the opportunity to transform the message's header or body before - forwarding it. - -- `ha`. This optional parameter determines whether or not this bridge - should support high availability. True means it will connect to any - available server in a cluster and support failover. The default - value is `false`. - -- `retry-interval`. This optional parameter determines the period in - milliseconds between subsequent reconnection attempts, if the - connection to the target server has failed. The default value is - `2000`milliseconds. - -- `retry-interval-multiplier`. This optional parameter determines - determines a multiplier to apply to the time since the last retry to - compute the time to the next retry. - - This allows you to implement an *exponential backoff* between retry - attempts. - - Let's take an example: - - If we set `retry-interval`to `1000` ms and we set - `retry-interval-multiplier` to `2.0`, then, if the first reconnect - attempt fails, we will wait `1000` ms then `2000` ms then `4000` ms - between subsequent reconnection attempts. - - The default value is `1.0` meaning each reconnect attempt is spaced - at equal intervals. - -- `initial-connect-attempts`. This optional parameter determines the - total number of initial connect attempts the bridge will make before - giving up and shutting down. A value of `-1` signifies an unlimited - number of attempts. The default value is `-1`. - -- `reconnect-attempts`. This optional parameter determines the total - number of reconnect attempts the bridge will make before giving up - and shutting down. A value of `-1` signifies an unlimited number of - attempts. The default value is `-1`. - -- `failover-on-server-shutdown`. This optional parameter determines - whether the bridge will attempt to failover onto a backup server (if - specified) when the target server is cleanly shutdown rather than - crashed. - - The bridge connector can specify both a live and a backup server, if - it specifies a backup server and this parameter is set to `true` - then if the target server is *cleanly* shutdown the bridge - connection will attempt to failover onto its backup. If the bridge - connector has no backup server configured then this parameter has no - effect. - - Sometimes you want a bridge configured with a live and a backup - target server, but you don't want to failover to the backup if the - live server is simply taken down temporarily for maintenance, this - is when this parameter comes in handy. - - The default value for this parameter is `false`. - -- `use-duplicate-detection`. This optional parameter determines - whether the bridge will automatically insert a duplicate id property - into each message that it forwards. - - Doing so, allows the target server to perform duplicate detection on - messages it receives from the source server. If the connection fails - or server crashes, then, when the bridge resumes it will resend - unacknowledged messages. This might result in duplicate messages - being sent to the target server. By enabling duplicate detection - allows these duplicates to be screened out and ignored. - - This allows the bridge to provide a *once and only once* delivery - guarantee without using heavyweight methods such as XA (see [Duplicate Detection](duplicate-detection.md) for - more information). - - The default value for this parameter is `true`. - -- `confirmation-window-size`. This optional parameter determines the - `confirmation-window-size` to use for the connection used to forward - messages to the target node. This attribute is described in section - [Reconnection and Session Reattachment](client-reconnection.md) - - > **Warning** - > - > When using the bridge to forward messages to an address which uses - > the `BLOCK` `address-full-policy` from a queue which has a - > `max-size-bytes` set it's important that - > `confirmation-window-size` is less than or equal to - > `max-size-bytes` to prevent the flow of messages from ceasing. - -- `producer-window-size`. This optional parameter determines the - producer flow control through the bridge. You usually leave this off - unless you are dealing with huge large messages. + The queue must already exist by the time the bridge is instantiated at + start-up. + +- `forwarding-address`. This is the address on the target server that the + message will be forwarded to. If a forwarding address is not specified, then + the original address of the message will be retained. + +- `filter-string`. An optional filter string can be supplied. If specified then + only messages which match the filter expression specified in the filter + string will be forwarded. The filter string follows the ActiveMQ Artemis filter + expression syntax described in [Filter Expressions](filter-expressions.md). + +- `transformer-class-name`. An optional transformer-class-name can be + specified. This is the name of a user-defined class which implements the + `org.apache.activemq.artemis.core.server.transformer.Transformer` interface. + + If this is specified then the transformer's `transform()` method will be + invoked with the message before it is forwarded. This gives you the opportunity + to transform the message's header or body before forwarding it. + +- `ha`. This optional parameter determines whether or not this bridge should + support high availability. True means it will connect to any available server + in a cluster and support failover. The default value is `false`. + +- `retry-interval`. This optional parameter determines the period in + milliseconds between subsequent reconnection attempts, if the connection to + the target server has failed. The default value is `2000`milliseconds. + +- `retry-interval-multiplier`. This optional parameter determines determines a + multiplier to apply to the time since the last retry to compute the time to + the next retry. + + This allows you to implement an *exponential backoff* between retry + attempts. + + Let's take an example: + + If we set `retry-interval`to `1000` ms and we set `retry-interval-multiplier` + to `2.0`, then, if the first reconnect attempt fails, we will wait `1000` ms + then `2000` ms then `4000` ms between subsequent reconnection attempts. + + The default value is `1.0` meaning each reconnect attempt is spaced at equal + intervals. + +- `initial-connect-attempts`. This optional parameter determines the total + number of initial connect attempts the bridge will make before giving up and + shutting down. A value of `-1` signifies an unlimited number of attempts. The + default value is `-1`. + +- `reconnect-attempts`. This optional parameter determines the total number of + reconnect attempts the bridge will make before giving up and shutting down. A + value of `-1` signifies an unlimited number of attempts. The default value is + `-1`. + +- `failover-on-server-shutdown`. This optional parameter determines whether the + bridge will attempt to failover onto a backup server (if specified) when the + target server is cleanly shutdown rather than crashed. + + The bridge connector can specify both a live and a backup server, if it + specifies a backup server and this parameter is set to `true` then if the + target server is *cleanly* shutdown the bridge connection will attempt to + failover onto its backup. If the bridge connector has no backup server + configured then this parameter has no effect. + + Sometimes you want a bridge configured with a live and a backup target + server, but you don't want to failover to the backup if the live server is + simply taken down temporarily for maintenance, this is when this parameter + comes in handy. + + The default value for this parameter is `false`. + +- `use-duplicate-detection`. This optional parameter determines whether the + bridge will automatically insert a duplicate id property into each message + that it forwards. + + Doing so, allows the target server to perform duplicate detection on messages + it receives from the source server. If the connection fails or server crashes, + then, when the bridge resumes it will resend unacknowledged messages. This + might result in duplicate messages being sent to the target server. By enabling + duplicate detection allows these duplicates to be screened out and ignored. + + This allows the bridge to provide a *once and only once* delivery guarantee + without using heavyweight methods such as XA (see [Duplicate + Detection](duplicate-detection.md) for more information). + + The default value for this parameter is `true`. + +- `confirmation-window-size`. This optional parameter determines the + `confirmation-window-size` to use for the connection used to forward messages + to the target node. This attribute is described in section [Reconnection and + Session Reattachment](client-reconnection.md) + + > **Warning** + > + > When using the bridge to forward messages to an address which uses the + > `BLOCK` `address-full-policy` from a queue which has a `max-size-bytes` set + > it's important that `confirmation-window-size` is less than or equal to + > `max-size-bytes` to prevent the flow of messages from ceasing. + +- `producer-window-size`. This optional parameter determines the producer flow + control through the bridge. You usually leave this off unless you are dealing + with huge large messages. - Default=-1 (disabled) - -- `user`. This optional parameter determines the user name to use when - creating the bridge connection to the remote server. If it is not - specified the default cluster user specified by `cluster-user` in - `broker.xml` will be used. - -- `password`. This optional parameter determines the password to use - when creating the bridge connection to the remote server. If it is - not specified the default cluster password specified by - `cluster-password` in `broker.xml` will be used. - -- `static-connectors` or `discovery-group-ref`. Pick either of these - options to connect the bridge to the target server. - - The `static-connectors` is a list of `connector-ref` elements - pointing to `connector` elements defined elsewhere. A *connector* - encapsulates knowledge of what transport to use (TCP, SSL, HTTP etc) - as well as the server connection parameters (host, port etc). For - more information about what connectors are and how to configure - them, please see [Configuring the Transport](configuring-transports.md). - - The `discovery-group-ref` element has one attribute - - `discovery-group-name`. This attribute points to a `discovery-group` - defined elsewhere. For more information about what discovery-groups - are and how to configure them, please see [Discovery Groups](clusters.md). + Default=-1 (disabled) + +- `user`. This optional parameter determines the user name to use when creating + the bridge connection to the remote server. If it is not specified the + default cluster user specified by `cluster-user` in `broker.xml` will be used. + +- `password`. This optional parameter determines the password to use when + creating the bridge connection to the remote server. If it is not specified + the default cluster password specified by `cluster-password` in `broker.xml` + will be used. + +- `static-connectors` or `discovery-group-ref`. Pick either of these options to + connect the bridge to the target server. + + The `static-connectors` is a list of `connector-ref` elements pointing to + `connector` elements defined elsewhere. A *connector* encapsulates knowledge of + what transport to use (TCP, SSL, HTTP etc) as well as the server connection + parameters (host, port etc). For more information about what connectors are and + how to configure them, please see [Configuring the + Transport](configuring-transports.md). + + The `discovery-group-ref` element has one attribute - `discovery-group-name`. + This attribute points to a `discovery-group` defined elsewhere. For more + information about what discovery-groups are and how to configure them, please + see [Discovery Groups](clusters.md). http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/core.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/core.md b/docs/user-manual/en/core.md new file mode 100644 index 0000000..cd8d131 --- /dev/null +++ b/docs/user-manual/en/core.md @@ -0,0 +1,228 @@ +# Using Core + +Apache ActiveMQ Artemis core is a messaging system with its own API. We call +this the *core API*. + +If you don't want to use the JMS API or any of the other supported protocols +you can use the core API directly. The core API provides all the functionality +of JMS but without much of the complexity. It also provides features that are +not available using JMS. + +## Core Messaging Concepts + +Some of the core messaging concepts are similar to JMS concepts, but core +messaging concepts are also different in some ways as well. In general the core +API is simpler than the JMS API, since we remove distinctions between queues, +topics and subscriptions. We'll discuss each of the major core messaging +concepts in turn, but to see the API in detail please consult the Javadoc. + +Also refer to the [addressing model](address-model.md) chapter for a high-level +overview of these concepts as well as configuration details. + +### Message + +- A message is the unit of data which is sent between clients and servers. + +- A message has a body which is a buffer containing convenient methods for + reading and writing data into it. + +- A message has a set of properties which are key-value pairs. Each property + key is a string and property values can be of type integer, long, short, + byte, byte[], String, double, float or boolean. + +- A message has an *address* it is being sent to. When the message arrives on + the server it is routed to any queues that are bound to the address. The + routing semantics (i.e. anycast or multicast) are determined by the "routing + type" of the address and queue. If the queues are bound with any filter, the + message will only be routed to that queue if the filter matches. An address may + have many queues bound to it or even none. There may also be entities other + than queues (e.g. *diverts*) bound to addresses. + +- Messages can be either durable or non durable. Durable messages in a durable + queue will survive a server crash or restart. Non durable messages will never + survive a server crash or restart. + +- Messages can be specified with a priority value between 0 and 9. 0 represents + the lowest priority and 9 represents the highest. The broker will attempt to + deliver higher priority messages before lower priority ones. + +- Messages can be specified with an optional expiry time. The broker will not + deliver messages after its expiry time has been exceeded. + +- Messages also have an optional timestamp which represents the time the + message was sent. + +- Apache ActiveMQ Artemis also supports the sending/consuming of very large + messages much larger than can fit in available RAM at any one time. + +### Address + +A server maintains a mapping between an address and a set of queues. Zero or +more queues can be bound to a single address. Each queue can be bound with an +optional message filter. When a message is routed, it is routed to the set of +queues bound to the message's address. If any of the queues are bound with a +filter expression, then the message will only be routed to the subset of bound +queues which match that filter expression. + +Other entities, such as *diverts* can also be bound to an address and messages +will also be routed there. + +> **Note:** +> +> Although core supports publish-subscribe semantics there is no such thing as +> a "topic" per se. "Topic" is mainly a JMS term. In core we just deal with +> *addresses*, *queues*, and *routing types*. +> +> For example, a JMS topic would be implemented by a single address to which +> many queues are bound using multicast routing. Each queue represents a +> "subscription" in normal "topic" terms. A JMS queue would be implemented as a +> single address to which one queue is bound using anycast routing - that queue +> represents the JMS queue. + +### Queue + +Queues can be durable, meaning the messages they contain survive a server crash +or restart, as long as the messages in them are durable. Non durable queues do +not survive a server restart or crash even if the messages they contain are +durable. + +Queues can also be temporary, meaning they are automatically deleted when the +client connection is closed, if they are not explicitly deleted before that. + +Queues can be bound with an optional filter expression. If a filter expression +is supplied then the server will only route messages that match that filter +expression to any queues bound to the address. + +Many queues can be bound to a single address. A particular queue is only bound +to a maximum of one address. + +### Routing Type + +The routing type determines the semantics used when routing messages to the +queues bound to the address where the message was sent. Two types are +supported: + +- `ANYCAST` + + The message is routed to only **one** of the queues bound to the address. If + multiple queues are bound to the address then messages are routed to them in a + round-robin fashion. + +- `MULTICAST` + + The message is route to **all** of the queues bound to the address. + +## Core API + +### ServerLocator + +Clients use `ServerLocator` instances to create `ClientSessionFactory` +instances. `ServerLocator` instances are used to locate servers and create +connections to them. + +In JMS terms think of a `ServerLocator` in the same way you would a JMS +Connection Factory. + +`ServerLocator` instances are created using the `ActiveMQClient` factory class. + +### ClientSessionFactory + +Clients use `ClientSessionFactory` instances to create `ClientSession` +instances. `ClientSessionFactory` instances are basically the connection to a +server + +In JMS terms think of them as JMS Connections. + +`ClientSessionFactory` instances are created using the `ServerLocator` class. + +### ClientSession + +A client uses a `ClientSession`for consuming and producing messages and for +grouping them in transactions. `ClientSession` instances can support both +transactional and non transactional semantics and also provide an `XAResource` +interface so messaging operations can be performed as part of a +[JTA](http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html) +transaction. + +`ClientSession` instances group `ClientConsumer` instances and `ClientProducer` +instances. + +`ClientSession` instances can be registered with an optional +`SendAcknowledgementHandler`. This allows your client code to be notified +asynchronously when sent messages have successfully reached the server. This +unique Apache ActiveMQ Artemis feature, allows you to have full guarantees that +sent messages have reached the server without having to block on each message +sent until a response is received. Blocking on each messages sent is costly +since it requires a network round trip for each message sent. By not blocking +and receiving send acknowledgements asynchronously you can create true end to +end asynchronous systems which is not possible using the standard JMS API. For +more information on this advanced feature please see the section [Guarantees of +sends and commits](send-guarantees.md). + +### ClientConsumer + +Clients use `ClientConsumer` instances to consume messages from a queue. Core +messaging supports both synchronous and asynchronous message consumption +semantics. `ClientConsumer` instances can be configured with an optional filter +expression and will only consume messages which match that expression. + +### ClientProducer + +Clients create `ClientProducer` instances on `ClientSession` instances so they +can send messages. `ClientProducer` instances can specify an address to which +all sent messages are routed, or they can have no specified address, and the +address is specified at send time for the message. + +> **Warning** +> +> Please note that `ClientSession`, `ClientProducer` and `ClientConsumer` +> instances are *designed to be re-used*. +> +> It's an anti-pattern to create new `ClientSession`, `ClientProducer` and +> `ClientConsumer` instances for each message you produce or consume. If you do +> this, your application will perform very poorly. This is discussed further +> in the section on performance tuning [Performance Tuning](perf-tuning.md). + +## A simple example of using Core + +Here's a very simple program using the core messaging API to send and receive a +message. Logically it's comprised of two sections: firstly setting up the +producer to write a message to an *addresss*, and secondly, creating a *queue* +for the consumer using anycast routing, creating the consumer, and *starting* +it. + +```java +ServerLocator locator = ActiveMQClient.createServerLocator("vm://0"); + +// In this simple example, we just use one session for both producing and receiving + +ClientSessionFactory factory = locator.createClientSessionFactory(); +ClientSession session = factory.createSession(); + +// A producer is associated with an address ... + +ClientProducer producer = session.createProducer("example"); +ClientMessage message = session.createMessage(true); +message.getBodyBuffer().writeString("Hello"); + +// We need a queue attached to the address ... + +session.createQueue("example", RoutingType.ANYCAST, "example", true); + +// And a consumer attached to the queue ... + +ClientConsumer consumer = session.createConsumer("example"); + +// Once we have a queue, we can send the message ... + +producer.send(message); + +// We need to start the session before we can -receive- messages ... + +session.start(); +ClientMessage msgReceived = consumer.receive(); + +System.out.println("message = " + msgReceived.getBodyBuffer().readString()); + +session.close(); +``` http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/critical-analysis.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/critical-analysis.md b/docs/user-manual/en/critical-analysis.md index 18c17cd..40da82d 100644 --- a/docs/user-manual/en/critical-analysis.md +++ b/docs/user-manual/en/critical-analysis.md @@ -22,7 +22,7 @@ You can use these following configuration options on broker.xml to configure how Name | Description -:--- | :--- +--- | --- critical-analyzer | Enable or disable the critical analysis (default true) critical-analyzer-timeout | Timeout used to do the critical analysis (default 120000 milliseconds) critical-analyzer-check-period | Time used to check the response times (default half of critical-analyzer-timeout) @@ -42,7 +42,7 @@ If you have critical-analyzer-policy=HALT [Artemis Critical Analyzer] 18:10:00,831 ERROR [org.apache.activemq.artemis.core.server] AMQ224079: The process for the virtual machine will be killed, as component org.apache.activemq.artemis.tests.integration.critical.CriticalSimpleTest$2@5af97850 is not responsive ``` -While if you have critical-analyzer-policy=SHUTDOWN +While if you have critical-analyzer-policy=`SHUTDOWN` ``` [Artemis Critical Analyzer] 18:07:53,475 ERROR [org.apache.activemq.artemis.core.server] AMQ224080: The server process will now be stopped, as component org.apache.activemq.artemis.tests.integration.critical.CriticalSimpleTest$2@5af97850 is not responsive @@ -85,7 +85,7 @@ AMQ119003: End Thread dump - The Server will be halted if configured to `HALT` -- The system will be stopped if `SHUTDOWN` is used: -* Notice that if the system is not behaving well, there is no guarantees the stop will work. +- The system will be stopped if `SHUTDOWN` is used. **Notice**: If the system + is not behaving well, there is no guarantees the stop will work. http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/data-tools.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/data-tools.md b/docs/user-manual/en/data-tools.md new file mode 100644 index 0000000..fb7443f --- /dev/null +++ b/docs/user-manual/en/data-tools.md @@ -0,0 +1,348 @@ +# Data Tools + +You can use the Artemis CLI to execute data maintenance tools: + +This is a list of sub-commands available + +Name | Description +---|--- +exp | Export the message data using a special and independent XML format +imp | Imports the journal to a running broker using the output from expt +data | Prints a report about journal records and summary of existent records, as well a report on paging +encode | shows an internal format of the journal encoded to String +decode | imports the internal journal format from encode + +You can use the help at the tool for more information on how to execute each of the tools. For example: + +``` +$ ./artemis help data print +NAME + artemis data print - Print data records information (WARNING: don't use + while a production server is running) + +SYNOPSIS + artemis data print [--bindings <binding>] [--broker <brokerConfig>] + [--f] [--jdbc] [--jdbc-bindings-table-name <jdbcBindings>] + [--jdbc-connection-url <jdbcURL>] + [--jdbc-driver-class-name <jdbcClassName>] + [--jdbc-large-message-table-name <jdbcLargeMessages>] + [--jdbc-message-table-name <jdbcMessages>] + [--jdbc-page-store-table-name <jdbcPageStore>] [--journal <journal>] + [--large-messages <largeMessges>] [--output <output>] + [--paging <paging>] [--safe] [--verbose] [--] [<configuration>] + +OPTIONS + --bindings <binding> + The folder used for bindings (default from broker.xml) + + --broker <brokerConfig> + This would override the broker configuration from the bootstrap + + --f + This will allow certain tools like print-data to be performed + ignoring any running servers. WARNING: Changing data concurrently + with a running broker may damage your data. Be careful with this + option. + + --jdbc + It will activate jdbc + + --jdbc-bindings-table-name <jdbcBindings> + Name of the jdbc bindigns table + + --jdbc-connection-url <jdbcURL> + The connection used for the database + + --jdbc-driver-class-name <jdbcClassName> + JDBC driver classname + + --jdbc-large-message-table-name <jdbcLargeMessages> + Name of the large messages table + + --jdbc-message-table-name <jdbcMessages> + Name of the jdbc messages table + + --jdbc-page-store-table-name <jdbcPageStore> + Name of the page sotre messages table + + --journal <journal> + The folder used for messages journal (default from broker.xml) + + --large-messages <largeMessges> + The folder used for large-messages (default from broker.xml) + + --output <output> + Output name for the file + + --paging <paging> + The folder used for paging (default from broker.xml) + + --safe + It will print your data structure without showing your data + + --verbose + Adds more information on the execution + + -- + This option can be used to separate command-line options from the + list of argument, (useful when arguments might be mistaken for + command-line options + + <configuration> + Broker Configuration URI, default + 'xml:${ARTEMIS_INSTANCE}/etc/bootstrap.xml' +``` + + +For a full list of data tools commands available use: + +``` +$ ./artemis help data +NAME + artemis data - data tools group (print|imp|exp|encode|decode|compact) + (example ./artemis data print) + +SYNOPSIS + artemis data + artemis data compact [--verbose] [--paging <paging>] + [--journal <journal>] [--large-messages <largeMessges>] + [--broker <brokerConfig>] [--bindings <binding>] + artemis data decode [--verbose] [--suffix <suffix>] [--paging <paging>] + [--prefix <prefix>] [--file-size <size>] --input <input> + [--journal <journal>] [--directory <directory>] + [--large-messages <largeMessges>] [--broker <brokerConfig>] + [--bindings <binding>] + artemis data encode [--verbose] [--directory <directory>] + [--suffix <suffix>] [--paging <paging>] [--prefix <prefix>] + [--file-size <size>] [--journal <journal>] + [--large-messages <largeMessges>] [--broker <brokerConfig>] + [--bindings <binding>] + artemis data exp [--jdbc-bindings-table-name <jdbcBindings>] + [--jdbc-message-table-name <jdbcMessages>] [--paging <paging>] + [--jdbc-connection-url <jdbcURL>] + [--jdbc-large-message-table-name <jdbcLargeMessages>] [--f] + [--large-messages <largeMessges>] [--broker <brokerConfig>] + [--jdbc-page-store-table-name <jdbcPageStore>] + [--jdbc-driver-class-name <jdbcClassName>] [--jdbc] [--verbose] + [--journal <journal>] [--output <output>] [--bindings <binding>] + artemis data imp [--user <user>] [--legacy-prefixes] [--verbose] + [--host <host>] [--port <port>] [--transaction] --input <input> + [--password <password>] [--sort] + artemis data print [--jdbc-bindings-table-name <jdbcBindings>] + [--jdbc-message-table-name <jdbcMessages>] [--paging <paging>] + [--jdbc-connection-url <jdbcURL>] + [--jdbc-large-message-table-name <jdbcLargeMessages>] [--f] + [--large-messages <largeMessges>] [--broker <brokerConfig>] + [--jdbc-page-store-table-name <jdbcPageStore>] + [--jdbc-driver-class-name <jdbcClassName>] [--safe] [--jdbc] [--verbose] + [--journal <journal>] [--output <output>] [--bindings <binding>] + +COMMANDS + With no arguments, Display help information + + print + Print data records information (WARNING: don't use while a + production server is running) + + With --jdbc-bindings-table-name option, Name of the jdbc bindigns + table + + With --jdbc-message-table-name option, Name of the jdbc messages + table + + With --paging option, The folder used for paging (default from + broker.xml) + + With --jdbc-connection-url option, The connection used for the + database + + With --jdbc-large-message-table-name option, Name of the large + messages table + + With --f option, This will allow certain tools like print-data to be + performed ignoring any running servers. WARNING: Changing data + concurrently with a running broker may damage your data. Be careful + with this option. + + With --large-messages option, The folder used for large-messages + (default from broker.xml) + + With --broker option, This would override the broker configuration + from the bootstrap + + With --jdbc-page-store-table-name option, Name of the page sotre + messages table + + With --jdbc-driver-class-name option, JDBC driver classname + + With --safe option, It will print your data structure without + showing your data + + With --jdbc option, It will activate jdbc + + With --verbose option, Adds more information on the execution + + With --journal option, The folder used for messages journal (default + from broker.xml) + + With --output option, Output name for the file + + With --bindings option, The folder used for bindings (default from + broker.xml) + + exp + Export all message-data using an XML that could be interpreted by + any system. + + With --jdbc-bindings-table-name option, Name of the jdbc bindigns + table + + With --jdbc-message-table-name option, Name of the jdbc messages + table + + With --paging option, The folder used for paging (default from + broker.xml) + + With --jdbc-connection-url option, The connection used for the + database + + With --jdbc-large-message-table-name option, Name of the large + messages table + + With --f option, This will allow certain tools like print-data to be + performed ignoring any running servers. WARNING: Changing data + concurrently with a running broker may damage your data. Be careful + with this option. + + With --large-messages option, The folder used for large-messages + (default from broker.xml) + + With --broker option, This would override the broker configuration + from the bootstrap + + With --jdbc-page-store-table-name option, Name of the page sotre + messages table + + With --jdbc-driver-class-name option, JDBC driver classname + + With --jdbc option, It will activate jdbc + + With --verbose option, Adds more information on the execution + + With --journal option, The folder used for messages journal (default + from broker.xml) + + With --output option, Output name for the file + + With --bindings option, The folder used for bindings (default from + broker.xml) + + imp + Import all message-data using an XML that could be interpreted by + any system. + + With --user option, User name used to import the data. (default + null) + + With --legacy-prefixes option, Do not remove prefixes from legacy + imports + + With --verbose option, Adds more information on the execution + + With --host option, The host used to import the data (default + localhost) + + With --port option, The port used to import the data (default 61616) + + With --transaction option, If this is set to true you will need a + whole transaction to commit at the end. (default false) + + With --input option, The input file name (default=exp.dmp) + + With --password option, User name used to import the data. (default + null) + + With --sort option, Sort the messages from the input (used for older + versions that won't sort messages) + + decode + Decode a journal's internal format into a new journal set of files + + With --verbose option, Adds more information on the execution + + With --suffix option, The journal suffix (default amq) + + With --paging option, The folder used for paging (default from + broker.xml) + + With --prefix option, The journal prefix (default activemq-data) + + With --file-size option, The journal size (default 10485760) + + With --input option, The input file name (default=exp.dmp) + + With --journal option, The folder used for messages journal (default + from broker.xml) + + With --directory option, The journal folder (default journal folder + from broker.xml) + + With --large-messages option, The folder used for large-messages + (default from broker.xml) + + With --broker option, This would override the broker configuration + from the bootstrap + + With --bindings option, The folder used for bindings (default from + broker.xml) + + encode + Encode a set of journal files into an internal encoded data format + + With --verbose option, Adds more information on the execution + + With --directory option, The journal folder (default the journal + folder from broker.xml) + + With --suffix option, The journal suffix (default amq) + + With --paging option, The folder used for paging (default from + broker.xml) + + With --prefix option, The journal prefix (default activemq-data) + + With --file-size option, The journal size (default 10485760) + + With --journal option, The folder used for messages journal (default + from broker.xml) + + With --large-messages option, The folder used for large-messages + (default from broker.xml) + + With --broker option, This would override the broker configuration + from the bootstrap + + With --bindings option, The folder used for bindings (default from + broker.xml) + + compact + Compacts the journal of a non running server + + With --verbose option, Adds more information on the execution + + With --paging option, The folder used for paging (default from + broker.xml) + + With --journal option, The folder used for messages journal (default + from broker.xml) + + With --large-messages option, The folder used for large-messages + (default from broker.xml) + + With --broker option, This would override the broker configuration + from the bootstrap + + With --bindings option, The folder used for bindings (default from + broker.xml) + +``` \ No newline at end of file
