001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019:
020: package org.apache.axis2.engine;
021:
022: import org.apache.axis2.AxisFault;
023: import org.apache.axis2.context.MessageContext;
024: import org.apache.axis2.description.HandlerDescription;
025: import org.apache.axis2.description.Parameter;
026:
027: /**
028: * A Handler represents a piece of message processing functionality in Axis2.
029: *
030: * Handlers are combined into chains and phases in order to provide customizable functionality
031: * such as security, reliability, etc. Handlers must be multi-thread safe and should keep all
032: * their state in Context objects (see the org.apache.axis2.context package).
033: */
034: public interface Handler {
035:
036: /**
037: * @deprecated This method will be going away after the 1.3 release, it was never used.
038: */
039: public void cleanup();
040:
041: /**
042: * Initialize a Handler.
043: *
044: * @param handlerDesc the HandlerDescription for this Handler
045: */
046: public void init(HandlerDescription handlerDesc);
047:
048: /**
049: * This method will be called on each registered handler when a message
050: * needs to be processed. If the message processing is paused by the
051: * handler, then this method will be called again for the handler that
052: * paused the processing once it is resumed.
053: * <p/>
054: * This method may be called concurrently from multiple threads.
055: * <p/>
056: * Handlers that want to determine the type of message that is to be
057: * processed (e.g. response vs request, inbound vs. outbound, etc.) can
058: * retrieve that information from the MessageContext via
059: * MessageContext.getFLOW() and
060: * MessageContext.getAxisOperation().getMessageExchangePattern() APIs.
061: *
062: * @param msgContext the <code>MessageContext</code> to process with this
063: * <code>Handler</code>.
064: * @return An InvocationResponse that indicates what
065: * the next step in the message processing should be.
066: * @throws AxisFault if the handler encounters an error
067: */
068: public InvocationResponse invoke(MessageContext msgContext)
069: throws AxisFault;
070:
071: /**
072: * This method will be called on each registered handler that had its
073: * invoke(...) method called during the processing of the message, once
074: * the message processing has completed. During execution of the
075: * flowComplete's, handlers are invoked in the opposite order that they
076: * were invoked originally. Note that implementations SHOULD check
077: * msgContext.getFailureReason() to see if this is an error or a normal
078: * completion.
079: *
080: * @param msgContext the <code>MessageContext</code> to process with this
081: * <code>Handler</code>.
082: */
083: public void flowComplete(MessageContext msgContext);
084:
085: /**
086: * Gets the HandlerDescription of a handler.
087: *
088: * @return Returns HandlerDescription.
089: */
090: public HandlerDescription getHandlerDesc();
091:
092: /**
093: * Return the name of this Handler
094: *
095: * @return the handler's name as a String
096: */
097: public String getName();
098:
099: /**
100: * Get a Parameter from this Handler
101: *
102: * @param name the name of the desired value
103: * @return the Parameter, or null.
104: */
105: public Parameter getParameter(String name);
106:
107: /**
108: * This type encapsulates an enumeration of possible message processing
109: * instruction values that may be returned by a handler/phase within the
110: * runtime. The returned instruction will determine the next step in
111: * the processing.
112: */
113: public class InvocationResponse {
114: public static InvocationResponse CONTINUE = new InvocationResponse(
115: 0, "InvocationResponse.CONTINUE");
116: public static InvocationResponse SUSPEND = new InvocationResponse(
117: 1, "InvocationResponse.SUSPEND");
118: public static InvocationResponse ABORT = new InvocationResponse(
119: 2, "InvocationResponse.ABORT");
120:
121: private int instructionID;
122: private String description;
123:
124: private InvocationResponse(int instructionID, String description) {
125: this .instructionID = instructionID;
126: this .description = description;
127: }
128:
129: public boolean equals(InvocationResponse instruction) {
130: return this .instructionID == instruction.instructionID;
131: }
132:
133: public int hashCode() {
134: return instructionID;
135: }
136:
137: public boolean equals(Object obj) {
138: if (!(obj instanceof InvocationResponse)) {
139: return false;
140: }
141: final InvocationResponse instance = (InvocationResponse) obj;
142: return (instructionID == instance.instructionID);
143: }
144:
145: public String toString() {
146: return description;
147: }
148: }
149: }
|