001: /*
002: * Copyright 2005 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.ws.server;
018:
019: import org.springframework.ws.context.MessageContext;
020:
021: /**
022: * Workflow interface that allows for customized endpoint invocation chains. Applications can register any number of
023: * existing or custom interceptors for certain groups of endpoints, to add common preprocessing behavior without needing
024: * to modify each endpoint implementation.
025: * <p/>
026: * A <code>EndpointInterceptor</code> gets called before the appropriate {@link EndpointAdapter} triggers the invocation
027: * of the endpoint itself. This mechanism can be used for a large field of preprocessing aspects, e.g. for authorization
028: * checks, or message header checks. Its main purpose is to allow for factoring out repetitive endpoint code.
029: * <p/>
030: * Typically an interceptor chain is defined per {@link EndpointMapping} bean, sharing its granularity. To be able to
031: * apply a certain interceptor chain to a group of handlers, one needs to map the desired handlers via one
032: * <code>EndpointMapping</code> bean.The interceptors themselves are defined as beans in the application context,
033: * referenced by the mapping bean definition via its <code>interceptors</code> property (in XML: a <list> of
034: * <ref>).
035: *
036: * @author Arjen Poutsma
037: * @see EndpointInvocationChain#getInterceptors()
038: * @see org.springframework.ws.server.endpoint.interceptor.EndpointInterceptorAdapter
039: * @see org.springframework.ws.server.endpoint.mapping.AbstractEndpointMapping#setInterceptors(EndpointInterceptor[])
040: * @since 1.0.0
041: */
042: public interface EndpointInterceptor {
043:
044: /**
045: * Processes the incoming request message. Called after {@link EndpointMapping} determined an appropriate endpoint
046: * object, but before {@link EndpointAdapter} invokes the endpoint.
047: * <p/>
048: * {@link MessageDispatcher} processes an endpoint in an invocation chain, consisting of any number of interceptors,
049: * with the endpoint itself at the end. With this method, each interceptor can decide to abort the chain, typically
050: * creating a custom response.
051: *
052: * @param messageContext contains the incoming request message
053: * @param endpoint chosen endpoint to invoke
054: * @return <code>true</code> to continue processing of the request interceptor chain; <code>false</code> to indicate
055: * blocking of the request endpoint chain, <em>without invoking the endpoint</em>
056: * @throws Exception in case of errors
057: * @see org.springframework.ws.context.MessageContext#getRequest()
058: */
059: boolean handleRequest(MessageContext messageContext, Object endpoint)
060: throws Exception;
061:
062: /**
063: * Processes the outgoing response message. Called after {@link EndpointAdapter} actually invoked the endpoint. Can
064: * manipulate the response, if any, by adding new headers, etc.
065: * <p/>
066: * {@link MessageDispatcher} processes an endpoint in an invocation chain, consisting of any number of interceptors,
067: * with the endpoint itself at the end. With this method, each interceptor can post-process an invocation, getting
068: * applied in inverse order of the execution chain.
069: * <p/>
070: * Note: Will only be called if this interceptor's {@link #handleRequest} method has successfully completed.
071: *
072: * @param messageContext contains both request and response messages
073: * @param endpoint chosen endpoint to invoke
074: * @return <code>true</code> to continue processing of the reponse interceptor chain; <code>false</code> to indicate
075: * blocking of the response endpoint chain.
076: * @throws Exception in case of errors
077: * @see org.springframework.ws.context.MessageContext#getRequest()
078: * @see org.springframework.ws.context.MessageContext#hasResponse()
079: * @see org.springframework.ws.context.MessageContext#getResponse()
080: */
081: boolean handleResponse(MessageContext messageContext,
082: Object endpoint) throws Exception;
083:
084: /**
085: * Processes the outgoing response fault. Called after {@link EndpointAdapter} actually invoked the endpoint. Can
086: * manipulate the response, if any, by adding new headers, etc.
087: * <p/>
088: * {@link MessageDispatcher} processes an endpoint in an invocation chain, consisting of any number of interceptors,
089: * with the endpoint itself at the end. With this method, each interceptor can post-process an invocation, getting
090: * applied in inverse order of the execution chain.
091: * <p/>
092: * Note: Will only be called if this interceptor's {@link #handleRequest} method has successfully completed.
093: *
094: * @param messageContext contains both request and response messages, the response should contains a Fault
095: * @param endpoint chosen endpoint to invoke
096: * @return <code>true</code> to continue processing of the reponse interceptor chain; <code>false</code> to indicate
097: * blocking of the response handler chain.
098: */
099: boolean handleFault(MessageContext messageContext, Object endpoint)
100: throws Exception;
101: }
|