1 /*
2 * Copyright 2005 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.ws.server;
18
19 import org.springframework.ws.context.MessageContext;
20
21 /**
22 * Workflow interface that allows for customized endpoint invocation chains. Applications can register any number of
23 * existing or custom interceptors for certain groups of endpoints, to add common preprocessing behavior without needing
24 * to modify each endpoint implementation.
25 * <p/>
26 * A <code>EndpointInterceptor</code> gets called before the appropriate {@link EndpointAdapter} triggers the invocation
27 * of the endpoint itself. This mechanism can be used for a large field of preprocessing aspects, e.g. for authorization
28 * checks, or message header checks. Its main purpose is to allow for factoring out repetitive endpoint code.
29 * <p/>
30 * Typically an interceptor chain is defined per {@link EndpointMapping} bean, sharing its granularity. To be able to
31 * apply a certain interceptor chain to a group of handlers, one needs to map the desired handlers via one
32 * <code>EndpointMapping</code> bean.The interceptors themselves are defined as beans in the application context,
33 * referenced by the mapping bean definition via its <code>interceptors</code> property (in XML: a <list> of
34 * <ref>).
35 *
36 * @author Arjen Poutsma
37 * @see EndpointInvocationChain#getInterceptors()
38 * @see org.springframework.ws.server.endpoint.interceptor.EndpointInterceptorAdapter
39 * @see org.springframework.ws.server.endpoint.mapping.AbstractEndpointMapping#setInterceptors(EndpointInterceptor[])
40 * @since 1.0.0
41 */
42 public interface EndpointInterceptor {
43
44 /**
45 * Processes the incoming request message. Called after {@link EndpointMapping} determined an appropriate endpoint
46 * object, but before {@link EndpointAdapter} invokes the endpoint.
47 * <p/>
48 * {@link MessageDispatcher} processes an endpoint in an invocation chain, consisting of any number of interceptors,
49 * with the endpoint itself at the end. With this method, each interceptor can decide to abort the chain, typically
50 * creating a custom response.
51 *
52 * @param messageContext contains the incoming request message
53 * @param endpoint chosen endpoint to invoke
54 * @return <code>true</code> to continue processing of the request interceptor chain; <code>false</code> to indicate
55 * blocking of the request endpoint chain, <em>without invoking the endpoint</em>
56 * @throws Exception in case of errors
57 * @see org.springframework.ws.context.MessageContext#getRequest()
58 */
59 boolean handleRequest(MessageContext messageContext, Object endpoint) throws Exception;
60
61 /**
62 * Processes the outgoing response message. Called after {@link EndpointAdapter} actually invoked the endpoint. Can
63 * manipulate the response, if any, by adding new headers, etc.
64 * <p/>
65 * {@link MessageDispatcher} processes an endpoint in an invocation chain, consisting of any number of interceptors,
66 * with the endpoint itself at the end. With this method, each interceptor can post-process an invocation, getting
67 * applied in inverse order of the execution chain.
68 * <p/>
69 * Note: Will only be called if this interceptor's {@link #handleRequest} method has successfully completed.
70 *
71 * @param messageContext contains both request and response messages
72 * @param endpoint chosen endpoint to invoke
73 * @return <code>true</code> to continue processing of the reponse interceptor chain; <code>false</code> to indicate
74 * blocking of the response endpoint chain.
75 * @throws Exception in case of errors
76 * @see org.springframework.ws.context.MessageContext#getRequest()
77 * @see org.springframework.ws.context.MessageContext#hasResponse()
78 * @see org.springframework.ws.context.MessageContext#getResponse()
79 */
80 boolean handleResponse(MessageContext messageContext, Object endpoint) throws Exception;
81
82 /**
83 * Processes the outgoing response fault. Called after {@link EndpointAdapter} actually invoked the endpoint. Can
84 * manipulate the response, if any, by adding new headers, etc.
85 * <p/>
86 * {@link MessageDispatcher} processes an endpoint in an invocation chain, consisting of any number of interceptors,
87 * with the endpoint itself at the end. With this method, each interceptor can post-process an invocation, getting
88 * applied in inverse order of the execution chain.
89 * <p/>
90 * Note: Will only be called if this interceptor's {@link #handleRequest} method has successfully completed.
91 *
92 * @param messageContext contains both request and response messages, the response should contains a Fault
93 * @param endpoint chosen endpoint to invoke
94 * @return <code>true</code> to continue processing of the reponse interceptor chain; <code>false</code> to indicate
95 * blocking of the response handler chain.
96 */
97 boolean handleFault(MessageContext messageContext, Object endpoint) throws Exception;
98 }