org.apache.log4j.net

Class JMSAppender

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(LoggingEvent) method to do most of the real appending work.
protected boolean
checkEntryConditions()
void
close()
Close this JMSAppender.
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.
String
getPassword()
String
getProviderURL()
String
getSecurityCredentials()
String
getSecurityPrincipalName()
String
getTopicBindingName()
Returns the value of the TopicBindingName option.
protected TopicConnection
getTopicConnection()
Returns the TopicConnection used for this appender.
String
getTopicConnectionFactoryBindingName()
Returns the value of the TopicConnectionFactoryBindingName option.
protected TopicPublisher
getTopicPublisher()
Returns the TopicPublisher used for this appender.
protected TopicSession
getTopicSession()
Returns the TopicSession used for this appender.
String
getUserName()
protected Object
lookup(Context ctx, String name)
boolean
requiresLayout()
The JMSAppender sends serialized events and consequently does not require a layout.
void
setInitialContextFactoryName(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(String password)
The paswword to use when creating a topic session.
void
setProviderURL(String providerURL)
void
setSecurityCredentials(String securityCredentials)
void
setSecurityPrincipalName(String securityPrincipalName)
void
setTopicBindingName(String topicBindingName)
The TopicBindingName option takes a string value.
void
setTopicConnectionFactoryBindingName(String tcfBindingName)
The TopicConnectionFactoryBindingName option takes a string value.
void
setURLPkgPrefixes(String urlPkgPrefixes)
void
setUserName(String userName)
The user name to use when creating a topic session.

Methods inherited from class org.apache.log4j.AppenderSkeleton

activateOptions, addFilter, append, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isAsSevereAsThreshold, setErrorHandler, setLayout, setName, setThreshold

Constructor Details

JMSAppender

public JMSAppender()

Method Details

activateOptions

public void activateOptions()
Options are activated and become effective only after calling this method.
Specified by:
activateOptions in interface OptionHandler
Overrides:
activateOptions in interface AppenderSkeleton

append

public void append(LoggingEvent event)
This method called by AppenderSkeleton.doAppend(LoggingEvent) method to do most of the real appending work.
Overrides:
append in interface AppenderSkeleton

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.
Specified by:
close in interface Appender

getInitialContextFactoryName

public String getInitialContextFactoryName()

getLocationInfo

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

getPassword

public String getPassword()

getProviderURL

public String getProviderURL()

getSecurityCredentials

public String getSecurityCredentials()

getSecurityPrincipalName

public String getSecurityPrincipalName()

getTopicBindingName

public String getTopicBindingName()
Returns the value of the TopicBindingName option.

getTopicConnection

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

getTopicConnectionFactoryBindingName

public String getTopicConnectionFactoryBindingName()
Returns the value of the TopicConnectionFactoryBindingName option.

getTopicPublisher

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

getTopicSession

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

getUserName

public String getUserName()

lookup

protected Object lookup(Context ctx,
                        String name)
            throws NamingException

requiresLayout

public boolean requiresLayout()
The JMSAppender sends serialized events and consequently does not require a layout.
Specified by:
requiresLayout in interface Appender

setInitialContextFactoryName

public void setInitialContextFactoryName(String initialContextFactoryName)

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.

setPassword

public void setPassword(String password)
The paswword to use when creating a topic session.

setProviderURL

public void setProviderURL(String providerURL)

setSecurityCredentials

public void setSecurityCredentials(String securityCredentials)

setSecurityPrincipalName

public void setSecurityPrincipalName(String securityPrincipalName)

setTopicBindingName

public void setTopicBindingName(String topicBindingName)
The TopicBindingName option takes a string value. Its value will be used to lookup the appropriate Topic from the JNDI context.

setTopicConnectionFactoryBindingName

public void setTopicConnectionFactoryBindingName(String tcfBindingName)
The TopicConnectionFactoryBindingName option takes a string value. Its value will be used to lookup the appropriate TopicConnectionFactory from the JNDI context.

setURLPkgPrefixes

public void setURLPkgPrefixes(String urlPkgPrefixes)

setUserName

public void setUserName(String userName)

Copyright 2000-2005 Apache Software Foundation.