1 /*
2 * Copyright 2005-2011 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 *
26 * <p>An {@code EndpointInterceptor} gets called before the appropriate {@link EndpointAdapter} triggers the
27 * invocation of the endpoint itself. This mechanism can be used for a large field of preprocessing aspects, e.g. for
28 * authorization checks, or message header checks. Its main purpose is to allow for factoring out repetitive endpoint
29 * code.
30 *
31 * <p>Typically an interceptor chain is defined per {@link EndpointMapping} bean, sharing its granularity. To be able to
32 * apply a certain interceptor chain to a group of handlers, one needs to map the desired handlers via one
33 * {@code EndpointMapping} bean. The interceptors themselves are defined as beans in the application context,
34 * referenced by the mapping bean definition via its {@code interceptors} property (in XML: a <list> of
35 * <ref>).
36 *
37 * @author Arjen Poutsma
38 * @see EndpointInvocationChain#getInterceptors()
39 * @see org.springframework.ws.server.endpoint.interceptor.EndpointInterceptorAdapter
40 * @see org.springframework.ws.server.endpoint.mapping.AbstractEndpointMapping#setInterceptors(EndpointInterceptor[])
41 * @since 1.0.0
42 */
43 public interface EndpointInterceptor {
44
45 /**
46 * Processes the incoming request message. Called after {@link EndpointMapping} determined an appropriate endpoint
47 * object, but before {@link EndpointAdapter} invokes the endpoint.
48 *
49 * <p>{@link MessageDispatcher} processes an endpoint in an invocation chain, consisting of any number of interceptors,
50 * with the endpoint itself at the end. With this method, each interceptor can decide to abort the chain, typically
51 * creating a custom response.
52 *
53 * @param messageContext contains the incoming request message
54 * @param endpoint chosen endpoint to invoke
55 * @return {@code true} to continue processing of the request interceptor chain; {@code false} to indicate
56 * blocking of the request endpoint chain, <em>without invoking the endpoint</em>
57 * @throws Exception in case of errors
58 * @see MessageContext#getRequest()
59 */
60 boolean handleRequest(MessageContext messageContext, Object endpoint) throws Exception;
61
62 /**
63 * Processes the outgoing response message. Called after {@link EndpointAdapter} actually invoked the endpoint. Can
64 * manipulate the response, if any, by adding new headers, etc.
65 *
66 * <p>{@link MessageDispatcher} processes an endpoint in an invocation chain, consisting of any number of interceptors,
67 * with the endpoint itself at the end. With this method, each interceptor can post-process an invocation, getting
68 * applied in inverse order of the execution chain.
69 *
70 * <p>Note: Will only be called if this interceptor's {@link #handleRequest} method has successfully completed.
71 *
72 * @param messageContext contains both request and response messages
73 * @param endpoint chosen endpoint to invoke
74 * @return {@code true} to continue processing of the response interceptor chain; {@code false} to indicate
75 * blocking of the response endpoint chain.
76 * @throws Exception in case of errors
77 * @see MessageContext#getRequest()
78 * @see MessageContext#hasResponse()
79 * @see MessageContext#getResponse()
80 */
81 boolean handleResponse(MessageContext messageContext, Object endpoint) throws Exception;
82
83 /**
84 * Processes the outgoing response fault. Called after {@link EndpointAdapter} actually invoked the endpoint. Can
85 * manipulate the response, if any, by adding new headers, etc.
86 *
87 * <p>{@link MessageDispatcher} processes an endpoint in an invocation chain, consisting of any number of interceptors,
88 * with the endpoint itself at the end. With this method, each interceptor can post-process an invocation, getting
89 * applied in inverse order of the execution chain.
90 *
91 * <p>Note: Will only be called if this interceptor's {@link #handleRequest} method has successfully completed.
92 *
93 * @param messageContext contains both request and response messages, the response should contains a Fault
94 * @param endpoint chosen endpoint to invoke
95 * @return {@code true} to continue processing of the response interceptor chain; {@code false} to indicate
96 * blocking of the response handler chain.
97 */
98 boolean handleFault(MessageContext messageContext, Object endpoint) throws Exception;
99
100 /**
101 * Callback after completion of request and response (fault) processing. Will be called on any outcome of endpoint
102 * invocation, thus allows for proper resource cleanup.
103 *
104 * <p>Note: Will only be called if this interceptor's {@link #handleRequest} method has successfully completed.
105 *
106 * <p>As with the {@link #handleResponse} method, the method will be invoked on each interceptor in the chain in
107 * reverse order, so the first interceptor will be the last to be invoked.
108 *
109 * @param messageContext contains both request and response messages, the response should contains a Fault
110 * @param endpoint chosen endpoint to invoke
111 * @param ex exception thrown on handler execution, if any
112 * @throws Exception in case of errors
113 * @since 2.0.2
114 */
115 void afterCompletion(MessageContext messageContext, Object endpoint, Exception ex) throws Exception;
116 }
117