KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > ojb > broker > core > proxy > IndirectionHandler


1 package org.apache.ojb.broker.core.proxy;
2
3 /* Copyright 2002-2005 The Apache Software Foundation
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17
18 import java.io.Serializable JavaDoc;
19 import java.lang.reflect.Method JavaDoc;
20
21 import org.apache.ojb.broker.Identity;
22 import org.apache.ojb.broker.PBKey;
23 import org.apache.ojb.broker.PersistenceBrokerException;
24
25
26
27 /**
28  * Base interface for indirection handlers used by OJB's proxies. Note that this interface needs JDK 1.3 or above.
29  * Implemening classes are required to have a public constructor with the signature
30  * ({@link org.apache.ojb.broker.PBKey}, {@link org.apache.ojb.broker.Identity}).<br/>
31  * Implementing classes should use this interface to acquire a logger.
32  *
33  * @version $Id: IndirectionHandler.java,v 1.2.2.2 2005/12/21 22:25:30 tomdz Exp $
34  */
35 public interface IndirectionHandler extends Serializable JavaDoc
36 {
37     /**
38      * Returns the key of the persistence broker used by this indirection handler.
39      * .
40      * @return The broker key
41      */
42     PBKey getBrokerKey();
43
44     /**
45      * Returns the identity of the subject.
46      *
47      * @return The identity
48      */
49     Identity getIdentity();
50
51     /**
52      * [Copied from {@link java.lang.reflect.InvocationHandler}]:<br/>
53      * Processes a method invocation on a proxy instance and returns
54      * the result. This method will be invoked on an invocation handler
55      * when a method is invoked on a proxy instance that it is
56      * associated with.
57      *
58      * @param proxy The proxy instance that the method was invoked on
59      *
60      * @param method The <code>Method</code> instance corresponding to
61      * the interface method invoked on the proxy instance. The declaring
62      * class of the <code>Method</code> object will be the interface that
63      * the method was declared in, which may be a superinterface of the
64      * proxy interface that the proxy class inherits the method through.
65      *
66      * @param args An array of objects containing the values of the
67      * arguments passed in the method invocation on the proxy instance,
68      * or <code>null</code> if interface method takes no arguments.
69      * Arguments of primitive types are wrapped in instances of the
70      * appropriate primitive wrapper class, such as
71      * <code>java.lang.Integer</code> or <code>java.lang.Boolean</code>.
72      *
73      * @return The value to return from the method invocation on the
74      * proxy instance. If the declared return type of the interface
75      * method is a primitive type, then the value returned by
76      * this method must be an instance of the corresponding primitive
77      * wrapper class; otherwise, it must be a type assignable to the
78      * declared return type. If the value returned by this method is
79      * <code>null</code> and the interface method's return type is
80      * primitive, then a <code>NullPointerException</code> will be
81      * thrown by the method invocation on the proxy instance. If the
82      * value returned by this method is otherwise not compatible with
83      * the interface method's declared return type as described above,
84      * a <code>ClassCastException</code> will be thrown by the method
85      * invocation on the proxy instance.
86      *
87      * @throws PersistenceBrokerException The exception to throw from the method
88      * invocation on the proxy instance. The exception's type must be
89      * assignable either to any of the exception types declared in the
90      * <code>throws</code> clause of the interface method or to the
91      * unchecked exception types <code>java.lang.RuntimeException</code>
92      * or <code>java.lang.Error</code>. If a checked exception is
93      * thrown by this method that is not assignable to any of the
94      * exception types declared in the <code>throws</code> clause of
95      * the interface method, then an
96      * {@link java.lang.reflect.UndeclaredThrowableException} containing the
97      * exception that was thrown by this method will be thrown by the
98      * method invocation on the proxy instance.
99      *
100      * @see java.lang.reflect.UndeclaredThrowableException
101      */
102     Object JavaDoc invoke(Object JavaDoc proxy, Method JavaDoc method, Object JavaDoc[] args);
103
104     /**
105      * Returns the proxies real subject. The subject will be materialized if necessary.
106      *
107      * @return The subject
108      */
109     Object JavaDoc 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 JavaDoc 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 }
141
Popular Tags