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.lang.reflect.Method;
020
021 import org.apache.ojb.broker.Identity;
022 import org.apache.ojb.broker.PBKey;
023 import org.apache.ojb.broker.PersistenceBrokerException;
024
025
026
027 /**
028 * Base interface for indirection handlers used by OJB's proxies. Note that this interface needs JDK 1.3 or above.
029 * Implemening classes are required to have a public constructor with the signature
030 * ({@link org.apache.ojb.broker.PBKey}, {@link org.apache.ojb.broker.Identity}).<br/>
031 * Implementing classes should use this interface to acquire a logger.
032 *
033 * @version $Id: IndirectionHandler.java,v 1.1 2007-08-24 22:17:32 ewestfal Exp $
034 */
035 public interface IndirectionHandler extends Serializable
036 {
037 /**
038 * Returns the key of the persistence broker used by this indirection handler.
039 * .
040 * @return The broker key
041 */
042 PBKey getBrokerKey();
043
044 /**
045 * Returns the identity of the subject.
046 *
047 * @return The identity
048 */
049 Identity getIdentity();
050
051 /**
052 * [Copied from {@link java.lang.reflect.InvocationHandler}]:<br/>
053 * Processes a method invocation on a proxy instance and returns
054 * the result. This method will be invoked on an invocation handler
055 * when a method is invoked on a proxy instance that it is
056 * associated with.
057 *
058 * @param proxy The proxy instance that the method was invoked on
059 *
060 * @param method The <code>Method</code> instance corresponding to
061 * the interface method invoked on the proxy instance. The declaring
062 * class of the <code>Method</code> object will be the interface that
063 * the method was declared in, which may be a superinterface of the
064 * proxy interface that the proxy class inherits the method through.
065 *
066 * @param args An array of objects containing the values of the
067 * arguments passed in the method invocation on the proxy instance,
068 * or <code>null</code> if interface method takes no arguments.
069 * Arguments of primitive types are wrapped in instances of the
070 * appropriate primitive wrapper class, such as
071 * <code>java.lang.Integer</code> or <code>java.lang.Boolean</code>.
072 *
073 * @return The value to return from the method invocation on the
074 * proxy instance. If the declared return type of the interface
075 * method is a primitive type, then the value returned by
076 * this method must be an instance of the corresponding primitive
077 * wrapper class; otherwise, it must be a type assignable to the
078 * declared return type. If the value returned by this method is
079 * <code>null</code> and the interface method's return type is
080 * primitive, then a <code>NullPointerException</code> will be
081 * thrown by the method invocation on the proxy instance. If the
082 * value returned by this method is otherwise not compatible with
083 * the interface method's declared return type as described above,
084 * a <code>ClassCastException</code> will be thrown by the method
085 * invocation on the proxy instance.
086 *
087 * @throws PersistenceBrokerException The exception to throw from the method
088 * invocation on the proxy instance. The exception's type must be
089 * assignable either to any of the exception types declared in the
090 * <code>throws</code> clause of the interface method or to the
091 * unchecked exception types <code>java.lang.RuntimeException</code>
092 * or <code>java.lang.Error</code>. If a checked exception is
093 * thrown by this method that is not assignable to any of the
094 * exception types declared in the <code>throws</code> clause of
095 * the interface method, then an
096 * {@link java.lang.reflect.UndeclaredThrowableException} containing the
097 * exception that was thrown by this method will be thrown by the
098 * method invocation on the proxy instance.
099 *
100 * @see java.lang.reflect.UndeclaredThrowableException
101 */
102 Object invoke(Object proxy, Method method, Object[] args);
103
104 /**
105 * Returns the proxies real subject. The subject will be materialized if necessary.
106 *
107 * @return The subject
108 */
109 Object getRealSubject() throws PersistenceBrokerException;
110
111 /**
112 * Sets the real subject of this proxy.
113 * [olegnitz] This looks stupid, but is really necessary for OTM:
114 * the materialization listener replaces the real subject
115 * by its clone to ensure transaction isolation.
116 * Is there a better way to do this?
117 */
118 void setRealSubject(Object object);
119
120 /**
121 * Determines whether the real subject already has been materialized.
122 *
123 * @return <code>true</code> if the real subject has already been loaded
124 */
125 boolean alreadyMaterialized();
126
127 /**
128 * Adds a materialization listener.
129 *
130 * @param l The listener to add
131 */
132 void addListener(MaterializationListener l);
133
134 /**
135 * Removes a materialization listener.
136 *
137 * @param l The listener to remove
138 */
139 void removeListener(MaterializationListener l);
140 }