mirror of
https://github.com/apache/activemq-artemis.git
synced 2025-02-08 19:15:08 +00:00
9a587c5633
https://issues.apache.org/jira/browse/ACTIVEMQ6-3 We are renaming packages from activemq6 to activemq as that's more generic and version independent The previous commit renamed the directories. On this commit now I'm changing the code. If we changed the code and the directories on the same commit git would remove and add a lot of files without recognizing the renames.
204 lines
12 KiB
XML
204 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!-- ============================================================================= -->
|
||
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
|
||
<!-- -->
|
||
<!-- The text of and illustrations in this document are licensed by Red Hat under -->
|
||
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
|
||
<!-- -->
|
||
<!-- An explanation of CC-BY-SA is available at -->
|
||
<!-- -->
|
||
<!-- http://creativecommons.org/licenses/by-sa/3.0/. -->
|
||
<!-- -->
|
||
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
|
||
<!-- of it, you must provide the URL for the original version. -->
|
||
<!-- -->
|
||
<!-- Red Hat, as the licensor of this document, waives the right to enforce, -->
|
||
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
|
||
<!-- permitted by applicable law. -->
|
||
<!-- ============================================================================= -->
|
||
|
||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent">
|
||
%BOOK_ENTITIES;
|
||
]>
|
||
<chapter id="connection-ttl">
|
||
<title>Detecting Dead Connections</title>
|
||
<para>In this section we will discuss connection time-to-live (TTL) and explain how HornetQ
|
||
deals with crashed clients and clients which have exited without cleanly closing their
|
||
resources.</para>
|
||
<section id="dead.connections">
|
||
<title>Cleaning up Dead Connection Resources on the Server</title>
|
||
<para>Before a HornetQ client application exits it is considered good practice that it
|
||
should close its resources in a controlled manner, using a <literal>finally</literal>
|
||
block.</para>
|
||
<para>Here's an example of a well behaved core client application closing its session and
|
||
session factory in a finally block:</para>
|
||
<programlisting>
|
||
ServerLocator locator = null;
|
||
ClientSessionFactory sf = null;
|
||
ClientSession session = null;
|
||
|
||
try
|
||
{
|
||
locator = HornetQClient.createServerLocatorWithoutHA(..);
|
||
|
||
sf = locator.createClientSessionFactory();;
|
||
|
||
session = sf.createSession(...);
|
||
|
||
... do some stuff with the session...
|
||
}
|
||
finally
|
||
{
|
||
if (session != null)
|
||
{
|
||
session.close();
|
||
}
|
||
|
||
if (sf != null)
|
||
{
|
||
sf.close();
|
||
}
|
||
|
||
if(locator != null)
|
||
{
|
||
locator.close();
|
||
}
|
||
}</programlisting>
|
||
<para>And here's an example of a well behaved JMS client application:</para>
|
||
<programlisting>
|
||
Connection jmsConnection = null;
|
||
|
||
try
|
||
{
|
||
ConnectionFactory jmsConnectionFactory = HornetQJMSClient.createConnectionFactoryWithoutHA(...);
|
||
|
||
jmsConnection = jmsConnectionFactory.createConnection();
|
||
|
||
... do some stuff with the connection...
|
||
}
|
||
finally
|
||
{
|
||
if (connection != null)
|
||
{
|
||
connection.close();
|
||
}
|
||
}</programlisting>
|
||
<para>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!</para>
|
||
<para>If this occurs then it can leave server side resources, like sessions, hanging on the
|
||
server. If these were not removed they would cause a resource leak on the server and
|
||
over time this result in the server running out of memory or other resources.</para>
|
||
<para>We have to balance the requirement for cleaning up dead client resources with the fact
|
||
that sometimes the network between the client and the server can fail and then come
|
||
back, allowing the client to reconnect. HornetQ supports client reconnection, so we
|
||
don't want to clean up "dead" server side resources too soon or this will prevent any
|
||
client from reconnecting, as it won't be able to find its old sessions on the
|
||
server.</para>
|
||
<para>HornetQ makes all of this configurable. For each <literal
|
||
>ClientSessionFactory</literal> we define a <emphasis>connection TTL</emphasis>.
|
||
Basically, the TTL determines how long the server will keep a connection alive in the
|
||
absence of any data arriving from the client. The client will automatically send "ping"
|
||
packets periodically to prevent the server from closing it down. If the server doesn't
|
||
receive any packets on a connection for the connection TTL time, then it will
|
||
automatically close all the sessions on the server that relate to that
|
||
connection.</para>
|
||
<para>If you're using JMS, the connection TTL is defined by the <literal
|
||
>ConnectionTTL</literal> attribute on a <literal>HornetQConnectionFactory</literal>
|
||
instance, or if you're deploying JMS connection factory instances direct into JNDI on
|
||
the server side, you can specify it in the xml config, using the parameter <literal
|
||
>connection-ttl</literal>.</para>
|
||
<para>The default value for connection ttl on an "unreliable" connection (e.g. a Netty
|
||
connection) is <literal>60000</literal>ms, i.e. 1 minute. The default value for connection
|
||
ttl on a "reliable" connection (e.g. an in-vm connection) is <literal>-1</literal>. A
|
||
value of <literal>-1</literal> for <literal>ConnectionTTL</literal> means the server
|
||
will never time out the connection on the server side.</para>
|
||
<para id="connection-ttl.override">If you do not wish clients to be able to specify their own connection TTL, you can
|
||
override all values used by a global value set on the server side. This can be done by
|
||
specifying the <literal>connection-ttl-override</literal> attribute in the server side
|
||
configuration. The default value for <literal>connection-ttl-override</literal> is
|
||
<literal>-1</literal> which means "do not override" (i.e. let clients use their own
|
||
values).</para>
|
||
<section>
|
||
<title>Closing core sessions or JMS connections that you have failed to close</title>
|
||
<para>As previously discussed, it's important that all core client sessions and JMS
|
||
connections are always closed explicitly in a <literal>finally</literal> block when
|
||
you are finished using them. </para>
|
||
<para>If you fail to do so, HornetQ will detect this at garbage collection time, and log
|
||
a warning similar to the following in the logs (If you are using JMS the warning
|
||
will involve a JMS connection not a client session):</para>
|
||
<programlisting>
|
||
[Finalizer] 20:14:43,244 WARNING [org.apache.activemq.core.client.impl.DelegatingSession] I'm closing a ClientSession you left open. Please make sure you close all ClientSessions explicitly before let
|
||
ting them go out of scope!
|
||
[Finalizer] 20:14:43,244 WARNING [org.apache.activemq.core.client.impl.DelegatingSession] The session you didn't close was created here:
|
||
java.lang.Exception
|
||
at org.apache.activemq.core.client.impl.DelegatingSession.<init>(DelegatingSession.java:83)
|
||
at org.acme.yourproject.YourClass (YourClass.java:666)</programlisting>
|
||
<para>HornetQ will then close the connection / client session for you.</para>
|
||
<para>Note that the log will also tell you the exact line of your user code where you
|
||
created the JMS connection / client session that you later did not close. This will
|
||
enable you to pinpoint the error in your code and correct it appropriately.</para>
|
||
</section>
|
||
</section>
|
||
<section>
|
||
<title>Detecting failure from the client side.</title>
|
||
<para>In the previous section we discussed how the client sends pings to the server and how
|
||
"dead" connection resources are cleaned up by the server. There's also another reason
|
||
for pinging, and that's for the <emphasis>client</emphasis> to be able to detect that
|
||
the server or network has failed.</para>
|
||
<para>As long as the client is receiving data from the server it will consider the
|
||
connection to be still alive. </para>
|
||
<para>If the client does not receive any packets for <literal
|
||
>client-failure-check-period</literal> milliseconds then it will consider the
|
||
connection failed and will either initiate failover, or call any <literal
|
||
>FailureListener</literal> instances (or <literal>ExceptionListener</literal>
|
||
instances if you are using JMS) depending on how it has been configured.</para>
|
||
<para>If you're using JMS it's defined by the <literal>ClientFailureCheckPeriod</literal>
|
||
attribute on a <literal>HornetQConnectionFactory</literal> instance, or if you're
|
||
deploying JMS connection factory instances direct into JNDI on the server side, you can
|
||
specify it in the <literal>hornetq-jms.xml </literal> configuration file, using the
|
||
parameter <literal>client-failure-check-period</literal>.</para>
|
||
<para>The default value for client failure check period on an "unreliable" connection (e.g.
|
||
a Netty connection) is <literal>30000</literal>ms, i.e. 30 seconds. The default value
|
||
for client failure check period on a "reliable" connection (e.g. an in-vm connection)
|
||
is <literal>-1</literal>. A value of <literal>-1</literal> means the client will never fail the
|
||
connection on the client side if no data is received from the server. Typically this is
|
||
much lower than connection TTL to allow clients to reconnect in case of transitory
|
||
failure.</para>
|
||
</section>
|
||
<section id="connection-ttl.async-connection-execution">
|
||
<title>Configuring Asynchronous Connection Execution</title>
|
||
<para>Most packets received on the server side are executed on the remoting thread. These packets
|
||
represent short-running operations and are always executed on the remoting thread for
|
||
performance reasons.</para>
|
||
<para>However, by default some kinds of packets are executed using a thread 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:</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.RollbackMessage</literal></para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionCloseMessage</literal></para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionCommitMessage</literal></para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionXACommitMessage</literal></para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionXAPrepareMessage</literal></para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><literal>org.apache.activemq.core.protocol.core.impl.wireformat.SessionXARollbackMessage</literal></para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>To disable asynchronous connection execution, set the parameter
|
||
<literal>async-connection-execution-enabled</literal> in
|
||
<literal>hornetq-configuration.xml</literal> to <literal>false</literal> (default value is
|
||
<literal>true</literal>).</para>
|
||
</section>
|
||
</chapter>
|