{
    "mode": "perldoc",
    "parameter": "SOAP::SOM",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/SOAP%3A%3ASOM/json",
    "generated": "2026-05-30T07:10:22Z",
    "sections": {
        "NAME": {
            "content": "SOAP::SOM - provides access to the values contained in SOAP Response\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Objects from the SOAP::SOM class aren't generally instantiated directly\nby an application. Rather, they are handed back by the deserialization\nof a message. In other words, developers will almost never do this:\n\n$som = SOAP::SOM->new;\n\nSOAP::SOM objects are returned by a SOAP::Lite call in a client context.\nFor example:\n\nmy $client = SOAP::Lite\n->readable(1)\n->uri($NS)\n->proxy($HOST)\n$som = $client->someMethod();\n",
            "subsections": []
        },
        "METHODS": {
            "content": "new(message)\n$som = SOAP::SOM->new($messageasxml);\n\nAs said, the need to actually create an object of this class should\nbe very rare. However, if the need arises, the syntax must be\nfollowed. The single argument to new must be a valid XML document\nthe parser will understand as a SOAP response.\n\nThe following group of methods provide general data retrieval from the\nSOAP::SOM object. The model for this is an abbreviated form of XPath.\nFollowing this group are methods that are geared towards specific\nretrieval of commonly requested elements.\n\nmatch(path)\n$som->match('/Envelope/Body/[1]');\n\nThis method sets the internal pointers within the data structure so\nthat the retrieval methods that follow will have access to the\ndesired data. In the example path, the match is being made against\nthe method entity, which is the first child tag of the body in a\nSOAP response. The enumeration of container children starts at 1 in\nthis syntax, not 0. The returned value is dependent on the context\nof the call. If the call is made in a boolean context (such as \"if\n($som->match($path))\"), the return value is a boolean indicating\nwhether the requested path matched at all. Otherwise, an object\nreference is returned. The returned object is also a SOAP::SOM\ninstance but is smaller, containing the subset of the document tree\nmatched by the expression.\n\nvalueof(node)\n$res = $som->valueof('[1]');\n\nWhen the SOAP::SOM object has matched a path internally with the\nmatch method, this method allows retrieval of the data within any of\nthe matched nodes. The data comes back as native Perl data, not a\nclass instance (see dataof). In a scalar context, this method\nreturns just the first element from a matched node set. In an array\ncontext, all elements are returned. Assuming that the earlier call\nhappens after the earlier call to match, it retrieves the result\nentity from the method response that is contained in $som, as this\nis the first child element in a method-response tag.\n\ndataof(node)\n$resobj = $som->dataof('[1]');\n\nPerforms the same operation as the earlier valueof method, except\nthat the data is left in its SOAP::Data form, rather than being\ndeserialized. This allows full access to all the attributes that\nwere serialized along with the data, such as namespace and encoding.\n\nheaderof(node)\n$resobj = $som->headerof('[1]');\n\nActs much like dataof, except that it returns an object of the\nSOAP::Header class (covered later in this chapter), rather than\nSOAP::Data. This is the preferred interface for manipulating the\nheader entities in a message.\n\nnamespaceuriof(node)\n$ns = $som->namespaceof('[1]');\n\nRetrieves the namespace URI that governs the requested node. Note\nthat namespaces are inherited, so this method will return the\nrelevant value, even if it derives from a parent or other ancestor\nnode.\n\nThe following methods provide more direct access to the message\nenvelope. All these methods return some form of a Perl value, most often\na hash reference, when called. Context is also relevant: in a scalar\ncontext only the first matching node is returned, while in an array\ncontext, all matching nodes are. When called as a static method or as a\nregular function (such as \"SOAP::SOM::envelope\"), any of the following\nmethods returns the XPath string that is used with the match method to\nretrieve the data.\n\nroot\n$root = $som->root;\n\nReturns the value of the root element as a hash reference. It\nbehaves exactly as \"$som-\"valueof('/')> does.\n\nenvelope\n$envelope = $som->envelope;\n\nRetrieves the \"Envelope\" element of the message, returning it and\nits data as a hash reference. Keys in the hash will be Header and\nBody (plus any optional elements that may be present in a SOAP 1.1\nenvelope), whose values will be the serialized header and body,\nrespectively.\n\nheader\n$header = $som->header;\n\nRetrieves the header portion of the envelope as a hash reference.\nAll data within it will have been deserialized. If the attributes of\nthe header are desired, the static form of the method can be\ncombined with match to fetch the header as a SOAP::Data object:\n\n$header = $som->match(SOAP::SOM::header)->dataof;\n\nheaders\n@hdrs = $som->headers;\n\nRetrieves the node set of values with deserialized headers from\nwithin the Header container. This is different from the earlier\nheader method in that it returns the whole header as a single\nstructure, and this returns the child elements as an array. In other\nwords, the following expressions yield the same data structure:\n\n$header = ($som->headers)[0];\n$header = $som->valueof(SOAP::SOM::header.'/[1]');\n\nbody\n$body = $som->body;\n\nRetrieves the message body as a hash reference. The entity tags act\nas keys, with their deserialized content providing the values.\n\nfault\nif ($som->fault) { die $som->fault->faultstring }\n\nActs both as a boolean test whether a fault occurred, and as a way\nto retrieve the Fault entity itself from the message body as a hash\nreference. If the message contains a fault, the next four methods\n(faultcode, faultstring, faultactor, and faultdetail) may be used to\nretrieve the respective parts of the fault (which are also available\non the hash reference as keys). If fault in a boolean context is\ntrue, the \"result\", \"paramsin\", \"paramsout\", and \"method\" methods\nall return \"undef\".\n\nfaultcode\n$code = $som->faultcode;\n\nReturns the faultcode element of the fault if there is a fault;\nundef otherwise.\n\nfaultstring\n$string = $som->faultstring;\n\nReturns the faultstring element of the fault if there is a fault;\nundef otherwise.\n\nfaultactor\n$actor = $som->faultactor;\n\nReturns the faultactor element of the fault, if there is a fault and\nif the actor was specified within it. The faultactor element is\noptional in the serialization of a fault, so it may not always be\npresent. This element is usually a string.\n\nfaultdetail\n$detail = $som->faultdetail;\n\nReturns the content of the detail element of the fault, if there is\na fault and if the detail element was provided. Note that the name\nof the element isn't the same as the method, due to the possibility\nfor confusion had the method been called simply, detail. As with the\nfaultactor element, this isn't always a required component of a\nfault, so it isn't guaranteed to be present. The specification for\nthe detail portion of a fault calls for it to contain a series of\nelement tags, so the application may expect a hash reference as a\nreturn value when detail information is available (and undef\notherwise).\n\nmethod\n$method = $som->method\n\nRetrieves the \"method\" element of the message, as a hash reference.\nThis includes all input parameters when called on a request message\nor all result/output parameters when called on a response message.\nIf there is a fault present in the message, it returns undef.\n\nresult\n$value = $som->result;\n\nReturns the value that is the result of a SOAP response. The value\nwill be already deserialized into a native Perl datatype.\n\nparamsin\n@list = $som->paramsin;\n\nRetrieves the parameters being passed in on a SOAP request. If\ncalled in a scalar context, the first parameter is returned. When\ncalled in a list context, the full list of all parameters is\nreturned. Each parameter is a hash reference, following the\nestablished structure for such return values.\n\nparamsout\n@list = $som->paramsout;\n\nReturns the output parameters from a SOAP response. These are the\nnamed parameters that are returned in addition to the explicit\nresponse entity itself. It shares the same scalar/list context\nbehavior as the paramsin method.\n\nparamsall\n@list = $som->paramsall;\n\nReturns all parameters from a SOAP response, including the result\nentity itself, as one array.\n\nparts()\nReturn an array of \"MIME::Entity\"'s if the current payload contains\nattachments, or returns undefined if payload is not MIME multipart.\n\nismultipart()\nReturns true if payload is MIME multipart, false otherwise.\n",
            "subsections": []
        },
        "EXAMPLES": {
            "content": "ACCESSING ELEMENT VALUES\nSuppose for the following SOAP Envelope:\n\n<Envelope>\n<Body>\n<fooResponse>\n<bar>abcd</bar>\n</fooResponse>\n</Body>\n</Envelope>\n\nAnd suppose you wanted to access the value of the bar element, then use\nthe following code:\n\nmy $soap = SOAP::Lite\n->uri($SOMENS)\n->proxy($SOMEHOST);\nmy $som = $soap->foo();\nprint $som->valueof('//fooResponse/bar');\n\nACCESSING ATTRIBUTE VALUES\nSuppose the following SOAP Envelope:\n\n<Envelope>\n<Body>\n<c2fResponse>\n<convertedTemp test=\"foo\">98.6</convertedTemp>\n</c2fResponse>\n</Body>\n</Envelope>\n\nThen to print the attribute 'test' use the following code:\n\nprint \"The attribute is: \" .\n$som->dataof('//c2fResponse/convertedTemp')->attr->{'test'};\n\nITERATING OVER AN ARRAY\nSuppose for the following SOAP Envelope:\n\n<Envelope>\n<Body>\n<catalog>\n<product>\n<title>Programming Web Service with Perl</title>\n<price>$29.95</price>\n</product>\n<product>\n<title>Perl Cookbook</title>\n<price>$49.95</price>\n</product>\n</catalog>\n</Body>\n</Envelope>\n\nIf the SOAP Envelope returned contained an array, use the following code\nto iterate over the array:\n\nfor my $t ($som->valueof('//catalog/product')) {\nprint $t->{title} . \" - \" . $t->{price} . \"\\n\";\n}\n\nDETECTING A SOAP FAULT\nA SOAP::SOM object is returned by a SOAP::Lite client regardless of\nwhether the call succeeded or not. Therefore, a SOAP Client is\nresponsible for determining if the returned value is a fault or not. To\ndo so, use the fault() method which returns 1 if the SOAP::SOM object is\na fault and 0 otherwise.\n\nmy $som = $client->someMethod(@parameters);\n\nif ($som->fault) {\nprint $som->faultdetail;\n} else {\n# do something\n}\n\nPARSING ARRAYS OF ARRAYS\nThe most efficient way To parse and to extract data out of an array\ncontaining another array encoded in a SOAP::SOM object is the following:\n\n$xml = <<ENDXML;\n<foo>\n<person>\n<foo>123</foo>\n<foo>456</foo>\n</person>\n<person>\n<foo>789</foo>\n<foo>012</foo>\n</person>\n</foo>\nENDXML\n\nmy $som = SOAP::Deserializer->deserialize($xml);\nmy $i = 0;\nforeach my $a ($som->dataof(\"//person/*\")) {\n$i++;\nmy $j = 0;\nforeach my $b ($som->dataof(\"//person/[$i]/*\")) {\n$j++;\n# do something\n}\n}\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "SOAP::Data, SOAP::Serializer\n",
            "subsections": []
        },
        "ACKNOWLEDGEMENTS": {
            "content": "Special thanks to O'Reilly publishing which has graciously allowed\nSOAP::Lite to republish and redistribute large excerpts from\n*Programming Web Services with Perl*, mainly the SOAP::Lite reference\nfound 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\nunder the same terms as Perl 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": []
        }
    },
    "summary": "SOAP::SOM - provides access to the values contained in SOAP Response",
    "flags": [],
    "examples": [
        "ACCESSING ELEMENT VALUES",
        "Suppose for the following SOAP Envelope:",
        "<Envelope>",
        "<Body>",
        "<fooResponse>",
        "<bar>abcd</bar>",
        "</fooResponse>",
        "</Body>",
        "</Envelope>",
        "And suppose you wanted to access the value of the bar element, then use",
        "the following code:",
        "my $soap = SOAP::Lite",
        "->uri($SOMENS)",
        "->proxy($SOMEHOST);",
        "my $som = $soap->foo();",
        "print $som->valueof('//fooResponse/bar');",
        "ACCESSING ATTRIBUTE VALUES",
        "Suppose the following SOAP Envelope:",
        "<Envelope>",
        "<Body>",
        "<c2fResponse>",
        "<convertedTemp test=\"foo\">98.6</convertedTemp>",
        "</c2fResponse>",
        "</Body>",
        "</Envelope>",
        "Then to print the attribute 'test' use the following code:",
        "print \"The attribute is: \" .",
        "$som->dataof('//c2fResponse/convertedTemp')->attr->{'test'};",
        "ITERATING OVER AN ARRAY",
        "Suppose for the following SOAP Envelope:",
        "<Envelope>",
        "<Body>",
        "<catalog>",
        "<product>",
        "<title>Programming Web Service with Perl</title>",
        "<price>$29.95</price>",
        "</product>",
        "<product>",
        "<title>Perl Cookbook</title>",
        "<price>$49.95</price>",
        "</product>",
        "</catalog>",
        "</Body>",
        "</Envelope>",
        "If the SOAP Envelope returned contained an array, use the following code",
        "to iterate over the array:",
        "for my $t ($som->valueof('//catalog/product')) {",
        "print $t->{title} . \" - \" . $t->{price} . \"\\n\";",
        "DETECTING A SOAP FAULT",
        "A SOAP::SOM object is returned by a SOAP::Lite client regardless of",
        "whether the call succeeded or not. Therefore, a SOAP Client is",
        "responsible for determining if the returned value is a fault or not. To",
        "do so, use the fault() method which returns 1 if the SOAP::SOM object is",
        "a fault and 0 otherwise.",
        "my $som = $client->someMethod(@parameters);",
        "if ($som->fault) {",
        "print $som->faultdetail;",
        "} else {",
        "# do something",
        "PARSING ARRAYS OF ARRAYS",
        "The most efficient way To parse and to extract data out of an array",
        "containing another array encoded in a SOAP::SOM object is the following:",
        "$xml = <<ENDXML;",
        "<foo>",
        "<person>",
        "<foo>123</foo>",
        "<foo>456</foo>",
        "</person>",
        "<person>",
        "<foo>789</foo>",
        "<foo>012</foo>",
        "</person>",
        "</foo>",
        "ENDXML",
        "my $som = SOAP::Deserializer->deserialize($xml);",
        "my $i = 0;",
        "foreach my $a ($som->dataof(\"//person/*\")) {",
        "$i++;",
        "my $j = 0;",
        "foreach my $b ($som->dataof(\"//person/[$i]/*\")) {",
        "$j++;",
        "# do something"
    ],
    "see_also": []
}