001 package org.apache.ojb.broker.core;
002
003 /* Copyright 2003-2005 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 import org.apache.ojb.broker.PBFactoryException;
019 import org.apache.ojb.broker.PBKey;
020 import org.apache.ojb.broker.PersistenceBroker;
021 import org.apache.ojb.broker.PersistenceBrokerInternal;
022 import org.apache.ojb.broker.util.configuration.Configurable;
023
024 /**
025 * Factory for {@link PersistenceBroker} instances.
026 * Each implementation have to provide a default constructor.
027 *
028 * @author <a href="mailto:thma@apache.org">Thomas Mahler<a>
029 * @version $Id: PersistenceBrokerFactoryIF.java,v 1.1 2007-08-24 22:17:35 ewestfal Exp $
030 */
031 public interface PersistenceBrokerFactoryIF extends Configurable
032 {
033 /**
034 * Set the {@link PBKey} used for convinience {@link PersistenceBroker}
035 * lookup method {@link #defaultPersistenceBroker}.
036 * <br/>
037 * Note: It's only allowed to set the default {@link PBKey} once.
038 * All further calls will cause an exception.
039 * If a default {@link org.apache.ojb.broker.metadata.JdbcConnectionDescriptor}
040 * was declared in configuration file, OJB will set the declared PBKey as default.
041 * <br/>
042 * This method is convenience for
043 * {@link org.apache.ojb.broker.metadata.MetadataManager#setDefaultPBKey}.
044 */
045 public void setDefaultKey(PBKey key);
046
047 /**
048 * Get the default {@link PBKey}.
049 * This method is convenience for
050 * {@link org.apache.ojb.broker.metadata.MetadataManager#getDefaultPBKey}.
051 *
052 * @see #setDefaultKey
053 */
054 public PBKey getDefaultKey();
055
056 /**
057 * Return {@link org.apache.ojb.broker.PersistenceBroker} instance for the given
058 * {@link org.apache.ojb.broker.PBKey}.
059 *
060 * @param key
061 */
062 public PersistenceBrokerInternal createPersistenceBroker(PBKey key) throws PBFactoryException;
063
064 /**
065 * Return a ready for action {@link org.apache.ojb.broker.PersistenceBroker} instance.
066 *
067 * @param jcdAlias An jcdAlias name specified in a <tt>jdbc-connection-descriptor</tt>
068 * @param user user name specified in a <tt>jdbc-connection-descriptor</tt>
069 * @param password valid password specified in a <tt>jdbc-connection-descriptor</tt>
070 */
071 public PersistenceBrokerInternal createPersistenceBroker(String jcdAlias, String user, String password)
072 throws PBFactoryException;
073
074 /**
075 * Return a default broker instance, specified in configuration
076 * or set using {@link #setDefaultKey}.
077 */
078 public PersistenceBrokerInternal defaultPersistenceBroker() throws PBFactoryException;
079
080 /**
081 * release all broker instances pooled by the factory.
082 * each broker instance is closed before release.
083 */
084 public void releaseAllInstances();
085
086 /**
087 * Returns the total number of
088 * active {@link org.apache.ojb.broker.PersistenceBroker}
089 * instances.
090 */
091 public int activePersistenceBroker();
092
093 /**
094 * Shutdown method for OJB, kills all running processes within OJB - after
095 * shutdown OJB can no longer be used.
096 * <br/>
097 * This method is introduced to solve hot/redeployment problems (memory leaks) caused by
098 * the usage of {@link ThreadLocal} instances in OJB source and the reuse of threads
099 * by the container (e.g. servlet- or ejb-container).
100 */
101 public void shutdown();
102 }