{ "content": [ { "type": "text", "text": "# SOAP::Server (perldoc)\n\n## NAME\n\nSOAP::Server - provides the basic framework for the transport-specific server classes to build upon\n\n## DESCRIPTION\n\nThe SOAP::Server class provides the basic framework for the transport-specific server classes to\nbuild upon. Note that in none of the code examples provided with SOAP::Lite is this class used\ndirectly. Instead, it is designed to be a superclass within more specific implementation\nclasses. The methods provided by SOAP::Server itself are:\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **METHODS** (13 subsections)\n- **SEE ALSO**\n- **ACKNOWLEDGEMENTS**\n- **COPYRIGHT**\n- **AUTHORS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "SOAP::Server", "section": "", "mode": "perldoc", "summary": "SOAP::Server - provides the basic framework for the transport-specific server classes to build upon", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 3, "subsections": [] }, { "name": "DESCRIPTION", "lines": 5, "subsections": [] }, { "name": "METHODS", "lines": 1, "subsections": [ { "name": "new", "lines": 7 }, { "name": "action", "lines": 9 }, { "name": "myuri", "lines": 6 }, { "name": "serializer", "lines": 1 }, { "name": "deserializer", "lines": 7 }, { "name": "options", "lines": 15 }, { "name": "dispatch_with", "lines": 10 }, { "name": "dispatch_to", "lines": 29 }, { "name": "objects_by_reference", "lines": 18 }, { "name": "on_action", "lines": 17 }, { "name": "on_dispatch", "lines": 54 }, { "name": "byNameOrOrder", "lines": 9 }, { "name": "byName", "lines": 29 } ] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "ACKNOWLEDGEMENTS", "lines": 4, "subsections": [] }, { "name": "COPYRIGHT", "lines": 5, "subsections": [] }, { "name": "AUTHORS", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "SOAP::Server - provides the basic framework for the transport-specific server classes to build\nupon\n", "subsections": [] }, "DESCRIPTION": { "content": "The SOAP::Server class provides the basic framework for the transport-specific server classes to\nbuild upon. Note that in none of the code examples provided with SOAP::Lite is this class used\ndirectly. Instead, it is designed to be a superclass within more specific implementation\nclasses. The methods provided by SOAP::Server itself are:\n", "subsections": [] }, "METHODS": { "content": "", "subsections": [ { "name": "new", "content": "$server = SOAP::Server->new(%options);\n\nCreates a new object of the class. Various default instance values are set up, and like many\nof the constructors in this module, most of the class methods described here may be passed\nin the construction call by giving the name followed by the parameter (or an array reference\nif there are multiple parameters).\n" }, { "name": "action", "content": "$action = $server->action\n\nRetrieves or sets the value of the action attribute on the server object. This attribute is\nused when mapping the request to an appropriate namespace or routine. For example, the HTTP\nlibrary sets the attribute to the value of the SOAPAction header when processing of the\nrequest begins, so that the findtarget method described later may retrieve the value to\nmatch it against the server's configuration. Returns the object itself when setting the\nattribute.\n" }, { "name": "myuri", "content": "$server->myuri(\"http://localhost:9000/SOAP\");\n\nGets or sets the myuri attribute. This specifies the specific URI that the server is\nanswering requests to (which may be different from the value specified in action or in the\nSOAPAction header).\n" }, { "name": "serializer", "content": "" }, { "name": "deserializer", "content": "$serializer = $server->serializer;\n$server->deserializer($newdeserobj);\n\nAs with the client objects, these methods provide direct access to the serialization and\ndeserialization objects the server object uses to transform input and output from and to\nXML. There is generally little or no need to explicitly set these to new values.\n" }, { "name": "options", "content": "$server->options({compressthreshold => 10000});\n\nSets (or retrieves) the current server options as a hash-table reference. At present, only\none option is used within the SOAP::Lite libraries themselves:\n\ncompressthreshold\nThe value of this option is expected to be a numerical value. If set, and if the\nCompress::Zlib library is available to use, messages whose size in bytes exceeds this\nvalue are compressed for transmission. Both ends of the conversation have to support\nthis and have it enabled.\n\nOther options may be defined and passed around using this mechanism. Note that setting the\noptions using this accessor requires a full hash reference be passed. To set just one or a\nfew values, retrieve the current reference value and use it to set the key(s).\n" }, { "name": "dispatch_with", "content": "$server->dispatchwith($newtable);\n\nRepresents one of two ways in which a SOAP::Server (or derived) object may specify mappings\nof incoming requests to server-side subroutines or namespaces. The value of the attribute is\na hash-table reference. To set the attribute, you must pass a new hash reference. The hash\ntable's keys are URI strings (literal URIs or the potential values of the SOAPAction\nheader), and the corresponding values are one of a class name or an object reference.\nRequests that come in for a URI found in the table are routed to the specified class or\nthrough the specified object.\n" }, { "name": "dispatch_to", "content": "$server->dispatchto($dir, 'Module', 'Mod::meth');\n\nThis is the more traditional way to specify modules and packages for routing requests. This\nis also an accessor, but it returns a list of values when called with no arguments (rather\nthan a single one). Each item in the list of values passed to this method is expected to be\none of four things:\n\n*Directory path*\nIf the value is a directory path, all modules located in that path are available for\nremote use.\n\n*Package name*\nWhen the value is a package name (without including a specific method name), all\nroutines within the package are available remotely.\n\n*Fully qualified method name*\nAlternately, when the value is a package-qualified name of a subroutine or method, that\nspecific routine is made available. This allows the server to make selected methods\navailable without opening the entire package.\n\n*Object reference*\nIf the value is an object reference, the object itself routes the request.\n\nThe list of values held by the dispatchto table are compared only after the URI mapping\ntable from the dispatchwith attribute has been consulted. If the request's URI or\nSOAPAction header don't map to a specific configuration, the path specified by the\naction header (or in absence, the URI) is converted to a package name and compared\nagainst this set of values.\n" }, { "name": "objects_by_reference", "content": "$server->objectsbyreference(qw(My:: Class));\n\nThis also returns a list of values when retrieving the current attribute value, as opposed\nto a single value.\n\nThis method doesn't directly specify classes for request routing so much as it modifies the\nbehavior of the routing for the specified classes. The classes that are given as arguments\nto this method are marked to be treated as producing persistent objects. The client is given\nan object representation that contains just a handle on a local object with a default\npersistence of 600 idle seconds. Each operation on the object resets the idle timer to zero.\nThis facility is considered experimental in the current version of SOAP::Lite.\n\nA global variable/\"constant\" allows developers to specify the amount of time an object will\nbe persisted. The default value is 600 idle seconds. This value can be changed using the\nfollowing code:\n\n$SOAP::Constants::OBJSBYREFKEEPALIVE = 1000;\n" }, { "name": "on_action", "content": "$server->onaction(sub { ...new code });\n\nGets or sets the reference to a subroutine that is used for executing the onaction hook.\nWhere the client code uses this hook to construct the action-request data (such as for a\nSOAPAction header), the server uses the onaction hook to do any last-minute tests on the\nrequest itself, before it gets routed to a final destination. When called, the hook routine\nis passed three arguments:\n\naction\nThe action URI itself, retrieved from the action method described earlier.\n\nmethoduri\nThe URI of the XML namespace the method name is labeled with.\n\nmethodname\nThe name of the method being called by the request.\n" }, { "name": "on_dispatch", "content": "($uri, $name) = $server->ondispatch->($request);\n\nGets or sets the subroutine reference used for the ondispatch hook. This hook is called at\nthe start of the request-routing phase and is given a single argument when called:\n\nrequest\nAn object of the SOAP::SOM class, containing the deserialized request from the client.\n\nfindtarget\n($class, $uri, $name) = $server->findtarget($req)\n\nTaking as its argument an object of the SOAP::SOM class that contains the deserialized\nrequest, this method returns a three-element list describing the method that is to be\ncalled. The elements are:\n\nclass\nThe class into which the method call should be made. This may come back as either a\nstring or an objectreference, if the dispatching is configured using an object instance.\n\nuri The URN associated with the request method. This is the value that was used when\nconfiguring the method routing on the server object.\n\nname\nThe name of the method to call.\n\nhandle\n$server->handle($requesttext);\n\nImplements the main functionality of the serving process, in which the server takes an\nincoming request and dispatches it to the correct server-side subroutine. The parameter\ntaken as input is either plain XML or MIME-encoded content (if MIME-encoding support is\nenabled).\n\nmakefault\nreturn $server->makefault($code, $message);\n\nCreates a SOAP::Fault object from the data passed in. The order of arguments is: code,\nmessage, detail, actor. The first two are required (because they must be present in all\nfaults), but the last two may be omitted unless needed.\n\nSOAP::Server::Parameters\nThis class provides two methods, but the primary purpose from the developer's point of view is\nto allow classes that a SOAP server exposes to inherit from it. When a class inherits from the\nSOAP::Server::Parameters class, the list of parameters passed to a called method includes the\ndeserialized request in the form of a SOAP::SOM object. This parameter is passed at the end of\nthe arguments list, giving methods the option of ignoring it unless it is needed.\n\nThe class provides two subroutines (not methods), for retrieving parameters from the SOAP::SOM\nobject. These are designed to be called without an object reference in the parameter list, but\nwith an array reference instead (as the first parameter). The remainder of the arguments list is\nexpected to be the list from the method-call itself, including the SOAP::SOM object at the end\nof the list. The routines may be useful to understand if an application wishes to subclass\nSOAP::Server::Parameters and inherit from the new class instead.\n" }, { "name": "byNameOrOrder", "content": "@args = SOAP::Server::Parameters::byNameOrOrder ([qw(a b)], @);\n\nUsing the list of argument names passed in the initial argument as an array reference, this\nroutine returns a list of the parameter values for the parameters matching those names, in\nthat order. If none of the names given in the initial array-reference exist in the parameter\nlist, the values are returned in the order in which they already appear within the list of\nparameters. In this case, the number of returned values may differ from the length of the\nrequested-parameters list.\n" }, { "name": "byName", "content": "@args = SOAP::Server::Parameters::byName ([qw(a b c)], @);\n\nActs in a similar manner to the previous, with the difference that it always returns as many\nvalues as requested, even if some (or all) don't exist. Parameters that don't exist in the\nparameter list are returned as undef values.\n\nEXAMPLE\nThe following is an example CGI based Web Service that utilizes a Perl module that inherits from\nthe \"SOAP::Server::Parameters\" class. This allows the methods of that class to access its input\nby name.\n\n#!/usr/bin/perl\nuse SOAP::Transport::HTTP;\nSOAP::Transport::HTTP::CGI\n->dispatchto('C2FService')\n->handle;\nBEGIN {\npackage C2FService;\nuse vars qw(@ISA);\n@ISA = qw(Exporter SOAP::Server::Parameters);\nuse SOAP::Lite;\nsub c2f {\nmy $self = shift;\nmy $envelope = pop;\nmy $temp = $envelope->dataof(\"//c2f/temperature\");\nreturn SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32));\n}\n}\n" } ] }, "SEE ALSO": { "content": "SOAP::SOM, SOAP::Transport::HTTP\n", "subsections": [] }, "ACKNOWLEDGEMENTS": { "content": "Special thanks to O'Reilly publishing which has graciously allowed SOAP::Lite to republish and\nredistribute large excerpts from *Programming Web Services with Perl*, mainly the SOAP::Lite\nreference found in Appendix B.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] }, "AUTHORS": { "content": "Paul Kulchenko (paulclinger@yahoo.com)\n\nRandy J. Ray (rjray@blackperl.com)\n\nByrne Reese (byrne@majordojo.com)\n", "subsections": [] } } } }