| /* |
| * Copyright 2001-2004 The Apache Software Foundation. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package org.apache.axis ; |
| |
| import org.w3c.dom.Document; |
| import org.w3c.dom.Element; |
| |
| import javax.xml.namespace.QName; |
| import java.io.Serializable; |
| import java.util.Hashtable; |
| import java.util.List; |
| |
| /** |
| * An AXIS handler. |
| * |
| * @author Doug Davis (dug@us.ibm.com) |
| */ |
| public interface Handler extends Serializable { |
| /** |
| * Init is called when the chain containing this Handler object |
| * is instantiated. |
| */ |
| public void init(); |
| |
| /** |
| * Cleanup is called when the chain containing this Handler object |
| * is done processing the chain. |
| */ |
| public void cleanup(); |
| |
| /** |
| * Invoke is called to do the actual work of the Handler object. |
| * If there is a fault during the processing of this method it is |
| * invoke's job to catch the exception and undo any partial work |
| * that has been completed. Once we leave 'invoke' if a fault |
| * is thrown, this classes 'onFault' method will be called. |
| * Invoke should rethrow any exceptions it catches, wrapped in |
| * an AxisFault. |
| * |
| * @param msgContext the <code>MessageContext</code> to process with this |
| * <code>Handler</code>. |
| * @throws AxisFault if the handler encounters an error |
| */ |
| public void invoke(MessageContext msgContext) throws AxisFault ; |
| |
| /** |
| * Called when a subsequent handler throws a fault. |
| * |
| * @param msgContext the <code>MessageContext</code> to process the fault |
| * to |
| */ |
| public void onFault(MessageContext msgContext); |
| |
| /** |
| * Indicate if this handler can process <code>qname</code>. |
| * |
| * @param qname the <code>QName</code> to check |
| * @return true if this <code>Handler</code> can handle <code>qname</code>, |
| * false otherwise |
| */ |
| public boolean canHandleBlock(QName qname); |
| |
| // fixme: will modifications to this List be reflected in the state of this |
| // handler? |
| /** |
| * Return a list of QNames which this Handler understands. By returning |
| * a particular QName here, we are committing to fulfilling any contracts |
| * defined in the specification of the SOAP header with that QName. |
| * |
| * @return a List of <code>QName</code> instances |
| */ |
| public List getUnderstoodHeaders(); |
| |
| // fixme: doesn't specify what happens when an option is re-defined |
| /** |
| * Add the given option (name/value) to this handler's bag of options. |
| * |
| * @param name the name of the option |
| * @param value the new value of the option |
| */ |
| public void setOption(String name, Object value); |
| |
| /** |
| * Returns the option corresponding to the 'name' given. |
| * |
| * @param name the name of the option |
| * @return the value of the option |
| */ |
| public Object getOption(String name); |
| |
| /** |
| * Set the name (i.e. registry key) of this Handler. |
| * |
| * @param name the new name |
| */ |
| public void setName(String name); |
| |
| /** |
| * Return the name (i.e. registry key) for this <code>Handler</code>. |
| * |
| * @return the name for this <code>Handler</code> |
| */ |
| public String getName(); |
| |
| // fixme: doesn't tell us if modifying this Hashset will modify this Handler |
| // fixme: do we mean to use a Hahset, or will Map do? |
| /** |
| * Return the entire list of options. |
| * |
| * @return a <code>Hashset</code> containing all name/value pairs |
| */ |
| public Hashtable getOptions(); |
| |
| // fixme: this doesn't indicate if opts becomes the new value of |
| // getOptions(), or if it is merged into it. Also doesn't specify if |
| // modifications to opts after calling this method will affect this handler |
| /** |
| * Sets a whole list of options. |
| * |
| * @param opts a <code>Hashtable</code> of name-value pairs to use |
| */ |
| public void setOptions(Hashtable opts); |
| |
| // fixme: presumably doc is used as the factory & host for Element, and |
| // Element should not be grafted into doc by getDeploymentData, but will |
| // potentially be grafted in by code calling this - could we clarify this? |
| /** |
| * This will return the root element of an XML doc that describes the |
| * deployment information about this handler. This is NOT the WSDL, |
| * this is all of the static internal data use by Axis - WSDL takes into |
| * account run-time information (like which service we're talking about) |
| * this is just the data that's stored in the registry. Used by the |
| * 'list' Admin function. |
| * |
| * @param doc a <code>Document</code> within which to build the deployment |
| * data |
| * @return an Element representing the deployment data |
| */ |
| public Element getDeploymentData(Document doc); |
| |
| /** |
| * Obtain WSDL information. Some Handlers will implement this by |
| * merely setting properties in the MessageContext, others (providers) |
| * will take responsibility for doing the "real work" of generating |
| * WSDL for a given service. |
| * |
| * @param msgContext the <code>MessageContext</code> to generate the WSDL |
| * to |
| * @throws AxisFault if there was a problem generating the WSDL |
| */ |
| public void generateWSDL(MessageContext msgContext) throws AxisFault; |
| }; |