1. /*
  2. * Copyright 1999-2004 The Apache Software Foundation.
  3. *
  4. * Licensed under the Apache License, Version 2.0 (the "License");
  5. * you may not use this file except in compliance with the License.
  6. * You may obtain a copy of the License at
  7. *
  8. * http://www.apache.org/licenses/LICENSE-2.0
  9. *
  10. * Unless required by applicable law or agreed to in writing, software
  11. * distributed under the License is distributed on an "AS IS" BASIS,
  12. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13. * See the License for the specific language governing permissions and
  14. * limitations under the License.
  15. */
  16. package org.apache.commons.pool;
  17. /**
  18. * An interface defining life-cycle methods for
  19. * instances to be used in an
  20. * {@link ObjectPool ObjectPool}.
  21. * <p>
  22. * By contract, when an {@link ObjectPool ObjectPool}
  23. * delegates to a <tt>PoolableObjectFactory</tt>,
  24. * <ol>
  25. * <li>
  26. * {@link #makeObject makeObject}
  27. * is called whenever a new instance is needed.
  28. * </li>
  29. * <li>
  30. * {@link #activateObject activateObject}
  31. * is invoked on every instance before it is returned from the
  32. * pool.
  33. * </li>
  34. * <li>
  35. * {@link #passivateObject passivateObject}
  36. * is invoked on every instance when it is returned to the
  37. * pool.
  38. * </li>
  39. * <li>
  40. * {@link #destroyObject destroyObject}
  41. * is invoked on every instance when it is being "dropped" from the
  42. * pool (whether due to the response from
  43. * {@link #validateObject validateObject}, or
  44. * for reasons specific to the pool implementation.)
  45. * </li>
  46. * <li>
  47. * {@link #validateObject validateObject}
  48. * is invoked in an implementation-specific fashion to determine if an instance
  49. * is still valid to be returned by the pool.
  50. * It will only be invoked on an {@link #activateObject "activated"}
  51. * instance.
  52. * </li>
  53. * </ol>
  54. *
  55. * @see ObjectPool
  56. *
  57. * @author Rodney Waldhoff
  58. * @version $Revision: 1.8 $ $Date: 2004/02/28 12:16:21 $
  59. */
  60. public interface PoolableObjectFactory {
  61. /**
  62. * Creates an instance that can be returned by the pool.
  63. * @return an instance that can be returned by the pool.
  64. */
  65. Object makeObject() throws Exception;
  66. /**
  67. * Destroys an instance no longer needed by the pool.
  68. * @param obj the instance to be destroyed
  69. */
  70. void destroyObject(Object obj) throws Exception;
  71. /**
  72. * Ensures that the instance is safe to be returned by the pool.
  73. * Returns <tt>false</tt> if this object should be destroyed.
  74. * @param obj the instance to be validated
  75. * @return <tt>false</tt> if this <i>obj</i> is not valid and should
  76. * be dropped from the pool, <tt>true</tt> otherwise.
  77. */
  78. boolean validateObject(Object obj);
  79. /**
  80. * Reinitialize an instance to be returned by the pool.
  81. * @param obj the instance to be activated
  82. */
  83. void activateObject(Object obj) throws Exception;
  84. /**
  85. * Uninitialize an instance to be returned to the pool.
  86. * @param obj the instance to be passivated
  87. */
  88. void passivateObject(Object obj) throws Exception;
  89. }