001 package org.apache.ojb.broker.core.proxy;
002
003 /* Copyright 2002-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 java.io.Serializable;
019 import java.util.Set;
020
021 import org.apache.ojb.broker.Identity;
022 import org.apache.ojb.broker.ManageableCollection;
023 import org.apache.ojb.broker.PBKey;
024 import org.apache.ojb.broker.query.Query;
025
026 /**
027 * Factory class for creating instances of the indirection handler used by OJB's proxies, and
028 * for the collection proxies.
029 *
030 * @author <a href="mailto:tomdz@apache.org">Thomas Dudziak<a>
031 * @version $Id: ProxyFactory.java,v 1.1 2007-08-24 22:17:32 ewestfal Exp $
032 */
033 public interface ProxyFactory extends Serializable
034 {
035 /**
036 * Returns the indirection handler class.
037 *
038 * @return The class for indirection handlers
039 */
040 public abstract Class getIndirectionHandlerClass();
041
042 /**
043 * Sets the indirection handler class.
044 *
045 * @param indirectionHandlerClass The class for indirection handlers
046 */
047 public abstract void setIndirectionHandlerClass(Class indirectionHandlerClass);
048
049 /**
050 * Returns the class of a default IndirectionHandler that can be used for this implementaiton
051 * if now IndirectionHandlerClass implementation is given.
052 *
053 */
054 public abstract Class getDefaultIndirectionHandlerClass();
055
056
057 /**
058 * Returns the class of the base class that the given IndirectionHandler must extend/implement
059 *
060 */
061 public abstract Class getIndirectionHandlerBaseClass();
062
063
064 /**
065 * Creates a new indirection handler instance.
066 *
067 * @param persistenceConf The persistence configuration
068 * @param id The subject's ids
069 * @return The new instance
070 */
071 public abstract IndirectionHandler createIndirectionHandler(PBKey pbKey, Identity id);
072
073 /**
074 * Returns the list proxy class.
075 *
076 * @return The class used for list proxies
077 */
078 public abstract Class getListProxyClass();
079
080 /**
081 * Dets the proxy class to use for collection classes that implement the {@link java.util.List} interface.
082 * Notes that the proxy class must implement the {@link java.util.List} interface, and have a constructor
083 * of the signature ({@link org.apache.ojb.broker.PBKey}, {@link java.lang.Class}, {@link org.apache.ojb.broker.query.Query}).
084 *
085 * @param listProxyClass The proxy class
086 */
087 public abstract void setListProxyClass(Class listProxyClass);
088
089 /**
090 * Returns the set proxy class.
091 *
092 * @return The class used for set proxies
093 */
094 public abstract Class getSetProxyClass();
095
096 /**
097 * Dets the proxy class to use for collection classes that implement the {@link Set} interface.
098 *
099 * @param setProxyClass The proxy class
100 */
101 public abstract void setSetProxyClass(Class setProxyClass);
102
103 /**
104 * Returns the collection proxy class.
105 *
106 * @return The class used for collection proxies
107 */
108 public abstract Class getCollectionProxyClass();
109
110 /**
111 * Dets the proxy class to use for generic collection classes implementing the {@link java.util.Collection} interface.
112 *
113 * @param collectionProxyClass The proxy class
114 */
115 public abstract void setCollectionProxyClass(Class collectionProxyClass);
116
117 /**
118 * Create a Collection Proxy for a given context.
119 *
120 * @param persistenceConf The persistence configuration that the proxy will be bound to
121 * @param context The creation context
122 * @return The collection proxy
123 */
124 public abstract ManageableCollection createCollectionProxy(PBKey brokerKey, Query query, Class collectionClass);
125
126
127 public OJBProxy createProxy(Class baseClass, IndirectionHandler handler) throws Exception;
128
129
130 /**
131 * Get the real Object
132 *
133 * @param objectOrProxy
134 * @return Object
135 */
136 public Object getRealObject(Object objectOrProxy);
137
138 /**
139 * Get the real Object for already materialized Handler
140 *
141 * @param objectOrProxy
142 * @return Object or null if the Handel is not materialized
143 */
144 public Object getRealObjectIfMaterialized(Object objectOrProxy);
145
146 /**
147 * Get the real Class
148 *
149 * @param objectOrProxy
150 * @return Class
151 */
152 public Class getRealClass(Object objectOrProxy);
153 /**
154 * Determines whether the given object is an OJB proxy.
155 *
156 * @return <code>true</code> if the object is an OJB proxy
157 */
158 public boolean isNormalOjbProxy(Object proxyOrObject);
159
160 /**
161 * Determines whether the given object is an OJB virtual proxy.
162 *
163 * @return <code>true</code> if the object is an OJB virtual proxy
164 */
165 public boolean isVirtualOjbProxy(Object proxyOrObject);
166
167 /**
168 * Returns <tt>true</tt> if the given object is a {@link java.lang.reflect.Proxy}
169 * or a {@link VirtualProxy} instance.
170 */
171 public boolean isProxy(Object proxyOrObject);
172
173 /**
174 * Returns the invocation handler object of the given proxy object.
175 *
176 * @param obj The object
177 * @return The invocation handler if the object is an OJB proxy, or <code>null</code>
178 * otherwise
179 */
180 public IndirectionHandler getIndirectionHandler(Object obj);
181
182 /**
183 * Determines whether the object is a materialized object, i.e. no proxy or a
184 * proxy that has already been loaded from the database.
185 *
186 * @param object The object to test
187 * @return <code>true</code> if the object is materialized
188 */
189 public boolean isMaterialized(Object object);
190
191
192 /**
193 * Return CollectionProxy for item is item is a CollectionProxy, otherwise return null
194 */
195 public CollectionProxy getCollectionProxy(Object item);
196
197 /**
198 * Reports if item is a CollectionProxy.
199 *
200 * TODO: Provide handling for pluggable collection proxy implementations
201 */
202 public boolean isCollectionProxy(Object item);
203
204 /**
205 * Materialization-safe version of toString. If the object is a yet-unmaterialized proxy,
206 * then only the text "unmaterialized proxy for ..." is returned and the proxy is NOT
207 * materialized. Otherwise, the normal toString method is called. This useful e.g. for
208 * logging etc.
209 *
210 * @param object The object for which a string representation shall be generated
211 * @return The string representation
212 */
213 public String toString(Object proxy);
214
215 /**
216 * Method that returns whether or not this ProxyFactory can generate reference Proxies
217 * for classes regardless if they extend an interface or not.
218 *
219 */
220 boolean interfaceRequiredForProxyGeneration();
221 }