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    }