← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/libjboss-remoting-java/oneiric

« back to all changes in this revision

Viewing changes to docs/guide/en/chap9.xml

  • Committer: Package Import Robot
  • Author(s): Torsten Werner
  • Date: 2011-09-09 14:01:03 UTC
  • mfrom: (1.1.6 upstream)
  • Revision ID: package-import@ubuntu.com-20110909140103-hqokx61534tas9rg
Tags: 2.5.3.SP1-1
http://bugs.debian.org/628303
* Newer but not newest upstream release. Do not build samples.
* Change debian/watch to upstream's svn repo.
* Add patch to fix compile error caused by tomcat update.
  (Closes: #628303)
* Switch to source format 3.0.
* Switch to debhelper level 7.
* Remove useless Depends.
* Update Standards-Version: 3.9.2.
* Update README.source.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/guide/en/chap9.xml
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<chapter id="chapter-connection-failure" xreflabel="Network Connection Monitoring">
 
3
  <title>Network Connection Monitoring</title>
 
4
  
 
5
  <para>Remoting has two mechanisms for monitoring the health of estabilished
 
6
  connections, which inform listeners on the client and server sides when a
 
7
  possible connection failure has been detected.</para>
 
8
  
 
9
  <section>
 
10
    <title>Client side monitoring</title>
 
11
 
 
12
    <para>On the client side, an
 
13
    <classname>org.jboss.remoting.ConnectionValidator</classname> periodically
 
14
    sends a PING message to the server and reports a failure if the response
 
15
    does not arrive within a specified timeout period. The PING is sent on one
 
16
    thread, and another thread determines if the response arrives in time.
 
17
    Separating these two activities allows Remoting to detect a failure
 
18
    regardless of the cause of the failure.</para>
 
19
    
 
20
    <para>The creation of the <classname>ConnectionValidator</classname> is the
 
21
    responsibility of the <classname>org.jboss.remoting.Client</classname>
 
22
    class. All the application code needs to do is to register an implementation
 
23
    of the <code>org.jboss.remoting.ConnectionListener</code> interface, which
 
24
    has only one method:</para>
 
25
  
 
26
    <programlisting>public void handleConnectionException(Throwable throwable, Client client);</programlisting>
 
27
  
 
28
    <para>What actions the <classname>ConnectionListener</classname> chooses to
 
29
    take are up to the application, but disconnecting the
 
30
    <classname>Client</classname> might be a reasonable strategy.</para>
 
31
    
 
32
    <para>The <classname>Client</classname> class has three methods for
 
33
    registering a <classname>ConnectionListener</classname>:</para>
 
34
    
 
35
    <programlisting>
 
36
       public void addConnectionListener(ConnectionListener listener);
 
37
       public void addConnectionListener(ConnectionListener listener, int pingPeriod);
 
38
       public void addConnectionListener(ConnectionListener listener, Map metadata);
 
39
    </programlisting>
 
40
 
 
41
    <para>The second method supports configuring the frequency of PING messages,
 
42
    and the third method supports more general configuration of the
 
43
    <classname>ConnectionValidator</classname>. Note that a given
 
44
    <classname>Client</classname> maintains a single
 
45
    <classname>ConnectionValidator</classname>, so the parameters in the
 
46
    metadata map are applied only on the first call to
 
47
    <methodname>Client.addConnectionListener()</methodname>. The following
 
48
    parameters are supported by <classname>ConnectionValidator</classname>,
 
49
    which is where the parameter names are defined:</para>
 
50
    
 
51
    <para><emphasis role="bold">VALIDATOR_PING_PERIOD</emphasis> (actual value
 
52
    "validatorPingPeriod") - specifies the time, in milliseconds, that elapses
 
53
    between the sending of PING messages to the server. The default value is
 
54
    2000.</para>
 
55
    
 
56
    <para><emphasis role="bold">VALIDATOR_PING_TIMEOUT</emphasis> (actual value
 
57
    "validatorPingTimeout") - specifies the time, in milliseconds, allowed for
 
58
    arrival of a response to a PING message. The default value is 1000.</para> 
 
59
    
 
60
    <para><emphasis role="bold">FAILURE_DISCONNECT_TIMEOUT</emphasis> (actual value
 
61
    "failureDisconnectTimeout") - if the parameter "stopLeaseOnFailure" 
 
62
    (see <xref linkend="section-interactions"/>) is set to
 
63
    "true", then "failureDisconnectTimeout" determines the disconnect timeout value
 
64
    to be used by <classname>org.jboss.remoting.LeasePinger</classname> in shutting
 
65
    down.  In particular, if "failureDisconnectTimeout" is set to "0", then 
 
66
    <classname>LeasePinger</classname> will avoid any network i/o.</para>
 
67
    
 
68
    <para> Normally, the values for these parameters are obtained either from
 
69
    the <classname>Client</classname>'s configuration map or the metadata map
 
70
    passed to <methodname>addConnectionListener()</methodname>, with values in
 
71
    the metadata map taking precedence. However, another relevant parameter is
 
72
    defined in <classname>org.jboss.remoting.Client</classname>:</para>
 
73
    
 
74
    <para><emphasis role="bold">USE_ALL_PARAMS</emphasis> (actual value
 
75
    "useAllParams") - this parameter is searched for in the
 
76
    <classname>InvokerLocator</classname>, in the configuration map passed to
 
77
    the <classname>Client</classname>, and in the metadata map (in that order).
 
78
    If the last occurrence found is set to "true", then parameter values are
 
79
    first obtained from the <classname>InvokerLocator</classname>, followed by
 
80
    the <classname>Client</classname>'s configuration map and the
 
81
    metadata map.</para>
 
82
    
 
83
    <para>Note that <classname>ConnectionValidator</classname> creates a
 
84
    client invoker to sends the PING messages, and it passes the metadata map to
 
85
    configure the client invoker.</para>
 
86
    
 
87
    <para><emphasis role="bold">NOTE.</emphasis> The default values of VALIDATOR_PING_PERIOD
 
88
    and VALIDATOR_PING_TIMEOUT have often been found in practice to be too small, increasing
 
89
    the likelihood of spurious connection failures.</para>
 
90
    
 
91
    <para><emphasis role="bold">NOTE.</emphasis> It is important to set VALIDATOR_PING_PERIOD
 
92
    to a value greater than the value of VALIDATOR_PING_TIMEOUT.  Doing so gives the
 
93
    <classname>ConnectionValidator</classname> a chance to notify all
 
94
    <classname>ConnectionListener</classname>s, which might result in shutting down the
 
95
    connection, before the next PING is sent.</para>
 
96
    
 
97
    <para>For more configuration parameters, see <xref
 
98
    linkend="section-interactions"/>.</para>
 
99
    
 
100
  </section>
 
101
 
 
102
  <section id="section-server-side" xreflabel="Server side monitoring">
 
103
    <title>Server side monitoring</title>
 
104
  
 
105
    <para>A remoting server also has the capability to detect when a client is
 
106
    no longer available. This is done by estabilishing a lease with the remoting
 
107
    clients that connect to a server. On the client side, an
 
108
    <classname>org.jboss.remoting.LeasePinger</classname> periodically sends
 
109
    PING messages to the server, and on the server side an
 
110
    <classname>org.jboss.remoting.Lease</classname> informs registered listeners
 
111
    if the PING doesn't arrive withing the specified timeout period.</para>
 
112
  
 
113
    <para><emphasis role="bold">Server side activation.</emphasis> To turn on
 
114
    server side connection failure detection of remoting clients, it is
 
115
    necessary to satisfy two criteria. The first is that the client lease period
 
116
    is set and is a value greater than 0. The value is represented in
 
117
    milliseconds. The client lease period can be set by either the
 
118
    'clientLeasePeriod' attribute within the Connector configuration or by
 
119
    calling the <classname>Connector</classname> method</para>
 
120
    
 
121
    <programlisting>public void setLeasePeriod(long leasePeriodValue);</programlisting>
 
122
    
 
123
    <para>The second
 
124
    criterion is that an implementation of the
 
125
    <code>org.jboss.remoting.ConnectionListener</code> interface is added as a
 
126
    connection listener to the Connector, either via the method</para>
 
127
    
 
128
    <programlisting>public void addConnectionListener(ConnectionListener listener)</programlisting>
 
129
    
 
130
    <para>or through the use of the
 
131
    <code>ServerInvoker.CONNECTION_LISTENER</code> parameter (actual value
 
132
    "connectionListener") in the <classname>Connector</classname>'s
 
133
    configuration map, XML configuration file, or
 
134
    <classname>ServerConfiguration</classname> POJO. If the
 
135
    <code>ServerInvoker.CONNECTION_LISTENER</code> parameter is used, the value
 
136
    can be either a JMX object name or the fully qualified name of a class that
 
137
    implements <classname>ConnectionListener</classname> and has a default
 
138
    constructor. Once both criteria are met, the remoting server will turn on
 
139
    client leasing.</para>
 
140
    
 
141
    <para>The ConnectionListener will be notified of both client failures and
 
142
    client disconnects via the handleConnectionException() method. If the client
 
143
    failed, meaning its lease was not renewed within configured time period, the
 
144
    first parameter to the handleConnectionException() method will be null. If
 
145
    the client disconnected in a regular manner, the first parameter to the
 
146
    handleConnectionException() method will be of type
 
147
    ClientDisconnectedException (which indicates a normal termination). Note,
 
148
    the client's lease will be renewed on the server with any and every
 
149
    invocation made on the server from the client, whether it be a normal
 
150
    invocation or a ping from the client internally.</para>
 
151
  
 
152
    <para>The actual lease window established on the server side is dynamic
 
153
    based the rate at which the client updates its lease. In particular, the
 
154
    lease window will always be set to lease period * 2 for any lease that does
 
155
    not have a lease update duration that is longer than 75% of the lease window
 
156
    (meaning if set lease period to 10 seconds and always update that lease in
 
157
    less then 7.5 seconds, the lease period will always remain 10 seconds). If
 
158
    the update duration is greater than 75% of the lease window, the lease
 
159
    window will be reset to the lease duration X 2 (meaning if set lease period
 
160
    to 10 seconds and update that lease in 8 seconds, the new lease window will
 
161
    be set to 16 seconds). Also, the lease will not immediately expire on the
 
162
    first lease timeout (meaning did not get an update within the lease window).
 
163
    It takes two consecutive timeouts before a lease will expire and a
 
164
    notification for client connection failure is fired. This essentially means
 
165
    that the time it will take before a connection listener is notified of a
 
166
    client connection failure will be at least 4 X lease period (no
 
167
    exceptions).</para>
 
168
  
 
169
    <para><emphasis role="bold">Client side activation.</emphasis> By default,
 
170
    the client is not configured to do client leasing. To allow a client to do
 
171
    leasing, either set the parameter "leasing" to "true" in the
 
172
    <classname>InvokerLocator</classname> or set the parameter
 
173
    <code>Client.ENABLE_LEASE</code> (actual value "enableLease") to true in the
 
174
    <classname>InvokerLocator</classname> or in the
 
175
    <classname>Client</classname> configuration map. [The use of
 
176
    <code>Client.ENABLE_LEASE</code> is recommended.] This does not mean that
 
177
    client will lease for sure, but will indicate the client should call on the
 
178
    server to see if the server has activated leasing and get the leasing period
 
179
    suggested by the server. It is possible to override the suggested lease
 
180
    period by setting the parameter
 
181
    <code>org.jboss.remoting.InvokerLocator.CLIENT_LEASE_PERIOD</code> (actual
 
182
    value "lease_period") to a value greater than 0 and less than the value
 
183
    suggested by the server. <emphasis role="bold">Note. </emphasis>If the
 
184
    client and server are local, meaning running within the JVM, leasing (and
 
185
    thus connection notification) will not be activated, even if is configured
 
186
    to do so.</para>
 
187
  
 
188
    <para>If leasing is turned on within the client side, there is no API or
 
189
    configuration changes needed, unless want to override as mentioned
 
190
    previously. When the client initially connects to the server, it will check
 
191
    to see if client leasing is turned on by the server. If it is, it will
 
192
    internally start pinging periodically to the server to maintain the lease.
 
193
    When the client disconnects, it will internally send message to the server
 
194
    to stop monitoring lease for this client. Therefore, it is <emphasis
 
195
    role="bold">IMPORTANT</emphasis> that disconnect is called on the client
 
196
    when done using it. Otherwise, the client will continue to make its ping
 
197
    call on the server to keep its lease current.</para>
 
198
  
 
199
    <para>The client can also provide extra metadata that will be communicated to
 
200
    the connection listener in case of failure by supplying a metadata Map to
 
201
    the Client constructor. This map will be included in the Client instance
 
202
    passed to the connection listener (via the handleConnectionException()
 
203
    method) via the Client's getConfiguration() method.</para>
 
204
  
 
205
    <para>From the server side, there are two ways in which to disable leasing
 
206
    (i.e. turn leasing off). The first is to call:</para>
 
207
  
 
208
    <programlisting>public void removeConnectionListener(ConnectionListener listener)</programlisting>
 
209
  
 
210
    <para>and remove all the registered ConnectionListeners. Once the last one
 
211
    has been removed, leasing will be disabled and all the current leasing
 
212
    sessions will be terminated. The other way is to call:</para>
 
213
  
 
214
    <programlisting>public void setLeasePeriod(long leasePeriodValue)</programlisting>
 
215
  
 
216
    <para>and pass a value less than zero. This will disable leasing, preventing
 
217
    any new leases to be established but will allow current leasing sessions to
 
218
    continue.</para>
 
219
  
 
220
    <para>The following parameter is relevant to leasing configuration on the server side:</para>
 
221
    
 
222
    <para><emphasis
 
223
    role="bold"><code>org.jboss.remoting.ServerInvoker.CLIENT_LEASE_PERIOD</code></emphasis>
 
224
    (actual value "clientLeasePeriod") - specifies the timeout period used by
 
225
    the server to determine if a PING is late. The default value is "5000",
 
226
    which indicates that leasing will be activated if an
 
227
    <classname>org.jboss.remoting.ConnectionListener</classname> is registered
 
228
    with the server. This is also the suggested lease period returned by the
 
229
    server when the client inquires if leasing is activated.</para>
 
230
    
 
231
    <para>The following parameters are relevant to leasing configuration on the client side:</para>
 
232
        
 
233
    <para><emphasis
 
234
    role="bold"><code>org.jboss.remoting.Client.ENABLE_LEASE</code></emphasis>
 
235
    (actual value "enableLease") - if set to "true", will lead
 
236
    <classname>org.jboss.remoting.Client</classname> to attempt to set up a
 
237
    lease with the server, if leasing is activated on the server.</para>
 
238
    
 
239
    <para><emphasis
 
240
    role="bold"><code>org.jboss.remoting.InvokerLocator.CLIENT_LEASE</code></emphasis>
 
241
    (actual value "leasing") - if set to "true" in the
 
242
    <classname>InvokerLocator</classname>, will lead
 
243
    <classname>org.jboss.remoting.Client</classname> to attempt to set up a
 
244
    lease with the server, if leasing is activated on the server. It is
 
245
    suggested that this parameter be avoided, in favor of
 
246
    <code>Client.ENABLE_LEASE</code>.</para>
 
247
    
 
248
    <para><emphasis
 
249
    role="bold"><code>org.jboss.remoting.InvokerLocator.CLIENT_LEASE_PERIOD</code></emphasis>
 
250
    (actual value "lease_period") - if set to a value greater than 0 and less
 
251
    than the suggested lease period returned by the server, will be used to
 
252
    determine the time between PING messages sent by
 
253
    <classname>LeasePinger</classname>.</para>
 
254
    
 
255
    <para><emphasis
 
256
    role="bold"><code>org.jboss.remoting.LeasePinger.LEASE_PINGER_TIMEOUT</code></emphasis>
 
257
    (actual value "leasePingerTimeout") - specifies the per invocation timeout
 
258
    value use by <classname>LeasePinger</classname> when it sends PING messages.
 
259
    In the absence of a configured value, the timeout value used by the
 
260
    <classname>Client</classname> that created the
 
261
    <classname>LeasePinger</classname> will be used.</para>
 
262
    
 
263
    <para>For examples of how to use server side connection listeners, reference
 
264
    org.jboss.test.remoting.lease.LeaseTestServer and
 
265
    org.jboss.test.remoting.lease.LeaseTestClient.</para>
 
266
  
 
267
  </section>
 
268
  
 
269
  <section id="section-interactions" xreflabel="Interactions between client side and server side connection monitoring">
 
270
  
 
271
    <title>Interactions between client side and server side connection monitoring</title>
 
272
    
 
273
    <para>As of Remoting version 2.4, the client side and server side connection
 
274
    monitoring mechanisms can be, and by default are, more closely related, in
 
275
    two ways.</para>
 
276
    
 
277
    <orderedlist>
 
278
       <listitem> If the parameter
 
279
       <code>org.jboss.remoting.ConnectionValidator.TIE_TO_LEASE</code> (actual
 
280
       value "tieToLease") is set to true, then, when the server receives a PING
 
281
       message from an
 
282
       <classname>org.jboss.remoting.ConnectionValidator</classname>, it will
 
283
       return a boolean value that indicates whether a lease currently exists
 
284
       for the connection being monitored. If leasing is activated on the client
 
285
       and server side, then a value of "false" indicates that the lease has
 
286
       failed, and the <classname>ConnectionValidator</classname> will treat a
 
287
       returned value of "false" the same as a timeout; that is, it will notifiy
 
288
       listeners of a connection failure. The default value of this parameter is
 
289
       "true". <emphasis role="bold">Note. </emphasis>If leasing is not
 
290
       activated on the client side, then this parameter has no
 
291
       effect.</listitem>
 
292
       
 
293
       <listitem><para>If the parameter
 
294
       <code>org.jboss.remoting.ConnectionValidator.STOP_LEASE_ON_FAILURE</code>
 
295
       (actual value "stopLeaseOnFailure") is set to true, then, upon detecting
 
296
       a connection failure, <classname>ConnectionValidator</classname> will
 
297
       stop the <classname>LeasePinger</classname>, if any, pinging a lease on
 
298
       the same connection. The default value is "true".</para> </listitem>
 
299
       
 
300
    </orderedlist>
 
301
    
 
302
    <para><emphasis role="bold">Note.</emphasis> As of release 2.5.2, an important
 
303
    concept related to connection monitoring, <emphasis>connection identity</emphasis>,
 
304
        is available.  Suppose that leasing is enabled and that a client invoker
 
305
        stops and is replaced by a new client invoker.  If the 
 
306
        replacement occurs quickly, the server side <classname>Lease</classname> may never 
 
307
        miss a ping, in which there is no evidence that anything changed on the client side.
 
308
        That is, the connection is still alive, as far as the server is concerned. That
 
309
        semantics might be perfectly acceptable for some applications, but other 
 
310
        applications might interpret the same events as a connection failure followed by
 
311
        a new connection.  Remoting can be configured to treat a connection as being 
 
312
        defined by a client/server pair, which supports the second category of applications.
 
313
        </para>
 
314
        
 
315
    <para>More specifically, when configured to do so by setting the parameter
 
316
    <code>org.jboss.remoting.Remoting.USE_CLIENT_CONNECTION_IDENTITY</code> (actual value
 
317
    "useClientConnectionIdentity") to "true", Remoting identifies a connection with a
 
318
    <classname>LeasePinger</classname>/<classname>Lease</classname> pair.  A
 
319
    <classname>Client</classname> participates in a connection when it is connected
 
320
    by way of the new method</para>
 
321
    
 
322
    <programlisting>public void connect(ConnectionListener listener, Map metadata) throws Exception;</programlisting>
 
323
    
 
324
    <para>This method serves to connect the <classname>Client</classname> to the server
 
325
    by way of a new or existing client invoker, and it also (1) registers the 
 
326
    <classname>ConnectionListener</classname> with the <classname>Client</classname>'s
 
327
    new or exiting <classname>ConnectionValidator</classname> and (2) registers
 
328
    the <classname>ConnectionValidator</classname> with the client invoker's 
 
329
    <classname>LeasePinger</classname>.  Subsequently, if any
 
330
    <classname>ConnectionValidator</classname> registered with that
 
331
    <classname>LeasePinger</classname> detects a connection failure, it will
 
332
    (if "stopLeaseOnFailure" is "true") stop the <classname>LeasePinger</classname>,
 
333
    and the <classname>LeasePinger</classname> will cause each registered
 
334
    <classname>ConnectionValidator</classname>s to notify each of its
 
335
    registered <classname>ConnectionListener</classname>s of the connection failure.
 
336
    Once the <classname>LeasePinger</classname> has been shut down and all of the
 
337
    notifications have been made, the connection anchored by the 
 
338
    <classname>LeasePinger</classname> is defunct, and the 
 
339
        associated <classname>Client</classname>'s should be disconnected by a call
 
340
        to <methodname>Client.disconnect()</methodname>.  If such a <classname>Client</classname>
 
341
        is reconnected by a call to <methodname>Client.connect()</methodname>, it
 
342
        will be associated with a new <classname>LeasePinger</classname> and, therefore,
 
343
        a new connection.</para>
 
344
        
 
345
    <para><emphasis role="bold">TIE_TO_LEASE</emphasis> (actual value
 
346
    "tieToLease") - specifies whether <classname>ConnectionValidator</classname>
 
347
    should treat the failure of a related lease on the server side as a
 
348
    connection failure. The default value is "true".</para>
 
349
    
 
350
    <para><emphasis role="bold">STOP_LEASE_ON_FAILURE</emphasis> (actual value
 
351
    "stopLeaseOnFailure") - specifies whether, when a
 
352
    <classname>ConnectionValidator</classname> detects a connection failure, it
 
353
    should stop the associated
 
354
    <classname>org.jboss.remoting.LeasePinger</classname>, if any. The default
 
355
    value is "true".</para>
 
356
    
 
357
    <para><emphasis role="bold">org.jboss.remoting.Remoting.USE_CLIENT_CONNECTION_IDENTITY</emphasis>
 
358
    (actual value "useClientConnectionIdentity") - tells Remoting to adhere to the
 
359
    new "connection identity" semantics.</para>
 
360
  </section>
 
361
</chapter>
 
 
b'\\ No newline at end of file'