## org.apache.log4j.net
Class JMSAppender

    java.lang.Object
      org.apache.log4j.AppenderSkeleton
          org.apache.log4j.net.JMSAppender

All Implemented Interfaces:
  Appender, OptionHandler

    public class JMSAppender

extends AppenderSkeleton

A simple appender that publishes events to a JMS Topic. The events are serialized and transmitted as JMS message type `ObjectMessage`.

JMS `topics` and `topic connection factories` are administered objects that are retrieved using JNDI messaging which in turn requires the retreival of a JNDI `Context`.

There are two common methods for retrieving a JNDI `Context`. If a file resource named jndi.properties is available to the JNDI API, it will use the information found therein to retrieve an initial JNDI context. To obtain an initial context, your code will simply call:

       InitialContext jndiContext = new InitialContext();

Calling the no-argument `InitialContext()` method will also work from within Enterprise Java Beans (EJBs) because it is part of the EJB contract for application servers to provide each bean an environment naming context (ENC).

In the second approach, several predetermined properties are set and these properties are passed to the `InitialContext` contructor to connect to the naming service provider. For example, to connect to JBoss naming service one would write:

       Properties env = new Properties( );
       env.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory");
       env.put(Context.PROVIDER_URL, "jnp://hostname:1099");
       env.put(Context.URL_PKG_PREFIXES, "org.jboss.naming:org.jnp.interfaces");
       InitialContext jndiContext = new InitialContext(env);

where hostname is the host where the JBoss applicaiton server is running.

To connect to the the naming service of Weblogic application server one would write:

       Properties env = new Properties( );
       env.put(Context.INITIAL_CONTEXT_FACTORY, "weblogic.jndi.WLInitialContextFactory");
       env.put(Context.PROVIDER_URL, "t3://localhost:7001");
       InitialContext jndiContext = new InitialContext(env);

Other JMS providers will obviously require different values. The initial JNDI context can be obtained by calling the no-argument `InitialContext()` method in EJBs. Only clients running in a separate JVM need to be concerned about the jndi.properties file and calling `InitialContext.InitialContext()` or alternatively correctly setting the different properties before calling `InitialContext.InitialContext(java.util.Hashtable)` method.

Author:
  Ceki Gülcü

Field Summary

Fields inherited from class org.apache.log4j.AppenderSkeleton
`closed, errorHandler, headFilter, layout, name, tailFilter, threshold`

Constructor Summary
`JMSAppender()`

Method Summary
`void` `activateOptions()` Options are activated and become effective only after calling this method.
`void` `append(LoggingEvent event)` This method called by `AppenderSkeleton.doAppend(org.apache.log4j.spi.LoggingEvent)` method to do most of the real appending work.
`protected boolean` `checkEntryConditions()`
`void` `close()` Close this JMSAppender.
`java.lang.String` `getInitialContextFactoryName()` Returns the value of the InitialContextFactoryName option.
`boolean` `getLocationInfo()` Returns value of the LocationInfo property which determines whether location (stack) info is sent to the remote subscriber.
`java.lang.String` `getPassword()`
`java.lang.String` `getProviderURL()`
`java.lang.String` `getSecurityCredentials()`
`java.lang.String` `getSecurityPrincipalName()`
`java.lang.String` `getTopicBindingName()` Returns the value of the TopicBindingName option.
`protected javax.jms.TopicConnection` `getTopicConnection()` Returns the TopicConnection used for this appender.
`java.lang.String` `getTopicConnectionFactoryBindingName()` Returns the value of the TopicConnectionFactoryBindingName option.
`protected javax.jms.TopicPublisher` `getTopicPublisher()` Returns the TopicPublisher used for this appender.
`protected javax.jms.TopicSession` `getTopicSession()` Returns the TopicSession used for this appender.
`java.lang.String` `getUserName()`
`protected java.lang.Object` `lookup(javax.naming.Context ctx, java.lang.String name)`
`boolean` `requiresLayout()` The JMSAppender sends serialized events and consequently does not require a layout.
`void` `setInitialContextFactoryName(java.lang.String initialContextFactoryName)` Setting the InitialContextFactoryName method will cause this `JMSAppender` instance to use the `InitialContext.InitialContext(Hashtable)` method instead of the no-argument constructor.
`void` `setLocationInfo(boolean locationInfo)` If true, the information sent to the remote subscriber will include caller's location information.
`void` `setPassword(java.lang.String password)` The paswword to use when creating a topic session.
`void` `setProviderURL(java.lang.String providerURL)`
`void` `setSecurityCredentials(java.lang.String securityCredentials)`
`void` `setSecurityPrincipalName(java.lang.String securityPrincipalName)`
`void` `setTopicBindingName(java.lang.String topicBindingName)` The TopicBindingName option takes a string value.
`void` `setTopicConnectionFactoryBindingName(java.lang.String tcfBindingName)` The TopicConnectionFactoryBindingName option takes a string value.
`void` `setURLPkgPrefixes(java.lang.String urlPkgPrefixes)`
`void` `setUserName(java.lang.String userName)` The user name to use when `creating a topic session`.

