View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
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  package javax.xml.rpc.handler;
17  
18  import java.util.List;
19  import java.util.Map;
20  
21  /**
22   * The <code>javax.xml.rpc.handler.HandlerChain</code> represents
23   * a list of handlers. All elements in the HandlerChain are of
24   * the type <code>javax.xml.rpc.handler.Handler</code>.
25   * <p>
26   * An implementation class for the <code>HandlerChain</code>
27   * interface abstracts the policy and mechanism for the invocation
28   * of the registered handlers.
29   *
30   * @version 1.0
31   */
32  public interface HandlerChain extends List {
33  
34      /**
35       * The <code>handleRequest</code> method initiates the request
36       * processing for this handler chain.
37       * @param context MessageContext parameter provides access to
38       *             the request SOAP message.
39       * @return boolean Returns <code>true</code> if all handlers in
40       *             chain have been processed. Returns <code>false</code>
41       *
42       *             if a handler in the chain returned
43       *             <code>false</code> from its handleRequest
44       *             method.
45       * @throws javax.xml.rpc.JAXRPCException if any processing error happens
46       */
47      public boolean handleRequest(MessageContext context);
48  
49      /**
50       * The <code>handleResponse</code> method initiates the response
51       * processing for this handler chain.
52       *
53       * @param context MessageContext parameter provides access to the response
54       *                  SOAP message.
55       * @return boolean Returns <code>true</code> if all handlers in
56       *             chain have been processed. Returns <code>false</code>
57       *             if a handler in the chain returned
58       *             <code>false</code> from its handleResponse method.
59       * @throws javax.xml.rpc.JAXRPCException if any processing error happens
60       */
61      public boolean handleResponse(MessageContext context);
62  
63      /**
64       * The <code>handleFault</code> method initiates the SOAP
65       * fault processing for this handler chain.
66       *
67       * @param  context MessageContext parameter provides access to the SOAP
68       *         message.
69       * @return Returns boolean Returns <code>true</code> if all handlers in
70       *             chain have been processed. Returns <code>false</code>
71       *             if a handler in the chain returned
72       *             <code>false</code> from its handleFault method.
73       * @throws javax.xml.rpc.JAXRPCException if any processing error happens
74       */
75      public boolean handleFault(MessageContext context);
76  
77      /**
78       * Initializes the configuration for a HandlerChain.
79       *
80       * @param config Configuration for the initialization of this handler
81       *                 chain
82       *
83       * @throws javax.xml.rpc.JAXRPCException if there is any error that prevents
84       *              initialization
85       */
86      public void init(Map config);
87  
88      /**
89       * Indicates the end of lifecycle for a HandlerChain.
90       *
91       * @throws javax.xml.rpc.JAXRPCException if there was any error that
92       *              prevented destroy from completing
93       */
94      public void destroy();
95  
96      /**
97       * Sets SOAP Actor roles for this <code>HandlerChain</code>. This
98       * specifies the set of roles in which this HandlerChain is to act
99       * for the SOAP message processing at this SOAP node. These roles
100      * assumed by a HandlerChain must be invariant during the
101      * processing of an individual SOAP message through the HandlerChain.
102      * <p>
103      * A <code>HandlerChain</code> always acts in the role of the
104      * special SOAP actor <code>next</code>. Refer to the SOAP
105      * specification for the URI name for this special SOAP actor.
106      * There is no need to set this special role using this method.
107      *
108      * @param soapActorNames URIs for SOAP actor name
109      */
110     public void setRoles(String[] soapActorNames);
111 
112     /**
113      * Gets SOAP actor roles registered for this HandlerChain at
114      * this SOAP node. The returned array includes the special
115      * SOAP actor <code>next</code>.
116      * @return String[] SOAP Actor roles as URIs
117      */
118     public java.lang.String[] getRoles();
119 }
120