001: /*
002: * Copyright 1999-2004 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.chain;
017:
018: import java.util.HashMap;
019: import java.util.Iterator;
020: import java.util.Map;
021: import org.apache.commons.chain.impl.CatalogFactoryBase;
022:
023: import org.apache.commons.logging.Log;
024: import org.apache.commons.logging.LogFactory;
025:
026: /**
027: * <p>A {@link CatalogFactory} is a class used to store and retrieve
028: * {@link Catalog}s. The factory allows for a default {@link Catalog}
029: * as well as {@link Catalog}s stored with a name key. Follows the
030: * Factory pattern (see GoF).</p>
031: *
032: * <p>The base <code>CatalogFactory</code> implementation also implements
033: * a resolution mechanism which allows lookup of a command based on a single
034: * String which encodes both the catalog and command names.</p>
035: *
036: * @author Sean Schofield
037: * @version $Revision: 411893 $ $Date: 2006-06-05 19:59:05 +0100 (Mon, 05 Jun 2006) $
038: */
039:
040: public abstract class CatalogFactory {
041:
042: /**
043: * <p>Values passed to the <code>getCommand(String)</code> method should
044: * use this as the delimiter between the "catalog" name and the "command"
045: * name.</p>
046: */
047: public static final String DELIMITER = ":";
048:
049: // --------------------------------------------------------- Public Methods
050:
051: /**
052: * <p>Gets the default instance of Catalog associated with the factory
053: * (if any); otherwise, return <code>null</code>.</p>
054: *
055: * @return the default Catalog instance
056: */
057: public abstract Catalog getCatalog();
058:
059: /**
060: * <p>Sets the default instance of Catalog associated with the factory.</p>
061: *
062: * @param catalog the default Catalog instance
063: */
064: public abstract void setCatalog(Catalog catalog);
065:
066: /**
067: * <p>Retrieves a Catalog instance by name (if any); otherwise
068: * return <code>null</code>.</p>
069: *
070: * @param name the name of the Catalog to retrieve
071: * @return the specified Catalog
072: */
073: public abstract Catalog getCatalog(String name);
074:
075: /**
076: * <p>Adds a named instance of Catalog to the factory (for subsequent
077: * retrieval later).</p>
078: *
079: * @param name the name of the Catalog to add
080: * @param catalog the Catalog to add
081: */
082: public abstract void addCatalog(String name, Catalog catalog);
083:
084: /**
085: * <p>Return an <code>Iterator</code> over the set of named
086: * {@link Catalog}s known to this {@link CatalogFactory}.
087: * If there are no known catalogs, an empty Iterator is returned.</p>
088: * @return An Iterator of the names of the Catalogs known by this factory.
089: */
090: public abstract Iterator getNames();
091:
092: /**
093: * <p>Return a <code>Command</code> based on the given commandID.</p>
094: *
095: * <p>At this time, the structure of commandID is relatively simple: if the
096: * commandID contains a DELIMITER, treat the segment of the commandID
097: * up to (but not including) the DELIMITER as the name of a catalog, and the
098: * segment following the DELIMITER as a command name within that catalog.
099: * If the commandID contains no DELIMITER, treat the commandID as the name
100: * of a command in the default catalog.</p>
101: *
102: * <p>To preserve the possibility of future extensions to this lookup
103: * mechanism, the DELIMITER string should be considered reserved, and
104: * should not be used in command names. commandID values which contain
105: * more than one DELIMITER will cause an
106: * <code>IllegalArgumentException</code> to be thrown.</p>
107: *
108: * @param commandID the identifier of the command to return
109: * @return the command located with commandID, or <code>null</code>
110: * if either the command name or the catalog name cannot be resolved
111: * @throws IllegalArgumentException if the commandID contains more than
112: * one DELIMITER
113: *
114: * @since Chain 1.1
115: */
116: public Command getCommand(String commandID) {
117:
118: String commandName = commandID;
119: String catalogName = null;
120: Catalog catalog = null;
121:
122: if (commandID != null) {
123: int splitPos = commandID.indexOf(DELIMITER);
124: if (splitPos != -1) {
125: catalogName = commandID.substring(0, splitPos);
126: commandName = commandID.substring(splitPos
127: + DELIMITER.length());
128: if (commandName.indexOf(DELIMITER) != -1) {
129: throw new IllegalArgumentException(
130: "commandID ["
131: + commandID
132: + "] has too many delimiters (reserved for future use)");
133: }
134: }
135: }
136:
137: if (catalogName != null) {
138: catalog = this .getCatalog(catalogName);
139: if (catalog == null) {
140: Log log = LogFactory.getLog(CatalogFactory.class);
141: log.warn("No catalog found for name: " + catalogName
142: + ".");
143: return null;
144: }
145: } else {
146: catalog = this .getCatalog();
147: if (catalog == null) {
148: Log log = LogFactory.getLog(CatalogFactory.class);
149: log.warn("No default catalog found.");
150: return null;
151: }
152: }
153:
154: return catalog.getCommand(commandName);
155:
156: }
157:
158: // ------------------------------------------------------- Static Variables
159:
160: /**
161: * <p>The set of registered {@link CatalogFactory} instances,
162: * keyed by the relevant class loader.</p>
163: */
164: private static Map factories = new HashMap();
165:
166: // -------------------------------------------------------- Static Methods
167:
168: /**
169: * <p>Return the singleton {@link CatalogFactory} instance
170: * for the relevant <code>ClassLoader</code>. For applications
171: * that use a thread context class loader (such as web applications
172: * running inside a servet container), this will return a separate
173: * instance for each application, even if this class is loaded from
174: * a shared parent class loader.</p>
175: *
176: * @return the per-application singleton instance of {@link CatalogFactory}
177: */
178: public static CatalogFactory getInstance() {
179:
180: CatalogFactory factory = null;
181: ClassLoader cl = getClassLoader();
182: synchronized (factories) {
183: factory = (CatalogFactory) factories.get(cl);
184: if (factory == null) {
185: factory = new CatalogFactoryBase();
186: factories.put(cl, factory);
187: }
188: }
189: return factory;
190:
191: }
192:
193: /**
194: * <p>Clear all references to registered catalogs, as well as to the
195: * relevant class loader. This method should be called, for example,
196: * when a web application utilizing this class is removed from
197: * service, to allow for garbage collection.</p>
198: */
199: public static void clear() {
200:
201: synchronized (factories) {
202: factories.remove(getClassLoader());
203: }
204:
205: }
206:
207: // ------------------------------------------------------- Private Methods
208:
209: /**
210: * <p>Return the relevant <code>ClassLoader</code> to use as a Map key
211: * for this request. If there is a thread context class loader, return
212: * that; otherwise, return the class loader that loaded this class.</p>
213: */
214: private static ClassLoader getClassLoader() {
215:
216: ClassLoader cl = Thread.currentThread().getContextClassLoader();
217: if (cl == null) {
218: cl = CatalogFactory.class.getClassLoader();
219: }
220: return cl;
221:
222: }
223:
224: }
|