Handler


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  
17  package org.apache.axis ;
18  
19  import org.w3c.dom.Document  ;
20  import org.w3c.dom.Element  ;
21  
22  import javax.xml.namespace.QName  ;
23  import java.io.Serializable  ;
24  import java.util.Hashtable  ;
25  import java.util.List  ;
26  
27  /**
28   * An AXIS handler.
29   *
30   * @author Doug Davis (dug@us.ibm.com)
31   */
32  public interface Handler extends Serializable   {
33      /**
34       * Init is called when the chain containing this Handler object
35       * is instantiated.
36       */
37      public void init();
38  
39      /**
40       * Cleanup is called when the chain containing this Handler object
41       * is done processing the chain.
42       */
43      public void cleanup();
44  
45      /**
46       * Invoke is called to do the actual work of the Handler object.
47       * If there is a fault during the processing of this method it is
48       * invoke's job to catch the exception and undo any partial work
49       * that has been completed.  Once we leave 'invoke' if a fault
50       * is thrown, this classes 'onFault' method will be called.
51       * Invoke should rethrow any exceptions it catches, wrapped in
52       * an AxisFault.
53       *
54       * @param msgContext    the <code>MessageContext</code> to process with this
55       *              <code>Handler</code>.
56       * @throws AxisFault if the handler encounters an error
57       */
58      public void invoke(MessageContext msgContext) throws AxisFault ;
59  
60      /**
61       * Called when a subsequent handler throws a fault.
62       *
63       * @param msgContext    the <code>MessageContext</code> to process the fault
64       *              to
65       */
66      public void onFault(MessageContext msgContext);
67  
68      /**
69       * Indicate if this handler can process <code>qname</code>.
70       *
71       * @param qname  the <code>QName</code> to check
72       * @return true if this <code>Handler</code> can handle <code>qname<code>,
73       *              false otherwise
74       */
75      public boolean canHandleBlock(QName   qname);
76  
77      // fixme: will modifications to this List be reflected in the state of this
78      //  handler?
79      /**
80       * Return a list of QNames which this Handler understands.  By returning
81       * a particular QName here, we are committing to fulfilling any contracts
82       * defined in the specification of the SOAP header with that QName.
83       *
84       * @return a List of <code>QName</code> instances
85       */
86      public List   getUnderstoodHeaders();
87  
88      // fixme: doesn't specify what happens when an option is re-defined
89      /**
90       * Add the given option (name/value) to this handler's bag of options.
91       *
92       * @param name  the name of the option
93       * @param value the new value of the option
94       */
95      public void setOption(String   name, Object   value);
96  
97      /**
98       * Returns the option corresponding to the 'name' given.
99       *
100      * @param name  the name of the option
101      * @return the value of the option
102      */
103     public Object   getOption(String   name);
104 
105     /**
106      * Set the name (i.e. registry key) of this Handler.
107      *
108      * @param name  the new name
109      */
110     public void setName(String   name);
111 
112     /**
113      * Return the name (i.e. registry key) for this <code>Handler</code>.
114      *
115      * @return the name for this <code>Handler</code>
116      */
117     public String   getName();
118 
119     // fixme: doesn't tell us if modifying this Hashset will modify this Handler
120     // fixme: do we mean to use a Hahset, or will Map do?
121     /**
122      * Return the entire list of options.
123      *
124      * @return a <code>Hashset</code> containing all name/value pairs
125      */
126     public Hashtable   getOptions();
127 
128     // fixme: this doesn't indicate if opts becomes the new value of
129     //  getOptions(), or if it is merged into it. Also doesn't specify if
130     //  modifications to opts after calling this method will affect this handler
131     /**
132      * Sets a whole list of options.
133      *
134      * @param opts  a <code>Hashtable</code> of name-value pairs to use
135      */
136     public void setOptions(Hashtable   opts);
137 
138     // fixme: presumably doc is used as the factory & host for Element, and
139     //  Element should not be grafted into doc by getDeploymentData, but will
140     //  potentially be grafted in by code calling this - could we clarify this?
141     /**
142      * This will return the root element of an XML doc that describes the
143      * deployment information about this handler.  This is NOT the WSDL,
144      * this is all of the static internal data use by Axis - WSDL takes into
145      * account run-time information (like which service we're talking about)
146      * this is just the data that's stored in the registry.  Used by the
147      * 'list' Admin function.
148      *
149      * @param doc  a <code>Document</code> within which to build the deployment
150      *              data
151      * @return an Element representing the deployment data
152      */
153     public Element   getDeploymentData(Document   doc);
154 
155     /**
156      * Obtain WSDL information.  Some Handlers will implement this by
157      * merely setting properties in the MessageContext, others (providers)
158      * will take responsibility for doing the "real work" of generating
159      * WSDL for a given service.
160      *
161      * @param msgContext the <code>MessageContext</code> to generate the WSDL
162      *              to
163      * @throws AxisFault  if there was a problem generating the WSDL
164      */
165     public void generateWSDL(MessageContext msgContext) throws AxisFault;
166 };
167
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags