KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > excalibur > pool > ValidatedResourceLimitingPool


1 /*
2
3  ============================================================================
4                    The Apache Software License, Version 1.1
5  ============================================================================
6  
7  Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved.
8  
9  Redistribution and use in source and binary forms, with or without modifica-
10  tion, are permitted provided that the following conditions are met:
11  
12  1. Redistributions of source code must retain the above copyright notice,
13     this list of conditions and the following disclaimer.
14  
15  2. Redistributions in binary form must reproduce the above copyright notice,
16     this list of conditions and the following disclaimer in the documentation
17     and/or other materials provided with the distribution.
18  
19  3. The end-user documentation included with the redistribution, if any, must
20     include the following acknowledgment: "This product includes software
21     developed by the Apache Software Foundation (http://www.apache.org/)."
22     Alternately, this acknowledgment may appear in the software itself, if
23     and wherever such third-party acknowledgments normally appear.
24  
25  4. The names "Jakarta", "Avalon", "Excalibur" and "Apache Software Foundation"
26     must not be used to endorse or promote products derived from this software
27     without prior written permission. For written permission, please contact
28     apache@apache.org.
29  
30  5. Products derived from this software may not be called "Apache", nor may
31     "Apache" appear in their name, without prior written permission of the
32     Apache Software Foundation.
33  
34  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
35  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
36  FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
37  APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
38  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU-
39  DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
40  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
41  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
42  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
43  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44  
45  This software consists of voluntary contributions made by many individuals
46  on behalf of the Apache Software Foundation. For more information on the
47  Apache Software Foundation, please see <http://www.apache.org/>.
48  
49 */
50 package org.apache.avalon.excalibur.pool;
51
52 /**
53  * A ResourceLimitingPool which validates reused poolables before they are
54  * returned with a call get().
55  *
56  * @author <a HREF="mailto:leif@tanukisoftware.com">Leif Mortenson</a>
57  * @version CVS $Revision: 1.2 $ $Date: 2003/02/20 17:09:24 $
58  * @since 4.1
59  */
60 public class ValidatedResourceLimitingPool
61     extends ResourceLimitingPool
62 {
63     /*---------------------------------------------------------------
64      * Private Fields
65      *-------------------------------------------------------------*/
66     /**
67      * Used for communication between the get() and newPoolable() methods, only valid
68      * within a single synchronized block.
69      */
70     private boolean m_needsValidation;
71
72     /*---------------------------------------------------------------
73      * Constructors
74      *-------------------------------------------------------------*/
75     /**
76      * Creates a new ValidatedResourceLimitingPool
77      *
78      * @param factory The ObjectFactory which will be used to create new Poolables as needed by
79      * the pool.
80      * @param max Maximum number of Poolables which can be stored in the pool, 0 implies no limit.
81      * @param maxStrict true if the pool should never allow more than max Poolable to be created.
82      * Will cause an exception to be thrown if more than max Poolables are requested and blocking
83      * is false.
84      * @param blocking true if the pool should cause a thread calling get() to block when Poolables
85      * are not currently available on the pool.
86      * @param blockTimeout The maximum amount of time, in milliseconds, that a call to get() will
87      * block before an exception is thrown. A value of 0 implies an indefinate wait.
88      * @param trimInterval The minimum interval with which old unused poolables will be removed
89      * from the pool. A value of 0 will cause the pool to never trim poolables.
90      */
91     public ValidatedResourceLimitingPool( final ObjectFactory factory,
92                                           int max,
93                                           boolean maxStrict,
94                                           boolean blocking,
95                                           long blockTimeout,
96                                           long trimInterval )
97     {
98
99         super( factory, max, maxStrict, blocking, blockTimeout, trimInterval );
100     }
101
102     /*---------------------------------------------------------------
103      * Pool Methods
104      *-------------------------------------------------------------*/
105     /**
106      * Gets a Poolable from the pool. If there is room in the pool, a new Poolable will be
107      * created. Depending on the parameters to the constructor, the method may block or throw
108      * an exception if a Poolable is not available on the pool.
109      *
110      * @return Always returns a Poolable. Contract requires that put must always be called with
111      * the Poolable returned.
112      * @throws Exception An exception may be thrown as described above or if there is an exception
113      * thrown by the ObjectFactory's newInstance() method.
114      */
115     public Poolable get() throws Exception JavaDoc
116     {
117         Poolable poolable;
118         boolean needsValidation;
119
120         // If an obtained Poolable is invalid, then we will want to obtain another one requiring
121 // that we loop.
122 do
123         {
124             synchronized( m_semaphore )
125             {
126                 // Set the needs validation flag to false. The super.get() method will call the
127 // newPoolable() method causing the flag to be set to false if called.
128 m_needsValidation = true;
129
130                 poolable = super.get();
131
132                 // Store the validation flag in a local variable so that we can continue to use it
133 // after we release the semaphore.
134 needsValidation = m_needsValidation;
135             }
136
137             // If necessay, validate the poolable now that this thread owns it.
138 if( needsValidation )
139             {
140                 // Call the validation method for the obtained poolable.
141 if( !validatePoolable( poolable ) )
142                 {
143                     // The poolable is no longer valid. We need to resynchronize to remove the bad
144 // poolable and prepare to get another one.
145 synchronized( m_semaphore )
146                     {
147                         if( getLogger().isDebugEnabled() )
148                         {
149                             getLogger().debug( "Removing a " + poolable.getClass().getName()
150                                                + " from the pool because it failed validation." );
151                         }
152
153                         permanentlyRemovePoolable( poolable );
154                         poolable = null;
155                     }
156                 }
157             }
158         } while( poolable == null );
159
160         return poolable;
161     }
162
163     /*---------------------------------------------------------------
164      * ResourceLimitingPool Methods
165      *-------------------------------------------------------------*/
166     /**
167      * Create a new poolable instance by by calling the newInstance method
168      * on the pool's ObjectFactory.
169      * This is the method to override when you need to enforce creational
170      * policies.
171      * This method is only called by threads that have m_semaphore locked.
172      */
173     protected Poolable newPoolable() throws Exception JavaDoc
174     {
175         // Set the validation flag to false. See the exclamation in the get() method.
176 m_needsValidation = false;
177
178         return super.newPoolable();
179     }
180
181     /*---------------------------------------------------------------
182      * Public Methods
183      *-------------------------------------------------------------*/
184     /**
185      * If the poolable implements Validatable, then its validate() method will be called to give
186      * the poolable a chance to validate itself.
187      * Different functionality can be achieved by overriding this method.
188      * This method is only called by threads that have m_semaphore locked.
189      *
190      * @param poolable The Poolable to be validated
191      * @return true if the Poolable is valid, false if it should be removed from the pool.
192      */
193     protected boolean validatePoolable( Poolable poolable ) throws Exception JavaDoc
194     {
195         if( poolable instanceof Validatable )
196         {
197             return ( (Validatable)poolable ).validate();
198         }
199         else
200         {
201             return true;
202         }
203     }
204 }
205
206
Popular Tags