View Javadoc

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   * <p/>
26   * An [email protected] EndpointInterceptor} gets called before the appropriate [email protected] 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   * <p/>
31   * Typically an interceptor chain is defined per [email protected] 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   * [email protected] EndpointMapping} bean. The interceptors themselves are defined as beans in the application context,
34   * referenced by the mapping bean definition via its [email protected] interceptors} property (in XML: a &lt;list&gt; of
35   * &lt;ref&gt;).
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 [email protected] EndpointMapping} determined an appropriate endpoint
47       * object, but before [email protected] EndpointAdapter} invokes the endpoint.
48       * <p/>
49       * [email protected] 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 [email protected] true} to continue processing of the request interceptor chain; [email protected] 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 [email protected] EndpointAdapter} actually invoked the endpoint. Can
64       * manipulate the response, if any, by adding new headers, etc.
65       * <p/>
66       * [email protected] 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       * <p/>
70       * Note: Will only be called if this interceptor's [email protected] #handleRequest}  method has successfully completed.
71       *
72       * @param messageContext contains both request and response messages
73       * @param endpoint       chosen endpoint to invoke
74       * @return [email protected] true} to continue processing of the response interceptor chain; [email protected] 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 [email protected] EndpointAdapter} actually invoked the endpoint. Can
85       * manipulate the response, if any, by adding new headers, etc.
86       * <p/>
87       * [email protected] 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       * <p/>
91       * Note: Will only be called if this interceptor's [email protected] #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 [email protected] true} to continue processing of the response interceptor chain; [email protected] 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      * <p/>
104      * Note: Will only be called if this interceptor's [email protected] #handleRequest}  method has successfully completed.
105      * <p/>
106      * As with the [email protected] #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 }