#region License
/*
* Copyright 2002-2005 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#endregion
namespace Spring.Pool{
/// <summary>
/// Defines lifecycle methods for objects that are to be used in an
/// <see cref="Spring.Pool.IObjectPool"/> implementation.
/// </summary>
/// <remarks>
/// <p>
/// The following methods summarize the contract between an
/// <see cref="Spring.Pool.IObjectPool"/> and an
/// an <see cref="Spring.Pool.IPoolableObjectFactory"/>.
/// </p>
/// <list type="number">
/// <item>
/// <see cref="Spring.Pool.IPoolableObjectFactory.MakeObject"/>
/// is called whenever a new instance is needed.
/// </item>
/// <item>
/// <see cref="Spring.Pool.IPoolableObjectFactory.ActivateObject"/>
/// is invoked on every instance before it is returned from
/// the pool.
/// </item>
/// <item>
/// <see cref="Spring.Pool.IPoolableObjectFactory.PassivateObject"/>
/// is invoked on every instance when it is returned to the pool.
/// </item>
/// <item>
/// <see cref="Spring.Pool.IPoolableObjectFactory.DestroyObject"/>
/// is invoked on every instance when it is being dropped from the
/// pool (see
/// <see cref="Spring.Pool.IPoolableObjectFactory.ValidateObject"/>
/// </item>
/// </list>
/// <p>
/// Based on the Jakarta Commons Pool API.
/// </p>
/// </remarks>
/// <author>Federico Spinazzi</author>
/// <seealso cref="Spring.Pool.IObjectPool"/>
public interface IPoolableObjectFactory
{
/// <summary>
/// Creates an instance that can be returned by the pool.
/// </summary>
/// <returns>
/// An instance that can be returned by the pool.
/// </returns>
object MakeObject();
/// <summary>
/// Destroys an instance no longer needed by the pool.
/// </summary>
/// <remarks>
/// <p>
/// Invoked on every instance when it is being "dropped"
/// from the pool (whether due to the return value from a call to the
/// <see cref="Spring.Pool.IPoolableObjectFactory.ValidateObject"/>
/// method, or for reasons specific to the pool implementation.)
/// </p>
/// </remarks>
/// <param name="obj">The instance to be destroyed.</param>
void DestroyObject(object obj);
/// <summary>
/// Ensures that the instance is safe to be returned by the pool.
/// Returns false if this object should be destroyed.
/// </summary>
/// <remarks>
/// <p>
/// Invoked in an implementation-specific fashion to determine if an
/// instance is still valid to be returned by the pool.
/// It will only be invoked on an "activated" instance.
/// </p>
/// </remarks>
/// <param name="obj">The instance to validate.</param>
/// <returns>
/// <see langword="false"/> if this object is not valid and
/// should be dropped from the pool, otherwise <see langword="true"/>.
/// </returns>
bool ValidateObject(object obj);
/// <summary>
/// Reinitialize an instance to be returned by the pool.
/// </summary>
/// <remarks>
/// <p>
/// Invoked on every instance before it is returned from the pool.
/// </p>
/// </remarks>
/// <param name="obj">The instance to be activated.</param>
void ActivateObject(object obj);
/// <summary>
/// Uninitialize an instance to be returned to the pool.
/// </summary>
/// <remarks>
/// <p>
/// Invoked on every instance when it is returned to the pool.
/// </p>
/// </remarks>
/// <param name="obj">The instance returned to the pool.</param>
void PassivateObject(object obj);
}
}
|