Author: seb
Date: Mon Jan 15 17:02:57 2007
New Revision: 1218
Modified:
logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
Log:
on going work on the JMS*Appender doc
Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
==============================================================================
--- logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
(original)
+++ logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
Mon Jan 15 17:02:57 2007
@@ -1463,6 +1463,370 @@
tunnels the events it receives from its clients to a
second server.
</p>
+ <a name="JMSAppenderBase" />
+ <h3>JMSAppenderBase</h3>
+
+ <p>
+ The <a
href="../xref/ch/qos/logback/core/net/JMSAppenderBase.html">
+ <code>JMSAppenderBase</code></a> subclasses conceptually
accomplishes
+ the same task as the <code>SocketAppender</code> but as the
name
+ suggests it is based on the JMS API instead of TCP sockets.
+ JMS or the Java Message Service API
+ provides an abstraction for Message-Oriented Middleware (MOM)
products.
+ One of the key architectural concepts in JMS is the decoupling
of message
+ producers and message consumers. Senders do not have to wait
for receivers
+ to handle messages and conversely the receiver consumes
messages as they
+ become available; messages are said to be delivered
asynchronously. Just as
+ importantly, consumers as well as producers can be added or
removed at will
+ to a JMS channel. The set of the message producers and message
consumers can
+ vary independently and transparently over time, with both sets
oblivious
+ to each other.
+ </p>
+
+ <p>
+ The JMS specification provides for two types of
messaging models,
+ publish-and-subscribe and point-to-point queuing.
Logback supports the former
+ model with <code>JMSTopicAppender</code> and the latter
with <code>JMSQueueAppender</code>
+ Both appenders extend the <code>JMSAppenderBase</code>
class and
+ publish serialized events to a topic or queue specified
by the user.
+ One or more <code>JMSTopicSink</code> or
<code>JMSQueueSink</code> applications
+ can consume these serialized events.
+ </p>
+
+ <p>
+ The consumer of JMS appenders generated events need not
be only <code>JMSTopicSink</code>
+ or <code>JMSQueueSink</code> applications. Any
application or MessageDrivenBean
+ capable of subscribing to the appropriate topic or
queue and consuming serialized
+ logging event messages would be suitable.
+ Additional consumers could be quickly built based on
the <code>JMSTopicSink</code> or
+ <code>JMSQueueSink</code> model.
+ </p>
+
+ <p>
+ Here are <code>JMSAppenderBase</code>'s options:
+ </p>
+
+ <table>
+ <tr>
+ <th>Option Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><b><span
class="option">InitialContextFactoryName</span></b></td>
+ <td><code>String</code></td>
+ <td>
+ <p>
+ The class name of the initial JNDI
context factory. There is no need
+ to set this option if you have a
properly configured <em>jndi.properties</em>
+ file or if <code>JMSAppenderBase</code>
subclass is running
+ within an application server.
+ </p>
+ <p>
+ If you set this option, you should
+ also set the <span
class="option">ProviderURL</span> option.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td><b><span class="option">ProviderURL</span></b></td>
+ <td><code>String</code></td>
+ <td>
+ <p>
+ This option specifies configuration
information for the
+ JNDI service provider. The value of the
property should contain a
+ URL string (e.g.
<em>ldap://somehost:389</em>).
+ </p>
+ <p>
+ The <span
class="option">ProviderURL</span> option is taken into
+ account only if the <span
class="option">InitialContextFactoryName</span>
+ option is specified. It is ignored
otherwise.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td><b><span
class="option">URLPkgPrefixes</span></b></td>
+ <td><code>String</code></td>
+ <td>
+ <p>
+ This option contains the list
of package prefixes to
+ use when loading in URL context
factories. The value of the
+ property should be a
colon-separated list of package
+ prefixes for the class name of
the URL context factory class.
+ </p>
+ <p>
+ For JBoss the value of this
option should be:
+
org.jboss.naming:org.jnp.interfaces
+ This option is not needed under
Weblogic.
+ </p>
+ <p>
+ This option is taken into
account only if the
+ <span
class="option">InitialContextFactoryName</span>
+ option is specified. It is
ignored otherwise.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td><b><span
class="option">SecurityPrincipalName</span></b></td>
+ <td><code>String</code></td>
+ <td>
+ <p>
+ The security principal name to
use when accessing the JNDI namespace.
+ This option is usually not
required.
+ </p>
+ <p>
+ This option is taken into
account only if the
+ <span
class="option">InitialContextFactoryName</span>
+ option is specified. It is
ignored otherwise.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <b>
+ <span
class="option">SecurityCredentials</span>
+ </b>
+ </td>
+ <td>
+ <code>String</code>
+ </td>
+ <td>
+ <p>
+ The security credentials to use when
accessing the
+ JNDI namespace. This option is usually
not required.
+ </p>
+ <p>
+ This option is taken into account only
if the
+ <span class="option">
+ InitialContextFactoryName
+ </span>
+ option is specified. It is ignored
otherwise.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <b>
+ <span class="option">UserName</span>
+ </b>
+ </td>
+ <td>
+ <code>String</code>
+ </td>
+ <td>
+ <p>
+ The username to use when creating a
topic or queue connection.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <b>
+ <span class="option">Password</span>
+ </b>
+ </td>
+ <td>
+ <code>String</code>
+ </td>
+ <td>
+ <p>
+ The password to use when creating a
topic or queue connection.
+ </p>
+ </td>
+ </tr>
+ </table>
+
+ <p>
+ JMS topics, queues and connection factories are
administered objects that are obtained
+ using the JNDI API. This in turn implies the necessity
of retrieving a JNDI Context.
+ There are two common methods for obtaining a JNDI
Context. If a file resource named
+ <em>jndi.properties</em> is available to the JNDI API,
it will use the information
+ found therein to retrieve an initial JNDI context.
+ To obtain an initial context, one simply calls:
+ </p>
+
+<div class="source"><pre>InitialContext jndiContext = new
InitialContext();</pre></div>
+
+ <p>
+ Calling the no-argument <code>InitialContext()</code>
constructor will also work
+ from within Enterprise Java Beans (EJBs).
+ Indeed, it is part of the EJB contract for application
servers to provide
+ each enterprise bean an environment naming context
(ENC).
+ </p>
+
+ <p>
+ In the second approach, several predetermined
properties are specified.
+ These properties are passed to the
<code>InitialContext</code> constructor
+ to connect to the naming service provider.
+ For example, to connect to an
+ <a
href="http://www.activemq.org/site/home.html";><code>ActiveMQ</code></a>
+ naming server one would write:
+ </p>
+
+<div class="source"><pre>Properties env = new Properties();
+env.put(Context.INITIAL_CONTEXT_FACTORY,
"org.apache.activemq.jndi.ActiveMQInitialContextFactory");
+env.put(Context.PROVIDER_URL, "tcp://<em>hostname</em>:61616");
+Context ctx = new InitialContext(env);</pre></div>
+
+ <p>
+ where <em>hostname</em> is the host where the ActiveMQ
server is running.
+ </p>
+
+ <p>
+ Other JNDI providers will obviously require different
values.
+ As mentioned previously, the initial JNDI context can
be obtained by calling
+ the no-argument <code>InitialContext()</code>
constructor from within EJBs.
+ Only clients running in a separate JVM need to be
concerned about
+ the <em>jndi.properties</em> file or setting the
different properties
+ before calling <code>InitialContext</code> constructor
taking a
+ Properties (i.e. Hashtable) parameter.
+ </p>
+
+ <a name="JMSTopicAppender" />
+ <h3>JMSTopicAppender</h3>
+
+ <p>
+ The <a
href="../xref/ch/qos/logback/classic/net/JMSTopicAppender.html">
+ <code>JMSTopicAppender</code></a> acts as a message
producer to a publish and subscribe
+ Topic.
+ </p>
+
+ <p>
+ Its most important method, <code>doAppend()</code> is
listed below:
+ </p>
+
+<div class="source"><pre>public void append(LoggingEvent event) {
+ if (!isStarted()) {
+ return;
+ }
+
+ try {
+ ObjectMessage msg = topicSession.createObjectMessage();
+
+ msg.setObject(event);
+ topicPublisher.publish(msg);
+ successiveFailureCount = 0;
+ } catch (Exception e) {
+ successiveFailureCount++;
+ if (successiveFailureCount > SUCCESSIVE_FAILURE_LIMIT) {
+ stop();
+ }
+ addError("Could not publish message in JMSTopicAppender [" + name +
"].", e);
+ }
+}</pre></div>
+
+ <p>
+ The <code>isStarted()</code> method allows the appender
to check whether
+ prerequisite conditions for its proper functioning, in
particular the
+ availability of a valid and open
<code>TopicConnection</code> and a
+ <code>TopicSession</code>, are fulfilled. If that is
not the case,
+ the append method returns without performing any work.
+ If the prerequisite conditions are fulfilled, then the
method
+ proceeds to publish the logging event. This is done by
obtaining a
+ <code>javax.jms.ObjectMessage</code> from the
<code>TopicSession</code>
+ and then setting its payload to the logging event
received as
+ the input parameter. Once the payload of the message is
set, it is
+ published. The fact that <code>LoggingEvent</code> is
serializable
+ has its importance, as only Serializable objects can be
+ transported within an <code>ObjectMessage</code>.
+ </p>
+
+ <p>
+ In summary, the <code>JMSTopicAppender</code>
broadcasts messages consisting
+ of a serialized <code>LoggingEvent</code> payload over
a user-specified
+ JMS topic. These events can be processed by a
+ <a
href="../xref/ch/qos/logback/classic/net/JMSTopicSink.html">
+ <code>JMSTopicSink</code></a>
+ or a similar consumer. According to JMS specification,
the provider
+ will asynchronously call the <code>onMessage()</code>
of duly registered
+ and subscribed <code>javax.jms.MessageListener</code>
objects.
+ The <code>onMessage()</code> method in
<code>JMSTopicSink</code>
+ is implemented as follows:
+ </p>
+
+<div class="source"><pre>public void onMessage(javax.jms.Message message) {
+ LoggingEvent event;
+ try {
+ if (message instanceof ObjectMessage) {
+ ObjectMessage objectMessage = (ObjectMessage) message;
+ event = (LoggingEvent) objectMessage.getObject();
+ Logger log = (Logger)
LoggerFactory.getLogger(event.getLoggerRemoteView().getName());
+ log.callAppenders(event);
+ } else {
+ logger.warn("Received message is of type " + message.getJMSType()
+ + ", was expecting ObjectMessage.");
+ }
+ } catch (JMSException jmse) {
+ logger.error("Exception thrown while processing incoming message.", jmse);
+ }
+}</pre></div>
+
+ <p>
+ The <code>onMessage()</code> method begins by
retrieving the logging event's payload.
+ It then obtains a Logger with the same name as the
logger name of the incoming event.
+ The event is then logged through this logger as if it
were generated locally,
+ by calling its <code>callAppenders()</code> method. The
<code>SocketNode</code> class used by
+ <code>SimpleSocketServer</code> handles incoming
logging events essentially in the same way.
+ </p>
+
+ <p>
+ Some options are proper to
<code>JMSTopicAppender</code>. They are
+ listed below.
+ </p>
+
+ <table>
+ <tr>
+ <th>Option Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><b><span
class="option">TopicConnectionFactoryBindingName</span></b></td>
+ <td><code>String</code></td>
+ <td>
+ <p>
+ The name of the topic factory. There is
no default value for this mandatory option.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td><b><span
class="option">TopicBindingName</span></b></td>
+ <td><code>String</code></td>
+ <td>
+ <p>
+ The name of the topic to use. There is
no default value for this mandatory option.
+ </p>
+ </td>
+ </tr>
+ </table>
+
+
+ <a name="JMSQueueAppender" />
+ <h3>JMSQueueAppender</h3>
+
+ <p>
+ The <a
href="../xref/ch/qos/logback/classic/net/JMSQueueAppender.html">
+ <code>JMSQueueAppender</code></a> acts as a message
producer to a point-to-point
+ Queue.
+ </p>
+
+ <p>
+ It is working in a very similar manner to the
<code>JMSTopicAppender</code>.
+ </p>
+
+ queue's own options
+
+ jms comments
+
+ diff topic/queue: client goes off and back online
+
+
+
+
+
+
+
+
<a name="SMTPAppender"/>
<h3>SMTPAppender</h3>
_______________________________________________
logback-dev mailing list
[email protected]
http://qos.ch/mailman/listinfo/logback-dev