Methods inherited from class org.apache.log4j.AppenderSkeleton
`addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isAsSevereAsThreshold, setErrorHandler, setLayout, setName, setThreshold`

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### JMSAppender

    public JMSAppender()

Method Detail

### setTopicConnectionFactoryBindingName

    public void setTopicConnectionFactoryBindingName(java.lang.String tcfBindingName)

  The TopicConnectionFactoryBindingName option takes a string value. Its value will be used to lookup the appropriate `TopicConnectionFactory` from the JNDI context.

### getTopicConnectionFactoryBindingName

    public java.lang.String getTopicConnectionFactoryBindingName()

  Returns the value of the TopicConnectionFactoryBindingName option.

### setTopicBindingName

    public void setTopicBindingName(java.lang.String topicBindingName)

  The TopicBindingName option takes a string value. Its value will be used to lookup the appropriate `Topic` from the JNDI context.

### getTopicBindingName

    public java.lang.String getTopicBindingName()

  Returns the value of the TopicBindingName option.

### getLocationInfo

    public boolean getLocationInfo()

  Returns value of the LocationInfo property which determines whether location (stack) info is sent to the remote subscriber.

### activateOptions

    public void activateOptions()

  Options are activated and become effective only after calling this method.

  Specified by:
    `activateOptions` in interface `OptionHandler`
  Overrides:
    `activateOptions` in class `AppenderSkeleton`

### lookup

    protected java.lang.Object lookup(javax.naming.Context ctx,
                                      java.lang.String name)
                               throws javax.naming.NamingException

  Throws:
    `javax.naming.NamingException`

### checkEntryConditions

    protected boolean checkEntryConditions()

### close

    public void close()

  Close this JMSAppender. Closing releases all resources used by the appender. A closed appender cannot be re-opened.

### append

    public void append(LoggingEvent event)

  This method called by `AppenderSkeleton.doAppend(org.apache.log4j.spi.LoggingEvent)` method to do most of the real appending work.

  Specified by:
    `append` in class `AppenderSkeleton`

### getInitialContextFactoryName

    public java.lang.String getInitialContextFactoryName()

  Returns the value of the InitialContextFactoryName option. See `setInitialContextFactoryName(java.lang.String)` for more details on the meaning of this option.

### setInitialContextFactoryName

    public void setInitialContextFactoryName(java.lang.String initialContextFactoryName)

  Setting the InitialContextFactoryName method will cause this `JMSAppender` instance to use the `InitialContext.InitialContext(Hashtable)` method instead of the no-argument constructor. If you set this option, you should also at least set the ProviderURL option.

  See also `setProviderURL(String)`.

### getProviderURL

    public java.lang.String getProviderURL()

### setProviderURL

    public void setProviderURL(java.lang.String providerURL)

### setURLPkgPrefixes

    public void setURLPkgPrefixes(java.lang.String urlPkgPrefixes)

### getSecurityCredentials

    public java.lang.String getSecurityCredentials()

### setSecurityCredentials

    public void setSecurityCredentials(java.lang.String securityCredentials)

### getSecurityPrincipalName

    public java.lang.String getSecurityPrincipalName()

### setSecurityPrincipalName

    public void setSecurityPrincipalName(java.lang.String securityPrincipalName)

### getUserName

    public java.lang.String getUserName()

### setUserName

    public void setUserName(java.lang.String userName)

  The user name to use when `creating a topic session`. If you set this option, you should also set the Password option. See `setPassword(String)`.

### getPassword

    public java.lang.String getPassword()

### setPassword

    public void setPassword(java.lang.String password)

  The paswword to use when creating a topic session.

### setLocationInfo

    public void setLocationInfo(boolean locationInfo)

  If true, the information sent to the remote subscriber will include caller's location information. By default no location information is sent to the subscriber.

### getTopicConnection

    protected javax.jms.TopicConnection getTopicConnection()

  Returns the TopicConnection used for this appender. Only valid after activateOptions() method has been invoked.

### getTopicSession

    protected javax.jms.TopicSession getTopicSession()

  Returns the TopicSession used for this appender. Only valid after activateOptions() method has been invoked.

### getTopicPublisher

    protected javax.jms.TopicPublisher getTopicPublisher()

  Returns the TopicPublisher used for this appender. Only valid after activateOptions() method has been invoked.

### requiresLayout

    public boolean requiresLayout()

  The JMSAppender sends serialized events and consequently does not require a layout.

Copyright © 1999-2007 Apache Software Foundation. All Rights Reserved.