001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019:
020: package org.apache.axis2.util;
021:
022: import org.apache.axis2.AxisFault;
023: import org.apache.axis2.context.MessageContext;
024:
025: /**
026: * This is the interface for a piece of code that will plug into the user
027: * programming model impl (e.g. JAX-WS impl) and will be invoked while on the
028: * ultimate thread of execution. It is intended to provide a mechanism to
029: * allow information to be migrated between the Axis2 contexts and thread
030: * local storage.
031: * <p/>
032: * Note: It is up to each particular programming model impl to decide whether
033: * or not they wish to make use of the ThreadContextMigrators.
034: * <p/>
035: * For each general MEP, here is the invocation pattern:
036: * <p/>
037: * [one-way inbound]
038: * migrateContextToThread(req)
039: * cleanupThread(req)
040: * <p/>
041: * [req/rsp inbound]
042: * migrateContextToThread(req)
043: * migrateThreadToContext(rsp)
044: * cleanupContext(rsp)
045: * cleanupThread(req)
046: * <p/>
047: * [one-way outbound]
048: * migrateThreadToContext(req)
049: * cleanupContext(req)
050: * <p/>
051: * [req/rsp outbound (both sync and async)]
052: * migrateThreadToContext(req)
053: * cleanupContext(req)
054: * migrateContextToThread(rsp)
055: * Note: there is no corresponding cleanupThread(rsp); one of the inbound
056: * cases would need to handle this
057: * <p/>
058: * If a fault occurs during execution of one of the migrators, it will be
059: * treated like any other service fault (i.e. like what will happen if we can't
060: * deliver the message to a service or if a handler fails.
061: * <p/>
062: * The cleanup* methods can be expected to be invoked after any exeception
063: * that occurs within the scope of the migration that would cause that scope
064: * to be left so that the thread and/or context may be cleaned up properly.
065: */
066: public interface ThreadContextMigrator {
067: /**
068: * This method will be invoked when the processing of the message is
069: * guaranteed to be on the thread of execution that will be used in
070: * user space. It will be invoked for incoming messages.
071: * Implementations of this interface can use the information found in the
072: * MessageContext to determine whether a request or response is being
073: * processed.
074: * (e.g. MessageContext.getAxisOperation().getMessageExchangePattern())
075: *
076: * @param messageContext
077: * @throws AxisFault
078: */
079: void migrateContextToThread(MessageContext messageContext)
080: throws AxisFault;
081:
082: /**
083: * This method will be invoked when the processing of the message is
084: * guaranteed to still be on the thread of execution that was used in user
085: * space, after all processing has completed (i.e. when the particular
086: * processing of a message is unwinding.) It provides a mechanism which can
087: * be used to clean up the TLS.
088: *
089: * @param messageContext
090: */
091: void cleanupThread(MessageContext messageContext);
092:
093: /**
094: * This method will be invoked when the processing of the message is
095: * guaranteed to still be on the thread of execution that was used in
096: * user space. It will be invoked for both outgoing messages.
097: * Implementations of this interface can use the information found in the
098: * MessageContext to determine whether a request or response is being
099: * processed.
100: * (e.g. MessageContext.getAxisOperation().getMessageExchangePattern())
101: *
102: * @param messageContext
103: * @throws AxisFault
104: */
105: void migrateThreadToContext(MessageContext messageContext)
106: throws AxisFault;
107:
108: /**
109: * This method will be invoked when the processing of the message is
110: * guaranteed to be on the thread of execution that will be used in user
111: * space, after all processing has completed (i.e. when the particular
112: * processing of a message is unwinding.) It provides a mechanism which can
113: * be used to clean up the MessageContext or restore TLS.
114: *
115: * @param messageContext
116: */
117: void cleanupContext(MessageContext messageContext);
118: }
|