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.2.3 2005/12/21 22:25:31 tomdz Exp $
032: */
033: public interface ProxyFactory extends Serializable {
034: /**
035: * Returns the indirection handler class.
036: *
037: * @return The class for indirection handlers
038: */
039: public abstract Class getIndirectionHandlerClass();
040:
041: /**
042: * Sets the indirection handler class.
043: *
044: * @param indirectionHandlerClass The class for indirection handlers
045: */
046: public abstract void setIndirectionHandlerClass(
047: 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: * Returns the class of the base class that the given IndirectionHandler must extend/implement
058: *
059: */
060: public abstract Class getIndirectionHandlerBaseClass();
061:
062: /**
063: * Creates a new indirection handler instance.
064: *
065: * @param persistenceConf The persistence configuration
066: * @param id The subject's ids
067: * @return The new instance
068: */
069: public abstract IndirectionHandler createIndirectionHandler(
070: PBKey pbKey, Identity id);
071:
072: /**
073: * Returns the list proxy class.
074: *
075: * @return The class used for list proxies
076: */
077: public abstract Class getListProxyClass();
078:
079: /**
080: * Dets the proxy class to use for collection classes that implement the {@link java.util.List} interface.
081: * Notes that the proxy class must implement the {@link java.util.List} interface, and have a constructor
082: * of the signature ({@link org.apache.ojb.broker.PBKey}, {@link java.lang.Class}, {@link org.apache.ojb.broker.query.Query}).
083: *
084: * @param listProxyClass The proxy class
085: */
086: public abstract void setListProxyClass(Class listProxyClass);
087:
088: /**
089: * Returns the set proxy class.
090: *
091: * @return The class used for set proxies
092: */
093: public abstract Class getSetProxyClass();
094:
095: /**
096: * Dets the proxy class to use for collection classes that implement the {@link Set} interface.
097: *
098: * @param setProxyClass The proxy class
099: */
100: public abstract void setSetProxyClass(Class setProxyClass);
101:
102: /**
103: * Returns the collection proxy class.
104: *
105: * @return The class used for collection proxies
106: */
107: public abstract Class getCollectionProxyClass();
108:
109: /**
110: * Dets the proxy class to use for generic collection classes implementing the {@link java.util.Collection} interface.
111: *
112: * @param collectionProxyClass The proxy class
113: */
114: public abstract void setCollectionProxyClass(
115: 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(
125: PBKey brokerKey, Query query, Class collectionClass);
126:
127: public OJBProxy createProxy(Class baseClass,
128: IndirectionHandler handler) throws Exception;
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: /**
155: * Determines whether the given object is an OJB proxy.
156: *
157: * @return <code>true</code> if the object is an OJB proxy
158: */
159: public boolean isNormalOjbProxy(Object proxyOrObject);
160:
161: /**
162: * Determines whether the given object is an OJB virtual proxy.
163: *
164: * @return <code>true</code> if the object is an OJB virtual proxy
165: */
166: public boolean isVirtualOjbProxy(Object proxyOrObject);
167:
168: /**
169: * Returns <tt>true</tt> if the given object is a {@link java.lang.reflect.Proxy}
170: * or a {@link VirtualProxy} instance.
171: */
172: public boolean isProxy(Object proxyOrObject);
173:
174: /**
175: * Returns the invocation handler object of the given proxy object.
176: *
177: * @param obj The object
178: * @return The invocation handler if the object is an OJB proxy, or <code>null</code>
179: * otherwise
180: */
181: public IndirectionHandler getIndirectionHandler(Object obj);
182:
183: /**
184: * Determines whether the object is a materialized object, i.e. no proxy or a
185: * proxy that has already been loaded from the database.
186: *
187: * @param object The object to test
188: * @return <code>true</code> if the object is materialized
189: */
190: public boolean isMaterialized(Object object);
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: }
|