KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > excalibur > logger > factory > SMTPTargetFactory


1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
14  * implied.
15  *
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18 */
19 package org.apache.avalon.excalibur.logger.factory;
20
21 import javax.mail.Address JavaDoc;
22 import javax.mail.Session JavaDoc;
23 import javax.mail.internet.AddressException JavaDoc;
24 import javax.mail.internet.InternetAddress JavaDoc;
25 import org.apache.avalon.framework.configuration.Configuration;
26 import org.apache.avalon.framework.configuration.ConfigurationException;
27 import org.apache.avalon.framework.context.ContextException;
28 import org.apache.avalon.framework.parameters.Parameters;
29 import org.apache.log.LogTarget;
30 import org.apache.log.format.Formatter;
31 import org.apache.log.output.net.SMTPOutputLogTarget;
32
33 /**
34  * SMTPTargetFactory class.
35  *
36  * <p>
37  * This factory creates SMTPOutputLogTarget's. It uses the
38  * context-key attribute to locate the required JavaMail Session from
39  * the Context object passed to this factory. The default context-key
40  * is <code>session-context</code>.
41  * </p>
42  *
43  * <p>
44  * <pre>
45  * &lt;smtp id="target-id" context-key="context-key-to-session-object"&gt;
46  * &lt;format type="raw|pattern|extended"&gt;pattern to be used if needed&lt;/format&gt;
47  * &lt;to&gt;address-1@host&lt;/to&gt;
48  * &lt;to&gt;address-N@host&lt;/to&gt;
49  * &lt;from&gt;address@host&lt;/from&gt;
50  * &lt;subject&gt;subject line&lt;/subject&gt;
51  * &lt;maximum-size&gt;number&lt;/maximum-size&gt;
52  * &lt;maximum-delay-time&gt;seconds&lt;/maximum-delay-time&gt;
53  * &lt;debug&gt;false&lt;/debug&gt;
54  * &lt;/smtp&gt;
55  * </pre>
56  *
57  * The Factory will look for a javax.mail.Session instance in the Context using
58  * the specified context-key. If your needs are simple, then it is also possible
59  * to define a Session within the configuration by replacing the context-key
60  * attribute with a session child element as follows:
61  * <p>
62  * <pre>
63  * &lt;session&gt;
64  * &lt;parameter name="mail.host" value="mail.apache.com"/&gt;
65  * &lt;/session&gt;
66  * </pre>
67  * The Session is created by calling Session.getInstance, providing a Properties
68  * object whose values are defined in the above block. Any valid name value
69  * pair can be specified.
70  * <p>
71  *
72  * <dl>
73  * <dt>&lt;format&gt;</dt>
74  * <dd>
75  * The type attribute of the pattern element denotes the type of
76  * Formatter to be used and according to it the pattern to use for.
77  * This elements defaults to:
78  * <p>
79  * %7.7{priority} %5.5{time} [%8.8{category}] (%{context}): %{message}\\n%{throwable}
80  * </p>
81  * </dd>
82  * </dl>
83  * <p>
84  *
85  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
86  * @version CVS $Revision: 1.14 $ $Date: 2004/03/10 13:54:50 $
87  * @since 4.1
88  */
89 public class SMTPTargetFactory
90     extends AbstractTargetFactory
91 {
92     /**
93      * Creates an SMTPOutputLogTarget based on a Configuration
94      *
95      * @param config a <code>Configuration</code> instance
96      * @return <code>LogTarget</code> instance
97      * @exception ConfigurationException if an error occurs
98      */
99     public final LogTarget createTarget( final Configuration config )
100         throws ConfigurationException
101     {
102         try
103         {
104             SMTPOutputLogTarget logTarget = new SMTPOutputLogTarget(
105                 getSession( config ),
106                 getToAddresses( config ),
107                 getFromAddress( config ),
108                 getSubject( config ),
109                 getMaxSize( config ),
110                 getMaxDelayTime( config ),
111                 getFormatter( config )
112             );
113             
114             // Only set the debug flag when true. The flag is global in javamail
115 // and this makes things work more cleanly with old logkit versions.
116 boolean debug = getDebug( config );
117             if ( debug )
118             {
119                 logTarget.setDebug( debug );
120             }
121             
122             return logTarget;
123         }
124         catch( final ContextException ce )
125         {
126             throw new ConfigurationException( "Cannot find Session object in " +
127                                               "application context", ce );
128         }
129         catch( final AddressException JavaDoc ae )
130         {
131             throw new ConfigurationException( "Cannot create address", ae );
132         }
133     }
134
135     /**
136      * Helper method to obtain a formatter for this factory.
137      *
138      * @param config a <code>Configuration</code> instance
139      * @return a <code>Formatter</code> instance
140      */
141     protected Formatter getFormatter( final Configuration config )
142     {
143         final Configuration confFormat = config.getChild( "format" );
144
145         if( null != confFormat )
146         {
147             final FormatterFactory formatterFactory = new FormatterFactory();
148             return formatterFactory.createFormatter( confFormat );
149         }
150
151         return null;
152     }
153
154     /**
155      * Helper method to create a JavaMail <code>Session</code> object.
156      *
157      * If your session object has simple needs, you can nest a configuration element
158      * named <b>session</b> containing name-value pairs that are passed to
159      * <code>Session.getInstance()</code>.
160      *
161      * If no configuration is found, a <code>Session</code> will be loaded from this
162      * factory's context object.
163      *
164      * You can override this method if you need ot obtain the JavaMail session using
165      * some other means.
166      *
167      * @return JavaMail <code>Session</code> instance
168      * @exception ContextException if an error occurs
169      * @exception ConfigurationException if invalid session configuration
170      */
171     protected Session JavaDoc getSession( Configuration config )
172         throws ContextException, ConfigurationException
173     {
174         final Configuration sessionConfig = config.getChild( "session", false );
175
176         if( null == sessionConfig )
177         {
178             final String JavaDoc contextkey =
179                 m_configuration.getAttribute( "context-key", "session-context" );
180
181             if( m_context == null )
182             {
183                 throw new ConfigurationException( "Context not available" );
184             }
185
186             return (Session JavaDoc)m_context.get( contextkey );
187         }
188         else
189         {
190             return Session.getInstance(
191                 Parameters.toProperties(
192                     Parameters.fromConfiguration( sessionConfig ) ) );
193         }
194     }
195
196     /**
197      * Helper method to obtain the subject line to use from the given
198      * configuration object.
199      *
200      * @param config a <code>Configuration</code> instance
201      * @return subject line
202      */
203     private String JavaDoc getSubject( Configuration config )
204         throws ConfigurationException
205     {
206         return config.getChild( "subject" ).getValue();
207     }
208
209     /**
210      * Helper method to obtain the maximum size any particular SMTP
211      * message can be from a given configuration object.
212      *
213      * @param config a <code>Configuration</code> instance
214      * @return maximum SMTP mail size
215      */
216     private int getMaxSize( Configuration config )
217         throws ConfigurationException
218     {
219         return config.getChild( "maximum-size" ).getValueAsInteger( 1 );
220     }
221
222     /**
223      * Helper method to obtain the maximum delay time any particular SMTP
224      * message can be queued from a given configuration object.
225      *
226      * @param config a <code>Configuration</code> instance
227      * @return maximum SMTP mail delay time
228      */
229     private int getMaxDelayTime( Configuration config )
230         throws ConfigurationException
231     {
232         return config.getChild( "maximum-delay-time" ).getValueAsInteger( 0 );
233     }
234
235     /**
236      * Helper method to obtain the <i>to</i> address/es from the
237      * given configuration.
238      *
239      * @param config <code>Configuration</code> instance
240      * @return an array of <code>Address</code> objects
241      * @exception ConfigurationException if a configuration error occurs
242      * @exception AddressException if a addressing error occurs
243      */
244     private Address JavaDoc[] getToAddresses( final Configuration config )
245         throws ConfigurationException, AddressException JavaDoc
246     {
247         final Configuration[] toAddresses = config.getChildren( "to" );
248         final Address JavaDoc[] addresses = new Address JavaDoc[ toAddresses.length ];
249
250         for( int i = 0; i < toAddresses.length; ++i )
251         {
252             addresses[ i ] = createAddress( toAddresses[ i ].getValue() );
253         }
254
255         return addresses;
256     }
257
258     /**
259      * Helper method to obtain the <i>from</i> address from
260      * the given configuration.
261      *
262      * @param config a <code>Configuration</code> instance
263      * @return an <code>Address</code> object
264      * @exception ConfigurationException if a configuration error occurs
265      * @exception AddressException if a addressing error occurs
266      */
267     private Address JavaDoc getFromAddress( final Configuration config )
268         throws ConfigurationException, AddressException JavaDoc
269     {
270         return createAddress( config.getChild( "from" ).getValue() );
271     }
272
273     /**
274      * Helper method to obtain the debug glag to use from the given
275      * configuration object.
276      *
277      * @param config a <code>Configuration</code> instance
278      * @return subject line
279      */
280     private boolean getDebug( Configuration config )
281         throws ConfigurationException
282     {
283         return config.getChild( "debug" ).getValueAsBoolean();
284     }
285
286     /**
287      * Helper factory method to create a new <code>Address</code>
288      * object. Override this method in a subclass if you wish to
289      * create other Address types rather than
290      * <code>InternetAddress</code> (eg. <code>NewsAddress</code>)
291      *
292      * @param address address string from configuration
293      * @return an <code>Address</code> object
294      * @exception AddressException if an error occurs
295      */
296     protected Address JavaDoc createAddress( final String JavaDoc address )
297         throws AddressException JavaDoc
298     {
299         return new InternetAddress JavaDoc( address );
300     }
301 }
302
Popular Tags