001 /* ====================================================================
002 * The Apache Software License, Version 1.1
003 *
004 * Copyright (c) 2003 The Apache Software Foundation. All rights
005 * reserved.
006 *
007 * Redistribution and use in source and binary forms, with or without
008 * modification, are permitted provided that the following conditions
009 * are met:
010 *
011 * 1. Redistributions of source code must retain the above copyright
012 * notice, this list of conditions and the following disclaimer.
013 *
014 * 2. Redistributions in binary form must reproduce the above copyright
015 * notice, this list of conditions and the following disclaimer in
016 * the documentation and/or other materials provided with the
017 * distribution.
018 *
019 * 3. The end-user documentation included with the redistribution,
020 * if any, must include the following acknowledgment:
021 * "This product includes software developed by the
022 * Apache Software Foundation (http://www.apache.org/)."
023 * Alternately, this acknowledgment may appear in the software itself,
024 * if and wherever such third-party acknowledgments normally appear.
025 *
026 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
027 * Foundation" must not be used to endorse or promote products derived
028 * from this software without prior written permission. For written
029 * permission, please contact apache@apache.org.
030 *
031 * 5. Products derived from this software may not be called "Apache",
032 * nor may "Apache" appear in their name, without prior written
033 * permission of the Apache Software Foundation.
034 *
035 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
036 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
037 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
038 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
039 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
040 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
041 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
042 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
043 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
044 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
045 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
046 * SUCH DAMAGE.
047 * ====================================================================
048 *
049 * This software consists of voluntary contributions made by many
050 * individuals on behalf of the Apache Software Foundation. For more
051 * information on the Apache Software Foundation, please see
052 * <http://www.apache.org/>.
053 *
054 */
055 package org.jpu.patterns.singleton.onePerContext;
056
057 import java.util.List;
058 import java.util.Map;
059
060 /**
061 * Interface implemented by the {@link OnePerContextManager} class. See that class for more info.
062 */
063 public interface IOnePerContextManager {
064 public static final IContext DEFAULT_CONTEXT = new SimpleContext();
065
066 /**
067 * Interface to be implemented by classes that are registered as initializers via {@link IOnePerContextManager#addInitializer}.
068 * The list of initializers is called in order immediately after a One-Per-Context has been
069 * instantiated.
070 *
071 * @see #addInitializer
072 * @see #removeInitializer
073 * @see #getInitializers
074 */
075 public static interface IInitializer {
076 public void initialize(OnePerContextManager mgr, Object ctx, Object opc);
077 }
078
079 /**
080 * Interface to be implemented by classes that are registered as instantiators via {@link IOnePerContextManager#setInstantiator}.
081 * Every {@link OnePerContextManager} has exactly one instantiator whose function it is to create
082 * instances of the associated One-Per-Context class. The default implementation is
083 * {@link OnePerContextManager.DefaultInstantiator}, which uses <code>java.lang.Class.newInstance()</code> to invoke the
084 * no-arg constructor.
085 *
086 * @see #setInstantiator
087 * @see #getInstantiator
088 */
089 public static interface IInstantiator {
090 public Object newInstance(IOnePerContextManager mgr, Object ctx);
091 }
092
093 /**
094 * Returns the class passed as the first parameter to the constructor.
095 */
096 public Class getOnePerContextClass();
097
098 /**
099 * Returns a shallow copy of the internal map that maps contexts to One-Per-Context instances. Since
100 * the <code>Map</code> is a copy, the caller can query and modify it at will without synchronization.
101 */
102 public Map getObjects();
103
104 /**
105 * Returns a shallow copy of the internal list of {@link IOnePerContextManager.IInitializer}'s. Since
106 * the <code>List</code> is a copy, the caller can query and modify it at will without synchronization.
107 */
108 public List getInitializers();
109
110 /**
111 * Adds the given initializer at position "<code>i</code>".
112 */
113 public void addInitializer(int i, IInitializer initializer);
114
115 /**
116 * Removes the given initializer at position "<code>i</code>".
117 */
118 public IInitializer removeInitializer(int i);
119
120 /**
121 * Removes the given initializer.
122 */
123 public boolean removeInitializer(IInitializer ini);
124
125 /**
126 * Returns the {@link IOnePerContextManager.IInstantiator} used for instantiating One-Per-Context's.
127 */
128 public IInstantiator getInstantiator();
129
130 /**
131 * Sets the {@link IOnePerContextManager.IInstantiator} to be used for instantiating One-Per-Context's.
132 */
133 public void setInstantiator(IInstantiator i);
134
135 /**
136 * Returns the One-Per-Context of the given class associated with the given
137 * context. If no such instance exists, it is created and stored for subsequent reuse.
138 * @param ctx The context. Can be <code>null</code> in which case <code>onePerContextClass</code> is used as the context.
139 */
140 public Object getInstance( Object ctx );
141 }