KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > swt > internal > Callback


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.swt.internal;
12
13
14 /**
15  * Instances of this class represent entry points into Java
16  * which can be invoked from operating system level callback
17  * routines.
18  * <p>
19  * IMPORTANT: A callback is only valid when invoked on the
20  * thread which created it. The results are undefined (and
21  * typically bad) when a callback is passed out to the
22  * operating system (or other code) in such a way that the
23  * callback is called from a different thread.
24  */

25
26 public class Callback {
27     
28     Object JavaDoc object;
29     String JavaDoc method, signature;
30     int argCount;
31     int /*long*/ address, errorResult;
32     boolean isStatic, isArrayBased;
33
34     static final String JavaDoc PTR_SIGNATURE = C.PTR_SIZEOF == 4 ? "I" : "J"; //$NON-NLS-1$ //$NON-NLS-2$
35
static final String JavaDoc SIGNATURE_0 = getSignature(0);
36     static final String JavaDoc SIGNATURE_1 = getSignature(1);
37     static final String JavaDoc SIGNATURE_2 = getSignature(2);
38     static final String JavaDoc SIGNATURE_3 = getSignature(3);
39     static final String JavaDoc SIGNATURE_4 = getSignature(4);
40     static final String JavaDoc SIGNATURE_N = "(["+PTR_SIGNATURE+")"+PTR_SIGNATURE; //$NON-NLS-1$ //$NON-NLS-2$
41

42 /**
43  * Constructs a new instance of this class given an object
44  * to send the message to, a string naming the method to
45  * invoke and an argument count. Note that, if the object
46  * is an instance of <code>Class</code> it is assumed that
47  * the method is a static method on that class.
48  *
49  * @param object the object to send the message to
50  * @param method the name of the method to invoke
51  * @param argCount the number of arguments that the method takes
52  */

53 public Callback (Object JavaDoc object, String JavaDoc method, int argCount) {
54     this (object, method, argCount, false);
55 }
56
57 /**
58  * Constructs a new instance of this class given an object
59  * to send the message to, a string naming the method to
60  * invoke, an argument count and a flag indicating whether
61  * or not the arguments will be passed in an array. Note
62  * that, if the object is an instance of <code>Class</code>
63  * it is assumed that the method is a static method on that
64  * class.
65  *
66  * @param object the object to send the message to
67  * @param method the name of the method to invoke
68  * @param argCount the number of arguments that the method takes
69  * @param isArrayBased <code>true</code> if the arguments should be passed in an array and false otherwise
70  */

71 public Callback (Object JavaDoc object, String JavaDoc method, int argCount, boolean isArrayBased) {
72     this (object, method, argCount, isArrayBased, 0);
73 }
74
75 /**
76  * Constructs a new instance of this class given an object
77  * to send the message to, a string naming the method to
78  * invoke, an argument count, a flag indicating whether
79  * or not the arguments will be passed in an array and a value
80  * to return when an exception happens. Note that, if
81  * the object is an instance of <code>Class</code>
82  * it is assumed that the method is a static method on that
83  * class.
84  *
85  * @param object the object to send the message to
86  * @param method the name of the method to invoke
87  * @param argCount the number of arguments that the method takes
88  * @param isArrayBased <code>true</code> if the arguments should be passed in an array and false otherwise
89  * @param errorResult the return value if the java code throws an exception
90  */

91 public Callback (Object JavaDoc object, String JavaDoc method, int argCount, boolean isArrayBased, int /*long*/ errorResult) {
92
93     /* Set the callback fields */
94     this.object = object;
95     this.method = method;
96     this.argCount = argCount;
97     this.isStatic = object instanceof Class JavaDoc;
98     this.isArrayBased = isArrayBased;
99     this.errorResult = errorResult;
100     
101     /* Inline the common cases */
102     if (isArrayBased) {
103         signature = SIGNATURE_N;
104     } else {
105         switch (argCount) {
106             case 0: signature = SIGNATURE_0; break; //$NON-NLS-1$
107
case 1: signature = SIGNATURE_1; break; //$NON-NLS-1$
108
case 2: signature = SIGNATURE_2; break; //$NON-NLS-1$
109
case 3: signature = SIGNATURE_3; break; //$NON-NLS-1$
110
case 4: signature = SIGNATURE_4; break; //$NON-NLS-1$
111
default:
112                 signature = getSignature(argCount);
113         }
114     }
115     
116     /* Bind the address */
117     address = bind (this, object, method, signature, argCount, isStatic, isArrayBased, errorResult);
118 }
119
120 /**
121  * Allocates the native level resources associated with the
122  * callback. This method is only invoked from within the
123  * constructor for the argument.
124  *
125  * @param callback the callback to bind
126  * @param object the callback's object
127  * @param method the callback's method
128  * @param signature the callback's method signature
129  * @param argCount the callback's method argument count
130  * @param isStatic whether the callback's method is static
131  * @param isArrayBased whether the callback's method is array based
132  * @param errorResult the callback's error result
133  */

134 static native synchronized int /*long*/ bind (Callback callback, Object JavaDoc object, String JavaDoc method, String JavaDoc signature, int argCount, boolean isStatic, boolean isArrayBased, int /*long*/ errorResult);
135
136 /**
137  * Releases the native level resources associated with the callback,
138  * and removes all references between the callback and
139  * other objects. This helps to prevent (bad) application code
140  * from accidentally holding onto extraneous garbage.
141  */

142 public void dispose () {
143     if (object == null) return;
144     unbind (this);
145     object = method = signature = null;
146     address = 0;
147 }
148
149 /**
150  * Returns the address of a block of machine code which will
151  * invoke the callback represented by the receiver.
152  *
153  * @return the callback address
154  */

155 public int /*long*/ getAddress () {
156     return address;
157 }
158
159 /**
160  * Returns the SWT platform name.
161  *
162  * @return the platform name of the currently running SWT
163  */

164 public static native String JavaDoc getPlatform ();
165
166 /**
167  * Returns the number of times the system has been recursively entered
168  * through a callback.
169  * <p>
170  * Note: This should not be called by application code.
171  * </p>
172  *
173  * @return the entry count
174  *
175  * @since 2.1
176  */

177 public static native int getEntryCount ();
178
179 static String JavaDoc getSignature(int argCount) {
180     String JavaDoc signature = "("; //$NON-NLS-1$
181
for (int i = 0; i < argCount; i++) signature += PTR_SIGNATURE;
182     signature += ")" + PTR_SIGNATURE; //$NON-NLS-1$
183
return signature;
184 }
185
186 /**
187  * Indicates whether or not callbacks which are triggered at the
188  * native level should cause the messages described by the matching
189  * <code>Callback</code> objects to be invoked. This method is used
190  * to safely shut down SWT when it is run within environments
191  * which can generate spurious events.
192  * <p>
193  * Note: This should not be called by application code.
194  * </p>
195  *
196  * @param enable true if callbacks should be invoked
197  */

198 public static final native synchronized void setEnabled (boolean enable);
199
200 /**
201  * Returns whether or not callbacks which are triggered at the
202  * native level should cause the messages described by the matching
203  * <code>Callback</code> objects to be invoked. This method is used
204  * to safely shut down SWT when it is run within environments
205  * which can generate spurious events.
206  * <p>
207  * Note: This should not be called by application code.
208  * </p>
209  *
210  * @return true if callbacks should not be invoked
211  */

212 public static final native synchronized boolean getEnabled ();
213
214 /**
215  * This might be called directly from native code in environments
216  * which can generate spurious events. Check before removing it.
217  *
218  * @deprecated
219  *
220  * @param ignore true if callbacks should not be invoked
221  */

222 static final void ignoreCallbacks (boolean ignore) {
223     setEnabled (!ignore);
224 }
225
226 /**
227  * Immediately wipes out all native level state associated
228  * with <em>all</em> callbacks.
229  * <p>
230  * <b>WARNING:</b> This operation is <em>extremely</em> dangerous,
231  * and should never be performed by application code.
232  * </p>
233  */

234 public static final native synchronized void reset ();
235
236 /**
237  * Releases the native level resources associated with the callback.
238  *
239  * @see #dispose
240  */

241 static final native synchronized void unbind (Callback callback);
242
243 }
244
Popular Tags