1 /* 2 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.xml.internal.ws.api.pipe; 27 28 import java.security.AccessController; 29 import java.security.PrivilegedAction; 30 31 /** 32 * Interception for {@link Fiber} context switch. 33 * 34 * <p> 35 * Even though pipeline runs asynchronously, sometimes it's desirable 36 * to bind some state to the current thread running a fiber. Such state 37 * may include security subject (in terms of {@link AccessController#doPrivileged}), 38 * or a transaction. 39 * 40 * <p> 41 * This mechanism makes it possible to do such things, by allowing 42 * some code to be executed before and after a thread executes a fiber. 43 * 44 * <p> 45 * The design also encapsulates the entire fiber execution in a single 46 * opaque method invocation {@link Work#execute}, allowing the use of 47 * {@code finally} block. 48 * 49 * 50 * @author Kohsuke Kawaguchi 51 */ 52 public interface FiberContextSwitchInterceptor { 53 /** 54 * Allows the interception of the fiber execution. 55 * 56 * <p> 57 * This method needs to be implemented like this: 58 * 59 * <pre> 60 * <R,P> R execute( Fiber f, P p, Work<R,P> work ) { 61 * // do some preparation work 62 * ... 63 * try { 64 * // invoke 65 * return work.execute(p); 66 * } finally { 67 * // do some clean up work 68 * ... 69 * } 70 * } 71 * </pre> 72 * 73 * <p> 74 * While somewhat unintuitive, 75 * this interception mechanism enables the interceptor to wrap 76 * the whole fiber execution into a {@link AccessController#doPrivileged(PrivilegedAction)}, 77 * for example. 78 * 79 * @param f 80 * {@link Fiber} to be executed. 81 * @param p 82 * The opaque parameter value for {@link Work}. Simply pass this value to 83 * {@link Work#execute(Object)}. 84 * @return 85 * The opaque return value from the the {@link Work}. Simply return 86 * the value from {@link Work#execute(Object)}. 87 */ 88 <R,P> R execute( Fiber f, P p, Work<R,P> work ); 89 90 /** 91 * Abstraction of the execution that happens inside the interceptor. 92 */ 93 interface Work<R,P> { 94 /** 95 * Have the current thread executes the current fiber, 96 * and returns when it stops doing so. 97 * 98 * <p> 99 * The parameter and the return value is controlled by the 100 * JAX-WS runtime, and interceptors should simply treat 101 * them as opaque values. 102 */ 103 R execute(P param); 104 } 105 }