You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ro...@apache.org on 2004/06/14 09:00:56 UTC
cvs commit: ws-axis/c/include/axis/server Handler.h BasicHandler.h
roshan 2004/06/14 00:00:56
Modified: c/include/axis/server Handler.h BasicHandler.h
Log:
Added doxygen comments to help autobuild API docs
Revision Changes Path
1.10 +71 -11 ws-axis/c/include/axis/server/Handler.h
Index: Handler.h
===================================================================
RCS file: /home/cvs/ws-axis/c/include/axis/server/Handler.h,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- Handler.h 30 Apr 2004 05:38:30 -0000 1.9
+++ Handler.h 14 Jun 2004 07:00:55 -0000 1.10
@@ -23,28 +23,88 @@
#include "BasicHandler.h"
#include <map>
-/*
- * #ifdef _DEBUG
- * #include "AxisTrace.h"
- * #endif
- */
+
using namespace std;
+/**
+ * @class Handler
+ * @brief interface for handlers.
+ *
+ * @author Damitha Kumarage (damitha@opensource.lk, damitha@jkcsworld.com)
+ * @author Roshan Weerasuriya (roshan@opensource.lk, roshanw@jkcsworld.com)
+ */
+
/*
- * @class Handler
- * @brief interface for handlers
- * @author Damitha Kumarage (damitha@opensource.lk, damitha@jkcsworld.com)
+ * Revision 1.1 2004/06/14 roshan
+ * Added doxygen comments to help autobuild API docs
+ * Added the implementations of getOption(const string& sArg) and
+ * setOptionList(const map<string, string>* OptionList), because these methods
+ * are not needed to be implemented by the users. These are generic methods.
*/
+
class Handler : public HandlerBase
{
public:
+ /**
+ * Constructor.
+ */
Handler(){};
+
+ /**
+ * Destructor.
+ */
virtual ~Handler(){};
- virtual const string& getOption(const string& sArg)=0;
- virtual void setOptionList(const map<string, string>* OptionList)=0;
+
+ /**
+ * Returns the value of the given option.
+ *
+ * @param sArg The option name, i.e key
+ * @return The option value.
+ */
+ const string& getOption(const string& sArg)
+ {
+ m_sEmpty = "";
+
+ map<string, string>::const_iterator it = m_pOption->find(sArg);
+ if (it != m_pOption->end())
+ {
+ return (*it).second;
+ }
+ return m_sEmpty;
+ }
+
+ /**
+ * This method is automatically called by the Axis Engine when it loads a
+ * Handler. The purpose of this method is described below:
+ * For each Handler we could configure various parameters/options in the
+ * Server.wsdd or Client.wsdd. If the engine finds any such options then
+ * the engine will automaticaly call this method of each handler and will
+ * set those options to each Handler by calling this method of each
+ * Handler which those configuration options belong to. Normaly a Handler
+ * writer doesn't need to interact/deal with this method.
+ *
+ * @param OptionList The map which contains the options to be set.
+ */
+ void setOptionList(const map<string, string>* OptionList) {m_pOption = OptionList;};
+
+ /**
+ * Gets and returns the type of the handler. The return value here is
+ * always NORMAL_HANDLER.
+ *
+ * @return returns the type of the handler. The return value here is
+ * always NORMAL_HANDLER.
+ */
int AXISCALL getType(){return NORMAL_HANDLER;};
protected:
- const map<string, string>* m_pOption;
+ /**
+ * Used to store the options which are configured in the WSDD.
+ */
+ const map<string, string>* m_pOption;
+
+ /**
+ * Represents an empty string.
+ */
+ string m_sEmpty;
};
#endif
1.9 +168 -1 ws-axis/c/include/axis/server/BasicHandler.h
Index: BasicHandler.h
===================================================================
RCS file: /home/cvs/ws-axis/c/include/axis/server/BasicHandler.h,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- BasicHandler.h 25 May 2004 03:47:33 -0000 1.8
+++ BasicHandler.h 14 Jun 2004 07:00:56 -0000 1.9
@@ -13,7 +13,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*
- * @author Susantha Kumara (skumara@virtusa.com)
*
*/
@@ -44,15 +43,183 @@
#ifdef __cplusplus
+/**
+ * @class HandlerBase
+ * @brief interface for the Handlers. This is the base class for:
+ * - Handler
+ * - WrapperClassHandler
+ * In the Axis Architecture there are different types of Handlers :
+ * - NORMAL_HANDLER : A Handler which is used to process SOAP Headers.
+ * - WEBSERVICE_HANDLER : A web service is also considered as a Handler.
+ * - CHAIN_HANDLER :
+ * Each of these handlers will inherit from this HandlerBase which serves as
+ * the base point for all the different types of Handlers.
+ *
+ * @author Susantha Kumara (skumara@virtusa.com)
+ * @author Roshan Weerasuriya (roshan@opensource.lk, roshanw@jkcsworld.com)
+ *
+ */
+
+/*
+ * Revision 1.1 2004/06/14 roshan
+ * Added doxygen comments to help autobuild API docs
+ */
+
class HandlerBase
{
public:
+ /**
+ * Constructor.
+ */
HandlerBase(){};
+
+ /**
+ * Destructor.
+ */
virtual ~HandlerBase(){};
+
+ /**
+ * The invoke method is automatically called by the Axis Engine when it
+ * needs to execute a Handler. The main task of the handler which a
+ * Handler writer expects the Handler to be performed needs to be written
+ * within the invoke method of the Handler.
+ *
+ * A example code segment within a invoke method which is written to
+ * process a SOAP Header is as following:
+ * <PRE>
+ * int ESHHandler::invoke(void *pvIMsg)
+ * {
+ * IMessageData *pIMsg = (IMessageData*) pvIMsg;
+ * AxisChar* pachTemp;
+ * if(pIMsg->isPastPivot()) {
+ * //this is a response
+ *
+ * IHandlerSoapSerializer* pISZ;
+ * pIMsg->getSoapSerializer(&pISZ);
+ *
+ * IHeaderBlock* pIHeaderBlock= pISZ->createHeaderBlock();
+ *
+ * pIHeaderBlock->setLocalName("echoMeStringResponse");
+ * pIHeaderBlock->setUri("http://soapinterop.org/echoheader/");
+ *
+ * pachTemp = "EchoStringHeaderHandlerPr1.id";
+ *
+ * const AxisChar* pachHeaderVal = pIMsg->getProperty(pachTemp);
+ * printf("in the ESHHandler::Invoke : %s\n",pachHeaderVal);
+ *
+ * BasicNode* pBasicNode = pIHeaderBlock->createChild(CHARACTER_NODE);
+ * pBasicNode->setValue(pachHeaderVal);
+ *
+ * pIHeaderBlock->addChild(pBasicNode);
+ *
+ * } else {
+ * //this is a request
+ *
+ * IHandlerSoapDeSerializer* pIHandlerSoapDeSerializer;
+ * pIMsg->getSoapDeSerializer(&pIHandlerSoapDeSerializer);
+ *
+ * IHeaderBlock* pIHeaderBlock= pIHandlerSoapDeSerializer->getHeaderBlock("echoMeString", "http://soapinterop.org/echoheader/");
+ *
+ * if (pIHeaderBlock != NULL) {
+ *
+ * const BasicNode* pBasicNode= pIHeaderBlock->getFirstChild();
+ *
+ * const AxisChar* pachHeaderValue;
+ *
+ * if (pBasicNode != NULL)
+ * {
+ * if((pBasicNode->getNodeType()) == CHARACTER_NODE) {
+ * pachHeaderValue= pBasicNode->getValue();
+ * } else {
+ * pachHeaderValue = "This was not the expected value Ros";
+ * }
+ * } else
+ * {
+ * pachHeaderValue = "pBascNode is NULL";
+ * }
+ *
+ * AxisChar* pachTmpValue = (AxisChar*) malloc(strlen(pachHeaderValue) + 4);
+ * strcpy(pachTmpValue, pachHeaderValue);
+ *
+ * pachTemp = "EchoStringHeaderHandlerPr1.id";
+ * pIMsg->setProperty(pachTemp, pachTmpValue);
+ *
+ * free(pachTmpValue);
+ *
+ *
+ * } else {
+ * //do some thing
+ * }
+ *
+ * }
+ *
+ * return AXIS_SUCCESS;
+ * }
+ * </PRE>
+ *
+ * In case of a Web Service Handler the invoke method should do what is
+ * required by a web service invoke method, which is different from the
+ * above shown example.
+ *
+ * @param pMsg The MessageData object pointer. This MessageData object is
+ * passed to every handler when serving to a client request. The handler
+ * writer can get access to objects such as:
+ * - IHandlerSoapDeSerializer
+ * - IHandlerSoapSerializer
+ * - The properties/data/info which are set by other handlers
+ * - The properties/data/info which is set by the Client Stub in case
+ * the Handler is a Client side Handler.
+ * etc.
+ * @return AXIS_SUCCESS or AXIS_FAIL to indicate success or fail.
+ */
virtual int AXISCALL invoke(void* pMsg)=0;
+
+ /**
+ * Called when ever a fault is occured within the handler. The tasks which
+ * needs to be persormed when ever an error occurs within a Handler has
+ * to be written within this method.
+ *
+ * @param mMsg The MessageData object pointer. This MessageData object is
+ * passed to every handler when serving to a client request. The handler
+ * writer can get access to objects such as:
+ * - IHandlerSoapDeSerializer
+ * - IHandlerSoapSerializer
+ * etc.
+ * @return AXIS_SUCCESS or AXIS_FAIL to indicate success or fail.
+ */
virtual void AXISCALL onFault(void* mMsg)=0;
+
+ /**
+ * The initialization tasks which needs to be performed within a Handler
+ * has to be written here. This method will be automatically called by the
+ * Axis Engine when it loads a handler.
+ *
+ * @return AXIS_SUCCESS or AXIS_FAIL to indicate success or fail.
+ */
virtual int AXISCALL init()=0;
+
+ /**
+ * The finalization tasks which needs to be performed within a Handler
+ * has to be written here. This method will be automatically called by the
+ * Axis Engine when it unloads a handler.
+ *
+ * @return AXIS_SUCCESS or AXIS_FAIL to indicate success or fail.
+ */
virtual int AXISCALL fini()=0;
+
+ /**
+ * Gets and returns the type of the handler. The return value could be :
+ * - NORMAL_HANDLER
+ * - WEBSERVICE_HANDLER
+ * - CHAIN_HANDLER
+ *
+ * @return This returns the following depending on the actual Handler
+ * type:
+ * - NORMAL_HANDLER : In case of a normal Handler which is used to
+ * process SOAP Headers.
+ * - WEBSERVICE_HANDLER : In case of a Web Service.
+ * - CHAIN_HANDLER
+ */
virtual int AXISCALL getType()=0;
};
#endif