001 package org.apache.fulcrum.pool; 002 003 004 /* 005 * Licensed to the Apache Software Foundation (ASF) under one 006 * or more contributor license agreements. See the NOTICE file 007 * distributed with this work for additional information 008 * regarding copyright ownership. The ASF licenses this file 009 * to you under the Apache License, Version 2.0 (the 010 * "License"); you may not use this file except in compliance 011 * with the License. You may obtain a copy of the License at 012 * 013 * http://www.apache.org/licenses/LICENSE-2.0 014 * 015 * Unless required by applicable law or agreed to in writing, 016 * software distributed under the License is distributed on an 017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 018 * KIND, either express or implied. See the License for the 019 * specific language governing permissions and limitations 020 * under the License. 021 */ 022 023 024 025 /** 026 * The Pool Service extends the Factory Service by adding support 027 * for pooling instantiated objects. When a new instance is 028 * requested, the service first checks its pool if one is available. 029 * If the the pool is empty, a new object will be instantiated 030 * from the specified class. If only class name is given, the request 031 * to create an instance will be forwarded to the Factory Service. 032 * 033 * <p>For objects implementing the Recyclable interface, a recycle 034 * method will be called, when they are taken from the pool, and 035 * a dispose method, when they are returned to the pool. 036 * 037 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a> 038 * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a> 039 * @version $Id: PoolService.java 542061 2007-05-28 00:26:58Z seade $ 040 */ 041 public interface PoolService 042 { 043 /** Avalon role - used to id the component within the manager */ 044 String ROLE = PoolService.class.getName(); 045 046 047 /** 048 * The default pool capacity. 049 */ 050 public static final int DEFAULT_POOL_CAPACITY = 128; 051 052 /** 053 * Gets an instance of a specified class either from the pool 054 * or by instantiating from the class if the pool is empty. 055 * 056 * @param clazz the class. 057 * @return the instance. 058 * @throws PoolException if recycling fails. 059 */ 060 public Object getInstance(Class clazz) 061 throws PoolException; 062 063 /** 064 * Gets an instance of a specified class either from the pool 065 * or by instantiating from the class if the pool is empty. 066 * 067 * @param clazz the class. 068 * @param params an array containing the parameters of the constructor. 069 * @param signature an array containing the signature of the constructor. 070 * @return the instance. 071 * @throws PoolException if recycling fails. 072 */ 073 public Object getInstance(Class clazz, 074 Object params[], 075 String signature[]) 076 throws PoolException; 077 078 /** 079 * Puts a used object back to the pool. Objects implementing 080 * the Recyclable interface can provide a recycle method to 081 * be called when they are reused and a dispose method to be 082 * called when they are returned to the pool. 083 * 084 * @param instance the object instance to recycle. 085 * @return true if the instance was accepted. 086 */ 087 public boolean putInstance(Object instance); 088 089 /** 090 * Gets the capacity of the pool for a named class. 091 * 092 * @param className the name of the class. 093 */ 094 public int getCapacity(String className); 095 096 /** 097 * Sets the capacity of the pool for a named class. 098 * Note that the pool will be cleared after the change. 099 * 100 * @param className the name of the class. 101 * @param capacity the new capacity. 102 */ 103 public void setCapacity(String className, 104 int capacity); 105 106 /** 107 * Gets the current size of the pool for a named class. 108 * 109 * @param className the name of the class. 110 */ 111 public int getSize(String className); 112 113 /** 114 * Clears instances of a named class from the pool. 115 * 116 * @param className the name of the class. 117 */ 118 public void clearPool(String className); 119 120 /** 121 * Clears all instances from the pool. 122 */ 123 void clearPool(); 124 125 }