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