1 /* 2 * Copyright (c) 1997, 2015, 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 * @author Kohsuke Kawaguchi 50 */ 51 public interface FiberContextSwitchInterceptor { 52 /** 53 * Allows the interception of the fiber execution. 54 * 55 * <p> 56 * This method needs to be implemented like this: 57 * 58 * <pre> 59 * <R,P> R execute( Fiber f, P p, Work<R,P> work ) { 60 * // do some preparation work 61 * ... 62 * try { 63 * // invoke 64 * return work.execute(p); 65 * } finally { 66 * // do some clean up work 67 * ... 68 * } 69 * } 70 * </pre> 71 * 72 * <p> 73 * While somewhat unintuitive, 74 * this interception mechanism enables the interceptor to wrap 75 * the whole fiber execution into a {@link AccessController#doPrivileged(PrivilegedAction)}, 76 * for example. 77 * 78 * @param f 79 * {@link Fiber} to be executed. 80 * @param p 81 * The opaque parameter value for {@link Work}. Simply pass this value to 82 * {@link Work#execute(Object)}. 83 * @return 84 * The opaque return value from the the {@link Work}. Simply return 85 * the value from {@link Work#execute(Object)}. 86 */ 87 <R,P> R execute( Fiber f, P p, Work<R,P> work ); 88 89 /** 90 * Abstraction of the execution that happens inside the interceptor. 91 */ 92 interface Work<R,P> { 93 /** 94 * Have the current thread executes the current fiber, 95 * and returns when it stops doing so. 96 * 97 * <p> 98 * The parameter and the return value is controlled by the 99 * JAX-WS runtime, and interceptors should simply treat 100 * them as opaque values. 101 */ 102 R execute(P param); 103 } 104 }